Agent Install and Configuration

An NGINX Agent installation and configuration document.

You are not viewing the latest documentation for Instance Manager. Visit to read the latest content.

This document helps you get NGINX Agent up and running.


  1. Get the installation packages or binaries.
  2. Get the license files.
    1. Download the NGINX Instance Manager Server license file (for production use).
    2. Optional: Download the repository certificate and key (for repository (“repo”) access).
  3. Install and configure the NGINX Instance Manager Server.
    1. Know the fully qualified domain name (“FQDN”) and gRPC port number.
    2. This document uses the example
  4. Have NGINX running on your instance.
    1. Know the binary location for NGINX.
    2. 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.

Install Agent

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.

License File Locations

There are two license files included with nginx-agent that are needed for the repository install:

  1. nginx-repo.crt or 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/nginx following the instructions for setting up the repository below.
  2. 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:

  • /etc/ssl/nginx/nginx-repo.crt
  • /etc/ssl/nginx/nginx-repo.key

Install from the NGINX public repositories

This method allows you to use a simple yum or apt-get install and use of the nginx-repo.crt and nginx-repo.key.

  1. Create the /etc/ssl/nginx directory
sudo mkdir /etc/ssl/nginx
cd /etc/ssl/nginx
  1. 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.

  2. 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
  1. Install the required certificate authority dependencies.

sudo yum install ca-certificates

sudo apt-get install apt-transport-https lsb-release ca-certificates
sudo wget
sudo apt-key add nginx_signing.key
  1. Install the repository file.

sudo wget -P /etc/yum.repos.d

printf "deb 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
sudo apt-get update
cat /etc/apt/apt.conf.d/90pkgs-nginx "true"; "true";     "/etc/ssl/nginx/nginx-repo.crt";      "/etc/ssl/nginx/nginx-repo.key";
  1. 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
sudo rpmkeys --import /tmp/nginx_signing.key

sudo apt-get install -y nginx-agent
  1. Proceed to Agent Configuration Section.

Install from package files directly

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 rpm or apt-get update commands for newer packages).

  1. Installation.
sudo yum -y --nogpgcheck install /home/user/nginx-agent-1.0.1-1.x86_64.rpm
  1. Upgrades.
sudo yum -y --nogpgcheck upgrade /home/user/nginx-agent-1.0.2-1.x86_64.rpm

  1. Installation.
sudo apt-get -y install /home/user/nginx-agent_1.0.1-1_amd64.deb
  1. Upgrades.
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 Instance Manager configuration

NGINX Agent defaults to on a new installation which almost always fails (you must change the server flag).

  1. Open any required firewall ports or SELinux/apparmor rules for the ports and IPs you want to use.

  2. Edit the /etc/nginx-agent/nginx-agent.conf file and change the server and ports to reflect your choices. For example, the following file will listen on IP and use the default ports of 11000 for UI/API and 10000 for gRPC.

Additionally, you can specify a separate metrics address via metrics_server, as well as specifying TLS with metrics-tls. server on it’s own will use the same address and TLS for both.

The 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_status if you use NGINX Plus or plus_api line 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
# tls options
  # 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
  # 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
  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
  # 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:
  stub_status: ""
  # specify plus status api url (see
  plus_api: ""
  # specify metrics poll interval
  metrics_poll_interval: 1000ms

SELinux for nginx-agent

Install SELinux Policy Module

sudo yum install -y nginx-agent_selinux

Add ports for Instance Manager SELinux context

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

Start and Enable NGINX Agent

For systemd systems perform the following steps.

  1. Start the NGINX Agent.
sudo systemctl start nginx-agent
  1. Enable the NGINX Agent to start on boot.
sudo systemctl enable nginx-agent

sudo initctl start nginx-agent

What’s Next

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 Management Suite: v1.