Getting started
Overview
Follow these steps to configure and run NGINX Agent and a mock interface (“control plane”) to which NGINX Agent will report.
Install NGINX
Follow the steps in the Installation section to download, install, and run NGINX.
Clone the NGINX Agent Repository
Using your preferred method, clone the NGINX Agent repository into your development directory. See Cloning a GitHub Repository for additional help.
Install Go
NGINX Agent and the Mock Control Plane are written in Go. Go 1.22 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 gRPC Mock Control Plane
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[0000] http listening at 54790 # mock control plane port
INFO[0000] grpc listening at 54789 # grpc control plane port which NGINX Agent will report to
NGINX Agent Settings
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/
Create the agent-dynamic.conf
file, which is required for NGINX Agent to run.
In Linux environments:
sudo touch /var/lib/nginx-agent/agent-dynamic.conf
In FreeBSD environments:
sudo touch /var/db/nginx-agent/agent-dynamic.conf
Enable the gRPC interface
Add the the following settings to /etc/nginx-agent/nginx-agent.conf
:
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.
Enable the REST interface
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:
# Set API address to allow remote management
host: 127.0.0.1
# Set this value to a secure port number to prevent information leaks
port: 8038
# 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.
Launch Swagger UI
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:
make launch-swagger-ui
Extensions
An extension is a piece of code, not critical to the main functionality that 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 /etc/nginx-agent/nginx-agent.conf
.
Here is an example of enabling the advanced metrics extension:
extensions:
- advanced-metrics
Start NGINX Agent
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 NGINX Agent. Issue the following command from the agent
source code root directory.
sudo make run
# Command Output snippet
WARN[0000] Log level is info
INFO[0000] setting displayName to XXX
INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX
INFO[0000] NginxBinary initializing
INFO[0000] Commander initializing
INFO[0000] Comms initializing
INFO[0000] OneTimeRegistration initializing
INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX
INFO[0000] Metrics initializing
INFO[0000] MetricsThrottle initializing
INFO[0000] DataPlaneStatus initializing
INFO[0000] MetricsThrottle waiting for report ready
INFO[0000] Metrics waiting for handshake to be completed
INFO[0000] ProcessWatcher initializing
INFO[0000] Extensions initializing
INFO[0000] FileWatcher initializing
INFO[0000] FileWatchThrottle initializing
INFO[0001] Events initializing
INFO[0001] 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.
Start and Enable Start on Boot
To start NGINX Agent on systemd
systems, run the following command:
sudo systemctl start nginx-agent
To enable NGINX Agent to start on boot, run the following command:
sudo systemctl enable nginx-agent
Logs
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 /var/log/nginx-agent
.
Important:
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.
For more information, see NGINX Agent Log Rotation.