Server Install and Configuration
An NGINX Instance Manager installation document.
This document helps you get NGINX Instance Manager up and running.
- Get the installation packages or binaries.
- Get license files.
- Download NGINX Instance Manager Server license file (for production use)
- Optional: Download repository certificate and key (for repo access)
- Create a Linux instance for hosting the NGINX Instance Manager Server.
- Ensure the firewall is open for gRPC port and API/GUI port.
- Suggested sizing is 2GB Memory, 1 vCPU, and 20GB disk space.
You can choose one of the following two options:
- Use the public NGINX repositories with a certificate and key or internal package management system (like Red Hat Satellite)
- Use the packages directly by downloading them from the myF5 portal or from NGINX/F5 sales team.
There are three license files included with NGINX Instance Manager:
NGINX-Instance-Manager.lic(may be named differently): This is the nginx-manager server license and is placed in the
/etc/nginx-manager/directory. It is referenced by the
license:option in the
/etc/nginx-manager/nginx-manager.conffile. Without this file, you will only see the scan functions and the inventory page will display an error.
nginx-repo.cer(this may have the extension
.cer): This file is used to run NGINX Plus as a proxy for nginx-manager and is also used to pull packages from the public repositories. The apt and yum repository files reference this and the private key file below to pull packages. You can place these files in
/etc/ssl/nginxfollowing the instructions for setting up the repository below.
nginx-repo.key: This file is used with the crt file above for running NGINX Plus and accessing repositories for nginx-manager and nginx-agent.
To use the repositories without modification; rename, and move, the nginx-repo files to:
This method allows you to use a simple
apt-get install and use of the
- Create the /etc/ssl/nginx directory
$ sudo mkdir /etc/ssl/nginx $ cd /etc/ssl/nginx
Log in to MyF5 Customer Portal and download your nginx-manager-repo.crt and nginx-manager-repo.key files. You should rename nginx-repo.cer and nginx-repo.key (or similar name) to the suggested names.
Copy the files to the /etc/ssl/nginx/ directory.
$ sudo cp nginx-*.crt /etc/ssl/nginx/nginx-repo.crt $ sudo cp nginx-*.key /etc/ssl/nginx/nginx-repo.key
- Install the required certificate authority dependencies.
$ sudo yum install ca-certificates
$ sudo apt-get install apt-transport-https lsb-release ca-certificates $ sudo wget https://nginx.org/keys/nginx_signing.key $ sudo apt-key add nginx_signing.key
- Install the repository file.
$ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/instance-manager.repo
$ printf "deb https://pkgs.nginx.com/instance-manager/debian stable nginx-plus\n" | sudo tee /etc/apt/sources.list.d/instance-manager.list $ sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx $ sudo apt-get update
$ cat /etc/apt/apt.conf.d/90pkgs-nginx Acquire::https::pkgs.nginx.com::Verify-Peer "true"; Acquire::https::pkgs.nginx.com::Verify-Host "true"; Acquire::https::pkgs.nginx.com::SslCert "/etc/ssl/nginx/nginx-repo.crt"; Acquire::https::pkgs.nginx.com::SslKey "/etc/ssl/nginx/nginx-repo.key";
- Install the Instance Manager Server.
$ sudo yum install -y nginx-manager
If you have a signing key error run the following
$ curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key $ sudo rpmkeys --import /tmp/nginx_signing.key
$ sudo apt-get install -y nginx-manager
- Proceed to Server Configuration Section.
You will need the packages for NGINX Instance Manager. Download them directly from MyF5 Customer Portal
or use the one provided by your NGINX Sales Team. Run updates manually with this method (take the following steps and run the
apt-get update commands for newer packages).
$ sudo yum -y --nogpgcheck install /home/user/nginx-manager-0.9.0-1.x86_64.rpm
$ sudo yum -y --nogpgcheck upgrade /home/user/nginx-manager-0.9.1-1.x86_64.rpm
$ sudo apt-get -y install /home/user/nginx-manager-0.9.0-1_amd64.deb
$ sudo apt-get -y upgrade /home/user/nginx-manager-0.9.1-1_amd64.deb
Configure the NGINX Instance Manager Server for use with or without an NGINX proxy.
- Add the license file to the
/etc/nginx-managerdirectory. Ensure the name matches what is in the
nginx-manager.conffile. (above exmaple uses
NGINX Instance Manager defaults to running on 127.0.0.1 only (it is not exposed to external interfaces). It is recommmended to use the included NGINX Plus package to proxy traffic to NGINX Instance Manager.
If your organization prevents this or you wish to test Instance Manager in a secured environment without any authentication, you can enable Instance Manager to listen on external interfaces.
Open any required firewall ports or SELinux/apparmor rules for the ports and IPs you wish to use.
Edit the /etc/nginx-manager/nginx-manager.conf file and change the bind_address and ports to reflect your choices. For example, the following file will listen on 10.1.1.4 ip and use the default ports of 11000 for UI/API and 10000 for grpc
# # /etc/nginx-manager/nginx-manager.conf # # Configuration file for NGINX Instance Manager Server # bind address for all service ports (default "127.0.0.1") bind_address: 10.1.1.4 # gRPC service port for agent communication (default "10000") grpc_port: 10000 # gRPC-gateway service port for API and UI (default "11000") gateway_port: 11000 # SSL CN or servername for certs # server_name: nginx-manager.example.com # path to x.509 certificate file (optional) # cert: /etc/ssl/nginx-manager/nginx-manager.crt # path to x.509 certificate key file (optional) # key: /etc/ssl/nginx-manager/nginx-manager.key # set log level (panic, fatal, error, info, debug, trace; default: info) (default "info") log: level: info path: /var/log/nginx-manager/ # Metrics default storage path (default "/tmp/metrics") (directory must be already present) metrics: storage_path: /var/nginx-manager/ # Path to license file license: /etc/nginx-manager/nginx-manager.lic
You can also use 0.0.0.0 for the bind_address to enable all external ports (note this is insecure).
NGINX Instance Manager is designed as a web application with an API. NGINX Plus is our recommended solution for web applications requiring advanced authentication, proxy, and load balancing. A copy of NGINX Plus is included with the NGINX Instance Manager distribution to be used as a frontend for NGINX Instance Manager. This is the only permitted use of the included NGINX Plus instance. For external uses and other systems, contact your sales team to purchase additional subscriptions.
The repository certificate and key (
nginx-repo.key) can be used to pull an nginx-plus package that is used to proxy connections to
nginx-manager. To setup NGINX Plus, use the included certificate and key (it may be easier to copy them into
/etc/ssl/nginx/nginx-repo.key) and follow the NGINX Plus Installation Steps
NGINX Instance Manager also has an SELinux policy module that can be installed on SELinux enabled systems. It is provided as an RPM and can be pulled from the same repository as the server packages. You can do this manually as well and place ports in the httpd context.
$ sudo yum install -y nginx-manager_selinux
Instance Manager uses the nginx-manager_t context in the policy module and you will have to verify and add any ports you use. For external ports, you should also add them to the firewall exceptions.
To add a port to the nginx-manager context, you can use a similar command to one one below that adds 10000 and 11000:
$ sudo semanage port -a -t nginx_manager_port_t -p tcp 10000 $ sudo semanage port -a -t nginx_manager_port_t -p tcp 11000
If you already have defined the port context, replace
$ sudo semanage port -m -t nginx_manager_port_t -p tcp 10000 $ sudo semanage port -m -t nginx_manager_port_t -p tcp 11000
If you remove nginx-manager-selinux you should also remove the ports using a command similar to the one below:
$ sudo semanage port -d -t nginx_manager_port_t 10000 $ sudo semanage port -d -t nginx_manager_port_t 11000
For systemd systems perform the following steps.
- Start the NGINX Instance Manager Server.
$ sudo systemctl start nginx-manager
- Enable the NGINX Instance Manager Server to start on boot.
$ sudo systemctl enable nginx-manager
$ sudo initctl start nginx-manager
Point your browser to the FQDN and port you configured Instance Manager on. If your servername is nginx-manager.example.com and the port is 11000, then your browser can access the UI at http://nginx-manager.example.com:11000
To access the swagger-ui page, simply append ‘/swagger-ui’ to the end of the url. For example, the server above would be http://nginx-manager.example.com:11000/swagger-ui.
To access metrics through grafana or prometheus, configure the data source as a prometheus endpoint and add ‘/metrics’ to the end of the url. For example, the server above would be http://nginx-manager.example.com:11000/metrics.
After installing the server, you can configure options in multiple ways. The most common method is to utilize the configuration file, however, command-line options are also available.
NGINX Instance Manager uses a conf file located in /etc/nginx-manager/nginx-manager.conf by default.
The nginx-manager binary will look in the binary file location first for a configuration file, then use the /etc/nginx-manager/nginx-manager.conf file. Command line options also override these. The order of precendence from highest to lowest is:
- Command Line
- First config found (".", “/etc/nginx-manager”)
- Command Default
Here is a sample conf file and also the default when you install NGINX Instance Manager, located in /etc/nginx-manager/nginx-manager.conf
# # /etc/nginx-manager/nginx-manager.conf # # Configuration file for NGINX Instance Manager Server # bind address for all service ports (default "127.0.0.1") bind_address: 127.0.0.1 # gRPC service port for agent communication (default "10000") grpc_port: 10000 # gRPC-gateway service port for API and UI (default "11000") gateway_port: 11000 # SSL server name for use with cert and key below (optional) # server_name: # path to x.509 certificate file (optional) # cert: # path to x.509 certificate key file (optional) # key: # set log level (panic, fatal, error, info, debug, trace; default: info) (default "info") log: level: info path: /var/log/nginx-manager/ # Metrics default storage path (default "/tmp/metrics") (directory must be already present) metrics: storage_path: /var/nginx-manager/
- Configure Authentication on the Server
- Configure nginx-agent on nginx instances
- Use Grafana to display metrics
- Scan a network range for new instances