Install and Configure NGINX Agent

Follow the instructions in this guide to install and configure the NGINX Agent on your data plane systems.


This documentation applies to NGINX Instance Manager 2.0.0 and later.


Prerequisites

This section lists the prerequisites for installing and configuring NGINX Agent. Follow the steps below to complete the requirements:

  1. NGINX Instance Manager is installed and configured on a server.

    Note:
    When installing and configuring NGINX Instance Manager, take note of the fully qualified domain name (FQDN) and gRPC port number. You’ll need this information to properly configure the NGINX Agent to communicate with NGINX Instance Manager.
  2. Make sure NGINX is running on your instance:

    ps aux | grep nginx
    
  3. If a previous version of NGINX Agent was installed, you must stop the current NGINX Agent process before running the NGINX Agent install script. To check if any NGINX Agent processes are running, run the following command:

    ps aux | grep nginx-agent
    
  4. If a previous version of NGINX Agent was installed, make sure to uninstall nginx-agent-selinux before running the NGINX Agent install script. To see if nginx_agent_selinux is installed, run the following command:

    rpm -qa | grep nginx_agent_selinux
    

    dpkg -s nginx_agent_selinux
    
  5. Review the Technical Specifications guide for system requirements.


Install NGINX Agent

You can choose one of the following two methods to install the NGINX Agent on your data plane host:

  • Install via the NGINX Instance Manager API Gateway
  • Install from packages downloaded from MyF5 Customer Portal or from your NGINX/F5 sales team.

Install using the API

You can install the NGINX Agent using curl, wget, or any command-line tool for transferring data with URLs. If the NGINX Instance Manager server is not set up with valid TLS certificates, you can use the available insecure flags of those tools. See the following examples:

  • curl

    curl https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo sh
    
  • insecure curl

    curl -k https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo sh
    
  • wget

    wget https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent -O - | sudo sh
    
  • insecure wget

    wget --no-check-certificate https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent -O - | sudo sh
    

When installing the NGINX Agent with the install script, you can optionally set the instance-name and instance-group with the following flags:

  • --instance-name

  • --instance-group

The following curl example shows how to download and run the script with the optional flags:

curl https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent > install.sh
sudo sh ./install.sh --instance-name my-instance-name --instance-group my-instance-group

Installing from Package Files

To install directly from package files, you’ll need to download the files from the MyF5 Customer Portal or use the package files provided by your NGINX Sales Team. The file you need is agent-install.sh.

To install from package files, take the following steps:

  1. Copy agent-install.sh to the data plane host where you want to install the NGINX Agent.

  2. Run the following command to install OR update NGINX Agent:

    sudo PACKAGE_HOST=<NGINX-INSTANCE-MANAGER-FQDN> ./agent-install.sh 
    
    Note:
    In the example above, <NGINX-INSTANCE-MANAGER-FQDN> is the the fully qualified domain name or IP address for the NGINX Instance Manager API gateway.


Start and Enable NGINX Agent

To start the NGINX Agent on systemd systems, run the following command:

sudo systemctl start nginx-agent

To enable the NGINX Agent to start on boot, run the following command:

sudo systemctl enable nginx-agent


Verifying NGINX Agent is Running and Registered

Run the following command on your data plane to verify that the NGINX Agent process is running:

ps aux | grep nginx-agent

You should see output that looks similar to the following example:

root      293850  109  1.1 1240056 23536 ?       Ssl  22:00   0:07 /usr/local/bin/nginx-agent
vagrant   293866  0.0  0.0   8160   736 pts/0    S+   22:00   0:00 grep --color=auto nginx-agent

Once you’ve verified the NGINX Agent is running on your data plane, you should confirm it’s registered with NGINX Instance Manager. You can do this two ways:

  • (API) Send an API request similar to the following example to get the inventory list. Your instance should be listed.

    curl -u <user>:<password> https://<NGINX-INSTANCE-MANAGER-FQDN>/api/platform/v1/systems | jq
    
  • (Web interface) Open the NGINX Instance Manager web interface and log in. The registered instance is shown in the Instances list.


    Registered instances

Once you’ve verified the NGINX Agent instance is registered with NGINX Instance Manager, no additional action is required for monitoring the instance.

Note:
If you need to remove the instance, ensure that the NGINX Agent service is stopped first. Then you can remove the instance from the inventory.


Configuring NGINX Agent

The following sections explain how to configure the NGINX Agent using configuration files, CLI flags, and environment variables.

Note:
  • The NGINX Agent interprets configuration values set by configuration files, CLI flags, and environment variables in the following priorities:

    1. CLI flags overwrite configuration files and environment variable values.
    2. Environment variables overwrite configuration file values.
    3. Config files are the lowest priority and config settings are superseded if either of the other options is used.
  • The NGINX Agent is configured by default to connect to the NGINX Instance Manager server on port 443 based on the address used to download the install script. If this setting doesn’t work, you can change the server fields in the nginx-agent.conf file. Instructions are provided in the following sections.

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

Configuring via Config File

The configuration files for the NGINX Agent are /etc/nginx-agent/nginx-agent.conf and /etc/nginx-agent/agent-dynamic.conf. These files have comments at the top indicating their purpose.

Examples of the configuration files are provided below:

example nginx-agent.conf
Note:
In the following example nginx-agent.conf file, you can change the server.host and server.grpcPort to connect to the NGINX Instance Manager server.
#
# /etc/nginx-agent/nginx-agent.conf
#
# Configuration file for NGINX Agent.
#
# This file tracks agent configuration values that are meant to be statically set. There  
# are additional agent configuration values that are set via the API and agent install script
# which can be found in /etc/nginx-agent/agent-dynamic.conf. 

# specify the server grpc port to connect to
server:
  # host of the control plane
  host: <NGINX-INSTANCE-MANAGER-FQDN>
  grpcPort: 443
  # metrics: "agent-ingest"
  # command: "dataplane-manager"
# tls options
tls:
  # enable tls in the nginx-agent setup for grpcs
  # default to enable to connect with secure connection but without client cert for mtls
  enable: true
  # controls whether the server certificate chain and host name are verified.
  # for production use, see instructions for configuring TLS
  skip_verify: false
log:
  # set log level (panic, fatal, error, info, debug, trace; default "info")
  level: info
  # set log path. if empty, don't log to file.
  path: /var/log/nginx-agent/
nginx:
  # path of NGINX logs to exclude
  exclude_logs: ""
# data plane status message / 'heartbeat'
dataplane:
  # watch the config_dirs to keep the dataplane and control plane in sync
  sync: 
    enable: true
  # poll interval for data plane status
  status:
    poll_interval: 30s
metrics:
  # specify the size of a buffer to build before sending metrics
  bulk_size: 20
  # specify metrics poll interval
  report_interval: 1m
  collection_interval: 15s
  mode: aggregated

# OSS NGINX default config path
# path to aux file dirs can also be added
config_dirs: "/etc/nginx:/usr/local/etc/nginx"

example dynamic-agent.conf
#
# /etc/nginx-agent/dynamic-agent.conf
#
# Dynamic configuration file for NGINX Agent.
#
# The purpose of this file is to track agent configuration
# values that can be dynamically changed via the API and the agent install script.
# You may edit this file, but API calls that modify the tags on this system will
# overwrite the tag values in this file.
#
# The agent configuration values that API calls can modify are as follows:
#    - tags
#
# The agent configuration values that the agent install script can modify are as follows:
#    - instance_name
#    - instance_group
#    - location

instance_group: devenv-group 
instance_name: devenv-agent
tags:
  - devenv
  - test

NGINX Agent CLI Flags & Usage

This section displays the configurable options for the NGINX Agent that can be set with CLI flags. See the CLI flags and their uses in the figure below:

NGINX Agent CLI flags & usage
Usage:
  nginx-agent [flags]
  nginx-agent [command]

Available Commands:
  completion  Generate completion script.
  help        Help about any command

Flags:
      --config-dirs string                     Defines the paths that you want to grant nginx-agent read/write access to. This key is formatted as a string and follows Unix PATH format. (default "/etc/nginx:/usr/local/etc/nginx")
  -h, --help                                   help for nginx-agent
      --instance-group string                  The instance's 'group' value.
      --instance-name string                   The instance's 'name' value.
      --log-level string                       The desired verbosity level for logging messages from nginx-agent. Available options, in order of severity from highest to lowest, are: panic, fatal, error, info, debug, and trace. (default "info")
      --log-path string                        The path to output log messages to. If the default path doesn't exist, log messages are output to stdout/stderr. (default "/var/log/nginx-agent")
      --metrics-collection-interval duration   Sets the interval, in seconds, at which metrics are collected. (default 15s)
      --metrics-mode string                    Sets the desired metrics collection mode: streaming or aggregation. (default "aggregation")
      --nginx-exclude-logs string              One or more NGINX access log paths that you want to exclude from metrics collection. This key is formatted as a string and multiple values should be provided as a comma-separated list.
      --server-grpcport int                    The desired GRPC port to use for nginx-agent traffic. (default 443)
      --server-host string                     The IP address of the server host. IPv4 addresses and hostnames are supported. (default "127.0.0.1")
      --server-token string                    An authentication token that grants nginx-agent access to the commander and metrics services. Auto-generated by default. (default "647c3ada-042c-49d0-b8a5-3bce8ac142b3")
      --tags strings                           A comma-separated list of tags to add to the current instance or machine, to be used for inventory purposes.
      --tls-ca string                          The path to the CA certificate file to use for TLS.
      --tls-cert string                        The path to the certificate file to use for TLS.
      --tls-enable                             Enables TLS for secure communications.
      --tls-key string                         The path to the certificate key file to use for TLS.
  -v, --version                                version for nginx-agent

Use "nginx-agent [command] --help" for more information about a command.

NGINX Agent Environment Variables

This section displays the configurable options for the NGINX Agent that can be set with environment variables. A list of the configurable environment variables can be seen below:

NGINX Agent Environment Variables
- NMS_INSTANCE_GROUP
- NMS_INSTANCE_NAME
- NMS_LOG_LEVEL
- NMS_PATH
- NMS_METRICS_COLLECTION_INTERVAL
- NMS_METRICS_MODE
- NMS_NGINX_EXCLUDE_LOGS
- NMS_SERVER_GRPCPORT
- NMS_SERVER_HOST
- NMS_SERVER_TOKEN
- NMS_TAGS
- NMS_TLS_CA
- NMS_TLS_CERT
- NMS_TLS_ENABLE
- NMS_TLS_KEY
- NMS_CONFIG_DIRS


SELinux for NGINX Agent

This section explains how to install and configure the SELinux policy for the NGINX Agent.

Installing NGINX Agent SELinux Policy Module

The NGINX Agent package includes the following SELinux files:

  • /usr/share/man/man8/nginx_agent_selinux.8.gz
  • /usr/share/selinux/devel/include/contrib/nginx_agent.if
  • /usr/share/selinux/packages/nginx_agent.pp

To install and load the policy, run the following commands:

sudo semodule -n -i /usr/share/selinux/packages/nginx_agent.pp
sudo /usr/sbin/load_policy

Adding Ports for NGINX Agent SELinux Context

You can modify the NGINX Agent to comply with SELinux. You should add external ports to the firewall exception.

The following example shows how to allow external ports outside the HTTPD context. You may need to enable NGINX to connect to these ports.

sudo setsebool -P httpd_can_network_connect 1

For additional information on using NGINX with SELinux, refer to the guide Using NGINX and NGINX Plus with SELinux.



Secure the NGINX Agent with mTLS

Important:
By default, communication between the NGINX Agent and NGINX Instance Manager is unsecured.

For instructions on how configure mTLS to secure communication between the NGINX Agent and NGINX Instance Manager, see NGINX Agent TLS Settings.



NGINX Metrics

After you register an NGINX instance with NGINX Instance Manager, the NGINX Agent will collect and report metrics. For more information about the metrics that are reported, see Overview: Instance Metrics.