diff --git a/hugo/content/changelog.md b/hugo/content/changelog.md index 6430ebd4f..1f29daa6d 100644 --- a/hugo/content/changelog.md +++ b/hugo/content/changelog.md @@ -2,7 +2,7 @@ title: "Changelog" draft: false description: "NGINX Agent updates changelog." -weight: 900 +weight: 1100 toc: true tags: [ "docs" ] docs: "DOCS-1093" diff --git a/hugo/content/community.md b/hugo/content/community.md index 773e06419..460385fcb 100644 --- a/hugo/content/community.md +++ b/hugo/content/community.md @@ -2,7 +2,7 @@ title: "Contributing and Support" draft: false description: "Learn about the NGINX Agent community." -weight: 800 +weight: 900 toc: true tags: [ "docs" ] docs: "DOCS-1087" diff --git a/hugo/content/configuration-overview.md b/hugo/content/configuration-overview.md new file mode 100644 index 000000000..ff99e3a80 --- /dev/null +++ b/hugo/content/configuration-overview.md @@ -0,0 +1,238 @@ +--- +title: "Configuration Overview" +draft: false +description: "Learn the overview of configuration" +weight: 500 +toc: true +tags: [ "docs" ] +docs: "DOCS-1229" +categories: ["configuration"] +doctypes: ["task"] +--- + +## Overview + +The following sections explain how to configure the NGINX Agent using configuration files, CLI flags, and environment variables. + +{{}} + +- The NGINX Agent interprets configuration values set by configuration files, CLI flags, and environment variables in the following priorities: + + 1. CLI flags overwrite configuration files and environment variable values. + 2. Environment variables overwrite configuration file values. + 3. Config files are the lowest priority and config settings are superseded if either of the other options is used. + +- You must open any required firewall ports or add SELinux/AppArmor rules for the ports and IPs you want to use. + +{{}} + +### Configure with Config Files + +The configuration files for the NGINX Agent are `/etc/nginx-agent/nginx-agent.conf` and `/var/lib/nginx-agent/agent-dynamic.conf`. The `agent-dynamic.conf` file 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. + +Examples of the configuration files are provided below: + +
+ example nginx-agent.conf + +{{}} +In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control/management plane. +{{}} + +```nginx {hl_lines=[13]} +# +# /etc/nginx-agent/nginx-agent.conf +# +# Configuration file for NGINX Agent. +# +# This file tracks agent configuration values that are meant to be statically set. There +# are additional NGINX Agent configuration values that are set via the API and agent install script +# which can be found in /etc/nginx-agent/agent-dynamic.conf. + +# specify the server grpc port to connect to +server: + # host of the control plane + host: + grpcPort: 443 +# tls options +tls: + # enable tls in the nginx-agent setup for grpcs + # default to enable to connect with secure connection but without client cert for mtls + enable: true + # controls whether the server certificate chain and host name are verified. + # for production use, see instructions for configuring TLS + skip_verify: false +log: + # set log level (panic, fatal, error, info, debug, trace; default "info") + level: info + # set log path. if empty, don't log to file. + path: /var/log/nginx-agent/ +nginx: + # path of NGINX logs to exclude + exclude_logs: "" + # Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check) + treat_warnings_as_errors: false # Default is false +# data plane status message / 'heartbeat' +dataplane: + status: + # poll interval for dataplane status - the frequency the agent will query the dataplane for changes + poll_interval: 30s + # report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed + report_interval: 24h +metrics: + # specify the size of a buffer to build before sending metrics + bulk_size: 20 + # specify metrics poll interval + report_interval: 1m + collection_interval: 15s + mode: aggregated + +# OSS NGINX default config path +# path to aux file dirs can also be added +config_dirs: "/etc/nginx:/usr/local/etc/nginx" + +extensions: + - nginx-app-protect + +# Enable reporting NGINX App Protect details to the control plane. +nginx_app_protect: + # Report interval for NGINX App Protect details - the frequency the NGINX Agent checks NGINX App Protect for changes. + report_interval: 15s + # Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false). + precompiled_publication: true +``` + +
+ + +
+ example dynamic-agent.conf + +```yaml +# +# /var/lib/nginx-agent/agent-dynamic.conf +# On FreeBSD /var/db/nginx-agent/agent-dynamic.conf +# +# Dynamic configuration file for NGINX Agent. +# +# The purpose of this file is to track agent configuration +# values that can be dynamically changed via the API and the agent install script. +# You may edit this file, but API calls that modify the tags on this system will +# overwrite the tag values in this file. +# +# The agent configuration values that API calls can modify are as follows: +# - tags +# +# The agent configuration value that the agent install script can modify are as follows: +# - instance_group + +instance_group: devenv-group +tags: + - devenv + - test +``` + +
+ + +### NGINX Agent CLI Flags & Usage {#nginx-agent-cli-flags-usage} + +This section displays the configurable options for the NGINX Agent that can be set with CLI flags. See the CLI flags and their uses in the figure below: + +
+ NGINX Agent CLI flags & usage + +```text +Usage: + nginx-agent [flags] + nginx-agent [command] + +Available Commands: + completion Generate completion script. + help Help about any command + +Flags: + --api-cert string The cert used by the Agent API. + --api-host string The host used by the Agent API. (default "127.0.0.1") + --api-key string The key used by the Agent API. + --api-port int The desired port to use for nginx-agent to expose for HTTP traffic. + --config-dirs string Defines the paths that you want to grant nginx-agent read/write access to. This key is formatted as a string and follows Unix PATH format. (default "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms") + --dataplane-report-interval duration The amount of time the agent will report on the dataplane. After this period of time it will send a snapshot of the dataplane information. (default 24h0m0s) + --dataplane-status-poll-interval duration The frequency the agent will check the dataplane for changes. Used as a "heartbeat" to keep the gRPC connections alive. (default 30s) + --display-name string The instance's 'name' value. + --features strings A comma-separated list of features enabled for the agent. (default [registration,nginx-config-async,nginx-ssl-config,nginx-counting,metrics,metrics-throttle,dataplane-status,process-watcher,file-watcher,activity-events,agent-api]) + -h, --help help for nginx-agent + --instance-group string The instance's 'group' value. + --log-level string The desired verbosity level for logging messages from nginx-agent. Available options, in order of severity from highest to lowest, are: panic, fatal, error, info, debug, and trace. (default "info") + --log-path string The path to output log messages to. If the default path doesn't exist, log messages are output to stdout/stderr. (default "/var/log/nginx-agent") + --metrics-bulk-size int The amount of metrics reports collected before sending the data back to the server. (default 20) + --metrics-collection-interval duration Sets the interval, in seconds, at which metrics are collected. (default 15s) + --metrics-mode string Sets the desired metrics collection mode: streaming or aggregation. (default "aggregated") + --metrics-report-interval duration The polling period specified for a single set of metrics being collected. (default 1m0s) + --nginx-config-reload-monitoring-period duration The duration the NGINX Agent will monitor error logs after a NGINX reload (default 10s) + --nginx-exclude-logs string One or more NGINX access log paths that you want to exclude from metrics collection. This key is formatted as a string and multiple values should be provided as a comma-separated list. + --nginx-socket string The NGINX Plus counting unix socket location. (default "unix:/var/run/nginx-agent/nginx.sock") + --nginx-treat-warnings-as-errors On nginx -t, treat warnings as failures on configuration application. + --server-command string The name of the command server sent in the tls configuration. + --server-grpcport int The desired GRPC port to use for nginx-agent traffic. + --server-host string The IP address of the server host. IPv4 addresses and hostnames are supported. + --server-metrics string The name of the metrics server sent in the tls configuration. + --server-token string An authentication token that grants nginx-agent access to the commander and metrics services. Auto-generated by default. (default "750d0148-c4b2-499a-9011-ca5a8c752d52") + --tags strings A comma-separated list of tags to add to the current instance or machine, to be used for inventory purposes. + --tls-ca string The path to the CA certificate file to use for TLS. + --tls-cert string The path to the certificate file to use for TLS. + --tls-enable Enables TLS for secure communications. + --tls-key string The path to the certificate key file to use for TLS. + --tls-skip-verify Only intended for demonstration, sets InsecureSkipVerify for gRPC TLS credentials + -v, --version version for nginx-agent + +Use "nginx-agent [command] --help" for more information about a command. +``` + +
+ +#### NGINX Agent Config Dirs Option + +Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories the 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/management plane. The 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. +The NGINX Agent follows NGINX configuration directives to file paths outside the designated directories and reads certificates' metadata. The NGINX Agent uses the following directives: + +- [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) + +### NGINX Agent Environment Variables + +This section displays the configurable options for the NGINX Agent that can be set with environment variables. A list of the configurable environment variables can be seen below: + +
+ NGINX Agent Environment Variables + +```text +- NMS_INSTANCE_GROUP +- NMS_DISPLAY_NAME +- NMS_FEATURES +- NMS_LOG_LEVEL +- NMS_LOG_PATH +- NMS_PATH +- NMS_METRICS_COLLECTION_INTERVAL +- NMS_METRICS_MODE +- NMS_METRICS_BULK_SIZE +- NMS_METRICS_REPORT_INTERVAL +- NMS_NGINX_EXCLUDE_LOGS +- NMS_NGINX_SOCKET +- NMS_NGINX_TREAT_WARNINGS_AS_ERRORS +- NMS_SERVER_GRPCPORT +- NMS_SERVER_HOST +- NMS_SERVER_TOKEN +- NMS_SERVER_COMMAND +- NMS_SERVER_METRICS +- NMS_TAGS +- NMS_TLS_CA +- NMS_TLS_CERT +- NMS_TLS_ENABLE +- NMS_TLS_KEY +- NMS_TLS_SKIP_VERIFY +- NMS_CONFIG_DIRS +- NMS_DATAPLANE_REPORT_INTERVAL +- NMS_DATAPLANE_STATUS_POLL_INTERVAL +``` + +
\ No newline at end of file diff --git a/hugo/content/dev-environment-setup.md b/hugo/content/dev-environment-setup.md index a368ac053..7fd520d13 100644 --- a/hugo/content/dev-environment-setup.md +++ b/hugo/content/dev-environment-setup.md @@ -2,7 +2,7 @@ title: "Development Environment Setup" draft: false description: "Learn how to setup a Development Environment for NGINX Agent." -weight: 700 +weight: 800 toc: true tags: [ "docs" ] docs: "DOCS-1088" diff --git a/hugo/content/getting-started.md b/hugo/content/getting-started.md index 2f141b2a3..1be99b7e8 100644 --- a/hugo/content/getting-started.md +++ b/hugo/content/getting-started.md @@ -2,7 +2,7 @@ title: "Getting Started" draft: false description: "Learn how to configure and run NGINX Agent." -weight: 600 +weight: 700 toc: true tags: [ "docs" ] docs: "DOCS-1089" diff --git a/hugo/content/technical-specifications.md b/hugo/content/technical-specifications.md index 38d3e8ff9..15a866100 100644 --- a/hugo/content/technical-specifications.md +++ b/hugo/content/technical-specifications.md @@ -2,7 +2,7 @@ title: "Technical Specifications" draft: false description: "This document describes the requirements for NGINX Agent." -weight: 800 +weight: 1000 toc: true tags: [ "docs" ] docs: "DOCS-1092" diff --git a/hugo/content/upgrading.md b/hugo/content/upgrading.md index 54ef81b78..361f4ac8f 100644 --- a/hugo/content/upgrading.md +++ b/hugo/content/upgrading.md @@ -2,7 +2,7 @@ title: "Upgrade NGINX Agent Package" draft: false description: "Learn how to upgrade NGINX Agent" -weight: 500 +weight: 600 toc: true tags: [ "docs" ] docs: "DOCS-1227"