Learn how to configure and run NGINX Agent.
Follow these steps to configure and run NGINX Agent and a mock interface (“control plane”) to which the NGINX Agent will report.
Follow the steps in the Installation section to download, install, and run NGINX.
Using your preferred method, clone the NGINX Agent repository into your development directory. See Cloning a GitHub Repository for additional help.
NGINX Agent and the Mock Control Plane are written in Go. Go 1.21.0 or higher is required to build and run either application from the source code directory. You can download Go from the official website.
Start the mock control plane by running the following command from the
agent source code root directory:
go run sdk/examples/server.go # Command Output INFO http listening at 54790 # mock control plane port INFO grpc listening at 54789 # grpc control plane port which NGINX Agent will report to
If it doesn’t already exist, create the
/etc/nginx-agent/ directory and copy the
nginx-agent.conf file into it from the project root directory.
sudo mkdir /etc/nginx-agent sudo cp <project_root_directory>/nginx-agent.conf /etc/nginx-agent/
agent-dynamic.conf file in the
/var/lib/nginx-agent/ directory, which is required for NGINX Agent to run.
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
Add the the following settings to
server: host: 127.0.0.1 # mock control plane host grpcPort: 54789 # mock control plane gRPC port # gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION tls: enable: false skip_verify: true
For more information, see Agent Protocol Definitions and Documentation
The NGINX Agent REST interface can be exposed by validating the following lines in the
/etc/nginx-agent/nginx-agent.conf file are present:
api: port: 8081 # port to expose REST API # REST TLS parameters cert: "<TLS-CERTIFICATE>.crt" key: "<PRIVATE-KEY>.key"
The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent.
Swagger UI requires goswagger be installed. See instructions for installing goswagger for additional help.
To launch the Swagger UI for the REST interface run the following command
An extension is a piece of code, not critical to the main functionality that the NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics.
To enable an extension, it must be added to the extensions list in the
Here is an example of enabling the advanced metrics extension:
extensions: - advanced-metrics
If already running, restart NGINX Agent to apply the new configuration. Alternatively, if NGINX Agent is not running, you may run it from the source code root directory.
Open another terminal window and start the NGINX Agent. Issue the following command from the
agent source code root directory.
sudo make run # Command Output snippet WARN Log level is info INFO setting displayName to XXX INFO NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX INFO NginxBinary initializing INFO Commander initializing INFO Comms initializing INFO OneTimeRegistration initializing INFO Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX INFO Metrics initializing INFO MetricsThrottle initializing INFO DataPlaneStatus initializing INFO MetricsThrottle waiting for report ready INFO Metrics waiting for handshake to be completed INFO ProcessWatcher initializing INFO Extensions initializing INFO FileWatcher initializing INFO FileWatchThrottle initializing INFO Events initializing INFO OneTimeRegistration completed
Open a web browser to view the mock control plane at http://localhost:54790. The following links will be shown in the web interface:
- registered - shows registration information of the data plane
- nginxes - lists the nginx instances on the data plane
- configs - shows the protobuf payload for NGINX configuration sent to the management plane
- configs/chunked - shows the split-up payloads sent to the management plane
- configs/raw - shows the actual configuration as it would live on the data plane
- metrics - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API)
For more NGINX Agent use cases, refer to the NGINX Agent SDK examples.
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
NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for
Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services.