Skip to content

Commit c96d0d3

Browse files
JTorreGJTorreG
authored
docs: add agent content to the repo (#178)
* docs: add agent content to the repo * docs: fix images
1 parent f79270b commit c96d0d3

26 files changed

+2893
-0
lines changed

‎config/_default/config.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ enableGitInfo = true
1616
ngf = '/nginx-gateway-fabric/:sections[1:]/:filename'
1717
nim = '/nginx-instance-manager/:sections[1:]/:filename'
1818
nms = '/nginx-management-suite/:sections[1:]/:filename'
19+
agent = '/nginx-agent/:sections[1:]/:filename'
1920

2021
[caches]
2122
[caches.modules]

‎content/agent/_index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: "NGINX Agent"
3+
description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance."
4+
linkTitle: "NGINX Agent"
5+
menu: docs
6+
url: /nginx-agent/
7+
cascade:
8+
logo: "NGINX-product-icon.png"
9+
---

‎content/agent/changelog.md

Lines changed: 282 additions & 0 deletions
Large diffs are not rendered by default.

‎content/agent/configuration/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Configuration"
3+
description: "Learn how to configure NGINX Agent."
4+
linkTitle: "Configuration"
5+
weight: "400"
6+
menu: docs
7+
url: /nginx-agent/configuration/
8+
---

‎content/agent/configuration/configuration-overview.md

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
---
2+
title: "Basic configuration"
3+
draft: false
4+
weight: 100
5+
toc: true
6+
tags: [ "docs" ]
7+
docs: "DOCS-1229"
8+
categories: ["configuration"]
9+
doctypes: ["task"]
10+
---
11+
12+
The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables.
13+
14+
{{<note>}}
15+
16+
- NGINX Agent interprets configuration values set by configuration files, CLI flags, and environment variables in the following priorities:
17+
18+
1. CLI flags overwrite configuration files and environment variable values.
19+
2. Environment variables overwrite configuration file values.
20+
3. Config files are the lowest priority and config settings are superseded if either of the other options is used.
21+
22+
- You must open any required firewall ports or add SELinux/AppArmor rules for the ports and IPs you want to use.
23+
24+
{{</note>}}
25+
26+
## Configure with Config Files
27+
28+
The default locations of configuration files for NGINX Agent are `/etc/nginx-agent/nginx-agent.conf` and `/var/lib/nginx-agent/agent-dynamic.conf`. The `agent-dynamic.conf` file default location is different for FreeBSD which is located `/var/db/nginx-agent/agent-dynamic.conf`. These files have comments at the top indicating their purpose.
29+
30+
Examples of the configuration files are provided below:
31+
32+
<details open>
33+
<summary>example nginx-agent.conf</summary>
34+
35+
{{<note>}}
36+
In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane.
37+
{{</note>}}
38+
39+
```nginx {hl_lines=[13]}
40+
#
41+
# /etc/nginx-agent/nginx-agent.conf
42+
#
43+
# Configuration file for NGINX Agent.
44+
#
45+
# This file tracks agent configuration values that are meant to be statically set. There
46+
# are additional NGINX Agent configuration values that are set via the API and agent install script
47+
# which can be found in /etc/nginx-agent/agent-dynamic.conf.
48+
49+
# specify the server grpc port to connect to
50+
server:
51+
# host of the control plane
52+
host: <FQDN>
53+
grpcPort: 443
54+
backoff: # note: default values are prepopulated
55+
initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
56+
randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
57+
multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
58+
max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
59+
max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
60+
# tls options
61+
tls:
62+
# enable tls in the nginx-agent setup for grpcs
63+
# default to enable to connect with secure connection but without client cert for mtls
64+
enable: true
65+
# controls whether the server certificate chain and host name are verified.
66+
# for production use, see instructions for configuring TLS
67+
skip_verify: false
68+
log:
69+
# set log level (panic, fatal, error, info, debug, trace; default "info")
70+
level: info
71+
# set log path. if empty, don't log to file.
72+
path: /var/log/nginx-agent/
73+
nginx:
74+
# path of NGINX logs to exclude
75+
exclude_logs: ""
76+
# Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check)
77+
treat_warnings_as_errors: false # Default is false
78+
# data plane status message / 'heartbeat'
79+
dataplane:
80+
status:
81+
# poll interval for dataplane status - the frequency the NGINX Agent will query the dataplane for changes
82+
poll_interval: 30s
83+
# report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed
84+
report_interval: 24h
85+
metrics:
86+
# specify the size of a buffer to build before sending metrics
87+
bulk_size: 20
88+
# specify metrics poll interval
89+
report_interval: 1m
90+
collection_interval: 15s
91+
mode: aggregated
92+
backoff: # note: default values are prepopulated
93+
initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
94+
randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10
95+
multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5
96+
max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
97+
max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour
98+
99+
# OSS NGINX default config path
100+
# path to aux file dirs can also be added
101+
config_dirs: "/etc/nginx:/usr/local/etc/nginx"
102+
103+
# Internal queue size
104+
queue_size: 100
105+
106+
extensions:
107+
- nginx-app-protect
108+
109+
# Enable reporting NGINX App Protect details to the control plane.
110+
nginx_app_protect:
111+
# Report interval for NGINX App Protect details - the frequency NGINX Agent checks NGINX App Protect for changes.
112+
report_interval: 15s
113+
# Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false).
114+
precompiled_publication: true
115+
```
116+
117+
</details>
118+
119+
120+
<details open>
121+
<summary>example dynamic-agent.conf</summary>
122+
123+
{{<note>}}
124+
Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf`
125+
126+
Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf`
127+
{{</note>}}
128+
129+
```yaml
130+
# Dynamic configuration file for NGINX Agent.
131+
#
132+
# The purpose of this file is to track agent configuration
133+
# values that can be dynamically changed via the API and the agent install script.
134+
# You may edit this file, but API calls that modify the tags on this system will
135+
# overwrite the tag values in this file.
136+
#
137+
# The agent configuration values that API calls can modify are as follows:
138+
# tags:
139+
# - dev
140+
# - qa
141+
#
142+
# The agent configuration value that the agent install script can modify are as follows:
143+
# instance_group: my-instance-group
144+
145+
instance_group: my-instance-group
146+
tags:
147+
- dev
148+
- qa
149+
```
150+
151+
</details>
152+
153+
## CLI Flags & Environment Variables
154+
155+
This section details the CLI flags and corresponding environment variables used to configure the NGINX Agent.
156+
157+
### Usage
158+
159+
#### CLI Flags
160+
161+
```sh
162+
nginx-agent [flags]
163+
```
164+
165+
#### Environment Variables
166+
167+
```sh
168+
export ENV_VARIABLE_NAME="value"
169+
nginx-agent
170+
```
171+
172+
### CLI Flags and Environment Variables
173+
174+
{{< warning >}}
175+
176+
Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`.
177+
178+
If you are upgrading from an older version, update your configuration accordingly.
179+
180+
{{< /warning >}}
181+
182+
{{<bootstrap-table "table table-responsive table-bordered">}}
183+
| CLI flag | Environment variable | Description |
184+
|---------------------------------------------|--------------------------------------|-----------------------------------------------------------------------------|
185+
| `--api-cert` | `NGINX_AGENT_API_CERT` | Specifies the certificate used by the Agent API. |
186+
| `--api-host` | `NGINX_AGENT_API_HOST` | Sets the host used by the Agent API. Default: *127.0.0.1* |
187+
| `--api-key` | `NGINX_AGENT_API_KEY` | Specifies the key used by the Agent API. |
188+
| `--api-port` | `NGINX_AGENT_API_PORT` | Sets the port for exposing nginx-agent to HTTP traffic. |
189+
| `--config-dirs` | `NGINX_AGENT_CONFIG_DIRS` | Defines directories NGINX Agent can read/write. Default: *"/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms"* |
190+
| `--dataplane-report-interval` | `NGINX_AGENT_DATAPLANE_REPORT_INTERVAL` | Sets the interval for dataplane reporting. Default: *24h0m0s* |
191+
| `--dataplane-status-poll-interval` | `NGINX_AGENT_DATAPLANE_STATUS_POLL_INTERVAL` | Sets the interval for polling dataplane status. Default: *30s* |
192+
| `--display-name` | `NGINX_AGENT_DISPLAY_NAME` | Sets the instance's display name. |
193+
| `--dynamic-config-path` | `NGINX_AGENT_DYNAMIC_CONFIG_PATH` | Specifies the path of the Agent dynamic config file. Default: *"/var/lib/nginx-agent/agent-dynamic.conf"* |
194+
| `--features` | `NGINX_AGENT_FEATURES` | Specifies a comma-separated list of features enabled for the agent. Default: *[registration, nginx-config-async, nginx-ssl-config, nginx-counting, metrics, dataplane-status, process-watcher, file-watcher, activity-events, agent-api]* |
195+
| `--ignore-directives` | | Specifies a comma-separated list of directives to ignore for sensitive info.|
196+
| `--instance-group` | `NGINX_AGENT_INSTANCE_GROUP` | Sets the instance's group value. |
197+
| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (e.g., panic, fatal, error, info, debug, trace). Default: *info* |
198+
| `--log-path` | `NGINX_AGENT_LOG_PATH` | Specifies the path to output log messages. |
199+
| `--metrics-bulk-size` | `NGINX_AGENT_METRICS_BULK_SIZE` | Specifies the number of metrics reports collected before sending data. Default: *20* |
200+
| `--metrics-collection-interval` | `NGINX_AGENT_METRICS_COLLECTION_INTERVAL` | Sets the interval for metrics collection. Default: *15s* |
201+
| `--metrics-mode` | `NGINX_AGENT_METRICS_MODE` | Sets the metrics collection mode: streaming or aggregation. Default: *aggregated* |
202+
| `--metrics-report-interval` | `NGINX_AGENT_METRICS_REPORT_INTERVAL` | Sets the interval for reporting collected metrics. Default: *1m0s* |
203+
| `--nginx-config-reload-monitoring-period` | | Sets the duration to monitor error logs after an NGINX reload. Default: *10s* |
204+
| `--nginx-exclude-logs` | `NGINX_AGENT_NGINX_EXCLUDE_LOGS` | Specifies paths of NGINX access logs to exclude from metrics collection. |
205+
| `--nginx-socket` | `NGINX_AGENT_NGINX_SOCKET` | Specifies the location of the NGINX Plus counting Unix socket. Default: *unix:/var/run/nginx-agent/nginx.sock* |
206+
| `--nginx-treat-warnings-as-errors` | `NGINX_AGENT_NGINX_TREAT_WARNINGS_AS_ERRORS` | Treats warnings as failures on configuration application. |
207+
| `--queue-size` | `NGINX_AGENT_QUEUE_SIZE` | Specifies the size of the NGINX Agent internal queue. |
208+
| `--server-command` | | Specifies the name of the command server sent in the TLS configuration. |
209+
| `--server-grpcport` | `NGINX_AGENT_SERVER_GRPCPORT` | Sets the desired GRPC port for NGINX Agent traffic. |
210+
| `--server-host` | `NGINX_AGENT_SERVER_HOST` | Specifies the IP address of the server host. |
211+
| `--server-metrics` | | Specifies the name of the metrics server sent in the TLS configuration. |
212+
| `--server-token` | `NGINX_AGENT_SERVER_TOKEN` | Sets the authentication token for accessing the commander and metrics services. Default: *e202f883-54c6-4702-be15-3ba6e507879a* |
213+
| `--tags` | `NGINX_AGENT_TAGS` | Specifies a comma-separated list of tags for the instance or machine. |
214+
| `--tls-ca` | `NGINX_AGENT_TLS_CA` | Specifies the path to the CA certificate file for TLS. |
215+
| `--tls-cert` | `NGINX_AGENT_TLS_CERT` | Specifies the path to the certificate file for TLS. |
216+
| `--tls-enable` | `NGINX_AGENT_TLS_ENABLE` | Enables TLS for secure communications. |
217+
| `--tls-key` | `NGINX_AGENT_TLS_KEY` | Specifies the path to the certificate key file for TLS. |
218+
| `--tls-skip-verify` | `NGINX_AGENT_TLS_SKIP_VERIFY` | Insecurely skips verification for gRPC TLS credentials. |
219+
{{</bootstrap-table>}}
220+
221+
<br>
222+
223+
{{<note>}}
224+
Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories NGINX Agent can read from or write to. This setting also defines the location to which you can upload config files when using a control plane.
225+
226+
NGINX Agent cannot write to directories outside the specified location when updating a config and cannot upload files to directories outside of the configured location.
227+
228+
NGINX Agent follows NGINX configuration directives to file paths outside the designated directories and reads certificates' metadata. NGINX Agent uses the following directives:
229+
230+
- [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate)
231+
232+
{{</note>}}
233+
234+
{{<note>}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location.
235+
236+
Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf`
237+
238+
Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf`
239+
240+
{{</note>}}
241+
242+
## Log Rotation
243+
244+
By default, NGINX Agent rotates logs daily using logrotate with the following configuration:
245+
246+
<details open>
247+
<summary>NGINX Agent Logrotate Configuration</summary>
248+
249+
``` yaml
250+
/var/log/nginx-agent/*.log
251+
{
252+
# log files are rotated every day
253+
daily
254+
# log files are rotated if they grow bigger than 5M
255+
size 5M
256+
# truncate the original log file after creating a copy
257+
copytruncate
258+
# remove rotated logs older than 10 days
259+
maxage 10
260+
# log files are rotated 10 times before being removed
261+
rotate 10
262+
# old log files are compressed
263+
compress
264+
# if the log file is missing it will go on to the next one without issuing an error message
265+
missingok
266+
# do not rotate the log if it is empty
267+
notifempty
268+
}
269+
```
270+
</details>
271+
272+
If you need to change the default configuration, update the file at `/etc/logrotate.d/nginx-agent`.
273+
274+
For more details on logrotate configuration, see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate).

0 commit comments

Comments
 (0)