Agent Install and Configuration
An NGINX Agent installation and configuration document.
You are not viewing the latest documentation for NGINX Instance Manager. Please visit https://docs.nginx.com/nginx-instance-manager to read the latest content.
This document helps you get NGINX Agent up and running.
- Get the installation packages or binaries.
- Get the license files.
- Download the NGINX Instance Manager Server license file (for production use).
- Optional: Download the repository certificate and key (for repository (“repo”) access).
- Install and configure the NGINX Instance Manager Server.
- Know the fully qualified domain name (“FQDN”) and gRPC port number.
- This document uses the example
- Have NGINX running on your instance.
- Know the binary location for NGINX.
- Know the process ID (“pid”) location for NGINX.
You can run NGINX Open Source or NGINX Plus, or your own compiled version of NGINX. Our support list is suggestive. We currently offer 64bit (x86_64 and amd64) binaries and packages that can run on a variety of 64bit Linux systems.
The most difficult part is getting the packages onto your installed OS. You can choose one of the following two options:
- Use the public NGINX repositories with a certificate and key or an internal package management system (e.g. Red Hat Satellite)
- Use the packages directly by downloading them from the myF5 portal or from your NGINX/F5 sales team.
There are two license files included with
nginx-agent that are needed for the repository install:
nginx-repo.cer(this may have the extension
.cer): This file is 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/nginx-agent.repo
printf "deb https://pkgs.nginx.com/nginx-agent/debian stable nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-agent.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 NGINX Agent.
sudo yum install -y nginx-agent
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-agent
- Proceed to Agent Configuration Section.
You will need the packages for NGINX Instance Manager. Download them directly from the MyF5 Customer Portal or use the one provided by your NGINX Sales Team. Run the updates manually with this method (follow the steps below and run the
apt-get update commands for newer packages).
sudo yum -y --nogpgcheck install /home/user/nginx-agent-1.0.1-1.x86_64.rpm
sudo yum -y --nogpgcheck upgrade /home/user/nginx-agent-1.0.2-1.x86_64.rpm
sudo apt-get -y install /home/user/nginx-agent_1.0.1-1_amd64.deb
sudo apt-get -y upgrade /home/user/nginx-agent_1.0.2-1_amd64.deb
Configure the NGINX Instance Manager Server for use with or without an NGINX proxy.
NGINX Agent defaults to
127.0.0.1 on a new installation which almost always fails (you must change the server flag).
Open any required firewall ports or SELinux/apparmor rules for the ports and IPs you want to use.
/etc/nginx-agent/nginx-agent.conffile and change the server and ports to reflect your choices. For example, the following file will listen on
10.1.1.4IP and use the default ports of
11000for UI/API and
Additionally, you can specify a separate metrics address via
metrics_server, as well as specifying TLS with
server on it’s own will use the same address and TLS for both.
api-token argument is also exposed and will be added to client streaming if specified in order to authenticate to NCC metrics ingest and command services.
Change the appropriate options below, focusing on the server, bin_path, conf_path, and the URLs (depending on if you use NGINX Open Source or NGINX Plus).
Comment out the
stub_statusif you use NGINX Plus or
plus_apiline if you use NGINX Open Source. Otherwise you will receive 400 errors as the agent checks that location for metrics. For NGINX Open Source, you may also want to disable access logging on the stub_status page to keep those responses out of the metrics collection.
# # /etc/nginx-agent/nginx-agent.conf # # Configuration file for NGINX Agent # specify the server grpc port to connect to server: nginx-manager.example.com:10000 # tls options tls: # path to certificate cert: /etc/ssl/nginx-agent/agent.crt # path to certificate key key: /etc/ssl/nginx-agent/agent.key # path to CA cert bundle ca: /etc/ssl/nginx-agent/ca.pem log: # set log level (panic, fatal, error, info, debug, trace; default: info) (default "info") level: info # set log path. if empty, don't log to file. path: /var/log/nginx-agent/ # (optional) tags for this specific instance / machine for inventory purposes metadata: location: unspecified # instance tags # tags: # - web # - staging # - etc # list of allowed config directories (comma-separated) config_dirs: /etc/nginx,/usr/local/etc/nginx # nginx configuration options nginx: # path of nginx to manage bin_path: /usr/sbin/nginx # path of nginx config to manage conf_path: /etc/nginx/nginx.conf # specify stub status URL (see: nginx.org/r/stub_status) stub_status: "http://127.0.0.1:80/nginx_status" # specify plus status api url (see nginx.org/r/api) plus_api: "http://127.0.0.1:8080/api" # specify metrics poll interval metrics_poll_interval: 1000ms
sudo yum install -y nginx-agent_selinux
NGINX may need some adjustments to comply with SELinux, especially for ports outside the httpd context. Refer to the article Using NGINX and NGINX Plus with SELinux for more information. For external ports, you should also add them to the firewall exceptions.
When using ports outside the standard httpd context, you may need to allow nginx to connect to them. A boolean is enabled below to do this.
sudo setsebool -P httpd_can_network_connect 1
For systemd systems perform the following steps.
- Start the NGINX Agent.
sudo systemctl start nginx-agent
- Enable the NGINX Agent to start on boot.
sudo systemctl enable nginx-agent
sudo initctl start nginx-agent
Check the browser interface or API on the Instance Manager server, you should now see your instance on the inventory list. There is no additional action needed to have the instance information come up. To remove the instance, ensure that the service is stopped and won’t run. Then you can remove the instance in the inventory.
This documentation applies to the following versions of NGINX Instance Manager: v1.