Before the latest release, NGINX had to be controlled exclusively by Unix signals. The most notable one is SIGHUP or the well-known “nginx -s reload” command. This configuration method, while very stable, does not meet modern environment requirements: there are very few available options, no direct feedback messages on errors, and no real extensibility. We fixed that.
NGINX recently published the version 1.31.5 release containing a new feature called the NGINX Control API. This is a new interface for reading configuration and triggering reload operations that presents these functions to the user over a REST API. Filesystem system configuration files and UNIX signal daemon management are not optimal for all users of NGINX. With the rise of Kubernetes and the continued dominance of containers as a deployment target for NGINX we wanted to provide configuration and management interfaces that better support using NGINX in containers or behind managed deployments. The NGINX Control API provides a way to read and reload configuration that is transactional, returning deterministic success or failure codes as any HTTP response would. This Control API can be served across a trusted network. Furthermore, the Control API provides an interface that does not experience any interruption during reload.
Newly released, this Control API provides the ability to read the current in-memory configuration associated with a master process. This is a completely new capability. Since NGINX has always had the potential to reject a new configuration and continue unaffected during a reload, users sometimes fall into a trap where they no longer know what configuration NGINX is then running. The configuration on disk may have completely changed but NGINX is still running some old configuration. Before Control API there was no method of retrieving that current configuration. Finally in these cases the user can simply fetch it with an HTTP request.
The Control API also provides facilities to trigger NGINX reloads. This will capture all logs during reload and return them in the response to the user. Additionally, the HTTP status code in this response will provide a simple way to answer the question “did this reload succeed or fail”. Previously, users may have had to export and search through logs for this information or potentially check PIDs of worker processes. The Control API holds a unique position to capture post-reload failures such as socket permission errors that previously were only observable through the logs of a new master process. These failures, while not loggable by the old master configuration, are reflected in the HTTP status code of the response. This is a new capability for NGINX. Previously users who relied on commands such as “nginx -s reload” or by sending SIGHUP to the master process had to then search the logs to make sure the reload succeeded. Now this information is relayed to them automatically when they request a reload over the Control API.
Examples
A request to view the current configuration:
curl --unix-socket /tmp/unix 0.0.0.0/1/control/config | jq
[
{
"name": "/path/to/nginx.conf",
"content": "..."
},
{
"name": "/path/to/included.conf",
"content": "..."
}
]
A successful reload request:
curl --unix-socket /tmp/unix 0.0.0.0/1/control/config -X PATCH -v | jq
< HTTP/1.1 200 OK
< ...
<
{
"logs": []
}
A reload request that returns an error:
curl --unix-socket /tmp/unix 0.0.0.0/1/control/config -X PATCH -v | jq
< HTTP/1.1 422 Unprocessable Entity
< ...
<
{
"logs": [
"...: invalid number of arguments in \listen\ directive"
]
}
We have published the complete OpenAPI specification for the Control API in the documentation.
In our experience, this API makes it trivially simple to create UIs and scripts for advanced NGINX management and control.
Security Notes
The Control API socket is not open by default. Turn it on explicitly while starting the NGINX master process by passing the “-l” flag along with a network address or UNIX domain socket path.
While the Control API can be configured on a network address, we strongly discourage this for security reasons. If you can, run it on a Unix socket.
The Control API provides open access to the NGINX configuration and reload functionality without authentication or authorization. It is recommended to serve this API over a UNIX domain socket with locked-down file permissions for root-only access. Please fully research your security guidelines and access permissions before turning it on. That said, network address-based listening for the Control API may still be useful across trusted networks like VPNs, or if served by a proxy from an upstream configuration containing proper security features.
NGINX Control API is a major step in making NGINX more modern and dynamic. To try it, install NGINX 1.31.5 or later or NGINX Plus 37. Read the reference documentation here and the installation guide here.
