diff --git a/content/agent/about.md b/content/agent/about.md new file mode 100644 index 000000000..022dcdd90 --- /dev/null +++ b/content/agent/about.md @@ -0,0 +1,46 @@ +--- +title: "Overview" +weight: 100 +toc: true +docs: DOCS-000 +--- +{{}} + +{{}} + +### About F5 NGINX Agent +The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX One, enabling remote management of the NGINX Instance(s). It also gathers performance metrics from NGINX and transmits them to the NGINX One Console for enhanced monitoring and control. + +### Key Features +- Enable Access to Key NGINX One Use Cases + - Seamlessly integrates with essential NGINX One functionality, simplifying access to its core use cases and enhancing operational workflows. + - [Connect to NGINX One Console]({{< relref "/agent/install-upgrade/install/#connect-an-instance-to-nginx-one-console" >}}) + +- Real-Time Observability into NGINX One Data Plane Instances + - Provides live monitoring and actionable insights into the performance, status, and health of NGINX One Data Plane instances, improving decision-making and operational efficiency. + + - [OpenTelemetry](https://opentelemetry.io/) support comes with F5 NGINX Agent, and the ability to [export the metrics data]({{< relref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications. + +--- + +## How it works + +### Configuration management + +- The F5 NGINX Agent provides an interface that enables users to deploy configuration changes to NGINX from a centralized management plane. +- Additionally, the F5 NGINX Agent verifies that the configuration changes are successfully applied to NGINX. + +### Metrics Collection + +- The F5 NGINX Agent comes pre-packaged with an embedded OpenTelemetry Collector . +- This embedded collector gathers vital performance and health metrics for both NGINX and the underlying instance it operates on. +- For example, it tracks key metrics such as active connections, requests per second, HTTP status codes, and response times. Additionally, it collects system-level data, including CPU usage, memory consumption, and disk I/O. These insights provide deep observability into NGINX's behavior, enabling teams to troubleshoot issues effectively, optimize performance, and maintain high availability. +- Collected metrics can be seamlessly exported to the NGINX One Console or integrated with third-party data aggregators. + + + + +{{< img src="agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} + +--- + diff --git a/content/agent/changelog.md b/content/agent/changelog.md index b0f79ce37..e75b2496b 100644 --- a/content/agent/changelog.md +++ b/content/agent/changelog.md @@ -1,14 +1,16 @@ --- title: "Changelog" -weight: 1200 +weight: 700 toc: true -docs: "DOCS-1093" --- {{< note >}}You can find the full changelog, contributor list and assets for NGINX Agent in the [GitHub repository](https://github.com/nginx/agent/releases).{{< /note >}} See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< relref "./technical-specifications.md" >}}). +--- +## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) + --- ## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0) diff --git a/content/agent/configuration/_index.md b/content/agent/configuration/_index.md deleted file mode 100644 index 7a1f1bce8..000000000 --- a/content/agent/configuration/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Configuration" -description: "Learn how to configure NGINX Agent." -linkTitle: "Configuration" -weight: "400" -menu: docs -url: /nginx-agent/configuration/ ---- \ No newline at end of file diff --git a/content/agent/configuration/configure-nginx-agent-features.md b/content/agent/configuration/configure-nginx-agent-features.md deleted file mode 100644 index 2a1cddcd1..000000000 --- a/content/agent/configuration/configure-nginx-agent-features.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "Features configuration" -draft: false -weight: 150 -toc: true -tags: [ "docs" ] -categories: ["configuration"] -doctypes: ["task"] ---- - -## Overview - -This guide describes the F5 NGINX Agent features, and how to enable and disable features using the NGINX Agent configuration file. - -## Before you begin - -Before you start, make sure that you have: - -- NGINX Agent installed in your system. -- Access to the NGINX Agent configuration file. - - -## Features - -The following table lists the NGINX Agent features. - -{{}} -| **Feature Name** | **Description** | **Default/Non-default** | -| ------------- | ------------- | ------------- | -| registration | Registering the NGINX Agent with the management plane.| Default | -| nginx-config-async | Enable the publishing and uploading of NGINX configurations from the management plane.| Default | -| metrics | Enable collecting of NGINX metrics.| Default | -| metrics-throttle | Batch metrics before sending.| Non-default | -| metrics-sender | Reports metrics over the gRPC connection.| Non-default | -| dataplane-status | Report the health of the NGINX Instance.| Default | -| process-watcher | Observe changes to the NGINX process.| Default | -| file-watcher | Observe changes to the NGINX configuration or any changes to files on disk.| Default | -| activity-events | Send NGINX or NGINX Agent related events to the management plane.| Default | -| agent-api | Enable the NGINX Agent REST API.| Default | -{{}} - -## Use Cases - -### Enable metrics only -1. **Access the NGINX Instance:** SSH to the virtual machine/server where NGINX Agent is running. - -``` - ssh user@your-nginx-instance -``` - -2. **Edit NGINX Agent configuration:** - -``` - sudo vim /etc/nginx-agent/nginx-agent.conf -``` - -3. **Add Features section:** Add the following yaml to the end of the file: - -``` - features: - - metrics - - metrics-throttle - - dataplane-status -``` - -4. **Restart the NGINX Agent service:** Restart the NGINX Agent service to enable changes. - -Once the steps have been completed, users will be able to view metrics data being sent but will not have the capability to push NGINX configuration changes. - -### Enable the publishing of NGINX configurations and disable the collection of metrics. -1. **Access the NGINX Instance:** SSH to the virtual machine/server where NGINX Agent is running. - -``` - ssh user@your-nginx-instance -``` - -2. **Edit NGINX Agent configuration:** - -``` - sudo vim /etc/nginx-agent/nginx-agent.conf -``` - -3. **Add Features section:** Add the following yaml to the end of the file: - -``` - features: - - nginx-config-async - - dataplane-status - - file-watcher -``` - -4. **Restart the NGINX Agent service:** Restart the NGINX Agent service to enable changes. - -Once the steps have been completed, users will be able to publish NGINX configurations but metrics data will not be collected by the NGINX Agent. - diff --git a/content/agent/contribute/_index.md b/content/agent/contribute/_index.md index 24e4c7de2..a6764819d 100644 --- a/content/agent/contribute/_index.md +++ b/content/agent/contribute/_index.md @@ -1,8 +1,7 @@ --- title: "Contribute" -description: "Learn about the NGINX Agent community and contribute to the project." -linkTitle: "Contribute" -menu: docs -weight: "500" +weight: 600 url: /nginx-agent/contribute/ ---- \ No newline at end of file +--- + +Learn about the NGINX Agent community and how to contribute to the project. \ No newline at end of file diff --git a/content/agent/contribute/community.md b/content/agent/contribute/community.md index 2566b4741..3fbf8f161 100644 --- a/content/agent/contribute/community.md +++ b/content/agent/contribute/community.md @@ -1,14 +1,12 @@ --- title: "Community and contribution" -draft: false -weight: 100 toc: true -tags: [ "docs" ] -docs: "DOCS-1087" -categories: ["configuration"] -doctypes: ["task"] +weight: 100 +docs: DOCS-000 --- +This topic describes the various ways you can get involved with the F5 NGINX Agent project. + # Community - Our [Slack channel #nginx-agent](https://nginxcommunity.slack.com/), is the go-to place to start asking questions and sharing your thoughts. diff --git a/content/agent/contribute/dev-environment-setup.md b/content/agent/contribute/dev-environment-setup.md index 4860764f5..2e9fe571c 100644 --- a/content/agent/contribute/dev-environment-setup.md +++ b/content/agent/contribute/dev-environment-setup.md @@ -1,65 +1,61 @@ --- title: "Development environment setup" -draft: false -weight: 200 toc: true -tags: [ "docs" ] -docs: "DOCS-1088" -categories: ["development"] -doctypes: ["task"] +weight: 200 +docs: DOCS-000 --- ## Overview -Learn how to setup a Development Environment for NGINX Agent. +This page describes how to configure a development environment for F5 NGINX Agent. + +While most Linux or FreeBSD operating systems can be used to contribute to the NGINX Agent project, the following steps have been designed for Ubuntu. + +Ubuntu is the recommended operating system for development, as it comes with most packages requires to build and run NGINX Agent. + +## Before you begin -## Select an Operating System +To begin this task, you will require the following: -While most Linux or FreeBSD operating systems can be used to contribute to the NGINX Agent project, the following steps have been designed for Ubuntu. Ubuntu is packaged with most libraries required to build and run NGINX Agent, and is the recommended platform for NGINX Agent development. +- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). +- A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. +- A [Protocol Buffer Compiler](https://grpc.io/docs/protoc-installation/) installation. -## Install NGINX +You will also need a copy of the NGINX Agent repository, which you can clone using `git`: -Follow the steps in the [Installation]({{< relref "/agent/installation-upgrade/" >}}) section to download, install, and run NGINX and NGINX Agent. +```shell +git clone git@github.com:nginx/agent.git +``` -## Clone the NGINX Agent Repository +Read [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for more information -Using your preferred method, clone the NGINX Agent repository into your development directory. See [Cloning a GitHub Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for additional help. +Follow the steps in the [Installation]({{< relref "/agent/install-upgrade/install.md" >}}) topic to install NGINX Agent. -## Installing Prerequisite Packages +## Install prerequisite packages Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent. Change to the NGINX Agent source directory: -```bash +```shell cd /agent ``` Install Make: -```bash +```shell sudo apt install make ``` -NGINX Agent is written in Go. You may [download Go](https://go.dev/doc/install) and follow installation instructions on the same page or run: -```bash -sudo apt install golang-go -``` - -Install Protoc: -```bash -sudo apt install -y protobuf-compiler -``` - Install NGINX Agent tools and dependencies: Before starting development on NGINX Agent, it is important to download and install the necessary tool and dependencies required by NGINX Agent. You can do this by running the following `make` command: -```bash +```shell make install-tools deps ``` -## Building NGINX Agent from Source Code +## Build NGINX Agent from source code Run the following commands to build and run NGINX Agent: -```bash +```shell make build sudo make run ``` diff --git a/content/agent/contribute/start-mock-interface.md b/content/agent/contribute/start-mock-interface.md new file mode 100644 index 000000000..5b2a7e585 --- /dev/null +++ b/content/agent/contribute/start-mock-interface.md @@ -0,0 +1,90 @@ +--- +title: Start mock control plane interface +toc: true +weight: 300 +docs: DOCS-000 +--- + +This document describes how to configure and run F5 NGINX Agent using a mock interface ("control plane") for NGINX Agent to report to. + +The mock interface is useful when developing NGINX Agent, as it allows you to view what metrics are being reported. + +## Before you begin + +To begin this task, you will require the following: + +- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). +- A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. +- A [go-swagger](https://goswagger.io/go-swagger/install/) installation. + +You will also need a copy of the NGINX Agent repository, which you can clone using `git`: + +```shell +git clone git@github.com:nginx/agent.git +``` + +Read [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for more information. + +## Start the gRPC mock control plane + +Start the mock control plane by running the following command from the `agent` source code root directory: + +```shell +go run sdk/examples/server.go +``` +```text +INFO[0000] http listening at 54790 # mock control plane port +INFO[0000] grpc listening at 54789 # grpc control plane port which NGINX Agent will report to +``` + +The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent. + +To enable them, view the [Enable gRPC and REST interfaces]({{< relref "/agent/how-to/enable-interfaces.md" >}}) topic. + +## Launch Swagger UI + +To launch the Swagger UI for the REST interface run the following command: + +```shell +make launch-swagger-ui +``` + +## Start NGINX Agent + +Open another terminal window and start NGINX Agent. Issue the following command from the `agent` source code root directory. + +```shell +sudo make run +``` +```text +WARN[0000] Log level is info +INFO[0000] setting displayName to XXX +INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX +INFO[0000] NginxBinary initializing +INFO[0000] Commander initializing +INFO[0000] Comms initializing +INFO[0000] OneTimeRegistration initializing +INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX +INFO[0000] Metrics initializing +INFO[0000] MetricsThrottle initializing +INFO[0000] DataPlaneStatus initializing +INFO[0000] MetricsThrottle waiting for report ready +INFO[0000] Metrics waiting for handshake to be completed +INFO[0000] ProcessWatcher initializing +INFO[0000] Extensions initializing +INFO[0000] FileWatcher initializing +INFO[0000] FileWatchThrottle initializing +INFO[0001] Events initializing +INFO[0001] OneTimeRegistration completed +``` + +Open a web browser to view the mock control plane at [http://localhost:54790](http://localhost:54790). The following links will be shown in the web interface: + +- **registered** - shows registration information of the data plane +- **nginxes** - lists the nginx instances on the data plane +- **configs** - shows the protobuf payload for NGINX configuration sent to the management plane +- **configs/chunked** - shows the split-up payloads sent to the management plane +- **configs/raw** - shows the actual configuration as it would live on the data plane +- **metrics** - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API) + +For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/main/sdk/examples). \ No newline at end of file diff --git a/content/agent/how-to/_index.md b/content/agent/how-to/_index.md new file mode 100644 index 000000000..d0f9b4cc5 --- /dev/null +++ b/content/agent/how-to/_index.md @@ -0,0 +1,7 @@ +--- +title: "How-to guides" +weight: 500 +url: /nginx-agent/how-to/ +--- + +Learn how to configure NGINX Agent \ No newline at end of file diff --git a/content/agent/how-to/configuration-overview.md b/content/agent/how-to/configuration-overview.md new file mode 100644 index 000000000..03fbe48ac --- /dev/null +++ b/content/agent/how-to/configuration-overview.md @@ -0,0 +1,50 @@ +--- +title: "Configuration overview" +toc: true +weight: 300 +docs: DOCS-1229 +--- + +This page describes how to configure F5 NGINX Agent using configuration files, CLI (Command line interface) flags, and environment variables. + +{{}} + +- 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. + +{{}} + +## Configuration via Configuration Files + +The NGINX Agent configuration file is created using a YAML structure and can be found in `/etc/nginx-agent/nginx-agent.conf` + +1. Edit the configuration file `sudo vim /etc/nginx-agent/nginx-agent.conf` +2. Add the log property +```bash +log: + level: debug +``` +3. Save and exit +4. `sudo systemctl restart nginx-agent` + +## Configuration via CLI Parameters + +From a command line terminal: +```bash +sudo nginx-agent \ + --log-level=debug +``` + +## Configuration via Environment Variables +Environment variables are another way to set configuration values, especially in containerized deployments or CI/CD pipelines. + +```bash +sudo docker run \ + --env=NGINX_AGENT_LOG_LEVEL=debug \ + -d agent +``` diff --git a/content/agent/how-to/configure-agent-group.md b/content/agent/how-to/configure-agent-group.md new file mode 100644 index 000000000..dbfd3c6dd --- /dev/null +++ b/content/agent/how-to/configure-agent-group.md @@ -0,0 +1,87 @@ +--- +title: "Add users to nginx-agent group" +toc: true +weight: 400 +docs: DOCS-000 +--- + +This page describes how the F5 NGINX Agent process interacts with the NGINX user on a system, and how to add users to the NGINX Agent group. + +## 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: + + ```shell + sudo getent group | grep nginx-agent + ``` + + The output looks similar to the following example: + + ```shell + nginx-agent:x:1001:root,nginx + ``` + + If the group doesn't exist, create it by running the following command: + + ```shell + sudo groupadd nginx-agent + ``` + +2. Verify the ownership of `/var/run/nginx-agent` directory: + + ```shell + ls -l /var/run/nginx-agent + ``` + + The output looks similar to the following: + + ```shell + 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: + + ```shell + sudo chown :nginx-agent /var/run/nginx-agent + ``` + +3. To add NGINX user(s) to the `nginx-agent` group, run the following command: + + ```shell + sudo usermod -a -G nginx-agent + ``` + + For example to add the `nginx` user, take the following step: + + ```shell + sudo usermod -a -G nginx-agent nginx + ``` + + Repeat for all NGINX users. diff --git a/content/agent/how-to/connect-management-plane.md b/content/agent/how-to/connect-management-plane.md new file mode 100644 index 000000000..c0919d65e --- /dev/null +++ b/content/agent/how-to/connect-management-plane.md @@ -0,0 +1,114 @@ +--- +title: "Connect to management plane" +toc: true +weight: 600 +docs: DOCS-000 +--- + +## Overview + +To monitor and manage all your F5 NGINX Agent instances from a central management plane server, you first need to connect your instances and the server. You can configure the connection by making the required changes to the NGINX Agent configuration file. + +There are three types of connections you can establish between the NGINX Agent and the management plane server: + +- [Mutual Transport Layer Security (mTLS) connection](#mtls-connection) +- [Transport Layer Security (TLS) connection](#tls-connection) +- [Insecure connection](#insecure-connection) + +## mTLS connection + +To establish a mTLS connection between the NGINX Agent and the management plane server, follow these steps: + + 1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to enable mTLS for NGINX Agent. Replace the example values with your own: + + ```yaml + command: + server: + # the server host to connect to in order to send + # and receive commands e.g. config apply instructions + host: example.com + # the server port to connect to in order to send and receive commands + # e.g. config apply instructions + port: 443 + # the type of connection. Currently only "grpc" is supported. + type: grpc + auth: + # the token to be used in the authorization header + # for the Agent initiated requests + token: ... + tls: + # The client key to be used in the TLS/mTLS connection + key: /etc/ssl/certs/key.pem + # The client certificate to be used in the TLS/mTLS connection + cert: /etc/ssl/certs/cert.pem + # The certificate authority certificate to be used in the mTLS connection + ca: /etc/ssl/certs/ca.pem + # controls whether the server certificate chain and host name are verified + skip_verify: false + # A hostname value specified in the Subject Alternative Name extension + server_name: example.com + ``` +2. Restart the NGINX Agent service: + + ```shell + sudo systemctl restart nginx-agent + ``` + +## TLS connection + +To establish a TLS connection between the NGINX Agent and the management plane server, follow these steps: + +1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to enable TLS for NGINX Agent. Replace the example values with your own: + + ```yaml + command: + server: + # the server host to connect to in order to send and receive commands + # e.g. config apply instructions + host: example.com + # the server port to connect to in order to send and receive commands + # e.g. config apply instructions + port: 443 + # the type of connection. Currently only "grpc" is supported. + type: grpc + auth: + # the token to be used in the authorization header for the + # Agent initiated requests + token: ... + tls: + # controls whether the server certificate chain and host name are verified + skip_verify: false + ``` + + {{< note >}}To enable server-side TLS with a self-signed certificate, you must have TLS enabled and set `skip_verify` to `true`, which disables hostname validation. Setting `skip_verify` can be done only by updating the configuration file. **This is not recommended for production environments**.{{< /note >}} + +2. Restart the NGINX Agent service: + + ```shell + sudo systemctl restart nginx-agent + ``` + +## Insecure connection + +{{< warning >}}Insecure connections are not recommended for production environments.{{< /warning >}} + +To establish an insecure connection between the NGINX Agent and the management plane server, follow these steps: + +1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to enable an insecure connection for NGINX Agent. Replace the example values with your own: + + ```yaml + command: + server: + # the server host to connect to in order to send and receive commands e.g. config apply instructions + host: example.com + # the server port to connect to in order to send and receive commands e.g. config apply instructions + port: 443 + # the type of connection. Currently only "grpc" is supported. + type: grpc + ``` + +2. Restart the NGINX Agent service: + + ```shell + sudo systemctl restart nginx-agent + ``` diff --git a/content/agent/how-to/enable-interfaces.md b/content/agent/how-to/enable-interfaces.md new file mode 100644 index 000000000..fbd174e30 --- /dev/null +++ b/content/agent/how-to/enable-interfaces.md @@ -0,0 +1,73 @@ +--- +title: "Enable gRPC and REST interfaces" +toc: true +weight: 200 +docs: DOCS-000 +--- + +This document describes how to enable the gRPC and REST interfaces for F5 NGINX Agent. + +## Before you begin + +If it doesn't already exist, create the directory `/etc/nginx-agent/`and copy the `nginx-agent.conf` file into it from the project root directory. + +```shell +sudo mkdir /etc/nginx-agent +sudo cp /nginx-agent.conf /etc/nginx-agent/ +``` + +Create the `agent-dynamic.conf` file, which is required for NGINX Agent to run. + +In Linux environments: +```shell +sudo touch /var/lib/nginx-agent/agent-dynamic.conf +``` + +In FreeBSD environments: +```shell +sudo touch /var/db/nginx-agent/agent-dynamic.conf +``` + +--- + +## Enable the gRPC interface + +Add the the following settings to `/etc/nginx-agent/nginx-agent.conf`: + +```yaml +server: + host: 127.0.0.1 # mock control plane host + grpcPort: 54789 # mock control plane gRPC port + +# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION +tls: + enable: false + skip_verify: true +``` + +For more information, see [Agent Protocol Definitions and Documentation](https://github.com/nginx/agent/tree/main/docs/proto/README.md). + +--- + +## Enable the REST interface + +The NGINX Agent REST interface can be exposed by validating the following lines in the `/etc/nginx-agent/nginx-agent.conf` file are present: + +```yaml +api: + # Set API address to allow remote management + host: 127.0.0.1 + # Set this value to a secure port number to prevent information leaks + port: 8038 + # REST TLS parameters + cert: ".crt" + key: ".key" +``` + +--- + +## Start NGINX Agent + +To apply the new configuration, NGINX Agent must be started or restarted. + +You may want to view the [Start mock control plane interface]({{< relref "/agent/contribute/start-mock-interface.md" >}}) topic to test NGINX Agent, or view the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md" >}}) for more options. \ No newline at end of file diff --git a/content/agent/how-to/encrypt-communication.md b/content/agent/how-to/encrypt-communication.md new file mode 100644 index 000000000..00876ffc4 --- /dev/null +++ b/content/agent/how-to/encrypt-communication.md @@ -0,0 +1,126 @@ +--- +title: "Encrypt communication" +toc: true +weight: 500 +docs: DOCS-000 +--- + +## Overview + +Follow the steps in this guide to encrypt communication between F5 NGINX Agent and Instance Manager with TLS. + +## Before You Begin + +To enable mTLS, you must have TLS enabled and supply a key, cert, and a CA cert on both the client and server. TSee the [Secure Traffic with Certificates](https://docs.nginx.com/nginx-management-suite/admin-guides/configuration/secure-traffic/) topic for instructions on how to generate keys and set them in the specific values in the NGINX Agent configuration. + +## Enabling mTLS + +See the examples below for how to set these values using a configuration file, CLI flags, or environment variables. + +### Enabling mTLS via Config Values + +You can edit the `/etc/nginx-agent/nginx-agent.conf` file to enable mTLS for NGINX Agent. Make the following changes: + +```yaml +server: + metrics: "cert-sni-name" + command: "cert-sni-name" +tls: + enable: true + cert: "path-to-cert" + key: "path-to-key" + ca: "path-to-ca-cert" + skip_verify: false +``` + +The `cert-sni-name` value should match the SubjectAltName of the server certificate. For more information see [Configuring HTTPS servers](http://nginx.org/en/docs/http/configuring_https_servers.html). + +### Enabling mTLS with CLI Flags + +To enable mTLS for the NGINX Agent from the command line, run the following command: + +```shell +nginx-agent --tls-cert "path-to-cert" --tls-key "path-to-key" --tls-ca "path-to-ca-cert" --tls-enable +``` + +### Enabling mTLS with Environment Variables + +To enable mTLS for NGINX Agent using environment variables, run the following commands: + +```shell +NMS_TLS_CA="my-env-ca" +NMS_TLS_KEY="my-env-key" +NMS_TLS_CERT="my-env-cert" +NMS_TLS_ENABLE=true +``` + +
+ +--- + +## Enabling Server-Side TLS + +To enable server-side TLS you must have TLS enabled. See the following examples for how to set these values using a configuration file, CLI flags, or environment variables. + +### Enabling Server-Side TLS via Config Values + +You can edit the `/etc/nginx-agent/nginx-agent.conf` file to enable server-side TLS. Make the following changes: + +```shell +tls: + enable: true + skip_verify: false +``` + +### Enabling Server Side TLS with CLI Flags + +To enable server-side TLS from the command line, run the following command: + +```shell +nginx-agent --tls-enable +``` + +### Enabling Server-Side TLS with Environment Variables + +To enable server-side TLS using environment variables, run the following commands: + +```shell +NMS_TLS_ENABLE=true +``` + +
+ +--- + +## Enable Server-Side TLS With Self-Signed Certificate + +{{< warning >}}These steps are not recommended for production environments.{{< /warning >}} + +To enable server-side TLS with a self-signed certificate, you must have TLS enabled and set `skip_verify` to `true`, which disables hostname validation. Setting `skip_verify` can be done done only by updating the configuration file. See the following example: + +```shell +tls: + enable: true + skip_verify: true +``` + +## Insecure Mode (Not Recommended) + +To enable insecure mode, you simply need to set `tls:enable` to `false`. Setting this value to `false` can be done only by updating the configuration file or with environment variables. See the following examples: + +### Enabling Insecure Mode via Config Values** + +You can edit the `/etc/nginx-agent/nginx-agent.conf` file to enable insecure mode. Make the following changes: + +```shell +tls: + enable: false +``` + +### Enabling Insecure Mode with Environment Variables** + +To enable insecure mode using environment variables, run the following commands: + +```shell +NMS_TLS_ENABLE=false +``` diff --git a/content/agent/how-to/export-metrics.md b/content/agent/how-to/export-metrics.md new file mode 100644 index 000000000..9edae11dc --- /dev/null +++ b/content/agent/how-to/export-metrics.md @@ -0,0 +1,45 @@ +--- +title: "Export metrics data" +weight: 300 +docs: DOCS-000 +--- + +This document describes how to export the metrics data from F5 NGINX Agent. + +[//]: # "These are Markdown comments to guide you through document structure." +[//]: # "Remove them as you go, as well as unnecessary sections for this use case." + +## Overview + +[//]: # "Write a description which outlines precisely what this page of instructions will accomplish." +[//]: # "This description, like all instructions, should be direct and imperative." +[//]: # "Avoid ambiguous promises such as 'enables functionality': state precisely what it does." + +--- + +## Before you begin + +[//]: # "List all of the prerequisites for completing this task." +[//]: # "This might be the first page for a reader, so include a link to installation." + +To begin this task, you will require the following: + +- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). +- +- + +--- + +## Export metrics data + + + +--- + +## See also + +[//]: # "Examples of additional topics users might want to read include:" +[//]: # "Relevant reference information, configuration options and more complex use cases." + +- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) +- diff --git a/content/agent/install-upgrade/_index.md b/content/agent/install-upgrade/_index.md new file mode 100644 index 000000000..0274bc7da --- /dev/null +++ b/content/agent/install-upgrade/_index.md @@ -0,0 +1,7 @@ +--- +title: "Install and upgrade" +weight: 400 +url: /nginx-agent/install-upgrade/ +--- + +Learn how to install, upgrade, and uninstall NGINX Agent. \ No newline at end of file diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md new file mode 100644 index 000000000..66bca2ae9 --- /dev/null +++ b/content/agent/install-upgrade/install.md @@ -0,0 +1,871 @@ +--- +title: Install NGINX Agent +toc: true +weight: 100 +docs: DOCS-000 +--- + +This guide walks you through the steps to install NGINX Agent using a variety +of methods: + +- [Install using NGINX One Console](#connect-to-nginx-one-console) +- Install using the [NGINX Open Source repository](#manual-installation-using-the-nginx-open-source-repository) or [NGINX Plus repository](#manual-installation-using-the-nginx-plus-repository) +- [Install using GitHub package files](#github-package-files) + +## Before you begin + +- You must use one of the [supported operating system and architectures]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) +- The user running the NGINX Agent installation must have the same privileges as +the main NGINX process. We recommend **not** running NGINX or NGINX Agent as the root user. + +## Install NGINX Agent using NGINX One Console + +If you are using NGINX One Console to manage your NGINX instances, NGINX Agent is +installed automatically when you add an instance to NGINX One Console. + +For a quick guide on how to connect to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) + +## Manual installation using the NGINX Open Source repository + +Before you install NGINX Agent for the first time on your system, you need to set +up the `nginx-agent` packages repository. Afterward, you can install and update +NGINX Agent from the repository. + +
+{{< fa "brands fa-centos" >}} Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +1. Install the prerequisites: + + ```shell + sudo yum install yum-utils + ``` + +1. To set up the yum repository, create a file with name `/etc/yum.repos.d/nginx-agent.repo` +with the following contents: + + ```ini + [nginx-agent] + name=nginx agent repo + baseurl=http://packages.nginx.org/nginx-agent/centos/$releasever/$basearch/ + gpgcheck=1 + enabled=1 + gpgkey=https://nginx.org/keys/nginx_signing.key + module_hotfixes=true + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo yum install nginx-agent + ``` + + When prompted to accept the GPG key, verify that the fingerprint matches `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it. + +
+ +
+{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +1. Install the prerequisites: + + ```shell + sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring + ``` + +1. Import an official nginx signing key so apt can verify the packages authenticity. Fetch the key: + + ```shell + curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + ``` + +1. Verify that the downloaded file contains the proper key: + + ```shell + gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg + ``` + + The output should contain the full fingerprint `573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62` as follows: + + ``` + pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key + ``` + + {{< important >}}If the fingerprint is different, remove the file.{{< /important >}} + +1. Add the nginx agent repository: + + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://packages.nginx.org/nginx-agent/ubuntu/ `lsb_release -cs` agent" \ + | sudo tee /etc/apt/sources.list.d/nginx-agent.list + ``` + +1. To install `nginx-agent`, run the following commands: + + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
+ +
+{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +1. Install the prerequisites: + + ```shell + sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring + ``` + +1. Import an official nginx signing key so apt can verify the packages authenticity. + Fetch the key: + + ```shell + curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + ``` + +1. Verify that the downloaded file contains the proper key: + + ```shell + gpg --dry-run --quiet --no-keyring \ + --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg + ``` + + The output should contain the full fingerprint `573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62` + as follows: + + ``` + pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key + ``` + + {{< important >}}If the fingerprint is different, remove the file.{{< /important >}} + +1. Add the `nginx-agent` repository: + + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + http://packages.nginx.org/nginx-agent/debian/ `lsb_release -cs` agent" \ | sudo tee /etc/apt/sources.list.d/nginx-agent.list + ``` + +1. To install `nginx-agent`, run the following commands: + + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
+ +
+{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +1. Install the prerequisites: + + ```shell + sudo zypper install curl ca-certificates gpg2 gawk + ``` + +1. To set up the zypper repository for `nginx-agent` packages, run the following command: + + ```shell + sudo zypper addrepo --gpgcheck --refresh --check \ + 'http://packages.nginx.org/nginx-agent/sles/$releasever_major' nginx-agent + ``` + +1. Next, import an official NGINX signing key so `zypper`/`rpm` can verify the +package's authenticity. Fetch the key: + + ```shell + curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key + ``` + +1. Verify that the downloaded file contains the proper key: + + ```shell + gpg --with-fingerprint --dry-run --quiet --no-keyring --import --import-options import-show /tmp/nginx_signing.key + ``` + +1. The output should contain the full fingerprint `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62` as follows: + + ``` + pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 + uid nginx signing key + ``` + +1. Finally, import the key to the rpm database: + + ```shell + sudo rpmkeys --import /tmp/nginx_signing.key + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo zypper install nginx-agent + ``` + +
+ +
+{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +1. Install the prerequisites: + + ```shell + sudo apk add openssl curl ca-certificates + ``` + +1. To set up the apk repository for `nginx-agent` packages, run the following command: + + ```shell + printf "%s%s%s\n" \ + "http://packages.nginx.org/nginx-agent/alpine/v" \ + `grep -o -E '^[0-9]+\.[0-9]+' /etc/alpine-release` \ + "/main" \ + | sudo tee -a /etc/apk/repositories + ``` + +1. Next, import an official NGINX signing key so apk can verify the package's +authenticity. Fetch the key: + + ```shell + curl -o /tmp/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub + ``` + +1. Verify that downloaded file contains the proper key: + + ```shell + openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -text -noout + ``` + + The output should contain the following modulus: + + ``` + Public-Key: (2048 bit) + Modulus: + 00:fe:14:f6:0a:1a:b8:86:19:fe:cd:ab:02:9f:58: + 2f:37:70:15:74:d6:06:9b:81:55:90:99:96:cc:70: + 5c:de:5b:e8:4c:b2:0c:47:5b:a8:a2:98:3d:11:b1: + f6:7d:a0:46:df:24:23:c6:d0:24:52:67:ba:69:ab: + 9a:4a:6a:66:2c:db:e1:09:f1:0d:b2:b0:e1:47:1f: + 0a:46:ac:0d:82:f3:3c:8d:02:ce:08:43:19:d9:64: + 86:c4:4e:07:12:c0:5b:43:ba:7d:17:8a:a3:f0:3d: + 98:32:b9:75:66:f4:f0:1b:2d:94:5b:7c:1c:e6:f3: + 04:7f:dd:25:b2:82:a6:41:04:b7:50:93:94:c4:7c: + 34:7e:12:7c:bf:33:54:55:47:8c:42:94:40:8e:34: + 5f:54:04:1d:9e:8c:57:48:d4:b0:f8:e4:03:db:3f: + 68:6c:37:fa:62:14:1c:94:d6:de:f2:2b:68:29:17: + 24:6d:f7:b5:b3:18:79:fd:31:5e:7f:4c:be:c0:99: + 13:cc:e2:97:2b:dc:96:9c:9a:d0:a7:c5:77:82:67: + c9:cb:a9:e7:68:4a:e1:c5:ba:1c:32:0e:79:40:6e: + ef:08:d7:a3:b9:5d:1a:df:ce:1a:c7:44:91:4c:d4: + 99:c8:88:69:b3:66:2e:b3:06:f1:f4:22:d7:f2:5f: + ab:6d + Exponent: 65537 (0x10001) + ``` + +1. Finally, move the key to apk trusted keys storage: + + ```shell + sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/ + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo apk add nginx-agent + ``` +
+ +
+{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +1. Install the prerequisites: + + ```shell + sudo yum install yum-utils procps + ``` + +1. To set up the yum repository for Amazon Linux 2, create a file with name +`/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ```ini + [nginx-agent] + name=nginx agent repo + baseurl=http://packages.nginx.org/nginx-agent/amzn2/$releasever/$basearch/ + gpgcheck=1 + enabled=1 + gpgkey=https://nginx.org/keys/nginx_signing.key + module_hotfixes=true + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo yum install nginx-agent + ``` + +1. When prompted to accept the GPG key, verify that the fingerprint matches +`573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it. + +
+
+{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +1. To setup the pkg repository create a file with name `/etc/pkg/nginx-agent.conf` +with the following content: + + ```none + nginx-agent: { + URL: pkg+http://packages.nginx.org/nginx-agent/freebsd/${ABI}/latest + ENABLED: true + MIRROR_TYPE: SRV + } + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo pkg install nginx-agent + ``` +
+ +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Manual installation using the NGINX Plus repository + +Before you install NGINX Agent for the first time on your system, you need to +set up the `nginx-agent` packages repository. Afterward, you can install and update +NGINX Agent from the repository. + + +
+{{< fa "brands fa-centos" >}} Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/ssl/nginx/` directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Install the prerequisites: + + ```shell + sudo yum install yum-utils procps + ``` + +1. Set up the yum repository by creating the file `nginx-agent.repo` in + `/etc/yum.repos.d`, for example using `vi`: + + ```shell + sudo vi /etc/yum.repos.d/nginx-agent.repo + ``` + +1. Add the following lines to `nginx-agent.repo`: + + ```ini + [nginx-agent] + name=nginx agent repo + baseurl=https://pkgs.nginx.com/nginx-agent/centos/$releasever/$basearch/ + sslclientcert=/etc/ssl/nginx/nginx-repo.crt + sslclientkey=/etc/ssl/nginx/nginx-repo.key + gpgcheck=0 + enabled=1 + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo yum install nginx-agent + ``` + + When prompted to accept the GPG key, verify that the fingerprint matches + `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it. + +
+ +
+{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/ssl/nginx/` directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Install the prerequisites: + + ```shell + sudo apt-get install apt-transport-https lsb-release ca-certificates wget gnupg2 ubuntu-keyring + ``` + +1. Download and add [NGINX signing key](https://cs.nginx.com/static/keys/nginx_signing.key): + + ```shell + wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null + ``` + +1. Create `apt` configuration `/etc/apt/apt.conf.d/90pkgs-nginx`: + + ```conf + Acquire::https::pkgs.nginx.com::Verify-Peer "true"; + Acquire::https::pkgs.nginx.com::Verify-Host "true"; + Acquire::https::pkgs.nginx.com::SslCert "/etc/ssl/nginx/nginx-repo.crt"; + Acquire::https::pkgs.nginx.com::SslKey "/etc/ssl/nginx/nginx-repo.key"; + ``` + +1. Add the `nginx-agent` repository: + + ```shell + echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nginx-agent/ubuntu/ `lsb_release -cs` agent" \ + | sudo tee /etc/apt/sources.list.d/nginx-agent.list + ``` + +1. To install `nginx-agent`, run the following commands: + + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
+ +
+{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/ssl/nginx/` directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Install the prerequisites: + + ```shell + sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring + ``` + +1. Add the `nginx-agent` repository: + + ```shell + echo "deb https://pkgs.nginx.com/nginx-agent/debian/ `lsb_release -cs` agent" \ + | sudo tee /etc/apt/sources.list.d/nginx-agent.list + ``` + +1. Create apt configuration `/etc/apt/apt.conf.d/90pkgs-nginx`: + + ```conf + Acquire::https::pkgs.nginx.com::Verify-Peer "true"; + Acquire::https::pkgs.nginx.com::Verify-Host "true"; + Acquire::https::pkgs.nginx.com::SslCert "/etc/ssl/nginx/nginx-repo.crt"; + Acquire::https::pkgs.nginx.com::SslKey "/etc/ssl/nginx/nginx-repo.key"; + ``` + +1. To install `nginx-agent`, run the following commands: + + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
+ +
+{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/ssl/nginx/` directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Create a file bundle of the certificate and key: + + ```shell + cat /etc/ssl/nginx/nginx-repo.crt /etc/ssl/nginx/nginx-repo.key > /etc/ssl/nginx/nginx-repo-bundle.crt + ``` + +1. Install the prerequisites: + + ```shell + sudo zypper install curl ca-certificates gpg2 gawk + ``` + +1. To set up the zypper repository for `nginx-agent` packages, run the following + command: + + ```shell + sudo zypper addrepo --refresh --check \ + 'https://pkgs.nginx.com/nginx-agent/sles/$releasever_major?ssl_clientcert=/etc/ssl/nginx/nginx-repo-bundle.crt&ssl_verify=peer' nginx-agent + ``` + +1. Next, import an official NGINX signing key so `zypper`/`rpm` can verify the + package's authenticity. Fetch the key: + + ```shell + curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key + ``` + +1. Verify that the downloaded file contains the proper key: + + ```shell + gpg --with-fingerprint --dry-run --quiet --no-keyring --import --import-options import-show /tmp/nginx_signing.key + ``` + +1. The output should contain the full fingerprint + `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62` as follows: + + ```none + pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 + uid nginx signing key + ``` + +1. Finally, import the key to the rpm database: + + ```shell + sudo rpmkeys --import /tmp/nginx_signing.key + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo zypper install nginx-agent + ``` + +
+ +
+{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/apk/` directory: + + ```shell + sudo cp nginx-repo.key /etc/apk/cert.key + sudo cp nginx-repo.crt /etc/apk/cert.pem + ``` + +1. Install the prerequisites: + + ```shell + sudo apk add openssl curl ca-certificates + ``` + +1. To set up the apk repository for `nginx-agent` packages, run the following + command: + + ```shell + printf "%s%s%s\n" \ + "https://pkgs.nginx.com/nginx-agent/alpine/v" \ + `grep -o -E '^[0-9]+\.[0-9]+' /etc/alpine-release` \ + "/main" \ + | sudo tee -a /etc/apk/repositories + ``` + +1. Next, import an official NGINX signing key so apk can verify the package's authenticity. Fetch the key: + + ```shell + curl -o /tmp/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub + ``` + +1. Verify that downloaded file contains the proper key: + + ```shell + openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -text -noout + ``` + + The output should contain the following modulus: + + ```none + Public-Key: (2048 bit) + Modulus: + 00:fe:14:f6:0a:1a:b8:86:19:fe:cd:ab:02:9f:58: + 2f:37:70:15:74:d6:06:9b:81:55:90:99:96:cc:70: + 5c:de:5b:e8:4c:b2:0c:47:5b:a8:a2:98:3d:11:b1: + f6:7d:a0:46:df:24:23:c6:d0:24:52:67:ba:69:ab: + 9a:4a:6a:66:2c:db:e1:09:f1:0d:b2:b0:e1:47:1f: + 0a:46:ac:0d:82:f3:3c:8d:02:ce:08:43:19:d9:64: + 86:c4:4e:07:12:c0:5b:43:ba:7d:17:8a:a3:f0:3d: + 98:32:b9:75:66:f4:f0:1b:2d:94:5b:7c:1c:e6:f3: + 04:7f:dd:25:b2:82:a6:41:04:b7:50:93:94:c4:7c: + 34:7e:12:7c:bf:33:54:55:47:8c:42:94:40:8e:34: + 5f:54:04:1d:9e:8c:57:48:d4:b0:f8:e4:03:db:3f: + 68:6c:37:fa:62:14:1c:94:d6:de:f2:2b:68:29:17: + 24:6d:f7:b5:b3:18:79:fd:31:5e:7f:4c:be:c0:99: + 13:cc:e2:97:2b:dc:96:9c:9a:d0:a7:c5:77:82:67: + c9:cb:a9:e7:68:4a:e1:c5:ba:1c:32:0e:79:40:6e: + ef:08:d7:a3:b9:5d:1a:df:ce:1a:c7:44:91:4c:d4: + 99:c8:88:69:b3:66:2e:b3:06:f1:f4:22:d7:f2:5f: + ab:6d + Exponent: 65537 (0x10001) + ``` + +1. Finally, move the key to apk trusted keys storage: + + ```shell + sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/ + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo apk add nginx-agent + ``` + +
+
+{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the `nginx-repo.crt` and `nginx-repo.key` files to the `/etc/ssl/nginx/` + directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Install the prerequisites: + + ```shell + sudo yum install yum-utils procps ca-certificates + ``` + +1. To set up the yum repository for Amazon Linux 2, create a file with name + `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ```ini + [nginx-agent] + name=nginx-agent repo + baseurl=https://pkgs.nginx.com/nginx-agent/amzn2/$releasever/$basearch + sslclientcert=/etc/ssl/nginx/nginx-repo.crt + sslclientkey=/etc/ssl/nginx/nginx-repo.key + gpgcheck=0 + enabled=1 + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo yum install nginx-agent + ``` + +1. When prompted to accept the GPG key, verify that the fingerprint matches + `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it. + +
+ +
+{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +1. Create the `/etc/ssl/nginx` directory: + + ```shell + sudo mkdir -p /etc/ssl/nginx + ``` + +1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download + your `nginx-repo.crt` and `nginx-repo.key` files. + +1. Copy the files to the `/etc/ssl/nginx/` directory: + + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` + +1. Install the prerequisite `ca_root_nss` package: + + ```shell + sudo pkg install ca_root_nss + ``` + +1. To setup the pkg repository create a file with name `/etc/pkg/nginx-agent.conf` +with the following content: + + ```none + nginx-agent: { + URL: pkg+https://pkgs.nginx.com/nginx-agent/freebsd/${ABI}/latest + ENABLED: yes + MIRROR_TYPE: SRV + } + ``` + +1. Add the following lines to the `/usr/local/etc/pkg.conf` file: + + ```conf + PKG_ENV: { SSL_NO_VERIFY_PEER: "1", + SSL_CLIENT_CERT_FILE: "/etc/ssl/nginx/nginx-repo.crt", + SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" } + ``` + +1. To install `nginx-agent`, run the following command: + + ```shell + sudo pkg install nginx-agent + ``` + +
+ +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## GitHub package files + +To install NGINX Agent on your system using GitHub package files, go to the +[GitHub releases page](https://github.com/nginx/agent/releases) and download the +latest package supported by your operating system distribution and CPU architecture. + +Use your system's package manager to install the package. Some examples: + +- Debian, Ubuntu, and other distributions using the `dpkg` package manager. + + ```shell + sudo dpkg -i nginx-agent-.deb + ``` + +- RHEL, CentOS RHEL, Amazon Linux, Oracle Linux, and other distributions using + the `yum` package manager + + ```shell + sudo yum localinstall nginx-agent-.rpm + ``` + +- RHEL and other distributions using the `rpm` package manager + + ```shell + sudo rpm -i nginx-agent-.rpm + ``` + +- Alpine Linux + + ```shell + sudo apk add nginx-agent-.apk + ``` + +- FreeBSD + + ```shell + sudo pkg add nginx-agent-.pkg + ``` + +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Start, stop, and enable NGINX Agent + +To start NGINX Agent on `systemd` systems, run the following command: + +```shell +sudo systemctl start nginx-agent +``` + +To enable NGINX Agent to start on boot, run the following command: + +```shell +sudo systemctl enable nginx-agent +``` + +To stop NGINX Agent, run the following command: + +```shell +sudo systemctl stop nginx-agent +``` + +## Verify that NGINX Agent is running + +Once you have installed NGINX Agent, you can verify that it is running with the +following command: + +```shell +sudo systemctl status nginx-agent +``` + +To check the version installed, run the following command: +```shell +sudo nginx-agent -v +``` diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/agent/install-upgrade/migrate-v3.md new file mode 100644 index 000000000..8e557f368 --- /dev/null +++ b/content/agent/install-upgrade/migrate-v3.md @@ -0,0 +1,46 @@ +--- +title: Upgrade from v2.x to v3.0 +weight: 500 +docs: DOCS-000 +--- + +This topic describes how to migrate from F5 NGINX Agent v2 to NGINX Agent v3. + +## Overview + +--- + +## Before you begin + +To begin this task, you will require the following: + +- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/install.md" >}}). +- An NGINX Agent connected to NGINX One. For a quick guide on how to connect to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}) + +--- + +## Migrate from NGINX Agent v2 to v3 + +The migration from NGINX Agent v2 to v3 is handled automatically by the package manager on your OS during the installation of NGINX Agent v3. + +To install NGINX Agent v3 see [Install NGINX Agent]({{< ref "/agent/install-upgrade/install.md" >}}) + +To migrate NGINX Agent containers, we provide a script to convert NGINX Agent v2 config files to NGINX Agent v3 config files: [NGINX Agent Config Upgrade Script](https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh) + +To upgrade the configuration, you can follow this example: + +```shell +wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh +./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf +``` + +If your NGINX Agent container was previously a member of a config sync group, then your NGINX Agent config must be manually updated to add the config sync group label. +See [Add Config Sync Group]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. + +--- + +## Rolling back from NGINX Agent v3 to v2 + +If you need to roll back your environment to NGINX Agent v2, the upgrade process creates a backup of the NGINX Agent v2 config in the file `/etc/nginx-agent/nginx-agent-v2-backup.conf`. + +Replace the conents of `/etc/nginx-agent/nginx-agent.conf` with the contents of `/etc/nginx-agent/nginx-agent-v2-backup.conf` and then reinstall an older version of NGINX Agent. \ No newline at end of file diff --git a/content/agent/install-upgrade/uninstall.md b/content/agent/install-upgrade/uninstall.md new file mode 100644 index 000000000..7fe869d58 --- /dev/null +++ b/content/agent/install-upgrade/uninstall.md @@ -0,0 +1,145 @@ +--- +title: "Uninstall NGINX Agent" +toc: true +weight: 300 +docs: DOCS-000 +--- + +## Overview + +Learn how to uninstall F5 NGINX Agent from your system. + +## Before you begin + +### Prerequisites + +- NGINX Agent installed [NGINX Agent installed](../installation-oss) +- The user following these steps will need `root` privilege + +## Uninstall NGINX Agent +Complete the following steps on each host where you’ve installed NGINX Agent + + +- [Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#uninstall-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) +- [Uninstall NGINX Agent on Ubuntu](#uninstall-nginx-agent-on-ubuntu) +- [Uninstall NGINX Agent on Debian](#uninstall-nginx-agent-on-debian) +- [Uninstall NGINX Agent on SLES](#uninstall-nginx-agent-on-sles) +- [Uninstall NGINX Agent on Alpine Linux](#uninstall-nginx-agent-on-alpine-linux) +- [Uninstall NGINX Agent on Amazon Linux](#uninstall-nginx-agent-on-amazon-linux) +- [Uninstall NGINX Agent on FreeBSD](#uninstall-nginx-agent-on-freebsd) + +### Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +Complete the following steps on each host where you've installed NGINX Agent: + +1. Stop NGINX Agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. To uninstall NGINX Agent, run the following command: + + ```shell + sudo yum remove nginx-agent + ``` + +### Uninstall NGINX Agent on Ubuntu + +Complete the following steps on each host where you've installed NGINX Agent: + +1. Stop NGINX Agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. To uninstall NGINX Agent, run the following command: + + ```shell + sudo apt-get remove nginx-agent + ``` + + {{< note >}} The `apt-get remove ` command will remove the package from your system, while keeping the associated configuration files for possible future use. If you want to completely remove the package and all of its configuration files, you should use `apt-get purge `. {{< /note >}} + +### Uninstall NGINX Agent on Debian + +Complete the following steps on each host where you've installed NGINX Agent: + +1. Stop NGINX Agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. To uninstall NGINX Agent, run the following command: + + ```shell + sudo apt-get remove nginx-agent + ``` + + {{< note >}} The `apt-get remove ` command will remove the package from your system, while keeping the associated configuration files for possible future use. If you want to completely remove the package and all of its configuration files, you should use `apt-get purge `. {{< /note >}} + +### Uninstall NGINX Agent on SLES + +Complete the following steps on each host where you've installed NGINX Agent: + +1. Stop NGINX agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. To uninstall NGINX agent, run the following command: + + ```shell + sudo zypper remove nginx-agent + ``` + +### Uninstall NGINX Agent on Alpine Linux + +Complete the following steps on each host where you've installed NGINX agent: + +1. Stop NGINX agent: + + ```shell + sudo rc-service nginx-agent stop + ``` + +1. To uninstall NGINX agent, run the following command: + + ```shell + sudo apk del nginx-agent + ``` + +### Uninstall NGINX Agent on Amazon Linux + +Complete the following steps on each host where you've installed NGINX agent: + +1. Stop NGINX agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. To uninstall NGINX agent, run the following command: + + ```shell + sudo yum remove nginx-agent + ``` + +### Uninstall NGINX Agent on FreeBSD + +Complete the following steps on each host where you've installed NGINX agent: + +1. Stop NGINX agent: + + ```shell + sudo service nginx-agent stop + ``` + +1. To uninstall NGINX agent, run the following command: + + ```shell + sudo pkg delete nginx-agent + ``` diff --git a/content/agent/install-upgrade/upgrade.md b/content/agent/install-upgrade/upgrade.md new file mode 100644 index 000000000..55898a2bb --- /dev/null +++ b/content/agent/install-upgrade/upgrade.md @@ -0,0 +1,78 @@ +--- +title: "Upgrade NGINX Agent" +toc: true +weight: 200 +docs: DOCS-000 +--- + +## Overview + +Learn how to upgrade F5 NGINX Agent. + +## Upgrade NGINX Agent from version v2.31.0 or greater + +{{< note >}} Starting from version v2.31.0, NGINX Agent will automatically restart itself during an upgrade. {{< /note >}} + +To upgrade NGINX Agent, follow these steps: + +1. Open an SSH connection to the server where you’ve installed NGINX Agent and log in. + +1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade has issues: + + - `/etc/nginx-agent` + - `config_dirs` values for any configuration specified in `/etc/nginx-agent/nginx-agent.conf` + +1. Install the updated version of NGINX Agent: + + - CentOS, RHEL, RPM-Based + + ```shell + sudo yum -y makecache + sudo yum update -y nginx-agent + ``` + + - Debian, Ubuntu, Deb-Based + + ```shell + sudo apt-get update + sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" + ``` + +## Upgrade NGINX Agent from a version less than v2.31.0 + +To upgrade NGINX Agent, take the following steps: + +1. Open an SSH connection to the server where you’ve installed NGINX Agent and log in. + +1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade has issues: + + - `/etc/nginx-agent` + - `config_dirs` values for any configuration specified in `/etc/nginx-agent/nginx-agent.conf` + +1. Stop NGINX Agent: + + ```shell + sudo systemctl stop nginx-agent + ``` + +1. Install the updated version of NGINX Agent: + + - CentOS, RHEL, RPM-Based + + ```shell + sudo yum -y makecache + sudo yum update -y nginx-agent + ``` + + - Debian, Ubuntu, Deb-Based + + ```shell + sudo apt-get update + sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" + ``` + +1. Start NGINX Agent: + + ```shell + sudo systemctl start nginx-agent + ``` diff --git a/content/agent/otel/_index.md b/content/agent/otel/_index.md new file mode 100644 index 000000000..0e113fe11 --- /dev/null +++ b/content/agent/otel/_index.md @@ -0,0 +1,5 @@ +--- +title: OpenTelemetry +weight: 450 +url: /nginx-agent/otel/ +--- \ No newline at end of file diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md new file mode 100644 index 000000000..cac034103 --- /dev/null +++ b/content/agent/otel/configure-otel-metrics.md @@ -0,0 +1,229 @@ +--- +title: Metrics Export +weight: 200 +--- + +## Overview + +The F5 NGINX Agent v3 now includes an embedded [OpenTelemetry](https://opentelemetry.io/) Collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: + +* Metrics from NGINX Plus and NGINX OSS +* Host metrics (CPU, memory, disk, and network activity) from VMs or Containers + + +This guide walks you through enabling and configuring the embedded OpenTelemetry Collector for metric export. + +# Key Benefits + +* Seamless Integration: No need to deploy an external OpenTelemetry Collector. All components are embedded within the Agent for streamlined observability. +* Standardized Protocol: Support for OpenTelemetry standards ensures interoperability with a wide range of observability backends, including Jaeger, Prometheus, Splunk, and more. + +## Before you begin + +Before you begin configuring the F5 NGINX Agent OTel Collector: + +- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) +- F5 NGINX OSS/Plus installed on a Virtual Machine +- F5 NGINX Agent v3 is installed + + +## Configure the OTel Collector - Virtual Machine + +1. Locate the configuration file for the F5 NGINX Agent: + + ```bash + /etc/nginx-agent/nginx-agent.conf + ``` +2. Open the configuration file for editing: + + ```bash + sudo vim /etc/nginx-agent/nginx-agent.conf + ``` + +3. Edit the `/etc/nginx-agent/nginx-agent.conf` and add the following. + + Make sure to replace your-data-plane-key-here with the real data plane key that you are using for your application or service. + + ```vim + collector: + receivers: + host_metrics: + collection_interval: 1m0s + initial_delay: 1s + scrapers: + cpu: {} + memory: {} + disk: {} + network: {} + filesystem: {} + processors: + batch: {} + exporters: + otlp_exporters: + - server: + host: + port: 443 + authenticator: headers_setter + tls: + skip_verify: false + extensions: + headers_setter: + headers: + - action: insert + key: "authorization" + value: "your-data-plane-key-here" + ``` +4. Restart the NGINX Agent service + + ```bash + sudo systemctl restart nginx-agent + ``` + +## Running a Container to Connect to the NGINX One Console and Send Metrics + +This guide provides step-by-step instructions on how to run a container to connect to the NGINX One Console and send metrics. Follow these steps to ensure proper setup and execution. + +--- + +## Prerequisites +Before running the container, ensure the following: +1. **Docker Installed**: Docker must be installed on your system. You can download it from [Docker's official website](https://www.docker.com/). +2. **NGINX One Console**: The NGINX One Console is set up and accessible. +3. **Data Plane Token**: Obtain an access key or Data Plane token from the NGINX One Console for authentication. +4. **Network Connectivity**: Verify that the container can reach the NGINX One Console endpoint. + +--- + +## Steps to Run the Container + +### Step 1: Pull the NGINX Metrics Agent Container Image +The NGINX Metrics Agent container image must be downloaded from a trusted source such as Docker Hub or a private container registry. + +Run the following command to pull the official image: +```bash + +docker pull :latest +``` + +Ensure you are using the correct image version. Replace `latest` with the desired version tag if necessary. + +--- + +### Step 2: Create a Configuration File + +1. Create a configuration file named `nginx-agent.conf` in your current directory. +2. Populate the file with the following structure: + +```vim +command: + server: + host: "" # Command server host + port: 443 # Command server port + type: 0 # Server type (e.g., 0 for gRPC) + auth: + token: "" # Authentication token for the command server + tls: + skip_verify: false + + collector: + receivers: + host_metrics: + collection_interval: 1m0s + initial_delay: 1s + scrapers: + cpu: {} + memory: {} + disk: {} + network: {} + filesystem: {} + processors: + batch: {} + exporters: + otlp_exporters: + - server: + host: + port: 443 + authenticator: headers_setter + tls: + skip_verify: false + extensions: + headers_setter: + headers: + - action: insert + key: "authorization" + value: "your-data-plane-key-here" +``` + +Replace the placeholder values: +- ``: The URL of your NGINX One Console instance. +- ``: Your Data Plane access token. + +--- + +### Step 3: Run the Container +Run the NGINX Agent container with the configuration file mounted. + +Use the following command: +```bash +docker run -d \ + --name nginx-agent \ + -v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf \ + nginx/agent:latest +``` + +Key options explained: +- `-d`: Runs the container in detached mode. +- `--name nginx-agent`: Assigns a name to the container for easy identification. +- `-v $(pwd)/nginx-agent.conf:/etc/nginx-agent/nginx-agent.conf`: Mounts the configuration file into the container. + +--- + +### Step 4: Verify the Container is Running +Check the running status of the container: +```bash +docker ps +``` + +You should see an entry for `nginx-agent`. The `STATUS` field should indicate that the container is running. + +--- + +### Step 5: Monitor Logs +To ensure the container is functioning properly and communicating with NGINX One Console, monitor the container logs. + +Run the following command: +```bash +docker logs -f nginx-agent +``` + +Look for log entries indicating successful connection to the NGINX One Console and periodic metric transmission. + +--- + +### Troubleshooting + +1. **Container Fails to Start**: + - Check the configuration file for errors. + - Ensure the NGINX One Console endpoint is reachable from the host. + +2. **No Metrics Sent**: + - Verify the access token is valid. + - Confirm network connectivity to the NGINX One Console. + +3. **Logs Show Errors**: + - Examine the logs for specific error messages. + - Address any permission or network-related issues. + +--- + +## Clean Up +To stop and remove the container when it is no longer needed, run: +```bash +docker stop nginx-metrics-agent +docker rm nginx-metrics-agent +``` + +--- + +## Conclusion +Following these instructions, you can successfully run a container to connect to the NGINX One Console and send metrics. For further details or issues, refer to the documentation provided by NGINX or your administrator. \ No newline at end of file diff --git a/content/agent/otel/metrics.md b/content/agent/otel/metrics.md new file mode 100644 index 000000000..179f413b9 --- /dev/null +++ b/content/agent/otel/metrics.md @@ -0,0 +1,5 @@ +--- +title: OpenTelemetry metrics +weight: 300 +docs: DOCS-000 +--- \ No newline at end of file diff --git a/content/agent/overview.md b/content/agent/overview.md deleted file mode 100644 index ea9e92ddd..000000000 --- a/content/agent/overview.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Overview" -draft: false -weight: 100 -toc: true -tags: [ "docs" ] -docs: "DOCS-1091" -categories: ["configuration"] -doctypes: ["task"] ---- - -## Overview - -NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables: - -- Remote management of NGINX configurations -- Collection and reporting of real-time NGINX performance and operating system metrics -- Notifications of NGINX events - - -{{< img src="agent/grafana-dashboard-example.png" caption="Grafana dashboard showing metrics reported by NGINX Agent" alt="Grafana dashboard showing metrics reported by NGINX Agent" width="99%">}} - -## How it Works - -NGINX Agent runs as a companion process on a system running NGINX. It provides gRPC and REST interfaces for configuration management and metrics collection from the NGINX process and operating system. NGINX Agent enables remote interaction with NGINX using common Linux tools and unlocks the ability to build sophisticated monitoring and control systems that can manage large collections of NGINX instances. - -{{< img src="agent/agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} - - -## Configuration Management - -NGINX Agent provides an API interface for submission of updated configuration files. Upon receipt of a new file, it checks the output of `nginx -V` to determine the location of existing configurations. It then validates the new configuration with `nginx -t` before applying it via a signal HUP to the NGINX master process. - -## Collecting Metrics - -NGINX Agent interfaces with NGINX process information and parses NGINX logs to calculate and report metrics. When interfacing with NGINX Plus, NGINX Agent pulls relevant information from the NGINX Plus API. Reported metrics may be aggregated by [Prometheus](https://prometheus.io/) and visualized with tools like [Grafana](https://grafana.com/). - -### NGINX Open Source - -When running alongside an open source instance of NGINX, NGINX Agent requires that NGINX Access and Error logs are turned on and contain all default variables. - -### NGINX Plus - -For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. See [Instance Metrics Overview](https://docs.nginx.com/nginx-instance-manager/monitoring/overview-metrics/) for more details. Once NGINX Plus is configured with the `/api/` endpoint, the Agent will automatically use it on startup. - -## Event Notifications - -NGINX Agent allows a gRPC connected control system to register a listener for a specific event. The control mechanism is then invoked when NGINX Agent sends an associated system signal. The source of a notification can be either the NGINX instance or NGINX Agent itself. Here's a list of currently supported events: - - -{{< raw-html>}}
{{}} -{{}} -| Event | Description | -| -------------------------------- | -------------------------------------------- | -| AGENT_START_MESSAGE | Agent process started | -| AGENT_STOP_MESSAGE | Agent process stopped | -| NGINX_FOUND_MESSAGE | NGINX master process detected on system | -| NGINX_STOP_MESSAGE | NGINX master process stopped | -| NGINX_RELOAD_SUCCESS_MESSAGE | NGINX master process reloaded successfully | -| NGINX_RELOAD_FAILED_MESSAGE | NGINX master process failed to reload | -| NGINX_WORKER_START_MESSAGE | New NGINX worker process started | -| NGINX_WORKER_STOP_MESSAGE | NGINX worker process stopped | -| CONFIG_APPLY_SUCCESS_MESSAGE | Successfully applied new NGINX configuration | -| CONFIG_APPLY_FAILURE_MESSAGE | Failed to apply new NGINX configuration | -| CONFIG_ROLLBACK_SUCCESS_MESSAGE | Successfully rolled back NGINX configuration | -| CONFIG_ROLLBACK_FAILURE_MESSAGE | Failed to roll back NGINX configuration | -{{}} -{{< raw-html>}}
{{}} - - diff --git a/content/agent/support.md b/content/agent/support.md new file mode 100644 index 000000000..6ea9d3af6 --- /dev/null +++ b/content/agent/support.md @@ -0,0 +1,20 @@ +--- +title: Support +weight: 800 +toc: false +type: reference +product: Agent +--- + +## Support policy +F5 NGINX Agent adheres to the support policy detailed in the following knowledge base article: [K000140156](https://my.f5.com/manage/s/article/K000140156). + + +## Contact F5 Support + +For questions and/or assistance with installing, troubleshooting, or using NGINX Agent, contact support via the [MyF5 Customer Portal](https://account.f5.com/myf5). + +## Community support + +- If you experience issues with NGINX Agent, please [open an issue in GitHub](https://github.com/nginx/agent/issues/new). +- If you have any suggestions or feature requests, please [open an idea in GitHub discussions](https://github.com/nginx/agent/discussions). diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index a17b9fe9f..5bcd11efc 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -1,60 +1,73 @@ --- -title: "Technical specifications" -draft: false -weight: 200 +title: "Technical Specifications" toc: true -tags: [ "docs" ] -docs: "DOCS-1092" -categories: ["development"] -doctypes: ["task"] +weight: 700 +docs: DOCS-000 --- ## Overview -This document provides technical specifications for NGINX Agent. It includes information on supported distributions, deployment environments, NGINX versions, sizing recommendations, and logging. +This document outlines the technical specifications for the F5 NGINX Agent, including details on supported operating systems, deployment environments, compatible NGINX versions, minimum system sizing requirements, and logging considerations. -## Supported Distributions - -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 | Debian | -|-|-----------|--------------|--------------|----------------|--------| -|**Version**|8

9 | 3.17

3.18

3.19

3.20| 2023| LTS| 11

12| -|**Architecture**| x86_84

aarch64| x86_64

aarch64 | x86_64

aarch64 | x86_64

aarch64 | x86_64

aarch64 | -{{< /bootstrap-table >}} +## Supported Distributions -{{< bootstrap-table "table table-striped table-bordered" >}} -| |FreeBSD | Oracle Linux | Red Hat
Enterprise Linux
(RHEL) | Rocky Linux | SUSE Linux
Enterprise Server
(SLES) | Ubuntu | -|-|--------|--------------|---------------------------------|-------------|-------------------------------------|--------| -|**Version**|13

14|8.1+

9|8.1+

9.0+|8

9|12 SP5

15 SP2|20.04 LTS

22.04 LTS

24.04 LTS| -|**Architecture**|amd64|x86_64|x86_64

aarch64|x86_64

aarch64|x86_64|x86_64

aarch64| -{{< /bootstrap-table >}} +The NGINX Agent is versatile and can operate across various environments. Currently, the following distributions are supported: + +| Distribution | Supported Versions | Architectures | +|------------------------------------|---------------------------------------|---------------------| +| **AlmaLinux** | 8, 9 | x86_64, aarch64 | +| **Alpine Linux** | 3.16, 3.17, 3.18, 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, 12 | x86_64, aarch64 | +| **Oracle Linux** | 7.4+, 8.1+, 9 | x86_64 | +| **Red Hat Enterprise Linux (RHEL)**| 7.4+, 8.1+, 9.0+ | x86_64, aarch64 | +| **Rocky Linux** | 8, 9 | x86_64, aarch64 | +| **SUSE Linux Enterprise Server (SLES)** | 12 SP5, 15 SP2 | x86_64 | +| **Ubuntu** | 20.04 LTS, 22.04 LTS | x86_64, aarch64 | +--- ## Supported Deployment Environments -NGINX Agent can be deployed in the following environments: +The NGINX Agent supports deployment in the following environments: + +- **Bare Metal** machines +- **Containers** +- **Public Cloud** platforms, including AWS, Google Cloud Platform, and Microsoft Azure +- **Virtual Machines** -- Bare Metal -- Container -- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure -- Virtual Machine +--- ## Supported NGINX Versions -NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. +The NGINX Agent is compatible with all supported releases of NGINX Open Source and NGINX Plus. +--- + +## Minimum System Requirements -## Sizing Recommendations +Below are the recommended minimum system specifications for running the NGINX Agent: -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 >}} +| **Resource** | **Minimum Requirement** | +|--------------|--------------------------| +| **CPU** | 1 CPU core | +| **Memory** | 1 GB RAM | +| **Network** | 1 GbE NIC | +| **Storage** | 20 GB | + +--- ## 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). \ No newline at end of file +The NGINX Agent uses log files in standardized formats to collect metrics. As the number of log formats or instances grows, the size of these log files will increase correspondingly. + +To avoid system storage constraints caused by expanding log directories, it is recommended to: + +- Set up a **dedicated partition** for `/var/log/nginx-agent`. +- Enable **[log rotation](https://linux.die.net/man/8/logrotate)** to manage log file growth effectively. + +For additional details on managing logs, refer to the [Configuration Overview]({{< relref "/agent/how-to/configuration-overview.md#logs" >}}). \ No newline at end of file diff --git a/content/agent/troubleshooting.md b/content/agent/troubleshooting.md new file mode 100644 index 000000000..cd2c1ceef --- /dev/null +++ b/content/agent/troubleshooting.md @@ -0,0 +1,30 @@ +--- +title: Troubleshooting +toc: true +weight: 700 +docs: DOCS-000 +--- + +## F5 NGINX Agent Troubleshooting + +**1. Container running but Agent is not connected to NGINX One Console?** +- Check Agent logs ```bash + docker logs + ``` +- If you are using NGINX Plus, a valid license will need to be passed into the container run command. +- Ensure that the values sent with the container run command are correct. + +**2. Container running but instance is showing offline on NGINX One Console?** +- Check Agent logs ```bash + docker logs c5e1e3234900 | grep "nginx" + ``` +- Verify the following log message is shown: ```2025/02/17 19:02:58 [notice] 32#32: nginx/1.27.2 (nginx-plus-r33-p2 ``` +- If not found, it could mean the container image is missing the NGINX service +- Make sure NGINX is running ```ps -ef | grep "nginx"``` +- Make sure NGINX is part of the image file. + + +**3. NGINX Agent is installed on my Virtual Machine, but not showing up on NGINX One Console?** +- Verify the agent is running ```sudo systemctl status nginx-agent``` +- Check for any errors in the logs ```sudo tail -f /var/log/nginx-agent/agent.log``` +- Check ```/etc/nginx-agent/nginx-agent.conf``` for any misconfigurations. diff --git a/content/agent/v2/_index.md b/content/agent/v2/_index.md new file mode 100644 index 000000000..df7a692dd --- /dev/null +++ b/content/agent/v2/_index.md @@ -0,0 +1,8 @@ +--- +title: "NGINX Agent v2" +description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance." +weight: 900 +url: /nginx-agent/v2/ +cascade: + type: agent-v2-migration +--- \ No newline at end of file diff --git a/content/agent/v2/changelog.md b/content/agent/v2/changelog.md new file mode 100644 index 000000000..981348f9e --- /dev/null +++ b/content/agent/v2/changelog.md @@ -0,0 +1,282 @@ +--- +title: "Changelog" +weight: 1200 +toc: true +docs: "DOCS-1093" +--- + +{{< note >}}You can find the full changelog, contributor list and assets for NGINX Agent in the [GitHub repository](https://github.com/nginx/agent/releases).{{< /note >}} + +See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< relref "./technical-specifications.md" >}}). + +--- +## Release [v2.39.0](https://github.com/nginx/agent/releases/tag/v2.39.0) + +### 🌟 Highlights + +- Remove official docker images & move testing images to test folder by [@aphralG](https://github.com/aphralG) in [#838](https://github.com/nginx/agent/pull/838) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Race conditions fixes by [@oliveromahony](https://github.com/oliveromahony) in [#810](https://github.com/nginx/agent/pull/810) +- fix r30 pipeline failures by [@oliveromahony](https://github.com/oliveromahony) in [#844](https://github.com/nginx/agent/pull/844) +- Fixed make target pointing at wrong Dockerfile and renamed others to be consistent by [@oliveromahony](https://github.com/oliveromahony) in [#857](https://github.com/nginx/agent/pull/857) +- Fix broken links causing deployment failures by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#863](https://github.com/nginx/agent/pull/863) +- Fix NGINX OSS integration tests by [@dhurley](https://github.com/dhurley) in [#888](https://github.com/nginx/agent/pull/888) +- Fix docs docker failing without git context by [@nginx-jack](https://github.com/nginx-jack) in [#892](https://github.com/nginx/agent/pull/892) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Add automatic changelog generation in release workflow by [@spencerugbo](https://github.com/spencerugbo) in [#784](https://github.com/nginx/agent/pull/784) +- Add CLA bot workflow by [@lucacome](https://github.com/lucacome) in [#828](https://github.com/nginx/agent/pull/828) +- Refactor docker images by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#841](https://github.com/nginx/agent/pull/841) +- Docs: Add hugo version check and theme update to Makefile by [@nginx-jack](https://github.com/nginx-jack) in [#869](https://github.com/nginx/agent/pull/869) +- Change casing of docs makefile to Makefile by [@nginx-jack](https://github.com/nginx-jack) in [#884](https://github.com/nginx/agent/pull/884) +- docs: enableGitInfo config and docs-action bump by [@nginx-jack](https://github.com/nginx-jack) in [#886](https://github.com/nginx/agent/pull/886) +- Change go version to latest go 1.23.2 by [@oliveromahony](https://github.com/oliveromahony) in [#889](https://github.com/nginx/agent/pull/889) +- Remove link to github dockerfiles by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#897](https://github.com/nginx/agent/pull/897) +- Docs: Update link to 3rd party site by [@nginx-aoife](https://github.com/nginx-aoife) in [#898](https://github.com/nginx/agent/pull/898) +- Update the changelog for v2.38 by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#901](https://github.com/nginx/agent/pull/901) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Set log level to debug for inetegration tests by [@aphralG](https://github.com/aphralG) in [#826](https://github.com/nginx/agent/pull/826) +- updated runc dependency highlighted in security scan scan by [@oliveromahony](https://github.com/oliveromahony) in [#842](https://github.com/nginx/agent/pull/842) +- Update CODEOWNERS by [@oCHRISo](https://github.com/oCHRISo) in [#851](https://github.com/nginx/agent/pull/851) +- Check version command output by [@aphralG](https://github.com/aphralG) in [#853](https://github.com/nginx/agent/pull/853) +- Bump NGINX plus go client version from v1 to v2 by [@dhurley](https://github.com/dhurley) in [#879](https://github.com/nginx/agent/pull/879) +- Allowlist Error Messages by [@aphralG](https://github.com/aphralG) in [#907](https://github.com/nginx/agent/pull/907) + +--- +## Release [v2.38.0](https://github.com/nginx/agent/releases/tag/v2.38.0) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Fix broken URLS in docs by [@nginx-aoife](https://github.com/nginx-aoife) in [#796](https://github.com/nginx/agent/pull/796) +- fix name of deprecated flag by [@aphralG](https://github.com/aphralG) in [#811](https://github.com/nginx/agent/pull/811) +- Fix make image targets by [@dhurley](https://github.com/dhurley) in [#812](https://github.com/nginx/agent/pull/812) +- Fix debian oss image by [@dhurley](https://github.com/dhurley) in [#819](https://github.com/nginx/agent/pull/819) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- docs: update GPG keys by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#776](https://github.com/nginx/agent/pull/776) +- Add new docker images to v2 pipeline for integration testing by [@oliveromahony](https://github.com/oliveromahony) in [#756](https://github.com/nginx/agent/pull/756) +- Update website changelog for v2.37.0 by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#790](https://github.com/nginx/agent/pull/790) +- Pass on custom error log path at the time of validating config by [@achawla2012](https://github.com/achawla2012) in [#774](https://github.com/nginx/agent/pull/774) +- Remove blocking calls in metrics framework by [@oliveromahony](https://github.com/oliveromahony) in [#788](https://github.com/nginx/agent/pull/788) +- Update broken URL in installation-plus.md by [@nginx-aoife](https://github.com/nginx-aoife) in [#808](https://github.com/nginx/agent/pull/808) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- add new plus docker images to v2 pipeline by [@aphralG](https://github.com/aphralG) in [#779](https://github.com/nginx/agent/pull/779) +- Add MaxRecvMsgSize and MaxSendMsgSize to client and server options by [@oliveromahony](https://github.com/oliveromahony) in [#795](https://github.com/nginx/agent/pull/795) +- added leak tests for agent v2 by [@oliveromahony](https://github.com/oliveromahony) in [#807](https://github.com/nginx/agent/pull/807) + +--- +## Release [v2.37.0](https://github.com/nginx/agent/releases/tag/v2.37.0) + +### πŸš€ Features + +This release introduces the following new features: + +- feat: Update the changelog by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#753](https://github.com/nginx/agent/pull/753) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Prevent writing outside allowed directories list from a config payload with actions by [@oliveromahony](https://github.com/oliveromahony) in [#766](https://github.com/nginx/agent/pull/766) +- The letter v is now always prepended to output of -v by [@olli-holmala](https://github.com/olli-holmala) in [#751](https://github.com/nginx/agent/pull/751) +- Fix backoff to drop Metrics Reports from buffer after max_elapsed_time has been reached by [@oliveromahony](https://github.com/oliveromahony) in [#752](https://github.com/nginx/agent/pull/752) +- Fix Post Install Script Issues by [@spencerugbo](https://github.com/spencerugbo) in [#739](https://github.com/nginx/agent/pull/739) +- docs: fix github links in changelog by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#770](https://github.com/nginx/agent/pull/770) +- Fix post install script for when no nginx instance is installed by [@dhurley](https://github.com/dhurley) in [#773](https://github.com/nginx/agent/pull/773) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Upgrade prometheus exporter version to latest by [@oliveromahony](https://github.com/oliveromahony) in [#749](https://github.com/nginx/agent/pull/749) +- Add badges for Go version, release, license, contributions, and Slack… by [@oCHRISo](https://github.com/oCHRISo) in [#763](https://github.com/nginx/agent/pull/763) +- Add instructions for Amazon Linux 2023 by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#759](https://github.com/nginx/agent/pull/759) +- Add docs-build-push github workflow by [@nginx-jack](https://github.com/nginx-jack) in [#765](https://github.com/nginx/agent/pull/765) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Increase timeout period for collecting metrics by [@oliveromahony](https://github.com/oliveromahony) in [#755](https://github.com/nginx/agent/pull/755) + +--- +## Release [v2.36.1](https://github.com/nginx/agent/releases/tag/v2.36.1) + +### 🌟 Highlights + +- Upgrade crossplane version to prevent Agent from rolling back in the case of valid NGINX configurations by [@oliveromahony](https://github.com/oliveromahony) in [#746](https://github.com/nginx/agent/pull/746) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Added version regex to parse the logs to see if matches vsemvar format by [@oliveromahony](https://github.com/oliveromahony) in [#747](https://github.com/nginx/agent/pull/747) + +--- +## Release [v2.36.0](https://github.com/nginx/agent/releases/tag/v2.36.0) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Fix incorrect bold tag in heading by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#715](https://github.com/nginx/agent/pull/715) +- URL fix for building docker image in README.md by [@y82](https://github.com/y82) in [#720](https://github.com/nginx/agent/pull/720) +- Fix for version by [@oliveromahony](https://github.com/oliveromahony) in [#732](https://github.com/nginx/agent/pull/732) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- More flexible container images for the official images by [@oliveromahony](https://github.com/oliveromahony) in [#729](https://github.com/nginx/agent/pull/729) +- Update configuration examples by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#731](https://github.com/nginx/agent/pull/731) +- updated github.com/rs/cors version by [@oliveromahony](https://github.com/oliveromahony) in [#735](https://github.com/nginx/agent/pull/735) +- docs: update changelog by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#736](https://github.com/nginx/agent/pull/736) +- Upgrade crossplane by [@oliveromahony](https://github.com/oliveromahony) in [#737](https://github.com/nginx/agent/pull/737) + +--- +## Release [v2.35.1](https://github.com/nginx/agent/releases/tag/v2.35.1) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- fix: add deduplication for the same ssl cert metadata by [@mattdesmarais](https://github.com/mattdesmarais) [@oliveromahony](https://github.com/oliveromahony) in [#716](https://github.com/nginx/agent/pull/716) +- Fix release workflow by [@dhurley](https://github.com/dhurley) in [#724](https://github.com/nginx/agent/pull/724) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Update environment variables from NMS to NGINX_AGENT by [@spencerugbo](https://github.com/spencerugbo) in [#710](https://github.com/nginx/agent/pull/710) +- Update the flag & environment table callouts by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#712](https://github.com/nginx/agent/pull/712) +- updated golang version to 1.22 by [@oliveromahony](https://github.com/oliveromahony) in [#717](https://github.com/nginx/agent/pull/717) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- More detailed test for env variables migration by [@oliveromahony](https://github.com/oliveromahony) in [#709](https://github.com/nginx/agent/pull/709) + +--- +## Release [v2.35.0](https://github.com/nginx/agent/releases/tag/v2.35.0) + +### 🌟 Highlights + +- R32 operating system support parity by [@oliveromahony](https://github.com/oliveromahony) in [#708](https://github.com/nginx/agent/pull/708) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Change environment prefix from nms to nginx_agent by [@spencerugbo](https://github.com/spencerugbo) in [#706](https://github.com/nginx/agent/pull/706) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Consolidated CLI flag and Env Var sections by [@travisamartin](https://github.com/travisamartin) in [#701](https://github.com/nginx/agent/pull/701) +- Add Ubuntu Noble 24.04 LTS support by [@Dean-Coakley](https://github.com/Dean-Coakley) in [#682](https://github.com/nginx/agent/pull/682) + +--- +## Release [v2.34.1](https://github.com/nginx/agent/releases/tag/v2.34.1) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Fix metrics reporter retry logic by [@dhurley](https://github.com/dhurley) in [#700](https://github.com/nginx/agent/pull/700) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Update changelog for release 2.34 by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#693](https://github.com/nginx/agent/pull/693) + +--- +## Release [v2.34.0](https://github.com/nginx/agent/releases/tag/v2.34.0) + +### 🌟 Highlights + +- Bump the version of net package in golang by [@oliveromahony](https://github.com/oliveromahony) in [#645](https://github.com/nginx/agent/pull/645) + +- Add health check endpoint by [@dhurley](https://github.com/dhurley) in [#665](https://github.com/nginx/agent/pull/665) + +- Add pending health status by [@dhurley](https://github.com/dhurley) in [#672](https://github.com/nginx/agent/pull/672) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- fix: fix titles case by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#674](https://github.com/nginx/agent/pull/674) +- Fix oracle linux integration test by [@dhurley](https://github.com/dhurley) in [#676](https://github.com/nginx/agent/pull/676) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- chore: add 2.33.0 changelog by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#622](https://github.com/nginx/agent/pull/622) +- Change environment variable list to table with CLI references by [@ADubhlaoich](https://github.com/ADubhlaoich) in [#689](https://github.com/nginx/agent/pull/689) +- Add health checks documentation by [@dhurley](https://github.com/dhurley) in [#673](https://github.com/nginx/agent/pull/673) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Keep looking for master process by [@spencerugbo](https://github.com/spencerugbo) in [#617](https://github.com/nginx/agent/pull/617) +- Bump docker dependency to version v24.0.9 by [@dhurley](https://github.com/dhurley) in [#626](https://github.com/nginx/agent/pull/626) +- Bump the version of github.com/opencontainers/runc dependency by [@dhurley](https://github.com/dhurley) in [#657](https://github.com/nginx/agent/pull/657) +- Remove unnecessary freebsd logic for finding process executable by [@dhurley](https://github.com/dhurley) in [#668](https://github.com/nginx/agent/pull/668) +- Add additional checks in chunking functionality by [@dhurley](https://github.com/dhurley) in [#671](https://github.com/nginx/agent/pull/671) + +--- +## Release [v2.33.0](https://github.com/nginx/agent/releases/tag/v2.33.0) + +### πŸš€ Features + +This release introduces the following new features: + +- feat: Add Support for NAP 5 by [@edarzins](https://github.com/edarzins) in [#604](https://github.com/nginx/agent/pull/604) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Fix nfpm.yaml for apk packages by [@dhurley](https://github.com/dhurley) in [#597](https://github.com/nginx/agent/pull/597) +- fix unit test by [@oliveromahony](https://github.com/oliveromahony) in [#607](https://github.com/nginx/agent/pull/607) +- Fix user workflow performance tests by [@dhurley](https://github.com/dhurley) in [#612](https://github.com/nginx/agent/pull/612) +- fix Advanced Metrics by [@aphralG](https://github.com/aphralG) in [#598](https://github.com/nginx/agent/pull/598) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- chore: Add the 2.32.2 Changelog to the docs website by [@Jcahilltorre](https://github.com/Jcahilltorre) in [#601](https://github.com/nginx/agent/pull/601) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Bump the version of protobuf by [@oliveromahony](https://github.com/oliveromahony) in [#602](https://github.com/nginx/agent/pull/602) +- replace duplicate isContainer call by [@oliveromahony](https://github.com/oliveromahony) in [#596](https://github.com/nginx/agent/pull/596) +- Add logging to NGINX API http requests by [@dhurley](https://github.com/dhurley) in [#605](https://github.com/nginx/agent/pull/605) + diff --git a/content/agent/v2/configuration/_index.md b/content/agent/v2/configuration/_index.md new file mode 100644 index 000000000..4429d1349 --- /dev/null +++ b/content/agent/v2/configuration/_index.md @@ -0,0 +1,7 @@ +--- +title: "Configuration" +weight: "400" +url: /nginx-agent/v2/configuration/ +--- + +Learn how to configure NGINX Agent. \ No newline at end of file diff --git a/content/agent/configuration/configuration-overview.md b/content/agent/v2/configuration/configuration-overview.md similarity index 99% rename from content/agent/configuration/configuration-overview.md rename to content/agent/v2/configuration/configuration-overview.md index e82e76246..b5bdd2ef0 100644 --- a/content/agent/configuration/configuration-overview.md +++ b/content/agent/v2/configuration/configuration-overview.md @@ -1,5 +1,5 @@ --- -title: "Basic configuration" +title: "How to configure NGINX Agent" draft: false weight: 100 toc: true diff --git a/content/agent/configuration/configure-nginx-agent-group.md b/content/agent/v2/configuration/configure-nginx-agent-group.md similarity index 98% rename from content/agent/configuration/configure-nginx-agent-group.md rename to content/agent/v2/configuration/configure-nginx-agent-group.md index bb6260daf..45c3e9094 100644 --- a/content/agent/configuration/configure-nginx-agent-group.md +++ b/content/agent/v2/configuration/configure-nginx-agent-group.md @@ -1,5 +1,5 @@ --- -title: "Add NGINX users to nginx-agent Group" +title: "Add NGINX users to nginx-agent group" draft: false weight: 300 toc: true diff --git a/content/agent/configuration/encrypt-communication.md b/content/agent/v2/configuration/encrypt-communication.md similarity index 100% rename from content/agent/configuration/encrypt-communication.md rename to content/agent/v2/configuration/encrypt-communication.md diff --git a/content/agent/configuration/health-checks.md b/content/agent/v2/configuration/health-checks.md similarity index 100% rename from content/agent/configuration/health-checks.md rename to content/agent/v2/configuration/health-checks.md diff --git a/content/agent/installation-upgrade/_index.md b/content/agent/v2/installation-upgrade/_index.md similarity index 76% rename from content/agent/installation-upgrade/_index.md rename to content/agent/v2/installation-upgrade/_index.md index 3ef1ed5bb..8254dffaa 100644 --- a/content/agent/installation-upgrade/_index.md +++ b/content/agent/v2/installation-upgrade/_index.md @@ -3,5 +3,5 @@ title: "Installation and upgrade" description: "Learn how to install, upgrade, and uninstall NGINX Agent." menu: docs weight: 300 -url: /nginx-agent/installation-upgrade/ +url: /nginx-agent/v2/installation-upgrade/ --- \ No newline at end of file diff --git a/content/agent/installation-upgrade/container-environments/_index.md b/content/agent/v2/installation-upgrade/container-environments/_index.md similarity index 66% rename from content/agent/installation-upgrade/container-environments/_index.md rename to content/agent/v2/installation-upgrade/container-environments/_index.md index ae6338d52..6239e21ff 100644 --- a/content/agent/installation-upgrade/container-environments/_index.md +++ b/content/agent/v2/installation-upgrade/container-environments/_index.md @@ -3,5 +3,5 @@ title: "Container environments" description: "Learn how to build and run NGINX Agent docker images." menu: docs weight: 800 -ur: /nginx-agent/installation-upgrade/container-environments/ +url: /nginx-agent/v2/installation-upgrade/container-environments/ --- \ No newline at end of file diff --git a/content/agent/installation-upgrade/container-environments/docker-images.md b/content/agent/v2/installation-upgrade/container-environments/docker-images.md similarity index 98% rename from content/agent/installation-upgrade/container-environments/docker-images.md rename to content/agent/v2/installation-upgrade/container-environments/docker-images.md index 88879d743..5f3a1e48b 100644 --- a/content/agent/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-images.md @@ -114,7 +114,7 @@ docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent docker run --name nginx-agent -d nginx-agent ``` -{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< relref "/agent/configuration/configuration-overview" >}}).{{}} +{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< relref "/agent/v2/configuration/configuration-overview" >}}).{{}} ### Enable the gRPC interface diff --git a/content/agent/installation-upgrade/container-environments/docker-support.md b/content/agent/v2/installation-upgrade/container-environments/docker-support.md similarity index 92% rename from content/agent/installation-upgrade/container-environments/docker-support.md rename to content/agent/v2/installation-upgrade/container-environments/docker-support.md index 6d764a1f0..e4dd2002d 100644 --- a/content/agent/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-support.md @@ -12,7 +12,7 @@ docs: "DOCS-909" ## Overview -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 "/agent/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. +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 "/agent/v2/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 "/agent/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/v2/installation-upgrade/getting-started.md similarity index 98% rename from content/agent/installation-upgrade/getting-started.md rename to content/agent/v2/installation-upgrade/getting-started.md index 222ff2b48..6a1c336a2 100644 --- a/content/agent/installation-upgrade/getting-started.md +++ b/content/agent/v2/installation-upgrade/getting-started.md @@ -177,5 +177,5 @@ NGINX Agent uses formatted log files to collect metrics. Expanding log formats a {{< important >}} Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services. -For more information, see [NGINX Agent Log Rotation]({{< relref "/agent/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). +For more information, see [NGINX Agent Log Rotation]({{< relref "/agent/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). {{< /important >}} diff --git a/content/agent/installation-upgrade/installation-github.md b/content/agent/v2/installation-upgrade/installation-github.md similarity index 100% rename from content/agent/installation-upgrade/installation-github.md rename to content/agent/v2/installation-upgrade/installation-github.md diff --git a/content/agent/installation-upgrade/installation-oss.md b/content/agent/v2/installation-upgrade/installation-oss.md similarity index 100% rename from content/agent/installation-upgrade/installation-oss.md rename to content/agent/v2/installation-upgrade/installation-oss.md diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/v2/installation-upgrade/installation-plus.md similarity index 100% rename from content/agent/installation-upgrade/installation-plus.md rename to content/agent/v2/installation-upgrade/installation-plus.md diff --git a/content/agent/installation-upgrade/uninstall.md b/content/agent/v2/installation-upgrade/uninstall.md similarity index 100% rename from content/agent/installation-upgrade/uninstall.md rename to content/agent/v2/installation-upgrade/uninstall.md diff --git a/content/agent/installation-upgrade/upgrade.md b/content/agent/v2/installation-upgrade/upgrade.md similarity index 100% rename from content/agent/installation-upgrade/upgrade.md rename to content/agent/v2/installation-upgrade/upgrade.md diff --git a/content/agent/v2/technical-specifications.md b/content/agent/v2/technical-specifications.md new file mode 100644 index 000000000..efa731527 --- /dev/null +++ b/content/agent/v2/technical-specifications.md @@ -0,0 +1,54 @@ +--- +title: "Technical specifications" +weight: 100 +toc: true +docs: "DOCS-1092" +--- + +This document describes the requirements for NGINX Agent v2. + +## Supported distributions + +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

9 | 3.16

3.17

3.18

3.19| 2023| LTS| 7.4+| 11

12| +|**Architecture**| x86_84

aarch64| x86_64

aarch64 | x86_64

aarch64 | x86_64

aarch64 | x86_64

aarch64 | x86_64

aarch64 | +{{< /bootstrap-table >}} + +{{< bootstrap-table "table table-striped table-bordered" >}} +| |FreeBSD | Oracle Linux | Red Hat
Enterprise Linux
(RHEL) | Rocky Linux | SUSE Linux
Enterprise Server
(SLES) | Ubuntu | +|-|--------|--------------|---------------------------------|-------------|-------------------------------------|--------| +|**Version**|13

14|7.4+

8.1+

9|7.4+

8.1+

9.0+|8

9|12 SP5

15 SP2|20.04 LTS

22.04 LTS| +|**Architecture**|amd64|x86_64|x86_64

aarch64|x86_64

aarch64|x86_64|x86_64

aarch64| +{{< /bootstrap-table >}} + + +## Supported deployment environments + +NGINX Agent can be deployed in the following environments: + +- Bare Metal +- Container +- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure +- Virtual Machine + +## Supported NGINX versions + +NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. + + +## 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). \ No newline at end of file diff --git a/content/includes/agent/installation/manually-connect-to-console.md b/content/includes/agent/installation/manually-connect-to-console.md new file mode 100644 index 000000000..27d22d2e9 --- /dev/null +++ b/content/includes/agent/installation/manually-connect-to-console.md @@ -0,0 +1,23 @@ +If you have installed NGINX Agent manually, you will need to connect it to the +NGINX One Console to manage your NGINX instances. + +1. Ensure NGINX Agent is installed +1. Locate the NGINX Agent Configuration File: + + ```shell + /etc/nginx-agent/nginx-agent.conf + ``` + +1. Open the NGINX Agent configuration file in a text editor like vim: + + ```shell + sudo vim /etc/nginx-agent/nginx-agent.conf + ``` + +1. Uncomment the command block, and set the token to your data plane key +1. Save the changes and close the editor +1. Restart the NGINX Agent service: + + ```shell + sudo systemctl stop nginx-agent + ``` \ No newline at end of file diff --git a/go.mod b/go.mod index 573590eee..96da5bb32 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v0.42.1 // indirect \ No newline at end of file +require github.com/nginxinc/nginx-hugo-theme v0.42.24 // indirect diff --git a/go.sum b/go.sum index 0b0801e9a..55949eecc 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,6 @@ -github.com/nginxinc/nginx-hugo-theme v0.42.1 h1:SYj7R7fKPYwtbQobTcJWy/ZWQxa5tlHCSJfU2dxYXxY= -github.com/nginxinc/nginx-hugo-theme v0.42.1/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.41.22 h1:Gb/OLbpumNqp8vOPkZzO2GmgPDRd1yr2tWHWUBHg8BA= +github.com/nginxinc/nginx-hugo-theme v0.41.22/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.41.27 h1:M8ttO1ZkTGY06o0MYvnm3kc/sA6lOmIjVA3tF3cAses= +github.com/nginxinc/nginx-hugo-theme v0.41.27/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.24 h1:aQkkTob0EpK+1ID+31E3y+RIdThldC4HgA2LcJL4TXU= +github.com/nginxinc/nginx-hugo-theme v0.42.24/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= diff --git a/layouts/agent-v2-migration/list.html b/layouts/agent-v2-migration/list.html new file mode 100644 index 000000000..54b0b0f66 --- /dev/null +++ b/layouts/agent-v2-migration/list.html @@ -0,0 +1,10 @@ +{{ define "main" }} +
+ +
+ {{ partial "agent-v2-migration/list-main" . }} +
+
+{{ end }} \ No newline at end of file diff --git a/layouts/agent-v2-migration/single.html b/layouts/agent-v2-migration/single.html new file mode 100644 index 000000000..e91863080 --- /dev/null +++ b/layouts/agent-v2-migration/single.html @@ -0,0 +1,49 @@ +{{ define "main" }} +
+ + + {{if (.Params.catalog) }} +
+ {{ else if and (gt .WordCount 200 ) (.Params.toc) }} +
+ {{ else }} +
+ {{ end }} + +
+
+ NGINX Agent v3 is available!

+ This documentation is for NGINX Agent v2. We suggest reading the Migrate from NGINX Agent v2 to v3 topic to learn the differences between the two versions, and learn how to upgrade your instances. +
+
+ +

{{ .Title }}

+ + {{ if eq .Page.Draft true }}{{ partial "draft-badge.html" . }}{{ end }} + {{ if .Description }}

{{ .Description | markdownify }}

{{ end}} + + {{ if in .Params.doctypes "beta" }}{{ partial "beta-badge" . }}{{ end }} + + {{ .Content }} + {{ partial "version-list" . }} +
+ {{ partial "previous-next-links-in-section-with-title.html" . }} + +
+ {{ if and (gt .WordCount 200 ) (.Params.toc) }} + {{ if (add (len (findRE " + {{ partial "toc.html" . }} +
+ {{ end }} + {{ end }} + + +{{if .Params.script}} + {{ $script := (delimit (slice "scripts" .Params.script) "/")}} + {{ partial (string $script) .}} +{{end }} + +{{ end }} \ No newline at end of file diff --git a/layouts/partials/agent-v2-migration/list-main.html b/layouts/partials/agent-v2-migration/list-main.html new file mode 100644 index 000000000..51c39a214 --- /dev/null +++ b/layouts/partials/agent-v2-migration/list-main.html @@ -0,0 +1,53 @@ +
+
+ +
+ +
+
+
+ {{ range .Pages.GroupBy "Section" }} + + {{ range .Pages.ByWeight }} +
+
+

+ + {{ .Title }} +

+ {{/*}}

+ {{ if .Description }}{{ .Description | markdownify }}{{ end }} +

{{*/}} + +
+
+ + {{ end }} +
+
+ {{ end }} + + +
+ +
\ No newline at end of file diff --git a/layouts/shortcodes/v2-metrics.html b/layouts/shortcodes/v2-metrics.html new file mode 100644 index 000000000..dc14d9a35 --- /dev/null +++ b/layouts/shortcodes/v2-metrics.html @@ -0,0 +1,56 @@ +
+ {{ range .Site.Data.v2metrics }} + +

{{.name}} + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
description{{.description}}
type{{.type}}
categories{{.categories}}
source{{.source}}
rollup_aggregate{{.rollup_aggregate}}
unit{{.unit}}
aggregations + {{ range .aggregations }} + {{ . }}; + {{end}} +
dimensions + {{ range sort .dimensions }} +
  • + {{ . }} +
  • + {{end}} +
    +
    + {{ end }} +
    \ No newline at end of file