Remote agents: modes and options¶
This page details how the agent installed on a remote Docker host works. For installation and approval, see Auto-configuration with Docker on a remote host.
The agent reads the nginx-control.* labels of the containers on its host, builds a manifest and periodically pushes it to NGX Ops with a token. A label's target (target, or its alias proxy_pass) is an address reachable from the host that serves it, never a container name shared with Nginx.
A container without nginx-control.enable=true, without server_name or without at least one valid location is ignored. NGX Ops revalidates the entire manifest anyway.
Choose a mode¶
| Mode | Nginx reaches… | Inbound connection on the remote host | Streaming |
|---|---|---|---|
direct (default) |
directly the target of each location | One port per service | Yes |
relay |
a fixed agent port | One or two fixed ports | Yes, WebSocket and SSE included |
tunnel |
NGX Ops, which relays through an outbound tunnel | None | No |
Tunnel mode¶
If at least one vhost declares mode: tunnel, the agent opens an outbound WebSocket connection to NGX Ops (with the same token) and keeps it, with automatic reconnection. NGX Ops relays each vhost request through this tunnel; the agent routes it to the location's target by longest path prefix.
It suits hosts with no inbound port, behind a NAT for example.
Limits:
- one request at a time per connection, bodies fully buffered;
- no WebSocket or SSE through the tunnel (
relaymode handles them); - only one active tunnel connection per agent;
--insecure-skip-verifydisables TLS verification: reserved for tests.
Relay mode¶
The remote host can receive connections, but you want to avoid opening one port per service. The agent opens a fixed HTTP and/or HTTPS port and routes to the right target by host name and path. The connection is direct, with full streaming: NGX Ops is no longer in the request path.
labels:
nginx-control.enable: "true"
nginx-control.vhost.server_name: "app.example.com"
nginx-control.vhost.mode: "relay"
nginx-control.vhost.relay_scheme: "https" # http or https: relay used by this vhost
nginx-control.vhost.location01: "/"
nginx-control.vhost.location01.target: "http://127.0.0.1:8080"
Agent side:
./nginx-control-agent --dashboard-url https://dashboard.example.com \
--relay-http-listen :8080 --relay-http-advertise http://203.0.113.44:8080 \
--relay-https-listen :8443 --relay-https-advertise https://203.0.113.44:8443
One of the two relays is enough if you do not need to tell them apart. Without --relay-https-cert and --relay-https-key, the HTTPS relay uses a self-signed certificate generated in memory; the generated vhost then adds proxy_ssl_verify off;. Providing a real certificate avoids this.
listen and advertise¶
The two answer different questions:
--relay-*-listen: on which interface and port does the agent open its socket? This is almost always generic (:8080).--relay-*-advertise: at which address must Nginx reach the agent? A full address, with the scheme (http://10.20.0.5:8080), never a bare port number, which the agent refuses at startup.
| Situation | listen |
advertise |
|---|---|---|
Docker republishes the port under another number (8080:19000) |
:8080 |
http://vps.example.com:19000 |
| Several interfaces, only one reachable from Nginx | :8080 |
http://10.20.0.5:8080 |
| A load balancer is in between | :8080 |
the load balancer's public address |
| Simple deployment, one public IP | :8080 |
http://<this IP>:8080 |
Schemes at each hop¶
The three hops choose their scheme independently: client → Nginx (usually HTTPS), Nginx → agent (relay_scheme), agent → service (the target scheme). For example, an HTTP relay to a service that requires HTTPS with a self-signed certificate:
labels:
nginx-control.vhost.mode: "relay"
nginx-control.vhost.relay_scheme: "http"
nginx-control.vhost.location01.target: "https://127.0.0.1:9443"
By default, the agent verifies the certificate of an https:// service. For a self-signed certificate, enable --relay-backend-insecure-skip-verify (variable RELAY_BACKEND_INSECURE_SKIP_VERIFY=true). This setting only concerns the last hop, agent to service.
Location snippets in relay and tunnel¶
Since path routing is done on the agent side, the generated Nginx vhost only has a location /. A location that carries at least one snippet (nginx-control.vhost.locationNN.snippetMM) additionally gets its own location <path> block, with the same proxy_pass and the same headers, followed by the include snippets/.... Snippets of a / location are added in location /. Locations without a snippet generate no block.
Several NGX Ops (DMZ and LAN)¶
A single agent can publish to several independent NGX Ops, for example a front end in a DMZ and an internal dashboard. Each NGX Ops approves the agent separately and gives it its own token.
--targets-file (or TARGETS_FILE) replaces --dashboard-url, --state-file and --token with a JSON file:
[
{ "name": "dmz", "dashboardUrl": "https://dmz.example.com", "stateFile": "/data/dmz-state.json", "tokenFile": "/data/dmz-token" },
{ "name": "lan", "dashboardUrl": "https://lan.internal:3000", "stateFile": "/data/lan-state.json", "tokenFile": "/data/lan-token" }
]
Providing both forms at the same time is a startup error. By default, a container is published to all targets; to restrict it:
The relay mode relays and their advertised address remain shared between all targets. If DMZ and LAN do not reach the agent at the same address, run two agent processes.
Agent options¶
Each option exists as an environment variable (useful in a container); the command-line option takes precedence.
| Option | Role | Default |
|---|---|---|
--dashboard-url |
NGX Ops URL (except with --targets-file) |
— |
--targets-file |
Several targets | empty |
--hostname |
Name proposed at enrollment | system host name |
--state-file |
Local file (identifier and token) | ./nginx-control-agent-state.json |
--token / --token-file |
Direct token, or file re-read on each cycle | — |
--docker-socket |
Local Docker socket | /var/run/docker.sock |
--poll-interval |
Interval between two sends | 30s |
--tunnel |
Enables the tunnel client if needed | true |
--relay-http-listen / --relay-http-advertise |
HTTP relay | disabled |
--relay-https-listen / --relay-https-advertise |
HTTPS relay | disabled |
--relay-https-cert / --relay-https-key |
HTTPS relay certificate | self-signed |
--relay-backend-insecure-skip-verify |
Do not verify an HTTPS service's certificate | false |
Token: file or variable¶
TOKEN_FILE(default choice): the token does not go through the environment and its rotation requires no restart.TOKEN: convenient with a secrets vault that injects variables, but visible to anything that reads the container environment; a change requires recreating the container. If both are set,TOKENwins.
Host metrics¶
On Linux, the agent attaches to each send the host's CPU and memory usage, uptime and network throughput, shown on the Remote hosts page. On another system, this information is simply omitted.