Configure the NGINX Controller Agent
Customize the NGINX Controller Agent configuration
Follow the steps in this guide to customize the NGINX Controller Agent configuration.
Default Agent Settings
To access the Default Agent Settings page:
- Open the NGINX Controller user interface and log in.
- Select the NGINX Controller menu icon, then select Platform.
- On the Platform menu, select Agent.
On the Default Agent Settings page, you can set the following default settings for the NGINX Controller Agent:
- NGINX configuration file analysis. This setting is enabled by default.
- Periodic NGINX configuration syntax checking with “nginx -t”. This setting is disabled by default.
- Analyzing SSL certs. This setting is enabled by default.
Enable /api Location
NGINX Controller uses the
/api location on the NGINX Plus instance to collect metrics.
When you push a configuration to an NGINX Plus instance, NGINX Controller automatically enables the
/api location for that instance.
/apilocation settings that NGINX Controller creates will override any settings that you have previously defined.
If you use NGINX Controller solely to monitor your NGINX Plus instances, you may need to enable the
/api location on your instances manually.
Refer to the Configuring the API section of the NGINX Plus Admin Guide for instructions.
Controller Agent Configuration File
The configuration file for the NGINX Controller Agent is located at
/etc/controller-agent/agent.conf. This configuration file is a text-based file.
Change the API Key
When you first install the NGINX Controller Agent, your API key is written to the
agent.conf file automatically. If you ever need to change the API key, you can edit the following section in
[credentials] api_key = YOUR_API_KEY
Change the Hostname and UUID
To create unique objects for monitoring, the NGINX Controller Agent must be able to extract a valid hostname from the system. The hostname is also used as one of the components for generating a unique identifier. Essentially, the hostname and the UUID (universally unique identifier) unambiguously identify a particular instance of the NGINX Controller Agent to NGINX Controller. If the hostname or the UUID are changed, the NGINX Controller Agent and the server will register a new object for monitoring.
The NGINX Controller Agent tries its best to determine the correct hostname. If the Agent cannot determine the hostname, you can set the hostname in the
agent.conf file. Check for the following section, and provide the desired hostname here:
[credentials] .. hostname = myhostname1
The hostname should be real. The NGINX Controller Agent won’t start unless a valid hostname is defined. The following are not valid hostnames:
You can use the above method to replace the system’s hostname with an arbitrary alias. Keep in mind that if you redefine the hostname for a live object, the existing object will be marked as failed in the NGINX Controller user interface. Redefining the hostname in the NGINX Controller Agent’s configuration creates a new UUID and a new system for monitoring.
Alternatively, you can define an alias for the host in the NGINX Controller user interface. Go to the Graphs page, select the system that you want to update, and click the gear icon.
Preserving the UUID across OS upgrades
The UUID is generated based on a combination of the hostname and underlying OS functions. An upgrade to the OS may lead to a new UUID and cause previously registered agents to be offline.
If your use case requires that the UUID persist across upgrades, you can set the
store_uuid option in
[credentials] ... store_uuid = True
After restarting the Controller Agent –
service controller-agent restart – the UUID will be persisted to
agent.conf and used for future instance detection.
Set the Path to the NGINX Configuration File
The NGINX Controller Agent detects the NGINX configuration file automatically. You shouldn’t need to point the NGINX Controller Agent to the
nginx.conf file explicitly.
You should not make manual changes to the
nginx.conffile on NGINX Plus instances that are managed by NGINX Controller. Manually updating the
nginx.conffile on managed instances may adversely affect system performance. In most cases, NGINX Controller will revert or overwrite manual updates made to
If, for some reason, the NGINX Controller Agent cannot find the NGINX configuration, you can use the following option in
/etc/controller-agent/agent.conf to point to the configuration file:
[nginx] configfile = /etc/nginx/nginx.conf
We recommend using this option only as a workaround if needed. If you do need to add the path to the NGINX config file, we ask that you contact NGINX Support so they can help troubleshoot the issue.
Set Host Tags
You can define arbitrary tags on a “per-host” basis. Tags can be configured in the Controller user interface on the Graphs page, or set in the
[credentials] tags = foo bar foo:bar
Any changes to instance Tags made in the Controller user interface will overwrite the values stored in
You can use tags to build custom graphs, configure alerts, and filter the systems on the Graphs page in the Controller user interface.
Logging to Syslog
NGINX Admin Guide - Logging to Syslog
The NGINX Controller Agent can collect NGINX log files using
syslog. This could be useful when you don’t keep the NGINX logs on disk, or when monitoring a container environment such as Docker with NGINX Controller.
To configure the NGINX Controller Agent to send logs to
Add the following to the
[listeners] keys = syslog-default [listener_syslog-default] address = 127.0.0.1:12000
Restart the NGINX Controller Agent. This will reload the configuration, and the Agent will start listening on the specified IP address and port:
# service controller-agent restartImportant:
Make sure you add the
syslogsettings to your NGINX configuration file as well.
Exclude Certain NGINX Log Files
By default, the NGINX Controller Agent tries to find and watch all
access.log files described in the NGINX configuration. If there are multiple log files where the same request is logged, the metrics may be counted more than once.
To exclude specific NGINX log files from the metrics collection, add lines similar to the following to
Set Up a Proxy
If your system is in a DMZ environment without direct access to NGINX Controller, the only way for the NGINX Controller Agent to report collected metrics to NGINX Controller is through a proxy.
The NGINX Controller Agent will use the usual environment variables common on Linux systems (for example,
HTTP_PROXY). However, you can also define HTTPS proxy manually in
agent.conf. This can be done as follows:
[proxies] https = https://10.20.30.40:3030 ..
Controller Agent Logfile
The NGINX Controller Agent maintains its log file in
Upon installation, the NGINX Controller Agent’s log rotation schedule is added to
The normal level of logging for the NGINX Controller Agent is
INFO. If you ever need to debug the NGINX Controller Agent, change the level to
DEBUG as described below.
The size of the NGINX Controller Agent’s log file can proliferate in
DEBUGmode. You should use
DEBUGmode only for troubleshooting purposes.
Change the Agent Log Level
To change the log level for the NGINX Controller Agent:
[loggers]section of the NGINX Controller Agent configuration file –
levelto one of the following:
[loggers] level = DEBUG ...
Restart the NGINX Controller Agent to make the changes take effect.
This documentation applies to the following versions of NGINX Controller: 3.0, 3.1, 3.2, 3.3, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17, 3.18, 3.18.1, 3.18.2 and 3.18.3.
This documentation applies to the following versions of NGINX Controller API Management module: 3.18, 3.18.1, 3.19, 3.19.1, 3.19.2, 3.19.3 and 3.19.4.
This documentation applies to the following versions of NGINX Controller App Delivery module: 3.20, 3.20.1, 3.21, 3.22, 3.22.1, 3.22.2, 3.22.3, 3.22.4, 3.22.5 and 3.22.6.