nginx · Jcahilltorre · Feb 1, 2024 · Jan 31, 2024
@@ -175,7 +175,7 @@ Flags:
       --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-config-reload-monitoring-period duration   The duration 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.

@@ -0,0 +1,87 @@
+---
+title: "Add NGINX Users to nginx-agent Group"
+draft: false
+weight: 300
+toc: true
+tags: [ "docs" ]
+docs: "DOCS-933"
+categories: ["configuration"]
+doctypes: ["task"]
+---
+
+## Overview
+
+During installation, NGINX Agent detects the NGINX user (typically `nginx`) for the master and worker processes and adds this user to a group called `nginx-agent`.
+
+If you change the NGINX username after installing the NGINX Agent, you'll need to add the new username to the `nginx-agent` group so that the NGINX socket has the proper permissions.
+
+A failure to update the `nginx-agent` group when the NGINX username changes may result in non-compliance errors for NGINX Plus.
+
+
+## NGINX Socket
+
+NGINX Agent creates a socket in the default location `/var/run/nginx-agent/nginx.sock`. You can customize this location by editing the `nginx-agent.conf` file and setting the path similar to the following example:
+
+```nginx configuration
+nginx:
+ ...
+ socket: "unix:/var/run/nginx-agent/nginx.sock"
+```
+
+The socket server starts when the NGINX socket configuration is enabled; the socket configuration is enabled by default.
+
+
+## Add NGINX Users to nginx-agent Group
+
+To manually add NGINX users to the `nginx-agent` group, take the following steps:
+
+1. Verify the `nginx-agent` group exists:
+
+    ```bash
+    sudo getent group | grep nginx-agent
+    ```
+
+    The output looks similar to the following example:
+
+    ```bash
+    nginx-agent:x:1001:root,nginx
+    ```
+
+    If the group doesn't exist, create it by running the following command:
+
+    ```bash
+    sudo groupadd nginx-agent
+    ```
+
+2. Verify the ownership of `/var/run/nginx-agent` directory:
+
+    ```bash
+    ls -l /var/run/nginx-agent
+    ```
+
+    The output looks similar to the following:
+
+    ```bash
+    total 0
+    srwxrwxr-x 1 root nginx-agent 0 Jun 13 10:51 nginx.sockvv
+    ```
+
+    If the group ownership is not `nginx-agent`, change the ownership by running the following command:
+
+    ```bash
+    sudo chown :nginx-agent /var/run/nginx-agent
+    ```
+
+3. To add NGINX user(s) to the `nginx-agent` group, run the following command:
+
+    ```bash
+    sudo usermod -a -G nginx-agent <username>
+    ```
+
+    For example to add the `nginx` user, take the following step:
+
+    ```bash
+    sudo usermod -a -G nginx-agent nginx
+    ```
+
+    Repeat for all NGINX users.
@@ -9,7 +9,7 @@ docs: "DOCS-802"
 
 ## Overview
 
-Follow the steps in this guide to encrypt communication between the NGINX Agent and Instance Manager with TLS.
+Follow the steps in this guide to encrypt communication between NGINX Agent and Instance Manager with TLS.
 
 ## Before You Begin
 
@@ -21,7 +21,7 @@ See the examples below for how to set these values using a configuration file, C
 
 ### Enabling mTLS via Config Values
 
-You can edit the `/etc/nginx-agent/nginx-agent.conf` file to enable mTLS for the NGINX Agent. Make the following changes:
+You can edit the `/etc/nginx-agent/nginx-agent.conf` file to enable mTLS for NGINX Agent. Make the following changes:
 
 ```yaml
 server:
@@ -47,7 +47,7 @@ nginx-agent --tls-cert "path-to-cert" --tls-key "path-to-key" --tls-ca "path-to-
 
 ### Enabling mTLS with Environment Variables
 
-To enable mTLS for the NGINX Agent using environment variables, run the following commands:
+To enable mTLS for NGINX Agent using environment variables, run the following commands:
 
 ```bash
 NMS_TLS_CA="my-env-ca"

@@ -1,5 +1,5 @@
 ---
-title: "Docker Images"
+title: "Build Container Images"
 draft: false
 weight: 100
 toc: true
@@ -10,13 +10,17 @@ doctypes: ["task"]
 
 ## Overview
 
-Learn how to build and run NGINX Agent docker images
+Learn how to build NGINX Agent container images with Docker.
 
 ## Prerequisites
 1. Docker must be [installed and running](https://docs.docker.com/engine/install/)
 1. (Optional) If you plan to use NGINX Plus, you will need the nginx-repo.crt and nginx-repo.key files. You can download them from [MyF5](https://my.f5.com).
 
-## Building NGINX Agent image with NGINX Open Source
+## Building NGINX Agent image with Docker
+
+{{<tabs name="build-image">}}
+
+{{%tab name="NGINX Open Source"%}}
 
 To build an image that contains the latest NGINX Agent and the latest mainline version of NGINX run the following command:
 
@@ -30,8 +34,10 @@ To build an image that contains the latest NGINX Agent and the latest stable ver
 $ cd scripts/docker/official/nginx-oss-with-nginx-agent/alpine/
 $ docker build -t nginx-agent . --no-cache -f ./Dockerfile.stable
 ```
-
-## Building NGINX Agent image with NGINX Plus
+
+{{% /tab %}}
+
+{{%tab name="NGINX Plus"%}}
 
 1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5) and download your `nginx-repo.crt` and `nginx-repo.key` files. These files are also provided with the NGINX Plus trial package.
 
@@ -46,10 +52,15 @@ $ docker build -t nginx-agent . \
   --secret id=nginx-crt,src=nginx-repo.crt \
   --secret id=nginx-key,src=nginx-repo.key
 ```
+{{% /tab %}}
+{{% /tabs %}}
+
+<hr>
+
 
 ## Running NGINX Agent container
 
-Here is an example of how to run a NGINX Agent container:
+Here is an example of how to run a NGINX Agent container with Docker:
 
 ```console
 $ docker run --name nginx-agent -d nginx-agent

@@ -1,5 +1,5 @@
 ---
-title: Docker Support
+title: Container Support and Troubleshooting
 categories:
 - installation
 draft: false
@@ -12,13 +12,17 @@ docs: "DOCS-909"
 
 ## Overview
 
-Learn about the limitations of NGINX Agent when running in a Docker environment.
+The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< relref "installation-upgrade/container-environments/docker-images.md" >}}). Images are created with an NGINX Open Source or NGINX Plus instance and are available for various operating systems.
+
+See the [Technical Specifications]({{< relref "/technical-specifications.md#container-support" >}}) for a list of supported operationg systems.
+
+NGINX Agent running in a container has some limitations that need to be considered, and are listed below.
 
 ## Supported cgroups
 
-To collect metrics about the Docker container that the NGINX Agent is running in, the NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage.
+To collect metrics about the Docker container that the NGINX Agent is running in, NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage.
 
-The NGINX Agent supports both versions of cgroups.
+NGINX Agent supports both versions of cgroups.
 
 - https://www.kernel.org/doc/Documentation/cgroup-v1/ 
 - https://www.kernel.org/doc/Documentation/cgroup-v2.txt 
@@ -27,7 +31,7 @@ The NGINX Agent supports both versions of cgroups.
 
 ### Unsupported Metrics
 
-The following system metrics are not supported when running the NGINX Agent in a Docker container. The NGINX Agent returns no values for these metrics:
+The following system metrics are not supported when running NGINX Agent in a Docker container. NGINX Agent returns no values for these metrics:
 
 - system.cpu.idle
 - system.cpu.iowait

@@ -12,56 +12,21 @@ doctypes: ["task"]
 
 ## Supported Distributions
 
-NGINX Agent can run in most environments. The below list are the supported distributions.
-
-AlmaLinux
-- 8 (x86_64, aarch64)
-- 9 (x86_64, aarch64)
-
-Alpine Linux
-- 3.16 (x86_64, aarch64)
-- 3.17 (x86_64, aarch64)
-- 3.18 (x86_64, aarch64)
-- 3.19 (x86_64, aarch64)
-
-Amazon Linux
-- 2023 (x86_64, aarch64)
-
-Amazon Linux 2
-- LTS (x86_64, aarch64)
-
-CentOS
-- 7.4+ (x86_64, aarch64)
-
-Debian
-- 11 (x86_64, aarch64)
-- 12 (x86_64, aarch64)
-
-FreeBSD
-- 13 (amd64)
-- 14 (amd64)
-
-Oracle Linux
-- 7.4+ (x86_64)
-- 8.1+ (x86_64)
-- 9 (x86_64)
-
-Red Hat Enterprise Linux (RHEL)
-- 7.4+ (x86_64, aarch64)
-- 8.1+ (x86_64, aarch64)
-- 9.0+ (x86_64, aarch64)
-
-Rocky Linux
-- 8 (x86_64, aarch64)
-- 9 (x86_64, aarch64)
-
-SUSE Linux Enterprise Server (SLES)
-- 12 SP5 (x86_64)
-- 15 SP2 (x86_64)
-
-Ubuntu
-- 20.04 LTS (x86_64, aarch64)
-- 22.04 LTS (x86_64, aarch64)
+NGINX Agent can run in most environments. We support the following distributions:
+
+{{< bootstrap-table "table table-striped table-bordered" >}}
+| | AlmaLinux | Alpine Linux | Amazon Linux | Amazon Linux 2 | CentOS | Debian | 
+|-|-----------|--------------|--------------|----------------|--------|--------|
+|**Version**|8 <br><br>9 |  3.16<br><br>3.17<br><br> 3.18<br><br> 3.19|  2023|  LTS|  7.4+|  11<br><br> 12|
+|**Architecture**| x86_84<br><br>aarch64| x86_64<br><br>aarch64 | x86_64<br><br>aarch64 | x86_64<br><br>aarch64 | x86_64<br><br>aarch64 | x86_64<br><br>aarch64 |
+{{< /bootstrap-table >}}
+
+{{< bootstrap-table "table table-striped table-bordered" >}}
+| |FreeBSD | Oracle Linux | Red Hat <br>Enterprise Linux (RHEL) | Rocky Linux | SUSE Linux <br>Enterprise Server (SLES) | Ubuntu |
+|-|--------|--------------|---------------------------------|-------------|-------------------------------------|--------|
+|**Version**|13<br><br>14|7.4+<br><br>8.1+<br><br>9|7.4+<br><br>8.1+<br><br>9.0+|8<br><br>9|12 SP5<br><br>15 SP2|20.04 LTS<br><br>22.04 LTS|
+|**Architecture**|amd64|x86_64|x86_64<br><br>aarch64|x86_64<br><br>aarch64|x86_64|x86_64<br><br>aarch64|
+{{< /bootstrap-table >}}
 
 ## Supported Deployment Environments 
 
@@ -80,7 +45,12 @@ NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plu
 ## Sizing Recommendations
 
 Minimum system sizing recommendations for NGINX Agent:
-
+{{< bootstrap-table "table table-striped table-bordered" >}}
 | CPU        | Memory   | Network   | Storage |
 |------------|----------|-----------|---------|
 | 1 CPU core | 1 GB RAM | 1 GbE NIC | 20 GB   |
+{{< /bootstrap-table >}}
+
+## Logging
+
+NGINX Agent utilizes log files and formats to collect metrics. Increasing the log formats and instance counts will result in increased log file sizes. To prevent system storage issues due to a growing log directory, it is recommended to add a separate partition for `/var/log/nginx-agent` and enable [log rotation](http://nginx.org/en/docs/control.html#logs).
@@ -2,4 +2,4 @@ module github.com/nginx/agent/site
 
 go 1.18
 
-require github.com/nginxinc/nginx-hugo-theme v0.35.0 // indirect
+require github.com/nginxinc/nginx-hugo-theme v0.40.8 // indirect
@@ -8,3 +8,5 @@ github.com/nginxinc/nginx-hugo-theme v0.34.0 h1:G7LPVq7w1ls6IS4+OkTwjhFb67rLCzPd
 github.com/nginxinc/nginx-hugo-theme v0.34.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
 github.com/nginxinc/nginx-hugo-theme v0.35.0 h1:7XB2GMy6qeJgKEJy9wOS3SYKYpfvLW3/H+UHRPLM4FU=
 github.com/nginxinc/nginx-hugo-theme v0.35.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
+github.com/nginxinc/nginx-hugo-theme v0.40.8 h1:VtoSAtf9k67tI2jzbLRo0oFBAMHZBUPRh/xV4MYullI=
+github.com/nginxinc/nginx-hugo-theme v0.40.8/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=