From ef2a885da5ce2d059ffe9fb51ff456ee543a0376 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 10 Feb 2025 17:24:01 +0000 Subject: [PATCH 01/63] docs: transfer v3 Docs to public repo --- content/agent/_index.md | 13 +- content/agent/{overview.md => about.md} | 46 +- content/agent/changelog.md | 276 +----- content/agent/configuration/_index.md | 8 - .../configure-nginx-agent-features.md | 95 --- content/agent/contribute/_index.md | 10 +- content/agent/contribute/community.md | 10 +- .../agent/contribute/dev-environment-setup.md | 54 +- .../agent/contribute/start-mock-interface.md | 90 ++ content/agent/how-to/_index.md | 6 + .../agent/how-to/configuration-overview.md | 290 +++++++ content/agent/how-to/configure-agent-group.md | 87 ++ .../agent/how-to/connect-management-plane.md | 114 +++ content/agent/how-to/enable-interfaces.md | 73 ++ content/agent/how-to/encrypt-communication.md | 126 +++ content/agent/how-to/export-metrics.md | 45 + content/agent/install-upgrade/_index.md | 6 + content/agent/install-upgrade/install.md | 784 ++++++++++++++++++ content/agent/install-upgrade/migrate-v3.md | 44 + content/agent/install-upgrade/uninstall.md | 145 ++++ content/agent/install-upgrade/upgrade.md | 78 ++ content/agent/otel/_index.md | 4 + content/agent/otel/metrics.md | 5 + content/agent/support.md | 15 + content/agent/technical-specifications.md | 34 +- content/agent/v2/_index.md | 7 + content/agent/v2/changelog.md | 282 +++++++ content/agent/v2/configuration/_index.md | 6 + .../configuration/configuration-overview.md | 2 +- .../configure-nginx-agent-group.md | 2 +- .../configuration/encrypt-communication.md | 0 .../{ => v2}/configuration/health-checks.md | 0 .../{ => v2}/installation-upgrade/_index.md | 1 - .../container-environments/_index.md | 1 - .../container-environments/docker-images.md | 4 +- .../container-environments/docker-support.md | 4 +- .../installation-upgrade/getting-started.md | 2 +- .../installation-github.md | 0 .../installation-upgrade/installation-oss.md | 2 +- .../installation-upgrade/installation-plus.md | 2 +- .../installation-upgrade/uninstall.md | 0 .../{ => v2}/installation-upgrade/upgrade.md | 0 content/agent/v2/metrics.md | 10 + content/agent/v2/technical-specifications.md | 54 ++ 44 files changed, 2368 insertions(+), 469 deletions(-) rename content/agent/{overview.md => about.md} (67%) delete mode 100644 content/agent/configuration/_index.md delete mode 100644 content/agent/configuration/configure-nginx-agent-features.md create mode 100644 content/agent/contribute/start-mock-interface.md create mode 100644 content/agent/how-to/_index.md create mode 100644 content/agent/how-to/configuration-overview.md create mode 100644 content/agent/how-to/configure-agent-group.md create mode 100644 content/agent/how-to/connect-management-plane.md create mode 100644 content/agent/how-to/enable-interfaces.md create mode 100644 content/agent/how-to/encrypt-communication.md create mode 100644 content/agent/how-to/export-metrics.md create mode 100644 content/agent/install-upgrade/_index.md create mode 100644 content/agent/install-upgrade/install.md create mode 100644 content/agent/install-upgrade/migrate-v3.md create mode 100644 content/agent/install-upgrade/uninstall.md create mode 100644 content/agent/install-upgrade/upgrade.md create mode 100644 content/agent/otel/_index.md create mode 100644 content/agent/otel/metrics.md create mode 100644 content/agent/support.md create mode 100644 content/agent/v2/_index.md create mode 100644 content/agent/v2/changelog.md create mode 100644 content/agent/v2/configuration/_index.md rename content/agent/{ => v2}/configuration/configuration-overview.md (99%) rename content/agent/{ => v2}/configuration/configure-nginx-agent-group.md (98%) rename content/agent/{ => v2}/configuration/encrypt-communication.md (100%) rename content/agent/{ => v2}/configuration/health-checks.md (100%) rename content/agent/{ => v2}/installation-upgrade/_index.md (77%) rename content/agent/{ => v2}/installation-upgrade/container-environments/_index.md (67%) rename content/agent/{ => v2}/installation-upgrade/container-environments/docker-images.md (98%) rename content/agent/{ => v2}/installation-upgrade/container-environments/docker-support.md (87%) rename content/agent/{ => v2}/installation-upgrade/getting-started.md (98%) rename content/agent/{ => v2}/installation-upgrade/installation-github.md (100%) rename content/agent/{ => v2}/installation-upgrade/installation-oss.md (99%) rename content/agent/{ => v2}/installation-upgrade/installation-plus.md (99%) rename content/agent/{ => v2}/installation-upgrade/uninstall.md (100%) rename content/agent/{ => v2}/installation-upgrade/upgrade.md (100%) create mode 100644 content/agent/v2/metrics.md create mode 100644 content/agent/v2/technical-specifications.md diff --git a/content/agent/_index.md b/content/agent/_index.md index 95b9e6b1b..b3764d916 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -1,9 +1,6 @@ --- -title: "NGINX Agent" -description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance." -linkTitle: "NGINX Agent" -menu: docs -url: /nginx-agent/ -cascade: - logo: "NGINX-product-icon.png" ---- \ No newline at end of file +title: "NGINX Agent Documentation" +weight: 900 +--- + +NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance \ No newline at end of file diff --git a/content/agent/overview.md b/content/agent/about.md similarity index 67% rename from content/agent/overview.md rename to content/agent/about.md index ea9e92ddd..a793c0264 100644 --- a/content/agent/overview.md +++ b/content/agent/about.md @@ -1,53 +1,67 @@ --- title: "Overview" -draft: false weight: 100 toc: true -tags: [ "docs" ] -docs: "DOCS-1091" -categories: ["configuration"] -doctypes: ["task"] +docs: DOCS-000 --- -## 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 +[OpenTelemetry](https://opentelemetry.io/) support comes with NGINX Agent v3, and the ability to [export the metrics data]({{< relref "/how-to/export-metrics.md" >}}) for use in other applications. + +For an overview of the metrics available from NGINX Agent, read the following topics: + +- [OpenTelemetry metrics]({{< relref "/otel/metrics.md" >}}) (Agent v3) +- [Metrics]({{< relref "/v2/metrics.md" >}}) (Agent v2) -{{< 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 +{{< img src="grafana-dashboard-example.png" caption="A Grafana dashboard displaying metrics reported by NGINX Agent." alt="A Grafana dashboard displaying metrics reported by NGINX Agent.">}} + +--- -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. +## How it works -{{< img src="agent/agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} +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. -## Configuration Management +{{< img src="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 +For additional information, view the [Configuration overview]({{< relref "/how-to/configuration-overview.md" >}}) topic. + +--- + +## 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. +For NGINX Agent to work properly with an NGINX Plus instance, the API needs to be configured in that instance's nginx.conf. View the [Instance Metrics Overview](https://docs.nginx.com/nginx-management-suite/nim/about/overview-metrics/) topic for more details. Once NGINX Plus is configured with the `/api/` endpoint, the Agent will automatically use it on startup. + +--- -## Event Notifications +## 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 | diff --git a/content/agent/changelog.md b/content/agent/changelog.md index 448786e83..07f23553f 100644 --- a/content/agent/changelog.md +++ b/content/agent/changelog.md @@ -1,282 +1,12 @@ --- 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 "/agent/technical-specifications.md" >}}). +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) - +## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.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..9eebf5403 100644 --- a/content/agent/contribute/_index.md +++ b/content/agent/contribute/_index.md @@ -1,8 +1,6 @@ --- title: "Contribute" -description: "Learn about the NGINX Agent community and contribute to the project." -linkTitle: "Contribute" -menu: docs -weight: "500" -url: /nginx-agent/contribute/ ---- \ No newline at end of file +weight: 600 +--- + +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..d56c064cb 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]({{< ref "/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 "/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..2c148de78 --- /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]({{< ref "/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 "/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..3f01dc82b --- /dev/null +++ b/content/agent/how-to/_index.md @@ -0,0 +1,6 @@ +--- +title: "How-to guides" +weight: 500 +--- + +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..26c2a41b2 --- /dev/null +++ b/content/agent/how-to/configuration-overview.md @@ -0,0 +1,290 @@ +--- +title: "Configuration overview" +toc: true +weight: 100 +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 files + +The default locations of configuration files for NGINX Agent are `/etc/nginx-agent/nginx-agent.conf` and `/var/lib/nginx-agent/agent-dynamic.conf`. The `agent-dynamic.conf` file default location is different for FreeBSD which is located `/var/db/nginx-agent/agent-dynamic.conf`. These files have comments at the top indicating their purpose. + +Examples of the configuration files are provided below: + +
+ example nginx-agent.conf + +{{}} +In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane. +{{}} + +```nginx {hl_lines=[13]} +# +# /etc/nginx-agent/nginx-agent.conf +# +# Configuration file for NGINX Agent. +# +# This file tracks agent configuration values that are meant to be statically set. There +# are additional NGINX Agent configuration values that are set via the API and agent install script +# which can be found in /etc/nginx-agent/agent-dynamic.conf. + +# specify the server grpc port to connect to +server: + # host of the control plane + host: + grpcPort: 443 + backoff: # note: default values are prepopulated + initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour + randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 + multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 + max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour + max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour +# tls options +tls: + # enable tls in the nginx-agent setup for grpcs + # default to enable to connect with secure connection but without client cert for mtls + enable: true + # controls whether the server certificate chain and host name are verified. + # for production use, see instructions for configuring TLS + skip_verify: false +log: + # set log level (panic, fatal, error, info, debug, trace; default "info") + level: info + # set log path. if empty, don't log to file. + path: /var/log/nginx-agent/ +nginx: + # path of NGINX logs to exclude + exclude_logs: "" + # Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check) + treat_warnings_as_errors: false # Default is false +# data plane status message / 'heartbeat' +dataplane: + status: + # poll interval for dataplane status - the frequency the NGINX Agent will query the dataplane for changes + poll_interval: 30s + # report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed + report_interval: 24h +metrics: + # specify the size of a buffer to build before sending metrics + bulk_size: 20 + # specify metrics poll interval + report_interval: 1m + collection_interval: 15s + mode: aggregated + backoff: # note: default values are prepopulated + initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour + randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 + multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 + max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour + max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour + +# OSS NGINX default config path +# path to aux file dirs can also be added +config_dirs: "/etc/nginx:/usr/local/etc/nginx" + +# Internal queue size +queue_size: 100 + +extensions: + - nginx-app-protect + +# Enable reporting NGINX App Protect details to the control plane. +nginx_app_protect: + # Report interval for NGINX App Protect details - the frequency NGINX Agent checks NGINX App Protect for changes. + report_interval: 15s + # Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false). + precompiled_publication: true +``` + +
+ + +
+ example dynamic-agent.conf + +{{}} +Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` + +Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` +{{}} + +```yaml +# Dynamic configuration file for NGINX Agent. +# +# The purpose of this file is to track agent configuration +# values that can be dynamically changed via the API and the agent install script. +# You may edit this file, but API calls that modify the tags on this system will +# overwrite the tag values in this file. +# +# The agent configuration values that API calls can modify are as follows: +# tags: +# - dev +# - qa +# +# The agent configuration value that the agent install script can modify are as follows: +# instance_group: my-instance-group + +instance_group: my-instance-group +tags: + - dev + - qa +``` + +
+ +## CLI flags and environment variables + +This section details the CLI flags and corresponding environment variables used to configure the NGINX Agent. + +### CLI flags + +```sh +nginx-agent [flags] +``` + +### Environment variables + +```sh +export ENV_VARIABLE_NAME="value" +nginx-agent +``` + +### Flag and environment arguments + +{{< warning >}} + +Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`. + +If you are upgrading from an older version, update your configuration accordingly. + +{{< /warning >}} + +{{}} +| CLI flag | Environment variable | Description | +|---------------------------------------------|--------------------------------------|-----------------------------------------------------------------------------| +| `--api-cert` | `NGINX_AGENT_API_CERT` | Specifies the certificate used by the Agent API. | +| `--api-host` | `NGINX_AGENT_API_HOST` | Sets the host used by the Agent API. Default: *127.0.0.1* | +| `--api-key` | `NGINX_AGENT_API_KEY` | Specifies the key used by the Agent API. | +| `--api-port` | `NGINX_AGENT_API_PORT` | Sets the port for exposing nginx-agent to HTTP traffic. | +| `--config-dirs` | `NGINX_AGENT_CONFIG_DIRS` | Defines directories NGINX Agent can read/write. Default: *"/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms"* | +| `--dataplane-report-interval` | `NGINX_AGENT_DATAPLANE_REPORT_INTERVAL` | Sets the interval for dataplane reporting. Default: *24h0m0s* | +| `--dataplane-status-poll-interval` | `NGINX_AGENT_DATAPLANE_STATUS_POLL_INTERVAL` | Sets the interval for polling dataplane status. Default: *30s* | +| `--display-name` | `NGINX_AGENT_DISPLAY_NAME` | Sets the instance's display name. | +| `--dynamic-config-path` | `NGINX_AGENT_DYNAMIC_CONFIG_PATH` | Specifies the path of the Agent dynamic config file. Default: *"/var/lib/nginx-agent/agent-dynamic.conf"* | +| `--features` | `NGINX_AGENT_FEATURES` | Specifies a comma-separated list of features enabled for the agent. Default: *[registration, nginx-config-async, nginx-ssl-config, nginx-counting, metrics, dataplane-status, process-watcher, file-watcher, activity-events, agent-api]* | +| `--ignore-directives` | | Specifies a comma-separated list of directives to ignore for sensitive info.| +| `--instance-group` | `NGINX_AGENT_INSTANCE_GROUP` | Sets the instance's group value. | +| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (e.g., panic, fatal, error, info, debug, trace). Default: *info* | +| `--log-path` | `NGINX_AGENT_LOG_PATH` | Specifies the path to output log messages. | +| `--metrics-bulk-size` | `NGINX_AGENT_METRICS_BULK_SIZE` | Specifies the number of metrics reports collected before sending data. Default: *20* | +| `--metrics-collection-interval` | `NGINX_AGENT_METRICS_COLLECTION_INTERVAL` | Sets the interval for metrics collection. Default: *15s* | +| `--metrics-mode` | `NGINX_AGENT_METRICS_MODE` | Sets the metrics collection mode: streaming or aggregation. Default: *aggregated* | +| `--metrics-report-interval` | `NGINX_AGENT_METRICS_REPORT_INTERVAL` | Sets the interval for reporting collected metrics. Default: *1m0s* | +| `--nginx-config-reload-monitoring-period` | | Sets the duration to monitor error logs after an NGINX reload. Default: *10s* | +| `--nginx-exclude-logs` | `NGINX_AGENT_NGINX_EXCLUDE_LOGS` | Specifies paths of NGINX access logs to exclude from metrics collection. | +| `--nginx-socket` | `NGINX_AGENT_NGINX_SOCKET` | Specifies the location of the NGINX Plus counting Unix socket. Default: *unix:/var/run/nginx-agent/nginx.sock* | +| `--nginx-treat-warnings-as-errors` | `NGINX_AGENT_NGINX_TREAT_WARNINGS_AS_ERRORS` | Treats warnings as failures on configuration application. | +| `--queue-size` | `NGINX_AGENT_QUEUE_SIZE` | Specifies the size of the NGINX Agent internal queue. | +| `--server-command` | | Specifies the name of the command server sent in the TLS configuration. | +| `--server-grpcport` | `NGINX_AGENT_SERVER_GRPCPORT` | Sets the desired GRPC port for NGINX Agent traffic. | +| `--server-host` | `NGINX_AGENT_SERVER_HOST` | Specifies the IP address of the server host. | +| `--server-metrics` | | Specifies the name of the metrics server sent in the TLS configuration. | +| `--server-token` | `NGINX_AGENT_SERVER_TOKEN` | Sets the authentication token for accessing the commander and metrics services. Default: *e202f883-54c6-4702-be15-3ba6e507879a* | +| `--tags` | `NGINX_AGENT_TAGS` | Specifies a comma-separated list of tags for the instance or machine. | +| `--tls-ca` | `NGINX_AGENT_TLS_CA` | Specifies the path to the CA certificate file for TLS. | +| `--tls-cert` | `NGINX_AGENT_TLS_CERT` | Specifies the path to the certificate file for TLS. | +| `--tls-enable` | `NGINX_AGENT_TLS_ENABLE` | Enables TLS for secure communications. | +| `--tls-key` | `NGINX_AGENT_TLS_KEY` | Specifies the path to the certificate key file for TLS. | +| `--tls-skip-verify` | `NGINX_AGENT_TLS_SKIP_VERIFY` | Insecurely skips verification for gRPC TLS credentials. | +{{}} + +
+ +{{}} +Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories NGINX Agent can read from or write to. This setting also defines the location to which you can upload config files when using a control plane. + +NGINX Agent cannot write to directories outside the specified location when updating a config and cannot upload files to directories outside of the configured location. + +NGINX Agent follows NGINX configuration directives to file paths outside the designated directories and reads certificates' metadata. NGINX Agent uses the following directives: + +- [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) + +{{}} + +{{}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location. + +Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` + +Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` + +{{}} + +## Logs + +NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. + +We recommend adding a separate partition for `/var/log/nginx-agent`. + +{{< 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. +{{< /important >}} + +By default, NGINX Agent rotates logs daily using logrotate with the following configuration: + +
+ NGINX Agent Logrotate Configuration + +``` yaml +/var/log/nginx-agent/*.log +{ + # log files are rotated every day + daily + # log files are rotated if they grow bigger than 5M + size 5M + # truncate the original log file after creating a copy + copytruncate + # remove rotated logs older than 10 days + maxage 10 + # log files are rotated 10 times before being removed + rotate 10 + # old log files are compressed + compress + # if the log file is missing it will go on to the next one without issuing an error message + missingok + # do not rotate the log if it is empty + notifempty +} +``` +
+ +If you need to change the default configuration, update the file at `/etc/logrotate.d/nginx-agent`. + +For more details on logrotate configuration, see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate). + + +## Extensions + +An extension is noncritical code to the main functionality of NGINX Agent. They generally cover functionality outside of managing NGINX configuration and reporting metrics. + +To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. + +This example enables the advanced metrics extension: + +```yaml +extensions: + - advanced-metrics +``` \ No newline at end of file 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..c73557165 --- /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 "/contribute/start-mock-interface.md" >}}) topic to test NGINX Agent, or view the [Configuration overview]({{< relref "/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..96bf7648d --- /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]({{< ref "/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]({{< ref "/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..db1eae8ab --- /dev/null +++ b/content/agent/install-upgrade/_index.md @@ -0,0 +1,6 @@ +--- +title: "Install and upgrade" +weight: 400 +--- + +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..95f651468 --- /dev/null +++ b/content/agent/install-upgrade/install.md @@ -0,0 +1,784 @@ +--- +title: Install NGINX Agent +toc: true +weight: 100 +docs: DOCS-000 +--- + +This document describes the three main ways to install F5 NGINX agent: + +- Using the NGINX Open Source repository +- Using the NGINX Plus repository +- Using the GitHub package files + +## Before you begin + +There are a few prerequisites shared between all installation methods: + +- A [supported operating system and architecture](../technical-specifications/#supported-distributions) +- `root` privilege + +## NGINX Open Source repository + +Before you install NGINX Agent, you must install and run NGINX. + +If you don't have it installed already, read the [Installing NGINX Open Source +](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) topic. + + +### Configure NGINX OSS Repository for installing NGINX Agent + +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. + +- [Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#install-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) +- [Install NGINX Agent on Ubuntu](#install-nginx-agent-on-ubuntu) +- [Install NGINX Agent on Debian](#install-nginx-agent-on-debian) +- [Install NGINX Agent on SLES](#install-nginx-agent-on-sles) +- [Install NGINX Agent on Alpine Linux](#install-nginx-agent-on-alpine-linux) +- [Install NGINX Agent on Amazon Linux](#install-nginx-agent-on-amazon-linux) +- [Install NGINX Agent on FreeBSD](#install-nginx-agent-on-freebsd) + +#### 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 the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ``` + [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. + +#### 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 could 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 + ``` + +#### 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 could 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 + ``` + +#### 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 + ``` + +#### 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 + ``` + +#### 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 the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + ``` + [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. + +#### Install NGINX Agent on FreeBSD + +1. To setup the pkg repository create the file named `/etc/pkg/nginx-agent.conf` with the following content: + + ``` + 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 + ``` + +## NGINX Plus repository + +Before you install NGINX Agent, you must install and run NGINX Plus. + +If you don’t have it installed already, read the [Installing NGINX Plus +](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) topic. + +You will also need the following: + +- Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. +- An NGINX Plus subscription (Full or trial) +- Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. + +### Configure NGINX Plus Repository for installing NGINX Agent + +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. + +- [Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#install-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) +- [Install NGINX Agent on Ubuntu](#install-nginx-agent-on-ubuntu) +- [Install NGINX Agent on Debian](#install-nginx-agent-on-debian) +- [Install NGINX Agent on SLES](#install-nginx-agent-on-sles) +- [Install NGINX Agent on Alpine Linux](#install-nginx-agent-on-alpine-linux) +- [Install NGINX Agent on Amazon Linux](#install-nginx-agent-on-amazon-linux) +- [Install NGINX Agent on FreeBSD](#install-nginx-agent-on-freebsd) + +#### 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`: + + ``` + [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. + +#### 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`: + + ``` + 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 + ``` + +#### 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`: + + ``` + 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 + ``` + +#### 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: + + ``` + 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 + ``` + +#### 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: + + ``` + 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 + ``` + +#### 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 the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ``` + [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. + +#### 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 the file named `/etc/pkg/nginx-agent.conf` with the following content: + + ``` + 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: + + ``` + 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 + ``` + +## GitHub package files + +To install NGINX Agent on your system, 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 + ``` + +## systemd environments + +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 +``` + +## 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 nginx-agent -v +``` + +## Enable interfaces + +Once NGINX Agent is successfully running, you can enable the required interfaces, which is described in the [Enable gRPC and REST interfaces]({{< relref "/how-to/enable-interfaces.md" >}}) topic. + +You may also be interested in the [Start mock control plane interface]({{< relref "/contribute/start-mock-interface.md" >}}) topic for development work. \ No newline at end of file diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/agent/install-upgrade/migrate-v3.md new file mode 100644 index 000000000..86646208e --- /dev/null +++ b/content/agent/install-upgrade/migrate-v3.md @@ -0,0 +1,44 @@ +--- +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. + +[//]: # "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]({{< ref "/install-upgrade/install.md" >}}). +- +- + +--- + +## Migrate from NGINX Agent v2 to v3 + + +--- + +## See also + +[//]: # "Examples of additional topics users might want to read include:" +[//]: # "Relevant reference information, configuration options and more complex use cases." + +- +- 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..9898dcd10 --- /dev/null +++ b/content/agent/otel/_index.md @@ -0,0 +1,4 @@ +--- +title: OpenTelemetry +weight: 450 +--- \ 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/support.md b/content/agent/support.md new file mode 100644 index 000000000..0c7fff1bf --- /dev/null +++ b/content/agent/support.md @@ -0,0 +1,15 @@ +--- +title: Support +weight: 800 +docs: DOCS-000 +--- + +## 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). \ No newline at end of file diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index a17b9fe9f..fac11fbdc 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -1,38 +1,34 @@ --- title: "Technical specifications" -draft: false -weight: 200 toc: true -tags: [ "docs" ] -docs: "DOCS-1092" -categories: ["development"] -doctypes: ["task"] +weight: 200 +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 provides technical specifications for F5 NGINX Agent. It includes information on supported distributions, deployment environments, NGINX versions, sizing recommendations, and logging. -## Supported Distributions +## 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 | +| | 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|8.1+
9|8.1+
9.0+|8
9|12 SP5
15 SP2|20.04 LTS
22.04 LTS
24.04 LTS| +|**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 +## Supported deployment environments NGINX Agent can be deployed in the following environments: @@ -41,12 +37,12 @@ NGINX Agent can be deployed in the following environments: - Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure - Virtual Machine -## Supported NGINX Versions +## Supported NGINX versions NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. -## Sizing Recommendations +## Sizing recommendations Minimum system sizing recommendations for NGINX Agent: {{< bootstrap-table "table table-striped table-bordered" >}} @@ -57,4 +53,8 @@ Minimum system sizing recommendations for NGINX Agent: ## 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 +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). + +More information is available in the [Configuration overview]({{< ref "/how-to/configuration-overview.md#logs" >}}) \ No newline at end of file diff --git a/content/agent/v2/_index.md b/content/agent/v2/_index.md new file mode 100644 index 000000000..f0138d948 --- /dev/null +++ b/content/agent/v2/_index.md @@ -0,0 +1,7 @@ +--- +title: "NGINX Agent v2" +description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance." +weight: 900 +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..cd9db7e49 --- /dev/null +++ b/content/agent/v2/configuration/_index.md @@ -0,0 +1,6 @@ +--- +title: "Configuration" +weight: "400" +--- + +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 77% rename from content/agent/installation-upgrade/_index.md rename to content/agent/v2/installation-upgrade/_index.md index 3ef1ed5bb..4c3d49899 100644 --- a/content/agent/installation-upgrade/_index.md +++ b/content/agent/v2/installation-upgrade/_index.md @@ -3,5 +3,4 @@ title: "Installation and upgrade" description: "Learn how to install, upgrade, and uninstall NGINX Agent." menu: docs weight: 300 -url: /nginx-agent/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 67% rename from content/agent/installation-upgrade/container-environments/_index.md rename to content/agent/v2/installation-upgrade/container-environments/_index.md index ae6338d52..ca964e34b 100644 --- a/content/agent/installation-upgrade/container-environments/_index.md +++ b/content/agent/v2/installation-upgrade/container-environments/_index.md @@ -3,5 +3,4 @@ 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/ --- \ 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..40b3a3b2f 100644 --- a/content/agent/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-images.md @@ -15,7 +15,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. -See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "/agent/technical-specifications.md" >}}) topic. +See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "technical-specifications.md" >}}) topic. ## Deploy Offical NGINX and NGINX Plus Containers @@ -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 "/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 87% 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..b0bdd98a6 100644 --- a/content/agent/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-support.md @@ -12,9 +12,9 @@ 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 "/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. +See the [Technical Specifications]({{< relref "/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. NGINX Agent running in a container has some limitations that need to be considered, and are listed below. 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..578037f53 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 "/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 99% rename from content/agent/installation-upgrade/installation-oss.md rename to content/agent/v2/installation-upgrade/installation-oss.md index cf24dd1a6..5e82dd21b 100644 --- a/content/agent/installation-upgrade/installation-oss.md +++ b/content/agent/v2/installation-upgrade/installation-oss.md @@ -16,7 +16,7 @@ Learn how to install NGINX Agent from the NGINX Open Source repository. ## Prerequisites - NGINX installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) -- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< relref "/technical-specifications.md#supported-distributions" >}}) - `root` privilege ## Configure NGINX OSS Repository for installing NGINX Agent diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/v2/installation-upgrade/installation-plus.md similarity index 99% rename from content/agent/installation-upgrade/installation-plus.md rename to content/agent/v2/installation-upgrade/installation-plus.md index fe77bbb58..ba4250210 100644 --- a/content/agent/installation-upgrade/installation-plus.md +++ b/content/agent/v2/installation-upgrade/installation-plus.md @@ -17,7 +17,7 @@ Learn how to install NGINX Agent from NGINX Plus repository - An NGINX Plus subscription (purchased or trial) - NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) -- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< relref "/technical-specifications.md#supported-distributions" >}}) - `root` privilege - Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. - Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. 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/metrics.md b/content/agent/v2/metrics.md new file mode 100644 index 000000000..e90e55c93 --- /dev/null +++ b/content/agent/v2/metrics.md @@ -0,0 +1,10 @@ +--- +title: Metrics +catalog: true +catalogType: v2metrics +toc: true +weight: 200 +docs: DOCS-000 +--- + +{{< v2-metrics >}} \ No newline at end of file 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 From ece7ce33ec4f0ced6331214c9140e7625d33848d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 12 Feb 2025 11:44:53 +0000 Subject: [PATCH 02/63] fix: fix broken links in v3 docs - theme bump --- content/agent/about.md | 8 +- .../agent/contribute/dev-environment-setup.md | 6 +- .../agent/contribute/start-mock-interface.md | 6 +- content/agent/how-to/enable-interfaces.md | 4 +- content/agent/how-to/export-metrics.md | 4 +- content/agent/install-upgrade/install.md | 8 +- content/agent/install-upgrade/migrate-v3.md | 2 +- .../container-environments/docker-images.md | 220 ++++++++ .../container-environments/docker-support.md | 83 +++ .../installation-upgrade/getting-started.md | 179 ++++++ .../installation-upgrade/installation-plus.md | 511 ++++++++++++++++++ content/agent/technical-specifications.md | 4 +- .../container-environments/docker-images.md | 4 +- .../container-environments/docker-support.md | 4 +- .../installation-upgrade/getting-started.md | 2 +- .../installation-upgrade/installation-oss.md | 2 +- .../installation-upgrade/installation-plus.md | 2 +- go.mod | 2 +- go.sum | 2 + layouts/agent-v2-migration/list.html | 10 + layouts/agent-v2-migration/single.html | 49 ++ .../agent-v2-migration/list-main.html | 53 ++ layouts/shortcodes/v2-metrics.html | 56 ++ 23 files changed, 1192 insertions(+), 29 deletions(-) create mode 100644 content/agent/installation-upgrade/container-environments/docker-images.md create mode 100644 content/agent/installation-upgrade/container-environments/docker-support.md create mode 100644 content/agent/installation-upgrade/getting-started.md create mode 100644 content/agent/installation-upgrade/installation-plus.md create mode 100644 layouts/agent-v2-migration/list.html create mode 100644 layouts/agent-v2-migration/single.html create mode 100644 layouts/partials/agent-v2-migration/list-main.html create mode 100644 layouts/shortcodes/v2-metrics.html diff --git a/content/agent/about.md b/content/agent/about.md index a793c0264..45af5aaba 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -11,12 +11,12 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta - Collection and reporting of real-time NGINX performance and operating system metrics - Notifications of NGINX events -[OpenTelemetry](https://opentelemetry.io/) support comes with NGINX Agent v3, and the ability to [export the metrics data]({{< relref "/how-to/export-metrics.md" >}}) for use in other applications. +[OpenTelemetry](https://opentelemetry.io/) support comes with NGINX Agent v3, and the ability to [export the metrics data]({{< relref "/agent/how-to/export-metrics.md" >}}) for use in other applications. For an overview of the metrics available from NGINX Agent, read the following topics: -- [OpenTelemetry metrics]({{< relref "/otel/metrics.md" >}}) (Agent v3) -- [Metrics]({{< relref "/v2/metrics.md" >}}) (Agent v2) +- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) (Agent v3) +- [Metrics]({{< relref "/agent/v2/metrics.md" >}}) (Agent v2) {{< img src="grafana-dashboard-example.png" caption="A Grafana dashboard displaying metrics reported by NGINX Agent." alt="A Grafana dashboard displaying metrics reported by NGINX Agent.">}} @@ -36,7 +36,7 @@ NGINX Agent enables remote interaction with NGINX using common Linux tools and u 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. -For additional information, view the [Configuration overview]({{< relref "/how-to/configuration-overview.md" >}}) topic. +For additional information, view the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md" >}}) topic. --- diff --git a/content/agent/contribute/dev-environment-setup.md b/content/agent/contribute/dev-environment-setup.md index d56c064cb..2e9fe571c 100644 --- a/content/agent/contribute/dev-environment-setup.md +++ b/content/agent/contribute/dev-environment-setup.md @@ -9,7 +9,7 @@ docs: DOCS-000 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. +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. @@ -17,7 +17,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). +- 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. @@ -29,7 +29,7 @@ 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 -Follow the steps in the [Installation]({{< relref "/install-upgrade/install.md" >}}) topic to install NGINX Agent. +Follow the steps in the [Installation]({{< relref "/agent/install-upgrade/install.md" >}}) topic to install NGINX Agent. ## Install prerequisite packages Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent. diff --git a/content/agent/contribute/start-mock-interface.md b/content/agent/contribute/start-mock-interface.md index 2c148de78..5b2a7e585 100644 --- a/content/agent/contribute/start-mock-interface.md +++ b/content/agent/contribute/start-mock-interface.md @@ -5,7 +5,7 @@ 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. +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. @@ -13,7 +13,7 @@ The mock interface is useful when developing NGINX Agent, as it allows you to vi To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). +- 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. @@ -39,7 +39,7 @@ INFO[0000] grpc listening at 54789 # grpc control plane port which NGINX Agent w 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 "/how-to/enable-interfaces.md" >}}) topic. +To enable them, view the [Enable gRPC and REST interfaces]({{< relref "/agent/how-to/enable-interfaces.md" >}}) topic. ## Launch Swagger UI diff --git a/content/agent/how-to/enable-interfaces.md b/content/agent/how-to/enable-interfaces.md index c73557165..fbd174e30 100644 --- a/content/agent/how-to/enable-interfaces.md +++ b/content/agent/how-to/enable-interfaces.md @@ -2,7 +2,7 @@ title: "Enable gRPC and REST interfaces" toc: true weight: 200 -docs: DOCS-000 +docs: DOCS-000 --- This document describes how to enable the gRPC and REST interfaces for F5 NGINX Agent. @@ -70,4 +70,4 @@ api: To apply the new configuration, NGINX Agent must be started or restarted. -You may want to view the [Start mock control plane interface]({{< relref "/contribute/start-mock-interface.md" >}}) topic to test NGINX Agent, or view the [Configuration overview]({{< relref "/how-to/configuration-overview.md" >}}) for more options. \ No newline at end of file +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/export-metrics.md b/content/agent/how-to/export-metrics.md index 96bf7648d..9edae11dc 100644 --- a/content/agent/how-to/export-metrics.md +++ b/content/agent/how-to/export-metrics.md @@ -24,7 +24,7 @@ This document describes how to export the metrics data from F5 NGINX Agent. To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). - - @@ -41,5 +41,5 @@ To begin this task, you will require the following: [//]: # "Examples of additional topics users might want to read include:" [//]: # "Relevant reference information, configuration options and more complex use cases." -- [OpenTelemetry metrics]({{< ref "/otel/metrics.md" >}}) +- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) - diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md index 95f651468..d95291816 100644 --- a/content/agent/install-upgrade/install.md +++ b/content/agent/install-upgrade/install.md @@ -13,14 +13,14 @@ This document describes the three main ways to install F5 NGINX agent: ## Before you begin -There are a few prerequisites shared between all installation methods: +There are a few prerequisites shared between all installation methods: - A [supported operating system and architecture](../technical-specifications/#supported-distributions) - `root` privilege ## NGINX Open Source repository -Before you install NGINX Agent, you must install and run NGINX. +Before you install NGINX Agent, you must install and run NGINX. If you don't have it installed already, read the [Installing NGINX Open Source ](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) topic. @@ -779,6 +779,6 @@ sudo nginx-agent -v ## Enable interfaces -Once NGINX Agent is successfully running, you can enable the required interfaces, which is described in the [Enable gRPC and REST interfaces]({{< relref "/how-to/enable-interfaces.md" >}}) topic. +Once NGINX Agent is successfully running, you can enable the required interfaces, which is described in the [Enable gRPC and REST interfaces]({{< relref "/agent/how-to/enable-interfaces.md" >}}) topic. -You may also be interested in the [Start mock control plane interface]({{< relref "/contribute/start-mock-interface.md" >}}) topic for development work. \ No newline at end of file +You may also be interested in the [Start mock control plane interface]({{< relref "/agent/contribute/start-mock-interface.md" >}}) topic for development work. \ No newline at end of file diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/agent/install-upgrade/migrate-v3.md index 86646208e..32811a075 100644 --- a/content/agent/install-upgrade/migrate-v3.md +++ b/content/agent/install-upgrade/migrate-v3.md @@ -24,7 +24,7 @@ This topic describes how to migrate from F5 NGINX Agent v2 to NGINX Agent v3. To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/install-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). - - diff --git a/content/agent/installation-upgrade/container-environments/docker-images.md b/content/agent/installation-upgrade/container-environments/docker-images.md new file mode 100644 index 000000000..bf1cf3637 --- /dev/null +++ b/content/agent/installation-upgrade/container-environments/docker-images.md @@ -0,0 +1,220 @@ +--- +title: "Build container images" +draft: false +weight: 100 +toc: true +tags: [ "docs" ] +categories: ["configuration"] +doctypes: ["task"] +docs: "DOCS-1410" +--- + +## Overview + +NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances and must run in the same container to work. This document explains multiple ways in which NGINX Agent can be run alongside NGINX in a container. + +If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. + +See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "/agent/technical-specifications.md" >}}) topic. + +## Deploy Offical NGINX and NGINX Plus Containers + +Docker images are available in the [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) NGINX documentation. + +This guide provides instructions on how to build images with NGINX Agent and NGINX packaged together. It includes steps for downloading the necessary Docker images, configuring your Docker environment, and deploying NGINX and NGINX Plus containers. + +## Set up your environment + +### Install a container engine + +You can use [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) to manage NGINX Agent container images. Follow the installation instructions for your preferred container engine and be sure the service is running before proceeding with the instructions in this document. + +{{}}The examples in this document primarily use Docker commands. You can adapt these using the appropriate [Podman commands](https://docs.podman.io/en/latest/Commands.html) if you're not using Docker.{{}} + +### Install the GNU Make package + +You need to use the [GNU Make](https://www.gnu.org/software/make/) package to build the NGINX Agent container images provided in the nginx-agent GitHub repository. + +If you do not already have Make installed, install it using the appropriate package manager for your operating system. + +For example, to install **make** using the Ubuntu Advanced Packaging Tool (APT), run the command **apt install** command shown in the example. In some cases, it may help to update the package source lists in your operating system before proceeding. + +1. Update the package source list: + + ```shell + sudo apt update + ``` + +2. Install the `make` package: + + ```shell + sudo apt install make + ``` + +### Clone the nginx-agent repository + +The NGINX Agent GitHub repo contains the Dockerfiles and supporting scripts that you will use to build your images. + +Run the appropriate command below to clone the GitHub repo by using HTTPS or SSH. + +{{}} + +{{%tab name="HTTPS"%}} + +```shell +git clone https://github.com/nginx/agent.git +``` + +{{% /tab %}} + +{{%tab name="SSH"%}} + +```shell +git clone git@github.com:nginx/agent.git +``` + +{{% /tab %}} + +{{% /tabs %}} + +### Download the NGINX Plus certificate and key {#myf5-download} + +{{< fa "circle-info" "text-muted" >}} **This step is required if you are using NGINX Plus. If you are using NGINX open source, you can skip this section.** + +In order to build a container image with NGINX Plus, you must provide the SSL certificate and private key files provided with your NGINX Plus license. These files grant access to the package repository from which the script will download the NGINX Plus package. + +1. Log in to the [MyF5](https://my.f5.com) customer portal. +1. Go to **My Products and Plans** > **Subscriptions**. +1. Select the product subscription. +1. Download the **SSL Certificate** and **Private Key** files. +1. Move the SSL certificate and private key files to the directory where you cloned the nginx-agent repo. + + - The Makefile expects to find these files in the path *./build/certs*. Assuming you cloned the nginx-agent repo to your **$HOME** directory, you would move and rename the files as follows: + + ```shell + mkdir -p $HOME/nginx-agent/build/certs + mv nginx-repo-S-X00012345.key $HOME/nginx-agent/build/certs/nginx-repo.key + mv nginx-repo-S-X00012345.crt $HOME/nginx-agent/build/certs/nginx-repo.crt + ``` + + - Be sure to replace the example certificate and key filenames shown in the example command with your actual file names. + - The file names in the *build/certs* directory must match those shown in the example. + +## Run the NGINX Agent container + +To run NGINX Agent container using Docker use the following command: + +```shell +docker pull docker-registry.nginx.com/nginx/agent:mainline +``` +```shell +docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent +``` +```shell +docker run --name nginx-agent -d nginx-agent +``` + +{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< relref "/agent/how-to/configuration-overview" >}}).{{}} + +### Enable the gRPC interface + +To connect your NGINX Agent container to your NGINX One or NGINX Instance Manager instance, you must enable the gRPC interface. To do this, you must edit the NGINX Agent configuration file, *nginx-agent.conf*. For example: + +```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 +``` + +### Enable the REST interface + +If your control plane requires REST API, you can expose NGINX Agent's REST API by editing the NGINX Agent configuration file, *nginx-agent.conf*. For example: + +```yaml +api: + host: 0.0.0.0 + port: 8038 +``` + +Once you have updated the *nginx-agent.conf* file, you can run the container with the updated **nginx-agent.conf** mounted and the port **8038** exposed with the following command: + +```console +docker run --name nginx-agent -d \ + --mount type=bind,source="$(pwd)"/nginx-agent.conf,target=/etc/nginx-agent/nginx-agent.conf,readonly \ + -p 127.0.0.1:8038:8038/tcp \ + nginx-agent +``` + +To ensure that the REST Interface is correctly configured, you can use the `curl` command targeting the following endpoint from your terminal: + +```shell +curl 0.0.0.0:8038/nginx/ +``` + +If the REST Interface is configured correctly, then you should see a JSON object ouputted to the terminal containing metadata such as NGINX version, path to the NGINX conf, and runtime modules. + +**Sample Output:** + +```code +[{"nginx_id":"b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437","version":"1.27.1","conf_path":"/etc/nginx/nginx.conf","process_id":"7","process_path":"/usr/sbin/nginx","start_time":1725878806000,"built_from_source":false,"loadable_modules":null,"runtime_modules":["http_addition_module","http_auth_request_module","http_dav_module","http_flv_module","http_gunzip_module","http_gzip_static_module","http_mp4_module","http_random_index_module","http_realip_module","http_secure_link_module","http_slice_module","http_ssl_module","http_stub_status_module","http_sub_module","http_v2_module","http_v3_module","mail_ssl_module","stream_realip_module","stream_ssl_module","stream_ssl_preread_module"],"plus":{"enabled":false,"release":""},"ssl":{"ssl_type":0,"details":["OpenSSL","3.3.0","9 Apr 2024 (running with OpenSSL 3.3.1 4 Jun 2024)"]},"status_url":"","configure_args":["","prefix=/etc/nginx","sbin-path=/usr/sbin/nginx","modules-path=/usr/lib/nginx/modules","conf-path=/etc/nginx/nginx.conf","error-log-path=/var/log/nginx/error.log","http-log-path=/var/log/nginx/access.log","pid-path=/var/run/nginx.pid","lock-path=/var/run/nginx.lock","http-client-body-temp-path=/var/cache/nginx/client_temp","http-proxy-temp-path=/var/cache/nginx/proxy_temp","http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp","http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp","http-scgi-temp-path=/var/cache/nginx/scgi_temp","with-perl_modules_path=/usr/lib/perl5/vendor_perl","user=nginx","group=nginx","with-compat","with-file-aio","with-threads","with-http_addition_module","with-http_auth_request_module","with-http_dav_module","with-http_flv_module","with-http_gunzip_module","with-http_gzip_static_module","with-http_mp4_module","with-http_random_index_module","with-http_realip_module","with-http_secure_link_module","with-http_slice_module","with-http_ssl_module","with-http_stub_status_module","with-http_sub_module","with-http_v2_module","with-http_v3_module","with-mail","with-mail_ssl_module","with-stream","with-stream_realip_module","with-stream_ssl_module","with-stream_ssl_preread_module","with-cc-opt='-Os -fstack-clash-protection -Wformat -Werror=format-security -g'","with-ld-opt=-Wl,--as-needed,-O1,--sort-common"],"error_log_paths":null}] +``` + +
+ +## Build the NGINX Agent images for specific OS targets + +{{}}The only **officially supported** base operating system is **Alpine**. The instructions below for other operating systems are provided for informational and **testing purposes only**.{{}} + +The NGINX Agent GitHub repo has a set of Make commands that you can use to build a container image for an specific operating system and version: + +- `make oss-image` builds an image containing NGINX Agent and NGINX open source. +- `make image` builds an image containing NGINX Agent and NGINX Plus. + +You can pass the following arguments when running the **make** command to build an NGINX Agent container image. + +{{}} +| Argument | Definition | +| ---------------- | -------------------------| +| OS_RELEASE | The Linux distribution to use as the base image.
Can also be set in the repo Makefile.| +| OS_VERSION | The version of the Linux distribution to use as the base image.
Can also be set in the repo Makefile.| +| AGENT_VERSION | The versions of NGINX agent that you want installed on the image.| + +{{}} + +### Build NGINX open source images + +Run the following `make` command to build the default image, which uses Alpine as the base image: + +```shell +IMAGE_BUILD_TARGET=install-agent-repo make oss-image +``` + +To build an image with Debian and an older version of NGINX Agent you can run the following command: + +```shell +IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make oss-image +``` + +### Build NGINX Plus images + +{{}}You need a license to use NGINX Agent with NGINX Plus. You must complete the steps in the [Download the certificate and key files from MyF5](#myf5-download) section before proceeding.{{}} + +Run the following `make` command to build the default image, which uses Ubuntu 24.04 (Noble) as the base image. + +```shell +IMAGE_BUILD_TARGET=install-agent-repo make image +``` + +To build an image with Debian and an older version of NGINX Agent you can run the following command: + +```shell +IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make image +``` + + + diff --git a/content/agent/installation-upgrade/container-environments/docker-support.md b/content/agent/installation-upgrade/container-environments/docker-support.md new file mode 100644 index 000000000..6d764a1f0 --- /dev/null +++ b/content/agent/installation-upgrade/container-environments/docker-support.md @@ -0,0 +1,83 @@ +--- +title: Container support and troubleshooting +categories: +- installation +draft: false +tags: +- docs +toc: true +weight: 200 +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. + +See the [Technical Specifications]({{< relref "/agent/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. + +NGINX Agent running in a container has some limitations that need to be considered, and are listed below. + +## Supported cgroups + +To collect metrics about the Docker container that the NGINX Agent is running in, NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage. + +NGINX Agent supports both versions of cgroups. + +- https://www.kernel.org/doc/Documentation/cgroup-v1/ +- https://www.kernel.org/doc/Documentation/cgroup-v2.txt + +## Metrics + +### Unsupported Metrics + +The following system metrics are not supported when running NGINX Agent in a Docker container. NGINX Agent returns no values for these metrics: + +- system.cpu.idle +- system.cpu.iowait +- system.cpu.stolen +- system.mem.buffered +- system.load.1 +- system.load.5 +- system.load.15 +- system.disk.total +- system.disk.used +- system.disk.free +- system.disk.in_use +- system.io.kbs_r +- system.io.kbs_w +- system.io.wait_r +- system.io.wait_w +- system.io.iops_r +- system.io.iops_w + +### Memory Metrics + +If no memory limit is set when starting the Docker container, then the memory limit that's shown in the metrics for the container will be the total memory of the Docker host system. + +### Swap Memory Metrics + +If a warning message similar to the following example is seen in the NGINX Agent logs, the swap memory limit for the Docker container is greater than the swap memory for the Docker host system: + +```bash +Swap memory limit specified for the container, ... is greater than the host system swap memory ... +``` + +The `system.swap.total` metric for the container matches the total swap memory for the Docker host system instead of the swap memory limit specified when starting the Docker container. + +If a warning message similar to the following example is seen in the NGINX Agent logs, the Docker host system does not have cgroup swap limit capabilities enabled. To enable these capabilities, follow the steps below. + +```bash +Unable to collect Swap metrics because the file ... was not found +``` + +#### Enable cgroup swap limit capabilities + +Run the following command to see if the cgroup swap limit capabilities are enabled: + +```bash +$ docker info | grep swap +WARNING: No swap limit support +``` + +To enable cgroup swap limit capabilities, refer to this Docker guide: [Docker - Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities). diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md new file mode 100644 index 000000000..41d303aa4 --- /dev/null +++ b/content/agent/installation-upgrade/getting-started.md @@ -0,0 +1,179 @@ +--- +title: "Getting started" +draft: false +weight: 100 +toc: true +tags: [ "docs" ] +docs: "DOCS-1089" +categories: ["configuration"] +doctypes: ["task"] +--- + +## Overview + +Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which NGINX Agent will report. + +## Install NGINX + +Follow the steps in the [Installation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/) section to download, install, and run NGINX. + +## Clone the NGINX Agent Repository + +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. + +## Install Go + +NGINX Agent and the Mock Control Plane are written in Go. Go 1.23 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). + +## 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 + +# Command Output +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 +``` + +## NGINX Agent Settings + +If it doesn't already exist, create the `/etc/nginx-agent/` directory 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" +``` + +The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent. + +## Launch Swagger UI + +Swagger UI requires goswagger be installed. See [instructions for installing goswagger](https://goswagger.io/go-swagger/install/) for additional help. + +To launch the Swagger UI for the REST interface run the following command: + +```shell +make launch-swagger-ui +``` + +## Extensions + +An extension is a piece of code, not critical to the main functionality that NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics. + +To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. +Here is an example of enabling the advanced metrics extension: + +```yaml +extensions: + - advanced-metrics +``` + +## Start NGINX Agent + +If already running, restart NGINX Agent to apply the new configuration. Alternatively, if NGINX Agent is not running, you may run it from the source code root directory. + +Open another terminal window and start NGINX Agent. Issue the following command from the `agent` source code root directory. + +```shell +sudo make run + +# Command Output snippet +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). + +## Start and Enable Start on Boot + +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 +``` + +## Logs + +NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. + +{{< 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. +{{< /important >}} diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/installation-upgrade/installation-plus.md new file mode 100644 index 000000000..fe77bbb58 --- /dev/null +++ b/content/agent/installation-upgrade/installation-plus.md @@ -0,0 +1,511 @@ +--- +title: "Installation from NGINX Plus repository" +draft: false +weight: 400 +toc: true +tags: [ "docs" ] +docs: "DOCS-1217" +categories: ["configuration"] +doctypes: ["task"] +--- + +## Overview + +Learn how to install NGINX Agent from NGINX Plus repository + +## Prerequisites + +- An NGINX Plus subscription (purchased or trial) +- NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) +- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) +- `root` privilege +- Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. +- Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. + +## Configure NGINX Plus Repository for installing NGINX Agent + +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. + +- [Installing NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#installing-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) +- [Installing NGINX Agent on Ubuntu](#installing-nginx-agent-on-ubuntu) +- [Installing NGINX Agent on Debian](#installing-nginx-agent-on-debian) +- [Installing NGINX Agent on SLES](#installing-nginx-agent-on-sles) +- [Installing NGINX Agent on Alpine Linux](#installing-nginx-agent-on-alpine-linux) +- [Installing NGINX Agent on Amazon Linux 2023](#installing-nginx-agent-on-amazon-linux-2023) +- [Installing NGINX Agent on Amazon Linux](#installing-nginx-agent-on-amazon-linux) +- [Installing NGINX Agent on FreeBSD](#installing-nginx-agent-on-freebsd) + +### Installing 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`: + + ``` + [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 `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing 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`: + + ``` + 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 + ``` + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + + +### Installing 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`: + + ``` + 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 + ``` + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing 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 fingerprints `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` as follows: + + ``` + pub rsa4096 2024-05-29 [SC] + 8540A6F18833A80E9C1653A42FD21310B49F6B46 + uid nginx signing key + + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] + 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 + uid nginx signing key + + pub rsa4096 2024-05-29 [SC] + 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 + 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 + ``` + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing 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: + + ``` + 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 + ``` + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing NGINX Agent on Amazon Linux 2023 + +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 dnf install yum-utils procps-ng ca-certificates + ``` + +1. To set up the dnf repository for Amazon Linux 2023, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ``` + [nginx-agent] + name=nginx-agent repo + baseurl=https://packages.nginx.org/nginx-agent/amzn/2023/$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 dnf install nginx-agent + ``` + +1. When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing NGINX Agent on Amazon Linux 2 + +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 the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: + + ``` + [nginx-agent] + name=nginx-agent repo + baseurl=https://pkgs.nginx.com/nginx-agent/amzn/2023/$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 `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` + +### Installing 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 the file named `/etc/pkg/nginx-agent.conf` with the following content: + + ``` + 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: + + ``` + 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 + ``` + +1. Verify the installation: + + ```shell + sudo nginx-agent -v + ``` diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index fac11fbdc..f11a5cde4 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -53,8 +53,8 @@ Minimum system sizing recommendations for NGINX Agent: ## 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. +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). -More information is available in the [Configuration overview]({{< ref "/how-to/configuration-overview.md#logs" >}}) \ No newline at end of file +More information is available in the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md#logs" >}}) \ No newline at end of file diff --git a/content/agent/v2/installation-upgrade/container-environments/docker-images.md b/content/agent/v2/installation-upgrade/container-environments/docker-images.md index 40b3a3b2f..5f3a1e48b 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-images.md @@ -15,7 +15,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. -See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "technical-specifications.md" >}}) topic. +See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "/agent/technical-specifications.md" >}}) topic. ## Deploy Offical NGINX and NGINX Plus Containers @@ -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 "/v2/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/v2/installation-upgrade/container-environments/docker-support.md b/content/agent/v2/installation-upgrade/container-environments/docker-support.md index b0bdd98a6..e4dd2002d 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-support.md @@ -12,9 +12,9 @@ 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 "/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. +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 "/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. +See the [Technical Specifications]({{< relref "/agent/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. NGINX Agent running in a container has some limitations that need to be considered, and are listed below. diff --git a/content/agent/v2/installation-upgrade/getting-started.md b/content/agent/v2/installation-upgrade/getting-started.md index 578037f53..6a1c336a2 100644 --- a/content/agent/v2/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 "/v2/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/v2/installation-upgrade/installation-oss.md b/content/agent/v2/installation-upgrade/installation-oss.md index 5e82dd21b..cf24dd1a6 100644 --- a/content/agent/v2/installation-upgrade/installation-oss.md +++ b/content/agent/v2/installation-upgrade/installation-oss.md @@ -16,7 +16,7 @@ Learn how to install NGINX Agent from the NGINX Open Source repository. ## Prerequisites - NGINX installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) -- A [supported operating system and architecture]({{< relref "/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) - `root` privilege ## Configure NGINX OSS Repository for installing NGINX Agent diff --git a/content/agent/v2/installation-upgrade/installation-plus.md b/content/agent/v2/installation-upgrade/installation-plus.md index ba4250210..fe77bbb58 100644 --- a/content/agent/v2/installation-upgrade/installation-plus.md +++ b/content/agent/v2/installation-upgrade/installation-plus.md @@ -17,7 +17,7 @@ Learn how to install NGINX Agent from NGINX Plus repository - An NGINX Plus subscription (purchased or trial) - NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) -- A [supported operating system and architecture]({{< relref "/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) - `root` privilege - Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. - Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. diff --git a/go.mod b/go.mod index dee18a98e..36306b1cd 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.41.22 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.41.27 // indirect diff --git a/go.sum b/go.sum index 1819ea06c..81af599e2 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,4 @@ 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= 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 @@ +
+
+
+

+ {{ .Title }} +

+ {{ if .Description }} +

+ {{ .Description | markdownify }} +

+ {{ 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. +
+
+ {{ if .Content }} +

+ {{ .Content | markdownify }} +

+ {{ end }} +
+
+ +
+
+
+ {{ 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 From 3e3778639413aa3fb9fd171f714448087634a681 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 12 Feb 2025 11:55:03 +0000 Subject: [PATCH 03/63] docs: re-add note --- content/agent/installation-upgrade/getting-started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md index 41d303aa4..511da4874 100644 --- a/content/agent/installation-upgrade/getting-started.md +++ b/content/agent/installation-upgrade/getting-started.md @@ -176,4 +176,6 @@ 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/how-to/configuration-overview.md#nginx-agent-log-rotation" >}}). {{< /important >}} From 8eab420afe7fb5769341ab0ee4fee9768a238f7f Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Wed, 12 Feb 2025 13:21:30 +0000 Subject: [PATCH 04/63] fix: add url meta --- content/agent/_index.md | 13 +- content/agent/contribute/_index.md | 1 + content/agent/how-to/_index.md | 1 + content/agent/install-upgrade/_index.md | 1 + .../container-environments/docker-images.md | 220 -------- .../container-environments/docker-support.md | 83 --- .../installation-upgrade/getting-started.md | 181 ------- .../installation-upgrade/installation-plus.md | 511 ------------------ content/agent/otel/_index.md | 1 + content/agent/v2/_index.md | 1 + content/agent/v2/configuration/_index.md | 1 + .../agent/v2/installation-upgrade/_index.md | 1 + .../container-environments/_index.md | 1 + 13 files changed, 16 insertions(+), 1000 deletions(-) delete mode 100644 content/agent/installation-upgrade/container-environments/docker-images.md delete mode 100644 content/agent/installation-upgrade/container-environments/docker-support.md delete mode 100644 content/agent/installation-upgrade/getting-started.md delete mode 100644 content/agent/installation-upgrade/installation-plus.md diff --git a/content/agent/_index.md b/content/agent/_index.md index b3764d916..95b9e6b1b 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -1,6 +1,9 @@ --- -title: "NGINX Agent Documentation" -weight: 900 ---- - -NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance \ No newline at end of file +title: "NGINX Agent" +description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance." +linkTitle: "NGINX Agent" +menu: docs +url: /nginx-agent/ +cascade: + logo: "NGINX-product-icon.png" +--- \ No newline at end of file diff --git a/content/agent/contribute/_index.md b/content/agent/contribute/_index.md index 9eebf5403..a6764819d 100644 --- a/content/agent/contribute/_index.md +++ b/content/agent/contribute/_index.md @@ -1,6 +1,7 @@ --- title: "Contribute" weight: 600 +url: /nginx-agent/contribute/ --- Learn about the NGINX Agent community and how to contribute to the project. \ No newline at end of file diff --git a/content/agent/how-to/_index.md b/content/agent/how-to/_index.md index 3f01dc82b..d0f9b4cc5 100644 --- a/content/agent/how-to/_index.md +++ b/content/agent/how-to/_index.md @@ -1,6 +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/install-upgrade/_index.md b/content/agent/install-upgrade/_index.md index db1eae8ab..0274bc7da 100644 --- a/content/agent/install-upgrade/_index.md +++ b/content/agent/install-upgrade/_index.md @@ -1,6 +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/installation-upgrade/container-environments/docker-images.md b/content/agent/installation-upgrade/container-environments/docker-images.md deleted file mode 100644 index bf1cf3637..000000000 --- a/content/agent/installation-upgrade/container-environments/docker-images.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: "Build container images" -draft: false -weight: 100 -toc: true -tags: [ "docs" ] -categories: ["configuration"] -doctypes: ["task"] -docs: "DOCS-1410" ---- - -## Overview - -NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances and must run in the same container to work. This document explains multiple ways in which NGINX Agent can be run alongside NGINX in a container. - -If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. - -See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< relref "/agent/technical-specifications.md" >}}) topic. - -## Deploy Offical NGINX and NGINX Plus Containers - -Docker images are available in the [Deploying NGINX and NGINX Plus on Docker](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-docker/) NGINX documentation. - -This guide provides instructions on how to build images with NGINX Agent and NGINX packaged together. It includes steps for downloading the necessary Docker images, configuring your Docker environment, and deploying NGINX and NGINX Plus containers. - -## Set up your environment - -### Install a container engine - -You can use [Docker](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) to manage NGINX Agent container images. Follow the installation instructions for your preferred container engine and be sure the service is running before proceeding with the instructions in this document. - -{{}}The examples in this document primarily use Docker commands. You can adapt these using the appropriate [Podman commands](https://docs.podman.io/en/latest/Commands.html) if you're not using Docker.{{}} - -### Install the GNU Make package - -You need to use the [GNU Make](https://www.gnu.org/software/make/) package to build the NGINX Agent container images provided in the nginx-agent GitHub repository. - -If you do not already have Make installed, install it using the appropriate package manager for your operating system. - -For example, to install **make** using the Ubuntu Advanced Packaging Tool (APT), run the command **apt install** command shown in the example. In some cases, it may help to update the package source lists in your operating system before proceeding. - -1. Update the package source list: - - ```shell - sudo apt update - ``` - -2. Install the `make` package: - - ```shell - sudo apt install make - ``` - -### Clone the nginx-agent repository - -The NGINX Agent GitHub repo contains the Dockerfiles and supporting scripts that you will use to build your images. - -Run the appropriate command below to clone the GitHub repo by using HTTPS or SSH. - -{{}} - -{{%tab name="HTTPS"%}} - -```shell -git clone https://github.com/nginx/agent.git -``` - -{{% /tab %}} - -{{%tab name="SSH"%}} - -```shell -git clone git@github.com:nginx/agent.git -``` - -{{% /tab %}} - -{{% /tabs %}} - -### Download the NGINX Plus certificate and key {#myf5-download} - -{{< fa "circle-info" "text-muted" >}} **This step is required if you are using NGINX Plus. If you are using NGINX open source, you can skip this section.** - -In order to build a container image with NGINX Plus, you must provide the SSL certificate and private key files provided with your NGINX Plus license. These files grant access to the package repository from which the script will download the NGINX Plus package. - -1. Log in to the [MyF5](https://my.f5.com) customer portal. -1. Go to **My Products and Plans** > **Subscriptions**. -1. Select the product subscription. -1. Download the **SSL Certificate** and **Private Key** files. -1. Move the SSL certificate and private key files to the directory where you cloned the nginx-agent repo. - - - The Makefile expects to find these files in the path *./build/certs*. Assuming you cloned the nginx-agent repo to your **$HOME** directory, you would move and rename the files as follows: - - ```shell - mkdir -p $HOME/nginx-agent/build/certs - mv nginx-repo-S-X00012345.key $HOME/nginx-agent/build/certs/nginx-repo.key - mv nginx-repo-S-X00012345.crt $HOME/nginx-agent/build/certs/nginx-repo.crt - ``` - - - Be sure to replace the example certificate and key filenames shown in the example command with your actual file names. - - The file names in the *build/certs* directory must match those shown in the example. - -## Run the NGINX Agent container - -To run NGINX Agent container using Docker use the following command: - -```shell -docker pull docker-registry.nginx.com/nginx/agent:mainline -``` -```shell -docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent -``` -```shell -docker run --name nginx-agent -d nginx-agent -``` - -{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< relref "/agent/how-to/configuration-overview" >}}).{{}} - -### Enable the gRPC interface - -To connect your NGINX Agent container to your NGINX One or NGINX Instance Manager instance, you must enable the gRPC interface. To do this, you must edit the NGINX Agent configuration file, *nginx-agent.conf*. For example: - -```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 -``` - -### Enable the REST interface - -If your control plane requires REST API, you can expose NGINX Agent's REST API by editing the NGINX Agent configuration file, *nginx-agent.conf*. For example: - -```yaml -api: - host: 0.0.0.0 - port: 8038 -``` - -Once you have updated the *nginx-agent.conf* file, you can run the container with the updated **nginx-agent.conf** mounted and the port **8038** exposed with the following command: - -```console -docker run --name nginx-agent -d \ - --mount type=bind,source="$(pwd)"/nginx-agent.conf,target=/etc/nginx-agent/nginx-agent.conf,readonly \ - -p 127.0.0.1:8038:8038/tcp \ - nginx-agent -``` - -To ensure that the REST Interface is correctly configured, you can use the `curl` command targeting the following endpoint from your terminal: - -```shell -curl 0.0.0.0:8038/nginx/ -``` - -If the REST Interface is configured correctly, then you should see a JSON object ouputted to the terminal containing metadata such as NGINX version, path to the NGINX conf, and runtime modules. - -**Sample Output:** - -```code -[{"nginx_id":"b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437","version":"1.27.1","conf_path":"/etc/nginx/nginx.conf","process_id":"7","process_path":"/usr/sbin/nginx","start_time":1725878806000,"built_from_source":false,"loadable_modules":null,"runtime_modules":["http_addition_module","http_auth_request_module","http_dav_module","http_flv_module","http_gunzip_module","http_gzip_static_module","http_mp4_module","http_random_index_module","http_realip_module","http_secure_link_module","http_slice_module","http_ssl_module","http_stub_status_module","http_sub_module","http_v2_module","http_v3_module","mail_ssl_module","stream_realip_module","stream_ssl_module","stream_ssl_preread_module"],"plus":{"enabled":false,"release":""},"ssl":{"ssl_type":0,"details":["OpenSSL","3.3.0","9 Apr 2024 (running with OpenSSL 3.3.1 4 Jun 2024)"]},"status_url":"","configure_args":["","prefix=/etc/nginx","sbin-path=/usr/sbin/nginx","modules-path=/usr/lib/nginx/modules","conf-path=/etc/nginx/nginx.conf","error-log-path=/var/log/nginx/error.log","http-log-path=/var/log/nginx/access.log","pid-path=/var/run/nginx.pid","lock-path=/var/run/nginx.lock","http-client-body-temp-path=/var/cache/nginx/client_temp","http-proxy-temp-path=/var/cache/nginx/proxy_temp","http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp","http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp","http-scgi-temp-path=/var/cache/nginx/scgi_temp","with-perl_modules_path=/usr/lib/perl5/vendor_perl","user=nginx","group=nginx","with-compat","with-file-aio","with-threads","with-http_addition_module","with-http_auth_request_module","with-http_dav_module","with-http_flv_module","with-http_gunzip_module","with-http_gzip_static_module","with-http_mp4_module","with-http_random_index_module","with-http_realip_module","with-http_secure_link_module","with-http_slice_module","with-http_ssl_module","with-http_stub_status_module","with-http_sub_module","with-http_v2_module","with-http_v3_module","with-mail","with-mail_ssl_module","with-stream","with-stream_realip_module","with-stream_ssl_module","with-stream_ssl_preread_module","with-cc-opt='-Os -fstack-clash-protection -Wformat -Werror=format-security -g'","with-ld-opt=-Wl,--as-needed,-O1,--sort-common"],"error_log_paths":null}] -``` - -
    - -## Build the NGINX Agent images for specific OS targets - -{{}}The only **officially supported** base operating system is **Alpine**. The instructions below for other operating systems are provided for informational and **testing purposes only**.{{}} - -The NGINX Agent GitHub repo has a set of Make commands that you can use to build a container image for an specific operating system and version: - -- `make oss-image` builds an image containing NGINX Agent and NGINX open source. -- `make image` builds an image containing NGINX Agent and NGINX Plus. - -You can pass the following arguments when running the **make** command to build an NGINX Agent container image. - -{{}} -| Argument | Definition | -| ---------------- | -------------------------| -| OS_RELEASE | The Linux distribution to use as the base image.
    Can also be set in the repo Makefile.| -| OS_VERSION | The version of the Linux distribution to use as the base image.
    Can also be set in the repo Makefile.| -| AGENT_VERSION | The versions of NGINX agent that you want installed on the image.| - -{{    }} - -### Build NGINX open source images - -Run the following `make` command to build the default image, which uses Alpine as the base image: - -```shell -IMAGE_BUILD_TARGET=install-agent-repo make oss-image -``` - -To build an image with Debian and an older version of NGINX Agent you can run the following command: - -```shell -IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make oss-image -``` - -### Build NGINX Plus images - -{{}}You need a license to use NGINX Agent with NGINX Plus. You must complete the steps in the [Download the certificate and key files from MyF5](#myf5-download) section before proceeding.{{}} - -Run the following `make` command to build the default image, which uses Ubuntu 24.04 (Noble) as the base image. - -```shell -IMAGE_BUILD_TARGET=install-agent-repo make image -``` - -To build an image with Debian and an older version of NGINX Agent you can run the following command: - -```shell -IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make image -``` - - - diff --git a/content/agent/installation-upgrade/container-environments/docker-support.md b/content/agent/installation-upgrade/container-environments/docker-support.md deleted file mode 100644 index 6d764a1f0..000000000 --- a/content/agent/installation-upgrade/container-environments/docker-support.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Container support and troubleshooting -categories: -- installation -draft: false -tags: -- docs -toc: true -weight: 200 -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. - -See the [Technical Specifications]({{< relref "/agent/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. - -NGINX Agent running in a container has some limitations that need to be considered, and are listed below. - -## Supported cgroups - -To collect metrics about the Docker container that the NGINX Agent is running in, NGINX Agent uses the available cgroup files to calculate metrics like CPU and memory usage. - -NGINX Agent supports both versions of cgroups. - -- https://www.kernel.org/doc/Documentation/cgroup-v1/ -- https://www.kernel.org/doc/Documentation/cgroup-v2.txt - -## Metrics - -### Unsupported Metrics - -The following system metrics are not supported when running NGINX Agent in a Docker container. NGINX Agent returns no values for these metrics: - -- system.cpu.idle -- system.cpu.iowait -- system.cpu.stolen -- system.mem.buffered -- system.load.1 -- system.load.5 -- system.load.15 -- system.disk.total -- system.disk.used -- system.disk.free -- system.disk.in_use -- system.io.kbs_r -- system.io.kbs_w -- system.io.wait_r -- system.io.wait_w -- system.io.iops_r -- system.io.iops_w - -### Memory Metrics - -If no memory limit is set when starting the Docker container, then the memory limit that's shown in the metrics for the container will be the total memory of the Docker host system. - -### Swap Memory Metrics - -If a warning message similar to the following example is seen in the NGINX Agent logs, the swap memory limit for the Docker container is greater than the swap memory for the Docker host system: - -```bash -Swap memory limit specified for the container, ... is greater than the host system swap memory ... -``` - -The `system.swap.total` metric for the container matches the total swap memory for the Docker host system instead of the swap memory limit specified when starting the Docker container. - -If a warning message similar to the following example is seen in the NGINX Agent logs, the Docker host system does not have cgroup swap limit capabilities enabled. To enable these capabilities, follow the steps below. - -```bash -Unable to collect Swap metrics because the file ... was not found -``` - -#### Enable cgroup swap limit capabilities - -Run the following command to see if the cgroup swap limit capabilities are enabled: - -```bash -$ docker info | grep swap -WARNING: No swap limit support -``` - -To enable cgroup swap limit capabilities, refer to this Docker guide: [Docker - Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/#your-kernel-does-not-support-cgroup-swap-limit-capabilities). diff --git a/content/agent/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md deleted file mode 100644 index 511da4874..000000000 --- a/content/agent/installation-upgrade/getting-started.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "Getting started" -draft: false -weight: 100 -toc: true -tags: [ "docs" ] -docs: "DOCS-1089" -categories: ["configuration"] -doctypes: ["task"] ---- - -## Overview - -Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which NGINX Agent will report. - -## Install NGINX - -Follow the steps in the [Installation](https://docs.nginx.com/nginx/admin-guide/installing-nginx/) section to download, install, and run NGINX. - -## Clone the NGINX Agent Repository - -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. - -## Install Go - -NGINX Agent and the Mock Control Plane are written in Go. Go 1.23 or higher is required to build and run either application from the source code directory. You can [download Go from the official website](https://go.dev/dl/). - -## 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 - -# Command Output -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 -``` - -## NGINX Agent Settings - -If it doesn't already exist, create the `/etc/nginx-agent/` directory 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" -``` - -The mock control plane can use either gRPC or REST protocols to communicate with NGINX Agent. - -## Launch Swagger UI - -Swagger UI requires goswagger be installed. See [instructions for installing goswagger](https://goswagger.io/go-swagger/install/) for additional help. - -To launch the Swagger UI for the REST interface run the following command: - -```shell -make launch-swagger-ui -``` - -## Extensions - -An extension is a piece of code, not critical to the main functionality that NGINX agent is responsible for. This generally falls outside the remit of managing NGINX Configuration and reporting NGINX metrics. - -To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. -Here is an example of enabling the advanced metrics extension: - -```yaml -extensions: - - advanced-metrics -``` - -## Start NGINX Agent - -If already running, restart NGINX Agent to apply the new configuration. Alternatively, if NGINX Agent is not running, you may run it from the source code root directory. - -Open another terminal window and start NGINX Agent. Issue the following command from the `agent` source code root directory. - -```shell -sudo make run - -# Command Output snippet -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). - -## Start and Enable Start on Boot - -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 -``` - -## Logs - -NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. - -{{< 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/how-to/configuration-overview.md#nginx-agent-log-rotation" >}}). -{{< /important >}} diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/installation-upgrade/installation-plus.md deleted file mode 100644 index fe77bbb58..000000000 --- a/content/agent/installation-upgrade/installation-plus.md +++ /dev/null @@ -1,511 +0,0 @@ ---- -title: "Installation from NGINX Plus repository" -draft: false -weight: 400 -toc: true -tags: [ "docs" ] -docs: "DOCS-1217" -categories: ["configuration"] -doctypes: ["task"] ---- - -## Overview - -Learn how to install NGINX Agent from NGINX Plus repository - -## Prerequisites - -- An NGINX Plus subscription (purchased or trial) -- NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) -- A [supported operating system and architecture]({{< relref "/agent/technical-specifications.md#supported-distributions" >}}) -- `root` privilege -- Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. -- Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. - -## Configure NGINX Plus Repository for installing NGINX Agent - -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. - -- [Installing NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#installing-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) -- [Installing NGINX Agent on Ubuntu](#installing-nginx-agent-on-ubuntu) -- [Installing NGINX Agent on Debian](#installing-nginx-agent-on-debian) -- [Installing NGINX Agent on SLES](#installing-nginx-agent-on-sles) -- [Installing NGINX Agent on Alpine Linux](#installing-nginx-agent-on-alpine-linux) -- [Installing NGINX Agent on Amazon Linux 2023](#installing-nginx-agent-on-amazon-linux-2023) -- [Installing NGINX Agent on Amazon Linux](#installing-nginx-agent-on-amazon-linux) -- [Installing NGINX Agent on FreeBSD](#installing-nginx-agent-on-freebsd) - -### Installing 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`: - - ``` - [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 `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing 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`: - - ``` - 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 - ``` - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - - -### Installing 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`: - - ``` - 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 - ``` - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing 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 fingerprints `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3` as follows: - - ``` - pub rsa4096 2024-05-29 [SC] - 8540A6F18833A80E9C1653A42FD21310B49F6B46 - uid nginx signing key - - pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] - 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 - uid nginx signing key - - pub rsa4096 2024-05-29 [SC] - 9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3 - 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 - ``` - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing 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: - - ``` - 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 - ``` - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing NGINX Agent on Amazon Linux 2023 - -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 dnf install yum-utils procps-ng ca-certificates - ``` - -1. To set up the dnf repository for Amazon Linux 2023, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: - - ``` - [nginx-agent] - name=nginx-agent repo - baseurl=https://packages.nginx.org/nginx-agent/amzn/2023/$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 dnf install nginx-agent - ``` - -1. When prompted to accept the GPG key, verify that the fingerprint matches `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing NGINX Agent on Amazon Linux 2 - -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 the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: - - ``` - [nginx-agent] - name=nginx-agent repo - baseurl=https://pkgs.nginx.com/nginx-agent/amzn/2023/$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 `8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46`, `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, `9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3`, and if so, accept it. - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` - -### Installing 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 the file named `/etc/pkg/nginx-agent.conf` with the following content: - - ``` - 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: - - ``` - 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 - ``` - -1. Verify the installation: - - ```shell - sudo nginx-agent -v - ``` diff --git a/content/agent/otel/_index.md b/content/agent/otel/_index.md index 9898dcd10..0e113fe11 100644 --- a/content/agent/otel/_index.md +++ b/content/agent/otel/_index.md @@ -1,4 +1,5 @@ --- title: OpenTelemetry weight: 450 +url: /nginx-agent/otel/ --- \ No newline at end of file diff --git a/content/agent/v2/_index.md b/content/agent/v2/_index.md index f0138d948..df7a692dd 100644 --- a/content/agent/v2/_index.md +++ b/content/agent/v2/_index.md @@ -2,6 +2,7 @@ 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/configuration/_index.md b/content/agent/v2/configuration/_index.md index cd9db7e49..4429d1349 100644 --- a/content/agent/v2/configuration/_index.md +++ b/content/agent/v2/configuration/_index.md @@ -1,6 +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/v2/installation-upgrade/_index.md b/content/agent/v2/installation-upgrade/_index.md index 4c3d49899..8254dffaa 100644 --- a/content/agent/v2/installation-upgrade/_index.md +++ b/content/agent/v2/installation-upgrade/_index.md @@ -3,4 +3,5 @@ title: "Installation and upgrade" description: "Learn how to install, upgrade, and uninstall NGINX Agent." menu: docs weight: 300 +url: /nginx-agent/v2/installation-upgrade/ --- \ No newline at end of file diff --git a/content/agent/v2/installation-upgrade/container-environments/_index.md b/content/agent/v2/installation-upgrade/container-environments/_index.md index ca964e34b..6239e21ff 100644 --- a/content/agent/v2/installation-upgrade/container-environments/_index.md +++ b/content/agent/v2/installation-upgrade/container-environments/_index.md @@ -3,4 +3,5 @@ title: "Container environments" description: "Learn how to build and run NGINX Agent docker images." menu: docs weight: 800 +url: /nginx-agent/v2/installation-upgrade/container-environments/ --- \ No newline at end of file From e4732a0b63939120363a4b7952fb8827f85c272d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 3 Mar 2025 16:09:01 +0000 Subject: [PATCH 05/63] docs: remove v2 metrics page --- content/agent/about.md | 1 - content/agent/v2/metrics.md | 10 ---------- 2 files changed, 11 deletions(-) delete mode 100644 content/agent/v2/metrics.md diff --git a/content/agent/about.md b/content/agent/about.md index 45af5aaba..1e9f0f32f 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -16,7 +16,6 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta For an overview of the metrics available from NGINX Agent, read the following topics: - [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) (Agent v3) -- [Metrics]({{< relref "/agent/v2/metrics.md" >}}) (Agent v2) {{< img src="grafana-dashboard-example.png" caption="A Grafana dashboard displaying metrics reported by NGINX Agent." alt="A Grafana dashboard displaying metrics reported by NGINX Agent.">}} diff --git a/content/agent/v2/metrics.md b/content/agent/v2/metrics.md deleted file mode 100644 index e90e55c93..000000000 --- a/content/agent/v2/metrics.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Metrics -catalog: true -catalogType: v2metrics -toc: true -weight: 200 -docs: DOCS-000 ---- - -{{< v2-metrics >}} \ No newline at end of file From 5fdc6639ee89d135fe23710c559eff619366c2a9 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 27 Mar 2025 17:25:09 +0000 Subject: [PATCH 06/63] docs: update theme --- go.mod | 2 +- go.sum | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 36306b1cd..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.41.27 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.24 // indirect diff --git a/go.sum b/go.sum index 81af599e2..55949eecc 100644 --- a/go.sum +++ b/go.sum @@ -2,3 +2,5 @@ github.com/nginxinc/nginx-hugo-theme v0.41.22 h1:Gb/OLbpumNqp8vOPkZzO2GmgPDRd1yr 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= From 9535b7d368de6839926ce0c25a4c484010fe16e1 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Thu, 27 Mar 2025 18:04:06 +0000 Subject: [PATCH 07/63] docs:Adding agent v3 docs (#326) * docs:Adding agent v3 docs * docs: fix missing file reference * docs: Add missing install page * docs: Add v3 migrate docs * docs: Add missing feedback from PR --- content/agent/about.md | 83 ++---- .../agent/how-to/configuration-overview.md | 280 ++---------------- content/agent/install-upgrade/install.md | 66 +++-- content/agent/install-upgrade/migrate-v3.md | 38 +-- content/agent/otel/configure-otel-metrics.md | 229 ++++++++++++++ content/agent/technical-specifications.md | 83 +++--- content/agent/troubleshooting.md | 30 ++ 7 files changed, 408 insertions(+), 401 deletions(-) create mode 100644 content/agent/otel/configure-otel-metrics.md create mode 100644 content/agent/troubleshooting.md diff --git a/content/agent/about.md b/content/agent/about.md index 1e9f0f32f..022dcdd90 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -4,80 +4,43 @@ weight: 100 toc: true docs: DOCS-000 --- +{{}} + +{{}} -NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables: +### 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. -- Remote management of NGINX configurations -- Collection and reporting of real-time NGINX performance and operating system metrics -- Notifications of NGINX events +### 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" >}}) -[OpenTelemetry](https://opentelemetry.io/) support comes with NGINX Agent v3, and the ability to [export the metrics data]({{< relref "/agent/how-to/export-metrics.md" >}}) for use in other applications. +- 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. -For an overview of the metrics available from NGINX Agent, read the following topics: - -- [OpenTelemetry metrics]({{< relref "/agent/otel/metrics.md" >}}) (Agent v3) - - -{{< img src="grafana-dashboard-example.png" caption="A Grafana dashboard displaying metrics reported by NGINX Agent." alt="A Grafana dashboard displaying metrics reported by NGINX Agent.">}} + - [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 -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-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. - -For additional information, view the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md" >}}) topic. - ---- - -## 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/). +### Configuration management ---- - -### NGINX Open Source +- 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 -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. +- 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. + ---- -### 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. View the [Instance Metrics Overview](https://docs.nginx.com/nginx-management-suite/nim/about/overview-metrics/) topic for more details. Once NGINX Plus is configured with the `/api/` endpoint, the Agent will automatically use it on startup. +{{< img src="agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} --- -## 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/how-to/configuration-overview.md b/content/agent/how-to/configuration-overview.md index 26c2a41b2..03fbe48ac 100644 --- a/content/agent/how-to/configuration-overview.md +++ b/content/agent/how-to/configuration-overview.md @@ -1,7 +1,7 @@ --- title: "Configuration overview" toc: true -weight: 100 +weight: 300 docs: DOCS-1229 --- @@ -19,272 +19,32 @@ This page describes how to configure F5 NGINX Agent using configuration files, C {{}} -## Configuration files +## Configuration via Configuration Files -The default locations of configuration files for NGINX Agent are `/etc/nginx-agent/nginx-agent.conf` and `/var/lib/nginx-agent/agent-dynamic.conf`. The `agent-dynamic.conf` file default location is different for FreeBSD which is located `/var/db/nginx-agent/agent-dynamic.conf`. These files have comments at the top indicating their purpose. +The NGINX Agent configuration file is created using a YAML structure and can be found in `/etc/nginx-agent/nginx-agent.conf` -Examples of the configuration files are provided below: - -
    - example nginx-agent.conf - -{{}} -In the following example `nginx-agent.conf` file, you can change the `server.host` and `server.grpcPort` to connect to the control plane. -{{}} - -```nginx {hl_lines=[13]} -# -# /etc/nginx-agent/nginx-agent.conf -# -# Configuration file for NGINX Agent. -# -# This file tracks agent configuration values that are meant to be statically set. There -# are additional NGINX Agent configuration values that are set via the API and agent install script -# which can be found in /etc/nginx-agent/agent-dynamic.conf. - -# specify the server grpc port to connect to -server: - # host of the control plane - host: - grpcPort: 443 - backoff: # note: default values are prepopulated - initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 - multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 - max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour -# tls options -tls: - # enable tls in the nginx-agent setup for grpcs - # default to enable to connect with secure connection but without client cert for mtls - enable: true - # controls whether the server certificate chain and host name are verified. - # for production use, see instructions for configuring TLS - skip_verify: false +1. Edit the configuration file `sudo vim /etc/nginx-agent/nginx-agent.conf` +2. Add the log property +```bash log: - # set log level (panic, fatal, error, info, debug, trace; default "info") - level: info - # set log path. if empty, don't log to file. - path: /var/log/nginx-agent/ -nginx: - # path of NGINX logs to exclude - exclude_logs: "" - # Set to true when NGINX configuration should contain no warnings when performing a configuration apply (nginx -t is used to carry out this check) - treat_warnings_as_errors: false # Default is false -# data plane status message / 'heartbeat' -dataplane: - status: - # poll interval for dataplane status - the frequency the NGINX Agent will query the dataplane for changes - poll_interval: 30s - # report interval for dataplane status - the maximum duration to wait before syncing dataplane information if no updates have been observed - report_interval: 24h -metrics: - # specify the size of a buffer to build before sending metrics - bulk_size: 20 - # specify metrics poll interval - report_interval: 1m - collection_interval: 15s - mode: aggregated - backoff: # note: default values are prepopulated - initial_interval: 100ms # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - randomization_factor: 0.10 # Add the appropriate float value here, e.g., 0.10 - multiplier: 1.5 # Add the appropriate float value here, e.g., 1.5 - max_interval: 1m # Add the appropriate duration value here, e.g., "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - max_elapsed_time: 0 # Add the appropriate duration value here, e.g., "0" for indefinite "100ms" for 100 milliseconds, "5s" for 5 seconds, "1m" for 1 minute, "1h" for 1 hour - -# OSS NGINX default config path -# path to aux file dirs can also be added -config_dirs: "/etc/nginx:/usr/local/etc/nginx" - -# Internal queue size -queue_size: 100 - -extensions: - - nginx-app-protect - -# Enable reporting NGINX App Protect details to the control plane. -nginx_app_protect: - # Report interval for NGINX App Protect details - the frequency NGINX Agent checks NGINX App Protect for changes. - report_interval: 15s - # Enable precompiled publication from the NGINX Management Suite (true) or perform compilation on the data plane host (false). - precompiled_publication: true + level: debug ``` +3. Save and exit +4. `sudo systemctl restart nginx-agent` -
    - - -
    - example dynamic-agent.conf +## Configuration via CLI Parameters -{{}} -Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` - -Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` -{{}} - -```yaml -# Dynamic configuration file for NGINX Agent. -# -# The purpose of this file is to track agent configuration -# values that can be dynamically changed via the API and the agent install script. -# You may edit this file, but API calls that modify the tags on this system will -# overwrite the tag values in this file. -# -# The agent configuration values that API calls can modify are as follows: -# tags: -# - dev -# - qa -# -# The agent configuration value that the agent install script can modify are as follows: -# instance_group: my-instance-group - -instance_group: my-instance-group -tags: - - dev - - qa -``` - -
    - -## CLI flags and environment variables - -This section details the CLI flags and corresponding environment variables used to configure the NGINX Agent. - -### CLI flags - -```sh -nginx-agent [flags] -``` - -### Environment variables - -```sh -export ENV_VARIABLE_NAME="value" -nginx-agent +From a command line terminal: +```bash +sudo nginx-agent \ + --log-level=debug ``` -### Flag and environment arguments - -{{< warning >}} - -Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`. - -If you are upgrading from an older version, update your configuration accordingly. +## Configuration via Environment Variables +Environment variables are another way to set configuration values, especially in containerized deployments or CI/CD pipelines. -{{< /warning >}} - -{{}} -| CLI flag | Environment variable | Description | -|---------------------------------------------|--------------------------------------|-----------------------------------------------------------------------------| -| `--api-cert` | `NGINX_AGENT_API_CERT` | Specifies the certificate used by the Agent API. | -| `--api-host` | `NGINX_AGENT_API_HOST` | Sets the host used by the Agent API. Default: *127.0.0.1* | -| `--api-key` | `NGINX_AGENT_API_KEY` | Specifies the key used by the Agent API. | -| `--api-port` | `NGINX_AGENT_API_PORT` | Sets the port for exposing nginx-agent to HTTP traffic. | -| `--config-dirs` | `NGINX_AGENT_CONFIG_DIRS` | Defines directories NGINX Agent can read/write. Default: *"/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms"* | -| `--dataplane-report-interval` | `NGINX_AGENT_DATAPLANE_REPORT_INTERVAL` | Sets the interval for dataplane reporting. Default: *24h0m0s* | -| `--dataplane-status-poll-interval` | `NGINX_AGENT_DATAPLANE_STATUS_POLL_INTERVAL` | Sets the interval for polling dataplane status. Default: *30s* | -| `--display-name` | `NGINX_AGENT_DISPLAY_NAME` | Sets the instance's display name. | -| `--dynamic-config-path` | `NGINX_AGENT_DYNAMIC_CONFIG_PATH` | Specifies the path of the Agent dynamic config file. Default: *"/var/lib/nginx-agent/agent-dynamic.conf"* | -| `--features` | `NGINX_AGENT_FEATURES` | Specifies a comma-separated list of features enabled for the agent. Default: *[registration, nginx-config-async, nginx-ssl-config, nginx-counting, metrics, dataplane-status, process-watcher, file-watcher, activity-events, agent-api]* | -| `--ignore-directives` | | Specifies a comma-separated list of directives to ignore for sensitive info.| -| `--instance-group` | `NGINX_AGENT_INSTANCE_GROUP` | Sets the instance's group value. | -| `--log-level` | `NGINX_AGENT_LOG_LEVEL` | Sets the logging level (e.g., panic, fatal, error, info, debug, trace). Default: *info* | -| `--log-path` | `NGINX_AGENT_LOG_PATH` | Specifies the path to output log messages. | -| `--metrics-bulk-size` | `NGINX_AGENT_METRICS_BULK_SIZE` | Specifies the number of metrics reports collected before sending data. Default: *20* | -| `--metrics-collection-interval` | `NGINX_AGENT_METRICS_COLLECTION_INTERVAL` | Sets the interval for metrics collection. Default: *15s* | -| `--metrics-mode` | `NGINX_AGENT_METRICS_MODE` | Sets the metrics collection mode: streaming or aggregation. Default: *aggregated* | -| `--metrics-report-interval` | `NGINX_AGENT_METRICS_REPORT_INTERVAL` | Sets the interval for reporting collected metrics. Default: *1m0s* | -| `--nginx-config-reload-monitoring-period` | | Sets the duration to monitor error logs after an NGINX reload. Default: *10s* | -| `--nginx-exclude-logs` | `NGINX_AGENT_NGINX_EXCLUDE_LOGS` | Specifies paths of NGINX access logs to exclude from metrics collection. | -| `--nginx-socket` | `NGINX_AGENT_NGINX_SOCKET` | Specifies the location of the NGINX Plus counting Unix socket. Default: *unix:/var/run/nginx-agent/nginx.sock* | -| `--nginx-treat-warnings-as-errors` | `NGINX_AGENT_NGINX_TREAT_WARNINGS_AS_ERRORS` | Treats warnings as failures on configuration application. | -| `--queue-size` | `NGINX_AGENT_QUEUE_SIZE` | Specifies the size of the NGINX Agent internal queue. | -| `--server-command` | | Specifies the name of the command server sent in the TLS configuration. | -| `--server-grpcport` | `NGINX_AGENT_SERVER_GRPCPORT` | Sets the desired GRPC port for NGINX Agent traffic. | -| `--server-host` | `NGINX_AGENT_SERVER_HOST` | Specifies the IP address of the server host. | -| `--server-metrics` | | Specifies the name of the metrics server sent in the TLS configuration. | -| `--server-token` | `NGINX_AGENT_SERVER_TOKEN` | Sets the authentication token for accessing the commander and metrics services. Default: *e202f883-54c6-4702-be15-3ba6e507879a* | -| `--tags` | `NGINX_AGENT_TAGS` | Specifies a comma-separated list of tags for the instance or machine. | -| `--tls-ca` | `NGINX_AGENT_TLS_CA` | Specifies the path to the CA certificate file for TLS. | -| `--tls-cert` | `NGINX_AGENT_TLS_CERT` | Specifies the path to the certificate file for TLS. | -| `--tls-enable` | `NGINX_AGENT_TLS_ENABLE` | Enables TLS for secure communications. | -| `--tls-key` | `NGINX_AGENT_TLS_KEY` | Specifies the path to the certificate key file for TLS. | -| `--tls-skip-verify` | `NGINX_AGENT_TLS_SKIP_VERIFY` | Insecurely skips verification for gRPC TLS credentials. | -{{}} - -
    - -{{}} -Use the `--config-dirs` command-line option, or the `config_dirs` key in the `nginx-agent.conf` file, to identify the directories NGINX Agent can read from or write to. This setting also defines the location to which you can upload config files when using a control plane. - -NGINX Agent cannot write to directories outside the specified location when updating a config and cannot upload files to directories outside of the configured location. - -NGINX Agent follows NGINX configuration directives to file paths outside the designated directories and reads certificates' metadata. NGINX Agent uses the following directives: - -- [`ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_certificate) - -{{}} - -{{}} Use the `--dynamic-config-path` command-line option to set the location of the dynamic config file. This setting also requires you to move your dynamic config to the new path, or create a new dynamic config file at the specified location. - -Default location in Linux environments: `/var/lib/nginx-agent/agent-dynamic.conf` - -Default location in FreeBSD environments: `/var/db/nginx-agent/agent-dynamic.conf` - -{{}} - -## Logs - -NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. - -We recommend adding a separate partition for `/var/log/nginx-agent`. - -{{< 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. -{{< /important >}} - -By default, NGINX Agent rotates logs daily using logrotate with the following configuration: - -
    - NGINX Agent Logrotate Configuration - -``` yaml -/var/log/nginx-agent/*.log -{ - # log files are rotated every day - daily - # log files are rotated if they grow bigger than 5M - size 5M - # truncate the original log file after creating a copy - copytruncate - # remove rotated logs older than 10 days - maxage 10 - # log files are rotated 10 times before being removed - rotate 10 - # old log files are compressed - compress - # if the log file is missing it will go on to the next one without issuing an error message - missingok - # do not rotate the log if it is empty - notifempty -} +```bash +sudo docker run \ + --env=NGINX_AGENT_LOG_LEVEL=debug \ + -d agent ``` -
    - -If you need to change the default configuration, update the file at `/etc/logrotate.d/nginx-agent`. - -For more details on logrotate configuration, see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate). - - -## Extensions - -An extension is noncritical code to the main functionality of NGINX Agent. They generally cover functionality outside of managing NGINX configuration and reporting metrics. - -To enable an extension, it must be added to the extensions list in the `/etc/nginx-agent/nginx-agent.conf`. - -This example enables the advanced metrics extension: - -```yaml -extensions: - - advanced-metrics -``` \ No newline at end of file diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md index d95291816..d9660cc1b 100644 --- a/content/agent/install-upgrade/install.md +++ b/content/agent/install-upgrade/install.md @@ -7,6 +7,7 @@ docs: DOCS-000 This document describes the three main ways to install F5 NGINX agent: +- Using NGINX One Console - Using the NGINX Open Source repository - Using the NGINX Plus repository - Using the GitHub package files @@ -15,17 +16,34 @@ This document describes the three main ways to install F5 NGINX agent: There are a few prerequisites shared between all installation methods: +- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) - A [supported operating system and architecture](../technical-specifications/#supported-distributions) - `root` privilege -## NGINX Open Source repository - -Before you install NGINX Agent, you must install and run NGINX. - -If you don't have it installed already, read the [Installing NGINX Open Source -](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) topic. - - +When F5 NGINX Agent is installed, it will remain idle in the background. For proper functionality, two actions are required: +- **Install NGINX:** Ensure the NGINX is installed on the system. +- **Connect to the NGINX One Console:** Establish a connection between the installed NGINX instance and the NGINX One Console." + + +## Connect 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 Connect +1. Ensure the F5 NGINX Agent is installed +1. Locate the F5 NGINX Agent Configuration File: + ```bash + /etc/nginx-agent/nginx-agent.conf + ``` +1. Open the NGINX Agent configuration file in a text editor like vim: +`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 F5 NGINX Agent service: + ```bash + sudo systemctl stop nginx-agent + ``` + +## Manual Installations ### Configure NGINX OSS Repository for installing NGINX Agent 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. @@ -318,19 +336,6 @@ Before you install NGINX Agent for the first time on your system, you need to se sudo pkg install nginx-agent ``` -## NGINX Plus repository - -Before you install NGINX Agent, you must install and run NGINX Plus. - -If you don’t have it installed already, read the [Installing NGINX Plus -](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) topic. - -You will also need the following: - -- Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. -- An NGINX Plus subscription (Full or trial) -- Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. - ### Configure NGINX Plus Repository for installing NGINX Agent 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. @@ -755,7 +760,7 @@ Use your system's package manager to install the package. Some examples: sudo pkg add nginx-agent-.pkg ``` -## systemd environments +## Starting, Stopping, and Enabling NGINX Agent To start NGINX Agent on `systemd` systems, run the following command: @@ -769,16 +774,21 @@ To enable NGINX Agent to start on boot, run the following command: 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 nginx-agent -v +sudo systemctl status nginx-agent ``` -## Enable interfaces - -Once NGINX Agent is successfully running, you can enable the required interfaces, which is described in the [Enable gRPC and REST interfaces]({{< relref "/agent/how-to/enable-interfaces.md" >}}) topic. - -You may also be interested in the [Start mock control plane interface]({{< relref "/agent/contribute/start-mock-interface.md" >}}) topic for development work. \ No newline at end of file +To check the version installed, run the following command: +```shell +sudo nginx-agent -v +``` \ No newline at end of file diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/agent/install-upgrade/migrate-v3.md index 32811a075..8e557f368 100644 --- a/content/agent/install-upgrade/migrate-v3.md +++ b/content/agent/install-upgrade/migrate-v3.md @@ -6,39 +6,41 @@ docs: DOCS-000 This topic describes how to migrate from F5 NGINX Agent v2 to NGINX Agent v3. -[//]: # "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" >}}). -- -- +- 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. --- -## See also +## Rolling back from NGINX Agent v3 to v2 -[//]: # "Examples of additional topics users might want to read include:" -[//]: # "Relevant reference information, configuration options and more complex use cases." +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/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/technical-specifications.md b/content/agent/technical-specifications.md index f11a5cde4..5bcd11efc 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -1,60 +1,73 @@ --- -title: "Technical specifications" +title: "Technical Specifications" toc: true -weight: 200 +weight: 700 docs: DOCS-000 --- ## Overview -This document provides technical specifications for F5 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: +## Supported 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 >}} +The NGINX Agent is versatile and can operate across various environments. Currently, the following distributions are supported: -{{< 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 >}} +| 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 +## Supported Deployment Environments -NGINX Agent can be deployed in the following environments: +The NGINX Agent supports deployment in the following environments: -- Bare Metal -- Container -- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure -- Virtual Machine +- **Bare Metal** machines +- **Containers** +- **Public Cloud** platforms, including AWS, Google Cloud Platform, and Microsoft Azure +- **Virtual Machines** -## Supported NGINX versions +--- -NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. +## Supported NGINX Versions +The NGINX Agent is compatible with all supported releases of NGINX Open Source and NGINX Plus. + +--- -## Sizing recommendations +## Minimum System Requirements -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 >}} +Below are the recommended minimum system specifications for running the NGINX Agent: + +| **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. +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: -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). +- 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. -More information is available in the [Configuration overview]({{< relref "/agent/how-to/configuration-overview.md#logs" >}}) \ No newline at end of file +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. From 1e91a74ffc0104ea221a2216a23ddd55897b8533 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Mon, 31 Mar 2025 16:08:34 +0100 Subject: [PATCH 08/63] docs: review Agent v3 install doc (#327) * docs: review Agent v3 install doc * docs: fix link * docs: rewrite sentence * docs: move manual connect section * docs: collapse install sections * docs: replace amazon with aws icon * docs: replace with shortcode --- content/agent/install-upgrade/install.md | 972 ++++++++++-------- .../manually-connect-to-console.md | 23 + 2 files changed, 547 insertions(+), 448 deletions(-) create mode 100644 content/includes/agent/installation/manually-connect-to-console.md diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md index d9660cc1b..b903e94b9 100644 --- a/content/agent/install-upgrade/install.md +++ b/content/agent/install-upgrade/install.md @@ -5,68 +5,46 @@ weight: 100 docs: DOCS-000 --- -This document describes the three main ways to install F5 NGINX agent: +This guide walks you through the steps to install NGINX Agent using a variety +of methods: -- Using NGINX One Console -- Using the NGINX Open Source repository -- Using the NGINX Plus repository -- Using the GitHub package files +- [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 -There are a few prerequisites shared between all installation methods: +- You must use one of the [supported operating system and architectures]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) +- You need to have `root` privileges -- [NGINX One Console Getting Started]({{< relref "/nginx-one/getting-started" >}}) -- A [supported operating system and architecture](../technical-specifications/#supported-distributions) -- `root` privilege +## Install NGINX Agent using NGINX One Console -When F5 NGINX Agent is installed, it will remain idle in the background. For proper functionality, two actions are required: -- **Install NGINX:** Ensure the NGINX is installed on the system. -- **Connect to the NGINX One Console:** Establish a connection between the installed NGINX instance and the 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. -## Connect 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 Connect -1. Ensure the F5 NGINX Agent is installed -1. Locate the F5 NGINX Agent Configuration File: - ```bash - /etc/nginx-agent/nginx-agent.conf - ``` -1. Open the NGINX Agent configuration file in a text editor like vim: -`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 F5 NGINX Agent service: - ```bash - sudo systemctl stop nginx-agent - ``` - -## Manual Installations -### Configure NGINX OSS Repository for installing NGINX Agent +## 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. +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. -- [Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#install-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) -- [Install NGINX Agent on Ubuntu](#install-nginx-agent-on-ubuntu) -- [Install NGINX Agent on Debian](#install-nginx-agent-on-debian) -- [Install NGINX Agent on SLES](#install-nginx-agent-on-sles) -- [Install NGINX Agent on Alpine Linux](#install-nginx-agent-on-alpine-linux) -- [Install NGINX Agent on Amazon Linux](#install-nginx-agent-on-amazon-linux) -- [Install NGINX Agent on FreeBSD](#install-nginx-agent-on-freebsd) +
    +{{< 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 +### Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux 1. Install the prerequisites: - ```shell - sudo yum install yum-utils - ``` + ```shell + sudo yum install yum-utils + ``` -1. To set up the yum repository, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: +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/ @@ -78,355 +56,402 @@ Before you install NGINX Agent for the first time on your system, you need to se 1. To install `nginx-agent`, run the following command: - ```shell - sudo yum install nginx-agent - ``` + ```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. - 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. +
    -#### Install NGINX Agent on Ubuntu +
    +{{< 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 - ``` + ```shell + sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring + ``` -1. Import an official nginx signing key so apt could verify the packages authenticity. Fetch the key: +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 - ``` + ```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 - ``` + ```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: + 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 - ``` + ``` + 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 >}} + {{< 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 - ``` + ```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 - ``` + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
    -#### Install NGINX Agent on Debian +
    +{{< 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 - ``` + ```shell + sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring + ``` -1. Import an official nginx signing key so apt could verify the packages authenticity. Fetch the key: +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 - ``` + ```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 - ``` + ```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: + 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 - ``` + ``` + 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 >}} + {{< 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 - ``` + ```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 - ``` + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
    -#### Install NGINX Agent on SLES +
    +{{< 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 - ``` + ```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 - ``` + ```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: +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 - ``` + ```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 - ``` + ```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 - ``` + ``` + 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 - ``` + ```shell + sudo rpmkeys --import /tmp/nginx_signing.key + ``` 1. To install `nginx-agent`, run the following command: - ```shell - sudo zypper install nginx-agent - ``` + ```shell + sudo zypper install nginx-agent + ``` + +
    -#### Install NGINX Agent on Alpine Linux +
    +{{< 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 - ``` + ```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 - ``` + ```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: +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 - ``` + ```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) - ``` + ```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/ - ``` + ```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 - ``` + ```shell + sudo apk add nginx-agent + ``` +
    + +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux -#### Install NGINX Agent on Amazon Linux +### Install NGINX Agent on Amazon Linux 1. Install the prerequisites: - ```shell - sudo yum install yum-utils procps - ``` + ```shell + sudo yum install yum-utils procps + ``` -1. To set up the yum repository for Amazon Linux 2, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: - ``` - [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 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 - ``` + ```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. +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. -#### Install NGINX Agent on FreeBSD +
    +
    +{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD -1. To setup the pkg repository create the file named `/etc/pkg/nginx-agent.conf` with the following content: +### Install NGINX Agent on FreeBSD - ``` - nginx-agent: { - URL: pkg+http://packages.nginx.org/nginx-agent/freebsd/${ABI}/latest - ENABLED: true - MIRROR_TYPE: SRV - } - ``` +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 - ``` + ```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 -### Configure NGINX Plus Repository for installing NGINX Agent +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. -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. -- [Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux](#install-nginx-agent-on-rhel-centos-rocky-linux-almalinux-and-oracle-linux) -- [Install NGINX Agent on Ubuntu](#install-nginx-agent-on-ubuntu) -- [Install NGINX Agent on Debian](#install-nginx-agent-on-debian) -- [Install NGINX Agent on SLES](#install-nginx-agent-on-sles) -- [Install NGINX Agent on Alpine Linux](#install-nginx-agent-on-alpine-linux) -- [Install NGINX Agent on Amazon Linux](#install-nginx-agent-on-amazon-linux) -- [Install NGINX Agent on FreeBSD](#install-nginx-agent-on-freebsd) +
    +{{< 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 +### 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 - ``` + ```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. 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/ - ``` + ```shell + sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/ + ``` 1. Install the prerequisites: - ```shell - sudo yum install yum-utils procps - ``` + ```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`: +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 - ``` + ```shell + sudo vi /etc/yum.repos.d/nginx-agent.repo + ``` 1. Add the following lines to `nginx-agent.repo`: - ``` - [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 - ``` + ```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 - ``` + ```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. + +
    - 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 +### Install NGINX Agent on Ubuntu 1. Create the `/etc/ssl/nginx` directory: - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` + ```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/ - ``` + ```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 - ``` + 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 - ``` + ```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"; @@ -435,308 +460,354 @@ Before you install NGINX Agent for the first time on your system, you need to se 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 - ``` + ```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 - ``` + ```shell + sudo apt update + sudo apt install nginx-agent + ``` + +
    + +
    +{{< fa "brands fa-debian" >}} Install NGINX Agent on 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 - ``` + ```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. 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/ - ``` + ```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 - ``` + ```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 - ``` + ```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`: - ``` - 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"; - ``` + ```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 - ``` + ```shell + sudo apt update + sudo apt install nginx-agent + ``` -#### Install NGINX Agent on SLES +
    + +
    +{{< 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 - ``` + ```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. 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/ - ``` + ```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 - ``` + ```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 - ``` + ```shell + sudo zypper install curl ca-certificates gpg2 gawk + ``` -1. To set up the zypper repository for `nginx-agent` packages, run the following command: +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 - ``` + ```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: +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 - ``` + ```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 - ``` + ```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: +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 - ``` + ```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 - ``` + ```shell + sudo rpmkeys --import /tmp/nginx_signing.key + ``` 1. To install `nginx-agent`, run the following command: - ```shell - sudo zypper install nginx-agent - ``` + ```shell + sudo zypper install nginx-agent + ``` -#### 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. +
    +{{< 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 - ``` + ```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 - ``` + ```shell + sudo apk add openssl curl ca-certificates + ``` -1. To set up the apk repository for `nginx-agent` packages, run the following command: +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 - ``` + ```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 - ``` + ```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) - ``` + ```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/ - ``` + ```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 - ``` + ```shell + sudo apk add nginx-agent + ``` + +
    +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux -#### 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 - ``` + ```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. 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: +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/ - ``` + ```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 - ``` + ```shell + sudo yum install yum-utils procps ca-certificates + ``` -1. To set up the yum repository for Amazon Linux 2, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents: +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: - ``` - [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 - ``` + ```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 - ``` + ```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. + +
    -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 +### Install NGINX Agent on FreeBSD 1. Create the `/etc/ssl/nginx` directory: - ```shell - sudo mkdir -p /etc/ssl/nginx - ``` + ```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. 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/ - ``` + ```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 - ``` + ```shell + sudo pkg install ca_root_nss + ``` -1. To setup the pkg repository create the file named `/etc/pkg/nginx-agent.conf` with the following content: +1. To setup the pkg repository create a file with name `/etc/pkg/nginx-agent.conf` +with the following content: - ``` - nginx-agent: { - URL: pkg+https://pkgs.nginx.com/nginx-agent/freebsd/${ABI}/latest - ENABLED: yes - MIRROR_TYPE: SRV - } - ``` + ```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: - ``` - 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" } - ``` + ```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 - ``` + ```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, 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. +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 - ``` + ```shell + sudo dpkg -i nginx-agent-.deb + ``` -- RHEL, CentOS RHEL, Amazon Linux, Oracle Linux, and other distributions using the `yum` package manager +- RHEL, CentOS RHEL, Amazon Linux, Oracle Linux, and other distributions using + the `yum` package manager ```shell sudo yum localinstall nginx-agent-.rpm @@ -760,7 +831,11 @@ Use your system's package manager to install the package. Some examples: sudo pkg add nginx-agent-.pkg ``` -## Starting, Stopping, and Enabling NGINX Agent +### 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: @@ -782,7 +857,8 @@ 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: +Once you have installed NGINX Agent, you can verify that it is running with the +following command: ```shell sudo systemctl status nginx-agent @@ -791,4 +867,4 @@ sudo systemctl status nginx-agent To check the version installed, run the following command: ```shell sudo nginx-agent -v -``` \ 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 From d9609a5d6c88a09ffbe614a1a5ee2741d9b3a48e Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 1 Apr 2025 12:00:50 +0100 Subject: [PATCH 09/63] docs: Change root wording agent (#339) * fix: root requirements for agent install * fix: bold not --- content/agent/install-upgrade/install.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md index b903e94b9..66bca2ae9 100644 --- a/content/agent/install-upgrade/install.md +++ b/content/agent/install-upgrade/install.md @@ -15,7 +15,8 @@ of methods: ## Before you begin - You must use one of the [supported operating system and architectures]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) -- You need to have `root` privileges +- 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 From 13db0c633251da99f38a089791d82013bdfe4237 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Thu, 3 Apr 2025 16:18:54 +0100 Subject: [PATCH 10/63] docs: update agent v3 support doc (#357) --- content/agent/support.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/content/agent/support.md b/content/agent/support.md index 0c7fff1bf..6ea9d3af6 100644 --- a/content/agent/support.md +++ b/content/agent/support.md @@ -1,15 +1,20 @@ --- title: Support weight: 800 -docs: DOCS-000 +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). + +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). \ No newline at end of file +- If you have any suggestions or feature requests, please [open an idea in GitHub discussions](https://github.com/nginx/agent/discussions). From e0003e047e519b64c334ef037ad59094b3913b8d Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 1 Apr 2025 12:00:50 +0100 Subject: [PATCH 11/63] docs: Change root wording agent (#339) * fix: root requirements for agent install * fix: bold not --- content/agent/about.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/content/agent/about.md b/content/agent/about.md index 022dcdd90..2ea284ef9 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -42,5 +42,39 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX {{< img src="agent-flow.png" caption="How Agent works" alt="How NGINX Agent works" width="99%">}} +```mermaid +graph BT + + %% Define colors for the subgraphs + style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000 + style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 + style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style Logs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + + subgraph ManagementPlane["Management Plane"] + CommandControl["Command Server"] + OTelManagementPlane["OTel Receiver"] + end + + subgraph Compute["NGINX Instance"] + subgraph Agent["Agent Process"] + OTelDataPlane["OTel Collector"] + end + + NGINX["NGINX Process"] + NGINXConfig["NGINX Config Files"] + Logs["NGINX Logs"] + + Agent --> |Watch/Reload| NGINX + Agent <--> |Reads/Writes| Logs + Agent <--> |Reads/Writes| NGINXConfig + OTelDataPlane --> |Collects| Metrics["Host Metrics"] + OTelDataPlane --> |Reads| NGINXMetrics["NGINX Metrics"] + end + + Compute <--> |gRPC| ManagementPlane +``` --- From e8c3f327ed66c59a5c0687234eddfa98606420e9 Mon Sep 17 00:00:00 2001 From: Christopher van de Sande Date: Tue, 1 Apr 2025 18:16:24 +0200 Subject: [PATCH 12/63] Add Agent V3 Diagram --- content/agent/about.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/content/agent/about.md b/content/agent/about.md index 2ea284ef9..80ece1071 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -47,15 +47,17 @@ graph BT %% Define colors for the subgraphs style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000 + style CommandControl fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 + style OTelManagementPlane fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - style Logs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 subgraph ManagementPlane["Management Plane"] CommandControl["Command Server"] - OTelManagementPlane["OTel Receiver"] + OTelManagementPlane["OTel Collector"] end subgraph Compute["NGINX Instance"] @@ -63,15 +65,18 @@ graph BT OTelDataPlane["OTel Collector"] end - NGINX["NGINX Process"] - NGINXConfig["NGINX Config Files"] - Logs["NGINX Logs"] + subgraph NGINX["NGINX Process"] + NGINXMetrics["Metrics"] + end + NGINXConfig["NGINX Configuration Files"] + ErrorLogs["NGINX Error Logs"] + Metrics["Host Metrics"] --> |Collects| OTelDataPlane + NGINXMetrics --> |Reads| OTelDataPlane["OTel Collector"] Agent --> |Watch/Reload| NGINX - Agent <--> |Reads/Writes| Logs + Agent --> |Reads| ErrorLogs + OTelDataPlane --> |Reads| AccessLogs["NGINX Access Logs"] Agent <--> |Reads/Writes| NGINXConfig - OTelDataPlane --> |Collects| Metrics["Host Metrics"] - OTelDataPlane --> |Reads| NGINXMetrics["NGINX Metrics"] end Compute <--> |gRPC| ManagementPlane From d959cea5157acb01107781e4a7371aa8da2fb918 Mon Sep 17 00:00:00 2001 From: Christopher van de Sande Date: Thu, 3 Apr 2025 15:51:13 +0100 Subject: [PATCH 13/63] Add Agent V3 diagram description --- content/agent/about.md | 27 +++++++++++++++++---------- go.mod | 2 +- go.sum | 2 ++ 3 files changed, 20 insertions(+), 11 deletions(-) diff --git a/content/agent/about.md b/content/agent/about.md index 80ece1071..9ac39897c 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -21,9 +21,7 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX - [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 @@ -36,12 +34,9 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX - 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%">}} +### How Agent works +--- ```mermaid graph BT @@ -55,9 +50,9 @@ graph BT style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - subgraph ManagementPlane["Management Plane"] + subgraph ManagementPlane["NGINX One"] CommandControl["Command Server"] - OTelManagementPlane["OTel Collector"] + OTelManagementPlane["OTel Receiver"] end subgraph Compute["NGINX Instance"] @@ -81,5 +76,17 @@ graph BT Compute <--> |gRPC| ManagementPlane ``` ---- + +The figure shows: + +- An NGINX Instance running on bare metal, virtual machine or container +- The NGINX One Cloud Console includes: + - Command Server to manage NGINX configurations, push new/updated configuration files remotely, perform integrity tests, and automatically roll back to last good configuration if issues are detected. + - OpenTelemetry (OTel) Receiver that receives observability data from connected Agent instances. +- An Agent Process running on the NGINX Instance. The Agent is responsible for: + - Watching, applying, validating, and managing rollback operations on NGINX configuration files. + - Embedding an OpenTelemetry Collector, collecting metrics from both NGINX processes and host system performance data, then securely passing metric data to the NGINX One Cloud Console. +- Collection and monitoring of Host Metrics (CPU usage, Memory utilization, Disk I/O). +- Management and troubleshooting features leveraging NGINX Configuration Files, NGINX Logs (both access and error), and process-level metrics. +- Collected data is made available on the NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. diff --git a/go.mod b/go.mod index 96da5bb32..90217f278 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.24 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.25 // indirect diff --git a/go.sum b/go.sum index 55949eecc..10bea363f 100644 --- a/go.sum +++ b/go.sum @@ -4,3 +4,5 @@ github.com/nginxinc/nginx-hugo-theme v0.41.27 h1:M8ttO1ZkTGY06o0MYvnm3kc/sA6lOmI 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= +github.com/nginxinc/nginx-hugo-theme v0.42.25 h1:QkLTREuOohkq+hmBZCfWELAri4AOvhc6gmIJA1esUfo= +github.com/nginxinc/nginx-hugo-theme v0.42.25/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From 60879a8257777375f3446f1d2cc751b990239ace Mon Sep 17 00:00:00 2001 From: Christopher van de Sande Date: Fri, 4 Apr 2025 15:02:59 +0100 Subject: [PATCH 14/63] change wording based on feedback --- content/agent/about.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/agent/about.md b/content/agent/about.md index 9ac39897c..aa3bc4889 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -81,12 +81,11 @@ The figure shows: - An NGINX Instance running on bare metal, virtual machine or container - The NGINX One Cloud Console includes: - - Command Server to manage NGINX configurations, push new/updated configuration files remotely, perform integrity tests, and automatically roll back to last good configuration if issues are detected. + - Command Server to manage NGINX configurations, push new/updated configuration files remotely, and perform integrity tests. - OpenTelemetry (OTel) Receiver that receives observability data from connected Agent instances. -- An Agent Process running on the NGINX Instance. The Agent is responsible for: - - Watching, applying, validating, and managing rollback operations on NGINX configuration files. - - Embedding an OpenTelemetry Collector, collecting metrics from both NGINX processes and host system performance data, then securely passing metric data to the NGINX One Cloud Console. -- Collection and monitoring of Host Metrics (CPU usage, Memory utilization, Disk I/O). -- Management and troubleshooting features leveraging NGINX Configuration Files, NGINX Logs (both access and error), and process-level metrics. +- An Agent process running on the NGINX Instance. The Agent is responsible for: + - Watching, applying, validating, automatically roll back to last good configuration if issues are detected. + - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to the NGINX One Cloud Console. +- Collection and monitoring of host metrics (CPU usage, Memory utilization, Disk I/O) by the Agent OTel collector. - Collected data is made available on the NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. From 8ec364633c5386a73fd9fa665af472cad4027e30 Mon Sep 17 00:00:00 2001 From: Christopher van de Sande Date: Mon, 7 Apr 2025 13:55:08 +0100 Subject: [PATCH 15/63] Address PR feedback --- content/agent/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent/about.md b/content/agent/about.md index aa3bc4889..512ab92e9 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -36,7 +36,7 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX - Collected metrics can be seamlessly exported to the NGINX One Console or integrated with third-party data aggregators. ### How Agent works ---- + ```mermaid graph BT From fa9dc451628820f22a425f76475dffba3220fcbb Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 8 Apr 2025 13:33:52 +0100 Subject: [PATCH 16/63] docs: about formatting (#375) * docs: about formatting * fix: product name * fix: fix product name --- content/agent/about.md | 29 ++++++++++++++--------------- go.mod | 2 +- go.sum | 2 ++ 3 files changed, 17 insertions(+), 16 deletions(-) diff --git a/content/agent/about.md b/content/agent/about.md index 512ab92e9..f6449b15d 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -8,16 +8,16 @@ 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. +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. +## 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. +- 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. @@ -25,17 +25,17 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX ### Configuration management -- The F5 NGINX Agent provides an interface that enables users to deploy configuration changes to NGINX from a centralized management plane. +- 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. +- 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. -### How Agent works +## How NGINX Agent works ```mermaid graph BT @@ -83,9 +83,8 @@ The figure shows: - The NGINX One Cloud Console includes: - Command Server to manage NGINX configurations, push new/updated configuration files remotely, and perform integrity tests. - OpenTelemetry (OTel) Receiver that receives observability data from connected Agent instances. -- An Agent process running on the NGINX Instance. The Agent is responsible for: +- An NGINX Agent process running on the NGINX instance. NGINX Agent is responsible for: - Watching, applying, validating, automatically roll back to last good configuration if issues are detected. - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to the NGINX One Cloud Console. - Collection and monitoring of host metrics (CPU usage, Memory utilization, Disk I/O) by the Agent OTel collector. - Collected data is made available on the NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. - diff --git a/go.mod b/go.mod index 90217f278..a3d4d13aa 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.25 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.26 // indirect diff --git a/go.sum b/go.sum index 10bea363f..8ff764f5f 100644 --- a/go.sum +++ b/go.sum @@ -6,3 +6,5 @@ github.com/nginxinc/nginx-hugo-theme v0.42.24 h1:aQkkTob0EpK+1ID+31E3y+RIdThldC4 github.com/nginxinc/nginx-hugo-theme v0.42.24/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.25 h1:QkLTREuOohkq+hmBZCfWELAri4AOvhc6gmIJA1esUfo= github.com/nginxinc/nginx-hugo-theme v0.42.25/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.26 h1:DCJMXt/l3DY646sB+RgojnSRaWPNAz9o6imKfXZF8gA= +github.com/nginxinc/nginx-hugo-theme v0.42.26/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From e77cab59dab3dffd9fe4aa2f087240a4d1a7f665 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Wed, 9 Apr 2025 12:58:07 +0100 Subject: [PATCH 17/63] docs: Agent v3 tech spec (#382)hhhhhhhhhhhhhhhhhhhhhhhh * docs: update agent v3 tech specs * docs: fix moved v2 path * Update content/agent/technical-specifications.md Co-authored-by: yar * Update content/agent/technical-specifications.md Co-authored-by: yar * Update content/agent/technical-specifications.md Co-authored-by: yar --------- Co-authored-by: yar --- content/agent/technical-specifications.md | 70 +++---------------- .../installation-unprivileged.md | 4 +- .../nginx-plus/supported-distributions.md | 20 ++++++ content/nginx/technical-specs.md | 16 +---- 4 files changed, 33 insertions(+), 77 deletions(-) create mode 100644 content/includes/nginx-plus/supported-distributions.md diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index 5bcd11efc..d765798c0 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -5,69 +5,19 @@ weight: 700 docs: DOCS-000 --- -## Overview +NGINX Agent is designed to operate efficiently on any system that meets the standard +hardware requirements for running NGINX Plus itself. This ensures compatibility, stability, +and performance aligned with the NGINX core platform: -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 ---- - -## Supported Distributions - -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 - -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** - ---- - -## Supported NGINX Versions - -The NGINX Agent is compatible with all supported releases of NGINX Open Source and NGINX Plus. - ---- - -## Minimum System Requirements - -Below are the recommended minimum system specifications for running the NGINX Agent: - -| **Resource** | **Minimum Requirement** | -|--------------|--------------------------| -| **CPU** | 1 CPU core | -| **Memory** | 1 GB RAM | -| **Network** | 1 GbE NIC | -| **Storage** | 20 GB | - ---- - -## Logging +{{< include "nginx-plus/supported-distributions.md" >}} -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 see the detailed technical specifications for NGINX Plus, refer to the official +[NGINX Plus documentation]({{< ref "/nginx/technical-specs.md" >}}). -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. +### Recommended hardware -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 +For recommended hardware, see the +[Sizing guide for deploying NGINX Plus on bare metal servers](https://www.f5.com/pdf/deployment-guide/Sizing-Guide-for-Deploying-NGINX-Plus-on-Bare-Metal-Servers-2019-11-09.pdf). diff --git a/content/agent/v2/installation-upgrade/installation-unprivileged.md b/content/agent/v2/installation-upgrade/installation-unprivileged.md index 137bdf752..e32029d9d 100644 --- a/content/agent/v2/installation-upgrade/installation-unprivileged.md +++ b/content/agent/v2/installation-upgrade/installation-unprivileged.md @@ -29,12 +29,12 @@ The installation process involves installing NGINX Plus without root privileges You can install NGINX Plus without root privileges following the steps on the [NGINX Plus installation page]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus/#unpriv_install" >}}). The steps include a script that will allow you to install NGINX Plus in a non-root environment. {{< note >}} -NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group. +NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/v2/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group. {{< /note >}} ### Install NGINX Agent -After installing NGINX Plus, you can install NGINX agent following the steps on the [NGINX Agent installation page]({{< ref "/agent/installation-upgrade/installation-oss.md" >}}). +After installing NGINX Plus, you can install NGINX agent following the steps on the [NGINX Agent installation page]({{< ref "/agent/v2/installation-upgrade/installation-oss.md" >}}). ### Start NGINX Agent diff --git a/content/includes/nginx-plus/supported-distributions.md b/content/includes/nginx-plus/supported-distributions.md new file mode 100644 index 000000000..86439439b --- /dev/null +++ b/content/includes/nginx-plus/supported-distributions.md @@ -0,0 +1,20 @@ +--- +docs: +--- + +{{}} +| Distribution | Supported on R33 | Supported on R32 | +|-------------------------------------|-----------------------------------------------|-----------------------------------------------| +| AlmaLinux | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | +| Alpine Linux | 3.17 (x86_64, aarch64) **(deprecated)**
    3.18 (x86_64, aarch64)
    3.19 (x86_64, aarch64)
    3.20 (x86_64, aarch64) **(new)** | 3.16 (x86_64, aarch64) **(deprecated)**
    3.17 (x86_64, aarch64)
    3.18 (x86_64, aarch64)
    3.19 (x86_64, aarch64) | +| Amazon Linux | 2023 (x86_64, aarch64) | 2023 (x86_64, aarch64) | +| Amazon Linux 2 | LTS (x86_64, aarch64) | LTS (x86_64, aarch64) | +| CentOS | **Not supported** | 7.4+ (x86_64) **(deprecated)** | +| Debian | 11 (x86_64, aarch64)
    12 (x86_64, aarch64) | 11 (x86_64, aarch64)
    12 (x86_64, aarch64) | +| FreeBSD | 13 (amd64)
    14 (amd64) | 13 (amd64)
    14 (amd64) | +| Oracle Linux | 8.1+ (x86_64, aarch64)
    9 (x86_64) | 7.4+ (x86_64) **(deprecated)**
    8.1+ (x86_64, aarch64)
    9 (x86_64) | +| Red Hat Enterprise Linux (RHEL) | 8.1+ (x86_64, aarch64)
    9.0+ (x86_64, aarch64) | 7.4+ (x86_64) **(deprecated)**
    8.1+ (x86_64, aarch64)
    9.0+ (x86_64, aarch64) | +| Rocky Linux | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | +| SUSE Linux Enterprise Server (SLES) | 12 SP5 (x86_64) **(deprecated)**
    15 SP2+ (x86_64) | 12 SP5 (x86_64)
    15 SP2+ (x86_64) | +| Ubuntu | 20.04 LTS (x86_64, aarch64)
    22.04 LTS (x86_64, aarch64)
    24.04 LTS (x86_64, aarch64) | 20.04 LTS (x86_64, aarch64)
    22.04 LTS (x86_64, aarch64)
    24.04 LTS (x86_64, aarch64 **(new)** | +{{    }} \ No newline at end of file diff --git a/content/nginx/technical-specs.md b/content/nginx/technical-specs.md index c65fcb06d..1c7dd479f 100644 --- a/content/nginx/technical-specs.md +++ b/content/nginx/technical-specs.md @@ -14,21 +14,7 @@ NGINX Plus is available only as a binary; it is not distributed as source code. ## Supported Distributions {#supported-distributions} -{{}} -| Distribution | Supported on R34 | Supported on R33 | -|-------------------------------------|----------------------------------------------------|--------------------------------------------------------| -| AlmaLinux | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | -| Alpine Linux | 3.18 (x86_64, aarch64) **(deprecated)**
    3.19 (x86_64, aarch64)
    3.20 (x86_64, aarch64)
    3.21 (x86_64, aarch64) **(new)** | 3.17 (x86_64, aarch64) **(deprecated)**
    3.18 (x86_64, aarch64)
    3.19 (x86_64, aarch64)
    3.20 (x86_64, aarch64) **(new)** | -| Amazon Linux | 2023 (x86_64, aarch64) | 2023 (x86_64, aarch64) | -| Amazon Linux 2 | LTS (x86_64, aarch64) | LTS (x86_64, aarch64) | -| Debian | 11 (x86_64, aarch64)
    12 (x86_64, aarch64) | 11 (x86_64, aarch64)
    12 (x86_64, aarch64) | -| FreeBSD | 13 (amd64)
    14 (amd64) | 13 (amd64)
    14 (amd64) | -| Oracle Linux | 8.1+ (x86_64, aarch64)
    9 (x86_64) | 8.1+ (x86_64, aarch64)
    9 (x86_64) | -| Red Hat Enterprise Linux (RHEL) | 8.1+ (x86_64, aarch64)
    9.0+ (x86_64, aarch64) | 8.1+ (x86_64, aarch64)
    9.0+ (x86_64, aarch64) | -| Rocky Linux | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | 8 (x86_64, aarch64)
    9 (x86_64, aarch64) | -| SUSE Linux Enterprise Server (SLES) | 15 SP2+ (x86_64) | 12 SP5 (x86_64) **(deprecated)**
    15 SP2+ (x86_64) | -| Ubuntu | 20.04 LTS (x86_64, aarch64) **(deprecated)**
    22.04 LTS (x86_64, aarch64)
    24.04 LTS (x86_64, aarch64) | 20.04 LTS (x86_64, aarch64)
    22.04 LTS (x86_64, aarch64)
    24.04 LTS (x86_64, aarch64) | -{{    }} +{{< include "nginx-plus/supported-distributions.md" >}} --- From 7b76e795ae83765626365bf28106be67e6fedd4a Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Mon, 14 Apr 2025 10:06:16 +0100 Subject: [PATCH 18/63] Update metrics docs, add run-container guide (#352) * Update metrics docs, add run-container guide * Apply suggestion to update metadata for how-to guide. Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion to update markdown format, and code block Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion to update locating config file Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion to title Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion to title Co-authored-by: Alan Dooley * Apply suggestion to sentence. Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion to use correct note element Co-authored-by: Alan Dooley * Apply suggestion Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Apply suggestion Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/how-to/run-agent-container.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> * docs: Change Container to container, based on PR feedback * Update content/agent/otel/configure-otel-metrics.md Co-authored-by: yar * Apply suggestions from code review Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> * docs: improve layout --------- Co-authored-by: Jon Torre <78599298+JTorreG@users.noreply.github.com> Co-authored-by: Alan Dooley Co-authored-by: yar Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> Co-authored-by: Jon Cahill-Torre --- content/agent/how-to/export-metrics.md | 45 ---- content/agent/how-to/run-agent-container.md | 105 +++++++++ content/agent/otel/configure-otel-metrics.md | 228 ++----------------- content/agent/otel/metrics.md | 5 - 4 files changed, 124 insertions(+), 259 deletions(-) delete mode 100644 content/agent/how-to/export-metrics.md create mode 100644 content/agent/how-to/run-agent-container.md delete mode 100644 content/agent/otel/metrics.md diff --git a/content/agent/how-to/export-metrics.md b/content/agent/how-to/export-metrics.md deleted file mode 100644 index 9edae11dc..000000000 --- a/content/agent/how-to/export-metrics.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -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/how-to/run-agent-container.md b/content/agent/how-to/run-agent-container.md new file mode 100644 index 000000000..09c7397c6 --- /dev/null +++ b/content/agent/how-to/run-agent-container.md @@ -0,0 +1,105 @@ +--- +title: "Run the NGINX Agent in a container" +weight: 300 +toc: true +type: how-to +product: Agent +--- + +## Overview + +This guide serves as a step-by-step guide to run NGINX Agent in a container. It covers the basic setup needed to get the NGINX Agent up and running efficiently and securely. + +## Before you begin + +Before you begin this guide ensure: + +{{< note >}} +This guide uses Docker but NGINX Agent also works with other container applications. +{{< /note >}} + +- **Docker:** Ensure Docker is installed and configured on your system. [Download Docker from the official site](https://www.docker.com/products/docker-desktop/). +- **Credentials:** Acquire any necessary authentication tokens or credentials required for the NGINX Agent. + +## Prepare the environment + +To run NGINX Agent in a container you will need to download the NGINX Agent +container image and create a configuration file. + +### Pull the NGINX Agent container image + +The NGINX 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. + + +### Create a configuration file + +Create a configuration file named `nginx-agent.conf` in your current directory +and populate the file with the following structure: + +```yaml +command: + server: + host: "" # Command server host + port: 443 # Command server port + auth: + token: "" # Authentication token for the command server + tls: + skip_verify: false +``` + +Replace the placeholder values: + +- ``: The URL of your NGINX One Console instance. +- ``: Your Data Plane access token. + + +## 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. + + +### 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 indicates that the container is running. + +### 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. diff --git a/content/agent/otel/configure-otel-metrics.md b/content/agent/otel/configure-otel-metrics.md index cac034103..0e302b7a4 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/agent/otel/configure-otel-metrics.md @@ -1,229 +1,39 @@ --- -title: Metrics Export +title: Export metrics with NGINX Agent 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: +F5 NGINX Agent 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 +* Metrics from NGINX Plus and NGINX Open Source * 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. +{{< note >}} +The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. +{{< /note >}} -# Key Benefits +### 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 +### Verify that metrics are exported -Before you begin configuring the F5 NGINX Agent OTel Collector: +You can validate that metrics are successfully exported by using the methods below: -- [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 +- **NGINX One dashboard** + - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. -## Configure the OTel Collector - Virtual Machine +- **Agent logs** -1. Locate the configuration file for the F5 NGINX Agent: + Check the OpenTelemetry Collector logs for confirmation of successful metric processing: - ```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 + 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` + 2. Look for the following logs: + + ```text + Everything is ready. Begin running and processing data. + ``` \ No newline at end of file diff --git a/content/agent/otel/metrics.md b/content/agent/otel/metrics.md deleted file mode 100644 index 179f413b9..000000000 --- a/content/agent/otel/metrics.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: OpenTelemetry metrics -weight: 300 -docs: DOCS-000 ---- \ No newline at end of file From b7dcd9561c13d183331daca4c3db77513391ee4d Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Tue, 22 Apr 2025 11:57:57 +0100 Subject: [PATCH 19/63] docs: Agent v3 docs to includes (#418) * docs: move agent content to includes and n1 * fix: move agent section * fix: relref to ref --- content/agent/about.md | 4 +- content/agent/changelog.md | 2 +- .../agent/contribute/dev-environment-setup.md | 4 +- .../agent/contribute/start-mock-interface.md | 4 +- content/agent/how-to/enable-interfaces.md | 2 +- content/agent/install-upgrade/_index.md | 2 +- .../install-upgrade/install-from-github.md | 72 ++ .../install-upgrade/install-from-oss-repo.md | 103 +++ .../install-upgrade/install-from-plus-repo.md | 104 +++ content/agent/install-upgrade/install.md | 871 ------------------ content/agent/install-upgrade/uninstall.md | 128 +-- content/agent/install-upgrade/update.md | 14 + content/agent/install-upgrade/upgrade.md | 78 -- content/agent/tech-specs.md | 8 + content/agent/v2/changelog.md | 2 +- .../container-environments/docker-images.md | 4 +- .../container-environments/docker-support.md | 4 +- .../installation-upgrade/getting-started.md | 2 +- .../installation-upgrade/installation-oss.md | 2 +- .../installation-upgrade/installation-plus.md | 2 +- .../agent/installation/oss/oss-alpine.md | 73 ++ .../installation/oss/oss-amazon-linux.md | 34 + .../agent/installation/oss/oss-debian.md | 52 ++ .../agent/installation/oss/oss-freebsd.md | 23 + .../agent/installation/oss/oss-rhel.md | 33 + .../agent/installation/oss/oss-sles.md | 52 ++ .../agent/installation/oss/oss-ubuntu.md | 50 + .../agent/installation/plus/plus-alpine.md | 83 ++ .../installation/plus/plus-amazon-linux.md | 50 + .../agent/installation/plus/plus-debian.md | 50 + .../agent/installation/plus/plus-freebsd.md | 52 ++ .../agent/installation/plus/plus-rhel.md | 55 ++ .../agent/installation/plus/plus-sles.md | 75 ++ .../agent/installation/plus/plus-ubuntu.md | 55 ++ .../agent/installation/prerequisites.md | 13 + .../agent/installation/start-stop-agent.md | 27 + .../uninstall/uninstall-alpine.md | 20 + .../uninstall/uninstall-amazon-linux.md | 20 + .../uninstall/uninstall-debian.md | 22 + .../uninstall/uninstall-freebsd.md | 20 + .../installation/uninstall/uninstall-rhel.md | 20 + .../installation/uninstall/uninstall-sles.md | 20 + .../uninstall/uninstall-ubuntu.md | 22 + .../agent/installation/update-container.md} | 32 +- content/includes/agent/installation/update.md | 43 + .../agent/installation/verify-agent.md | 21 + .../agent/tech-specs.md} | 10 +- .../includes/nginx-one/how-to/add-instance.md | 23 + content/nginx-one/agent/_index.md | 6 + .../agent/connect-instances-to-console.md | 8 + .../nginx-one/agent/install-from-oss-repo.md | 101 ++ .../nginx-one/agent/install-from-plus-repo.md | 102 ++ content/nginx-one/agent/tech-specs.md | 8 + content/nginx-one/agent/uninstall.md | 81 ++ content/nginx-one/agent/update.md | 12 + content/nginx-one/glossary.md | 2 +- .../how-to/nginx-configs/add-instance.md | 20 +- 57 files changed, 1688 insertions(+), 1114 deletions(-) create mode 100644 content/agent/install-upgrade/install-from-github.md create mode 100644 content/agent/install-upgrade/install-from-oss-repo.md create mode 100644 content/agent/install-upgrade/install-from-plus-repo.md delete mode 100644 content/agent/install-upgrade/install.md create mode 100644 content/agent/install-upgrade/update.md delete mode 100644 content/agent/install-upgrade/upgrade.md create mode 100644 content/agent/tech-specs.md create mode 100644 content/includes/agent/installation/oss/oss-alpine.md create mode 100644 content/includes/agent/installation/oss/oss-amazon-linux.md create mode 100644 content/includes/agent/installation/oss/oss-debian.md create mode 100644 content/includes/agent/installation/oss/oss-freebsd.md create mode 100644 content/includes/agent/installation/oss/oss-rhel.md create mode 100644 content/includes/agent/installation/oss/oss-sles.md create mode 100644 content/includes/agent/installation/oss/oss-ubuntu.md create mode 100644 content/includes/agent/installation/plus/plus-alpine.md create mode 100644 content/includes/agent/installation/plus/plus-amazon-linux.md create mode 100644 content/includes/agent/installation/plus/plus-debian.md create mode 100644 content/includes/agent/installation/plus/plus-freebsd.md create mode 100644 content/includes/agent/installation/plus/plus-rhel.md create mode 100644 content/includes/agent/installation/plus/plus-sles.md create mode 100644 content/includes/agent/installation/plus/plus-ubuntu.md create mode 100644 content/includes/agent/installation/prerequisites.md create mode 100644 content/includes/agent/installation/start-stop-agent.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-alpine.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-amazon-linux.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-debian.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-freebsd.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-rhel.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-sles.md create mode 100644 content/includes/agent/installation/uninstall/uninstall-ubuntu.md rename content/{agent/install-upgrade/migrate-v3.md => includes/agent/installation/update-container.md} (58%) create mode 100644 content/includes/agent/installation/update.md create mode 100644 content/includes/agent/installation/verify-agent.md rename content/{agent/technical-specifications.md => includes/agent/tech-specs.md} (82%) create mode 100644 content/includes/nginx-one/how-to/add-instance.md create mode 100644 content/nginx-one/agent/_index.md create mode 100644 content/nginx-one/agent/connect-instances-to-console.md create mode 100644 content/nginx-one/agent/install-from-oss-repo.md create mode 100644 content/nginx-one/agent/install-from-plus-repo.md create mode 100644 content/nginx-one/agent/tech-specs.md create mode 100644 content/nginx-one/agent/uninstall.md create mode 100644 content/nginx-one/agent/update.md diff --git a/content/agent/about.md b/content/agent/about.md index f6449b15d..10c192d8c 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -14,12 +14,12 @@ The F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX - 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" >}}) + - [Connect to NGINX One Console]({{< ref "/agent/install-upgrade/install-from-oss-repo.md#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. + - [OpenTelemetry](https://opentelemetry.io/) support comes with F5 NGINX Agent, and the ability to [export the metrics data]({{< ref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications. diff --git a/content/agent/changelog.md b/content/agent/changelog.md index e75b2496b..8b5e6ebcd 100644 --- a/content/agent/changelog.md +++ b/content/agent/changelog.md @@ -6,7 +6,7 @@ toc: true {{< 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" >}}). +See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "./tech-specs.md" >}}). --- ## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) diff --git a/content/agent/contribute/dev-environment-setup.md b/content/agent/contribute/dev-environment-setup.md index 2e9fe571c..0c2f06315 100644 --- a/content/agent/contribute/dev-environment-setup.md +++ b/content/agent/contribute/dev-environment-setup.md @@ -17,7 +17,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}). - 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. @@ -29,7 +29,7 @@ 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 -Follow the steps in the [Installation]({{< relref "/agent/install-upgrade/install.md" >}}) topic to install NGINX Agent. +Follow the steps in the [Installation]({{< ref "/agent/install-upgrade/" >}}) topic to install NGINX Agent. ## Install prerequisite packages Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent. diff --git a/content/agent/contribute/start-mock-interface.md b/content/agent/contribute/start-mock-interface.md index 5b2a7e585..032421862 100644 --- a/content/agent/contribute/start-mock-interface.md +++ b/content/agent/contribute/start-mock-interface.md @@ -13,7 +13,7 @@ The mock interface is useful when developing NGINX Agent, as it allows you to vi To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< relref "/agent/install-upgrade/install.md" >}}). +- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}). - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. - A [go-swagger](https://goswagger.io/go-swagger/install/) installation. @@ -39,7 +39,7 @@ INFO[0000] grpc listening at 54789 # grpc control plane port which NGINX Agent w 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. +To enable them, view the [Enable gRPC and REST interfaces]({{< ref "/agent/how-to/enable-interfaces.md" >}}) topic. ## Launch Swagger UI diff --git a/content/agent/how-to/enable-interfaces.md b/content/agent/how-to/enable-interfaces.md index fbd174e30..a0e6c553c 100644 --- a/content/agent/how-to/enable-interfaces.md +++ b/content/agent/how-to/enable-interfaces.md @@ -70,4 +70,4 @@ api: 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 +You may want to view the [Start mock control plane interface]({{< ref "/agent/contribute/start-mock-interface.md" >}}) topic to test NGINX Agent, or view the [Configuration overview]({{< ref "/agent/how-to/configuration-overview.md" >}}) for more options. \ No newline at end of file diff --git a/content/agent/install-upgrade/_index.md b/content/agent/install-upgrade/_index.md index 0274bc7da..7890ac2b5 100644 --- a/content/agent/install-upgrade/_index.md +++ b/content/agent/install-upgrade/_index.md @@ -1,5 +1,5 @@ --- -title: "Install and upgrade" +title: "Install and update" weight: 400 url: /nginx-agent/install-upgrade/ --- diff --git a/content/agent/install-upgrade/install-from-github.md b/content/agent/install-upgrade/install-from-github.md new file mode 100644 index 000000000..3438a02ba --- /dev/null +++ b/content/agent/install-upgrade/install-from-github.md @@ -0,0 +1,72 @@ +--- +title: Install from GitHub package files +toc: true +weight: 300 +docs: DOCS-000 +--- + +{{< note>}} +If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) +to manage your NGINX instances, NGINX Agent is installed automatically when you +add an NGINX instance to NGINX One Console. + +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +{{< /note >}} + +Follow the steps in this guide to install NGINX Agent in your NGINX instance using +GitHub package files. + +## Before you begin + +{{< include "/agent/installation/prerequisites.md" >}} + +## 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 + +{{< include "/agent/installation/start-stop-agent.md" >}} + +## Verify that NGINX Agent is running + +{{< include "/agent/installation/verify-agent.md" >}} \ No newline at end of file diff --git a/content/agent/install-upgrade/install-from-oss-repo.md b/content/agent/install-upgrade/install-from-oss-repo.md new file mode 100644 index 000000000..d05eda965 --- /dev/null +++ b/content/agent/install-upgrade/install-from-oss-repo.md @@ -0,0 +1,103 @@ +--- +title: Install from Open Source repo +toc: true +weight: 100 +docs: DOCS-000 +--- + +{{< note>}} +If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) +to manage your NGINX instances, NGINX Agent is installed automatically when you +add an NGINX instance to NGINX One Console. + +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +{{< /note >}} + +## Overview + +Follow the steps in this guide to install NGINX Agent in your NGINX instance using +the NGINX Open Source repository. + +## Before you begin + +{{< include "/agent/installation/prerequisites.md" >}} + +## 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 + +{{< include "/agent/installation/oss/oss-rhel.md" >}} + +
    + +
    +{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +{{< include "/agent/installation/oss/oss-ubuntu.md" >}} + +
    + +
    +{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +{{< include "/agent/installation/oss/oss-debian.md" >}} + +
    + +
    +{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +{{< include "/agent/installation/oss/oss-sles.md" >}} + +
    + +
    +{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +{{< include "/agent/installation/oss/oss-alpine.md" >}} + +
    + +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +{{< include "/agent/installation/oss/oss-amazon-linux.md" >}} + +
    +
    +{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +{{< include "/agent/installation/oss/oss-freebsd.md" >}} + +
    + +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Start, stop, and enable NGINX Agent + +{{< include "/agent/installation/start-stop-agent.md" >}} + +## Verify that NGINX Agent is running + +{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/agent/install-upgrade/install-from-plus-repo.md b/content/agent/install-upgrade/install-from-plus-repo.md new file mode 100644 index 000000000..5617b2941 --- /dev/null +++ b/content/agent/install-upgrade/install-from-plus-repo.md @@ -0,0 +1,104 @@ +--- +title: Install from NGINX Plus repo +toc: true +weight: 200 +docs: DOCS-000 +--- + +{{< note>}} +If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) +to manage your NGINX instances, NGINX Agent is installed automatically when you +add an NGINX instance to NGINX One Console. + +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +{{< /note >}} + +## Overview + +Follow the steps in this guide to install NGINX Agent in your NGINX instance using +the NGINX Plus repository. + +## Before you begin + +{{< include "/agent/installation/prerequisites.md" >}} + +## 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 + +{{< include "/agent/installation/plus/plus-rhel.md" >}} + +
    + +
    +{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +{{< include "/agent/installation/plus/plus-ubuntu.md" >}} + +
    + +
    +{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +{{< include "/agent/installation/plus/plus-debian.md" >}} + +
    + +
    +{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +{{< include "/agent/installation/plus/plus-sles.md" >}} + +
    + +
    +{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +{{< include "/agent/installation/plus/plus-alpine.md" >}} + +
    +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +{{< include "/agent/installation/plus/plus-amazon-linux.md" >}} + +
    + +
    +{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +{{< include "/agent/installation/plus/plus-freebsd.md" >}} + +
    + +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Start, stop, and enable NGINX Agent + +{{< include "/agent/installation/start-stop-agent.md" >}} + +## Verify that NGINX Agent is running + +{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/agent/install-upgrade/install.md b/content/agent/install-upgrade/install.md deleted file mode 100644 index 66bca2ae9..000000000 --- a/content/agent/install-upgrade/install.md +++ /dev/null @@ -1,871 +0,0 @@ ---- -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/uninstall.md b/content/agent/install-upgrade/uninstall.md index 7fe869d58..b37aed02a 100644 --- a/content/agent/install-upgrade/uninstall.md +++ b/content/agent/install-upgrade/uninstall.md @@ -1,145 +1,81 @@ --- title: "Uninstall NGINX Agent" toc: true -weight: 300 +weight: 500 docs: DOCS-000 --- ## Overview -Learn how to uninstall F5 NGINX Agent from your system. +Follow the steps in this guide to remove F5 NGINX Agent from your NGINX instances. ## Before you begin -### Prerequisites - -- NGINX Agent installed [NGINX Agent installed](../installation-oss) -- The user following these steps will need `root` privilege +The user following performing the uninstall steps needs to have `root` privilege. ## Uninstall NGINX Agent -Complete the following steps on each host where you’ve installed 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) +
    +{{< fa "brands fa-centos" >}} Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux ### 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 - ``` +{{< include "/agent/installation/uninstall/uninstall-rhel.md" >}} -1. To uninstall NGINX Agent, run the following command: +
    - ```shell - sudo yum remove nginx-agent - ``` +
    +{{< fa "brands fa-ubuntu" >}} Uninstall NGINX Agent on Ubuntu ### 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 - ``` +{{< include "/agent/installation/uninstall/uninstall-ubuntu.md" >}} -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 >}} +
    +{{< fa "brands fa-debian" >}} Uninstall NGINX Agent on Debian ### 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: +{{< include "/agent/installation/uninstall/uninstall-debian.md" >}} - ```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 >}} +
    +{{< fa "brands fa-suse" >}} Uninstall NGINX Agent on SLES ### Uninstall NGINX Agent on SLES -Complete the following steps on each host where you've installed NGINX Agent: +{{< include "/agent/installation/uninstall/uninstall-sles.md" >}} -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 - ``` +
    +{{< fa "solid fa-mountain-sun" >}} Uninstall NGINX Agent on Alpine Linux ### Uninstall NGINX Agent on Alpine Linux -Complete the following steps on each host where you've installed NGINX agent: - -1. Stop NGINX agent: +{{< include "/agent/installation/uninstall/uninstall-alpine.md" >}} - ```shell - sudo rc-service nginx-agent stop - ``` +
    -1. To uninstall NGINX agent, run the following command: - - ```shell - sudo apk del nginx-agent - ``` +
    +{{< fa "brands fa-aws" >}} Uninstall NGINX Agent on Amazon Linux ### Uninstall NGINX Agent on Amazon Linux -Complete the following steps on each host where you've installed NGINX agent: - -1. Stop NGINX agent: +{{< include "/agent/installation/uninstall/uninstall-amazon-linux.md" >}} - ```shell - sudo systemctl stop nginx-agent - ``` +
    -1. To uninstall NGINX agent, run the following command: - - ```shell - sudo yum remove nginx-agent - ``` +
    +{{< fa "brands fa-freebsd" >}} Uninstall NGINX Agent on FreeBSD ### 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: +{{< include "/agent/installation/uninstall/uninstall-freebsd.md" >}} - ```shell - sudo pkg delete nginx-agent - ``` +
    diff --git a/content/agent/install-upgrade/update.md b/content/agent/install-upgrade/update.md new file mode 100644 index 000000000..c85ad6cd7 --- /dev/null +++ b/content/agent/install-upgrade/update.md @@ -0,0 +1,14 @@ +--- +title: "Update NGINX Agent" +toc: true +weight: 400 +docs: DOCS-000 +--- + +## Overview + +{{< include "/agent/installation/update.md" >}} + +## Migrate NGINX Agent running in containers + +{{< include "/agent/installation/update-container.md" >}} diff --git a/content/agent/install-upgrade/upgrade.md b/content/agent/install-upgrade/upgrade.md deleted file mode 100644 index 55898a2bb..000000000 --- a/content/agent/install-upgrade/upgrade.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -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/tech-specs.md b/content/agent/tech-specs.md new file mode 100644 index 000000000..b74911c7f --- /dev/null +++ b/content/agent/tech-specs.md @@ -0,0 +1,8 @@ +--- +title: "Technical Specifications" +toc: false +weight: 150 +docs: DOCS-000 +--- + +{{< include "/agent/tech-specs.md" >}} diff --git a/content/agent/v2/changelog.md b/content/agent/v2/changelog.md index 981348f9e..ff7f3c9f2 100644 --- a/content/agent/v2/changelog.md +++ b/content/agent/v2/changelog.md @@ -7,7 +7,7 @@ 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" >}}). +See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "./technical-specifications.md" >}}). --- ## Release [v2.39.0](https://github.com/nginx/agent/releases/tag/v2.39.0) diff --git a/content/agent/v2/installation-upgrade/container-environments/docker-images.md b/content/agent/v2/installation-upgrade/container-environments/docker-images.md index 0b0db3f06..c79278f7d 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-images.md @@ -14,7 +14,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. -See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) topic. +See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/tech-specs.md" >}}) topic. ## Deploy Offical NGINX and NGINX Plus Containers @@ -113,7 +113,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/v2/configuration/configuration-overview" >}}).{{}} +{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/v2/configuration/configuration-overview" >}}).{{}} ### Enable the gRPC interface diff --git a/content/agent/v2/installation-upgrade/container-environments/docker-support.md b/content/agent/v2/installation-upgrade/container-environments/docker-support.md index e3844a5f0..c22fa059a 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/v2/installation-upgrade/container-environments/docker-support.md @@ -10,9 +10,9 @@ type: ## 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/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. +The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< ref "/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]({{< ref "/agent/technical-specifications.md#container-support" >}}) for a list of supported operationg systems. +See the [Technical Specifications]({{< ref "/agent/tech-specs.md#container-support" >}}) for a list of supported operationg systems. NGINX Agent running in a container has some limitations that need to be considered, and are listed below. diff --git a/content/agent/v2/installation-upgrade/getting-started.md b/content/agent/v2/installation-upgrade/getting-started.md index 1d955c5ed..86b5efc90 100644 --- a/content/agent/v2/installation-upgrade/getting-started.md +++ b/content/agent/v2/installation-upgrade/getting-started.md @@ -176,5 +176,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/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). +For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). {{< /important >}} diff --git a/content/agent/v2/installation-upgrade/installation-oss.md b/content/agent/v2/installation-upgrade/installation-oss.md index 92c3a3306..fb4f2fb48 100644 --- a/content/agent/v2/installation-upgrade/installation-oss.md +++ b/content/agent/v2/installation-upgrade/installation-oss.md @@ -15,7 +15,7 @@ Learn how to install NGINX Agent from the NGINX Open Source repository. ## Prerequisites - NGINX installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) -- A [supported operating system and architecture]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< ref "/agent/tech-specs.md#supported-distributions" >}}) - `root` privilege ## Configure NGINX OSS Repository for installing NGINX Agent diff --git a/content/agent/v2/installation-upgrade/installation-plus.md b/content/agent/v2/installation-upgrade/installation-plus.md index 6ee2482d4..93c83dc59 100644 --- a/content/agent/v2/installation-upgrade/installation-plus.md +++ b/content/agent/v2/installation-upgrade/installation-plus.md @@ -16,7 +16,7 @@ Learn how to install NGINX Agent from NGINX Plus repository - An NGINX Plus subscription (purchased or trial) - NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) -- A [supported operating system and architecture]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< ref "/agent/tech-specs.md#supported-distributions" >}}) - `root` privilege - Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. - Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. diff --git a/content/includes/agent/installation/oss/oss-alpine.md b/content/includes/agent/installation/oss/oss-alpine.md new file mode 100644 index 000000000..a0782cd2e --- /dev/null +++ b/content/includes/agent/installation/oss/oss-alpine.md @@ -0,0 +1,73 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-amazon-linux.md b/content/includes/agent/installation/oss/oss-amazon-linux.md new file mode 100644 index 000000000..759cc06ce --- /dev/null +++ b/content/includes/agent/installation/oss/oss-amazon-linux.md @@ -0,0 +1,34 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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. \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-debian.md b/content/includes/agent/installation/oss/oss-debian.md new file mode 100644 index 000000000..193de20f0 --- /dev/null +++ b/content/includes/agent/installation/oss/oss-debian.md @@ -0,0 +1,52 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-freebsd.md b/content/includes/agent/installation/oss/oss-freebsd.md new file mode 100644 index 000000000..50e123295 --- /dev/null +++ b/content/includes/agent/installation/oss/oss-freebsd.md @@ -0,0 +1,23 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-rhel.md b/content/includes/agent/installation/oss/oss-rhel.md new file mode 100644 index 000000000..dfef423b5 --- /dev/null +++ b/content/includes/agent/installation/oss/oss-rhel.md @@ -0,0 +1,33 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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. \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-sles.md b/content/includes/agent/installation/oss/oss-sles.md new file mode 100644 index 000000000..3b41818c8 --- /dev/null +++ b/content/includes/agent/installation/oss/oss-sles.md @@ -0,0 +1,52 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/oss/oss-ubuntu.md b/content/includes/agent/installation/oss/oss-ubuntu.md new file mode 100644 index 000000000..e07b25b0e --- /dev/null +++ b/content/includes/agent/installation/oss/oss-ubuntu.md @@ -0,0 +1,50 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-from-oss-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-alpine.md b/content/includes/agent/installation/plus/plus-alpine.md new file mode 100644 index 000000000..8dad45834 --- /dev/null +++ b/content/includes/agent/installation/plus/plus-alpine.md @@ -0,0 +1,83 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-amazon-linux.md b/content/includes/agent/installation/plus/plus-amazon-linux.md new file mode 100644 index 000000000..f419b6341 --- /dev/null +++ b/content/includes/agent/installation/plus/plus-amazon-linux.md @@ -0,0 +1,50 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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. \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-debian.md b/content/includes/agent/installation/plus/plus-debian.md new file mode 100644 index 000000000..255728a8b --- /dev/null +++ b/content/includes/agent/installation/plus/plus-debian.md @@ -0,0 +1,50 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-freebsd.md b/content/includes/agent/installation/plus/plus-freebsd.md new file mode 100644 index 000000000..e92cec069 --- /dev/null +++ b/content/includes/agent/installation/plus/plus-freebsd.md @@ -0,0 +1,52 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-rhel.md b/content/includes/agent/installation/plus/plus-rhel.md new file mode 100644 index 000000000..bbd9fdb04 --- /dev/null +++ b/content/includes/agent/installation/plus/plus-rhel.md @@ -0,0 +1,55 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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. \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-sles.md b/content/includes/agent/installation/plus/plus-sles.md new file mode 100644 index 000000000..324a4769b --- /dev/null +++ b/content/includes/agent/installation/plus/plus-sles.md @@ -0,0 +1,75 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/plus/plus-ubuntu.md b/content/includes/agent/installation/plus/plus-ubuntu.md new file mode 100644 index 000000000..7b11d588c --- /dev/null +++ b/content/includes/agent/installation/plus/plus-ubuntu.md @@ -0,0 +1,55 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/prerequisites.md b/content/includes/agent/installation/prerequisites.md new file mode 100644 index 000000000..709bae10f --- /dev/null +++ b/content/includes/agent/installation/prerequisites.md @@ -0,0 +1,13 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-github.md + - content/agent/install-upgrade/install-from-oss-repo.md + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +- You must use one of the [supported operating system and architectures]({{< ref "/agent/tech-specs.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. \ No newline at end of file diff --git a/content/includes/agent/installation/start-stop-agent.md b/content/includes/agent/installation/start-stop-agent.md new file mode 100644 index 000000000..eaebad911 --- /dev/null +++ b/content/includes/agent/installation/start-stop-agent.md @@ -0,0 +1,27 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-github.md + - content/agent/install-upgrade/install-from-oss-repo.md + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 +``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-alpine.md b/content/includes/agent/installation/uninstall/uninstall-alpine.md new file mode 100644 index 000000000..eff48cdc6 --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-alpine.md @@ -0,0 +1,20 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md b/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md new file mode 100644 index 000000000..0bffabb06 --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md @@ -0,0 +1,20 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-debian.md b/content/includes/agent/installation/uninstall/uninstall-debian.md new file mode 100644 index 000000000..15a0d473d --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-debian.md @@ -0,0 +1,22 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 >}} \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-freebsd.md b/content/includes/agent/installation/uninstall/uninstall-freebsd.md new file mode 100644 index 000000000..0311d1d24 --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-freebsd.md @@ -0,0 +1,20 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-rhel.md b/content/includes/agent/installation/uninstall/uninstall-rhel.md new file mode 100644 index 000000000..0e12df126 --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-rhel.md @@ -0,0 +1,20 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-sles.md b/content/includes/agent/installation/uninstall/uninstall-sles.md new file mode 100644 index 000000000..f65237753 --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-sles.md @@ -0,0 +1,20 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 + ``` \ No newline at end of file diff --git a/content/includes/agent/installation/uninstall/uninstall-ubuntu.md b/content/includes/agent/installation/uninstall/uninstall-ubuntu.md new file mode 100644 index 000000000..15a0d473d --- /dev/null +++ b/content/includes/agent/installation/uninstall/uninstall-ubuntu.md @@ -0,0 +1,22 @@ +--- +docs: +files: + - content/agent/install-upgrade/uninstall.md + - content/nginx-one/agent/uninstall.md +--- + +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 >}} \ No newline at end of file diff --git a/content/agent/install-upgrade/migrate-v3.md b/content/includes/agent/installation/update-container.md similarity index 58% rename from content/agent/install-upgrade/migrate-v3.md rename to content/includes/agent/installation/update-container.md index 8e557f368..c0f5778b2 100644 --- a/content/agent/install-upgrade/migrate-v3.md +++ b/content/includes/agent/installation/update-container.md @@ -1,30 +1,10 @@ --- -title: Upgrade from v2.x to v3.0 -weight: 500 -docs: DOCS-000 +docs: +files: + - content/agent/install-upgrade/update.md + - content/nginx-one/agent/update.md --- -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: @@ -37,9 +17,7 @@ wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-confi 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 +### 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`. diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md new file mode 100644 index 000000000..c2df47c4f --- /dev/null +++ b/content/includes/agent/installation/update.md @@ -0,0 +1,43 @@ +--- +docs: +files: + - content/agent/install-upgrade/update.md + - content/nginx-one/agent/update.md +--- + + +{{< note >}} If you are using a version **older than NGINX Agent v2.31.0**, you must stop NGINX Agent before updating: + + - `sudo systemctl stop nginx-agent` + +And start it again after the update: + + - `sudo systemctl start nginx-agent` +{{< /note >}} + +Follow the steps below to update NGINX Agent to the latest version. +The same steps apply if you are **upgrading from NGINX Agent v2 to NGINX Agent v3**. + +1. Open an SSH connection to the server where you've installed NGINX Agent. + +1. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade does not complete + successfully: + + - `/etc/nginx-agent` + - Every configuration directory specfied in `/etc/nginx-agent/nginx-agent.conf` as a `config_dirs` value + +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" + ``` diff --git a/content/includes/agent/installation/verify-agent.md b/content/includes/agent/installation/verify-agent.md new file mode 100644 index 000000000..c41caa8fc --- /dev/null +++ b/content/includes/agent/installation/verify-agent.md @@ -0,0 +1,21 @@ +--- +docs: +files: + - content/agent/install-upgrade/install-from-github.md + - content/agent/install-upgrade/install-from-oss-repo.md + - content/agent/install-upgrade/install-from-plus-repo.md + - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-from-plus-repo.md +--- + +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 +``` \ No newline at end of file diff --git a/content/agent/technical-specifications.md b/content/includes/agent/tech-specs.md similarity index 82% rename from content/agent/technical-specifications.md rename to content/includes/agent/tech-specs.md index d765798c0..cc0e05792 100644 --- a/content/agent/technical-specifications.md +++ b/content/includes/agent/tech-specs.md @@ -1,8 +1,8 @@ --- -title: "Technical Specifications" -toc: true -weight: 700 -docs: DOCS-000 +docs: +files: + - content/agent/tech-specs.md + - content/nginx-one/agent/tech-specs.md --- NGINX Agent is designed to operate efficiently on any system that meets the standard @@ -20,4 +20,4 @@ To see the detailed technical specifications for NGINX Plus, refer to the offici ### Recommended hardware For recommended hardware, see the -[Sizing guide for deploying NGINX Plus on bare metal servers](https://www.f5.com/pdf/deployment-guide/Sizing-Guide-for-Deploying-NGINX-Plus-on-Bare-Metal-Servers-2019-11-09.pdf). +[Sizing guide for deploying NGINX Plus on bare metal servers](https://www.f5.com/pdf/deployment-guide/Sizing-Guide-for-Deploying-NGINX-Plus-on-Bare-Metal-Servers-2019-11-09.pdf). \ No newline at end of file diff --git a/content/includes/nginx-one/how-to/add-instance.md b/content/includes/nginx-one/how-to/add-instance.md new file mode 100644 index 000000000..f103e085a --- /dev/null +++ b/content/includes/nginx-one/how-to/add-instance.md @@ -0,0 +1,23 @@ +--- +docs: +--- + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. \ No newline at end of file diff --git a/content/nginx-one/agent/_index.md b/content/nginx-one/agent/_index.md new file mode 100644 index 000000000..b2225884d --- /dev/null +++ b/content/nginx-one/agent/_index.md @@ -0,0 +1,6 @@ +--- +title: NGINX Agent +description: +weight: 1100 +url: /nginx-one/nginx-agent +--- diff --git a/content/nginx-one/agent/connect-instances-to-console.md b/content/nginx-one/agent/connect-instances-to-console.md new file mode 100644 index 000000000..fceac3377 --- /dev/null +++ b/content/nginx-one/agent/connect-instances-to-console.md @@ -0,0 +1,8 @@ +--- +title: Connect NGINX instances to NGINX One Console +toc: true +weight: 300 +docs: DOCS-000 +--- + +{{< include "/nginx-one/how-to/add-instance.md" >}} \ No newline at end of file diff --git a/content/nginx-one/agent/install-from-oss-repo.md b/content/nginx-one/agent/install-from-oss-repo.md new file mode 100644 index 000000000..dd8ebd4ae --- /dev/null +++ b/content/nginx-one/agent/install-from-oss-repo.md @@ -0,0 +1,101 @@ +--- +title: Install from Open Source repo +toc: true +weight: 100 +docs: DOCS-000 +--- + +{{< note>}} +If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) +to manage your NGINX instances, NGINX Agent is installed automatically when you +add an NGINX instance to NGINX One Console. + +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +{{< /note >}} + +Follow the steps in this guide to install NGINX Agent in your NGINX instance using +the NGINX Open Source repository. + +## Before you begin + +{{< include "/agent/installation/prerequisites.md" >}} + +## 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 + +{{< include "/agent/installation/oss/oss-rhel.md" >}} + +
    + +
    +{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +{{< include "/agent/installation/oss/oss-ubuntu.md" >}} + +
    + +
    +{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +{{< include "/agent/installation/oss/oss-debian.md" >}} + +
    + +
    +{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +{{< include "/agent/installation/oss/oss-sles.md" >}} + +
    + +
    +{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +{{< include "/agent/installation/oss/oss-alpine.md" >}} + +
    + +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +{{< include "/agent/installation/oss/oss-amazon-linux.md" >}} + +
    +
    +{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +{{< include "/agent/installation/oss/oss-freebsd.md" >}} + +
    + +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Start, stop, and enable NGINX Agent + +{{< include "/agent/installation/start-stop-agent.md" >}} + +## Verify that NGINX Agent is running + +{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/nginx-one/agent/install-from-plus-repo.md b/content/nginx-one/agent/install-from-plus-repo.md new file mode 100644 index 000000000..55fc0eea9 --- /dev/null +++ b/content/nginx-one/agent/install-from-plus-repo.md @@ -0,0 +1,102 @@ +--- +title: Install from NGINX Plus repo +toc: true +weight: 200 +docs: DOCS-000 +--- + +{{< note>}} +If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) +to manage your NGINX instances, NGINX Agent is installed automatically when you +add an NGINX instance to NGINX One Console. + +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +{{< /note >}} + +Follow the steps in this guide to install NGINX Agent in your NGINX instance using +the NGINX Plus repository. + +## Before you begin + +{{< include "/agent/installation/prerequisites.md" >}} + +## 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 + +{{< include "/agent/installation/plus/plus-rhel.md" >}} + +
    + +
    +{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu + +### Install NGINX Agent on Ubuntu + +{{< include "/agent/installation/plus/plus-ubuntu.md" >}} + +
    + +
    +{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian + +### Install NGINX Agent on Debian + +{{< include "/agent/installation/plus/plus-debian.md" >}} + +
    + +
    +{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES + +### Install NGINX Agent on SLES + +{{< include "/agent/installation/plus/plus-sles.md" >}} + +
    + +
    +{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux + +### Install NGINX Agent on Alpine Linux + +{{< include "/agent/installation/plus/plus-alpine.md" >}} + +
    +
    +{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux + +### Install NGINX Agent on Amazon Linux + +{{< include "/agent/installation/plus/plus-amazon-linux.md" >}} + +
    + +
    +{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD + +### Install NGINX Agent on FreeBSD + +{{< include "/agent/installation/plus/plus-freebsd.md" >}} + +
    + +### Manually connect NGINX Agent to NGINX One Console + +{{< include "agent/installation/manually-connect-to-console" >}} + +## Start, stop, and enable NGINX Agent + +{{< include "/agent/installation/start-stop-agent.md" >}} + +## Verify that NGINX Agent is running + +{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/nginx-one/agent/tech-specs.md b/content/nginx-one/agent/tech-specs.md new file mode 100644 index 000000000..84c2840ea --- /dev/null +++ b/content/nginx-one/agent/tech-specs.md @@ -0,0 +1,8 @@ +--- +title: "Technical Specifications" +toc: false +weight: 50 +docs: DOCS-000 +--- + +{{< include "/agent/tech-specs.md" >}} diff --git a/content/nginx-one/agent/uninstall.md b/content/nginx-one/agent/uninstall.md new file mode 100644 index 000000000..169029461 --- /dev/null +++ b/content/nginx-one/agent/uninstall.md @@ -0,0 +1,81 @@ +--- +title: "Uninstall NGINX Agent" +toc: true +weight: 500 +docs: DOCS-000 +--- + +## Overview + +Learn how to uninstall F5 NGINX Agent from your system. + +## Before you begin + +The user following performing the uninstall steps needs to have `root` privilege. + +## Uninstall NGINX Agent + +Complete the following steps on each host where you've installed NGINX Agent + +
    +{{< fa "brands fa-centos" >}} Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +### Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux + +{{< include "/agent/installation/uninstall/uninstall-rhel.md" >}} + +
    + +
    +{{< fa "brands fa-ubuntu" >}} Uninstall NGINX Agent on Ubuntu + +### Uninstall NGINX Agent on Ubuntu + +{{< include "/agent/installation/uninstall/uninstall-ubuntu.md" >}} + +
    + +
    +{{< fa "brands fa-debian" >}} Uninstall NGINX Agent on Debian + +### Uninstall NGINX Agent on Debian + +{{< include "/agent/installation/uninstall/uninstall-debian.md" >}} + +
    + +
    +{{< fa "brands fa-suse" >}} Uninstall NGINX Agent on SLES + +### Uninstall NGINX Agent on SLES + +{{< include "/agent/installation/uninstall/uninstall-sles.md" >}} + +
    + +
    +{{< fa "solid fa-mountain-sun" >}} Uninstall NGINX Agent on Alpine Linux + +### Uninstall NGINX Agent on Alpine Linux + +{{< include "/agent/installation/uninstall/uninstall-alpine.md" >}} + +
    + +
    +{{< fa "brands fa-aws" >}} Uninstall NGINX Agent on Amazon Linux + +### Uninstall NGINX Agent on Amazon Linux + +{{< include "/agent/installation/uninstall/uninstall-amazon-linux.md" >}} + +
    + +
    +{{< fa "brands fa-freebsd" >}} Uninstall NGINX Agent on FreeBSD + +### Uninstall NGINX Agent on FreeBSD + +{{< include "/agent/installation/uninstall/uninstall-freebsd.md" >}} + +
    diff --git a/content/nginx-one/agent/update.md b/content/nginx-one/agent/update.md new file mode 100644 index 000000000..09de27120 --- /dev/null +++ b/content/nginx-one/agent/update.md @@ -0,0 +1,12 @@ +--- +title: "Update NGINX Agent" +toc: true +weight: 400 +docs: DOCS-000 +--- + +{{< include "/agent/installation/update.md" >}} + +## Migrate NGINX Agent running in containers + +{{< include "/agent/installation/update-container.md" >}} \ No newline at end of file diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index 68e8498ee..1f9919ce7 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -3,7 +3,7 @@ description: '' docs: DOCS-1396 title: Glossary toc: true -weight: 1000 +weight: 1200 type: - reference --- diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md index 884df0c15..fd155519c 100644 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ b/content/nginx-one/how-to/nginx-configs/add-instance.md @@ -25,25 +25,7 @@ Before you add an instance to NGINX One Console, ensure: ## Add an instance -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. +{{< include "/nginx-one/how-to/add-instance.md" >}} ## Managed and Unmanaged Certificates From abf09d4f3694d40b6d760c3aa5eef3128aeda0d2 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Tue, 22 Apr 2025 15:06:44 +0100 Subject: [PATCH 20/63] Agent fix url (#437) Fix URL in Update NGINX Agent --- content/includes/agent/installation/update-container.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index c0f5778b2..9c6e87c40 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -10,7 +10,7 @@ To migrate NGINX Agent containers, we provide a script to convert NGINX Agent v2 To upgrade the configuration, you can follow this example: ```shell -wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh +wget https://raw.githubusercontent.com/nginx/agent/refs/heads/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 ``` From 90f23133c0fe195c9d3f1dcb66e32d22b346a805 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 28 Apr 2025 11:25:29 +0100 Subject: [PATCH 21/63] update hugo --- go.mod | 2 +- go.sum | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/go.mod b/go.mod index a7dc51830..602575fd1 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.28 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.30 // indirect diff --git a/go.sum b/go.sum index 8a25e80eb..1349b409d 100644 --- a/go.sum +++ b/go.sum @@ -4,3 +4,5 @@ github.com/nginxinc/nginx-hugo-theme v0.42.27 h1:D80Sf/o9lR4P0NDFfP/hCQllohz6C5q github.com/nginxinc/nginx-hugo-theme v0.42.27/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.28 h1:1SGzBADcXnSqP4rOKEhlfEUloopH6UvMg+XTyVVQyjU= github.com/nginxinc/nginx-hugo-theme v0.42.28/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.30 h1:qcHvB8tElbFN5ZWgs/TGn5IEmvnT5PG4ImQCCbMZ/Rw= +github.com/nginxinc/nginx-hugo-theme v0.42.30/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From 8c4573b6c874c247e21263a32074f48baaa04631 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Mon, 28 Apr 2025 13:20:36 +0100 Subject: [PATCH 22/63] update v3 agent about (#452) * update v3 agent about * update hugo * updage go.sum * convert about agent to includes * fix mermaid graphs --- content/agent/about.md | 47 ++++----------------- content/includes/agent/about.md | 43 +++++++++++++++++++ content/includes/agent/architecture.md | 22 ++++++++++ content/nginx-one/agent/about.md | 57 ++++++++++++++++++++++++++ 4 files changed, 129 insertions(+), 40 deletions(-) create mode 100644 content/includes/agent/about.md create mode 100644 content/includes/agent/architecture.md create mode 100644 content/nginx-one/agent/about.md diff --git a/content/agent/about.md b/content/agent/about.md index 10c192d8c..5b27a0302 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -1,41 +1,18 @@ --- -title: "Overview" +title: "About" weight: 100 toc: true docs: DOCS-000 --- {{}} - -{{}} - -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]({{< ref "/agent/install-upgrade/install-from-oss-repo.md#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]({{< ref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications. +NGINX Agent v3.0 is a major release that introduces new features and enhancements. +Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. +{{}} +{{< include "agent/about.md" >}} -### 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. - -## How NGINX Agent works +## Architecture ```mermaid graph BT @@ -77,14 +54,4 @@ graph BT Compute <--> |gRPC| ManagementPlane ``` -The figure shows: - -- An NGINX Instance running on bare metal, virtual machine or container -- The NGINX One Cloud Console includes: - - Command Server to manage NGINX configurations, push new/updated configuration files remotely, and perform integrity tests. - - OpenTelemetry (OTel) Receiver that receives observability data from connected Agent instances. -- An NGINX Agent process running on the NGINX instance. NGINX Agent is responsible for: - - Watching, applying, validating, automatically roll back to last good configuration if issues are detected. - - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to the NGINX One Cloud Console. -- Collection and monitoring of host metrics (CPU usage, Memory utilization, Disk I/O) by the Agent OTel collector. -- Collected data is made available on the NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. +{{< include "agent/architecture.md" >}} \ No newline at end of file diff --git a/content/includes/agent/about.md b/content/includes/agent/about.md new file mode 100644 index 000000000..9025e2f56 --- /dev/null +++ b/content/includes/agent/about.md @@ -0,0 +1,43 @@ +--- +docs: +files: + - content/agent/about.md + - content/nginx-one/agent/about.md +--- + +F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX One and enable remote management of NGINX instances. 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. + - [Connects NGINX instances to NGINX One Console]({{< ref "/agent/install-upgrade/install-from-oss-repo.md#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. + - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/), and the ability to + [export the metrics data]({{< ref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications. + + + +### Configuration management + +- NGINX Agent provides an interface that enables users to deploy configuration changes to NGINX instances from a + centralized management plane. +- Additionally, NGINX Agent verifies that the configuration changes are successfully applied to NGINX instances. + +### Metrics collection + +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 NGINX One Console or integrated with third-party data aggregators. diff --git a/content/includes/agent/architecture.md b/content/includes/agent/architecture.md new file mode 100644 index 000000000..752cc19b6 --- /dev/null +++ b/content/includes/agent/architecture.md @@ -0,0 +1,22 @@ +--- +docs: +files: + - content/agent/about.md + - content/nginx-one/agent/about.md +--- + +The figure shows: + +- An NGINX instance running on bare metal, virtual machine or container +- NGINX One Cloud Console includes: + + - Command Server to manage NGINX configurations, push new/updated configuration files remotely, and perform integrity tests. + - OpenTelemetry (OTel) Receiver that receives observability data from connected Agent instances. + +- An NGINX Agent process running on the NGINX instance. NGINX Agent is responsible for: + + - Watching, applying, validating, automatically roll back to last good configuration if issues are detected. + - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to NGINX One Cloud Console. + +- Collection and monitoring of host metrics (CPU usage, Memory utilization, Disk I/O) by the Agent OTel collector. +- Collected data is made available on NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. diff --git a/content/nginx-one/agent/about.md b/content/nginx-one/agent/about.md new file mode 100644 index 000000000..0fc25820a --- /dev/null +++ b/content/nginx-one/agent/about.md @@ -0,0 +1,57 @@ +--- +title: "About" +weight: 10 +toc: true +--- + +{{}} +NGINX Agent v3.0 is a major release that introduces new features and enhancements. + +Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. +{{}} + +{{< include "agent/about.md" >}} + +## Architecture + +```mermaid +graph BT + + %% Define colors for the subgraphs + style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000 + style CommandControl fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 + style OTelManagementPlane fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 + style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 + style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 + + subgraph ManagementPlane["NGINX One"] + CommandControl["Command Server"] + OTelManagementPlane["OTel Receiver"] + end + + subgraph Compute["NGINX Instance"] + subgraph Agent["Agent Process"] + OTelDataPlane["OTel Collector"] + end + + subgraph NGINX["NGINX Process"] + NGINXMetrics["Metrics"] + end + NGINXConfig["NGINX Configuration Files"] + ErrorLogs["NGINX Error Logs"] + + Metrics["Host Metrics"] --> |Collects| OTelDataPlane + NGINXMetrics --> |Reads| OTelDataPlane["OTel Collector"] + Agent --> |Watch/Reload| NGINX + Agent --> |Reads| ErrorLogs + OTelDataPlane --> |Reads| AccessLogs["NGINX Access Logs"] + Agent <--> |Reads/Writes| NGINXConfig + end + + Compute <--> |gRPC| ManagementPlane +``` + +{{< include "agent/architecture.md" >}} From 85b6d64415e646aea8e54934cf7cbfaf459ba40b Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Thu, 1 May 2025 16:51:40 +0100 Subject: [PATCH 23/63] Move Agent v3 Docs under NGINX One Console (#468) * move agent v3 docs to NGINX One * fix: update community pages * remove github discussions from agent v3 docs * one line content types * update message * update messaging * remove agent connect instances doc * modify N1 doc to cover v2 and v3 --- content/agent/_index.md | 1 + content/agent/about.md | 116 +++---- content/agent/changelog.md | 5 +- content/agent/community.md | 20 ++ content/agent/configuration/_index.md | 10 + .../configuration/configuration-overview.md | 7 +- .../configure-nginx-agent-group.md | 5 +- .../configuration/encrypt-communication.md | 2 +- .../{v2 => }/configuration/health-checks.md | 3 +- content/agent/contribute/_index.md | 7 - content/agent/contribute/community.md | 22 -- .../agent/contribute/dev-environment-setup.md | 7 +- .../agent/contribute/start-mock-interface.md | 5 +- .../{v2 => }/installation-upgrade/_index.md | 3 + .../container-environments/_index.md | 3 + .../container-environments/docker-images.md | 9 +- .../container-environments/docker-support.md | 8 +- .../installation-upgrade/getting-started.md | 7 +- .../installation-github.md | 5 +- .../installation-upgrade/installation-oss.md | 7 +- .../installation-upgrade/installation-plus.md | 7 +- .../installation-unprivileged.md | 7 +- .../installation-upgrade/uninstall.md | 5 +- .../{v2 => }/installation-upgrade/upgrade.md | 5 +- content/agent/otel/_index.md | 5 - content/agent/tech-specs.md | 8 - .../{v2 => }/technical-specifications.md | 8 +- content/agent/v2/_index.md | 8 - content/agent/v2/changelog.md | 282 ------------------ content/agent/v2/configuration/_index.md | 7 - content/includes/agent/about.md | 4 +- .../agent/installation/prerequisites.md | 2 +- content/nginx-one/agent/_index.md | 2 +- content/nginx-one/agent/about.md | 2 +- content/nginx-one/agent/changelog.md | 21 ++ content/nginx-one/agent/community.md | 20 ++ .../agent}/configure-otel-metrics.md | 19 +- .../agent/connect-instances-to-console.md | 8 - .../{ => nginx-one}/agent/how-to/_index.md | 0 .../agent/how-to/configuration-overview.md | 0 .../agent/how-to/configure-agent-group.md | 0 .../agent/how-to/connect-management-plane.md | 0 .../agent/how-to/enable-interfaces.md | 2 +- .../agent/how-to/encrypt-communication.md | 0 .../agent/how-to/run-agent-container.md | 0 .../nginx-one/agent/install-from-oss-repo.md | 101 ------- .../nginx-one/agent/install-from-plus-repo.md | 102 ------- .../agent/install-upgrade/_index.md | 0 .../install-upgrade/install-from-github.md | 0 .../install-upgrade/install-from-oss-repo.md | 0 .../install-upgrade/install-from-plus-repo.md | 0 .../agent/install-upgrade/uninstall.md | 0 .../agent/install-upgrade/update.md | 0 .../{ => nginx-one}/agent/troubleshooting.md | 0 content/nginx-one/agent/uninstall.md | 81 ----- content/nginx-one/agent/update.md | 12 - content/nginx-one/getting-started.md | 15 +- layouts/agent-v2-migration/single.html | 5 +- .../agent-v2-migration/list-main.html | 19 +- 59 files changed, 219 insertions(+), 790 deletions(-) create mode 100644 content/agent/community.md create mode 100644 content/agent/configuration/_index.md rename content/agent/{v2 => }/configuration/configuration-overview.md (99%) rename content/agent/{v2 => }/configuration/configure-nginx-agent-group.md (98%) rename content/agent/{v2 => }/configuration/encrypt-communication.md (99%) rename content/agent/{v2 => }/configuration/health-checks.md (98%) delete mode 100644 content/agent/contribute/_index.md delete mode 100644 content/agent/contribute/community.md rename content/agent/{v2 => }/installation-upgrade/_index.md (71%) rename content/agent/{v2 => }/installation-upgrade/container-environments/_index.md (73%) rename content/agent/{v2 => }/installation-upgrade/container-environments/docker-images.md (97%) rename content/agent/{v2 => }/installation-upgrade/container-environments/docker-support.md (87%) rename content/agent/{v2 => }/installation-upgrade/getting-started.md (98%) rename content/agent/{v2 => }/installation-upgrade/installation-github.md (97%) rename content/agent/{v2 => }/installation-upgrade/installation-oss.md (99%) rename content/agent/{v2 => }/installation-upgrade/installation-plus.md (99%) rename content/agent/{v2 => }/installation-upgrade/installation-unprivileged.md (93%) rename content/agent/{v2 => }/installation-upgrade/uninstall.md (98%) rename content/agent/{v2 => }/installation-upgrade/upgrade.md (97%) delete mode 100644 content/agent/otel/_index.md delete mode 100644 content/agent/tech-specs.md rename content/agent/{v2 => }/technical-specifications.md (95%) delete mode 100644 content/agent/v2/_index.md delete mode 100644 content/agent/v2/changelog.md delete mode 100644 content/agent/v2/configuration/_index.md create mode 100644 content/nginx-one/agent/changelog.md create mode 100644 content/nginx-one/agent/community.md rename content/{agent/otel => nginx-one/agent}/configure-otel-metrics.md (87%) delete mode 100644 content/nginx-one/agent/connect-instances-to-console.md rename content/{ => nginx-one}/agent/how-to/_index.md (100%) rename content/{ => nginx-one}/agent/how-to/configuration-overview.md (100%) rename content/{ => nginx-one}/agent/how-to/configure-agent-group.md (100%) rename content/{ => nginx-one}/agent/how-to/connect-management-plane.md (100%) rename content/{ => nginx-one}/agent/how-to/enable-interfaces.md (87%) rename content/{ => nginx-one}/agent/how-to/encrypt-communication.md (100%) rename content/{ => nginx-one}/agent/how-to/run-agent-container.md (100%) delete mode 100644 content/nginx-one/agent/install-from-oss-repo.md delete mode 100644 content/nginx-one/agent/install-from-plus-repo.md rename content/{ => nginx-one}/agent/install-upgrade/_index.md (100%) rename content/{ => nginx-one}/agent/install-upgrade/install-from-github.md (100%) rename content/{ => nginx-one}/agent/install-upgrade/install-from-oss-repo.md (100%) rename content/{ => nginx-one}/agent/install-upgrade/install-from-plus-repo.md (100%) rename content/{ => nginx-one}/agent/install-upgrade/uninstall.md (100%) rename content/{ => nginx-one}/agent/install-upgrade/update.md (100%) rename content/{ => nginx-one}/agent/troubleshooting.md (100%) delete mode 100644 content/nginx-one/agent/uninstall.md delete mode 100644 content/nginx-one/agent/update.md diff --git a/content/agent/_index.md b/content/agent/_index.md index 330490eb8..ee41678ad 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -5,4 +5,5 @@ description: NGINX Agent is a companion daemon for your NGINX Open Source or NGI url: /nginx-agent/ cascade: logo: NGINX-product-icon.png + type: agent-v2-migration --- diff --git a/content/agent/about.md b/content/agent/about.md index 5b27a0302..31c87dd32 100644 --- a/content/agent/about.md +++ b/content/agent/about.md @@ -1,57 +1,67 @@ --- -title: "About" +title: About +draft: false weight: 100 toc: true -docs: DOCS-000 +nd-docs: DOCS-1091 +nd-content-type: how-to --- -{{}} -NGINX Agent v3.0 is a major release that introduces new features and enhancements. - -Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. -{{}} - -{{< include "agent/about.md" >}} - -## Architecture - -```mermaid -graph BT - - %% Define colors for the subgraphs - style ManagementPlane fill:#d0eac4,stroke:#228B22,stroke-width:2px,color:#000000 - style CommandControl fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 - style OTelManagementPlane fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 - style Compute fill:#cfe2f1,stroke:#1E90FF,stroke-width:2px,color:#000000 - style NGINX fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - style NGINXConfig fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - style ErrorLogs fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - style Agent fill:#b5e0b6,stroke:#008000,stroke-width:2px,color:#000000 - - subgraph ManagementPlane["NGINX One"] - CommandControl["Command Server"] - OTelManagementPlane["OTel Receiver"] - end - - subgraph Compute["NGINX Instance"] - subgraph Agent["Agent Process"] - OTelDataPlane["OTel Collector"] - end - - subgraph NGINX["NGINX Process"] - NGINXMetrics["Metrics"] - end - NGINXConfig["NGINX Configuration Files"] - ErrorLogs["NGINX Error Logs"] - - Metrics["Host Metrics"] --> |Collects| OTelDataPlane - NGINXMetrics --> |Reads| OTelDataPlane["OTel Collector"] - Agent --> |Watch/Reload| NGINX - Agent --> |Reads| ErrorLogs - OTelDataPlane --> |Reads| AccessLogs["NGINX Access Logs"] - Agent <--> |Reads/Writes| NGINXConfig - end - - Compute <--> |gRPC| ManagementPlane -``` - -{{< include "agent/architecture.md" >}} \ No newline at end of file + +## Overview + +NGINX Agent v2 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: + + +{{}} +| 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 | +{{}} + + + diff --git a/content/agent/changelog.md b/content/agent/changelog.md index 8b5e6ebcd..26bc17291 100644 --- a/content/agent/changelog.md +++ b/content/agent/changelog.md @@ -6,10 +6,7 @@ toc: true {{< 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]({{< ref "./tech-specs.md" >}}). - ---- -## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) +See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}). --- ## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0) diff --git a/content/agent/community.md b/content/agent/community.md new file mode 100644 index 000000000..2f0fdc3cf --- /dev/null +++ b/content/agent/community.md @@ -0,0 +1,20 @@ +--- +title: "Community and contribution" +toc: true +weight: 600 +nd-docs: DOCS-000 +--- + +Discover the various ways you can participate in the F5 NGINX Agent project: + +## Community + +- Have questions or ideas to discuss? Join the conversation about NGINX Agent in the [NGINX Community Forum](https://community.nginx.org/). + +## Contribute + +Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details. + +## License + +[Apache License, Version 2.0](https://github.com/nginx/agent/blob/main/LICENSE) diff --git a/content/agent/configuration/_index.md b/content/agent/configuration/_index.md new file mode 100644 index 000000000..ca784b6eb --- /dev/null +++ b/content/agent/configuration/_index.md @@ -0,0 +1,10 @@ +--- +title: "Configuration" +weight: "400" +url: /nginx-agent/configuration/ +cascade: + logo: NGINX-product-icon.png + layout: agent-v2-migration +--- + +Learn how to configure NGINX Agent. \ No newline at end of file diff --git a/content/agent/v2/configuration/configuration-overview.md b/content/agent/configuration/configuration-overview.md similarity index 99% rename from content/agent/v2/configuration/configuration-overview.md rename to content/agent/configuration/configuration-overview.md index 4d5751d8c..8556c2cdf 100644 --- a/content/agent/v2/configuration/configuration-overview.md +++ b/content/agent/configuration/configuration-overview.md @@ -3,9 +3,10 @@ title: Basic configuration draft: false weight: 100 toc: true -docs: DOCS-1229 -type: -- how-to +nd-docs: DOCS-1229 +nd-content-type: how-to + + --- The following sections explain how to configure NGINX Agent using configuration files, CLI flags, and environment variables. diff --git a/content/agent/v2/configuration/configure-nginx-agent-group.md b/content/agent/configuration/configure-nginx-agent-group.md similarity index 98% rename from content/agent/v2/configuration/configure-nginx-agent-group.md rename to content/agent/configuration/configure-nginx-agent-group.md index 97098f37c..bf3f1d0f7 100644 --- a/content/agent/v2/configuration/configure-nginx-agent-group.md +++ b/content/agent/configuration/configure-nginx-agent-group.md @@ -3,9 +3,8 @@ title: "Add NGINX users to nginx-agent group" draft: false weight: 300 toc: true -docs: DOCS-933 -type: -- how-to +nd-docs: DOCS-933 +nd-content-type: how-to --- ## Overview diff --git a/content/agent/v2/configuration/encrypt-communication.md b/content/agent/configuration/encrypt-communication.md similarity index 99% rename from content/agent/v2/configuration/encrypt-communication.md rename to content/agent/configuration/encrypt-communication.md index a7cf75134..6a1503cf6 100644 --- a/content/agent/v2/configuration/encrypt-communication.md +++ b/content/agent/configuration/encrypt-communication.md @@ -2,7 +2,7 @@ title: Encrypt communication toc: true weight: 200 -docs: DOCS-802 +nd-docs: DOCS-802 --- ## Overview diff --git a/content/agent/v2/configuration/health-checks.md b/content/agent/configuration/health-checks.md similarity index 98% rename from content/agent/v2/configuration/health-checks.md rename to content/agent/configuration/health-checks.md index 4aa65608a..f57561cbc 100644 --- a/content/agent/v2/configuration/health-checks.md +++ b/content/agent/configuration/health-checks.md @@ -3,8 +3,7 @@ title: Health checks draft: false weight: 400 toc: true -type: -- how-to +nd-content-type: how-to --- ## Overview diff --git a/content/agent/contribute/_index.md b/content/agent/contribute/_index.md deleted file mode 100644 index 029474cbc..000000000 --- a/content/agent/contribute/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Contribute" -weight: 600 -url: /nginx-agent/contribute/ ---- - -Learn about the NGINX Agent community and how to contribute to the project. diff --git a/content/agent/contribute/community.md b/content/agent/contribute/community.md deleted file mode 100644 index 3fbf8f161..000000000 --- a/content/agent/contribute/community.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Community and contribution" -toc: true -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. - -- Our [GitHub issues page](https://github.com/nginx/agent/issues) offers space for a more technical discussion at your own pace. - -# Contribute - -Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details. - -# License - -[Apache License, Version 2.0](https://github.com/nginx/agent/blob/main/LICENSE) diff --git a/content/agent/contribute/dev-environment-setup.md b/content/agent/contribute/dev-environment-setup.md index 0c2f06315..6051aa095 100644 --- a/content/agent/contribute/dev-environment-setup.md +++ b/content/agent/contribute/dev-environment-setup.md @@ -2,7 +2,8 @@ title: "Development environment setup" toc: true weight: 200 -docs: DOCS-000 +nd-docs: DOCS-000 +draft: true --- ## Overview @@ -17,7 +18,7 @@ Ubuntu is the recommended operating system for development, as it comes with mos To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}). +- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}). - 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. @@ -29,7 +30,7 @@ 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 -Follow the steps in the [Installation]({{< ref "/agent/install-upgrade/" >}}) topic to install NGINX Agent. +Follow the steps in the [Installation]({{< ref "/nginx-one/agent/install-upgrade/" >}}) topic to install NGINX Agent. ## Install prerequisite packages Depending on the operating system distribution, it may be necessary to install the following packages in order to build NGINX Agent. diff --git a/content/agent/contribute/start-mock-interface.md b/content/agent/contribute/start-mock-interface.md index 032421862..9b338d09f 100644 --- a/content/agent/contribute/start-mock-interface.md +++ b/content/agent/contribute/start-mock-interface.md @@ -2,7 +2,8 @@ title: Start mock control plane interface toc: true weight: 300 -docs: DOCS-000 +nd-docs: DOCS-000 +draft: true --- This document describes how to configure and run F5 NGINX Agent using a mock interface ("control plane") for NGINX Agent to report to. @@ -13,7 +14,7 @@ The mock interface is useful when developing NGINX Agent, as it allows you to vi To begin this task, you will require the following: -- A [working NGINX Agent instance]({{< ref "/agent/install-upgrade/" >}}). +- A [working NGINX Agent instance]({{< ref "/nginx-one/agent/install-upgrade/" >}}). - A [Go installation](https://go.dev/dl/) of version 1.22.2 or newer. - A [go-swagger](https://goswagger.io/go-swagger/install/) installation. diff --git a/content/agent/v2/installation-upgrade/_index.md b/content/agent/installation-upgrade/_index.md similarity index 71% rename from content/agent/v2/installation-upgrade/_index.md rename to content/agent/installation-upgrade/_index.md index 8f11c8c30..d17ef4d5d 100644 --- a/content/agent/v2/installation-upgrade/_index.md +++ b/content/agent/installation-upgrade/_index.md @@ -3,4 +3,7 @@ title: Installation and upgrade description: Learn how to install, upgrade, and uninstall NGINX Agent. weight: 300 url: /nginx-agent/v2/installation-upgrade/ +cascade: + logo: NGINX-product-icon.png + type: agent-v2-migration --- diff --git a/content/agent/v2/installation-upgrade/container-environments/_index.md b/content/agent/installation-upgrade/container-environments/_index.md similarity index 73% rename from content/agent/v2/installation-upgrade/container-environments/_index.md rename to content/agent/installation-upgrade/container-environments/_index.md index 17c7ca4cc..bc1eeddd7 100644 --- a/content/agent/v2/installation-upgrade/container-environments/_index.md +++ b/content/agent/installation-upgrade/container-environments/_index.md @@ -3,4 +3,7 @@ title: Container environments description: Learn how to build and run NGINX Agent docker images. weight: 800 url: /nginx-agent/v2/installation-upgrade/container-environments/ +cascade: + logo: NGINX-product-icon.png + type: agent-v2-migration --- diff --git a/content/agent/v2/installation-upgrade/container-environments/docker-images.md b/content/agent/installation-upgrade/container-environments/docker-images.md similarity index 97% rename from content/agent/v2/installation-upgrade/container-environments/docker-images.md rename to content/agent/installation-upgrade/container-environments/docker-images.md index c79278f7d..f21c23929 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-images.md +++ b/content/agent/installation-upgrade/container-environments/docker-images.md @@ -3,9 +3,8 @@ title: Build container images draft: false weight: 100 toc: true -docs: DOCS-1410 -type: -- how-to +nd-docs: DOCS-1410 +nd-content-type: how-to --- ## Overview @@ -14,7 +13,7 @@ NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance. -See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/tech-specs.md" >}}) topic. +See the requirements and supported operating systems in the [NGINX Agent Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) topic. ## Deploy Offical NGINX and NGINX Plus Containers @@ -113,7 +112,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]({{< ref "/agent/v2/configuration/configuration-overview" >}}).{{}} +{{}}To learn more about the configuration options, refer to the NGINX Agent [Configuration Overview]({{< ref "/agent/configuration/configuration-overview" >}}).{{}} ### Enable the gRPC interface diff --git a/content/agent/v2/installation-upgrade/container-environments/docker-support.md b/content/agent/installation-upgrade/container-environments/docker-support.md similarity index 87% rename from content/agent/v2/installation-upgrade/container-environments/docker-support.md rename to content/agent/installation-upgrade/container-environments/docker-support.md index c22fa059a..1a57cafab 100644 --- a/content/agent/v2/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/installation-upgrade/container-environments/docker-support.md @@ -3,16 +3,16 @@ title: Container support and troubleshooting draft: false toc: true weight: 200 -docs: DOCS-909 -type: +nd-docs: DOCS-909 +nd-content-type: - task --- ## 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]({{< ref "/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. +The NGINX Agent repository includes [Dockerfiles](https://github.com/nginx/agent/tree/main/scripts/docker) that can be used to [build custom container images]({{< ref "/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. -See the [Technical Specifications]({{< ref "/agent/tech-specs.md#container-support" >}}) for a list of supported operationg systems. +See the [Technical Specifications]({{< ref "/agent/technical-specifications.md" >}}) for a list of supported operationg systems. NGINX Agent running in a container has some limitations that need to be considered, and are listed below. diff --git a/content/agent/v2/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md similarity index 98% rename from content/agent/v2/installation-upgrade/getting-started.md rename to content/agent/installation-upgrade/getting-started.md index 86b5efc90..c7ee427af 100644 --- a/content/agent/v2/installation-upgrade/getting-started.md +++ b/content/agent/installation-upgrade/getting-started.md @@ -3,9 +3,8 @@ title: Getting started draft: false weight: 100 toc: true -docs: DOCS-1089 -type: -- how-to +nd-docs: DOCS-1089 +nd-content-type: how-to --- ## Overview @@ -176,5 +175,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]({{< ref "/agent/v2/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). +For more information, see [NGINX Agent Log Rotation]({{< ref "/agent/configuration/configuration-overview.md#nginx-agent-log-rotation" >}}). {{< /important >}} diff --git a/content/agent/v2/installation-upgrade/installation-github.md b/content/agent/installation-upgrade/installation-github.md similarity index 97% rename from content/agent/v2/installation-upgrade/installation-github.md rename to content/agent/installation-upgrade/installation-github.md index 282f1e8d9..d1cbbb2d6 100644 --- a/content/agent/v2/installation-upgrade/installation-github.md +++ b/content/agent/installation-upgrade/installation-github.md @@ -3,9 +3,8 @@ title: Installation from GitHub release draft: false weight: 200 toc: true -docs: DOCS-1090 -type: -- how-to +nd-docs: DOCS-1090 +nd-content-type: how-to --- ## Overview diff --git a/content/agent/v2/installation-upgrade/installation-oss.md b/content/agent/installation-upgrade/installation-oss.md similarity index 99% rename from content/agent/v2/installation-upgrade/installation-oss.md rename to content/agent/installation-upgrade/installation-oss.md index fb4f2fb48..ab4016d08 100644 --- a/content/agent/v2/installation-upgrade/installation-oss.md +++ b/content/agent/installation-upgrade/installation-oss.md @@ -3,9 +3,8 @@ title: Installation from NGINX repository draft: false weight: 300 toc: true -docs: DOCS-1216 -type: -- how-to +nd-docs: DOCS-1216 +nd-content-type: how-to --- ## Overview @@ -15,7 +14,7 @@ Learn how to install NGINX Agent from the NGINX Open Source repository. ## Prerequisites - NGINX installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) -- A [supported operating system and architecture]({{< ref "/agent/tech-specs.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) - `root` privilege ## Configure NGINX OSS Repository for installing NGINX Agent diff --git a/content/agent/v2/installation-upgrade/installation-plus.md b/content/agent/installation-upgrade/installation-plus.md similarity index 99% rename from content/agent/v2/installation-upgrade/installation-plus.md rename to content/agent/installation-upgrade/installation-plus.md index 93c83dc59..add1272dc 100644 --- a/content/agent/v2/installation-upgrade/installation-plus.md +++ b/content/agent/installation-upgrade/installation-plus.md @@ -3,9 +3,8 @@ title: Installation from NGINX Plus repository draft: false weight: 400 toc: true -docs: DOCS-1217 -type: -- how-to +nd-docs: DOCS-1217 +nd-content-type: how-to --- ## Overview @@ -16,7 +15,7 @@ Learn how to install NGINX Agent from NGINX Plus repository - An NGINX Plus subscription (purchased or trial) - NGINX Plus installed. Once installed, ensure it is running. If you don't have it installed already, follow these steps to install [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/) -- A [supported operating system and architecture]({{< ref "/agent/tech-specs.md#supported-distributions" >}}) +- A [supported operating system and architecture]({{< ref "/agent/technical-specifications.md#supported-distributions" >}}) - `root` privilege - Your credentials to the MyF5 Customer Portal, provided by email from F5, Inc. - Your NGINX Plus certificate and public key (`nginx-repo.crt` and `nginx-repo.key` files), provided by email from F5, Inc. diff --git a/content/agent/v2/installation-upgrade/installation-unprivileged.md b/content/agent/installation-upgrade/installation-unprivileged.md similarity index 93% rename from content/agent/v2/installation-upgrade/installation-unprivileged.md rename to content/agent/installation-upgrade/installation-unprivileged.md index e32029d9d..a89f532ef 100644 --- a/content/agent/v2/installation-upgrade/installation-unprivileged.md +++ b/content/agent/installation-upgrade/installation-unprivileged.md @@ -2,7 +2,8 @@ title: Run without root privileges weight: 450 toc: true -type: how-to +nd-content-type: + - how-to product: Agent --- @@ -29,12 +30,12 @@ The installation process involves installing NGINX Plus without root privileges You can install NGINX Plus without root privileges following the steps on the [NGINX Plus installation page]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus/#unpriv_install" >}}). The steps include a script that will allow you to install NGINX Plus in a non-root environment. {{< note >}} -NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/v2/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group. +NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group. {{< /note >}} ### Install NGINX Agent -After installing NGINX Plus, you can install NGINX agent following the steps on the [NGINX Agent installation page]({{< ref "/agent/v2/installation-upgrade/installation-oss.md" >}}). +After installing NGINX Plus, you can install NGINX agent following the steps on the [NGINX Agent installation page]({{< ref "/agent/installation-upgrade/installation-oss.md" >}}). ### Start NGINX Agent diff --git a/content/agent/v2/installation-upgrade/uninstall.md b/content/agent/installation-upgrade/uninstall.md similarity index 98% rename from content/agent/v2/installation-upgrade/uninstall.md rename to content/agent/installation-upgrade/uninstall.md index 2f783dbb6..56db538f0 100644 --- a/content/agent/v2/installation-upgrade/uninstall.md +++ b/content/agent/installation-upgrade/uninstall.md @@ -3,9 +3,8 @@ title: Uninstall NGINX Agent package draft: false weight: 700 toc: true -docs: DOCS-1230 -type: -- how-to +nd-docs: DOCS-1230 +nd-content-type: how-to --- ## Overview diff --git a/content/agent/v2/installation-upgrade/upgrade.md b/content/agent/installation-upgrade/upgrade.md similarity index 97% rename from content/agent/v2/installation-upgrade/upgrade.md rename to content/agent/installation-upgrade/upgrade.md index 50477e94b..6182d996c 100644 --- a/content/agent/v2/installation-upgrade/upgrade.md +++ b/content/agent/installation-upgrade/upgrade.md @@ -3,9 +3,8 @@ title: Upgrade NGINX Agent package draft: false weight: 600 toc: true -docs: DOCS-1227 -type: -- how-to +nd-docs: DOCS-1227 +nd-content-type: how-to --- ## Overview diff --git a/content/agent/otel/_index.md b/content/agent/otel/_index.md deleted file mode 100644 index 0e113fe11..000000000 --- a/content/agent/otel/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: OpenTelemetry -weight: 450 -url: /nginx-agent/otel/ ---- \ No newline at end of file diff --git a/content/agent/tech-specs.md b/content/agent/tech-specs.md deleted file mode 100644 index b74911c7f..000000000 --- a/content/agent/tech-specs.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Technical Specifications" -toc: false -weight: 150 -docs: DOCS-000 ---- - -{{< include "/agent/tech-specs.md" >}} diff --git a/content/agent/v2/technical-specifications.md b/content/agent/technical-specifications.md similarity index 95% rename from content/agent/v2/technical-specifications.md rename to content/agent/technical-specifications.md index efa731527..d9e88f2bf 100644 --- a/content/agent/v2/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -2,7 +2,7 @@ title: "Technical specifications" weight: 100 toc: true -docs: "DOCS-1092" +nd-docs: "DOCS-1092" --- This document describes the requirements for NGINX Agent v2. @@ -12,7 +12,7 @@ This document describes the requirements for NGINX Agent v2. 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 | +| | 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 | @@ -26,7 +26,7 @@ NGINX Agent can run in most environments. We support the following distributions {{< /bootstrap-table >}} -## Supported deployment environments +## Supported deployment environments NGINX Agent can be deployed in the following environments: @@ -35,7 +35,7 @@ NGINX Agent can be deployed in the following environments: - Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure - Virtual Machine -## Supported NGINX versions +## Supported NGINX versions NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus. diff --git a/content/agent/v2/_index.md b/content/agent/v2/_index.md deleted file mode 100644 index df7a692dd..000000000 --- a/content/agent/v2/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -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 deleted file mode 100644 index ff7f3c9f2..000000000 --- a/content/agent/v2/changelog.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -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]({{< ref "./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 deleted file mode 100644 index 4429d1349..000000000 --- a/content/agent/v2/configuration/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -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/includes/agent/about.md b/content/includes/agent/about.md index 9025e2f56..4125fd568 100644 --- a/content/includes/agent/about.md +++ b/content/includes/agent/about.md @@ -13,14 +13,14 @@ 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. - - [Connects NGINX instances to NGINX One Console]({{< ref "/agent/install-upgrade/install-from-oss-repo.md#connect-an-instance-to-nginx-one-console" >}}) + - [Connects NGINX instances to NGINX One Console]({{< ref "/nginx-one/agent/install-upgrade/install-from-oss-repo.md#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. - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/), and the ability to - [export the metrics data]({{< ref "/agent/otel/configure-otel-metrics.md" >}}) for use in other applications. + [export the metrics data]({{< ref "/nginx-one/agent/configure-otel-metrics.md" >}}) for use in other applications. diff --git a/content/includes/agent/installation/prerequisites.md b/content/includes/agent/installation/prerequisites.md index 709bae10f..6b7b039ca 100644 --- a/content/includes/agent/installation/prerequisites.md +++ b/content/includes/agent/installation/prerequisites.md @@ -8,6 +8,6 @@ files: - content/nginx-one/agent/install-from-plus-repo.md --- -- You must use one of the [supported operating system and architectures]({{< ref "/agent/tech-specs.md#supported-distributions" >}}) +- You must use one of the [supported operating system and architectures]({{< ref "/nginx-one/agent/tech-specs.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. \ No newline at end of file diff --git a/content/nginx-one/agent/_index.md b/content/nginx-one/agent/_index.md index b2225884d..37e8b880d 100644 --- a/content/nginx-one/agent/_index.md +++ b/content/nginx-one/agent/_index.md @@ -2,5 +2,5 @@ title: NGINX Agent description: weight: 1100 -url: /nginx-one/nginx-agent +url: /nginx-one/agent --- diff --git a/content/nginx-one/agent/about.md b/content/nginx-one/agent/about.md index 0fc25820a..c9a0ae627 100644 --- a/content/nginx-one/agent/about.md +++ b/content/nginx-one/agent/about.md @@ -7,7 +7,7 @@ toc: true {{}} NGINX Agent v3.0 is a major release that introduces new features and enhancements. -Visit our [Update]({{< ref "/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. +Visit our [Update]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. {{}} {{< include "agent/about.md" >}} diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md new file mode 100644 index 000000000..f4514e16d --- /dev/null +++ b/content/nginx-one/agent/changelog.md @@ -0,0 +1,21 @@ +--- +title: "NGINX Agent Changelog" +weight: 700 +toc: true +--- + +{{< 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]({{< ref "/nginx-one/agent/tech-specs.md" >}}). + +--- +## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) + +### 🌟 Highlights + +### πŸ› Bug Fixes + +### πŸ“ Documentation + +### πŸ”¨ Maintenance + diff --git a/content/nginx-one/agent/community.md b/content/nginx-one/agent/community.md new file mode 100644 index 000000000..013d2e302 --- /dev/null +++ b/content/nginx-one/agent/community.md @@ -0,0 +1,20 @@ +--- +title: "Community and contribution" +toc: true +weight: 600 +docs: DOCS-000 +--- + +Discover the various ways you can participate in the F5 NGINX Agent project: + +## Community + +- Have questions or ideas to discuss? Join the conversation about NGINX Agent in the [NGINX Community Forum](https://community.nginx.org/). + +## Contribute + +Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details. + +## License + +[Apache License, Version 2.0](https://github.com/nginx/agent/blob/main/LICENSE) diff --git a/content/agent/otel/configure-otel-metrics.md b/content/nginx-one/agent/configure-otel-metrics.md similarity index 87% rename from content/agent/otel/configure-otel-metrics.md rename to content/nginx-one/agent/configure-otel-metrics.md index 0e302b7a4..796897346 100644 --- a/content/agent/otel/configure-otel-metrics.md +++ b/content/nginx-one/agent/configure-otel-metrics.md @@ -1,13 +1,14 @@ --- -title: Export metrics with NGINX Agent -weight: 200 +title: Export NGINX instance metrics +weight: 450 +toc: true --- ## Overview -F5 NGINX Agent now includes an embedded [OpenTelemetry](https://opentelemetry.io/) collector, streamlining observability and metric collection for NGINX instances. With this feature, you can collect: +F5 NGINX Agent 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 Open Source +* Metrics from NGINX Plus and NGINX Open Source * Host metrics (CPU, memory, disk, and network activity) from VMs or Containers {{< note >}} @@ -21,7 +22,7 @@ The OpenTelemetry exporter is enabled by default. Once a valid connection to the ### Verify that metrics are exported -You can validate that metrics are successfully exported by using the methods below: +You can validate that metrics are successfully exported by using the methods below: - **NGINX One dashboard** @@ -29,11 +30,11 @@ You can validate that metrics are successfully exported by using the methods bel - **Agent logs** - Check the OpenTelemetry Collector logs for confirmation of successful metric processing: + Check the OpenTelemetry Collector logs for confirmation of successful metric processing: 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` - 2. Look for the following logs: - + 2. Look for the following logs: + ```text Everything is ready. Begin running and processing data. - ``` \ No newline at end of file + ``` diff --git a/content/nginx-one/agent/connect-instances-to-console.md b/content/nginx-one/agent/connect-instances-to-console.md deleted file mode 100644 index fceac3377..000000000 --- a/content/nginx-one/agent/connect-instances-to-console.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Connect NGINX instances to NGINX One Console -toc: true -weight: 300 -docs: DOCS-000 ---- - -{{< include "/nginx-one/how-to/add-instance.md" >}} \ No newline at end of file diff --git a/content/agent/how-to/_index.md b/content/nginx-one/agent/how-to/_index.md similarity index 100% rename from content/agent/how-to/_index.md rename to content/nginx-one/agent/how-to/_index.md diff --git a/content/agent/how-to/configuration-overview.md b/content/nginx-one/agent/how-to/configuration-overview.md similarity index 100% rename from content/agent/how-to/configuration-overview.md rename to content/nginx-one/agent/how-to/configuration-overview.md diff --git a/content/agent/how-to/configure-agent-group.md b/content/nginx-one/agent/how-to/configure-agent-group.md similarity index 100% rename from content/agent/how-to/configure-agent-group.md rename to content/nginx-one/agent/how-to/configure-agent-group.md diff --git a/content/agent/how-to/connect-management-plane.md b/content/nginx-one/agent/how-to/connect-management-plane.md similarity index 100% rename from content/agent/how-to/connect-management-plane.md rename to content/nginx-one/agent/how-to/connect-management-plane.md diff --git a/content/agent/how-to/enable-interfaces.md b/content/nginx-one/agent/how-to/enable-interfaces.md similarity index 87% rename from content/agent/how-to/enable-interfaces.md rename to content/nginx-one/agent/how-to/enable-interfaces.md index a0e6c553c..2fc194e20 100644 --- a/content/agent/how-to/enable-interfaces.md +++ b/content/nginx-one/agent/how-to/enable-interfaces.md @@ -70,4 +70,4 @@ api: To apply the new configuration, NGINX Agent must be started or restarted. -You may want to view the [Start mock control plane interface]({{< ref "/agent/contribute/start-mock-interface.md" >}}) topic to test NGINX Agent, or view the [Configuration overview]({{< ref "/agent/how-to/configuration-overview.md" >}}) for more options. \ No newline at end of file +You may want to start the mock control plane interface to test NGINX Agent, or view the [Configuration overview]({{< ref "/nginx-one/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/nginx-one/agent/how-to/encrypt-communication.md similarity index 100% rename from content/agent/how-to/encrypt-communication.md rename to content/nginx-one/agent/how-to/encrypt-communication.md diff --git a/content/agent/how-to/run-agent-container.md b/content/nginx-one/agent/how-to/run-agent-container.md similarity index 100% rename from content/agent/how-to/run-agent-container.md rename to content/nginx-one/agent/how-to/run-agent-container.md diff --git a/content/nginx-one/agent/install-from-oss-repo.md b/content/nginx-one/agent/install-from-oss-repo.md deleted file mode 100644 index dd8ebd4ae..000000000 --- a/content/nginx-one/agent/install-from-oss-repo.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Install from Open Source repo -toc: true -weight: 100 -docs: DOCS-000 ---- - -{{< note>}} -If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) -to manage your NGINX instances, NGINX Agent is installed automatically when you -add an NGINX instance to NGINX One Console. - -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) -{{< /note >}} - -Follow the steps in this guide to install NGINX Agent in your NGINX instance using -the NGINX Open Source repository. - -## Before you begin - -{{< include "/agent/installation/prerequisites.md" >}} - -## 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 - -{{< include "/agent/installation/oss/oss-rhel.md" >}} - -
    - -
    -{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu - -### Install NGINX Agent on Ubuntu - -{{< include "/agent/installation/oss/oss-ubuntu.md" >}} - -
    - -
    -{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian - -### Install NGINX Agent on Debian - -{{< include "/agent/installation/oss/oss-debian.md" >}} - -
    - -
    -{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES - -### Install NGINX Agent on SLES - -{{< include "/agent/installation/oss/oss-sles.md" >}} - -
    - -
    -{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux - -### Install NGINX Agent on Alpine Linux - -{{< include "/agent/installation/oss/oss-alpine.md" >}} - -
    - -
    -{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux - -### Install NGINX Agent on Amazon Linux - -{{< include "/agent/installation/oss/oss-amazon-linux.md" >}} - -
    -
    -{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD - -### Install NGINX Agent on FreeBSD - -{{< include "/agent/installation/oss/oss-freebsd.md" >}} - -
    - -### Manually connect NGINX Agent to NGINX One Console - -{{< include "agent/installation/manually-connect-to-console" >}} - -## Start, stop, and enable NGINX Agent - -{{< include "/agent/installation/start-stop-agent.md" >}} - -## Verify that NGINX Agent is running - -{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/nginx-one/agent/install-from-plus-repo.md b/content/nginx-one/agent/install-from-plus-repo.md deleted file mode 100644 index 55fc0eea9..000000000 --- a/content/nginx-one/agent/install-from-plus-repo.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Install from NGINX Plus repo -toc: true -weight: 200 -docs: DOCS-000 ---- - -{{< note>}} -If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) -to manage your NGINX instances, NGINX Agent is installed automatically when you -add an NGINX instance to NGINX One Console. - -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< relref "/nginx-one/how-to/nginx-configs/add-instance" >}}) -{{< /note >}} - -Follow the steps in this guide to install NGINX Agent in your NGINX instance using -the NGINX Plus repository. - -## Before you begin - -{{< include "/agent/installation/prerequisites.md" >}} - -## 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 - -{{< include "/agent/installation/plus/plus-rhel.md" >}} - -
    - -
    -{{< fa "brands fa-ubuntu" >}} Install NGINX Agent on Ubuntu - -### Install NGINX Agent on Ubuntu - -{{< include "/agent/installation/plus/plus-ubuntu.md" >}} - -
    - -
    -{{< fa "brands fa-debian" >}} Install NGINX Agent on Debian - -### Install NGINX Agent on Debian - -{{< include "/agent/installation/plus/plus-debian.md" >}} - -
    - -
    -{{< fa "brands fa-suse" >}} Install NGINX Agent on SLES - -### Install NGINX Agent on SLES - -{{< include "/agent/installation/plus/plus-sles.md" >}} - -
    - -
    -{{< fa "solid fa-mountain-sun" >}} Install NGINX Agent on Alpine Linux - -### Install NGINX Agent on Alpine Linux - -{{< include "/agent/installation/plus/plus-alpine.md" >}} - -
    -
    -{{< fa "brands fa-aws" >}} Install NGINX Agent on Amazon Linux - -### Install NGINX Agent on Amazon Linux - -{{< include "/agent/installation/plus/plus-amazon-linux.md" >}} - -
    - -
    -{{< fa "brands fa-freebsd" >}} Install NGINX Agent on FreeBSD - -### Install NGINX Agent on FreeBSD - -{{< include "/agent/installation/plus/plus-freebsd.md" >}} - -
    - -### Manually connect NGINX Agent to NGINX One Console - -{{< include "agent/installation/manually-connect-to-console" >}} - -## Start, stop, and enable NGINX Agent - -{{< include "/agent/installation/start-stop-agent.md" >}} - -## Verify that NGINX Agent is running - -{{< include "/agent/installation/verify-agent.md" >}} diff --git a/content/agent/install-upgrade/_index.md b/content/nginx-one/agent/install-upgrade/_index.md similarity index 100% rename from content/agent/install-upgrade/_index.md rename to content/nginx-one/agent/install-upgrade/_index.md diff --git a/content/agent/install-upgrade/install-from-github.md b/content/nginx-one/agent/install-upgrade/install-from-github.md similarity index 100% rename from content/agent/install-upgrade/install-from-github.md rename to content/nginx-one/agent/install-upgrade/install-from-github.md diff --git a/content/agent/install-upgrade/install-from-oss-repo.md b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md similarity index 100% rename from content/agent/install-upgrade/install-from-oss-repo.md rename to content/nginx-one/agent/install-upgrade/install-from-oss-repo.md diff --git a/content/agent/install-upgrade/install-from-plus-repo.md b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md similarity index 100% rename from content/agent/install-upgrade/install-from-plus-repo.md rename to content/nginx-one/agent/install-upgrade/install-from-plus-repo.md diff --git a/content/agent/install-upgrade/uninstall.md b/content/nginx-one/agent/install-upgrade/uninstall.md similarity index 100% rename from content/agent/install-upgrade/uninstall.md rename to content/nginx-one/agent/install-upgrade/uninstall.md diff --git a/content/agent/install-upgrade/update.md b/content/nginx-one/agent/install-upgrade/update.md similarity index 100% rename from content/agent/install-upgrade/update.md rename to content/nginx-one/agent/install-upgrade/update.md diff --git a/content/agent/troubleshooting.md b/content/nginx-one/agent/troubleshooting.md similarity index 100% rename from content/agent/troubleshooting.md rename to content/nginx-one/agent/troubleshooting.md diff --git a/content/nginx-one/agent/uninstall.md b/content/nginx-one/agent/uninstall.md deleted file mode 100644 index 169029461..000000000 --- a/content/nginx-one/agent/uninstall.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Uninstall NGINX Agent" -toc: true -weight: 500 -docs: DOCS-000 ---- - -## Overview - -Learn how to uninstall F5 NGINX Agent from your system. - -## Before you begin - -The user following performing the uninstall steps needs to have `root` privilege. - -## Uninstall NGINX Agent - -Complete the following steps on each host where you've installed NGINX Agent - -
    -{{< fa "brands fa-centos" >}} Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux - -### Uninstall NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux - -{{< include "/agent/installation/uninstall/uninstall-rhel.md" >}} - -
    - -
    -{{< fa "brands fa-ubuntu" >}} Uninstall NGINX Agent on Ubuntu - -### Uninstall NGINX Agent on Ubuntu - -{{< include "/agent/installation/uninstall/uninstall-ubuntu.md" >}} - -
    - -
    -{{< fa "brands fa-debian" >}} Uninstall NGINX Agent on Debian - -### Uninstall NGINX Agent on Debian - -{{< include "/agent/installation/uninstall/uninstall-debian.md" >}} - -
    - -
    -{{< fa "brands fa-suse" >}} Uninstall NGINX Agent on SLES - -### Uninstall NGINX Agent on SLES - -{{< include "/agent/installation/uninstall/uninstall-sles.md" >}} - -
    - -
    -{{< fa "solid fa-mountain-sun" >}} Uninstall NGINX Agent on Alpine Linux - -### Uninstall NGINX Agent on Alpine Linux - -{{< include "/agent/installation/uninstall/uninstall-alpine.md" >}} - -
    - -
    -{{< fa "brands fa-aws" >}} Uninstall NGINX Agent on Amazon Linux - -### Uninstall NGINX Agent on Amazon Linux - -{{< include "/agent/installation/uninstall/uninstall-amazon-linux.md" >}} - -
    - -
    -{{< fa "brands fa-freebsd" >}} Uninstall NGINX Agent on FreeBSD - -### Uninstall NGINX Agent on FreeBSD - -{{< include "/agent/installation/uninstall/uninstall-freebsd.md" >}} - -
    diff --git a/content/nginx-one/agent/update.md b/content/nginx-one/agent/update.md deleted file mode 100644 index 09de27120..000000000 --- a/content/nginx-one/agent/update.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Update NGINX Agent" -toc: true -weight: 400 -docs: DOCS-000 ---- - -{{< include "/agent/installation/update.md" >}} - -## Migrate NGINX Agent running in containers - -{{< include "/agent/installation/update-container.md" >}} \ No newline at end of file diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index 9e3a0e8e5..65279befd 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -88,18 +88,7 @@ To install NGINX Agent on an NGINX instance: - Replace `YOUR_DATA_PLANE_KEY` with your actual data plane key. - The `-y` option automatically confirms any prompts during installation. -The `install` script writes an `nginx-agent.conf` file to the `/etc/nginx-agent/` directory, with the [data plane key](#generate-data-plane-key) that you generated. You can find this information in the `nginx-agent.conf` file: - -```yaml -server: - token: "" - host: agent.connect.nginx.com - grpcPort: 443 - -tls: - enable: True - skip_verify: False -``` +The `install` script writes an `nginx-agent.conf` file to the `/etc/nginx-agent/` directory, with the [data plane key](#generate-data-plane-key) that you generated. You can find the key, host address, TLS status, and other information in the `nginx-agent.conf` file. If you followed the [Installation and upgrade](https://docs.nginx.com/nginx-agent/installation-upgrade/) guides for installing NGINX Agent, you may need to add this information manually to `nginx-agent.conf`. @@ -170,7 +159,7 @@ nginx -s reload {{< include "/use-cases/monitoring/enable-nginx-oss-stub-status.md" >}} ---- +--- ## View instance metrics with the NGINX One dashboard diff --git a/layouts/agent-v2-migration/single.html b/layouts/agent-v2-migration/single.html index e91863080..faeed088a 100644 --- a/layouts/agent-v2-migration/single.html +++ b/layouts/agent-v2-migration/single.html @@ -12,10 +12,11 @@
    {{ 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. + This documentation is for NGINX Agent v2. Follow the Update NGINX Agent topic to learn how to upgrade your instances to the latest version. +

    For NGINX Agent v3 documentation, visit the NGINX One Console docs.
    diff --git a/layouts/partials/agent-v2-migration/list-main.html b/layouts/partials/agent-v2-migration/list-main.html index 51c39a214..4a0369e8c 100644 --- a/layouts/partials/agent-v2-migration/list-main.html +++ b/layouts/partials/agent-v2-migration/list-main.html @@ -9,12 +9,13 @@

    {{ .Description | markdownify }}

    {{ 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. + This documentation is for NGINX Agent v2. Follow the Update NGINX Agent topic to learn how to upgrade your instances to the latest version. +

    For NGINX Agent v3 documentation, visit the NGINX One Console docs.
    -
    +
    {{ if .Content }}

    {{ .Content | markdownify }} @@ -27,7 +28,7 @@

    {{ range .Pages.GroupBy "Section" }} - + {{ range .Pages.ByWeight }}
    @@ -36,18 +37,18 @@

    {{ .Title }}

    {{/*}}

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

    {{*/}} - +
    {{ end }} -
    -
    + + {{ end }} - + \ No newline at end of file From dda165a7bc65bbbf29a074dbdbf5186e999d3d23 Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Wed, 7 May 2025 15:08:20 +0100 Subject: [PATCH 24/63] Add environment variables table to Configuration Overview (#532) Add a table that details agents options --- .../agent/how-to/configuration-overview.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/content/nginx-one/agent/how-to/configuration-overview.md b/content/nginx-one/agent/how-to/configuration-overview.md index 03fbe48ac..df2d72a94 100644 --- a/content/nginx-one/agent/how-to/configuration-overview.md +++ b/content/nginx-one/agent/how-to/configuration-overview.md @@ -48,3 +48,39 @@ sudo docker run \ --env=NGINX_AGENT_LOG_LEVEL=debug \ -d agent ``` +
    +NGINX Agent configuration options + +{{< bootstrap-table "table table-striped table-bordered" >}} +| **Environment Variable** | **Command-Line Option** | **Description** | **Default Value** | +|--------------------------------------------------|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------|--------------------------------------------------------| +| NGINX_AGENT_LOG_LEVEL | --log-level | The desired verbosity level for logging messages from nginx-agent. Available options: panic, fatal, error, info, and debug. | info | +| NGINX_AGENT_LOG_PATH | --log-path | The path to output log messages to. If the default path doesn't exist, logs are output to stdout/stderr. | /var/log/nginx-agent/nginx-agent.log | +| NGINX_AGENT_DATA_PLANE_NGINX_RELOAD_MONITORING_PERIOD | --data-plane-config-nginx-reload-monitoring-period | The amount of time used to monitor NGINX after a configuration reload (units in seconds). | N/A | +| NGINX_AGENT_DATA_PLANE_NGINX_TREAT_WARNINGS_AS_ERRORS | --data-plane-config-nginx-treat-warnings-as-errors | Warning messages in the NGINX error logs are treated as errors after a configuration reload. | N/A | +| NGINX_AGENT_DATA_PLANE_NGINX_EXCLUDE_LOGS | --data-plane-config-nginx-exclude-logs | Specify one or more log paths to exclude from metrics collection and error monitoring (Unix PATH format). | N/A | +| NGINX_AGENT_ALLOWED_DIRECTORIES | --allowed-directories | A comma-separated list of paths granting read/write permissions for the agent. | N/A | +| NGINX_AGENT_FEATURES | --features | Comma-separated list of features enabled for the agent. | N/A | +| NGINX_AGENT_LABELS | --labels | A comma-separated list of key-value pairs defining agent labels (e.g., grouping). | N/A | +| NGINX_AGENT_COMMAND_SERVER_HOST | --command-server-host | Specifies target hostname for the command and control server. | N/A | +| NGINX_AGENT_COMMAND_SERVER_PORT | --command-server-port | Specifies the port of the command and control server. | N/A | +| NGINX_AGENT_COMMAND_AUTH_TOKEN | --command-auth-token | Authentication token used to establish communication with the command server. | N/A | +| NGINX_AGENT_COMMAND_AUTH_TOKENPATH | --command-auth-tokenpath | File path for the authentication token used with the server. | N/A | +| NGINX_AGENT_COMMAND_TLS_CERT | --command-tls-cert | Certificate file path required for TLS communication. | N/A | +| NGINX_AGENT_COMMAND_TLS_KEY | --command-tls-key | Certificate key file path required for TLS communication. | N/A | +| NGINX_AGENT_COMMAND_TLS_CA | --command-tls-ca | CA certificate file path for TLS communication. | N/A | +| NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY | --command-tls-skip-verify | **For Testing Only:** Disables client-side verification of the server's certificate chain and hostname. | N/A | +| NGINX_AGENT_COMMAND_TLS_SERVER_NAME | --command-tls-server-name | Specifies server name sent in the TLS handshake configuration. | N/A | +| NGINX_AGENT_INSTANCE_WATCHER_MONITORING_FREQUENCY | --instance-watcher-monitoring-frequency | Frequency (in seconds) for instance monitoring. | N/A | +| NGINX_AGENT_HEALTH_WATCHER_MONITORING_FREQUENCY | --health-watcher-monitoring-frequency | Frequency (in seconds) for monitoring NGINX health changes. | N/A | +| NGINX_AGENT_FILE_WATCHER_MONITORING_FREQUENCY | --file-watcher-monitoring-frequency | Frequency (in seconds) for monitoring file changes. | N/A | +| NGINX_AGENT_COLLECTOR_CONFIG_PATH | --collector-config-path | Path to OpenTelemetry (OTel) Collector configuration file. | /etc/nginx-agent/opentelemetry-collector-agent.yaml | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_HEALTH_PATH | --collector-extensions-health-path | Path configured for health check server communication with OTel Collector. | / | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_SERVER_HOST | --collector-extensions-health-server-host | Hostname for publishing health check statuses of OTel Collector. | localhost | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_SERVER_PORT | --collector-extensions-health-server-port | Port for publishing health check statuses of OTel Collector. | 13133 | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_TLS_CA | --collector-extensions-health-tls-ca | CA certificate file path for TLS communication with OTel health server. | N/A | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_TLS_CERT | --collector-extensions-health-tls-cert | TLS Certificate file path for communication with OTel health server. | N/A | +| NGINX_AGENT_COLLECTOR_EXTENSIONS_TLS_KEY | --collector-extensions-health-tls-key | File path for TLS key used when connecting with OTel health server. | N/A | +| NGINX_AGENT_COLLECTOR_PROCESSORS_BATCH_SEND_BATCH_TIMEOUT | --collector-processors-batch-send-batch-timeout | Maximum time duration for sending batch data metrics regardless of size. | 200ms +{{< /bootstrap-table >}} |% +
    \ No newline at end of file From 879d759e84a1a62f0ba81e6c98221eec10e371a4 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Thu, 15 May 2025 17:34:14 +0100 Subject: [PATCH 25/63] fix: remove content from list sections for agent --- content/nginx-one/agent/how-to/_index.md | 2 -- content/nginx-one/agent/install-upgrade/_index.md | 4 +--- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/content/nginx-one/agent/how-to/_index.md b/content/nginx-one/agent/how-to/_index.md index d0f9b4cc5..99d8bc45e 100644 --- a/content/nginx-one/agent/how-to/_index.md +++ b/content/nginx-one/agent/how-to/_index.md @@ -3,5 +3,3 @@ 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/nginx-one/agent/install-upgrade/_index.md b/content/nginx-one/agent/install-upgrade/_index.md index 7890ac2b5..d8ba0318e 100644 --- a/content/nginx-one/agent/install-upgrade/_index.md +++ b/content/nginx-one/agent/install-upgrade/_index.md @@ -2,6 +2,4 @@ title: "Install and update" weight: 400 url: /nginx-agent/install-upgrade/ ---- - -Learn how to install, upgrade, and uninstall NGINX Agent. \ No newline at end of file +--- \ No newline at end of file From 44cc12568a499115a6a03179ff9db6340e2a7fa1 Mon Sep 17 00:00:00 2001 From: John David White <127981157+john-david3@users.noreply.github.com> Date: Mon, 19 May 2025 13:28:31 +0100 Subject: [PATCH 26/63] Update agent install docs (#559) * Update agent install docs * PR feedback * PR feedback --- .../installation/manually-connect-to-console.md | 13 ++++++++++++- go.mod | 2 +- go.sum | 2 ++ 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/content/includes/agent/installation/manually-connect-to-console.md b/content/includes/agent/installation/manually-connect-to-console.md index 27d22d2e9..065990a75 100644 --- a/content/includes/agent/installation/manually-connect-to-console.md +++ b/content/includes/agent/installation/manually-connect-to-console.md @@ -2,6 +2,11 @@ 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 + + ```shell + nginx-agent -v + ``` + 1. Locate the NGINX Agent Configuration File: ```shell @@ -19,5 +24,11 @@ NGINX One Console to manage your NGINX instances. 1. Restart the NGINX Agent service: ```shell - sudo systemctl stop nginx-agent + sudo systemctl restart nginx-agent + ``` + +1. Check the Agent log for `"Agent Connected"` + + ```shell + sudo cat /var/log/nginx-agent/agent.log | grep "Agent connected" ``` \ No newline at end of file diff --git a/go.mod b/go.mod index 602575fd1..24c110672 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.30 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.34 // indirect diff --git a/go.sum b/go.sum index 1349b409d..635374884 100644 --- a/go.sum +++ b/go.sum @@ -6,3 +6,5 @@ github.com/nginxinc/nginx-hugo-theme v0.42.28 h1:1SGzBADcXnSqP4rOKEhlfEUloopH6Uv github.com/nginxinc/nginx-hugo-theme v0.42.28/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.30 h1:qcHvB8tElbFN5ZWgs/TGn5IEmvnT5PG4ImQCCbMZ/Rw= github.com/nginxinc/nginx-hugo-theme v0.42.30/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.34 h1:9wNBHsyjY89YDI8vTYHav3YHPR2ngqKKtX5S8y9gFHg= +github.com/nginxinc/nginx-hugo-theme v0.42.34/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From e65870197dcf17f0b73ba9627fc7433364e25a0b Mon Sep 17 00:00:00 2001 From: nginx-seanmoloney <133861979+nginx-seanmoloney@users.noreply.github.com> Date: Wed, 21 May 2025 11:17:19 +0100 Subject: [PATCH 27/63] Clean up files (#576) Remove files: connect-management-plane.md, enable-interfaces.md, encrypt-communication.md --- .../agent/how-to/connect-management-plane.md | 114 ---------------- .../agent/how-to/enable-interfaces.md | 73 ---------- .../agent/how-to/encrypt-communication.md | 126 ------------------ 3 files changed, 313 deletions(-) delete mode 100644 content/nginx-one/agent/how-to/connect-management-plane.md delete mode 100644 content/nginx-one/agent/how-to/enable-interfaces.md delete mode 100644 content/nginx-one/agent/how-to/encrypt-communication.md diff --git a/content/nginx-one/agent/how-to/connect-management-plane.md b/content/nginx-one/agent/how-to/connect-management-plane.md deleted file mode 100644 index c0919d65e..000000000 --- a/content/nginx-one/agent/how-to/connect-management-plane.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -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/nginx-one/agent/how-to/enable-interfaces.md b/content/nginx-one/agent/how-to/enable-interfaces.md deleted file mode 100644 index 2fc194e20..000000000 --- a/content/nginx-one/agent/how-to/enable-interfaces.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -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 start the mock control plane interface to test NGINX Agent, or view the [Configuration overview]({{< ref "/nginx-one/agent/how-to/configuration-overview.md" >}}) for more options. \ No newline at end of file diff --git a/content/nginx-one/agent/how-to/encrypt-communication.md b/content/nginx-one/agent/how-to/encrypt-communication.md deleted file mode 100644 index 00876ffc4..000000000 --- a/content/nginx-one/agent/how-to/encrypt-communication.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -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 -``` From 7f054068ed25157be1590afeea446cb1090fcd60 Mon Sep 17 00:00:00 2001 From: John David White <127981157+john-david3@users.noreply.github.com> Date: Wed, 21 May 2025 15:07:25 +0100 Subject: [PATCH 28/63] Update Agent v3 docs spelling errors (#577) --- content/includes/agent/installation/update-container.md | 2 +- content/includes/nginx-one/add-file/new-ssl-bundle.md | 2 +- go.mod | 2 +- go.sum | 2 ++ 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index 9c6e87c40..09c8090e7 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -21,4 +21,4 @@ See [Add Config Sync Group]({{< ref "/nginx-one/how-to/config-sync-groups/manage 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 +Replace the contents 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/includes/nginx-one/add-file/new-ssl-bundle.md b/content/includes/nginx-one/add-file/new-ssl-bundle.md index 4ba76c690..c078213e5 100644 --- a/content/includes/nginx-one/add-file/new-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/new-ssl-bundle.md @@ -2,7 +2,7 @@ docs: --- -First you can select the toggle to allow NGINX One Console to manaage the new certificate or bundle. +First you can select the toggle to allow NGINX One Console to manage the new certificate or bundle. In the screen that appears, you can add a certificate name. If you don't add a name, NGINX One will add a name for you, based on the expiration date for the certificate. diff --git a/go.mod b/go.mod index 24c110672..2a432e12a 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.34 // indirect +require github.com/nginxinc/nginx-hugo-theme v0.42.35 // indirect diff --git a/go.sum b/go.sum index 635374884..9253a8c04 100644 --- a/go.sum +++ b/go.sum @@ -8,3 +8,5 @@ github.com/nginxinc/nginx-hugo-theme v0.42.30 h1:qcHvB8tElbFN5ZWgs/TGn5IEmvnT5PG github.com/nginxinc/nginx-hugo-theme v0.42.30/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= github.com/nginxinc/nginx-hugo-theme v0.42.34 h1:9wNBHsyjY89YDI8vTYHav3YHPR2ngqKKtX5S8y9gFHg= github.com/nginxinc/nginx-hugo-theme v0.42.34/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v0.42.35 h1:e+pSTeYy8TJ5rVAJiVyL4F/tlqGYRGlHSFxj4FtmVpM= +github.com/nginxinc/nginx-hugo-theme v0.42.35/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From 01fbd5757e806567bfa35c0c73bbfdca7dc4103c Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:28:57 -0700 Subject: [PATCH 29/63] Draft: new N1C doc homepage --- .../agent/installation/install-agent-api.md | 83 +- .../includes/nap-waf/build-nginx-image-cmd.md | 2 +- .../nginx-one/add-file/existing-ssl-bundle.md | 2 +- .../learn-about-deployment.md | 6 +- content/nap-waf/v4/admin-guide/install.md | 4 +- content/nap-waf/v5/admin-guide/compiler.md | 2 +- content/ngf/overview/custom-policies.md | 9 +- content/ngf/overview/product-telemetry.md | 3 +- content/nginx-one/about.md | 2 +- content/nginx-one/api/_index.md | 4 +- content/nginx-one/certificates/_index.md | 6 + .../certificates/manage-certificates.md | 197 +++++ content/nginx-one/changelog.md | 10 +- .../nginx-one/config-sync-groups/_index.md | 6 + .../config-sync-groups/add-file-csg.md | 67 ++ .../manage-config-sync-groups.md | 261 ++++++ content/nginx-one/glossary.md | 4 +- content/nginx-one/how-to/_index.md | 2 +- content/nginx-one/nginx-configs/_index.md | 6 + content/nginx-one/nginx-configs/add-file.md | 67 ++ .../nginx-one/nginx-configs/add-instance.md | 75 ++ .../clean-up-unavailable-instances.md | 40 + .../manage-config-sync-groups.md | 239 ++++++ .../view-edit-nginx-configurations.md | 41 + content/nginx-one/rbac/_index.md | 4 +- content/nginx-one/staged-configs/_index.md | 6 + .../staged-configs/add-staged-config.md | 88 ++ .../staged-configs/api-staged-config.md | 20 + .../staged-configs/edit-staged-config.md | 38 + .../load-balancer/tcp-udp-load-balancer.md | 40 +- .../load-balancer/udp-health-check.md | 160 +--- .../manage-waf-security-policies.md | 763 ++++++++++++------ .../overview-nap-waf-config-management.md | 72 +- .../waf-config-management.md | 30 + layouts/partials/list-main.html | 30 +- 35 files changed, 1855 insertions(+), 534 deletions(-) create mode 100644 content/nginx-one/certificates/_index.md create mode 100644 content/nginx-one/certificates/manage-certificates.md create mode 100644 content/nginx-one/config-sync-groups/_index.md create mode 100644 content/nginx-one/config-sync-groups/add-file-csg.md create mode 100644 content/nginx-one/config-sync-groups/manage-config-sync-groups.md create mode 100644 content/nginx-one/nginx-configs/_index.md create mode 100644 content/nginx-one/nginx-configs/add-file.md create mode 100644 content/nginx-one/nginx-configs/add-instance.md create mode 100644 content/nginx-one/nginx-configs/clean-up-unavailable-instances.md create mode 100644 content/nginx-one/nginx-configs/manage-config-sync-groups.md create mode 100644 content/nginx-one/nginx-configs/view-edit-nginx-configurations.md create mode 100644 content/nginx-one/staged-configs/_index.md create mode 100644 content/nginx-one/staged-configs/add-staged-config.md create mode 100644 content/nginx-one/staged-configs/api-staged-config.md create mode 100644 content/nginx-one/staged-configs/edit-staged-config.md create mode 100644 content/nim/nginx-app-protect/waf-config-management.md diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 15009d21f..95a9650aa 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,75 +1,74 @@ ---- -docs: DOCS-1031 -files: - - content/nim/nginx-app-protect/setup-waf-config-management.md ---- - -{{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}} - -If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: +**Note**: To complete this step, make sure that `gpg` is installed on your system. You can install NGINX Agent using various command-line tools like `curl` or `wget`. If your NGINX Instance Manager host is not set up with valid TLS certificates, you can use the insecure flags provided by those tools. See the following examples: {{}} {{%tab name="curl"%}} -- **Secure:** +- Secure: ```bash - curl https:///install/nginx-agent | sudo sh + curl https:///install/nginx-agent | sudo sh ``` -- **Insecure:** +- Insecure: ```bash - curl --insecure https:///install/nginx-agent | sudo sh + curl --insecure https:///install/nginx-agent | sudo sh ``` -To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: + You can add your NGINX instance to an existing instance group or create one using `--instance-group` or `-g` flag when installing NGINX Agent. + + The following example shows how to download and run the script with the optional `--instance-group` flag adding the NGINX instance to the instance group **my-instance-group**: + + ```bash + curl https:///install/nginx-agent > install.sh; chmod u+x install.sh + sudo ./install.sh --instance-group my-instance-group + ``` -```shell -curl https:///install/nginx-agent -o install.sh -chmod u+x install.sh -sudo ./install.sh --instance-group -``` + By default, the install script attempts to use a secure connection when downloading packages. If, however, the script cannot create a secure connection, it uses an insecure connection instead and logs the following warning message: -By default, the install script uses a secure connection to download packages. If it can’t establish one, it falls back to an insecure connection and logs this message: + ``` text + Warning: An insecure connection will be used during this nginx-agent installation + ``` -```text -Warning: An insecure connection will be used during this nginx-agent installation -``` + To require a secure connection, you can set the optional flag `skip-verify` to `false`. -To enforce a secure connection, set the `--skip-verify` flag to false: + The following example shows how to download and run the script with an enforced secure connection: -```shell -curl https:///install/nginx-agent -o install.sh -chmod u+x install.sh -sudo ./install.sh --skip-verify false -``` + ```bash + curl https:///install/nginx-agent > install.sh chmod u+x install.sh; chmod u+x install.sh + sudo sh ./install.sh --skip-verify false + ``` {{%/tab%}} {{%tab name="wget"%}} -- **Secure:** - ```shell - wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false +- Secure: + + ```bash + wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false ``` -- **Insecure:** +- Insecure: - ```shell - wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh + ```bash + wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` -To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: + When you install the NGINX Agent, you can use the `--instance-group` or `-g` flag to add your NGINX instance to an existing instance group or to a new group that you specify. -```shell -wget https:///install/nginx-agent -O install.sh -chmod u+x install.sh -sudo ./install.sh --instance-group -``` + The following example downloads and runs the NGINX Agent install script with the optional `--instance-group` flag, adding the NGINX instance to the instance group **my-instance-group**: + + ```bash + wget https://gnms1.npi.f5net.com/install/nginx-agent -O install.sh ; chmod u+x install.sh + sudo ./install.sh --instance-group my-instance-group + ``` -{{%/tab%}} +{{%/tab%}} {{}} + + + diff --git a/content/includes/nap-waf/build-nginx-image-cmd.md b/content/includes/nap-waf/build-nginx-image-cmd.md index fcb89d363..41bf90d03 100644 --- a/content/includes/nap-waf/build-nginx-image-cmd.md +++ b/content/includes/nap-waf/build-nginx-image-cmd.md @@ -10,7 +10,7 @@ To build the image, execute the following command in the directory containing th ```shell -sudo docker build --no-cache --platform linux/amd64 \ +sudo docker build --no-cache \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t nginx-app-protect-5 . diff --git a/content/includes/nginx-one/add-file/existing-ssl-bundle.md b/content/includes/nginx-one/add-file/existing-ssl-bundle.md index e6a8c59a4..250669d3e 100644 --- a/content/includes/nginx-one/add-file/existing-ssl-bundle.md +++ b/content/includes/nginx-one/add-file/existing-ssl-bundle.md @@ -2,7 +2,7 @@ docs: --- -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). In the **Choose Certificate** drop-down, select the managed certificate of your choice, and select **Add**. You can then: 1. Review details of the certificate. The next steps depend on whether the certificate is a CA bundle or a certificate / key pair. diff --git a/content/nap-dos/deployment-guide/learn-about-deployment.md b/content/nap-dos/deployment-guide/learn-about-deployment.md index 430fd9e2e..df137bd2e 100644 --- a/content/nap-dos/deployment-guide/learn-about-deployment.md +++ b/content/nap-dos/deployment-guide/learn-about-deployment.md @@ -1405,7 +1405,7 @@ You need root permissions to execute the following steps. 6. Create a Docker image: ```shell - docker build --no-cache --platform linux/amd64 -t app-protect-dos . + docker build --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. @@ -1966,13 +1966,13 @@ Make sure to replace upstream and proxy pass directives in this example with rel For CentOS: ```shell - docker build --no-cache --platform linux/amd64 -t app-protect-dos . + docker build --no-cache -t app-protect-dos . ``` For RHEL: ```shell - docker build --platform linux/amd64 --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . + docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. diff --git a/content/nap-waf/v4/admin-guide/install.md b/content/nap-waf/v4/admin-guide/install.md index c3e0575dc..3158ac9d3 100644 --- a/content/nap-waf/v4/admin-guide/install.md +++ b/content/nap-waf/v4/admin-guide/install.md @@ -939,7 +939,7 @@ If a user other than **nginx** is to be used, note the following: - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . + DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). @@ -1289,7 +1289,7 @@ You need root permissions to execute the following steps. - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . + DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). diff --git a/content/nap-waf/v5/admin-guide/compiler.md b/content/nap-waf/v5/admin-guide/compiler.md index ea0f28500..dd0e828e4 100644 --- a/content/nap-waf/v5/admin-guide/compiler.md +++ b/content/nap-waf/v5/admin-guide/compiler.md @@ -98,7 +98,7 @@ curl -s https://private-registry.nginx.com/v2/nap/waf-compiler/tags/list --key < Run the command below to build your image, where `waf-compiler-:custom` is an example of the image tag: ```shell - sudo docker build --no-cache --platform linux/amd64 \ + sudo docker build --no-cache \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t waf-compiler-:custom . diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index 5aeb99fce..c7e5a785d 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -17,11 +17,10 @@ The following table summarizes NGINX Gateway Fabric custom policies: {{< bootstrap-table "table table-striped table-bordered" >}} -| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | -|---------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | -| [UpstreamSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | +| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | +|---------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| +| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | +| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha1 | {{< /bootstrap-table >}} diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index 3c73a4cb5..cd9f7a20f 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -32,8 +32,7 @@ Telemetry data is collected once every 24 hours and sent to a service managed by - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected. - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest. - **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. -- **SnippetsFilters Info:** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. - +- **SnippetsFilters Info**a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. This data is used to identify the following information: - The flavors of Kubernetes environments that are most popular among our users. diff --git a/content/nginx-one/about.md b/content/nginx-one/about.md index f20c40bea..6d0dd4594 100644 --- a/content/nginx-one/about.md +++ b/content/nginx-one/about.md @@ -1,7 +1,7 @@ --- description: '' docs: DOCS-1392 -title: About +title: Manage your NGINX fleet toc: true weight: 10 type: diff --git a/content/nginx-one/api/_index.md b/content/nginx-one/api/_index.md index e1f50db88..1fe244a36 100644 --- a/content/nginx-one/api/_index.md +++ b/content/nginx-one/api/_index.md @@ -1,6 +1,6 @@ --- -title: API +title: NGINX One API description: weight: 1000 url: /nginx-one/api ---- \ No newline at end of file +--- diff --git a/content/nginx-one/certificates/_index.md b/content/nginx-one/certificates/_index.md new file mode 100644 index 000000000..0ea28d683 --- /dev/null +++ b/content/nginx-one/certificates/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Monitor your certificates +weight: 400 +url: /nginx-one/certificates +--- diff --git a/content/nginx-one/certificates/manage-certificates.md b/content/nginx-one/certificates/manage-certificates.md new file mode 100644 index 000000000..13c532e38 --- /dev/null +++ b/content/nginx-one/certificates/manage-certificates.md @@ -0,0 +1,197 @@ +--- +docs: null +title: Manage certificates +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how you can manage SSL/TLS certificates with the F5 NGINX One Console. Valid certificates support encrypted connections between NGINX and your users. + +You may have separate sets of SSL/TLS certificates, as described in the following table: + +{{}} +| Functionality | Typical file names | Notes | +|-------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| +| Website traffic | /etc/nginx/ssl/example.com.crt
    /etc/nginx/ssl/example.com.key | Typically purchased from a Certificate Authority (CA) | +| Repository access | /etc/ssl/nginx/nginx-repo.crt
    /etc/ssl/nginx/nginx-repo.key | Supports access to repositories to download and install NGINX packages | +| NGINX Licensing | /etc/ssl/nginx/server.crt
    /etc/ssl/nginx/server.key | Supports access to repositories. Based on licenses downloaded from https://my.f5.com/ | +{{    }} + +Allowed directories depend on the [NGINX Agent]({{< ref "/nginx-one/getting-started/#install-nginx-agent" >}}). Look for the `/etc/nginx-agent/nginx-agent.conf` file. +Find the `config_dirs` parameter in that file, as described in the NGINX Agent [Basic configuration](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#cli-flags--environment-variables). +You may need to add a directory like `/etc/ssl` to that parameter. + +From the NGINX One Console you can: + +- Monitor all certificates configured for use by your connected NGINX Instances. +- Ensure that your certificates are current and correct. +- Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. + +You can manage the certificates for: + +- [Unique instances]({{< ref "/nginx-one/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) +- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) + + +{{< tip >}} + +If you are managing the certificate from NGINX One Console, we recommend that you avoid directly manipulating the files on the data plane. + +{{< /tip >}} + +## Before you start + +Before you add and manage certificates with the NGINX One Console make sure: + +- You have access to the NGINX One Console +- You have access through the F5 Distributed Cloud role, as described in the [Authentication]({{< ref "/nginx-one/api/authentication.md" >}}) guide, to manage SSL/TLS certificates + - You have the `f5xc-nginx-one-user` role for your account +- Your SSL/TLS certificates and keys match + +### SSL/TLS certificates and more + +NGINX One Console supports certificates for access to repositories. You may need a copy of these files from your Certificate Authority (CA) to upload them to NGINX One Console: + +- SSL Certificate + - Example file extensions: .crt, .pem +- Privacy certificate + - Example file extensions: .key, .pem + +The NGINX One Console allows you to upload these certificates as text and as files. You can also upload your own certificate files (with file extensions such as .crt and .key). + +Make sure your certificates, keys, and pem files are encrypted to one of the following standards: + +- RSA +- ECC/ECDSA + +In other words, any private key of this type should be supported, regardless of the curve types or hashing algorithm. + +For exmaple, if you use ECDSA private keys in PEM format, the PEM headers should contain: + +``` +-----BEGIN EC PRIVATE KEY----- + +-----END EC PRIVATE KEY----- + +``` + +If you use one of these keys, the US National Institute of Standards and Technology, in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf), recommends a key size of at least +2048 bits. It also has recommnedations for ECDSA. + +### Include certificates in NGINX configuration + +For NGINX configuration, these files are typically associated with the following NGINX directives: + +- [`ssl_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate) +- [`ssl_certificate_key`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate_key) +- [`ssl_trusted_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_trusted_certificate) +- [`ssl_client_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) +- [`proxy_ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate) +- [`proxy_ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate_key) + +## Important considerations + +Most websites include valid information from public keys and certificates or CA bundles. However, the NGINX One Console accepts, but provides warnings for these use cases: + +- When the public certificate is expired +- When the leaf certificate part of a certificate chain is expired +- When any of the components of a CA bundle are expired +- When the public key does not match the private certificate + +In such cases, you may get websites that present "Your connection is not private" warning messages in client web browsers. + +## Review existing certificates + +Follow these steps to review existing certificates for your instances. + +On the left-hand pane, select **Certificates**. In the window that appears, you see: + +{{}} +| Term | Definition | +|-------------|-------------| +| **Total** | Total number of certificates available to NGINX One Console | +| **Valid (31+ days)** | Number of certificates that expire in 31 or more days | +| **Expires Soon (<31 days)** | Number of certificates that expire in less than 31 days | +| **Expired** | Number of exprired certificates | +| **Not Ready** | Certificates with a start date in the future | +| **Managed** | Managed by and stored in the NGINX One Console | +| **Unmanaged** | Detected by, and not managed by NGINX One Console. To convert to managed, you may need to upload the certificate and key during the process. | +{{}} + +You can **Add Filter** to filter certificates by: + +- Name +- Status +- Subject Name +- Type + +The Export option supports exports of basic certification file information to a CSV file. It does _not_ include the content of the public certificate or the private key. + +## Add a new certificate or bundle + +To add a new certificate, select **Add Certificate**. + + +In the screen that appears, you can add a certificate name. If you don't add a name, NGINX One will add a name for you, based on the expiration date for the certificate. + +You can add certificates in the following formats: + +- **SSL Certificate and Key** +- **CA Certificate Bundle** + +In each case, you can upload files directly, or enter the content of the certificates in a text box. Once you upload these certificates, you'll see: + +- **Certificate Details**, with the Subject Name, start and end dates. +- **Key Details**, with the encryption key size and algorithm, such as RSA + + +## Edit an existing certificate or bundle + +You can modify existing certificates from the **Certificates** screen. Select the certificate of your choice. Depending on the type of certificate, you'll then see either a **Edit Certificate** or **Edit CA Bundle** option. The NGINX One Console then presents a window with the same options as shown when you [Add a new certificate](#add-a-new-certificate-or-bundle). + +If that certificate is already managed as part of a Config Sync Group, the changes you make affect all instances in that group. + +## Remove a deployed certificate + +You can remove a deployed certificate from an independent instance or from a Config Sync Group. This will remove the certificate's association with the instance or group, but it does not delete the certificate files from the instance(s). + +Every instance with a deployed certificate includes paths to certificates in their configuration files. If you remove the deployed file path to one certificate, that change is limited to that one instance. + +Every Config Sync Group also includes paths to certificates in its configuration files. If you remove the deployed path to one certificate, that change affects all instances which belong to that Config Sync Group. + +## Delete a deployed certificate + +To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis (`...`) and then select **Delete**. Before deleting that certificate, you should see a warning. + +If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group. + +{{< warning >}} Be cautious if you want to delete certificates that are being used by an instance or a Config Sync Group. Deleting such certificates leads to failure in affected NGINX deployments. {{< /warning >}} + +## Managed and unmanaged certificates + +If you register an instance to NGINX One Console, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), and the associated SSL/TLS certificates: + +- Are used in their NGINX configuration +- Do _not_ match an existing managed SSL certificate/CA bundle + +These certificates appear in the list of unmanaged certificates. + +We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your data plane from the NGINX One Console. + +To convert these cerificates to managed, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + + + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/changelog.md b/content/nginx-one/changelog.md index db867eba0..a0d6b88d5 100644 --- a/content/nginx-one/changelog.md +++ b/content/nginx-one/changelog.md @@ -83,8 +83,8 @@ You can: - Remove a deployed certificate from a Config Sync Group For more information, including warnings about risks, see our documentation on how you can: -- [Add a file]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) +- [Add a file]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) ### Revert a configuration @@ -108,7 +108,7 @@ From the NGINX One Console you can now: - Ensure that your certificates are current and correct. - Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. -For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}). +For more information, see the full documentation on how you can [Manage Certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). ## August 22, 2024 @@ -116,7 +116,7 @@ For more information, see the full documentation on how you can [Manage Certific Config Sync Groups are now available in the F5 NGINX One Console. This feature allows you to manage and synchronize NGINX configurations across multiple instances as a single entity, ensuring consistency and simplifying the management of your NGINX environment. -For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). +For more information, see the full documentation on [Managing Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). ## August 8, 2024 @@ -136,7 +136,7 @@ Select the link for each CVE to see the details, including the CVE's publish dat ### Edit NGINX configurations -You can now make configuration changes to your NGINX instances. For more details, see [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}). +You can now make configuration changes to your NGINX instances. For more details, see [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}). ## May 28, 2024 diff --git a/content/nginx-one/config-sync-groups/_index.md b/content/nginx-one/config-sync-groups/_index.md new file mode 100644 index 000000000..db1ee5560 --- /dev/null +++ b/content/nginx-one/config-sync-groups/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Organize in groups +weight: 400 +url: /nginx-one/config-sync-groups +--- diff --git a/content/nginx-one/config-sync-groups/add-file-csg.md b/content/nginx-one/config-sync-groups/add-file-csg.md new file mode 100644 index 000000000..9b6905aea --- /dev/null +++ b/content/nginx-one/config-sync-groups/add-file-csg.md @@ -0,0 +1,67 @@ +--- +docs: null +title: Add a file to a Config Sync Group +toc: true +weight: 400 +type: +- how-to +--- + +## Overview + +{{< include "nginx-one/add-file/overview.md" >}} + +## Before you start + +Before you add files in your configuration, ensure: + +- You have access to the NGINX One Console. +- Config Sync Groups are properly registered with NGINX One Console + +## Important considerations + +This page applies when you want to add a file to a Config Sync Group. Any changes you make here apply to all [Instances]({{< ref "/nginx-one/glossary.md" >}}) of that Config Sync Group. + +## Add a file + +You can use the NGINX One Console to add a file to a specific Config Sync Group. To do so: + +1. Select the Config Sync Group to manage. +1. Select the **Configuration** tab. + + {{< tip >}} + + {{< include "nginx-one/add-file/edit-config-tip.md" >}} + + {{< /tip >}} + +1. Select **Edit Configuration**. +1. In the **Edit Configuration** window that appears, select **Add File**. + +You now have multiple options, described in the sections which follow. + +### New Configuration File + +Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. + +### New SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} + + {{< tip >}} + + Make sure to specify the path to your certificate in your NGINX configuration, + with the `ssl_certificate` and `ssl_certificate_key` directives. + + {{< /tip >}} + +### Existing SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} +With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md new file mode 100644 index 000000000..8b24001cd --- /dev/null +++ b/content/nginx-one/config-sync-groups/manage-config-sync-groups.md @@ -0,0 +1,261 @@ +--- +docs: null +title: Manage Config Sync Groups +toc: true +weight: 300 +type: +- how-to +--- + +## Overview + +If you work with several instances of NGINX, it can help to organize these instances in Config Sync Groups. Each instance in a Config Sync Group has the same configuration. + +This guide explains how to create and manage Config Sync Groups in the F5 NGINX One Console. Config Sync Groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. + +If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find Config Sync Groups in NGINX One similar, though the steps and terminology differ slightly. + +Config Sync Groups are functionally different from syncing instances in a cluster. They let you to manage and synchronize configurations across multiple NGINX instances, all at once. + +This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While Config Sync Groups focus on configuration management, cluster syncing supports failover and data consistency. + +## Before you start + +Before you create and manage Config Sync Groups, ensure: + +- You have access to the NGINX One Console. +- You have the necessary permissions to create and manage Config Sync Groups. +- If you plan to add existing instances to a Config Sync Group, make sure those NGINX instances are properly registered with NGINX One. + +## Configuration management + +Config Sync Groups support configuration inheritance and persistance. If you've just created a Config Sync Group, you can define the configuration for that group in the following ways: + +- Before adding an instance to a group, you can [Define the Config Sync Group configuration manually](#define-the-config-sync-group-configuration-manually). +- When you add the first instance to a group, that instance defines the configuration for that Config Sync Group. +- Afterwards, you can modify the configuration of the Config Sync Group. That modifies the configuration of all member instances. Future members of that group inherit that modified configuration. + +On the other hand, if you remove all instances from a Config Sync Group, the original configuration persists. In other words, the group retains the configuration from that first instance (or the original configuration). Any new instance that you add later still inherits that configuration. + +{{< tip >}}You can use _unmanaged_ certificates. Your actions can affect the [Config Sync Group status](#config-sync-group-status). For future instances on the data plane, if it: + +- Has unmanaged certificates in the same file paths as defined by the NGINX configuration as the Config Sync Group, that instance will be [**In Sync**](#config-sync-group-status). +- Will be [**Out of Sync**](#config-sync-group-status) if the instance: + - Does not have unmanaged certificates in the same file paths + - Has unmanaged certificates in a different directory from the Config Sync Group +{{< /tip >}} + +### Risk when adding multiple instances to a Config Sync Group + +If you add multiple instances to a single Config Sync Group, simultaneously (with automation), there's a risk that the instance selects a random configuration. To prevent this problem, you should: + +1. Create a Config Sync Group. +1. Add a configuration to the Config Sync Group, so all instances inherit it. +1. Add the instances in a separate operation. + +Your instances should synchronize with your desired configuration within 30 seconds. + +### Use an instance to define the Config Sync Group configuration + +1. Follow the steps in the [**Add an existing instance to a Config Sync Group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a Config Sync Group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. +2. The NGINX configuration from this instance will automatically become the group's configuration. +3. You can further edit and publish this configuration by following the steps in the [**Publish the Config Sync Group configuration**](#publish-the-config-sync-group-configuration) section. + +### Define the Config Sync Group configuration manually + +You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. + +To manually set the group configuration: + +1. Follow steps 1–4 in the [**Create a Config Sync Group**](#create-a-config-sync-group) section to create your Config Sync Group. +2. After creating the group, select the **Configuration** tab. +3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. +4. To add a configuration, select **Edit Configuration**. +5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. +6. After making your changes, select **Next** to view a split screen showing your changes. +7. If you're satisfied with the configuration, select **Save and Publish**. + +## Important considerations + +When you plan Config Sync Groups, consider the following factors: + +- **Single Config Sync Group membership**: You can add an instance to only one Config Sync Group. + +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. + +- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same Config Sync Group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. + +## Create a Config Sync Group + +When you create a Config Sync Group, you can manage the configurations of multiple NGINX instances as a single entity. + +1. On the left menu, select **Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, type a name for your Config Sync Group. +4. Select **Create** to add the Config Sync Group. + +## Manage Config Sync Group membership + +Now that you created a Config Sync Group, you can add instances to that group. As described in [Configuration management](#configuration-management), the first instance you add to a group, when you add it, defines the initial configuration for the group. You can update the configuration for the entire Config Sync Group. + +Any instance that joins the group afterwards inherits that configuration. + +### Add an existing instance to a Config Sync Group {#add-an-existing-instance-to-a-config-sync-group} + +You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. At the end of the file, add a new line beginning with `instance_group:`, followed by the Config Sync Group name. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +### Add a new instance to a Config Sync Group {#add-a-new-instance-to-a-config-sync-group} + +When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. In the **Instances** pane, select **Add Instance to Config Sync Group**. +4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to Config Sync Group**. +5. Select **Next**. +6. **Generate a new data plane key** (choose this option if you don't have an existing key): + + - Select **Generate new key** to create a new data plane key for the instance. + - Select **Generate Data Plane Key**. + - Copy and securely store the generated key, as it is displayed only once. + +7. **Use an existing data plane key** (choose this option if you already have a key): + + - Select **Use existing key**. + - In the **Data Plane Key** field, enter the existing data plane key. + +{{}} + +{{%tab name="Virtual Machine or Bare Metal"%}} + +8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. +9. Select **Done** to complete the process. + +{{%/tab%}} + +{{%tab name="Docker Container"%}} + +8. **Log in to the NGINX private registry**: + + - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) license from [MyF5](https://my.f5.com/manage/s/). + + ```shell + sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none + ``` + +9. **Pull the Docker image**: + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + +10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. + +11. Select **Done** to complete the process. + +{{%/tab%}} + +{{}} + +{{}} + +Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. + +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). + +{{}} + +### Move an instance to a different Config Sync Group + +If you need to move an NGINX instance to a different Config Sync Group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and change it to the name of the new Config Sync Group. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +If you move an instance with certificates from one Config Sync Group to another, NGINX One adds or removes those certificates from the data plane, to synchronize with the deployed certificates of the group. + +### Remove an instance from a Config Sync Group + +If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. + + ```text + # instance_group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +By removing or commenting out this line, the instance will no longer be associated with any Config Sync Group. + +## Publish the Config Sync Group configuration {#publish-the-config-sync-group-configuration} + +After the Config Sync Group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. + +1. On the left menu, select **Config Sync Groups**. +2. Select the Config Sync Group in the list. +3. Select the **Configuration** tab to view the group's NGINX configuration. +4. To modify the group's configuration, select **Edit Configuration**. +5. Make the necessary changes to the configuration. +6. When you're finished, select **Next**. A split view displays the changes. +7. If you're satisfied with the changes, select **Save and Publish**. + +Publishing the group configuration ensures that all instances within the Config Sync Group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. + +## Config Sync Group status + +The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. + +{{}} +| **Status** | **Description** | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **In Sync** | All instances within the Config Sync Group have configurations that match the group configuration. No action is required. | +| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | +| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | +| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | +{{}} + +Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index c315d35ef..187c8585d 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -3,7 +3,7 @@ description: '' docs: DOCS-1396 title: Glossary toc: true -weight: 1000 +weight: 2000 type: - reference --- @@ -14,7 +14,7 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed {{}} | Term | Definition | |-------------|-------------| -| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | +| **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. | | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. You'll see the namespace in the NGINX One Console URL as `/namespaces//` | diff --git a/content/nginx-one/how-to/_index.md b/content/nginx-one/how-to/_index.md index 3e88ec7ae..e7b505736 100644 --- a/content/nginx-one/how-to/_index.md +++ b/content/nginx-one/how-to/_index.md @@ -1,6 +1,6 @@ --- description: title: How-to guides -weight: 200 +weight: 700 url: /nginx-one/how-to/ --- diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md new file mode 100644 index 000000000..d36819e7b --- /dev/null +++ b/content/nginx-one/nginx-configs/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Organize your NGINX instances +weight: 300 +url: /nginx-one/nginx-configs +--- diff --git a/content/nginx-one/nginx-configs/add-file.md b/content/nginx-one/nginx-configs/add-file.md new file mode 100644 index 000000000..4549647f5 --- /dev/null +++ b/content/nginx-one/nginx-configs/add-file.md @@ -0,0 +1,67 @@ +--- +docs: null +title: Add a file to an instance +toc: true +weight: 400 +type: +- how-to +--- + +## Overview + +{{< include "nginx-one/add-file/overview.md" >}} + +## Before you start + +Before you add files in your configuration, ensure: + +- You have access to the NGINX One Console. +- NGINX instances are properly registered with NGINX One Console + +## Important considerations + +If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. +For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}). + +## Add a file + +You can use the NGINX One Console to add a file to a specific instance. To do so: + +1. Select the instance to manage. +1. Select the **Configuration** tab. + + {{< tip >}} + + {{< include "nginx-one/add-file/edit-config-tip.md" >}} + + {{< /tip >}} + +1. Select **Edit Configuration**. +1. In the **Edit Configuration** window that appears, select **Add File**. + +You now have multiple options, described in the sections which follow. + +### New Configuration File + +Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. + +### New SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} + + {{< tip >}} + + Make sure to specify the path to your certificate in your NGINX configuration, + with the `ssl_certificate` and `ssl_certificate_key` directives. + + {{< /tip >}} + +### Existing SSL Certificate or CA Bundle + +{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) +- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md new file mode 100644 index 000000000..ddf5eb095 --- /dev/null +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -0,0 +1,75 @@ +--- +description: '' +title: Add an NGINX instance +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need +to set up a data plane key to connect your instances to NGINX One. + +## Before you start + +Before you add an instance to NGINX One Console, ensure: + +- You have administrator access to NGINX One Console. +- You have configured instances of NGINX that you want to manage through NGINX One Console. +- You have or are ready to configure a data plane key. +- You have or are ready to set up managed certificates. + +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} + +## Add an instance + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. + +## Managed and Unmanaged Certificates + +If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. + +### If the certificate is already managed + +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. + +NGINX One Console can manage your instances along with those certificates. + +### If the certificate is not managed + +These certificates appear in the list of **Unmanaged Certificates**. + +To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. + +To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + +Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. + +## Add an instance to a Config Sync Group + +When you [Manage Config Sync Group membership]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md new file mode 100644 index 000000000..6a119617d --- /dev/null +++ b/content/nginx-one/nginx-configs/clean-up-unavailable-instances.md @@ -0,0 +1,40 @@ +--- +description: '' +docs: null +title: Clean up unavailable NGINX instances +toc: true +weight: 200 +type: +- how-to +--- + +## Overview + +This guide explains how to set up automatic cleanup for NGINX instances in NGINX One. The cleanup process removes instances that have been unavailable for a specified duration. By default, this period is 24 hours from the time the NGINX instance was last updated. Administrators can change or disable the cleanup duration in **Settings > Instance Settings**. Events will be generated for NGINX instances that have been automatically cleaned up; you can see these events on the **Overview > Events** page. + +## Before you start + +Before you set up automatic cleanup for NGINX instances, ensure: + +- You have administrator access to NGINX One. +- You understand that this action will delete instances permanently after they are unavailable for the specified duration. + +## Configure instance cleanup + +Follow these steps to set up automatic cleanup for NGINX instances in NGINX One: + +1. On the left menu, select **Instance Settings**. +1. On the **Instance Settings** page, in the **Unavailable Instance Cleanup** section, select **Edit Duration**. +1. Choose the cleanup duration. + - Select one of the predefined durations (None, 1 day, 7 days, 30 days) or set a custom duration. Selecting **None** disables automatic cleanup. + - If you choose **Custom**, enter the duration in hours or days. +1. Select **Save** to apply the changes. + +## Event log details + +When instances are cleaned up automatically, an event log entry is created. You can find these events on the **Overview > Events** page. The event log includes the following details: + +- **Impacted Object ID**: The unique identifier of the NGINX instance that was cleaned up. +- **Type**: The type of event, which will be "Automated Object Cleanup". +- **Timestamp**: The date and time when the instance was cleaned up. +- **Message**: A description indicating that the instance was unavailable for the configured duration before being cleaned up. diff --git a/content/nginx-one/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/manage-config-sync-groups.md new file mode 100644 index 000000000..41589dadd --- /dev/null +++ b/content/nginx-one/nginx-configs/manage-config-sync-groups.md @@ -0,0 +1,239 @@ +--- +docs: null +title: Manage config sync groups +toc: true +weight: 300 +type: +- how-to +--- + +## Overview + +This guide explains how to create and manage config sync groups in the F5 NGINX One Console. Config sync groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. + +If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find config sync groups in NGINX One similar, though the steps and terminology differ slightly. + +## Before you start + +Before you create and manage config sync groups, ensure: + +- You have access to the NGINX One Console. +- You have the necessary permissions to create and manage config sync groups. +- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. + +## Important considerations + +- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified config sync group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. + +- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same config sync group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. + +- **Single config sync group membership**: An instance can join only one config sync group at a time. + +- **Configuration inheritance**: If the config sync group already has a configuration defined, that configuration will be pushed to instances when they join. + +- **Using an instance's configuration for the group configuration**: If an instance is the first to join a config sync group and the group's configuration hasn't been defined, the instance’s configuration will become the group’s configuration. Any instances added later will automatically inherit this configuration. + + {{< note >}} If you add multiple instances to a single config sync group, simultaneously (with automation), follow these steps. Your instances will inherit your desired configuration: + + 1. Create a config sync group. + 1. Add a configuration to the config sync group, so all instances inherit it. + 1. Add the instances in a separate operation. + + Your instances should synchronize with your desired configuration within 30 seconds. {{< /note >}} + +- **Persistence of a config sync group's configuration**: The configuration for a config sync group persists until you delete the group. Even if you remove all instances, the group's configuration stays intact. Any new instances that join later will automatically inherit this configuration. + +- **Config sync groups vs. cluster syncing**: Config sync groups are not the same as cluster syncing. Config sync groups let you to manage and synchronize configurations across multiple NGINX instances as a single entity. This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While config sync groups focus on configuration management, cluster syncing supports failover and data consistency. + +## Create a config sync group + +Creating a config sync group allows you to manage the configurations of multiple NGINX instances as a single entity. + +1. On the left menu, select **Config Sync Groups**. +2. Select **Add Config Sync Group**. +3. In the **Name** field, type a name for your config sync group. +4. Select **Create** to add the config sync group. + +## Manage config sync group membership + +### Add an existing instance to a config sync group {#add-an-existing-instance-to-a-config-sync-group} + +You can add existing NGINX instances that are already registered with NGINX One to a config sync group. + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. At the end of the file, add a new line beginning with `instance_group:`, followed by the config sync group name. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent: + + ``` shell + sudo systemctl restart nginx-agent + ``` + +### Add a new instance to a config sync group {#add-a-new-instance-to-a-config-sync-group} + +When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. + +1. On the left menu, select **Config Sync Groups**. +2. Select the config sync group in the list. +3. In the **Instances** pane, select **Add Instance to Config Sync Group**. +4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to config sync group**. +5. Select **Next**. +6. **Generate a new data plane key** (choose this option if you don't have an existing key): + + - Select **Generate new key** to create a new data plane key for the instance. + - Select **Generate Data Plane Key**. + - Copy and securely store the generated key, as it is displayed only once. + +7. **Use an existing data plane key** (choose this option if you already have a key): + + - Select **Use existing key**. + - In the **Data Plane Key** field, enter the existing data plane key. + +{{}} + +{{%tab name="Virtual Machine or Bare Metal"%}} + +8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. +9. Select **Done** to complete the process. + +{{%/tab%}} + +{{%tab name="Docker Container"%}} + +8. **Log in to the NGINX private registry**: + + - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) from [MyF5](https://my.f5.com/manage/s/). + + ```shell + sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none + ``` + +9. **Pull the Docker image**: + + - From the **OS Type** list, choose the appropriate operating system for your Docker image. + - After selecting the OS, run the provided command to pull the Docker image. + + **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). + +10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. + +11. Select **Done** to complete the process. + +{{%/tab%}} + +{{}} + +{{}} + +Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. + +For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). + +{{}} + +### Change the config sync group for an instance + +If you need to move an NGINX instance to a different config sync group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and change it to the name of the new config sync group. + + ``` text + instance_group: + ``` + +4. Restart NGINX Agent by running the following command: + + ```shell + sudo systemctl restart nginx-agent + ``` + +**Important:** If the instance is the first to join the new config sync group and a group configuration hasn’t been added manually beforehand, the instance’s configuration will automatically become the group’s configuration. Any instances added to this group later will inherit this configuration. + +### Remove an instance from a config sync group + +If you need to remove an NGINX instance from a config sync group without adding it to another group, follow these steps: + +1. Open a command-line terminal on the NGINX instance. +2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. +3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. + + ```text + # instance_group: + ``` + +4. Restart NGINX Agent: + + ```shell + sudo systemctl restart nginx-agent + ``` + +By removing or commenting out this line, the instance will no longer be associated with any config sync group. + +## Add the config sync group configuration + +You can set the configuration for a config sync group in two ways: + +### Define the group configuration manually + +You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. + +To manually set the group configuration: + +1. Follow steps 1–4 in the [**Create a config sync group**](#create-a-config-sync-group) section to create your config sync group. +2. After creating the group, select the **Configuration** tab. +3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. +4. To add a configuration, select **Edit Configuration**. +5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. +6. After making your changes, select **Next** to view a split screen showing your changes. +7. If you're satisfied with the configuration, select **Save and Publish**. + +### Use an instance's configuration + +If you don't manually define a group config, the NGINX configuration of the first instance added to a config sync group becomes the group's configuration. Any additional instances added afterward inherit this group configuration. + +To set the group configuration by adding an instance: + +1. Follow the steps in the [**Add an existing instance to a config sync group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a config sync group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. +2. The NGINX configuration from this instance will automatically become the group's configuration. +3. You can further edit and publish this configuration by following the steps in the [**Publish the config sync group configuration**](#publish-the-config-sync-group-configuration) section. + +## Publish the config sync group configuration {#publish-the-config-sync-group-configuration} + +After the config sync group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. + +1. On the left menu, select **Config Sync Groups**. +2. Select the config sync group in the list. +3. Select the **Configuration** tab to view the group's NGINX configuration. +4. To modify the group's configuration, select **Edit Configuration**. +5. Make the necessary changes to the configuration. +6. When you're finished, select **Next**. A split view displays the changes. +7. If you're satisfied with the changes, select **Save and Publish**. + +Publishing the group configuration ensures that all instances within the config sync group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. + +## Understanding config sync statuses + +The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. + +{{}} +| **Status** | **Description** | +|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| **In Sync** | All instances within the config sync group have configurations that match the group configuration. No action is required. | +| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | +| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | +| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | +{{}} + +Monitoring the **Config Sync Status** helps ensure that your configurations are consistently applied across all instances in a group, reducing the risk of configuration drift. + +## See also + +- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) +- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md new file mode 100644 index 000000000..9b742104c --- /dev/null +++ b/content/nginx-one/nginx-configs/view-edit-nginx-configurations.md @@ -0,0 +1,41 @@ +--- +# We use sentence case and present imperative tone +title: View and edit NGINX configurations +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + + +## Overview + +This guide explains how to add a **Instances** to your NGINX One Console. + +## Before you start + +Before you add **Instances** to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. + +To view and edit an NGINX configuration, follow these steps: + +1. On the left menu, select **Instances**. +2. Select the instance you want to view the configuration for. +3. Select the **Configuration** tab to see the current configuration for the NGINX instance. +4. Select **Edit Configuration** to make changes to the current configuration. +5. Make your changes to the configuration files. The config analyzer will let you know if there are any errors. +6. When you are satisfied with the changes, select **Next**. +7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration. + +Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< ref "/nginx-one/staged-configs/_index.md" >}}). + +## See also + +- [Manage Config Sync Groups]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/rbac/_index.md b/content/nginx-one/rbac/_index.md index a1f7050ff..36c5b464d 100644 --- a/content/nginx-one/rbac/_index.md +++ b/content/nginx-one/rbac/_index.md @@ -1,6 +1,6 @@ --- -title: Role-based access control +title: Organize your administrators with RBAC description: -weight: 300 +weight: 500 url: /nginx-one/rbac --- diff --git a/content/nginx-one/staged-configs/_index.md b/content/nginx-one/staged-configs/_index.md new file mode 100644 index 000000000..4186aa21b --- /dev/null +++ b/content/nginx-one/staged-configs/_index.md @@ -0,0 +1,6 @@ +--- +description: +title: Set up new instances +weight: 200 +url: /nginx-one/how-to/staged-configs +--- diff --git a/content/nginx-one/staged-configs/add-staged-config.md b/content/nginx-one/staged-configs/add-staged-config.md new file mode 100644 index 000000000..94007c407 --- /dev/null +++ b/content/nginx-one/staged-configs/add-staged-config.md @@ -0,0 +1,88 @@ +--- +# We use sentence case and present imperative tone +title: Add a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 100 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +product: +--- + +## Overview + +This guide explains how to add a Staged Configuration to your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you add a Staged Configuration to NGINX One Console, ensure: + +- You have an NGINX One Console account with staged configuration permissions. + +## Add a Staged Configuration + +You can add a Staged Configuration from: + +- Empty files +- An existing Instance +- An existing Config Sync Group +- An existing Staged Configuration + +To start the process from NGINX One Console, select **Manage > Staged Configruations**. Select **Add Staged Configuration**. + +The following sections start from the **Add Staged Configuration** window that appears. + +### Start from an empty file + +To start a new Staged Configuration: + +1. Select **New Configuration**. +1. Enter a name. +1. Select **Next**. + + You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode. +1. Type or paste content for `/etc/nginx/nginx.conf`. +1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. +1. When you're done, select **Save**. + +### Start from an existing Instance + +To start from an existing Instance: + +1. Select **Existing Source**. +1. Enter a name for your new Staged Configuration. +1. Select **Instance**. +1. In the Choose Instance menu that appears, select an existing Instance. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Config Sync Group + +To start from an existing Config Sync Group: + +1. Select **Existing Source**. +1. Select **Config Sync Group**. +1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save. + +### Start from an existing Staged Config + +To start from an existing Staged Config: + +1. Select **Existing Source**. +1. Select **Staged Configuration**. +1. In the Choose Staged Configuration menu that appears, select an existing Staged Configuration. +1. Enter a name for your new Staged Configuration. +1. Select **Next**. + +NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save. + diff --git a/content/nginx-one/staged-configs/api-staged-config.md b/content/nginx-one/staged-configs/api-staged-config.md new file mode 100644 index 000000000..8eadfdb55 --- /dev/null +++ b/content/nginx-one/staged-configs/api-staged-config.md @@ -0,0 +1,20 @@ +--- +# We use sentence case and present imperative tone +title: Use the API to manage your Staged Configurations +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can: + +- [Create an NGINX Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}}) + - The details allow you to add existing configuration files. +- [Get a list of existing Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}}) + - Be sure to record the `object_id` of your target Staged Configuration for your analysis report. +- [Get an analysis report for an existing Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}}) diff --git a/content/nginx-one/staged-configs/edit-staged-config.md b/content/nginx-one/staged-configs/edit-staged-config.md new file mode 100644 index 000000000..8f101a0fd --- /dev/null +++ b/content/nginx-one/staged-configs/edit-staged-config.md @@ -0,0 +1,38 @@ +--- +# We use sentence case and present imperative tone +title: View and edit a Staged Configuration +# Weights are assigned in increments of 100: determines sorting order +weight: 200 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +type: tutorial +# Intended for internal catalogue and search, case sensitive: +product: NGINX One +--- + +## Overview + +This guide explains how to edit an existing Staged Configuration in your NGINX One Console. + +{{< include "nginx-one/staged-config-overview.md" >}} + +## Before you start + +Before you edit a Staged Configuration, ensure: + +- You have an NGINX One Console account with staged configuration permissions.``` + +## View and edit a Staged Configuration + + +Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page. + +To view and edit an NGINX configuration, follow these steps: + +1. On the left menu, select **Staged Configurations**. +1. Select the staged configuration you want to view or modify. +1. Select **Edit** to make changes to the current configuration. +1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors. +1. When you are satisfied with the changes, select **Next**. +1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration. diff --git a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md index bf40c20be..a7a6a7f61 100644 --- a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md +++ b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md @@ -9,9 +9,10 @@ type: - how-to --- -## Introduction {#intro} + +## Introduction -[Load balancing](https://www.f5.com/glossary/load-balancer) refers to efficiently distributing network traffic across multiple backend servers. +[Load balancing](https://www.nginx.com/solutions/load-balancing/) refers to efficiently distributing network traffic across multiple backend servers. In F5 NGINX Plus [R5]({{< ref "nginx/releases.md#r5" >}}) and later, NGINX Plus can proxy and load balance Transmission Control Protocol) (TCP) traffic. TCP is the protocol for many popular applications and services, such as LDAP, MySQL, and RTMP. @@ -19,13 +20,15 @@ In NGINX Plus [R9]({{< ref "nginx/releases.md#r9" >}}) and later, NGINX Plus can To load balance HTTP traffic, refer to the [HTTP Load Balancing]({{< ref "http-load-balancer.md" >}}) article. + ## Prerequisites - Latest NGINX Plus (no extra build steps required) or latest [NGINX Open Source](https://nginx.org/en/download.html) built with the `--with-stream` configuration flag - An application, database, or service that communicates over TCP or UDP - Upstream servers, each running the same instance of the application, database, or service -## Configuring reverse proxy {#proxy_pass} + +## Configuring Reverse Proxy First, you will need to configure _reverse proxy_ so that NGINX Plus or NGINX Open Source can forward TCP connections or UDP datagrams from clients to an upstream group or a proxied server. @@ -115,7 +118,8 @@ Open the NGINX configuration file and perform the following steps: } ``` -## Configuring TCP or UDP load balancing {#upstream} + +## Configuring TCP or UDP Load Balancing To configure load balancing: @@ -246,7 +250,8 @@ stream { } ``` -## Configuring health checks {#health} + +## Configuring Health Checks NGINX can continually test your TCP or UDP upstream servers, avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. @@ -254,7 +259,8 @@ See [TCP Health Checks]({{< ref "nginx/admin-guide/load-balancer/tcp-health-chec See [UDP Health Checks]({{< ref "nginx/admin-guide/load-balancer/udp-health-check.md" >}}) for instructions how to configure health checks for UDP. -## On-the-fly configuration + +## On-the-Fly Configuration Upstream server groups can be easily reconfigured on-the-fly using NGINX Plus REST API. Using this interface, you can view all servers in an upstream group or a particular server, modify server parameters, and add or remove upstream servers. @@ -349,7 +355,8 @@ To enable on-the-fly configuration: } ``` -### On-the-fly configuration example + +### On-the-Fly Configuration Example ```nginx stream { @@ -396,22 +403,23 @@ For example, to add a new server to the server group, send a `POST` request: curl -X POST -d '{ \ "server": "appserv3.example.com:12345", \ "weight": 4 \ - }' -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers' + }' -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers' ``` To remove a server from the server group, send a `DELETE` request: ```shell -curl -X DELETE -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers/0' +curl -X DELETE -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers/0' ``` To modify a parameter for a specific server, send a `PATCH` request: ```shell -curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/9/http/upstreams/appservers/servers/0' +curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0' ``` -## Example of TCP and UDP load-balancing configuration {#example} + +## Example of TCP and UDP Load-Balancing Configuration This is a configuration example of TCP and UDP load balancing with NGINX: @@ -463,13 +471,3 @@ The three [`server`](https://nginx.org/en/docs/stream/ngx_stream_upstream_module - The second server listens on port 53 and proxies all UDP datagrams (the `udp` parameter to the `listen` directive) to an upstream group called **dns_servers**. If the `udp` parameter is not specified, the socket listens for TCP connections. - The third virtual server listens on port 12346 and proxies TCP connections to **backend4.example.com**, which can resolve to several IP addresses that are load balanced with the Round Robin method. - -## See also - -- [TCP Health Checks]({{< relref "tcp-health-check.md" >}}) - -- [UDP Health Checks]({{< relref "udp-health-check.md" >}}) - -- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) - -- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks) diff --git a/content/nginx/admin-guide/load-balancer/udp-health-check.md b/content/nginx/admin-guide/load-balancer/udp-health-check.md index 7885d032a..bb4818fd4 100644 --- a/content/nginx/admin-guide/load-balancer/udp-health-check.md +++ b/content/nginx/admin-guide/load-balancer/udp-health-check.md @@ -9,11 +9,10 @@ type: - how-to --- -NGINX Plus can continually test your upstream servers that handle UDP network traffic (DNS, RADIUS, syslog), avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. + +## Prerequisites -## Prerequisites {#prereq} - -- You have [configured an upstream group of servers]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) that handles UDP network traffic in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: +- You have configured an upstream group of servers that handles UDP network traffic (DNS, RADIUS, syslog) in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: ```nginx stream { @@ -45,7 +44,8 @@ NGINX Plus can continually test your upstream servers that handle UDP network tr See [TCP and UDP Load Balancing]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) for details. -## Passive UDP health checks {#hc_passive} + +## Passive UDP Health Checks NGINX Open Source or F5 NGINX Plus can mark the server as unavailable and stop sending UDP datagrams to it for some time if the server replies with an error or times out. @@ -62,7 +62,8 @@ upstream dns_upstream { } ``` -## Active UDP health checks {#hc_active} + +## Active UDP Health Checks Active Health Checks allow testing a wider range of failure types and are available only for NGINX Plus. For example, instead of waiting for an actual TCP request from a DNS client to fail before marking the DNS server as down (as in passive health checks), NGINX Plus will send special health check requests to each upstream server and check for a response that satisfies certain conditions. If a connection to the server cannot be established, the health check fails, and the server is considered unhealthy. NGINX Plus does not proxy client connections to unhealthy servers. If more than one health check is defined, the failure of any check is enough to consider the corresponding upstream server unhealthy. @@ -99,7 +100,8 @@ To enable active health checks: A basic UDP health check assumes that NGINX Plus sends the β€œnginx health check” string to an upstream server and expects the absence of ICMP β€œDestination Unreachable” message in response. You can configure your own health check tests in the `match {}` block. See [The β€œmatch {}” Configuration Block](#hc_active_match) for details. -### Fine-Tuning UDP Health Checks {#hc_active_finetune} + +### Fine-Tuning UDP Health Checks You can fine‑tune the health check by specifying the following parameters to the [`health_check`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check) directive: @@ -117,9 +119,10 @@ server { In the example, the time between UDP health checks is increased to 20 seconds, the server is considered unhealthy after 2 consecutive failed health checks, and the server needs to pass 2 consecutive checks to be considered healthy again. -### The β€œmatch {}” configuration block {#hc_active_match} + +### The β€œmatch {}” Configuration Block -A basic UDP health check assumes that NGINX Plus sends the β€œnginx health check” string to an upstream server and expects the absence of ICMP β€œDestination Unreachable” message in response. You can configure your own health check tests that will verify server responses. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. +You can verify server responses to health checks by configuring a number of tests. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. 1. In the top‑level `stream {}` context, specify the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) block and set its name, for example, `udp_test`: @@ -152,9 +155,8 @@ A basic UDP health check assumes that NGINX Plus sends the β€œnginx health check These parameters can be used in different combinations, but no more than one `send` and one `expect` parameter can be specified at a time. -## Usage scenarios - -### NTP health checks {#example_ntp} + +#### Example Test for NTP To fine‑tune health checks for NTP, you should specify both `send` and `expect` parameters with the following text strings: @@ -165,138 +167,14 @@ match ntp { } ``` -#### Complete NTP health check configuration example - -```nginx - -stream { - upstream ntp_upstream { - zone ntp_zone 64k; - server 192.168.136.130:53; - server 192.168.136.131:53; - server 192.168.136.132:53; -} - server { - listen 53 udp; - proxy_pass ntp_upstream; - health_check match=ntp udp; - proxy_timeout 1s; - proxy_responses 1; - error_log logs/ntp.log; - } - - match ntp { - send \xe3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00; - expect ~* \x24; - } -} -``` - -### DNS health checks {#example_dns} - -[DNS health checks](#hc_active) can be enhanced to perform real DNS lookup queries. You can craft a valid DNS query packet, send it to the upstream server, and inspect the response to determine health. - -The process includes three steps: -- [Creating a CNAME test record](#create-a-cname-record) on your DNS server. -- [Crafting a raw DNS query packet](#construct-a-raw-dns-query-packet) to be sent by NGINX Plus. -- [Validating the expected response](#configure-the-match-block-for-dns-lookup) using the `match` block, where the `send` parameter represents a raw DNS query packet, and `expect` represents the value of the CNAME record. - -#### Create a CNAME record - -First, create a CNAME record on your DNS server for a health check that points to the target website. - -For example, if you are using BIND self-hosted DNS solution on a Linux server: - -- Open the zone file in a text editor: - -```shell -sudo nano /etc/bind/zones/db.example.com -``` -- Add a CNAME record, making `healthcheck.example.com` resolve to `healthy.svcs.example.com`: - -```none -healthcheck IN CNAME healthy.svcs.example.com. -``` - -- Save the file and reload the DNS service: - -```shell -sudo systemctl reload bind9 -``` - -Once the CNAME record is live and resolvable, you can craft a DNS query packet that represents a DNS lookup and can be used in the `send` directive. - -#### Construct a raw DNS query packet - -The `send` parameter of the `match` block allows you to send raw UDP packets for health checks. To query your CNAME record, you need to construct a valid DNS query packet according to the [DNS protocol message format](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1), including a header and question section. + +#### Example Test for DNS -The DNS Query packet can be created using DNS packet builders, such as Python Scapy or dnslib, or packet analyzers, such as tcpdump or Wireshark. If using a packet analyzer, extract only the DNS layer, removing Ethernet, IP, and UDP-related headers. - -This is the raw DNS query of `healthcheck.example.com`, represented as one line in Hex with `\x` prefixes: - -```none -\x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01 -``` -where: - -{{}} -| HEX | Description | -|------------------|------------------------| -| \x00\x01 | Transaction ID: 0x0001 | -| \x01\x00 | Flags: Standard query, recursion desired | -| \x00\x01 | Questions: 1 | -| \x00\x00 | Answer RRs: 0 | -| \x00\x00 | Authority RRs: 0 | -| \x00\x00 | Additional RRs: 0 | -| \x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b | "healthcheck" | -| \x07\x65\x78\x61\x6d\x70\x6c\x65 | "example" | -| \x03\x63\x6f\x6d | "com" | -| \x00 | end of name | -| \x00\x01 | Type: A | -| \x00\x01 | Class: IN | -{{}} - -#### Configure the match block for DNS lookup - -Finally, specify the `match` block in the NGINX configuration file to pair the raw query with an expected response. The `send` directive should contain the DNS query packet, while `expect` directive should contain a matching DNS record in the DNS server's response: +To fine‑tune health checks for DNS, you should also specify both `send` and `expect` parameters with the following text strings: ```nginx match dns { - send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; - expect ~* "healthy.svcs.example.com"; -} -``` - -#### Complete DNS health check configuration example - -```nginx - -stream { - upstream dns_upstream { - zone dns_zone 64k; - server 192.168.136.130:53; - server 192.168.136.131:53; - server 192.168.136.132:53; -} - server { - listen 53 udp; - proxy_pass dns_upstream; - health_check match=dns udp; - proxy_timeout 1s; - proxy_responses 1; - error_log logs/dns.log; - } - - match dns { - # make sure appropriate CNAME record exists - send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; - expect ~* "healthy.svcs.example.com"; - } + send \x00\x2a\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x03\x73\x74\x6c\x04\x75\x6d\x73\x6c\x03\x65\x64\x75\x00\x00\x01\x00\x01; + expect ~* "health.is.good"; } ``` - -## See also - -- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) - -- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks#activeHealthCheck) diff --git a/content/nim/nginx-app-protect/manage-waf-security-policies.md b/content/nim/nginx-app-protect/manage-waf-security-policies.md index 5c0e5ebf3..71684b133 100644 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ b/content/nim/nginx-app-protect/manage-waf-security-policies.md @@ -1,7 +1,8 @@ --- -title: Manage and deploy WAF policies and log profiles -description: Learn how to use F5 NGINX Instance Manager to manage NGINX App Protect WAF security policies and security log profiles. -weight: 300 +title: Manage WAF Security Policies and Security Log Profiles +description: Learn how to use F5 NGINX Management Suite Instance Manager to manage NGINX + App Protect WAF security policies and security log profiles. +weight: 200 toc: true type: how-to product: NIM @@ -10,76 +11,83 @@ docs: DOCS-1105 ## Overview -F5 NGINX Instance Manager lets you manage NGINX App Protect WAF configurations using either the web interface or REST API. You can edit, update, and deploy security policies, log profiles, attack signatures, and threat campaigns to individual instances or instance groups. +F5 NGINX Management Suite Instance Manager provides the ability to manage the configuration of NGINX App Protect WAF instances either by the user interface or the REST API. This includes editing, updating, and deploying security policies, log profiles, attack signatures, and threat campaigns to individual instances and/or instance groups. -You can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. The bundle includes all necessary components for a specific NGINX App Protect WAF version. Precompiling the bundle improves performance by avoiding separate compilation of each component during deployment. +In Instance Manager v2.14.0 and later, you can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. A security policy bundle consists of the security policy, the attack signatures, and threat campaigns for a particular version of NGINX App Protect WAF, and additional supporting files that make it possible for NGINX App Protect WAF to use the bundle. Because the security policy bundle is pre-compiled, the configuration gets applied faster than when you individually reference the security policy, attack signature, and threat campaign files. {{}} -The following capabilities are available only through the Instance Manager REST API: +The following capabilities are only available via the Instance Manager REST API: - Update security policies - Create, read, and update security policy bundles -- Create, read, update, and delete security log profiles -- Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups +- Create, read, update, and delete Security Log Profiles +- Publish security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups {{}} --- -## Before you begin +## Before You Begin -Before continuing, complete the following steps: +Complete the following prerequisites before proceeding with this guide: -- [Set up App Protect WAF configuration management]({{< ref "setup-waf-config-management" >}}) -- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: +- [Set Up App Protect WAF Configuration Management]({{< ref "setup-waf-config-management" >}}) +- Verify that your user account has the [necessary permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the Instance Manager REST API: - - **Module**: Instance Manager - - **Feature**: Instance Management β†’ `READ` - - **Feature**: Security Policies β†’ `READ`, `CREATE`, `UPDATE`, `DELETE` + - **Module**: Instance Manager + - **Feature**: Instance Management + - **Access**: `READ` + - **Feature**: Security Policies + - **Access**: `READ`, `CREATE`, `UPDATE`, `DELETE` -To use policy bundles, you also need to: +The following are required to use support policy bundles: -- Have `UPDATE` permissions for each referenced security policy -- [Install the correct `nms-nap-compiler` package]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}) for your App Protect WAF version -- [Install the required attack signatures and threat campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}) +- You must have `UPDATE` permissions for the security policies specified in the request. +- The correct `nms-nap-compiler` packages for the NGINX App Protect WAF version you're using are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}). +- The attack signatures and threat campaigns that you want to use are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}). -### Access the web interface +### How to Access the Web Interface -To access the web interface, open a browser and go to the fully qualified domain name (FQDN) of your NGINX Instance Manager. Log in, then select **Instance Manager** from the Launchpad. +To access the web interface, go to the FQDN for your NGINX Instance Manager host in a web browser and log in. Once you're logged in, select "Instance Manager" from the Launchpad menu. -### Access the REST API +### How to Access the REST API {{< include "nim/how-to-access-nim-api.md" >}} --- -## Create a security policy {#create-security-policy} +## Create a Security Policy {#create-security-policy} {{}} {{%tab name="web interface"%}} -To create a security policy using the NGINX Instance Manager web interface: +
    + +To create a security policy using the Instance Manager web interface: + +1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. +2. On the left menu, select **App Protect**. +3. On the *Security Policies* page, select **Create**. +4. On the *Create Policy* page, fill out the necessary fields: -1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, select **Create**. -5. On the *Create Policy* page, enter the required information: - - **Name**: Enter a name for the policy. - - **Description**: (Optional) Add a brief description. - - **Enter Policy**: Paste or type the JSON-formatted policy into the editor. The interface automatically validates the JSON. + - **Name**: Provide a name for the policy. + - **Description**: (Optional) Add a short description for the policy. + - **Enter Policy**: Type or paste the policy in JSON format into the form provided. The editor will validate the JSON for accuracy. - For help writing custom policies, see the [NGINX App Protect WAF Declarative Policy guide](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) and the [Policy Authoring and Tuning section](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) in the configuration guide. + For more information about creating custom policies, refer to the [NGINX App Protect WAF Declarative Policy](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) guide and the [Policy Authoring and Tuning](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) section of the config guide. -6. Select **Save**. +5. Select **Save**. {{%/tab%}} {{%tab name="API"%}} -To upload a new security policy using the REST API, send a `POST` request to the Security Policies API endpoint. +To upload a new security policy, send an HTTP `POST` request to the Security Policies API endpoint. + +{{}}Before sending a security policy to Instance Manager, you need to encode it using `base64`. Submitting a policy in its original JSON format will result in an error.{{}} + +
    -You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. {{}} @@ -93,7 +101,7 @@ You must encode the JSON policy using `base64`. If you send the policy in plain For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ -H "Authorization: Bearer " \ -d @ignore-xss-example.json ``` @@ -126,7 +134,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ "modified": "2022-04-12T23:19:58.502Z", "name": "ignore-cross-site-scripting", "revisionTimestamp": "2022-04-12T23:19:58.502Z", - "uid": "" + "uid": "21daa130-4ba4-442b-bc4e-ab294af123e5" }, "selfLink": { "rel": "/api/platform/v1/services/environments/prod" @@ -140,13 +148,11 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ --- -## Update a security policy - +## Update a Security Policy -To update a security policy, send a `POST` or `PUT` request to the Security Policies API. +To update a security policy, send an HTTP `POST` request to the Security Policies API endpoint, `/api/platform/v1/security/policies`. -- Use `POST` with the `isNewRevision=true` parameter to add a new version of an existing policy. -- Use `PUT` with the policy UID to overwrite the existing version. +You can use the optional `isNewRevision` parameter to indicate whether the updated policy is a new version of an existing policy. {{}} @@ -159,35 +165,33 @@ To update a security policy, send a `POST` or `PUT` request to the Security Poli {{}} -To use `POST`, include the policy metadata and content in your request: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-xss-policy.json ``` -To use PUT, first retrieve the policy’s unique identifier (UID). You can do this by sending a GET request to the policies endpoint: +You can update a specific policy by sending an HTTP `PUT` request to the Security Policies API endpoint that includes the policy's unique identifier (UID). -```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " -``` +To find the UID, send an HTTP `GET` request to the Security Policies API endpoint. This returns a list of all Security Policies that contains the unique identifier for each policy. + +Include the UID for the security policy in your `PUT` request to update the policy. Once the policy update is accepted, the WAF compiler will create a new, updated bundle. -Then include the UID in your PUT request: +For example: ```shell -curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-xss-policy.json + --Content-Type application/json -d @update-xss-policy.json ``` -After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. +After you have pushed an updated security policy, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a security policy +## Delete a Security Policy {{}} @@ -195,29 +199,17 @@ After updating the policy, you can [publish it](#publish-policy) to selected ins
    -To delete a security policy using the NGINX Instance Manager web interface: - -1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. -2. From the Launchpad menu, select **Instance Manager**. -3. In the left menu, select **App Protect**. -4. On the *Security Policies* page, find the policy you want to delete. -5. Select the **Actions** menu (**...**) and choose **Delete**. +To delete a security policy using the Instance Manager web interface: +1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. +2. On the left menu, select **App Protect**. +3. On the *Security Policies* page, select the **Actions** menu (represented by an ellipsis, **...**) for the policy you want to delete. Select **Delete** to remove the policy. {{%/tab%}} {{%tab name="API"%}} -To delete a security policy using the REST API: - -1. Retrieve the UID for the policy by sending a `GET` request to the policies endpoint: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ - -H "Authorization: Bearer " - ``` - -2. Send a `DELETE` request using the policy UID: +To delete a security policy, send an HTTP `DELETE` request to the Security Policies API endpoint that includes the unique identifier for the policy that you want to delete. {{}} @@ -229,10 +221,10 @@ To delete a security policy using the REST API: {{}} -Example: +For example: ```shell -curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ +curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ -H "Authorization: Bearer " ``` @@ -240,42 +232,36 @@ curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/}} ---- +{{%comment%}}TO DO: Add sections for managing attack signatures and threat campaigns{{%/comment%}} -## Create security policy bundles {#create-security-policy-bundles} - - -To create a security policy bundle, send a `POST` request to the Security Policy Bundles API. The policies you want to include in the bundle must already exist in NGINX Instance Manager. +--- -Each bundle includes: +## Create Security Policy Bundles {#create-security-policy-bundles} -- A security policy -- Attack signatures -- Threat campaigns -- A version of NGINX App Protect WAF -- Supporting files required to compile and deploy the bundle +To create security policy bundles, send an HTTP `POST` request to the Security Policies Bundles API endpoint. The specified security policies you'd like to compile into security policy bundles must already exist in Instance Manager. -### Required fields +### Required Fields -- `appProtectWAFVersion`: The version of NGINX App Protect WAF to target. -- `policyName`: The name of the policy to include. Must reference an existing policy. -- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. +- `appProtectWAFVersion`: The version of NGINX App Protect WAF being used. +- `policyName`: The name of security policy to include in the bundle. This must reference an existing security policy; refer to the [Create a Security Policy](#create-security-policy) section above for instructions. -If you don’t include `attackSignatureVersionDateTime` or `threatCampaignVersionDateTime`, the latest versions are used by default. You can also set them explicitly by using `"latest"` as the value. +### Notes +- If you do not specify a value for the `attackSignatureVersionDateTime` and/or `threatCampaignVersionDateTime` fields, the latest version of each will be used by default. You can also explicitly state that you want to use the most recent version by specifying the keyword `latest` as the value. +- If the `policyUID` field is not defined, the latest version of the specified security policy will be used. This field **does not allow** use of the keyword `latest`. {{}} -| Method | Endpoint | -|--------|----------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | POST | `/api/platform/v1/security/policies/bundles` | {{}} -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -d @security-policy-bundles.json ``` @@ -288,7 +274,7 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "bundles": [{ "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18" }, @@ -319,10 +305,10 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" + "uid": "dceb8254-9a90-4e77-87ac-73070f821412" }, "content": "", "compilationStatus": { @@ -335,11 +321,11 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", - "policyName": "default-enforcement", - "policyUID": "", + "policyName": "defautl-enforcement", + "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "", "compilationStatus": { @@ -353,10 +339,10 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "", + "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" }, "content": "", "compilationStatus": { @@ -368,38 +354,39 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` + --- -## List security policy bundles {#list-security-policy-bundles} +## List Security Policy Bundles {#list-security-policy-bundles} -To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. +To list security policy bundles, send an HTTP `GET` request to the Security Policies Bundles API endpoint. -You’ll only see bundles you have `"READ"` permissions for. +{{}}The list will only contain the security policy bundles that you have "READ" permissions for in Instance Manager.{{}} -You can use the following query parameters to filter results: +You can filter the results by using the following query parameters: -- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. -- `policyName`: Return only bundles that match this policy name. -- `policyUID`: Return only bundles that match this policy UID. -- `startTime`: Return only bundles modified at or after this time. -- `endTime`: Return only bundles modified before this time. +- `includeBundleContent`: Boolean indicating whether to include the security policy bundle content for each bundle when getting a list of bundles or not. If not provided, defaults to `false`. Please note that the content returned is `base64 encoded`. +- `policyName`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy name will be returned. If not provided, it will not filter based on `policyName`. +- `policyUID`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy UID will be returned. If not provided, it will not filter based on `policyUID`. +- `startTime`: The security policy bundle's "modified time" has to be equal to or greater than this time value. If no value is supplied, it defaults to 24 hours from the current time. `startTime` has to be less than `endTime`. +- `endTime`: Indicates the time that the security policy bundles modified time has to be less than. If no value is supplied, it defaults to current time. `endTime` has to be greater than `startTime`. -If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. +
    {{}} -| Method | Endpoint | -|--------|----------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | GET | `/api/platform/v1/security/policies/bundles` | {{}} -Example: +For example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` @@ -414,10 +401,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "" + "uid": "dceb8254-9a90-4e77-87ac-73070f821412" }, "content": "", "compilationStatus": { @@ -431,10 +418,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", "policyName": "defautl-enforcement", - "policyUID": "", + "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "", "compilationStatus": { @@ -448,10 +435,10 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "", + "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" }, "content": "", "compilationStatus": { @@ -465,35 +452,35 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ --- -## Get a security policy bundle {#get-security-policy-bundle} +## Get a Security Policy Bundle {#get-security-policy-bundle} -To retrieve a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. +To get a specific security policy bundle, send an HTTP `GET` request to the Security Policies Bundles API endpoint that contains the security policy UID and security policy bundle UID in the path. -You must have `"READ"` permission for the bundle to retrieve it. +{{}}You must have "READ" permission for the security policy bundle to be able to retrieve information about a bundle by using the REST API.{{}} + +
    {{}} -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | {{}} -Example: + +For example: ```shell -curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ +curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/29d86fe8-612a-5c69-895a-04fc5b9849a6/bundles/trs35lv2-9a90-4e77-87ac-ythn4967 \ -H "Authorization: Bearer " ``` -The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file. - -Example: +The JSON response, shown in the example below, includes a `content` field that is base64 encoded. After you retrieve the information from the API, you will need to base64 decode the content field. You can include this in your API call, as shown in the following example cURL request: ```bash -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ - -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz +curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz ```
    @@ -505,10 +492,10 @@ curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", - "policyUID": "", + "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "" + "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" }, "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", "compilationStatus": { @@ -520,25 +507,28 @@ curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/ --- -## Create a security log profile {#create-security-log-profile} +## Create a Security Log Profile {#create-security-log-profile} + +Send an HTTP `POST` request to the Security Log Profiles API endpoint to upload a new security log profile. -To upload a new security log profile, send a `POST` request to the Security Log Profiles API endpoint. +{{}}Before sending a security log profile to Instance Manager, you need to encode it using `base64`. Submitting a log profile in its original JSON format will result in an error.{{}} + +
    -You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. {{}} -| Method | Endpoint | -|--------|-----------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------| | POST | `/api/platform/v1/security/logprofiles` | {{}} -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " \ -d @default-log-example.json ``` @@ -568,100 +558,87 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ "modified": "2023-07-05T22:09:19.634358096Z", "name": "default-log-example", "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", - "uid": "" + "uid": "54c35ad7-e082-4dc5-bb5d-2640a17d5620" }, "selfLink": { - "rel": "/api/platform/v1/security/logprofiles/" + "rel": "/api/platform/v1/security/logprofiles/54c35ad7-e082-4dc5-bb5d-2640a17d5620" } } ``` --- -## Update a security log profile {#update-security-log-profile} +## Update a Security Log Profile + +To update a security log profile, send an HTTP `POST` request to the Security Log Profiles API endpoint, `/api/platform/v1/security/logprofiles`. -To update a security log profile, you can either: +You can use the optional `isNewRevision` parameter to indicate whether the updated log profile is a new version of an existing log profile. -- Use `POST` with the `isNewRevision=true` parameter to add a new version. -- Use `PUT` with the log profile UID to overwrite the existing version. {{}} -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | +| Method | Endpoint | +|--------|---------------------------------------------------------| +| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | | PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -To create a new revision: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ +curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-default-log.json ``` -To overwrite an existing security log profile: +You can update a specific log profile by sending an HTTP `PUT` request to the Security Log Profiles API endpoint that includes the log profile's unique identifier (UID). + +To find the UID, send an HTTP `GET` request to the Security Log Profiles API endpoint. This returns a list of all Security Log Profiles that contains the unique identifier for each log profile. -1. Retrieve the profile’s UID: +Include the UID for the security log profile in your `PUT` request to update the log profile. - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-log-profile.json - ``` +For example: -2. Use the UID in your PUT request: - - ```shell - curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " \ - --Content-Type application/json \ - -d @update-log-profile.json - ``` +```shell +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ + -H "Authorization: Bearer " \ + --Content-Type application/json -d @update-default-log.json +``` -After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. +After you have pushed an updated security log profile, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a security log profile {#delete-security-log-profile} +## Delete a Security Log Profile -To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. +To delete a security log profile, send an HTTP `DELETE` request to the Security Log Profiles API endpoint that includes the unique identifier for the log profile that you want to delete. {{}} -| Method | Endpoint | -|--------|--------------------------------------------------------------------| +| Method | Endpoint | +|--------|------------------------------------------------------------| | DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -1. Retrieve the UID: - - ```shell - curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ - -H "Authorization: Bearer " - ``` - -2. Send the delete request: +For example: - ```shell - curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ - -H "Authorization: Bearer " - ``` +```shell +curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ + -H "Authorization: Bearer " +``` --- -## Publish updates to instances {#publish-policy} +## Publish Updates to Instances {#publish-policy} -Use the Publish API to push security policies, log profiles, attack signatures, and threat campaigns to NGINX instances or instance groups. +The Publish API lets you distribute security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups. -Call this endpoint *after* you've created or updated the resources you want to deploy. +{{}}Use this endpoint *after* you've added or updated security policies, security log profiles, attack signatures, and/or threat campaigns.{{}} {{}} @@ -673,20 +650,18 @@ Call this endpoint *after* you've created or updated the resources you want to d {{}} -Include the following information in your request, depending on what you're publishing: +When making a request to the Publish API, make sure to include all the necessary information for your specific use case: -- Instance and instance group UIDs -- Policy UID and name -- Log profile UID and name -- Attack signature library UID and version -- Threat campaign UID and version +- Instance and/or Instance Group UID(s) to push the bundle to +- Threat Campaign version and UID +- Attack Signature version and UID +- Security Policy UID(s) +- Security Log Profile UID(s) -Example: +For example: ```shell -curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ - -H "Authorization: Bearer " \ - -d @publish-request.json +curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorization: Bearer " ```
    @@ -696,27 +671,27 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ { "publications": [ { - "instances": [ - "" - ], + "attackSignatureLibrary": { + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "versionDateTime": "2022.10.02" + }, "instanceGroups": [ - "" + "3fa85f64-5717-4562-b3fc-2c963f66afa6" + ], + "instances": [ + "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], - "policyContent": { - "name": "example-policy", - "uid": "" - }, "logProfileContent": { - "name": "example-log-profile", - "uid": "" + "name": "default-log", + "uid": "ffdbda39-88be-420a-b673-19d4183b7e4c" }, - "attackSignatureLibrary": { - "uid": "", - "versionDateTime": "2023.10.02" + "policyContent": { + "name": "default-enforcement", + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "threatCampaign": { - "uid": "", - "versionDateTime": "2023.10.01" + "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", + "versionDateTime": "2022.10.01" } } ] @@ -746,91 +721,357 @@ curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ --- -## Check security policy and security log profile publication status {#check-publication-status} - -After publishing updates, you can check deployment status using the NGINX Instance Manager REST API. +## Check Security Policy and Security Log Profile Publication Status +When publishing an NGINX configuration that references a security policy and secuity log profile, the Instance Manager REST APIs can provide further details about the status of the configuration publications. To access this information, use the Instance Manager API endpoints and method as indicated. -Use the following endpoints to verify whether the configuration updates were successfully deployed to instances or instance groups. +To retrieve the details for the different configuration publication statuses for a particular security policy, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security policy. -### Check publication status for a security policy +| Method | Endpoint | +|--------|-----------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/associations/{security-policy-name}` | -To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. +You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: -{{}} +- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails +- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails -| Method | Endpoint | -|--------|--------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | - -{{}} - -Example: +The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/associations/ignore-xss" -H "Authorization: Bearer " ``` -In the response, look for the `lastDeploymentDetails` field under instance or `instanceGroup.instances`. +
    +JSON Response +```json +{ + "associations": [ + { + "attackSignatureLibrary": { + "uid": "c69460cc-6b59-4813-8d9c-76e4a6c56b4b", + "versionDateTime": "2023.02.16" + }, + "instance": { + "hostName": "ip-172-16-0-99", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + "systemUid": "0435a5de-41c1-3754-b2e8-9d9fe946bafe", + "uid": "29d86fe8-612a-5c69-895a-04fc5b9849a6" + }, + "instanceGroup": { + "displayName": "inst_group_1", + "instances": [ + { + "hostName": "hostname1", + "systemUid": "49d143c2-f556-4cd7-8658-76fff54fb861", + "uid": "c8e15dcf-c504-4b7f-b52d-def7b8fd2f64", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + }, + { + "hostName": "hostname2", + "systemUid": "88a99ab0-15bb-4719-9107-daf5007c33f7", + "uid": "ed7e9173-794f-41af-80d9-4ed37d593247", + "lastDeploymentDetails": { + "createTime": "2023-04-11T21:36:11.519174534Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-99" + } + ] + }, + "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-04-11T21:36:14.008108979Z" + }, + } + ], + "uid": "51f8addc-c0e9-438b-b0b6-3e4f1aa8202d" + }, + "policyUid": "9991f237-d9c7-47b7-98aa-faa836838f38", + "policyVersionDateTime": "2023-04-11T21:18:19.183Z", + "threatCampaign": { + "uid": "eab683fe-c2f1-4910-a88c-8bfbc6363164", + "versionDateTime": "2023.02.15" + } + } + ] +} +``` -### Check publication status for a security log profile +
    -{{}} +To retrieve the details for the different configuration publication statuses for a particular security log profile, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security log profile. -| Method | Endpoint | -|--------|-------------------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | +| Method | Endpoint | +|--------|-----------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{security-log-profile-name}` | -{{}} +You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: -Example: +- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails +- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails + +The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/logprofiles/associations/default-log" -H "Authorization: Bearer " ``` -The response also contains `lastDeploymentDetails` for each instance or group. +
    +JSON Response -### Check status for a specific instance +```json +{ + "associations": [ + { + "instance": { + "hostName": "", + "systemUid": "", + "uid": "" + }, + "instanceGroup": { + "displayName": "ig1", + "instances": [ + { + "hostName": "ip-172-16-0-142", + "systemUid": "1d1f03ff-02de-32c5-8dfd-902658aada4c", + "uid": "18d074e6-3868-51ba-9999-b7466a936815" + } + ], + "lastDeploymentDetails": { + "createTime": "2023-07-05T23:01:06.679136973Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-142" + } + ] + }, + "id": "9bfc9db7-877d-4e8e-a43d-9660a6cd11cc", + "message": "Instance Group config successfully published to ig1", + "status": "successful", + "updateTime": "2023-07-05T23:01:06.790802157Z" + }, + "uid": "0df0386e-82f7-4efc-863e-5d7cfbc3f7df" + }, + "logProfileUid": "b680f7c3-6fc0-4c6b-889a-3025580c7fcb", + "logProfileVersionDateTime": "2023-07-05T22:08:47.371Z" + }, + { + "instance": { + "hostName": "ip-172-16-0-5", + "lastDeploymentDetails": { + "createTime": "2023-07-05T21:45:08.698646791Z", + "details": { + "failure": [], + "pending": [], + "success": [ + { + "name": "ip-172-16-0-5" + } + ] + }, + "id": "73cf670a-738a-4a74-b3fb-ac9771e89814", + "message": "Instance config successfully published to", + "status": "successful", + "updateTime": "2023-07-05T21:45:08.698646791Z" + }, + "systemUid": "0afe5ac2-43aa-36c8-bcdc-7f88cdd35ab2", + "uid": "9bb4e2ef-3746-5d79-b526-e545fad27e90" + }, + "instanceGroup": { + "displayName": "", + "instances": [], + "uid": "" + }, + "logProfileUid": "bb3badb2-f8f5-4b95-9428-877fc208e2f1", + "logProfileVersionDateTime": "2023-07-03T21:46:17.006Z" + } + ] +} +``` -You can also view the deployment status for a specific instance by providing the system UID and instance UID. +
    -{{}} +To retrieve the configuration publication status details for a particular instance, send an HTTP `GET` request to the Instances API endpoint, providing the unique system and instance identifiers. -| Method | Endpoint | -|--------|------------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | +| Method | Endpoint | +|--------|-----------------------------------------------------------------| +| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-id}` | -{{}} +You can locate the configuration publication status in the the response within the `lastDeploymentDetails` field, which contains additional fields that provide more context around the status. -Example: +The example below shows a call to the `instances` endpoint and the corresponding JSON response containing a compiler related error message. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ - -H "Authorization: Bearer " +curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b" -H "Authorization: Bearer " ``` -In the response, look for the `lastDeploymentDetails` field, which shows the deployment status and any related errors. +
    +JSON Response -### Check deployment result by deployment ID +```json +{ + "build": { + "nginxPlus": true, + "release": "nginx-plus-r28", + "version": "1.23.2" + }, + "configPath": "/etc/nginx/nginx.conf", + "configVersion": { + "instanceGroup": { + "createTime": "0001-01-01T00:00:00Z", + "uid": "", + "versionHash": "" + }, + "versions": [ + { + "createTime": "2023-01-14T10:48:46.319Z", + "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "versionHash": "922e9d40fa6d4dd3a4b721295b8ecd95f73402644cb8d234f9f4f862b8a56bfc" + } + ] + }, + "displayName": "ip-192-0-2-27", + "links": [ + { + "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73", + "name": "system" + }, + { + "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "name": "self" + }, + { + "rel": "/api/platform/v1/systems/instances/deployments/b31c6ab1-4a46-4c81-a065-204575145e8e", + "name": "deployment" + } + ], + "processPath": "/usr/sbin/nginx", + "registrationTime": "2023-01-14T10:12:31.000Z", + "startTime": "2023-01-14T10:09:43Z", + "status": { + "lastStatusReport": "2023-01-14T11:11:49.323495017Z", + "state": "online" + }, + "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", + "version": "1.23.2", + "appProtect": { + "attackSignatureVersion": "Available after publishing Attack Signatures from Instance Manager", + "status": "active", + "threatCampaignVersion": "Available after publishing Threat Campaigns from Instance Manager", + "version": "4.2.0" + }, + "configureArgs": [ + ... + ], + "lastDeploymentDetails": { + "createTime": "2023-01-14T11:10:25.096812852Z", + "details": { + "error": "{\"instance:b9df6377-2c4f-3266-a64a-e064b0371c73\":\"failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.\"}", + "failure": [ + { + "failMessage": "failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.", + "name": "ip-192-0-2-27" + } + ], + "pending": [], + "success": [] + }, + "id": "b31c6ab1-4a46-4c81-a065-204575145e8e", + "message": "Instance config failed to publish to", + "status": "failed", + "updateTime": "2023-01-14T11:10:25.175145693Z" + }, + "loadableModules": [ + ... + ], + "packages": [ + ... + ], + "processId": "10345", + "ssl": { + "built": null, + "runtime": null + } +} +``` -When you use the Publish API to [publish security content](#publish-policy), NGINX Instance Manager creates a deployment ID for the request. You can use this ID to check the result of the publication. +
    -{{}} +When you use the Publish API (`/security/publish`) to [publish a security policy and security log profile](#publish-policy), Instance Manager creates a deployment ID for the request. To view the status of the update, or to check for any errors, use the endpoint and method shown below and reference the deployment ID. | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | -{{}} +You can locate the configuration publication status in the the response within the `details` field, which contains additional fields that provide more context around the status. -Example: +The example below shows a call to the `deployments` endpoint and the corresponding JSON response containing a compiler error message. ```shell -curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ +curl -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/instances/deployments/d38a8e5d-2312-4046-a60f-a30a4aea1fbb" \ -H "Authorization: Bearer " ``` -The response includes the full deployment status, success or failure details, and any compiler error messages. +
    +JSON Response + +```json +{ + "createTime": "2023-01-14T04:35:47.566082799Z", + "details": { + "error": "{\"instance:8a2092aa-5612-370d-bff0-5d7521e206d6\":\"failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again\"}", + "failure": [ + { + "failMessage": "failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again", + "name": "ip-192-0-2-243" + } + ], + "pending": [], + "success": [] + }, + "id": "d38a8e5d-2312-4046-a60f-a30a4aea1fbb", + "message": "Instance config failed to publish to", + "status": "failed", + "updateTime": "2023-01-14T04:35:47.566082799Z" +} +``` + +
    diff --git a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md index b0d31319f..92287079d 100644 --- a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md +++ b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md @@ -1,76 +1,68 @@ --- -description: Learn how to use F5 NGINX Instance Manager to set up and manage NGINX App Protect WAF security policies. +description: Learn how you can use F5 NGINX Management Suite Instance Manager to configure + NGINX App Protect WAF security policies. docs: DOCS-992 -title: "How WAF policy management works" +title: NGINX App Protect WAF configuration management toc: true -weight: 100 +weight: 500 type: - reference --- ## Overview -F5 NGINX Instance Manager helps you manage [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/) security configurations. +F5 NGINX Management Suite Instance Manager provides configuration management for [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/). -Use NGINX Instance Manager with NGINX App Protect WAF to inspect incoming traffic, detect threats, and block malicious requests. You can define policies in one place and push them to some or all of your NGINX App Protect WAF instances. +You can use NGINX App Protect WAF with Instance Manager to inspect incoming traffic, identify potential threats, and block malicious traffic. With Configuration Management for App Protect WAF, you can configure WAF security policies in a single location and push your configurations out to one, some, or all of your NGINX App Protect WAF instances. -### Key features +### Features -- Manage WAF policies using the NGINX Instance Manager web interface or REST API -- Update attack signature and threat campaign packages -- Compile WAF configurations into a binary bundle for deployment +- Manage NGINX App Protect WAF security configurations by using the NGINX Management Suite user interface or REST API +- Update Attack Signatures and Threat Campaign packages +- Compile security configurations into a binary bundle for consumption by NGINX App Protect WAF instances ## Architecture -NGINX Instance Manager lets you define and manage security policies, upload signature packages, and push configurations to your NGINX App Protect WAF instances. It can also compile your security configuration into a bundle before publishing it to the data plane. +As demonstrated in Figure 1, Instance Manager lets you manage security configurations for NGINX App Protect WAF. You can define security policies, upload attack signatures and threat campaign packages, and publish common configurations out to your NGINX App Protect WAF instances. Instance Manager can compile the security configuration into a bundle before pushing the configuration to the NGINX App Protect WAF data plane instances. The NGINX Management Suite Security Monitoring module provides data visualization for NGINX App Protect, so you can monitor, analyze, and refine your policies. -The **Security Monitoring** module shows real-time data from NGINX App Protect WAF so you can track traffic, spot anomalies, and fine-tune policies. +{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Management Suite with NGINX App Protect Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution" width="75%">}} -{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with NGINX App Protect architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to NGINX App Protect WAF instances in the data plane" >}} +### Security Bundle Compilation {#security-bundle} -### Security bundle compilation {#security-bundle} +Instance Manager provides a compiler that can be configured to bundle the complete security configuration -- including JSON security policies, attack signatures, threat campaigns, and log profiles -- into a single binary in `.tgz` format. This bundle is then pushed out to each selected NGINX App Protect WAF instance. -NGINX Instance Manager includes a compiler that packages your complete WAF configuration β€” security policies, attack signatures, threat campaigns, and log profiles β€” into a single `.tgz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances. +Performing the security bundle compilation on Instance Manager (precompiled publication) instead of on the NGINX App Protect WAF instances provides the following benefits: -**Why precompile with NGINX Instance Manager?** +- Eliminates the need to provision system resources on NGINX App Protect WAF instances to perform compilation. +- The bundles produced by Instance Manager can be reused by multiple NGINX App Protect WAF instances, instead of each instance having to perform the compilation separately. -- Saves system resources on WAF instances -- Lets you reuse the same bundle across multiple instances +However, if you prefer to maintain policy compilation on the NGINX App Protect WAF instance, that is supported with the following limitation: -If you choose to compile policies on the WAF instance instead, that works tooβ€”but with this limitation: +- Instance Manager does not publish JSON policies to the NGINX App Protect WAF instance. JSON policies referenced in an NGINX configuration must already exist on the NGINX App Protect WAF instance. -- NGINX Instance Manager won’t publish `.json` policies to the WAF instance. These policies must already exist on the instance and be referenced in the NGINX config. +The example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) context below enables NGINX App Protect WAF and tells NGINX where to find the compiled security bundle: -Example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) block to enable WAF and point to the bundle: +## Log Profile Compilation -```nginx -location / { - app_protect_enable on; - app_protect_policy_file /etc/app_protect/policies/policy_bundle.tgz; -} -``` - -## Log profile compilation - -You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). +Instance Manager can also be configured to compile log profiles when you install a new version of the WAF compiler. When you publish an NGINX configuration with the NGINX App Protect [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, Instance Manager publishes the compiled log profiles to the NGINX App Protect WAF instances when precompiled publication is enabled. {{}} -NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`. +Instance Manager and Security Monitoring both use NGINX App Protect log profiles. The configuration requirements for each are different. When using Instance Manager configuration management, you must reference the log profile in your NGINX configuration using the `.tgz` file extension instead of `.json`. {{}} -## Security management APIs +## Security Management APIs -Use the NGINX Instance Manager REST API to automate updates across your NGINX App Protect WAF instances. You can use the API to manage: +By using the Instance Manager REST API, you can automate configuration updates to be pushed out to all of your NGINX App Protect WAF instances. You can use the Instance Manager API to manage and deploy the following security configurations: -- Security policies -- Log profiles -- Attack signatures -- Threat campaigns +- security policies, +- log profiles, +- attack signatures, and +- threat campaigns. -Just like with the web interface, the compiler creates a binary bundle with your updates that you can push to your WAF instances. +Just as with changes made via the user interface, the Instance Manager compiler bundles all of the config updates into a single binary package that you can push out to your instances. Figure 2 shows an overview of the API endpoints available to support security policy configuration and publishing. -{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Instance Manager with NGINX App Protect WAF architecture overview" alt="Diagram showing how the NGINX Instance Manager REST API is used to create policies, upload signatures and campaigns, and publish compiled security bundles to NGINX App Protect WAF instances">}} +{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Management Suite with NGINX App Protect WAF Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution">}} -For full details, see the API documentation: +More information is available in the Instance Manager API documentation. {{< include "nim/how-to-access-api-docs.md" >}} diff --git a/content/nim/nginx-app-protect/waf-config-management.md b/content/nim/nginx-app-protect/waf-config-management.md new file mode 100644 index 000000000..5e76684d4 --- /dev/null +++ b/content/nim/nginx-app-protect/waf-config-management.md @@ -0,0 +1,30 @@ +--- +description: Learn how to use NGINX Management Suite Instance Manager to publish NGINX + App Protect WAF configurations. +docs: DOCS-1114 +title: WAF Configuration Management +toc: true +weight: 100 +--- + +## Overview + +You can use NGINX Management Suite Instance Manager to publish configurations to your NGINX App Protect WAF data plane instances. + +## Publish WAF Configurations + +1. Set up your NGINX Management Suite Instance Manager instance: + + - [Install the WAF Compiler]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#install-the-waf-compiler" >}}) + + - [Set up the Attack Signatures and Threat Campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#set-up-attack-signatures-and-threat-campaigns" >}}) + +2. In Instance Manager, [onboard the App Protect Instances]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#onboard-nginx-app-protect-waf-instances" >}}) you want to publish policies and log profiles to. + +3. [Create the security policies]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-policy" >}}). + +4. [Create the security log profiles]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-log-profile" >}}). + +5. [Add or edit a WAF Configuration]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to your NGINX Instances, and publish using Instance Manager. + + {{}}Map the App Protect directives on NGINX configuration to `.tgz` file extensions (not `.json`).{{< /note >}} diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index d9e123c6f..e5ecaf984 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -31,6 +31,33 @@

    {{ .Title }}

    + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX fleet")}} +

    Use the F5 NGINX One Console to deploy, scale, or migrate your apps

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}} +

    See benefits from the NGINX One Console

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} +

    Manage your work-in-progress

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your NGINX instances")}} +

    Keep an inventory of your deployments

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} +

    Update them before they expire

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}} +

    Secure your systems with role-based access control

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize in groups")}} +

    Configure and synchronize groups of NGINX instances simultaneously

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} +

    Automate NGINX fleet management

    + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}} +

    Terms unique to NGINX One Console

    + {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "How-to guides") }}
      {{ range .Pages }} @@ -43,6 +70,7 @@

    {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "API")}} +

    These are API docs

      {{ range .Pages }}
    • {{ .Title }}
      • @@ -96,4 +124,4 @@

      {{end}} - \ No newline at end of file + From 07c640686ad29a960d30b94c63ef80473ed0f814 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:31:10 -0700 Subject: [PATCH 30/63] Less --- .../waf-config-management.md | 30 ------------------- 1 file changed, 30 deletions(-) delete mode 100644 content/nim/nginx-app-protect/waf-config-management.md diff --git a/content/nim/nginx-app-protect/waf-config-management.md b/content/nim/nginx-app-protect/waf-config-management.md deleted file mode 100644 index 5e76684d4..000000000 --- a/content/nim/nginx-app-protect/waf-config-management.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: Learn how to use NGINX Management Suite Instance Manager to publish NGINX - App Protect WAF configurations. -docs: DOCS-1114 -title: WAF Configuration Management -toc: true -weight: 100 ---- - -## Overview - -You can use NGINX Management Suite Instance Manager to publish configurations to your NGINX App Protect WAF data plane instances. - -## Publish WAF Configurations - -1. Set up your NGINX Management Suite Instance Manager instance: - - - [Install the WAF Compiler]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#install-the-waf-compiler" >}}) - - - [Set up the Attack Signatures and Threat Campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#set-up-attack-signatures-and-threat-campaigns" >}}) - -2. In Instance Manager, [onboard the App Protect Instances]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#onboard-nginx-app-protect-waf-instances" >}}) you want to publish policies and log profiles to. - -3. [Create the security policies]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-policy" >}}). - -4. [Create the security log profiles]({{< ref "/nim/nginx-app-protect/manage-waf-security-policies#create-security-log-profile" >}}). - -5. [Add or edit a WAF Configuration]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to your NGINX Instances, and publish using Instance Manager. - - {{}}Map the App Protect directives on NGINX configuration to `.tgz` file extensions (not `.json`).{{< /note >}} From a9a6c5fd4229af0cb737cd77463b8cfa8a2f0c36 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 10:45:08 -0700 Subject: [PATCH 31/63] More --- .../nginx-one/config-sync-groups/_index.md | 2 +- .../nginx-one/how-to/certificates/_index.md | 6 - .../certificates/manage-certificates.md | 197 ------------- .../how-to/config-sync-groups/_index.md | 6 - .../how-to/config-sync-groups/add-file-csg.md | 67 ----- .../manage-config-sync-groups.md | 267 ------------------ .../nginx-one/how-to/nginx-configs/_index.md | 6 - .../how-to/nginx-configs/add-file.md | 67 ----- .../how-to/nginx-configs/add-instance.md | 75 ----- .../clean-up-unavailable-instances.md | 40 --- .../manage-config-sync-groups.md | 239 ---------------- .../view-edit-nginx-configurations.md | 41 --- .../nginx-one/how-to/staged-configs/_index.md | 6 - .../staged-configs/add-staged-config.md | 88 ------ .../staged-configs/api-staged-config.md | 29 -- .../staged-configs/edit-staged-config.md | 38 --- content/nginx-one/nginx-configs/_index.md | 2 +- layouts/partials/list-main.html | 4 +- 18 files changed, 4 insertions(+), 1176 deletions(-) delete mode 100644 content/nginx-one/how-to/certificates/_index.md delete mode 100644 content/nginx-one/how-to/certificates/manage-certificates.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/_index.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/add-file-csg.md delete mode 100644 content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md delete mode 100644 content/nginx-one/how-to/nginx-configs/_index.md delete mode 100644 content/nginx-one/how-to/nginx-configs/add-file.md delete mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md delete mode 100644 content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md delete mode 100644 content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md delete mode 100644 content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md delete mode 100644 content/nginx-one/how-to/staged-configs/_index.md delete mode 100644 content/nginx-one/how-to/staged-configs/add-staged-config.md delete mode 100644 content/nginx-one/how-to/staged-configs/api-staged-config.md delete mode 100644 content/nginx-one/how-to/staged-configs/edit-staged-config.md diff --git a/content/nginx-one/config-sync-groups/_index.md b/content/nginx-one/config-sync-groups/_index.md index db1ee5560..eaefeaea3 100644 --- a/content/nginx-one/config-sync-groups/_index.md +++ b/content/nginx-one/config-sync-groups/_index.md @@ -1,6 +1,6 @@ --- description: -title: Organize in groups +title: Change multiple instances with one push weight: 400 url: /nginx-one/config-sync-groups --- diff --git a/content/nginx-one/how-to/certificates/_index.md b/content/nginx-one/how-to/certificates/_index.md deleted file mode 100644 index 39e16a174..000000000 --- a/content/nginx-one/how-to/certificates/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Certificates -weight: 400 -url: /nginx-one/how-to/certificates ---- diff --git a/content/nginx-one/how-to/certificates/manage-certificates.md b/content/nginx-one/how-to/certificates/manage-certificates.md deleted file mode 100644 index 07a4f56e2..000000000 --- a/content/nginx-one/how-to/certificates/manage-certificates.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -docs: null -title: Manage certificates -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how you can manage SSL/TLS certificates with the F5 NGINX One Console. Valid certificates support encrypted connections between NGINX and your users. - -You may have separate sets of SSL/TLS certificates, as described in the following table: - -{{}} -| Functionality | Typical file names | Notes | -|-------------------|--------------------------------------------------------------------|----------------------------------------------------------------------------------------| -| Website traffic | /etc/nginx/ssl/example.com.crt
      /etc/nginx/ssl/example.com.key | Typically purchased from a Certificate Authority (CA) | -| Repository access | /etc/ssl/nginx/nginx-repo.crt
      /etc/ssl/nginx/nginx-repo.key | Supports access to repositories to download and install NGINX packages | -| NGINX Licensing | /etc/ssl/nginx/server.crt
      /etc/ssl/nginx/server.key | Supports access to repositories. Based on licenses downloaded from https://my.f5.com/ | -{{      }} - -Allowed directories depend on the [NGINX Agent]({{< ref "/nginx-one/getting-started/#install-nginx-agent" >}}). Look for the `/etc/nginx-agent/nginx-agent.conf` file. -Find the `config_dirs` parameter in that file, as described in the NGINX Agent [Basic configuration](https://docs.nginx.com/nginx-agent/configuration/configuration-overview/#cli-flags--environment-variables). -You may need to add a directory like `/etc/ssl` to that parameter. - -From the NGINX One Console you can: - -- Monitor all certificates configured for use by your connected NGINX Instances. -- Ensure that your certificates are current and correct. -- Manage your certificates from a central location. This can help you simplify operations and remotely update, rotate, and deploy those certificates. - -You can manage the certificates for: - -- [Unique instances]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) -- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) - - -{{< tip >}} - -If you are managing the certificate from NGINX One Console, we recommend that you avoid directly manipulating the files on the data plane. - -{{< /tip >}} - -## Before you start - -Before you add and manage certificates with the NGINX One Console make sure: - -- You have access to the NGINX One Console -- You have access through the F5 Distributed Cloud role, as described in the [Authentication]({{< ref "/nginx-one/api/authentication.md" >}}) guide, to manage SSL/TLS certificates - - You have the `f5xc-nginx-one-user` role for your account -- Your SSL/TLS certificates and keys match - -### SSL/TLS certificates and more - -NGINX One Console supports certificates for access to repositories. You may need a copy of these files from your Certificate Authority (CA) to upload them to NGINX One Console: - -- SSL Certificate - - Example file extensions: .crt, .pem -- Privacy certificate - - Example file extensions: .key, .pem - -The NGINX One Console allows you to upload these certificates as text and as files. You can also upload your own certificate files (with file extensions such as .crt and .key). - -Make sure your certificates, keys, and pem files are encrypted to one of the following standards: - -- RSA -- ECC/ECDSA - -In other words, any private key of this type should be supported, regardless of the curve types or hashing algorithm. - -For exmaple, if you use ECDSA private keys in PEM format, the PEM headers should contain: - -``` ------BEGIN EC PRIVATE KEY----- - ------END EC PRIVATE KEY----- - -``` - -If you use one of these keys, the US National Institute of Standards and Technology, in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf), recommends a key size of at least -2048 bits. It also has recommnedations for ECDSA. - -### Include certificates in NGINX configuration - -For NGINX configuration, these files are typically associated with the following NGINX directives: - -- [`ssl_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate) -- [`ssl_certificate_key`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_certificate_key) -- [`ssl_trusted_certificate`](https://nginx.org/en/docs/stream/ngx_stream_ssl_module.html#ssl_trusted_certificate) -- [`ssl_client_certificate`](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_client_certificate) -- [`proxy_ssl_certificate`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate) -- [`proxy_ssl_certificate_key`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ssl_certificate_key) - -## Important considerations - -Most websites include valid information from public keys and certificates or CA bundles. However, the NGINX One Console accepts, but provides warnings for these use cases: - -- When the public certificate is expired -- When the leaf certificate part of a certificate chain is expired -- When any of the components of a CA bundle are expired -- When the public key does not match the private certificate - -In such cases, you may get websites that present "Your connection is not private" warning messages in client web browsers. - -## Review existing certificates - -Follow these steps to review existing certificates for your instances. - -On the left-hand pane, select **Certificates**. In the window that appears, you see: - -{{}} -| Term | Definition | -|-------------|-------------| -| **Total** | Total number of certificates available to NGINX One Console | -| **Valid (31+ days)** | Number of certificates that expire in 31 or more days | -| **Expires Soon (<31 days)** | Number of certificates that expire in less than 31 days | -| **Expired** | Number of exprired certificates | -| **Not Ready** | Certificates with a start date in the future | -| **Managed** | Managed by and stored in the NGINX One Console | -| **Unmanaged** | Detected by, and not managed by NGINX One Console. To convert to managed, you may need to upload the certificate and key during the process. | -{{}} - -You can **Add Filter** to filter certificates by: - -- Name -- Status -- Subject Name -- Type - -The Export option supports exports of basic certification file information to a CSV file. It does _not_ include the content of the public certificate or the private key. - -## Add a new certificate or bundle - -To add a new certificate, select **Add Certificate**. - - -In the screen that appears, you can add a certificate name. If you don't add a name, NGINX One will add a name for you, based on the expiration date for the certificate. - -You can add certificates in the following formats: - -- **SSL Certificate and Key** -- **CA Certificate Bundle** - -In each case, you can upload files directly, or enter the content of the certificates in a text box. Once you upload these certificates, you'll see: - -- **Certificate Details**, with the Subject Name, start and end dates. -- **Key Details**, with the encryption key size and algorithm, such as RSA - - -## Edit an existing certificate or bundle - -You can modify existing certificates from the **Certificates** screen. Select the certificate of your choice. Depending on the type of certificate, you'll then see either a **Edit Certificate** or **Edit CA Bundle** option. The NGINX One Console then presents a window with the same options as shown when you [Add a new certificate](#add-a-new-certificate-or-bundle). - -If that certificate is already managed as part of a Config Sync Group, the changes you make affect all instances in that group. - -## Remove a deployed certificate - -You can remove a deployed certificate from an independent instance or from a Config Sync Group. This will remove the certificate's association with the instance or group, but it does not delete the certificate files from the instance(s). - -Every instance with a deployed certificate includes paths to certificates in their configuration files. If you remove the deployed file path to one certificate, that change is limited to that one instance. - -Every Config Sync Group also includes paths to certificates in its configuration files. If you remove the deployed path to one certificate, that change affects all instances which belong to that Config Sync Group. - -## Delete a deployed certificate - -To delete a certificate, find the name in the **Certificates** screen. Find the **Actions** column associated with the certificate. Select the ellipsis (`...`) and then select **Delete**. Before deleting that certificate, you should see a warning. - -If that certificate is managed and is part of a Config Sync Group, that change affects all instances in that group. - -{{< warning >}} Be cautious if you want to delete certificates that are being used by an instance or a Config Sync Group. Deleting such certificates leads to failure in affected NGINX deployments. {{< /warning >}} - -## Managed and unmanaged certificates - -If you register an instance to NGINX One Console, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), and the associated SSL/TLS certificates: - -- Are used in their NGINX configuration -- Do _not_ match an existing managed SSL certificate/CA bundle - -These certificates appear in the list of unmanaged certificates. - -We recommend that you convert your unmanaged certificates. Converting to a managed certificate allows you to centrally manage, update, and deploy a certificate to your data plane from the NGINX One Console. - -To convert these cerificates to managed, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - - - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Add a file in a configuration]({{< ref "/nginx-one/how-to/nginx-configs/add-file.md" >}}) diff --git a/content/nginx-one/how-to/config-sync-groups/_index.md b/content/nginx-one/how-to/config-sync-groups/_index.md deleted file mode 100644 index 31f258b69..000000000 --- a/content/nginx-one/how-to/config-sync-groups/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Config Sync Groups -weight: 250 -url: /nginx-one/how-to/config-sync-groups ---- diff --git a/content/nginx-one/how-to/config-sync-groups/add-file-csg.md b/content/nginx-one/how-to/config-sync-groups/add-file-csg.md deleted file mode 100644 index ad8d31ca0..000000000 --- a/content/nginx-one/how-to/config-sync-groups/add-file-csg.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -docs: null -title: Add a file to a Config Sync Group -toc: true -weight: 400 -type: -- how-to ---- - -## Overview - -{{< include "nginx-one/add-file/overview.md" >}} - -## Before you start - -Before you add files in your configuration, ensure: - -- You have access to the NGINX One Console. -- Config Sync Groups are properly registered with NGINX One Console - -## Important considerations - -This page applies when you want to add a file to a Config Sync Group. Any changes you make here apply to all [Instances]({{< ref "/nginx-one/glossary.md" >}}) of that Config Sync Group. - -## Add a file - -You can use the NGINX One Console to add a file to a specific Config Sync Group. To do so: - -1. Select the Config Sync Group to manage. -1. Select the **Configuration** tab. - - {{< tip >}} - - {{< include "nginx-one/add-file/edit-config-tip.md" >}} - - {{< /tip >}} - -1. Select **Edit Configuration**. -1. In the **Edit Configuration** window that appears, select **Add File**. - -You now have multiple options, described in the sections which follow. - -### New Configuration File - -Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. - -### New SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} - - {{< tip >}} - - Make sure to specify the path to your certificate in your NGINX configuration, - with the `ssl_certificate` and `ssl_certificate_key` directives. - - {{< /tip >}} - -### Existing SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md deleted file mode 100644 index eb5bf8251..000000000 --- a/content/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md +++ /dev/null @@ -1,267 +0,0 @@ ---- -docs: null -title: Manage Config Sync Groups -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -If you work with several instances of NGINX, it can help to organize these instances in Config Sync Groups. Each instance in a Config Sync Group has the same configuration. - -This guide explains how to create and manage Config Sync Groups in the F5 NGINX One Console. Config Sync Groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. - -If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find Config Sync Groups in NGINX One similar, though the steps and terminology differ slightly. - -Config Sync Groups are functionally different from syncing instances in a cluster. They let you to manage and synchronize configurations across multiple NGINX instances, all at once. - -This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While Config Sync Groups focus on configuration management, cluster syncing supports failover and data consistency. - -## Before you start - -Before you create and manage Config Sync Groups, ensure: - -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage Config Sync Groups. -- If you plan to add existing instances to a Config Sync Group, make sure those NGINX instances are properly registered with NGINX One. - -## Configuration management - -Config Sync Groups support configuration inheritance and persistance. If you've just created a Config Sync Group, you can define the configuration for that group in the following ways: - -- Before adding an instance to a group, you can [Define the Config Sync Group configuration manually](#define-the-config-sync-group-configuration-manually). -- When you add the first instance to a group, that instance defines the configuration for that Config Sync Group. -- Afterwards, you can modify the configuration of the Config Sync Group. That modifies the configuration of all member instances. Future members of that group inherit that modified configuration. - -On the other hand, if you remove all instances from a Config Sync Group, the original configuration persists. In other words, the group retains the configuration from that first instance (or the original configuration). Any new instance that you add later still inherits that configuration. - -{{< tip >}}You can use _unmanaged_ certificates. Your actions can affect the [Config Sync Group status](#config-sync-group-status). For future instances on the data plane, if it: - -- Has unmanaged certificates in the same file paths as defined by the NGINX configuration as the Config Sync Group, that instance will be [**In Sync**](#config-sync-group-status). -- Will be [**Out of Sync**](#config-sync-group-status) if the instance: - - Does not have unmanaged certificates in the same file paths - - Has unmanaged certificates in a different directory from the Config Sync Group -{{< /tip >}} - -### Risk when adding multiple instances to a Config Sync Group - -If you add multiple instances to a single Config Sync Group, simultaneously (with automation), there's a risk that the instance selects a random configuration. To prevent this problem, you should: - -1. Create a Config Sync Group. -1. Add a configuration to the Config Sync Group, so all instances inherit it. -1. Add the instances in a separate operation. - -Your instances should synchronize with your desired configuration within 30 seconds. - -### Use an instance to define the Config Sync Group configuration - -1. Follow the steps in the [**Add an existing instance to a Config Sync Group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a Config Sync Group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. -2. The NGINX configuration from this instance will automatically become the group's configuration. -3. You can further edit and publish this configuration by following the steps in the [**Publish the Config Sync Group configuration**](#publish-the-config-sync-group-configuration) section. - -### Define the Config Sync Group configuration manually - -You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. - -To manually set the group configuration: - -1. Follow steps 1–4 in the [**Create a Config Sync Group**](#create-a-config-sync-group) section to create your Config Sync Group. -2. After creating the group, select the **Configuration** tab. -3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. -4. To add a configuration, select **Edit Configuration**. -5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. -6. After making your changes, select **Next** to view a split screen showing your changes. -7. If you're satisfied with the configuration, select **Save and Publish**. - -## Important considerations - -When you plan Config Sync Groups, consider the following factors: - -- **Single Config Sync Group membership**: You can add an instance to only one Config Sync Group. - -- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified Config Sync Group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. - -- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same Config Sync Group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. - -## Create a Config Sync Group - -When you create a Config Sync Group, you can manage the configurations of multiple NGINX instances as a single entity. - -1. On the left menu, select **Config Sync Groups**. -2. Select **Add Config Sync Group**. -3. In the **Name** field, type a name for your Config Sync Group. -4. Select **Create** to add the Config Sync Group. - -## Manage Config Sync Group membership - -Now that you created a Config Sync Group, you can add instances to that group. As described in [Configuration management](#configuration-management), the first instance you add to a group, when you add it, defines the initial configuration for the group. You can update the configuration for the entire Config Sync Group. - -Any instance that joins the group afterwards inherits that configuration. - -{{< note >}} If you see the following [Config Sync Group Status](#config-sync-group-status) message: **Out of Sync**: - - - Review the instance details in NGINX One Console to identify any publication problems. - - After you change the configuration of the Config Sync Group, [Publish it](#publish-the-config-sync-group-configuration]. -In that case, review and resolve discrepancies between the Instance and the rest of the Config Sync Group. {{< /note >}} - -### Add an existing instance to a Config Sync Group {#add-an-existing-instance-to-a-config-sync-group} - -You can add existing NGINX instances that are already registered with NGINX One to a Config Sync Group. - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. At the end of the file, add a new line beginning with `instance_group:`, followed by the Config Sync Group name. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent: - - ``` shell - sudo systemctl restart nginx-agent - ``` - -### Add a new instance to a Config Sync Group {#add-a-new-instance-to-a-config-sync-group} - -When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. - -1. On the left menu, select **Config Sync Groups**. -2. Select the Config Sync Group in the list. -3. In the **Instances** pane, select **Add Instance to Config Sync Group**. -4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to Config Sync Group**. -5. Select **Next**. -6. **Generate a new data plane key** (choose this option if you don't have an existing key): - - - Select **Generate new key** to create a new data plane key for the instance. - - Select **Generate Data Plane Key**. - - Copy and securely store the generated key, as it is displayed only once. - -7. **Use an existing data plane key** (choose this option if you already have a key): - - - Select **Use existing key**. - - In the **Data Plane Key** field, enter the existing data plane key. - -{{}} - -{{%tab name="Virtual Machine or Bare Metal"%}} - -8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. -9. Select **Done** to complete the process. - -{{%/tab%}} - -{{%tab name="Docker Container"%}} - -8. **Log in to the NGINX private registry**: - - - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) license from [MyF5](https://my.f5.com/manage/s/). - - ```shell - sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none - ``` - -9. **Pull the Docker image**: - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - -10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. - -11. Select **Done** to complete the process. - -{{%/tab%}} - -{{}} - -{{}} - -Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. - -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). - -{{}} - -### Move an instance to a different Config Sync Group - -If you need to move an NGINX instance to a different Config Sync Group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and change it to the name of the new Config Sync Group. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent by running the following command: - - ```shell - sudo systemctl restart nginx-agent - ``` - -If you move an instance with certificates from one Config Sync Group to another, NGINX One adds or removes those certificates from the data plane, to synchronize with the deployed certificates of the group. - -### Remove an instance from a Config Sync Group - -If you need to remove an NGINX instance from a Config Sync Group without adding it to another group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. - - ```text - # instance_group: - ``` - -4. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -By removing or commenting out this line, the instance will no longer be associated with any Config Sync Group. - -## Publish the Config Sync Group configuration {#publish-the-config-sync-group-configuration} - -After the Config Sync Group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. - -1. On the left menu, select **Config Sync Groups**. -2. Select the Config Sync Group in the list. -3. Select the **Configuration** tab to view the group's NGINX configuration. -4. To modify the group's configuration, select **Edit Configuration**. -5. Make the necessary changes to the configuration. -6. When you're finished, select **Next**. A split view displays the changes. -7. If you're satisfied with the changes, select **Save and Publish**. - -Publishing the group configuration ensures that all instances within the Config Sync Group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. - -## Config Sync Group status - -The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. - -{{}} -| **Status** | **Description** | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| **In Sync** | All instances within the Config Sync Group have configurations that match the group configuration. No action is required. | -| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | -| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | -| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | -{{}} - -Monitor the **Config Sync Status** column. It can help you ensure that your configurations are consistently applied across all instances in a group. - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/_index.md b/content/nginx-one/how-to/nginx-configs/_index.md deleted file mode 100644 index b7fa815da..000000000 --- a/content/nginx-one/how-to/nginx-configs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Instances and Configurations -weight: 200 -url: /nginx-one/how-to/nginx ---- diff --git a/content/nginx-one/how-to/nginx-configs/add-file.md b/content/nginx-one/how-to/nginx-configs/add-file.md deleted file mode 100644 index 7b654d86e..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-file.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -docs: null -title: Add a file to an instance -toc: true -weight: 400 -type: -- how-to ---- - -## Overview - -{{< include "nginx-one/add-file/overview.md" >}} - -## Before you start - -Before you add files in your configuration, ensure: - -- You have access to the NGINX One Console. -- NGINX instances are properly registered with NGINX One Console - -## Important considerations - -If your instance is a member of a Config Sync Group, changes that you make may be synchronized to other instances in that group. -For more information, see how you can [Manage Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}). - -## Add a file - -You can use the NGINX One Console to add a file to a specific instance. To do so: - -1. Select the instance to manage. -1. Select the **Configuration** tab. - - {{< tip >}} - - {{< include "nginx-one/add-file/edit-config-tip.md" >}} - - {{< /tip >}} - -1. Select **Edit Configuration**. -1. In the **Edit Configuration** window that appears, select **Add File**. - -You now have multiple options, described in the sections which follow. - -### New Configuration File - -Enter the name of the desired configuration file, such as `abc.conf` and select **Add**. The configuration file appears in the **Edit Configuration** window. - -### New SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/new-ssl-bundle.md" >}} - - {{< tip >}} - - Make sure to specify the path to your certificate in your NGINX configuration, - with the `ssl_certificate` and `ssl_certificate_key` directives. - - {{< /tip >}} - -### Existing SSL Certificate or CA Bundle - -{{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md deleted file mode 100644 index 884df0c15..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: '' -title: Add an NGINX instance -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need -to set up a data plane key to connect your instances to NGINX One. - -## Before you start - -Before you add an instance to NGINX One Console, ensure: - -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} - -## Add an instance - -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. - -## Managed and Unmanaged Certificates - -If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. - -### If the certificate is already managed - -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. - -NGINX One Console can manage your instances along with those certificates. - -### If the certificate is not managed - -These certificates appear in the list of **Unmanaged Certificates**. - -To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. - -To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - -Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. - -## Add an instance to a Config Sync Group - -When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md deleted file mode 100644 index 6a119617d..000000000 --- a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: '' -docs: null -title: Clean up unavailable NGINX instances -toc: true -weight: 200 -type: -- how-to ---- - -## Overview - -This guide explains how to set up automatic cleanup for NGINX instances in NGINX One. The cleanup process removes instances that have been unavailable for a specified duration. By default, this period is 24 hours from the time the NGINX instance was last updated. Administrators can change or disable the cleanup duration in **Settings > Instance Settings**. Events will be generated for NGINX instances that have been automatically cleaned up; you can see these events on the **Overview > Events** page. - -## Before you start - -Before you set up automatic cleanup for NGINX instances, ensure: - -- You have administrator access to NGINX One. -- You understand that this action will delete instances permanently after they are unavailable for the specified duration. - -## Configure instance cleanup - -Follow these steps to set up automatic cleanup for NGINX instances in NGINX One: - -1. On the left menu, select **Instance Settings**. -1. On the **Instance Settings** page, in the **Unavailable Instance Cleanup** section, select **Edit Duration**. -1. Choose the cleanup duration. - - Select one of the predefined durations (None, 1 day, 7 days, 30 days) or set a custom duration. Selecting **None** disables automatic cleanup. - - If you choose **Custom**, enter the duration in hours or days. -1. Select **Save** to apply the changes. - -## Event log details - -When instances are cleaned up automatically, an event log entry is created. You can find these events on the **Overview > Events** page. The event log includes the following details: - -- **Impacted Object ID**: The unique identifier of the NGINX instance that was cleaned up. -- **Type**: The type of event, which will be "Automated Object Cleanup". -- **Timestamp**: The date and time when the instance was cleaned up. -- **Message**: A description indicating that the instance was unavailable for the configured duration before being cleaned up. diff --git a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md deleted file mode 100644 index 8bc10cce6..000000000 --- a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md +++ /dev/null @@ -1,239 +0,0 @@ ---- -docs: null -title: Manage config sync groups -toc: true -weight: 300 -type: -- how-to ---- - -## Overview - -This guide explains how to create and manage config sync groups in the F5 NGINX One Console. Config sync groups synchronize NGINX configurations across multiple NGINX instances, ensuring consistency and ease of management. - -If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx-instances/manage-instance-groups.md" >}}), you’ll find config sync groups in NGINX One similar, though the steps and terminology differ slightly. - -## Before you start - -Before you create and manage config sync groups, ensure: - -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage config sync groups. -- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. - -## Important considerations - -- **NGINX Agent configuration file location**: When you run the NGINX Agent installation script to register an instance with NGINX One, the script creates the `agent-dynamic.conf` file, which contains settings for the NGINX Agent, including the specified config sync group. This file is typically located in `/var/lib/nginx-agent/` on most systems; however, on FreeBSD, it's located at `/var/db/nginx-agent/`. - -- **Mixing NGINX Open Source and NGINX Plus instances**: You can add both NGINX Open Source and NGINX Plus instances to the same config sync group, but there are limitations. If your configuration includes features exclusive to NGINX Plus, synchronization will fail on NGINX Open Source instances because they don't support these features. NGINX One allows you to mix NGINX instance types for flexibility, but it’s important to ensure that the configurations you're applying are compatible with all instances in the group. - -- **Single config sync group membership**: An instance can join only one config sync group at a time. - -- **Configuration inheritance**: If the config sync group already has a configuration defined, that configuration will be pushed to instances when they join. - -- **Using an instance's configuration for the group configuration**: If an instance is the first to join a config sync group and the group's configuration hasn't been defined, the instance’s configuration will become the group’s configuration. Any instances added later will automatically inherit this configuration. - - {{< note >}} If you add multiple instances to a single config sync group, simultaneously (with automation), follow these steps. Your instances will inherit your desired configuration: - - 1. Create a config sync group. - 1. Add a configuration to the config sync group, so all instances inherit it. - 1. Add the instances in a separate operation. - - Your instances should synchronize with your desired configuration within 30 seconds. {{< /note >}} - -- **Persistence of a config sync group's configuration**: The configuration for a config sync group persists until you delete the group. Even if you remove all instances, the group's configuration stays intact. Any new instances that join later will automatically inherit this configuration. - -- **Config sync groups vs. cluster syncing**: Config sync groups are not the same as cluster syncing. Config sync groups let you to manage and synchronize configurations across multiple NGINX instances as a single entity. This is particularly useful when your NGINX instances are load-balanced by an external load balancer, as it ensures consistency across all instances. In contrast, cluster syncing, like [zone syncing]({{< ref "nginx/admin-guide/high-availability/zone_sync_details.md" >}}), ensures data consistency and high availability across NGINX instances in a cluster. While config sync groups focus on configuration management, cluster syncing supports failover and data consistency. - -## Create a config sync group - -Creating a config sync group allows you to manage the configurations of multiple NGINX instances as a single entity. - -1. On the left menu, select **Config Sync Groups**. -2. Select **Add Config Sync Group**. -3. In the **Name** field, type a name for your config sync group. -4. Select **Create** to add the config sync group. - -## Manage config sync group membership - -### Add an existing instance to a config sync group {#add-an-existing-instance-to-a-config-sync-group} - -You can add existing NGINX instances that are already registered with NGINX One to a config sync group. - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. At the end of the file, add a new line beginning with `instance_group:`, followed by the config sync group name. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent: - - ``` shell - sudo systemctl restart nginx-agent - ``` - -### Add a new instance to a config sync group {#add-a-new-instance-to-a-config-sync-group} - -When adding a new NGINX instance that is not yet registered with NGINX One, you need a data plane key to securely connect the instance. You can generate a new data plane key during the process or use an existing one if you already have it. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. In the **Instances** pane, select **Add Instance to Config Sync Group**. -4. In the **Add Instance to Config Sync Group** dialog, select **Register a new instance with NGINX One then add to config sync group**. -5. Select **Next**. -6. **Generate a new data plane key** (choose this option if you don't have an existing key): - - - Select **Generate new key** to create a new data plane key for the instance. - - Select **Generate Data Plane Key**. - - Copy and securely store the generated key, as it is displayed only once. - -7. **Use an existing data plane key** (choose this option if you already have a key): - - - Select **Use existing key**. - - In the **Data Plane Key** field, enter the existing data plane key. - -{{}} - -{{%tab name="Virtual Machine or Bare Metal"%}} - -8. Run the provided command, which includes the data plane key, in your NGINX instance terminal to register the instance with NGINX One. -9. Select **Done** to complete the process. - -{{%/tab%}} - -{{%tab name="Docker Container"%}} - -8. **Log in to the NGINX private registry**: - - - Replace `YOUR_JWT_HERE` with your JSON Web Token (JWT) from [MyF5](https://my.f5.com/manage/s/). - - ```shell - sudo docker login private-registry.nginx.com --username=YOUR_JWT_HERE --password=none - ``` - -9. **Pull the Docker image**: - - - From the **OS Type** list, choose the appropriate operating system for your Docker image. - - After selecting the OS, run the provided command to pull the Docker image. - - **Note**: Subject to availability, you can modify the `agent: ` to match the specific NGINX Plus version, OS type, and OS version you need. For example, you might use `agent: r32-ubi-9`. For more details on version tags and how to pull an image, see [Deploying NGINX and NGINX Plus on Docker]({{< ref "nginx/admin-guide/installing-nginx/installing-nginx-docker.md#pulling-the-image" >}}). - -10. Run the provided command, which includes the data plane key, in your NGINX instance terminal to start the Docker container. - -11. Select **Done** to complete the process. - -{{%/tab%}} - -{{}} - -{{}} - -Data plane keys are required for registering NGINX instances with the NGINX One Console. These keys serve as secure tokens, ensuring that only authorized instances can connect and communicate with NGINX One. - -For more details on creating and managing data plane keys, see [Create and manage data plane keys]({{}}). - -{{}} - -### Change the config sync group for an instance - -If you need to move an NGINX instance to a different config sync group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and change it to the name of the new config sync group. - - ``` text - instance_group: - ``` - -4. Restart NGINX Agent by running the following command: - - ```shell - sudo systemctl restart nginx-agent - ``` - -**Important:** If the instance is the first to join the new config sync group and a group configuration hasn’t been added manually beforehand, the instance’s configuration will automatically become the group’s configuration. Any instances added to this group later will inherit this configuration. - -### Remove an instance from a config sync group - -If you need to remove an NGINX instance from a config sync group without adding it to another group, follow these steps: - -1. Open a command-line terminal on the NGINX instance. -2. Open the `/var/lib/nginx-agent/agent-dynamic.conf` file in a text editor. -3. Locate the line that begins with `instance_group:` and either remove it or comment it out by adding a `#` at the beginning of the line. - - ```text - # instance_group: - ``` - -4. Restart NGINX Agent: - - ```shell - sudo systemctl restart nginx-agent - ``` - -By removing or commenting out this line, the instance will no longer be associated with any config sync group. - -## Add the config sync group configuration - -You can set the configuration for a config sync group in two ways: - -### Define the group configuration manually - -You can manually define the group's configuration before adding any instances. When you add instances to the group later, they automatically inherit this configuration. - -To manually set the group configuration: - -1. Follow steps 1–4 in the [**Create a config sync group**](#create-a-config-sync-group) section to create your config sync group. -2. After creating the group, select the **Configuration** tab. -3. Since no instances have been added, the **Configuration** tab will show an empty configuration with a message indicating that no config files exist yet. -4. To add a configuration, select **Edit Configuration**. -5. In the editor, define your NGINX configuration as needed. This might include adding or modifying `nginx.conf` or other related files. -6. After making your changes, select **Next** to view a split screen showing your changes. -7. If you're satisfied with the configuration, select **Save and Publish**. - -### Use an instance's configuration - -If you don't manually define a group config, the NGINX configuration of the first instance added to a config sync group becomes the group's configuration. Any additional instances added afterward inherit this group configuration. - -To set the group configuration by adding an instance: - -1. Follow the steps in the [**Add an existing instance to a config sync group**](#add-an-existing-instance-to-a-config-sync-group) or [**Add a new instance to a config sync group**](#add-a-new-instance-to-a-config-sync-group) sections to add your first instance to the group. -2. The NGINX configuration from this instance will automatically become the group's configuration. -3. You can further edit and publish this configuration by following the steps in the [**Publish the config sync group configuration**](#publish-the-config-sync-group-configuration) section. - -## Publish the config sync group configuration {#publish-the-config-sync-group-configuration} - -After the config sync group is created, you can modify and publish the group's configuration as needed. Any changes made to the group configuration will be applied to all instances within the group. - -1. On the left menu, select **Config Sync Groups**. -2. Select the config sync group in the list. -3. Select the **Configuration** tab to view the group's NGINX configuration. -4. To modify the group's configuration, select **Edit Configuration**. -5. Make the necessary changes to the configuration. -6. When you're finished, select **Next**. A split view displays the changes. -7. If you're satisfied with the changes, select **Save and Publish**. - -Publishing the group configuration ensures that all instances within the config sync group are synchronized with the latest group configuration. This helps maintain consistency across all instances in the group, preventing configuration drift. - -## Understanding config sync statuses - -The **Config Sync Status** column on the **Config Sync Groups** page provides insight into the synchronization state of your NGINX instances within each group. - -{{}} -| **Status** | **Description** | -|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| -| **In Sync** | All instances within the config sync group have configurations that match the group configuration. No action is required. | -| **Out of Sync** | At least one instance in the group has a configuration that differs from the group's configuration. You may need to review and resolve discrepancies to ensure consistency. | -| **Sync in Progress** | An instance is currently being synchronized with the group's configuration. This status appears when an instance is moved to a new group or when a configuration is being applied. | -| **Unknown** | The synchronization status of the instances in this group cannot be determined. This could be due to connectivity issues, instances being offline, or other factors. Investigating the cause of this status is recommended. | -{{}} - -Monitoring the **Config Sync Status** helps ensure that your configurations are consistently applied across all instances in a group, reducing the risk of configuration drift. - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md" >}}) diff --git a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md deleted file mode 100644 index 37d4fb6f5..000000000 --- a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: View and edit NGINX configurations -# Weights are assigned in increments of 100: determines sorting order -weight: 300 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: tutorial -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - - -## Overview - -This guide explains how to add a **Instances** to your NGINX One Console. - -## Before you start - -Before you add **Instances** to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions.``` - -Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. - -To view and edit an NGINX configuration, follow these steps: - -1. On the left menu, select **Instances**. -2. Select the instance you want to view the configuration for. -3. Select the **Configuration** tab to see the current configuration for the NGINX instance. -4. Select **Edit Configuration** to make changes to the current configuration. -5. Make your changes to the configuration files. The config analyzer will let you know if there are any errors. -6. When you are satisfied with the changes, select **Next**. -7. Compare and verify your changes before selecting **Save and Publish** to publish the edited configuration. - -Alternatively, you can select **Save Changes As**. In the window that appears, you can set up this instance as a [**Staged Configuration**]({{< ref "/nginx-one/how-to/staged-configs/_index.md" >}}). - -## See also - -- [Manage Config Sync Groups]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md" >}}) diff --git a/content/nginx-one/how-to/staged-configs/_index.md b/content/nginx-one/how-to/staged-configs/_index.md deleted file mode 100644 index 51e07d1aa..000000000 --- a/content/nginx-one/how-to/staged-configs/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -description: -title: Staged Configurations -weight: 800 -url: /nginx-one/how-to/staged-configs ---- diff --git a/content/nginx-one/how-to/staged-configs/add-staged-config.md b/content/nginx-one/how-to/staged-configs/add-staged-config.md deleted file mode 100644 index e69c0da78..000000000 --- a/content/nginx-one/how-to/staged-configs/add-staged-config.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: Add a Staged Configuration -# Weights are assigned in increments of 100: determines sorting order -weight: 100 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -nd-content-type: how-to -# Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit -nd-product: NGINX One ---- - -## Overview - -This guide explains how to add a Staged Configuration to your NGINX One Console. - -{{< include "nginx-one/staged-config-overview.md" >}} - -## Before you start - -Before you add a Staged Configuration to NGINX One Console, ensure: - -- You have an NGINX One Console account with staged configuration permissions. - -## Add a Staged Configuration - -You can add a Staged Configuration from: - -- Empty files -- An existing Instance -- An existing Config Sync Group -- An existing Staged Configuration - -To start the process from NGINX One Console, select **Manage > Staged Configurations**. Select **Add Staged Configuration**. - -The following sections start from the **Add Staged Configuration** window that appears. - -### Start from an empty file - -To start a new Staged Configuration: - -1. Select **New Configuration**. -1. Enter a name. -1. Select **Next**. - - You will see a new Staged Configuration with the default NGINX configuration file, `/etc/nginx/nginx.conf`, in edit mode. -1. Type or paste content for `/etc/nginx/nginx.conf`. -1. Select **Add File** to add the configuration, certificate, or other file(s) of your choice. -1. When you're done, select **Save**. - -### Start from an existing Instance - -To start from an existing Instance: - -1. Select **Existing Source**. -1. Enter a name for your new Staged Configuration. -1. Select **Instance**. -1. In the Choose Instance menu that appears, select an existing Instance. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Instance. You can now edit the configuration. When you're ready to stop and save your work, select Save. - -### Start from an existing Config Sync Group - -To start from an existing Config Sync Group: - -1. Select **Existing Source**. -1. Select **Config Sync Group**. -1. In the Choose Config Sync Group menu that appears, select an existing Config Sync Group. -1. Enter a name for your new Staged Configuration. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Config Sync Group. You can now edit the configuration. When you're ready to stop and save your work, select Save. - -### Start from an existing Staged Config - -To start from an existing Staged Config: - -1. Select **Existing Source**. -1. Select **Staged Configuration**. -1. In the Choose Staged Configuration menu that appears, select an existing Staged Configuration. -1. Enter a name for your new Staged Configuration. -1. Select **Next**. - -NGINX One Console imports the configuration from the existing Staged Configuration. You can now edit the configuration. When you're ready to stop and save your work, select Save. - diff --git a/content/nginx-one/how-to/staged-configs/api-staged-config.md b/content/nginx-one/how-to/staged-configs/api-staged-config.md deleted file mode 100644 index ff559d014..000000000 --- a/content/nginx-one/how-to/staged-configs/api-staged-config.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: Use the API to manage your Staged Configurations -# Weights are assigned in increments of 100: determines sorting order -weight: 500 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: how-to -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - -You can use F5 NGINX One Console API to manage your Staged Configurations. With our API, you can: - -- [Create an NGINX Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/createStagedConfig" >}}) - - Use details to add existing configuration files. -- [Get a list of existing Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/listStagedConfigs" >}}) - - Record the `object_id` of your target Staged Configuration for your analysis report. -- [Get an analysis report for an existing Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/getStagedConfigReport" >}}) - - Review the same recommendations found in the UI. -- [Export a Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/exportStagedConfig" >}}) - - Exports an existing Staged Configuration from the console. It sends you an archive of that configuration in `tar.gz` format. -- [Import a Staged Configuration]({{< ref "/nginx-one/api/api-reference-guide/#operation/importStagedConfig" >}}) - - Imports an existing Staged Configuration from your system and sends it to the console. This REST call assumes that your configuration is archived in `tar.gz` format. -- [Bulk manage multiple Staged Configurations]({{< ref "/nginx-one/api/api-reference-guide/#operation/bulkStagedConfigs" >}}) - - Allows you to delete multiple Staged Configurations. Requires each `object_id`. - - For several API endpoints, we ask for a `conf_path`. Make sure to set an absolute file path. If you make a REST call without an absolute file path, you'll see a 400 error message. diff --git a/content/nginx-one/how-to/staged-configs/edit-staged-config.md b/content/nginx-one/how-to/staged-configs/edit-staged-config.md deleted file mode 100644 index 8f101a0fd..000000000 --- a/content/nginx-one/how-to/staged-configs/edit-staged-config.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -# We use sentence case and present imperative tone -title: View and edit a Staged Configuration -# Weights are assigned in increments of 100: determines sorting order -weight: 200 -# Creates a table of contents and sidebar, useful for large documents -toc: true -# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this -type: tutorial -# Intended for internal catalogue and search, case sensitive: -product: NGINX One ---- - -## Overview - -This guide explains how to edit an existing Staged Configuration in your NGINX One Console. - -{{< include "nginx-one/staged-config-overview.md" >}} - -## Before you start - -Before you edit a Staged Configuration, ensure: - -- You have an NGINX One Console account with staged configuration permissions.``` - -## View and edit a Staged Configuration - - -Once you've registered your NGINX Staged Configs with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Staged Configurations** details page. - -To view and edit an NGINX configuration, follow these steps: - -1. On the left menu, select **Staged Configurations**. -1. Select the staged configuration you want to view or modify. -1. Select **Edit** to make changes to the current configuration. -1. Make your changes to the configuration files. The configuration analyzer will let you know if there are any errors. -1. When you are satisfied with the changes, select **Next**. -1. Compare and verify your changes before selecting **Save** to publish the edited Staged configuration. diff --git a/content/nginx-one/nginx-configs/_index.md b/content/nginx-one/nginx-configs/_index.md index d36819e7b..feffd5d05 100644 --- a/content/nginx-one/nginx-configs/_index.md +++ b/content/nginx-one/nginx-configs/_index.md @@ -1,6 +1,6 @@ --- description: -title: Organize your NGINX instances +title: Watch your NGINX instances weight: 300 url: /nginx-one/nginx-configs --- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index e5ecaf984..32f41efa0 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -40,7 +40,7 @@

      {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}}

      Manage your work-in-progress

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your NGINX instances")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

      Keep an inventory of your deployments

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} @@ -49,7 +49,7 @@

      {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

      Secure your systems with role-based access control

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize in groups")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}}

      Configure and synchronize groups of NGINX instances simultaneously

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} From 8e806e00ed815d9c6588e80bb4ef1690a1ae6932 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 11:11:59 -0700 Subject: [PATCH 32/63] update --- .../agent/installation/install-agent-api.md | 83 +- .../includes/nap-waf/build-nginx-image-cmd.md | 2 +- .../learn-about-deployment.md | 6 +- content/nap-waf/v4/admin-guide/install.md | 4 +- content/nap-waf/v5/admin-guide/compiler.md | 2 +- content/ngf/overview/custom-policies.md | 9 +- content/ngf/overview/product-telemetry.md | 3 +- .../load-balancer/tcp-udp-load-balancer.md | 40 +- .../load-balancer/udp-health-check.md | 160 +++- .../manage-waf-security-policies.md | 763 ++++++------------ .../overview-nap-waf-config-management.md | 72 +- 11 files changed, 519 insertions(+), 625 deletions(-) diff --git a/content/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 95a9650aa..15009d21f 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,74 +1,75 @@ -**Note**: To complete this step, make sure that `gpg` is installed on your system. You can install NGINX Agent using various command-line tools like `curl` or `wget`. If your NGINX Instance Manager host is not set up with valid TLS certificates, you can use the insecure flags provided by those tools. See the following examples: +--- +docs: DOCS-1031 +files: + - content/nim/nginx-app-protect/setup-waf-config-management.md +--- + +{{}}Make sure `gpg` is installed on your system before continuing. You can install NGINX Agent using command-line tools like `curl` or `wget`.{{}} + +If your NGINX Instance Manager host doesn't use valid TLS certificates, you can use the insecure flags to bypass verification. Here are some example commands: {{}} {{%tab name="curl"%}} -- Secure: +- **Secure:** ```bash - curl https:///install/nginx-agent | sudo sh + curl https:///install/nginx-agent | sudo sh ``` -- Insecure: +- **Insecure:** ```bash - curl --insecure https:///install/nginx-agent | sudo sh + curl --insecure https:///install/nginx-agent | sudo sh ``` - You can add your NGINX instance to an existing instance group or create one using `--instance-group` or `-g` flag when installing NGINX Agent. - - The following example shows how to download and run the script with the optional `--instance-group` flag adding the NGINX instance to the instance group **my-instance-group**: - - ```bash - curl https:///install/nginx-agent > install.sh; chmod u+x install.sh - sudo ./install.sh --instance-group my-instance-group - ``` +To add the instance to a specific instance group during installation, use the `--instance-group` (or `-g`) flag: - By default, the install script attempts to use a secure connection when downloading packages. If, however, the script cannot create a secure connection, it uses an insecure connection instead and logs the following warning message: +```shell +curl https:///install/nginx-agent -o install.sh +chmod u+x install.sh +sudo ./install.sh --instance-group +``` - ``` text - Warning: An insecure connection will be used during this nginx-agent installation - ``` +By default, the install script uses a secure connection to download packages. If it can’t establish one, it falls back to an insecure connection and logs this message: - To require a secure connection, you can set the optional flag `skip-verify` to `false`. +```text +Warning: An insecure connection will be used during this nginx-agent installation +``` - The following example shows how to download and run the script with an enforced secure connection: +To enforce a secure connection, set the `--skip-verify` flag to false: - ```bash - curl https:///install/nginx-agent > install.sh chmod u+x install.sh; chmod u+x install.sh - sudo sh ./install.sh --skip-verify false - ``` +```shell +curl https:///install/nginx-agent -o install.sh +chmod u+x install.sh +sudo ./install.sh --skip-verify false +``` {{%/tab%}} {{%tab name="wget"%}} +- **Secure:** -- Secure: - - ```bash - wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false + ```shell + wget https:///install/nginx-agent -O - | sudo sh -s --skip-verify false ``` -- Insecure: +- **Insecure:** - ```bash - wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh + ```shell + wget --no-check-certificate https:///install/nginx-agent -O - | sudo sh ``` - When you install the NGINX Agent, you can use the `--instance-group` or `-g` flag to add your NGINX instance to an existing instance group or to a new group that you specify. - - The following example downloads and runs the NGINX Agent install script with the optional `--instance-group` flag, adding the NGINX instance to the instance group **my-instance-group**: - - ```bash - wget https://gnms1.npi.f5net.com/install/nginx-agent -O install.sh ; chmod u+x install.sh - sudo ./install.sh --instance-group my-instance-group - ``` +To add your instance to a group during installation, use the `--instance-group` (or `-g`) flag: +```shell +wget https:///install/nginx-agent -O install.sh +chmod u+x install.sh +sudo ./install.sh --instance-group +``` {{%/tab%}} -{{}} - - +{{}} diff --git a/content/includes/nap-waf/build-nginx-image-cmd.md b/content/includes/nap-waf/build-nginx-image-cmd.md index 41bf90d03..fcb89d363 100644 --- a/content/includes/nap-waf/build-nginx-image-cmd.md +++ b/content/includes/nap-waf/build-nginx-image-cmd.md @@ -10,7 +10,7 @@ To build the image, execute the following command in the directory containing th ```shell -sudo docker build --no-cache \ +sudo docker build --no-cache --platform linux/amd64 \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t nginx-app-protect-5 . diff --git a/content/nap-dos/deployment-guide/learn-about-deployment.md b/content/nap-dos/deployment-guide/learn-about-deployment.md index df137bd2e..430fd9e2e 100644 --- a/content/nap-dos/deployment-guide/learn-about-deployment.md +++ b/content/nap-dos/deployment-guide/learn-about-deployment.md @@ -1405,7 +1405,7 @@ You need root permissions to execute the following steps. 6. Create a Docker image: ```shell - docker build --no-cache -t app-protect-dos . + docker build --no-cache --platform linux/amd64 -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. @@ -1966,13 +1966,13 @@ Make sure to replace upstream and proxy pass directives in this example with rel For CentOS: ```shell - docker build --no-cache -t app-protect-dos . + docker build --no-cache --platform linux/amd64 -t app-protect-dos . ``` For RHEL: ```shell - docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . + docker build --platform linux/amd64 --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect-dos . ``` The `--no-cache` option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect DoS. If the Dockerfile was previously used to build an image without the `--no-cache` option, the new image uses versions from the previously built image from the Docker cache. diff --git a/content/nap-waf/v4/admin-guide/install.md b/content/nap-waf/v4/admin-guide/install.md index 3158ac9d3..c3e0575dc 100644 --- a/content/nap-waf/v4/admin-guide/install.md +++ b/content/nap-waf/v4/admin-guide/install.md @@ -939,7 +939,7 @@ If a user other than **nginx** is to be used, note the following: - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . + DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). @@ -1289,7 +1289,7 @@ You need root permissions to execute the following steps. - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: ```shell - DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . + DOCKER_BUILDKIT=1 docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter . ``` The `DOCKER_BUILDKIT=1` enables `docker build` to recognize the `--secret` flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (`nginx-repo.crt` and `nginx-repo.key` files). More information [here](https://docs.docker.com/engine/reference/commandline/buildx_build/#secret). diff --git a/content/nap-waf/v5/admin-guide/compiler.md b/content/nap-waf/v5/admin-guide/compiler.md index dd0e828e4..ea0f28500 100644 --- a/content/nap-waf/v5/admin-guide/compiler.md +++ b/content/nap-waf/v5/admin-guide/compiler.md @@ -98,7 +98,7 @@ curl -s https://private-registry.nginx.com/v2/nap/waf-compiler/tags/list --key < Run the command below to build your image, where `waf-compiler-:custom` is an example of the image tag: ```shell - sudo docker build --no-cache \ + sudo docker build --no-cache --platform linux/amd64 \ --secret id=nginx-crt,src=nginx-repo.crt \ --secret id=nginx-key,src=nginx-repo.key \ -t waf-compiler-:custom . diff --git a/content/ngf/overview/custom-policies.md b/content/ngf/overview/custom-policies.md index c7e5a785d..5aeb99fce 100644 --- a/content/ngf/overview/custom-policies.md +++ b/content/ngf/overview/custom-policies.md @@ -17,10 +17,11 @@ The following table summarizes NGINX Gateway Fabric custom policies: {{< bootstrap-table "table table-striped table-bordered" >}} -| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | -|---------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha1 | +| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | +|---------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| +| [ClientSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/client-settings.md" >}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | +| [ObservabilityPolicy]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | +| [UpstreamSettingsPolicy]({{< ref "/ngf/how-to/traffic-management/upstream-settings.md" >}}) | Configure connection behavior between NGINX and backend | Direct | Service | Yes | Yes | v1alpha1 | {{< /bootstrap-table >}} diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index cd9f7a20f..3c73a4cb5 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -32,7 +32,8 @@ Telemetry data is collected once every 24 hours and sent to a service managed by - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected. - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest. - **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. -- **SnippetsFilters Info**a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. +- **SnippetsFilters Info:** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. + This data is used to identify the following information: - The flavors of Kubernetes environments that are most popular among our users. diff --git a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md index a7a6a7f61..bf40c20be 100644 --- a/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md +++ b/content/nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md @@ -9,10 +9,9 @@ type: - how-to --- - -## Introduction +## Introduction {#intro} -[Load balancing](https://www.nginx.com/solutions/load-balancing/) refers to efficiently distributing network traffic across multiple backend servers. +[Load balancing](https://www.f5.com/glossary/load-balancer) refers to efficiently distributing network traffic across multiple backend servers. In F5 NGINX Plus [R5]({{< ref "nginx/releases.md#r5" >}}) and later, NGINX Plus can proxy and load balance Transmission Control Protocol) (TCP) traffic. TCP is the protocol for many popular applications and services, such as LDAP, MySQL, and RTMP. @@ -20,15 +19,13 @@ In NGINX Plus [R9]({{< ref "nginx/releases.md#r9" >}}) and later, NGINX Plus can To load balance HTTP traffic, refer to the [HTTP Load Balancing]({{< ref "http-load-balancer.md" >}}) article. - ## Prerequisites - Latest NGINX Plus (no extra build steps required) or latest [NGINX Open Source](https://nginx.org/en/download.html) built with the `--with-stream` configuration flag - An application, database, or service that communicates over TCP or UDP - Upstream servers, each running the same instance of the application, database, or service - -## Configuring Reverse Proxy +## Configuring reverse proxy {#proxy_pass} First, you will need to configure _reverse proxy_ so that NGINX Plus or NGINX Open Source can forward TCP connections or UDP datagrams from clients to an upstream group or a proxied server. @@ -118,8 +115,7 @@ Open the NGINX configuration file and perform the following steps: } ``` - -## Configuring TCP or UDP Load Balancing +## Configuring TCP or UDP load balancing {#upstream} To configure load balancing: @@ -250,8 +246,7 @@ stream { } ``` - -## Configuring Health Checks +## Configuring health checks {#health} NGINX can continually test your TCP or UDP upstream servers, avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. @@ -259,8 +254,7 @@ See [TCP Health Checks]({{< ref "nginx/admin-guide/load-balancer/tcp-health-chec See [UDP Health Checks]({{< ref "nginx/admin-guide/load-balancer/udp-health-check.md" >}}) for instructions how to configure health checks for UDP. - -## On-the-Fly Configuration +## On-the-fly configuration Upstream server groups can be easily reconfigured on-the-fly using NGINX Plus REST API. Using this interface, you can view all servers in an upstream group or a particular server, modify server parameters, and add or remove upstream servers. @@ -355,8 +349,7 @@ To enable on-the-fly configuration: } ``` - -### On-the-Fly Configuration Example +### On-the-fly configuration example ```nginx stream { @@ -403,23 +396,22 @@ For example, to add a new server to the server group, send a `POST` request: curl -X POST -d '{ \ "server": "appserv3.example.com:12345", \ "weight": 4 \ - }' -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers' + }' -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers' ``` To remove a server from the server group, send a `DELETE` request: ```shell -curl -X DELETE -s 'http://127.0.0.1/api/6/stream/upstreams/appservers/servers/0' +curl -X DELETE -s 'http://127.0.0.1/api/9/stream/upstreams/appservers/servers/0' ``` To modify a parameter for a specific server, send a `PATCH` request: ```shell -curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/6/http/upstreams/appservers/servers/0' +curl -X PATCH -d '{ "down": true }' -s 'http://127.0.0.1/api/9/http/upstreams/appservers/servers/0' ``` - -## Example of TCP and UDP Load-Balancing Configuration +## Example of TCP and UDP load-balancing configuration {#example} This is a configuration example of TCP and UDP load balancing with NGINX: @@ -471,3 +463,13 @@ The three [`server`](https://nginx.org/en/docs/stream/ngx_stream_upstream_module - The second server listens on port 53 and proxies all UDP datagrams (the `udp` parameter to the `listen` directive) to an upstream group called **dns_servers**. If the `udp` parameter is not specified, the socket listens for TCP connections. - The third virtual server listens on port 12346 and proxies TCP connections to **backend4.example.com**, which can resolve to several IP addresses that are load balanced with the Round Robin method. + +## See also + +- [TCP Health Checks]({{< relref "tcp-health-check.md" >}}) + +- [UDP Health Checks]({{< relref "udp-health-check.md" >}}) + +- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) + +- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks) diff --git a/content/nginx/admin-guide/load-balancer/udp-health-check.md b/content/nginx/admin-guide/load-balancer/udp-health-check.md index bb4818fd4..7885d032a 100644 --- a/content/nginx/admin-guide/load-balancer/udp-health-check.md +++ b/content/nginx/admin-guide/load-balancer/udp-health-check.md @@ -9,10 +9,11 @@ type: - how-to --- - -## Prerequisites +NGINX Plus can continually test your upstream servers that handle UDP network traffic (DNS, RADIUS, syslog), avoid the servers that have failed, and gracefully add the recovered servers into the load‑balanced group. -- You have configured an upstream group of servers that handles UDP network traffic (DNS, RADIUS, syslog) in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: +## Prerequisites {#prereq} + +- You have [configured an upstream group of servers]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) that handles UDP network traffic in the [`stream {}`](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#stream) context, for example: ```nginx stream { @@ -44,8 +45,7 @@ type: See [TCP and UDP Load Balancing]({{< ref "nginx/admin-guide/load-balancer/tcp-udp-load-balancer.md" >}}) for details. - -## Passive UDP Health Checks +## Passive UDP health checks {#hc_passive} NGINX Open Source or F5 NGINX Plus can mark the server as unavailable and stop sending UDP datagrams to it for some time if the server replies with an error or times out. @@ -62,8 +62,7 @@ upstream dns_upstream { } ``` - -## Active UDP Health Checks +## Active UDP health checks {#hc_active} Active Health Checks allow testing a wider range of failure types and are available only for NGINX Plus. For example, instead of waiting for an actual TCP request from a DNS client to fail before marking the DNS server as down (as in passive health checks), NGINX Plus will send special health check requests to each upstream server and check for a response that satisfies certain conditions. If a connection to the server cannot be established, the health check fails, and the server is considered unhealthy. NGINX Plus does not proxy client connections to unhealthy servers. If more than one health check is defined, the failure of any check is enough to consider the corresponding upstream server unhealthy. @@ -100,8 +99,7 @@ To enable active health checks: A basic UDP health check assumes that NGINX Plus sends the β€œnginx health check” string to an upstream server and expects the absence of ICMP β€œDestination Unreachable” message in response. You can configure your own health check tests in the `match {}` block. See [The β€œmatch {}” Configuration Block](#hc_active_match) for details. - -### Fine-Tuning UDP Health Checks +### Fine-Tuning UDP Health Checks {#hc_active_finetune} You can fine‑tune the health check by specifying the following parameters to the [`health_check`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check) directive: @@ -119,10 +117,9 @@ server { In the example, the time between UDP health checks is increased to 20 seconds, the server is considered unhealthy after 2 consecutive failed health checks, and the server needs to pass 2 consecutive checks to be considered healthy again. - -### The β€œmatch {}” Configuration Block +### The β€œmatch {}” configuration block {#hc_active_match} -You can verify server responses to health checks by configuring a number of tests. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. +A basic UDP health check assumes that NGINX Plus sends the β€œnginx health check” string to an upstream server and expects the absence of ICMP β€œDestination Unreachable” message in response. You can configure your own health check tests that will verify server responses. These tests are defined within the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) configuration block. 1. In the top‑level `stream {}` context, specify the [`match {}`](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) block and set its name, for example, `udp_test`: @@ -155,8 +152,9 @@ You can verify server responses to health checks by configuring a number of test These parameters can be used in different combinations, but no more than one `send` and one `expect` parameter can be specified at a time. - -#### Example Test for NTP +## Usage scenarios + +### NTP health checks {#example_ntp} To fine‑tune health checks for NTP, you should specify both `send` and `expect` parameters with the following text strings: @@ -167,14 +165,138 @@ match ntp { } ``` - -#### Example Test for DNS +#### Complete NTP health check configuration example + +```nginx + +stream { + upstream ntp_upstream { + zone ntp_zone 64k; + server 192.168.136.130:53; + server 192.168.136.131:53; + server 192.168.136.132:53; +} + server { + listen 53 udp; + proxy_pass ntp_upstream; + health_check match=ntp udp; + proxy_timeout 1s; + proxy_responses 1; + error_log logs/ntp.log; + } + + match ntp { + send \xe3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00; + expect ~* \x24; + } +} +``` + +### DNS health checks {#example_dns} + +[DNS health checks](#hc_active) can be enhanced to perform real DNS lookup queries. You can craft a valid DNS query packet, send it to the upstream server, and inspect the response to determine health. + +The process includes three steps: +- [Creating a CNAME test record](#create-a-cname-record) on your DNS server. +- [Crafting a raw DNS query packet](#construct-a-raw-dns-query-packet) to be sent by NGINX Plus. +- [Validating the expected response](#configure-the-match-block-for-dns-lookup) using the `match` block, where the `send` parameter represents a raw DNS query packet, and `expect` represents the value of the CNAME record. + +#### Create a CNAME record + +First, create a CNAME record on your DNS server for a health check that points to the target website. + +For example, if you are using BIND self-hosted DNS solution on a Linux server: + +- Open the zone file in a text editor: + +```shell +sudo nano /etc/bind/zones/db.example.com +``` +- Add a CNAME record, making `healthcheck.example.com` resolve to `healthy.svcs.example.com`: + +```none +healthcheck IN CNAME healthy.svcs.example.com. +``` + +- Save the file and reload the DNS service: + +```shell +sudo systemctl reload bind9 +``` + +Once the CNAME record is live and resolvable, you can craft a DNS query packet that represents a DNS lookup and can be used in the `send` directive. + +#### Construct a raw DNS query packet + +The `send` parameter of the `match` block allows you to send raw UDP packets for health checks. To query your CNAME record, you need to construct a valid DNS query packet according to the [DNS protocol message format](https://datatracker.ietf.org/doc/html/rfc1035#section-4.1), including a header and question section. -To fine‑tune health checks for DNS, you should also specify both `send` and `expect` parameters with the following text strings: +The DNS Query packet can be created using DNS packet builders, such as Python Scapy or dnslib, or packet analyzers, such as tcpdump or Wireshark. If using a packet analyzer, extract only the DNS layer, removing Ethernet, IP, and UDP-related headers. + +This is the raw DNS query of `healthcheck.example.com`, represented as one line in Hex with `\x` prefixes: + +```none +\x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01 +``` +where: + +{{}} +| HEX | Description | +|------------------|------------------------| +| \x00\x01 | Transaction ID: 0x0001 | +| \x01\x00 | Flags: Standard query, recursion desired | +| \x00\x01 | Questions: 1 | +| \x00\x00 | Answer RRs: 0 | +| \x00\x00 | Authority RRs: 0 | +| \x00\x00 | Additional RRs: 0 | +| \x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b | "healthcheck" | +| \x07\x65\x78\x61\x6d\x70\x6c\x65 | "example" | +| \x03\x63\x6f\x6d | "com" | +| \x00 | end of name | +| \x00\x01 | Type: A | +| \x00\x01 | Class: IN | +{{}} + +#### Configure the match block for DNS lookup + +Finally, specify the `match` block in the NGINX configuration file to pair the raw query with an expected response. The `send` directive should contain the DNS query packet, while `expect` directive should contain a matching DNS record in the DNS server's response: ```nginx match dns { - send \x00\x2a\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x03\x73\x74\x6c\x04\x75\x6d\x73\x6c\x03\x65\x64\x75\x00\x00\x01\x00\x01; - expect ~* "health.is.good"; + send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; + expect ~* "healthy.svcs.example.com"; +} +``` + +#### Complete DNS health check configuration example + +```nginx + +stream { + upstream dns_upstream { + zone dns_zone 64k; + server 192.168.136.130:53; + server 192.168.136.131:53; + server 192.168.136.132:53; +} + server { + listen 53 udp; + proxy_pass dns_upstream; + health_check match=dns udp; + proxy_timeout 1s; + proxy_responses 1; + error_log logs/dns.log; + } + + match dns { + # make sure appropriate CNAME record exists + send \x00\x01\x01\x00\x00\x01\x00\x00\x00\x00\x00\x00\x0b\x68\x65\x61\x6c\x74\x68\x63\x68\x65\x63\x6b\x07\x65\x78\x61\x6d\x70\x6c\x65\x03\x63\x6f\x6d\x00\x00\x01\x00\x01; + expect ~* "healthy.svcs.example.com"; + } } ``` + +## See also + +- [Load Balancing DNS Traffic with NGINX and NGINX Plus](https://www.f5.com/company/blog/nginx/load-balancing-dns-traffic-nginx-plus) + +- [TCP/UDP Load Balancing with NGINX: Overview, Tips, and Tricks](https://blog.nginx.org/blog/tcp-load-balancing-udp-load-balancing-nginx-tips-tricks#activeHealthCheck) diff --git a/content/nim/nginx-app-protect/manage-waf-security-policies.md b/content/nim/nginx-app-protect/manage-waf-security-policies.md index 71684b133..5c0e5ebf3 100644 --- a/content/nim/nginx-app-protect/manage-waf-security-policies.md +++ b/content/nim/nginx-app-protect/manage-waf-security-policies.md @@ -1,8 +1,7 @@ --- -title: Manage WAF Security Policies and Security Log Profiles -description: Learn how to use F5 NGINX Management Suite Instance Manager to manage NGINX - App Protect WAF security policies and security log profiles. -weight: 200 +title: Manage and deploy WAF policies and log profiles +description: Learn how to use F5 NGINX Instance Manager to manage NGINX App Protect WAF security policies and security log profiles. +weight: 300 toc: true type: how-to product: NIM @@ -11,83 +10,76 @@ docs: DOCS-1105 ## Overview -F5 NGINX Management Suite Instance Manager provides the ability to manage the configuration of NGINX App Protect WAF instances either by the user interface or the REST API. This includes editing, updating, and deploying security policies, log profiles, attack signatures, and threat campaigns to individual instances and/or instance groups. +F5 NGINX Instance Manager lets you manage NGINX App Protect WAF configurations using either the web interface or REST API. You can edit, update, and deploy security policies, log profiles, attack signatures, and threat campaigns to individual instances or instance groups. -In Instance Manager v2.14.0 and later, you can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. A security policy bundle consists of the security policy, the attack signatures, and threat campaigns for a particular version of NGINX App Protect WAF, and additional supporting files that make it possible for NGINX App Protect WAF to use the bundle. Because the security policy bundle is pre-compiled, the configuration gets applied faster than when you individually reference the security policy, attack signature, and threat campaign files. +You can compile a security policy, attack signatures, and threat campaigns into a security policy bundle. The bundle includes all necessary components for a specific NGINX App Protect WAF version. Precompiling the bundle improves performance by avoiding separate compilation of each component during deployment. {{}} -The following capabilities are only available via the Instance Manager REST API: +The following capabilities are available only through the Instance Manager REST API: - Update security policies - Create, read, and update security policy bundles -- Create, read, update, and delete Security Log Profiles -- Publish security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups +- Create, read, update, and delete security log profiles +- Publish security policies, log profiles, attack signatures, and threat campaigns to instances and instance groups {{}} --- -## Before You Begin +## Before you begin -Complete the following prerequisites before proceeding with this guide: +Before continuing, complete the following steps: -- [Set Up App Protect WAF Configuration Management]({{< ref "setup-waf-config-management" >}}) -- Verify that your user account has the [necessary permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the Instance Manager REST API: +- [Set up App Protect WAF configuration management]({{< ref "setup-waf-config-management" >}}) +- Make sure your user account has the [required permissions]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}) to access the REST API: - - **Module**: Instance Manager - - **Feature**: Instance Management - - **Access**: `READ` - - **Feature**: Security Policies - - **Access**: `READ`, `CREATE`, `UPDATE`, `DELETE` + - **Module**: Instance Manager + - **Feature**: Instance Management β†’ `READ` + - **Feature**: Security Policies β†’ `READ`, `CREATE`, `UPDATE`, `DELETE` -The following are required to use support policy bundles: +To use policy bundles, you also need to: -- You must have `UPDATE` permissions for the security policies specified in the request. -- The correct `nms-nap-compiler` packages for the NGINX App Protect WAF version you're using are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}). -- The attack signatures and threat campaigns that you want to use are [installed on Instance Manager]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}). +- Have `UPDATE` permissions for each referenced security policy +- [Install the correct `nms-nap-compiler` package]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#install-the-waf-compiler" >}}) for your App Protect WAF version +- [Install the required attack signatures and threat campaigns]({{< ref "/nim/nginx-app-protect/setup-waf-config-management.md#set-up-attack-signatures-and-threat-campaigns" >}}) -### How to Access the Web Interface +### Access the web interface -To access the web interface, go to the FQDN for your NGINX Instance Manager host in a web browser and log in. Once you're logged in, select "Instance Manager" from the Launchpad menu. +To access the web interface, open a browser and go to the fully qualified domain name (FQDN) of your NGINX Instance Manager. Log in, then select **Instance Manager** from the Launchpad. -### How to Access the REST API +### Access the REST API {{< include "nim/how-to-access-nim-api.md" >}} --- -## Create a Security Policy {#create-security-policy} +## Create a security policy {#create-security-policy} {{}} {{%tab name="web interface"%}} -
      - -To create a security policy using the Instance Manager web interface: - -1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. -2. On the left menu, select **App Protect**. -3. On the *Security Policies* page, select **Create**. -4. On the *Create Policy* page, fill out the necessary fields: +To create a security policy using the NGINX Instance Manager web interface: - - **Name**: Provide a name for the policy. - - **Description**: (Optional) Add a short description for the policy. - - **Enter Policy**: Type or paste the policy in JSON format into the form provided. The editor will validate the JSON for accuracy. +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. From the Launchpad menu, select **Instance Manager**. +3. In the left menu, select **App Protect**. +4. On the *Security Policies* page, select **Create**. +5. On the *Create Policy* page, enter the required information: + - **Name**: Enter a name for the policy. + - **Description**: (Optional) Add a brief description. + - **Enter Policy**: Paste or type the JSON-formatted policy into the editor. The interface automatically validates the JSON. - For more information about creating custom policies, refer to the [NGINX App Protect WAF Declarative Policy](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) guide and the [Policy Authoring and Tuning](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) section of the config guide. + For help writing custom policies, see the [NGINX App Protect WAF Declarative Policy guide](https://docs.nginx.com/nginx-app-protect/declarative-policy/policy/) and the [Policy Authoring and Tuning section](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-authoring-and-tuning) in the configuration guide. -5. Select **Save**. +6. Select **Save**. {{%/tab%}} {{%tab name="API"%}} -To upload a new security policy, send an HTTP `POST` request to the Security Policies API endpoint. - -{{}}Before sending a security policy to Instance Manager, you need to encode it using `base64`. Submitting a policy in its original JSON format will result in an error.{{}} - -
      +To upload a new security policy using the REST API, send a `POST` request to the Security Policies API endpoint. +You must encode the JSON policy using `base64`. If you send the policy in plain JSON, the request will fail. {{}} @@ -101,7 +93,7 @@ To upload a new security policy, send an HTTP `POST` request to the Security Pol For example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies \ -H "Authorization: Bearer " \ -d @ignore-xss-example.json ``` @@ -134,7 +126,7 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ "modified": "2022-04-12T23:19:58.502Z", "name": "ignore-cross-site-scripting", "revisionTimestamp": "2022-04-12T23:19:58.502Z", - "uid": "21daa130-4ba4-442b-bc4e-ab294af123e5" + "uid": "" }, "selfLink": { "rel": "/api/platform/v1/services/environments/prod" @@ -148,11 +140,13 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies \ --- -## Update a Security Policy +## Update a security policy + -To update a security policy, send an HTTP `POST` request to the Security Policies API endpoint, `/api/platform/v1/security/policies`. +To update a security policy, send a `POST` or `PUT` request to the Security Policies API. -You can use the optional `isNewRevision` parameter to indicate whether the updated policy is a new version of an existing policy. +- Use `POST` with the `isNewRevision=true` parameter to add a new version of an existing policy. +- Use `PUT` with the policy UID to overwrite the existing version. {{}} @@ -165,33 +159,35 @@ You can use the optional `isNewRevision` parameter to indicate whether the updat {{}} -For example: +To use `POST`, include the policy metadata and content in your request: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-xss-policy.json ``` -You can update a specific policy by sending an HTTP `PUT` request to the Security Policies API endpoint that includes the policy's unique identifier (UID). +To use PUT, first retrieve the policy’s unique identifier (UID). You can do this by sending a GET request to the policies endpoint: -To find the UID, send an HTTP `GET` request to the Security Policies API endpoint. This returns a list of all Security Policies that contains the unique identifier for each policy. - -Include the UID for the security policy in your `PUT` request to update the policy. Once the policy update is accepted, the WAF compiler will create a new, updated bundle. +```shell +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " +``` -For example: +Then include the UID in your PUT request: ```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ +curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ -H "Authorization: Bearer " \ - --Content-Type application/json -d @update-xss-policy.json + --Content-Type application/json \ + -d @update-xss-policy.json ``` -After you have pushed an updated security policy, you can [publish it](#publish-policy) to selected instances or instance groups. +After updating the policy, you can [publish it](#publish-policy) to selected instances or instance groups. --- -## Delete a Security Policy +## Delete a security policy {{}} @@ -199,17 +195,29 @@ After you have pushed an updated security policy, you can [publish it](#publish-
      -To delete a security policy using the Instance Manager web interface: +To delete a security policy using the NGINX Instance Manager web interface: + +1. In your browser, go to the FQDN for your NGINX Instance Manager host and log in. +2. From the Launchpad menu, select **Instance Manager**. +3. In the left menu, select **App Protect**. +4. On the *Security Policies* page, find the policy you want to delete. +5. Select the **Actions** menu (**...**) and choose **Delete**. -1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in. Then, from the Launchpad menu, select **Instance Manager**. -2. On the left menu, select **App Protect**. -3. On the *Security Policies* page, select the **Actions** menu (represented by an ellipsis, **...**) for the policy you want to delete. Select **Delete** to remove the policy. {{%/tab%}} {{%tab name="API"%}} -To delete a security policy, send an HTTP `DELETE` request to the Security Policies API endpoint that includes the unique identifier for the policy that you want to delete. +To delete a security policy using the REST API: + +1. Retrieve the UID for the policy by sending a `GET` request to the policies endpoint: + + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies \ + -H "Authorization: Bearer " + ``` + +2. Send a `DELETE` request using the policy UID: {{}} @@ -221,10 +229,10 @@ To delete a security policy, send an HTTP `DELETE` request to the Security Polic {{}} -For example: +Example: ```shell -curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ +curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/policies/ \ -H "Authorization: Bearer " ``` @@ -232,36 +240,42 @@ curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/policies/23139e0a-4 {{      }} -{{%comment%}}TO DO: Add sections for managing attack signatures and threat campaigns{{%/comment%}} - --- -## Create Security Policy Bundles {#create-security-policy-bundles} +## Create security policy bundles {#create-security-policy-bundles} -To create security policy bundles, send an HTTP `POST` request to the Security Policies Bundles API endpoint. The specified security policies you'd like to compile into security policy bundles must already exist in Instance Manager. -### Required Fields +To create a security policy bundle, send a `POST` request to the Security Policy Bundles API. The policies you want to include in the bundle must already exist in NGINX Instance Manager. -- `appProtectWAFVersion`: The version of NGINX App Protect WAF being used. -- `policyName`: The name of security policy to include in the bundle. This must reference an existing security policy; refer to the [Create a Security Policy](#create-security-policy) section above for instructions. +Each bundle includes: -### Notes +- A security policy +- Attack signatures +- Threat campaigns +- A version of NGINX App Protect WAF +- Supporting files required to compile and deploy the bundle + +### Required fields + +- `appProtectWAFVersion`: The version of NGINX App Protect WAF to target. +- `policyName`: The name of the policy to include. Must reference an existing policy. +- `policyUID`: Optional. If omitted, the latest revision of the specified policy is used. This field does **not** accept the keyword `latest`. + +If you don’t include `attackSignatureVersionDateTime` or `threatCampaignVersionDateTime`, the latest versions are used by default. You can also set them explicitly by using `"latest"` as the value. -- If you do not specify a value for the `attackSignatureVersionDateTime` and/or `threatCampaignVersionDateTime` fields, the latest version of each will be used by default. You can also explicitly state that you want to use the most recent version by specifying the keyword `latest` as the value. -- If the `policyUID` field is not defined, the latest version of the specified security policy will be used. This field **does not allow** use of the keyword `latest`. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|----------------------------------------------| | POST | `/api/platform/v1/security/policies/bundles` | {{}} -For example: +Example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " \ -d @security-policy-bundles.json ``` @@ -274,7 +288,7 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "bundles": [{ "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18" }, @@ -305,10 +319,10 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "dceb8254-9a90-4e77-87ac-73070f821412" + "uid": "" }, "content": "", "compilationStatus": { @@ -321,11 +335,11 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", - "policyName": "defautl-enforcement", - "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", + "policyName": "default-enforcement", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "", "compilationStatus": { @@ -339,10 +353,10 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" + "uid": "" }, "content": "", "compilationStatus": { @@ -354,39 +368,38 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ } ``` - --- -## List Security Policy Bundles {#list-security-policy-bundles} +## List security policy bundles {#list-security-policy-bundles} -To list security policy bundles, send an HTTP `GET` request to the Security Policies Bundles API endpoint. +To list all security policy bundles, send a `GET` request to the Security Policy Bundles API. -{{}}The list will only contain the security policy bundles that you have "READ" permissions for in Instance Manager.{{}} +You’ll only see bundles you have `"READ"` permissions for. -You can filter the results by using the following query parameters: +You can use the following query parameters to filter results: -- `includeBundleContent`: Boolean indicating whether to include the security policy bundle content for each bundle when getting a list of bundles or not. If not provided, defaults to `false`. Please note that the content returned is `base64 encoded`. -- `policyName`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy name will be returned. If not provided, it will not filter based on `policyName`. -- `policyUID`: String used to filter the list of security policy bundles; only security policy bundles that have the specified security policy UID will be returned. If not provided, it will not filter based on `policyUID`. -- `startTime`: The security policy bundle's "modified time" has to be equal to or greater than this time value. If no value is supplied, it defaults to 24 hours from the current time. `startTime` has to be less than `endTime`. -- `endTime`: Indicates the time that the security policy bundles modified time has to be less than. If no value is supplied, it defaults to current time. `endTime` has to be greater than `startTime`. +- `includeBundleContent`: Whether to include base64-encoded content in the response. Defaults to `false`. +- `policyName`: Return only bundles that match this policy name. +- `policyUID`: Return only bundles that match this policy UID. +- `startTime`: Return only bundles modified at or after this time. +- `endTime`: Return only bundles modified before this time. -
      +If no time range is provided, the API defaults to showing bundles modified in the past 24 hours. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|----------------------------------------------| | GET | `/api/platform/v1/security/policies/bundles` | {{}} -For example: +Example: ```shell -curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/bundles \ -H "Authorization: Bearer " ``` @@ -401,10 +414,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "default-enforcement", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.06.20", "threatCampaignVersionDateTime": "2023.07.18", - "uid": "dceb8254-9a90-4e77-87ac-73070f821412" + "uid": "" }, "content": "", "compilationStatus": { @@ -418,10 +431,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.279.0", "policyName": "defautl-enforcement", - "policyUID": "04fc5b9849a6-612a-5c69-895a-29d86fe8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "", "compilationStatus": { @@ -435,10 +448,10 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", "policyName": "ignore-xss", - "policyUID": "849a604fc5b9-612a-5c69-895a-86f29de8", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "nbu844lz-9a90-4e77-87ac-zze8861d" + "uid": "" }, "content": "", "compilationStatus": { @@ -452,35 +465,35 @@ curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/bundles \ --- -## Get a Security Policy Bundle {#get-security-policy-bundle} +## Get a security policy bundle {#get-security-policy-bundle} -To get a specific security policy bundle, send an HTTP `GET` request to the Security Policies Bundles API endpoint that contains the security policy UID and security policy bundle UID in the path. +To retrieve a specific security policy bundle, send a `GET` request to the Security Policy Bundles API using the policy UID and bundle UID in the URL path. -{{}}You must have "READ" permission for the security policy bundle to be able to retrieve information about a bundle by using the REST API.{{}} - -
      +You must have `"READ"` permission for the bundle to retrieve it. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|-------------------------------------------------------------------------------------------------| | GET | `/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}` | {{}} - -For example: +Example: ```shell -curl -X GET https://{{NMS_FQDN}}/api/platform/v1/security/policies/29d86fe8-612a-5c69-895a-04fc5b9849a6/bundles/trs35lv2-9a90-4e77-87ac-ythn4967 \ +curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/ \ -H "Authorization: Bearer " ``` -The JSON response, shown in the example below, includes a `content` field that is base64 encoded. After you retrieve the information from the API, you will need to base64 decode the content field. You can include this in your API call, as shown in the following example cURL request: +The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file. + +Example: ```bash -curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-policy-uid}/bundles/{security-policy-bundle-uid}" -H "Authorization: Bearer xxxxx.yyyyy.zzzzz" | jq -r '.content' | base64 -d > security-policy-bundle.tgz +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies//bundles/" \ + -H "Authorization: Bearer " | jq -r '.content' | base64 -d > security-policy-bundle.tgz ```
      @@ -492,10 +505,10 @@ curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-poli "created": "2023-10-04T23:19:58.502Z", "modified": "2023-10-04T23:19:58.502Z", "appProtectWAFVersion": "4.457.0", - "policyUID": "29d86fe8-612a-5c69-895a-04fc5b9849a6", + "policyUID": "", "attackSignatureVersionDateTime": "2023.08.10", "threatCampaignVersionDateTime": "2023.08.09", - "uid": "trs35lv2-9a90-4e77-87ac-ythn4967" + "uid": "" }, "content": "ZXZlbnRzIHt9Cmh0dHAgeyAgCiAgICBzZXJ2ZXIgeyAgCiAgICAgICAgbGlzdGVuIDgwOyAgCiAgICAgICAgc2VydmVyX25hbWUgXzsKCiAgICAgICAgcmV0dXJuIDIwMCAiSGVsbG8iOyAgCiAgICB9ICAKfQ==", "compilationStatus": { @@ -507,28 +520,25 @@ curl -X GET "https://{NMS_FQDN}/api/platform/v1/security/policies/{security-poli --- -## Create a Security Log Profile {#create-security-log-profile} - -Send an HTTP `POST` request to the Security Log Profiles API endpoint to upload a new security log profile. +## Create a security log profile {#create-security-log-profile} -{{}}Before sending a security log profile to Instance Manager, you need to encode it using `base64`. Submitting a log profile in its original JSON format will result in an error.{{}} - -
      +To upload a new security log profile, send a `POST` request to the Security Log Profiles API endpoint. +You must encode the log profile in `base64` before sending it. If you send plain JSON, the request will fail. {{}} -| Method | Endpoint | -|--------|--------------------------------------| +| Method | Endpoint | +|--------|-----------------------------------------| | POST | `/api/platform/v1/security/logprofiles` | {{}} -For example: +Example: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ -H "Authorization: Bearer " \ -d @default-log-example.json ``` @@ -558,87 +568,100 @@ curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles \ "modified": "2023-07-05T22:09:19.634358096Z", "name": "default-log-example", "revisionTimestamp": "2023-07-05T22:09:19.634358096Z", - "uid": "54c35ad7-e082-4dc5-bb5d-2640a17d5620" + "uid": "" }, "selfLink": { - "rel": "/api/platform/v1/security/logprofiles/54c35ad7-e082-4dc5-bb5d-2640a17d5620" + "rel": "/api/platform/v1/security/logprofiles/" } } ``` --- -## Update a Security Log Profile - -To update a security log profile, send an HTTP `POST` request to the Security Log Profiles API endpoint, `/api/platform/v1/security/logprofiles`. +## Update a security log profile {#update-security-log-profile} -You can use the optional `isNewRevision` parameter to indicate whether the updated log profile is a new version of an existing log profile. +To update a security log profile, you can either: +- Use `POST` with the `isNewRevision=true` parameter to add a new version. +- Use `PUT` with the log profile UID to overwrite the existing version. {{}} -| Method | Endpoint | -|--------|---------------------------------------------------------| -| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| POST | `/api/platform/v1/security/logprofiles?isNewRevision=true` | | PUT | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -For example: +To create a new revision: ```shell -curl -X POST https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles?isNewRevision=true \ -H "Authorization: Bearer " \ -d @update-default-log.json ``` -You can update a specific log profile by sending an HTTP `PUT` request to the Security Log Profiles API endpoint that includes the log profile's unique identifier (UID). - -To find the UID, send an HTTP `GET` request to the Security Log Profiles API endpoint. This returns a list of all Security Log Profiles that contains the unique identifier for each log profile. +To overwrite an existing security log profile: -Include the UID for the security log profile in your `PUT` request to update the log profile. +1. Retrieve the profile’s UID: -For example: + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + --Content-Type application/json \ + -d @update-log-profile.json + ``` -```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ - -H "Authorization: Bearer " \ - --Content-Type application/json -d @update-default-log.json -``` +2. Use the UID in your PUT request: + + ```shell + curl -X PUT https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " \ + --Content-Type application/json \ + -d @update-log-profile.json + ``` -After you have pushed an updated security log profile, you can [publish it](#publish-policy) to selected instances or instance groups. +After updating the security log profile, you can [publish it](#publish-policy) to specific instances or instance groups. --- -## Delete a Security Log Profile +## Delete a security log profile {#delete-security-log-profile} -To delete a security log profile, send an HTTP `DELETE` request to the Security Log Profiles API endpoint that includes the unique identifier for the log profile that you want to delete. +To delete a security log profile, send a `DELETE` request to the Security Log Profiles API using the profile’s UID. {{}} -| Method | Endpoint | -|--------|------------------------------------------------------------| +| Method | Endpoint | +|--------|--------------------------------------------------------------------| | DELETE | `/api/platform/v1/security/logprofiles/{security-log-profile-uid}` | {{}} -For example: +1. Retrieve the UID: -```shell -curl -X DELETE https://{{NMS_FQDN}}/api/platform/v1/security/logprofiles/23139e0a-4ac8-49f9-b7a0-0577b42c70c7 \ - -H "Authorization: Bearer " -``` + ```shell + curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles \ + -H "Authorization: Bearer " + ``` + +2. Send the delete request: + + ```shell + curl -X DELETE https://{{NIM_FQDN}}/api/platform/v1/security/logprofiles/ \ + -H "Authorization: Bearer " + ``` --- -## Publish Updates to Instances {#publish-policy} +## Publish updates to instances {#publish-policy} -The Publish API lets you distribute security policies, security log profiles, attack signatures, and/or threat campaigns to instances and instance groups. +Use the Publish API to push security policies, log profiles, attack signatures, and threat campaigns to NGINX instances or instance groups. -{{}}Use this endpoint *after* you've added or updated security policies, security log profiles, attack signatures, and/or threat campaigns.{{}} +Call this endpoint *after* you've created or updated the resources you want to deploy. {{}} @@ -650,18 +673,20 @@ The Publish API lets you distribute security policies, security log profiles, at {{}} -When making a request to the Publish API, make sure to include all the necessary information for your specific use case: +Include the following information in your request, depending on what you're publishing: -- Instance and/or Instance Group UID(s) to push the bundle to -- Threat Campaign version and UID -- Attack Signature version and UID -- Security Policy UID(s) -- Security Log Profile UID(s) +- Instance and instance group UIDs +- Policy UID and name +- Log profile UID and name +- Attack signature library UID and version +- Threat campaign UID and version -For example: +Example: ```shell -curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorization: Bearer " +curl -X POST https://{{NIM_FQDN}}/api/platform/v1/security/publish \ + -H "Authorization: Bearer " \ + -d @publish-request.json ```
      @@ -671,27 +696,27 @@ curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorizat { "publications": [ { - "attackSignatureLibrary": { - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "versionDateTime": "2022.10.02" - }, - "instanceGroups": [ - "3fa85f64-5717-4562-b3fc-2c963f66afa6" - ], "instances": [ - "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "" ], + "instanceGroups": [ + "" + ], + "policyContent": { + "name": "example-policy", + "uid": "" + }, "logProfileContent": { - "name": "default-log", - "uid": "ffdbda39-88be-420a-b673-19d4183b7e4c" + "name": "example-log-profile", + "uid": "" }, - "policyContent": { - "name": "default-enforcement", - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6" + "attackSignatureLibrary": { + "uid": "", + "versionDateTime": "2023.10.02" }, "threatCampaign": { - "uid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", - "versionDateTime": "2022.10.01" + "uid": "", + "versionDateTime": "2023.10.01" } } ] @@ -721,357 +746,91 @@ curl -X PUT https://{{NMS_FQDN}}/api/platform/v1/security/publish -H "Authorizat --- -## Check Security Policy and Security Log Profile Publication Status -When publishing an NGINX configuration that references a security policy and secuity log profile, the Instance Manager REST APIs can provide further details about the status of the configuration publications. To access this information, use the Instance Manager API endpoints and method as indicated. +## Check security policy and security log profile publication status {#check-publication-status} -To retrieve the details for the different configuration publication statuses for a particular security policy, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security policy. +After publishing updates, you can check deployment status using the NGINX Instance Manager REST API. -| Method | Endpoint | -|--------|-----------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/associations/{security-policy-name}` | +Use the following endpoints to verify whether the configuration updates were successfully deployed to instances or instance groups. -You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: +### Check publication status for a security policy -- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails -- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails +To view deployment status for a specific policy, send a `GET` request to the Security Deployments Associations API using the policy name. -The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. +{{}} -```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/associations/ignore-xss" -H "Authorization: Bearer " -``` +| Method | Endpoint | +|--------|--------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/associations/{policy-name}` | -
      -JSON Response +{{}} -```json -{ - "associations": [ - { - "attackSignatureLibrary": { - "uid": "c69460cc-6b59-4813-8d9c-76e4a6c56b4b", - "versionDateTime": "2023.02.16" - }, - "instance": { - "hostName": "ip-172-16-0-99", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - "systemUid": "0435a5de-41c1-3754-b2e8-9d9fe946bafe", - "uid": "29d86fe8-612a-5c69-895a-04fc5b9849a6" - }, - "instanceGroup": { - "displayName": "inst_group_1", - "instances": [ - { - "hostName": "hostname1", - "systemUid": "49d143c2-f556-4cd7-8658-76fff54fb861", - "uid": "c8e15dcf-c504-4b7f-b52d-def7b8fd2f64", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - }, - { - "hostName": "hostname2", - "systemUid": "88a99ab0-15bb-4719-9107-daf5007c33f7", - "uid": "ed7e9173-794f-41af-80d9-4ed37d593247", - "lastDeploymentDetails": { - "createTime": "2023-04-11T21:36:11.519174534Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-99" - } - ] - }, - "id": "19cf5ed4-29d6-4139-b5f5-308c0d0ebb13", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-04-11T21:36:14.008108979Z" - }, - } - ], - "uid": "51f8addc-c0e9-438b-b0b6-3e4f1aa8202d" - }, - "policyUid": "9991f237-d9c7-47b7-98aa-faa836838f38", - "policyVersionDateTime": "2023-04-11T21:18:19.183Z", - "threatCampaign": { - "uid": "eab683fe-c2f1-4910-a88c-8bfbc6363164", - "versionDateTime": "2023.02.15" - } - } - ] -} +Example: + +```shell +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/associations/ignore-xss" \ + -H "Authorization: Bearer " ``` -
      +In the response, look for the `lastDeploymentDetails` field under instance or `instanceGroup.instances`. -To retrieve the details for the different configuration publication statuses for a particular security log profile, send an HTTP `GET` request to the Security Deployments Associations API endpoint, providing the name of the security log profile. -| Method | Endpoint | -|--------|-----------------------------------------------------------------------------| -| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{security-log-profile-name}` | +### Check publication status for a security log profile -You can locate the configuration publication status in the response within the field `lastDeploymentDetails` for instances and instance groups: +{{}} -- `lastDeploymentDetails` (for an instance): associations -> instance -> lastDeploymentDetails -- `lastDeploymentDetails` (for an instance in an instance group): associations -> instanceGroup -> instances -> lastDeploymentDetails +| Method | Endpoint | +|--------|-------------------------------------------------------------------------------------| +| GET | `/api/platform/v1/security/deployments/logprofiles/associations/{log-profile-name}` | -The example below shows a call to the `security deployments associations` endpoint and the corresponding JSON response containing successful deployments. +{{}} + +Example: ```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/security/deployments/logprofiles/associations/default-log" -H "Authorization: Bearer " +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/deployments/logprofiles/associations/default-log" \ + -H "Authorization: Bearer " ``` -
      -JSON Response +The response also contains `lastDeploymentDetails` for each instance or group. -```json -{ - "associations": [ - { - "instance": { - "hostName": "", - "systemUid": "", - "uid": "" - }, - "instanceGroup": { - "displayName": "ig1", - "instances": [ - { - "hostName": "ip-172-16-0-142", - "systemUid": "1d1f03ff-02de-32c5-8dfd-902658aada4c", - "uid": "18d074e6-3868-51ba-9999-b7466a936815" - } - ], - "lastDeploymentDetails": { - "createTime": "2023-07-05T23:01:06.679136973Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-142" - } - ] - }, - "id": "9bfc9db7-877d-4e8e-a43d-9660a6cd11cc", - "message": "Instance Group config successfully published to ig1", - "status": "successful", - "updateTime": "2023-07-05T23:01:06.790802157Z" - }, - "uid": "0df0386e-82f7-4efc-863e-5d7cfbc3f7df" - }, - "logProfileUid": "b680f7c3-6fc0-4c6b-889a-3025580c7fcb", - "logProfileVersionDateTime": "2023-07-05T22:08:47.371Z" - }, - { - "instance": { - "hostName": "ip-172-16-0-5", - "lastDeploymentDetails": { - "createTime": "2023-07-05T21:45:08.698646791Z", - "details": { - "failure": [], - "pending": [], - "success": [ - { - "name": "ip-172-16-0-5" - } - ] - }, - "id": "73cf670a-738a-4a74-b3fb-ac9771e89814", - "message": "Instance config successfully published to", - "status": "successful", - "updateTime": "2023-07-05T21:45:08.698646791Z" - }, - "systemUid": "0afe5ac2-43aa-36c8-bcdc-7f88cdd35ab2", - "uid": "9bb4e2ef-3746-5d79-b526-e545fad27e90" - }, - "instanceGroup": { - "displayName": "", - "instances": [], - "uid": "" - }, - "logProfileUid": "bb3badb2-f8f5-4b95-9428-877fc208e2f1", - "logProfileVersionDateTime": "2023-07-03T21:46:17.006Z" - } - ] -} -``` +### Check status for a specific instance -
      +You can also view the deployment status for a specific instance by providing the system UID and instance UID. -To retrieve the configuration publication status details for a particular instance, send an HTTP `GET` request to the Instances API endpoint, providing the unique system and instance identifiers. +{{}} -| Method | Endpoint | -|--------|-----------------------------------------------------------------| -| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-id}` | +| Method | Endpoint | +|--------|------------------------------------------------------------------| +| GET | `/api/platform/v1/systems/{system-uid}/instances/{instance-uid}` | -You can locate the configuration publication status in the the response within the `lastDeploymentDetails` field, which contains additional fields that provide more context around the status. +{{}} -The example below shows a call to the `instances` endpoint and the corresponding JSON response containing a compiler related error message. +Example: ```shell -curl -X GET "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b" -H "Authorization: Bearer " +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems//instances/" \ + -H "Authorization: Bearer " ``` -
      -JSON Response +In the response, look for the `lastDeploymentDetails` field, which shows the deployment status and any related errors. -```json -{ - "build": { - "nginxPlus": true, - "release": "nginx-plus-r28", - "version": "1.23.2" - }, - "configPath": "/etc/nginx/nginx.conf", - "configVersion": { - "instanceGroup": { - "createTime": "0001-01-01T00:00:00Z", - "uid": "", - "versionHash": "" - }, - "versions": [ - { - "createTime": "2023-01-14T10:48:46.319Z", - "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "versionHash": "922e9d40fa6d4dd3a4b721295b8ecd95f73402644cb8d234f9f4f862b8a56bfc" - } - ] - }, - "displayName": "ip-192-0-2-27", - "links": [ - { - "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73", - "name": "system" - }, - { - "rel": "/api/platform/v1/systems/b9df6377-2c4f-3266-a64a-e064b0371c73/instances/5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "name": "self" - }, - { - "rel": "/api/platform/v1/systems/instances/deployments/b31c6ab1-4a46-4c81-a065-204575145e8e", - "name": "deployment" - } - ], - "processPath": "/usr/sbin/nginx", - "registrationTime": "2023-01-14T10:12:31.000Z", - "startTime": "2023-01-14T10:09:43Z", - "status": { - "lastStatusReport": "2023-01-14T11:11:49.323495017Z", - "state": "online" - }, - "uid": "5663cf4e-a0c7-50c8-b93c-16fd11a0f00b", - "version": "1.23.2", - "appProtect": { - "attackSignatureVersion": "Available after publishing Attack Signatures from Instance Manager", - "status": "active", - "threatCampaignVersion": "Available after publishing Threat Campaigns from Instance Manager", - "version": "4.2.0" - }, - "configureArgs": [ - ... - ], - "lastDeploymentDetails": { - "createTime": "2023-01-14T11:10:25.096812852Z", - "details": { - "error": "{\"instance:b9df6377-2c4f-3266-a64a-e064b0371c73\":\"failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.\"}", - "failure": [ - { - "failMessage": "failed building config payload: policy compilation failed for deployment b31c6ab1-4a46-4c81-a065-204575145e8e due to integrations service error: the specified compiler (4.2.0) is missing, please install it and try again.", - "name": "ip-192-0-2-27" - } - ], - "pending": [], - "success": [] - }, - "id": "b31c6ab1-4a46-4c81-a065-204575145e8e", - "message": "Instance config failed to publish to", - "status": "failed", - "updateTime": "2023-01-14T11:10:25.175145693Z" - }, - "loadableModules": [ - ... - ], - "packages": [ - ... - ], - "processId": "10345", - "ssl": { - "built": null, - "runtime": null - } -} -``` +### Check deployment result by deployment ID -
      +When you use the Publish API to [publish security content](#publish-policy), NGINX Instance Manager creates a deployment ID for the request. You can use this ID to check the result of the publication. -When you use the Publish API (`/security/publish`) to [publish a security policy and security log profile](#publish-policy), Instance Manager creates a deployment ID for the request. To view the status of the update, or to check for any errors, use the endpoint and method shown below and reference the deployment ID. +{{}} | Method | Endpoint | |--------|------------------------------------------------------------------| | GET | `/api/platform/v1/systems/instances/deployments/{deployment-id}` | -You can locate the configuration publication status in the the response within the `details` field, which contains additional fields that provide more context around the status. +{{}} -The example below shows a call to the `deployments` endpoint and the corresponding JSON response containing a compiler error message. +Example: ```shell -curl -X GET --url "https://{NGINX-INSTANCE-MANAGER-FQDN}/api/platform/v1/systems/instances/deployments/d38a8e5d-2312-4046-a60f-a30a4aea1fbb" \ +curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/systems/instances/deployments/" \ -H "Authorization: Bearer " ``` -
      -JSON Response - -```json -{ - "createTime": "2023-01-14T04:35:47.566082799Z", - "details": { - "error": "{\"instance:8a2092aa-5612-370d-bff0-5d7521e206d6\":\"failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again\"}", - "failure": [ - { - "failMessage": "failed building config payload: policy bundle compilation failed for d38a8e5d-2312-4046-a60f-a30a4aea1fbb, integrations service returned the following error: missing the specified compiler (4.2.0) please install it and try again", - "name": "ip-192-0-2-243" - } - ], - "pending": [], - "success": [] - }, - "id": "d38a8e5d-2312-4046-a60f-a30a4aea1fbb", - "message": "Instance config failed to publish to", - "status": "failed", - "updateTime": "2023-01-14T04:35:47.566082799Z" -} -``` - -
      +The response includes the full deployment status, success or failure details, and any compiler error messages. diff --git a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md index 92287079d..b0d31319f 100644 --- a/content/nim/nginx-app-protect/overview-nap-waf-config-management.md +++ b/content/nim/nginx-app-protect/overview-nap-waf-config-management.md @@ -1,68 +1,76 @@ --- -description: Learn how you can use F5 NGINX Management Suite Instance Manager to configure - NGINX App Protect WAF security policies. +description: Learn how to use F5 NGINX Instance Manager to set up and manage NGINX App Protect WAF security policies. docs: DOCS-992 -title: NGINX App Protect WAF configuration management +title: "How WAF policy management works" toc: true -weight: 500 +weight: 100 type: - reference --- ## Overview -F5 NGINX Management Suite Instance Manager provides configuration management for [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/). +F5 NGINX Instance Manager helps you manage [NGINX App Protect WAF](https://www.nginx.com/products/nginx-app-protect/web-application-firewall/) security configurations. -You can use NGINX App Protect WAF with Instance Manager to inspect incoming traffic, identify potential threats, and block malicious traffic. With Configuration Management for App Protect WAF, you can configure WAF security policies in a single location and push your configurations out to one, some, or all of your NGINX App Protect WAF instances. +Use NGINX Instance Manager with NGINX App Protect WAF to inspect incoming traffic, detect threats, and block malicious requests. You can define policies in one place and push them to some or all of your NGINX App Protect WAF instances. -### Features +### Key features -- Manage NGINX App Protect WAF security configurations by using the NGINX Management Suite user interface or REST API -- Update Attack Signatures and Threat Campaign packages -- Compile security configurations into a binary bundle for consumption by NGINX App Protect WAF instances +- Manage WAF policies using the NGINX Instance Manager web interface or REST API +- Update attack signature and threat campaign packages +- Compile WAF configurations into a binary bundle for deployment ## Architecture -As demonstrated in Figure 1, Instance Manager lets you manage security configurations for NGINX App Protect WAF. You can define security policies, upload attack signatures and threat campaign packages, and publish common configurations out to your NGINX App Protect WAF instances. Instance Manager can compile the security configuration into a bundle before pushing the configuration to the NGINX App Protect WAF data plane instances. The NGINX Management Suite Security Monitoring module provides data visualization for NGINX App Protect, so you can monitor, analyze, and refine your policies. +NGINX Instance Manager lets you define and manage security policies, upload signature packages, and push configurations to your NGINX App Protect WAF instances. It can also compile your security configuration into a bundle before publishing it to the data plane. -{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Management Suite with NGINX App Protect Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution" width="75%">}} +The **Security Monitoring** module shows real-time data from NGINX App Protect WAF so you can track traffic, spot anomalies, and fine-tune policies. -### Security Bundle Compilation {#security-bundle} +{{< img src="nim/app-sec-overview.png" caption="Figure 1. NGINX Instance Manager with NGINX App Protect architecture overview" alt="Architecture diagram showing NGINX Instance Manager and Security Monitoring in the control plane pushing security bundles to NGINX App Protect WAF instances in the data plane" >}} -Instance Manager provides a compiler that can be configured to bundle the complete security configuration -- including JSON security policies, attack signatures, threat campaigns, and log profiles -- into a single binary in `.tgz` format. This bundle is then pushed out to each selected NGINX App Protect WAF instance. +### Security bundle compilation {#security-bundle} -Performing the security bundle compilation on Instance Manager (precompiled publication) instead of on the NGINX App Protect WAF instances provides the following benefits: +NGINX Instance Manager includes a compiler that packages your complete WAF configuration β€” security policies, attack signatures, threat campaigns, and log profiles β€” into a single `.tgz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances. -- Eliminates the need to provision system resources on NGINX App Protect WAF instances to perform compilation. -- The bundles produced by Instance Manager can be reused by multiple NGINX App Protect WAF instances, instead of each instance having to perform the compilation separately. +**Why precompile with NGINX Instance Manager?** -However, if you prefer to maintain policy compilation on the NGINX App Protect WAF instance, that is supported with the following limitation: +- Saves system resources on WAF instances +- Lets you reuse the same bundle across multiple instances -- Instance Manager does not publish JSON policies to the NGINX App Protect WAF instance. JSON policies referenced in an NGINX configuration must already exist on the NGINX App Protect WAF instance. +If you choose to compile policies on the WAF instance instead, that works tooβ€”but with this limitation: -The example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) context below enables NGINX App Protect WAF and tells NGINX where to find the compiled security bundle: +- NGINX Instance Manager won’t publish `.json` policies to the WAF instance. These policies must already exist on the instance and be referenced in the NGINX config. -## Log Profile Compilation +Example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) block to enable WAF and point to the bundle: -Instance Manager can also be configured to compile log profiles when you install a new version of the WAF compiler. When you publish an NGINX configuration with the NGINX App Protect [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, Instance Manager publishes the compiled log profiles to the NGINX App Protect WAF instances when precompiled publication is enabled. +```nginx +location / { + app_protect_enable on; + app_protect_policy_file /etc/app_protect/policies/policy_bundle.tgz; +} +``` + +## Log profile compilation + +You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on). {{}} -Instance Manager and Security Monitoring both use NGINX App Protect log profiles. The configuration requirements for each are different. When using Instance Manager configuration management, you must reference the log profile in your NGINX configuration using the `.tgz` file extension instead of `.json`. +NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`. {{}} -## Security Management APIs +## Security management APIs -By using the Instance Manager REST API, you can automate configuration updates to be pushed out to all of your NGINX App Protect WAF instances. You can use the Instance Manager API to manage and deploy the following security configurations: +Use the NGINX Instance Manager REST API to automate updates across your NGINX App Protect WAF instances. You can use the API to manage: -- security policies, -- log profiles, -- attack signatures, and -- threat campaigns. +- Security policies +- Log profiles +- Attack signatures +- Threat campaigns -Just as with changes made via the user interface, the Instance Manager compiler bundles all of the config updates into a single binary package that you can push out to your instances. Figure 2 shows an overview of the API endpoints available to support security policy configuration and publishing. +Just like with the web interface, the compiler creates a binary bundle with your updates that you can push to your WAF instances. -{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Management Suite with NGINX App Protect WAF Architecture Overview" alt="A diagram showing the architecture of the NGINX Management Suite with NGINX App Protect solution">}} +{{< img src="nim/app-sec-api-overview.png" caption="Figure 2. NGINX Instance Manager with NGINX App Protect WAF architecture overview" alt="Diagram showing how the NGINX Instance Manager REST API is used to create policies, upload signatures and campaigns, and publish compiled security bundles to NGINX App Protect WAF instances">}} -More information is available in the Instance Manager API documentation. +For full details, see the API documentation: {{< include "nim/how-to-access-api-docs.md" >}} From 152314a12c65da9fffc7d813abd2cdd2fb06cb87 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Fri, 25 Apr 2025 11:25:38 -0700 Subject: [PATCH 33/63] new messages --- layouts/partials/list-main.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 32f41efa0..cf05906b2 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -44,16 +44,16 @@

      Keep an inventory of your deployments

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} -

      Update them before they expire

      +

      Detect and resolve expired SSL certs in minutes

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

      Secure your systems with role-based access control

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}} -

      Configure and synchronize groups of NGINX instances simultaneously

      +

      Synchronize changes across cloud environments

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}} -

      Automate NGINX fleet management

      +

      Automate NGINX fleet management from the CLI

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Glossary")}}

      Terms unique to NGINX One Console

      From b4d6e87b0059261d921534f383a88624d4347525 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Thu, 15 May 2025 09:48:37 -0700 Subject: [PATCH 34/63] Sync with presentation --- content/nginx-one/secure-your-fleet/_index.md | 6 ++++++ layouts/partials/list-main.html | 13 ++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) create mode 100644 content/nginx-one/secure-your-fleet/_index.md diff --git a/content/nginx-one/secure-your-fleet/_index.md b/content/nginx-one/secure-your-fleet/_index.md new file mode 100644 index 000000000..3d693a250 --- /dev/null +++ b/content/nginx-one/secure-your-fleet/_index.md @@ -0,0 +1,6 @@ +--- +title: Secure your fleet +description: +weight: 250 +url: /nginx-one/secure-your-fleet +--- diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index cf05906b2..4167edd5a 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -19,7 +19,7 @@

      - {{ if or (lt .WordCount 1) (eq $PageTitle "F5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }} + {{ if or (lt .WordCount 1) (eq $PageTitle "fF5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }}
      @@ -32,25 +32,28 @@

      {{ .Title }}

      {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Manage your NGINX fleet")}} -

      Use the F5 NGINX One Console to deploy, scale, or migrate your apps

      +

      Simplify, scale, secure, and collaborate with your NGINX fleet

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Get started")}}

      See benefits from the NGINX One Console

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}} -

      Manage your work-in-progress

      +

      Collaborate with Staged Configurations

      + {{ end }} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Secure your fleet")}} +

      Configure alerts that match your security policies

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

      Keep an inventory of your deployments

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Monitor your certificates")}} -

      Detect and resolve expired SSL certs in minutes

      +

      Update your SSL certs before they expire

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Organize your administrators with RBAC")}}

      Secure your systems with role-based access control

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Change multiple instances with one push")}} -

      Synchronize changes across cloud environments

      +

      Simplify changes with Config Sync Groups

      {{ end }} {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "NGINX One API")}}

      Automate NGINX fleet management from the CLI

      From 2f1692985e75f7409b2030c10098901b04e9acd6 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 21 May 2025 07:28:25 -0700 Subject: [PATCH 35/63] Make more prod ready --- content/nginx-one/secure-your-fleet/_index.md | 6 ------ .../staged-configs/import-export-staged-config.md | 2 +- 2 files changed, 1 insertion(+), 7 deletions(-) delete mode 100644 content/nginx-one/secure-your-fleet/_index.md rename content/nginx-one/{how-to => }/staged-configs/import-export-staged-config.md (97%) diff --git a/content/nginx-one/secure-your-fleet/_index.md b/content/nginx-one/secure-your-fleet/_index.md deleted file mode 100644 index 3d693a250..000000000 --- a/content/nginx-one/secure-your-fleet/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Secure your fleet -description: -weight: 250 -url: /nginx-one/secure-your-fleet ---- diff --git a/content/nginx-one/how-to/staged-configs/import-export-staged-config.md b/content/nginx-one/staged-configs/import-export-staged-config.md similarity index 97% rename from content/nginx-one/how-to/staged-configs/import-export-staged-config.md rename to content/nginx-one/staged-configs/import-export-staged-config.md index 192fad4c4..68993ee99 100644 --- a/content/nginx-one/how-to/staged-configs/import-export-staged-config.md +++ b/content/nginx-one/staged-configs/import-export-staged-config.md @@ -26,7 +26,7 @@ Before you import or export a Staged Configuration to NGINX One Console, ensure: - You have an NGINX One Console account with staged configuration permissions. -You can also import, export, and manage multiple Staged Configurations through [the API]({{< ref "/nginx-one/how-to/staged-configs/api-staged-config.md" >}}). +You can also import, export, and manage multiple Staged Configurations through [the API]({{< ref "/nginx-one/staged-configs/api-staged-config.md" >}}). ## Considerations From b561c0c695fad2dbba1e8ab2e0701197afdeb366 Mon Sep 17 00:00:00 2001 From: Mike Jang <3287976+mjang@users.noreply.github.com> Date: Wed, 21 May 2025 07:28:51 -0700 Subject: [PATCH 36/63] Make more prod ready --- layouts/partials/list-main.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 4167edd5a..628de73e4 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -40,9 +40,9 @@

      {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Set up new instances")}}

      Collaborate with Staged Configurations

      {{ end }} - {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Secure your fleet")}} + {{ if and (eq $PageTitle "F5 NGINX One Console") (eq .Title "Watch your NGINX instances")}}

      Keep an inventory of your deployments

      {{ end }} From a58e6a959afcb89b79c0dda996991ac982ef6cb5 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Thu, 22 May 2025 14:56:56 +0100 Subject: [PATCH 37/63] Agent v3 - update glossary (#579) update glossary --- content/nginx-one/glossary.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/nginx-one/glossary.md b/content/nginx-one/glossary.md index e652705b1..b26a3a8cf 100644 --- a/content/nginx-one/glossary.md +++ b/content/nginx-one/glossary.md @@ -15,9 +15,11 @@ This glossary defines terms used in the F5 NGINX One Console and F5 Distributed | Term | Definition | |-------------|-------------| | **Config Sync Group** | A group of NGINX systems (or instances) with identical configurations. They may also share the same certificates. However, the instances in a Config Sync Group could belong to different systems and even different clusters. For more information, see this explanation of [Important considerations]({{< ref "/nginx-one/how-to/config-sync-groups/manage-config-sync-groups.md#important-considerations" >}}) | +| **Control Plane** | The control plane is the part of a network architecture that manages and controls the flow or data or traffic (the Data Plane). It is responsible for system-level tasks such as routing and traffic management. | | **Data Plane** | The data plane is the part of a network architecture that carries user traffic. It handles tasks like forwarding data packets between devices and managing network communication. In the context of NGINX, the data plane is responsible for tasks such as load balancing, caching, and serving web content. | | **Instance** | An instance is an individual system with NGINX installed. You can group the instances of your choice in a Config Sync Group. When you add an instance to NGINX One, you need to use a data plane key. | | **Namespace** | In F5 Distributed Cloud, a namespace groups a tenant’s configuration objects, similar to administrative domains. Every object in a namespace must have a unique name, and each namespace must be unique to its tenant. This setup ensures isolation, preventing cross-referencing of objects between namespaces. You'll see the namespace in the NGINX One Console URL as `/namespaces//` | +| **NGINX Agent** | A lightweight software component installed on NGINX instances to enable communication with the NGINX One console. | | **Staged Configurations** | Also known as **Staged Configs**. Allows you to save "work in progress." You can create it from scratch, an Instance, another Staged Config, or a Config Sync Group. It does _not_ have to be a working configuration until you publish it to an instance or a Config Sync Group. You can even manage your **Staged Configurations** through our [API]({{< ref "/nginx-one/api/api-reference-guide/#tag/StagedConfigs" >}}). | | **Tenant** | A tenant in F5 Distributed Cloud is an entity that owns a specific set of configuration and infrastructure. It is fundamental for isolation, meaning a tenant cannot access objects or infrastructure of other tenants. Tenants can be either individual or enterprise, with the latter allowing multiple users with role-based access control (RBAC). | {{}} From c21614fa2a15355f1fb9e9e38780fe5de9b58a43 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Thu, 22 May 2025 16:06:56 +0100 Subject: [PATCH 38/63] NGINX One and Agent v3 docs improvements based on feedback (#581) * fix n1 broken link * N1 and Agent updates --- content/nginx-one/getting-started.md | 2 +- content/nginx-one/how-to/nginx-configs/add-file.md | 4 ++-- content/nginx-one/how-to/nginx-configs/add-instance.md | 10 +++++----- .../nginx-configs/clean-up-unavailable-instances.md | 2 +- .../how-to/nginx-configs/manage-config-sync-groups.md | 6 +++--- .../nginx-configs/view-edit-nginx-configurations.md | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/content/nginx-one/getting-started.md b/content/nginx-one/getting-started.md index 65279befd..b37dd4d73 100644 --- a/content/nginx-one/getting-started.md +++ b/content/nginx-one/getting-started.md @@ -130,7 +130,7 @@ The NGINX One Console dashboard relies on APIs for NGINX Plus and NGINX Open Sou ### Enable NGINX Plus API -To collect metrics for NGINX Plus, add the following to your NGINX Plus configuration file: +To collect metrics for NGINX Plus, add the following to your NGINX Plus configuration file, `nginx.conf`: ```nginx # Enable the /api/ location with appropriate access control diff --git a/content/nginx-one/how-to/nginx-configs/add-file.md b/content/nginx-one/how-to/nginx-configs/add-file.md index 7b654d86e..f67b989b8 100644 --- a/content/nginx-one/how-to/nginx-configs/add-file.md +++ b/content/nginx-one/how-to/nginx-configs/add-file.md @@ -15,8 +15,8 @@ type: Before you add files in your configuration, ensure: -- You have access to the NGINX One Console. -- NGINX instances are properly registered with NGINX One Console +- You have [access to the NGINX One Console]({{< ref "/nginx-one/rbac/roles.md" >}}). +- NGINX instances are [properly registered]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) with NGINX One Console. ## Important considerations diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md index fd155519c..ce52382fb 100644 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ b/content/nginx-one/how-to/nginx-configs/add-instance.md @@ -16,10 +16,10 @@ to set up a data plane key to connect your instances to NGINX One. Before you add an instance to NGINX One Console, ensure: -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. +- You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. +- You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. +- You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). +- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}). {{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} @@ -33,7 +33,7 @@ If you add an instance with SSL/TLS certificates, those certificates can match a ### If the certificate is already managed -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One], these certificates are added to your list of **Managed Certificates**. +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. NGINX One Console can manage your instances along with those certificates. diff --git a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md index 6a119617d..d381ee3dd 100644 --- a/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md +++ b/content/nginx-one/how-to/nginx-configs/clean-up-unavailable-instances.md @@ -16,7 +16,7 @@ This guide explains how to set up automatic cleanup for NGINX instances in NGINX Before you set up automatic cleanup for NGINX instances, ensure: -- You have administrator access to NGINX One. +- You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. - You understand that this action will delete instances permanently after they are unavailable for the specified duration. ## Configure instance cleanup diff --git a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md b/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md index 8bc10cce6..3cdbc49d6 100644 --- a/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md +++ b/content/nginx-one/how-to/nginx-configs/manage-config-sync-groups.md @@ -17,9 +17,9 @@ If you’ve used [instance groups in NGINX Instance Manager]({{< ref "/nim/nginx Before you create and manage config sync groups, ensure: -- You have access to the NGINX One Console. -- You have the necessary permissions to create and manage config sync groups. -- NGINX instances are properly registered with NGINX One if you plan to add existing instances to a config sync group. +- You have [access to the NGINX One Console]({{< ref "/nginx-one/rbac/roles.md" >}}). +- You have the [necessary permissions to create and manage config sync groups]({{< ref "/nginx-one/rbac/roles.md" >}}). +- NGINX instances are [properly registered]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) with NGINX One Console, if you plan to add existing instances to a config sync group. ## Important considerations diff --git a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md index 37d4fb6f5..d1ece74c1 100644 --- a/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md +++ b/content/nginx-one/how-to/nginx-configs/view-edit-nginx-configurations.md @@ -20,7 +20,7 @@ This guide explains how to add a **Instances** to your NGINX One Console. Before you add **Instances** to NGINX One Console, ensure: -- You have an NGINX One Console account with staged configuration permissions.``` +- You have an NGINX One Console account [with staged configuration permissions]({{< ref "/nginx-one/rbac/roles.md" >}}). Once you've registered your NGINX Instances with the F5 NGINX One Console, you can view and edit their NGINX configurations on the **Instances** details page. From c94d883f493c670ff8f27dfed0b1d5478cdaae17 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 23 May 2025 13:18:28 +0100 Subject: [PATCH 39/63] fix: broken links after N1 docs changes --- content/includes/agent/installation/update-container.md | 2 +- content/nginx-one/agent/configure-otel-metrics.md | 2 +- .../nginx-one/agent/install-upgrade/install-from-github.md | 4 ++-- .../nginx-one/agent/install-upgrade/install-from-oss-repo.md | 2 +- .../nginx-one/agent/install-upgrade/install-from-plus-repo.md | 2 +- content/nginx-one/nginx-configs/add-instance.md | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index 09c8090e7..5777ac137 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -15,7 +15,7 @@ wget https://raw.githubusercontent.com/nginx/agent/refs/heads/v3/scripts/package ``` 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. +See [Add Config Sync Group]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. ### Rolling back from NGINX Agent v3 to v2 diff --git a/content/nginx-one/agent/configure-otel-metrics.md b/content/nginx-one/agent/configure-otel-metrics.md index 796897346..62b857f33 100644 --- a/content/nginx-one/agent/configure-otel-metrics.md +++ b/content/nginx-one/agent/configure-otel-metrics.md @@ -26,7 +26,7 @@ You can validate that metrics are successfully exported by using the methods bel - **NGINX One dashboard** - - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. + - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. - **Agent logs** diff --git a/content/nginx-one/agent/install-upgrade/install-from-github.md b/content/nginx-one/agent/install-upgrade/install-from-github.md index 3438a02ba..cfff1bba5 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-github.md +++ b/content/nginx-one/agent/install-upgrade/install-from-github.md @@ -5,12 +5,12 @@ weight: 300 docs: DOCS-000 --- -{{< note>}} +{{< note >}} If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}}) to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) {{< /note >}} Follow the steps in this guide to install NGINX Agent in your NGINX instance using diff --git a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md index d05eda965..c794bb68b 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md @@ -10,7 +10,7 @@ If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}} to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) {{< /note >}} ## Overview diff --git a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md index 5617b2941..a328b28ee 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md @@ -10,7 +10,7 @@ If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}} to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/how-to/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) {{< /note >}} ## Overview diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md index d0ede592d..fd3b70fd5 100644 --- a/content/nginx-one/nginx-configs/add-instance.md +++ b/content/nginx-one/nginx-configs/add-instance.md @@ -19,7 +19,7 @@ Before you add an instance to NGINX One Console, ensure: - You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. - You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. - You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). -- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/how-to/certificates/manage-certificates.md" >}}). +- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). {{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} From 8445dc028611515c4e7e4c7cd7c89a5f314c8e1a Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:25:53 +0100 Subject: [PATCH 40/63] Update content/includes/agent/about.md Co-authored-by: yar --- content/includes/agent/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/about.md b/content/includes/agent/about.md index 4125fd568..a12346425 100644 --- a/content/includes/agent/about.md +++ b/content/includes/agent/about.md @@ -18,7 +18,7 @@ Enable Access to key NGINX One use cases: 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. + instances, improving decision-making and operational efficiency. - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/), and the ability to [export the metrics data]({{< ref "/nginx-one/agent/configure-otel-metrics.md" >}}) for use in other applications. From 7c9efe88f04579adbe2d541d9fbe6a8ce79588af Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:26:13 +0100 Subject: [PATCH 41/63] Update content/includes/agent/about.md Co-authored-by: yar --- content/includes/agent/about.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/about.md b/content/includes/agent/about.md index a12346425..526ecdeed 100644 --- a/content/includes/agent/about.md +++ b/content/includes/agent/about.md @@ -19,7 +19,7 @@ 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. - - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/), and the ability to + - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/) and the ability to [export the metrics data]({{< ref "/nginx-one/agent/configure-otel-metrics.md" >}}) for use in other applications. From d57db93ad664b2a7e328d82d1507d38706c63d2f Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:26:21 +0100 Subject: [PATCH 42/63] Update content/includes/agent/architecture.md Co-authored-by: yar --- content/includes/agent/architecture.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/architecture.md b/content/includes/agent/architecture.md index 752cc19b6..56da20585 100644 --- a/content/includes/agent/architecture.md +++ b/content/includes/agent/architecture.md @@ -16,7 +16,7 @@ The figure shows: - An NGINX Agent process running on the NGINX instance. NGINX Agent is responsible for: - Watching, applying, validating, automatically roll back to last good configuration if issues are detected. - - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to NGINX One Cloud Console. + - Embedding an OpenTelemetry Collector, collecting metrics from NGINX processes, host system performance data, then securely passing metric data to NGINX One Cloud Console. - Collection and monitoring of host metrics (CPU usage, Memory utilization, Disk I/O) by the Agent OTel collector. - Collected data is made available on NGINX One Cloud Console for monitoring, alerting, troubleshooting, and capacity planning purposes. From 4f54f397083fca0013e8a78ee0413cc594ec7302 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:26:40 +0100 Subject: [PATCH 43/63] Update content/includes/agent/installation/oss/oss-debian.md Co-authored-by: yar --- content/includes/agent/installation/oss/oss-debian.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/oss/oss-debian.md b/content/includes/agent/installation/oss/oss-debian.md index 193de20f0..0a8a14fdb 100644 --- a/content/includes/agent/installation/oss/oss-debian.md +++ b/content/includes/agent/installation/oss/oss-debian.md @@ -30,7 +30,7 @@ files: as follows: ``` - pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 uid nginx signing key ``` From 079736ddf458392d9f06cfb9fc54a700add7d6ce Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:26:57 +0100 Subject: [PATCH 44/63] Update content/includes/agent/installation/oss/oss-sles.md Co-authored-by: yar --- content/includes/agent/installation/oss/oss-sles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/oss/oss-sles.md b/content/includes/agent/installation/oss/oss-sles.md index 3b41818c8..1d64a86de 100644 --- a/content/includes/agent/installation/oss/oss-sles.md +++ b/content/includes/agent/installation/oss/oss-sles.md @@ -34,7 +34,7 @@ package's authenticity. Fetch the 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] + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 uid nginx signing key ``` From d6f0ff8386af1946c5a1fb30d1067cd06eca0a45 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:27:09 +0100 Subject: [PATCH 45/63] Update content/includes/agent/installation/oss/oss-ubuntu.md Co-authored-by: yar --- content/includes/agent/installation/oss/oss-ubuntu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/oss/oss-ubuntu.md b/content/includes/agent/installation/oss/oss-ubuntu.md index e07b25b0e..78b900fbb 100644 --- a/content/includes/agent/installation/oss/oss-ubuntu.md +++ b/content/includes/agent/installation/oss/oss-ubuntu.md @@ -27,7 +27,7 @@ files: The output should contain the full fingerprint `573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62` as follows: ``` - pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 uid nginx signing key ``` From 6c8ed3cfa6c7194fa85487606cc4d927b83daefd Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:27:49 +0100 Subject: [PATCH 46/63] Update content/includes/agent/installation/plus/plus-sles.md Co-authored-by: yar --- content/includes/agent/installation/plus/plus-sles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/includes/agent/installation/plus/plus-sles.md b/content/includes/agent/installation/plus/plus-sles.md index 324a4769b..450443796 100644 --- a/content/includes/agent/installation/plus/plus-sles.md +++ b/content/includes/agent/installation/plus/plus-sles.md @@ -57,7 +57,7 @@ files: `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62` as follows: ```none - pub rsa2048 2011-08-19 [SC] [expires: 2024-06-14] + pub rsa2048 2011-08-19 [SC] [expires: 2027-05-24] 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 uid nginx signing key ``` From 9b0e746c2a797f3a087b0d4a3616bbe1eb025144 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:28:02 +0100 Subject: [PATCH 47/63] Update content/nginx-one/agent/community.md Co-authored-by: yar --- content/nginx-one/agent/community.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/agent/community.md b/content/nginx-one/agent/community.md index 013d2e302..ddaa1a6cb 100644 --- a/content/nginx-one/agent/community.md +++ b/content/nginx-one/agent/community.md @@ -13,7 +13,7 @@ Discover the various ways you can participate in the F5 NGINX Agent project: ## Contribute -Get involved with the project by contributing! Please see our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details. +Get involved with the project by contributing! See our [contributing guide](https://github.com/nginx/agent/blob/main/CONTRIBUTING.md) for details. ## License From 772db2482bc3afa6b6e14e850479f8ce90eb9c4e Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:28:11 +0100 Subject: [PATCH 48/63] Update content/nginx-one/agent/configure-otel-metrics.md Co-authored-by: yar --- content/nginx-one/agent/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/agent/configure-otel-metrics.md b/content/nginx-one/agent/configure-otel-metrics.md index 62b857f33..30eafdbed 100644 --- a/content/nginx-one/agent/configure-otel-metrics.md +++ b/content/nginx-one/agent/configure-otel-metrics.md @@ -9,7 +9,7 @@ toc: true F5 NGINX Agent 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 Open Source -* Host metrics (CPU, memory, disk, and network activity) from VMs or Containers +* Host metrics (CPU, memory, disk, and network activity) from VMs or Containers {{< note >}} The OpenTelemetry exporter is enabled by default. Once a valid connection to the management plane is established, the Agent will automatically begin exporting metrics. From fa381e8c3590e240d56c6831dc27fc34eafb2e45 Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Fri, 23 May 2025 13:28:20 +0100 Subject: [PATCH 49/63] Update content/nginx-one/agent/configure-otel-metrics.md Co-authored-by: yar --- content/nginx-one/agent/configure-otel-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/agent/configure-otel-metrics.md b/content/nginx-one/agent/configure-otel-metrics.md index 30eafdbed..094c03adc 100644 --- a/content/nginx-one/agent/configure-otel-metrics.md +++ b/content/nginx-one/agent/configure-otel-metrics.md @@ -32,7 +32,7 @@ You can validate that metrics are successfully exported by using the methods bel Check the OpenTelemetry Collector logs for confirmation of successful metric processing: - 1. Open the file: ```/var/log/nginx-agent/opentelemetry-collector-agent.log``` + 1. Open the file: `/var/log/nginx-agent/opentelemetry-collector-agent.log` 2. Look for the following logs: ```text From 275f631b80efd8f75fd94816e41acfa0c028690c Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 23 May 2025 13:36:16 +0100 Subject: [PATCH 50/63] fix conflicts --- .../how-to/nginx-configs/add-instance.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md new file mode 100644 index 000000000..8bae0ef02 --- /dev/null +++ b/content/nginx-one/how-to/nginx-configs/add-instance.md @@ -0,0 +1,75 @@ +--- +description: '' +title: Add an NGINX instance +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need +to set up a data plane key to connect your instances to NGINX One. + +## Before you start + +Before you add an instance to NGINX One Console, ensure: + +- You have administrator access to NGINX One Console. +- You have configured instances of NGINX that you want to manage through NGINX One Console. +- You have or are ready to configure a data plane key. +- You have or are ready to set up managed certificates. + +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} + +## Add an instance + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. + +## Managed and Unmanaged Certificates + +If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. + +### If the certificate is already managed + +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. + +NGINX One Console can manage your instances along with those certificates. + +### If the certificate is not managed + +These certificates appear in the list of **Unmanaged Certificates**. + +To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. + +To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + +Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. + +## Add an instance to a Config Sync Group + +When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +That instance inherits the setup of that Config Sync Group. From bc32d6f66b0ec54f0bbdc484ee5f29feaae71d71 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 23 May 2025 13:37:09 +0100 Subject: [PATCH 51/63] remove file that moved (fix conflicts) --- .../how-to/nginx-configs/add-instance.md | 75 ------------------- 1 file changed, 75 deletions(-) delete mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md deleted file mode 100644 index 8bae0ef02..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: '' -title: Add an NGINX instance -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need -to set up a data plane key to connect your instances to NGINX One. - -## Before you start - -Before you add an instance to NGINX One Console, ensure: - -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} - -## Add an instance - -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. - -## Managed and Unmanaged Certificates - -If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. - -### If the certificate is already managed - -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. - -NGINX One Console can manage your instances along with those certificates. - -### If the certificate is not managed - -These certificates appear in the list of **Unmanaged Certificates**. - -To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. - -To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - -Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. - -## Add an instance to a Config Sync Group - -When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -That instance inherits the setup of that Config Sync Group. From 2d51addd52c51e2dfa441d9a52594be48a5880c9 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 23 May 2025 13:38:04 +0100 Subject: [PATCH 52/63] recover file to fix conflicts with main --- .../how-to/nginx-configs/add-instance.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md new file mode 100644 index 000000000..8bae0ef02 --- /dev/null +++ b/content/nginx-one/how-to/nginx-configs/add-instance.md @@ -0,0 +1,75 @@ +--- +description: '' +title: Add an NGINX instance +toc: true +weight: 100 +type: +- how-to +--- + +## Overview + +This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need +to set up a data plane key to connect your instances to NGINX One. + +## Before you start + +Before you add an instance to NGINX One Console, ensure: + +- You have administrator access to NGINX One Console. +- You have configured instances of NGINX that you want to manage through NGINX One Console. +- You have or are ready to configure a data plane key. +- You have or are ready to set up managed certificates. + +{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} + +## Add an instance + +You can add an instance to NGINX One Console in the following ways: + +- Directly, under **Instances** +- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** + +In either case, NGINX One Console gives you a choice for data plane keys: + +- Create a new key +- Use an existing key + +NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. + +Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. + +```bash +curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y +``` + +Once the process is complete, you can configure that instance in your NGINX One Console. + +## Managed and Unmanaged Certificates + +If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. + +### If the certificate is already managed + +If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. + +NGINX One Console can manage your instances along with those certificates. + +### If the certificate is not managed + +These certificates appear in the list of **Unmanaged Certificates**. + +To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. + +To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: + +- Select a certificate +- Select **Convert to Managed** +- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section + +Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. + +## Add an instance to a Config Sync Group + +When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. +That instance inherits the setup of that Config Sync Group. From 546524db549c9c62d7afbe565f692746eb3f62f6 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 23 May 2025 13:38:59 +0100 Subject: [PATCH 53/63] remove add-instance.md (moved) --- .../how-to/nginx-configs/add-instance.md | 75 ------------------- 1 file changed, 75 deletions(-) delete mode 100644 content/nginx-one/how-to/nginx-configs/add-instance.md diff --git a/content/nginx-one/how-to/nginx-configs/add-instance.md b/content/nginx-one/how-to/nginx-configs/add-instance.md deleted file mode 100644 index 8bae0ef02..000000000 --- a/content/nginx-one/how-to/nginx-configs/add-instance.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -description: '' -title: Add an NGINX instance -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need -to set up a data plane key to connect your instances to NGINX One. - -## Before you start - -Before you add an instance to NGINX One Console, ensure: - -- You have administrator access to NGINX One Console. -- You have configured instances of NGINX that you want to manage through NGINX One Console. -- You have or are ready to configure a data plane key. -- You have or are ready to set up managed certificates. - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} - -## Add an instance - -You can add an instance to NGINX One Console in the following ways: - -- Directly, under **Instances** -- Indirectly, by selecting a Config Sync Group, and selecting **Add Instance to Config Sync Group** - -In either case, NGINX One Console gives you a choice for data plane keys: - -- Create a new key -- Use an existing key - -NGINX One Console takes the option you use, and adds the data plane key to a command that you'd use to register your target instance. You should see the command in the **Add Instance** screen in the console. - -Connect to the host where your NGINX instance is running. Run the provided command to [install NGINX Agent]({{< ref "/nginx-one/getting-started#install-nginx-agent" >}}) dependencies and packages on that host. - -```bash -curl https://agent.connect.nginx.com/nginx-agent/install | DATA_PLANE_KEY="" sh -s -- -y -``` - -Once the process is complete, you can configure that instance in your NGINX One Console. - -## Managed and Unmanaged Certificates - -If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. - -### If the certificate is already managed - -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. - -NGINX One Console can manage your instances along with those certificates. - -### If the certificate is not managed - -These certificates appear in the list of **Unmanaged Certificates**. - -To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. - -To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - -Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. - -## Add an instance to a Config Sync Group - -When you [Manage Config Sync Group membership]({{< ref "nginx-one/how-to/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -That instance inherits the setup of that Config Sync Group. From 0a913deaf52e041e7ad05381e937e6d0106c2fea Mon Sep 17 00:00:00 2001 From: Jon Torre <78599298+JTorreG@users.noreply.github.com> Date: Wed, 28 May 2025 10:17:43 +0100 Subject: [PATCH 54/63] Agent v3 IA changes (#601) --- content/includes/agent/about.md | 4 ++-- content/includes/agent/architecture.md | 2 +- .../installation/manually-connect-to-console.md | 8 ++++++++ .../includes/agent/installation/oss/oss-alpine.md | 2 +- .../agent/installation/oss/oss-amazon-linux.md | 2 +- .../includes/agent/installation/oss/oss-debian.md | 2 +- .../includes/agent/installation/oss/oss-freebsd.md | 2 +- content/includes/agent/installation/oss/oss-rhel.md | 2 +- content/includes/agent/installation/oss/oss-sles.md | 2 +- .../includes/agent/installation/oss/oss-ubuntu.md | 2 +- .../includes/agent/installation/plus/plus-alpine.md | 2 +- .../agent/installation/plus/plus-amazon-linux.md | 2 +- .../includes/agent/installation/plus/plus-debian.md | 2 +- .../includes/agent/installation/plus/plus-freebsd.md | 2 +- .../includes/agent/installation/plus/plus-rhel.md | 2 +- .../includes/agent/installation/plus/plus-sles.md | 2 +- .../includes/agent/installation/plus/plus-ubuntu.md | 2 +- content/includes/agent/installation/prerequisites.md | 6 +++--- .../includes/agent/installation/start-stop-agent.md | 4 ++-- .../agent/installation/uninstall/uninstall-alpine.md | 2 +- .../installation/uninstall/uninstall-amazon-linux.md | 2 +- .../agent/installation/uninstall/uninstall-debian.md | 2 +- .../installation/uninstall/uninstall-freebsd.md | 2 +- .../agent/installation/uninstall/uninstall-rhel.md | 2 +- .../agent/installation/uninstall/uninstall-sles.md | 2 +- .../agent/installation/uninstall/uninstall-ubuntu.md | 2 +- .../includes/agent/installation/update-container.md | 2 +- content/includes/agent/installation/update.md | 2 +- content/includes/agent/installation/verify-agent.md | 4 ++-- content/includes/agent/tech-specs.md | 2 +- content/includes/agent/v3-available.md | 12 ++++++++++++ content/nginx-one/agent/changelog.md | 8 +++++--- content/nginx-one/agent/community/_index.md | 5 +++++ content/nginx-one/agent/{ => community}/community.md | 0 .../agent/configure-instance-reporting/_index.md | 5 +++++ .../configuration-overview.md | 0 .../configure-agent-group.md | 0 content/nginx-one/agent/containers/_index.md | 5 +++++ .../{how-to => containers}/run-agent-container.md | 2 +- content/nginx-one/agent/how-to/_index.md | 5 ----- content/nginx-one/agent/install-upgrade/_index.md | 4 ++-- content/nginx-one/agent/metrics/_index.md | 5 +++++ .../agent/{ => metrics}/configure-otel-metrics.md | 0 content/nginx-one/agent/overview/_index.md | 5 +++++ content/nginx-one/agent/{ => overview}/about.md | 8 ++------ content/nginx-one/agent/{ => overview}/tech-specs.md | 2 +- content/nginx-one/agent/support/_index.md | 5 +++++ .../nginx-one/agent/{ => support}/troubleshooting.md | 0 48 files changed, 95 insertions(+), 52 deletions(-) create mode 100644 content/includes/agent/v3-available.md create mode 100644 content/nginx-one/agent/community/_index.md rename content/nginx-one/agent/{ => community}/community.md (100%) create mode 100644 content/nginx-one/agent/configure-instance-reporting/_index.md rename content/nginx-one/agent/{how-to => configure-instance-reporting}/configuration-overview.md (100%) rename content/nginx-one/agent/{how-to => configure-instance-reporting}/configure-agent-group.md (100%) create mode 100644 content/nginx-one/agent/containers/_index.md rename content/nginx-one/agent/{how-to => containers}/run-agent-container.md (99%) delete mode 100644 content/nginx-one/agent/how-to/_index.md create mode 100644 content/nginx-one/agent/metrics/_index.md rename content/nginx-one/agent/{ => metrics}/configure-otel-metrics.md (100%) create mode 100644 content/nginx-one/agent/overview/_index.md rename content/nginx-one/agent/{ => overview}/about.md (84%) rename content/nginx-one/agent/{ => overview}/tech-specs.md (90%) create mode 100644 content/nginx-one/agent/support/_index.md rename content/nginx-one/agent/{ => support}/troubleshooting.md (100%) diff --git a/content/includes/agent/about.md b/content/includes/agent/about.md index 526ecdeed..e23de8922 100644 --- a/content/includes/agent/about.md +++ b/content/includes/agent/about.md @@ -2,7 +2,7 @@ docs: files: - content/agent/about.md - - content/nginx-one/agent/about.md + - content/nginx-one/agent/overview/about.md --- F5 NGINX Agent is a lightweight companion daemon designed to work with NGINX One and enable remote management of NGINX instances. It also gathers performance metrics from NGINX and transmits them to the NGINX One Console for enhanced monitoring and control. @@ -20,7 +20,7 @@ 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. - NGINX Agent supports [OpenTelemetry](https://opentelemetry.io/) and the ability to - [export the metrics data]({{< ref "/nginx-one/agent/configure-otel-metrics.md" >}}) for use in other applications. + [export the metrics data]({{< ref "/nginx-one/agent/metrics/configure-otel-metrics.md" >}}) for use in other applications. diff --git a/content/includes/agent/architecture.md b/content/includes/agent/architecture.md index 56da20585..d09a138be 100644 --- a/content/includes/agent/architecture.md +++ b/content/includes/agent/architecture.md @@ -2,7 +2,7 @@ docs: files: - content/agent/about.md - - content/nginx-one/agent/about.md + - content/nginx-one/agent/overview/about.md --- The figure shows: diff --git a/content/includes/agent/installation/manually-connect-to-console.md b/content/includes/agent/installation/manually-connect-to-console.md index 065990a75..dc00015bd 100644 --- a/content/includes/agent/installation/manually-connect-to-console.md +++ b/content/includes/agent/installation/manually-connect-to-console.md @@ -1,3 +1,11 @@ +--- +docs: +files: + - content/nginx-one/agent/install-upgrade/install-from-github.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md +--- + If you have installed NGINX Agent manually, you will need to connect it to the NGINX One Console to manage your NGINX instances. diff --git a/content/includes/agent/installation/oss/oss-alpine.md b/content/includes/agent/installation/oss/oss-alpine.md index a0782cd2e..41f4d734a 100644 --- a/content/includes/agent/installation/oss/oss-alpine.md +++ b/content/includes/agent/installation/oss/oss-alpine.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/oss/oss-amazon-linux.md b/content/includes/agent/installation/oss/oss-amazon-linux.md index 759cc06ce..3a3f326b8 100644 --- a/content/includes/agent/installation/oss/oss-amazon-linux.md +++ b/content/includes/agent/installation/oss/oss-amazon-linux.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/oss/oss-debian.md b/content/includes/agent/installation/oss/oss-debian.md index 0a8a14fdb..1d8913352 100644 --- a/content/includes/agent/installation/oss/oss-debian.md +++ b/content/includes/agent/installation/oss/oss-debian.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/oss/oss-freebsd.md b/content/includes/agent/installation/oss/oss-freebsd.md index 50e123295..31014d5e1 100644 --- a/content/includes/agent/installation/oss/oss-freebsd.md +++ b/content/includes/agent/installation/oss/oss-freebsd.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. To setup the pkg repository create a file with name `/etc/pkg/nginx-agent.conf` diff --git a/content/includes/agent/installation/oss/oss-rhel.md b/content/includes/agent/installation/oss/oss-rhel.md index dfef423b5..50ae65222 100644 --- a/content/includes/agent/installation/oss/oss-rhel.md +++ b/content/includes/agent/installation/oss/oss-rhel.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/oss/oss-sles.md b/content/includes/agent/installation/oss/oss-sles.md index 1d64a86de..d6e41c15d 100644 --- a/content/includes/agent/installation/oss/oss-sles.md +++ b/content/includes/agent/installation/oss/oss-sles.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/oss/oss-ubuntu.md b/content/includes/agent/installation/oss/oss-ubuntu.md index 78b900fbb..b1f5127c9 100644 --- a/content/includes/agent/installation/oss/oss-ubuntu.md +++ b/content/includes/agent/installation/oss/oss-ubuntu.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-oss-repo.md - - content/nginx-one/agent/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md --- 1. Install the prerequisites: diff --git a/content/includes/agent/installation/plus/plus-alpine.md b/content/includes/agent/installation/plus/plus-alpine.md index 8dad45834..6b07cae37 100644 --- a/content/includes/agent/installation/plus/plus-alpine.md +++ b/content/includes/agent/installation/plus/plus-alpine.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download diff --git a/content/includes/agent/installation/plus/plus-amazon-linux.md b/content/includes/agent/installation/plus/plus-amazon-linux.md index f419b6341..505c5c910 100644 --- a/content/includes/agent/installation/plus/plus-amazon-linux.md +++ b/content/includes/agent/installation/plus/plus-amazon-linux.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/plus/plus-debian.md b/content/includes/agent/installation/plus/plus-debian.md index 255728a8b..81e453656 100644 --- a/content/includes/agent/installation/plus/plus-debian.md +++ b/content/includes/agent/installation/plus/plus-debian.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/plus/plus-freebsd.md b/content/includes/agent/installation/plus/plus-freebsd.md index e92cec069..3cb6442e8 100644 --- a/content/includes/agent/installation/plus/plus-freebsd.md +++ b/content/includes/agent/installation/plus/plus-freebsd.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/plus/plus-rhel.md b/content/includes/agent/installation/plus/plus-rhel.md index bbd9fdb04..8db68e5aa 100644 --- a/content/includes/agent/installation/plus/plus-rhel.md +++ b/content/includes/agent/installation/plus/plus-rhel.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/plus/plus-sles.md b/content/includes/agent/installation/plus/plus-sles.md index 450443796..d9e1cd3f0 100644 --- a/content/includes/agent/installation/plus/plus-sles.md +++ b/content/includes/agent/installation/plus/plus-sles.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/plus/plus-ubuntu.md b/content/includes/agent/installation/plus/plus-ubuntu.md index 7b11d588c..e14f84ee7 100644 --- a/content/includes/agent/installation/plus/plus-ubuntu.md +++ b/content/includes/agent/installation/plus/plus-ubuntu.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- 1. Create the `/etc/ssl/nginx` directory: diff --git a/content/includes/agent/installation/prerequisites.md b/content/includes/agent/installation/prerequisites.md index 6b7b039ca..9a91bf9cb 100644 --- a/content/includes/agent/installation/prerequisites.md +++ b/content/includes/agent/installation/prerequisites.md @@ -4,10 +4,10 @@ files: - content/agent/install-upgrade/install-from-github.md - content/agent/install-upgrade/install-from-oss-repo.md - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-oss-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- -- You must use one of the [supported operating system and architectures]({{< ref "/nginx-one/agent/tech-specs.md#supported-distributions" >}}) +- You must use one of the [supported operating system and architectures]({{< ref "/nginx-one/agent/overview/tech-specs.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. \ No newline at end of file diff --git a/content/includes/agent/installation/start-stop-agent.md b/content/includes/agent/installation/start-stop-agent.md index eaebad911..fdbbbce62 100644 --- a/content/includes/agent/installation/start-stop-agent.md +++ b/content/includes/agent/installation/start-stop-agent.md @@ -4,8 +4,8 @@ files: - content/agent/install-upgrade/install-from-github.md - content/agent/install-upgrade/install-from-oss-repo.md - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-oss-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- To start NGINX Agent on `systemd` systems, run the following command: diff --git a/content/includes/agent/installation/uninstall/uninstall-alpine.md b/content/includes/agent/installation/uninstall/uninstall-alpine.md index eff48cdc6..47e6e8d7c 100644 --- a/content/includes/agent/installation/uninstall/uninstall-alpine.md +++ b/content/includes/agent/installation/uninstall/uninstall-alpine.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md b/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md index 0bffabb06..8fc2c7eab 100644 --- a/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md +++ b/content/includes/agent/installation/uninstall/uninstall-amazon-linux.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-debian.md b/content/includes/agent/installation/uninstall/uninstall-debian.md index 15a0d473d..5a25674d5 100644 --- a/content/includes/agent/installation/uninstall/uninstall-debian.md +++ b/content/includes/agent/installation/uninstall/uninstall-debian.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX Agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-freebsd.md b/content/includes/agent/installation/uninstall/uninstall-freebsd.md index 0311d1d24..ef18d978b 100644 --- a/content/includes/agent/installation/uninstall/uninstall-freebsd.md +++ b/content/includes/agent/installation/uninstall/uninstall-freebsd.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-rhel.md b/content/includes/agent/installation/uninstall/uninstall-rhel.md index 0e12df126..4d0a01405 100644 --- a/content/includes/agent/installation/uninstall/uninstall-rhel.md +++ b/content/includes/agent/installation/uninstall/uninstall-rhel.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX Agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-sles.md b/content/includes/agent/installation/uninstall/uninstall-sles.md index f65237753..c46fef3d9 100644 --- a/content/includes/agent/installation/uninstall/uninstall-sles.md +++ b/content/includes/agent/installation/uninstall/uninstall-sles.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX Agent: diff --git a/content/includes/agent/installation/uninstall/uninstall-ubuntu.md b/content/includes/agent/installation/uninstall/uninstall-ubuntu.md index 15a0d473d..5a25674d5 100644 --- a/content/includes/agent/installation/uninstall/uninstall-ubuntu.md +++ b/content/includes/agent/installation/uninstall/uninstall-ubuntu.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/uninstall.md - - content/nginx-one/agent/uninstall.md + - content/nginx-one/agent/install-upgrade/uninstall.md --- Complete the following steps on each host where you've installed NGINX Agent: diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index 5777ac137..a18f5894e 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/update.md - - content/nginx-one/agent/update.md + - content/nginx-one/agent/install-upgrade/update.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) diff --git a/content/includes/agent/installation/update.md b/content/includes/agent/installation/update.md index c2df47c4f..6b6834ae7 100644 --- a/content/includes/agent/installation/update.md +++ b/content/includes/agent/installation/update.md @@ -2,7 +2,7 @@ docs: files: - content/agent/install-upgrade/update.md - - content/nginx-one/agent/update.md + - content/nginx-one/agent/install-upgrade/update.md --- diff --git a/content/includes/agent/installation/verify-agent.md b/content/includes/agent/installation/verify-agent.md index c41caa8fc..77facea04 100644 --- a/content/includes/agent/installation/verify-agent.md +++ b/content/includes/agent/installation/verify-agent.md @@ -4,8 +4,8 @@ files: - content/agent/install-upgrade/install-from-github.md - content/agent/install-upgrade/install-from-oss-repo.md - content/agent/install-upgrade/install-from-plus-repo.md - - content/nginx-one/agent/install-from-oss-repo.md - - content/nginx-one/agent/install-from-plus-repo.md + - content/nginx-one/agent/install-upgrade/install-from-oss-repo.md + - content/nginx-one/agent/install-upgrade/install-from-plus-repo.md --- Once you have installed NGINX Agent, you can verify that it is running with the diff --git a/content/includes/agent/tech-specs.md b/content/includes/agent/tech-specs.md index cc0e05792..129745c66 100644 --- a/content/includes/agent/tech-specs.md +++ b/content/includes/agent/tech-specs.md @@ -2,7 +2,7 @@ docs: files: - content/agent/tech-specs.md - - content/nginx-one/agent/tech-specs.md + - content/nginx-one/agent/overview/tech-specs.md --- NGINX Agent is designed to operate efficiently on any system that meets the standard diff --git a/content/includes/agent/v3-available.md b/content/includes/agent/v3-available.md new file mode 100644 index 000000000..66e5baff6 --- /dev/null +++ b/content/includes/agent/v3-available.md @@ -0,0 +1,12 @@ +--- +docs: +files: + - content/nginx-one/agent/overview/about.md + - content/nginx-one/agent/changelog.md +--- + +{{}} +NGINX Agent v3.0 is a major release that introduces new features and enhancements. + +Visit our [Update]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. +{{}} \ No newline at end of file diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md index f4514e16d..48677848e 100644 --- a/content/nginx-one/agent/changelog.md +++ b/content/nginx-one/agent/changelog.md @@ -1,16 +1,18 @@ --- -title: "NGINX Agent Changelog" -weight: 700 +title: "NGINX Agent changelog" +weight: 10000 toc: true --- {{< 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]({{< ref "/nginx-one/agent/tech-specs.md" >}}). +See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "/nginx-one/agent/overview/tech-specs.md" >}}). --- ## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) +{{< include "agent/v3-available.md" >}} + ### 🌟 Highlights ### πŸ› Bug Fixes diff --git a/content/nginx-one/agent/community/_index.md b/content/nginx-one/agent/community/_index.md new file mode 100644 index 000000000..aa967306e --- /dev/null +++ b/content/nginx-one/agent/community/_index.md @@ -0,0 +1,5 @@ +--- +title: "Community" +weight: 600 +url: /nginx-one/agent/community/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/community.md b/content/nginx-one/agent/community/community.md similarity index 100% rename from content/nginx-one/agent/community.md rename to content/nginx-one/agent/community/community.md diff --git a/content/nginx-one/agent/configure-instance-reporting/_index.md b/content/nginx-one/agent/configure-instance-reporting/_index.md new file mode 100644 index 000000000..daac817e1 --- /dev/null +++ b/content/nginx-one/agent/configure-instance-reporting/_index.md @@ -0,0 +1,5 @@ +--- +title: "Configure instance reporting" +weight: 400 +url: /nginx-one/agent/configure-instance-reporting/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/how-to/configuration-overview.md b/content/nginx-one/agent/configure-instance-reporting/configuration-overview.md similarity index 100% rename from content/nginx-one/agent/how-to/configuration-overview.md rename to content/nginx-one/agent/configure-instance-reporting/configuration-overview.md diff --git a/content/nginx-one/agent/how-to/configure-agent-group.md b/content/nginx-one/agent/configure-instance-reporting/configure-agent-group.md similarity index 100% rename from content/nginx-one/agent/how-to/configure-agent-group.md rename to content/nginx-one/agent/configure-instance-reporting/configure-agent-group.md diff --git a/content/nginx-one/agent/containers/_index.md b/content/nginx-one/agent/containers/_index.md new file mode 100644 index 000000000..d74d0a2c4 --- /dev/null +++ b/content/nginx-one/agent/containers/_index.md @@ -0,0 +1,5 @@ +--- +title: "Containers" +weight: 300 +url: /nginx-one/agent/containers/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/how-to/run-agent-container.md b/content/nginx-one/agent/containers/run-agent-container.md similarity index 99% rename from content/nginx-one/agent/how-to/run-agent-container.md rename to content/nginx-one/agent/containers/run-agent-container.md index 09c7397c6..27c1df8ed 100644 --- a/content/nginx-one/agent/how-to/run-agent-container.md +++ b/content/nginx-one/agent/containers/run-agent-container.md @@ -1,6 +1,6 @@ --- title: "Run the NGINX Agent in a container" -weight: 300 +weight: 100 toc: true type: how-to product: Agent diff --git a/content/nginx-one/agent/how-to/_index.md b/content/nginx-one/agent/how-to/_index.md deleted file mode 100644 index 99d8bc45e..000000000 --- a/content/nginx-one/agent/how-to/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "How-to guides" -weight: 500 -url: /nginx-agent/how-to/ ---- diff --git a/content/nginx-one/agent/install-upgrade/_index.md b/content/nginx-one/agent/install-upgrade/_index.md index d8ba0318e..0224aada9 100644 --- a/content/nginx-one/agent/install-upgrade/_index.md +++ b/content/nginx-one/agent/install-upgrade/_index.md @@ -1,5 +1,5 @@ --- title: "Install and update" -weight: 400 -url: /nginx-agent/install-upgrade/ +weight: 200 +url: /nginx-one/agent/install-upgrade/ --- \ No newline at end of file diff --git a/content/nginx-one/agent/metrics/_index.md b/content/nginx-one/agent/metrics/_index.md new file mode 100644 index 000000000..e089288c1 --- /dev/null +++ b/content/nginx-one/agent/metrics/_index.md @@ -0,0 +1,5 @@ +--- +title: "Metrics" +weight: 500 +url: /nginx-one/agent/metrics/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md similarity index 100% rename from content/nginx-one/agent/configure-otel-metrics.md rename to content/nginx-one/agent/metrics/configure-otel-metrics.md diff --git a/content/nginx-one/agent/overview/_index.md b/content/nginx-one/agent/overview/_index.md new file mode 100644 index 000000000..25d1de757 --- /dev/null +++ b/content/nginx-one/agent/overview/_index.md @@ -0,0 +1,5 @@ +--- +title: "Overview" +weight: 100 +url: /nginx-one/agent/install-upgrade/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/about.md b/content/nginx-one/agent/overview/about.md similarity index 84% rename from content/nginx-one/agent/about.md rename to content/nginx-one/agent/overview/about.md index c9a0ae627..423217190 100644 --- a/content/nginx-one/agent/about.md +++ b/content/nginx-one/agent/overview/about.md @@ -1,14 +1,10 @@ --- title: "About" -weight: 10 +weight: 100 toc: true --- -{{}} -NGINX Agent v3.0 is a major release that introduces new features and enhancements. - -Visit our [Update]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) guide to install the latest version in your environment. -{{}} +{{< include "agent/v3-available.md" >}} {{< include "agent/about.md" >}} diff --git a/content/nginx-one/agent/tech-specs.md b/content/nginx-one/agent/overview/tech-specs.md similarity index 90% rename from content/nginx-one/agent/tech-specs.md rename to content/nginx-one/agent/overview/tech-specs.md index 84c2840ea..b1105a287 100644 --- a/content/nginx-one/agent/tech-specs.md +++ b/content/nginx-one/agent/overview/tech-specs.md @@ -1,7 +1,7 @@ --- title: "Technical Specifications" toc: false -weight: 50 +weight: 200 docs: DOCS-000 --- diff --git a/content/nginx-one/agent/support/_index.md b/content/nginx-one/agent/support/_index.md new file mode 100644 index 000000000..253093e5e --- /dev/null +++ b/content/nginx-one/agent/support/_index.md @@ -0,0 +1,5 @@ +--- +title: "Support" +weight: 700 +url: /nginx-one/agent/support/ +--- \ No newline at end of file diff --git a/content/nginx-one/agent/troubleshooting.md b/content/nginx-one/agent/support/troubleshooting.md similarity index 100% rename from content/nginx-one/agent/troubleshooting.md rename to content/nginx-one/agent/support/troubleshooting.md From 71daf7ba54a94bd9dea87de63b779fb3db3ed4d8 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 30 May 2025 16:35:22 +0100 Subject: [PATCH 55/63] fix conflicts --- .../agent/installation/update-container.md | 2 +- .../install-upgrade/install-from-github.md | 2 +- .../install-upgrade/install-from-oss-repo.md | 2 +- .../install-upgrade/install-from-plus-repo.md | 2 +- .../agent/metrics/configure-otel-metrics.md | 2 +- .../connect-instances/add-instance.md | 12 +--- .../nginx-one/nginx-configs/add-instance.md | 67 ------------------- .../certificates/manage-certificates.md | 11 +-- .../config-sync-groups/add-file-csg.md | 12 +--- .../manage-config-sync-groups.md | 7 +- 10 files changed, 9 insertions(+), 110 deletions(-) delete mode 100644 content/nginx-one/nginx-configs/add-instance.md diff --git a/content/includes/agent/installation/update-container.md b/content/includes/agent/installation/update-container.md index a18f5894e..a974cfbce 100644 --- a/content/includes/agent/installation/update-container.md +++ b/content/includes/agent/installation/update-container.md @@ -15,7 +15,7 @@ wget https://raw.githubusercontent.com/nginx/agent/refs/heads/v3/scripts/package ``` 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/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. +See [Add Config Sync Group]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. ### Rolling back from NGINX Agent v3 to v2 diff --git a/content/nginx-one/agent/install-upgrade/install-from-github.md b/content/nginx-one/agent/install-upgrade/install-from-github.md index cfff1bba5..df7eb8436 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-github.md +++ b/content/nginx-one/agent/install-upgrade/install-from-github.md @@ -10,7 +10,7 @@ If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}} to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) {{< /note >}} Follow the steps in this guide to install NGINX Agent in your NGINX instance using diff --git a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md index c794bb68b..7daf6fed2 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-oss-repo.md @@ -10,7 +10,7 @@ If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}} to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) {{< /note >}} ## Overview diff --git a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md index a328b28ee..629a64119 100644 --- a/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md +++ b/content/nginx-one/agent/install-upgrade/install-from-plus-repo.md @@ -10,7 +10,7 @@ If you are using [NGINX One Console]({{< ref "/nginx-one/getting-started.md" >}} to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console. -For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance" >}}) +For a quick guide on how to connect your instance to NGINX One Console see: [Connect to NGINX One Console]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) {{< /note >}} ## Overview diff --git a/content/nginx-one/agent/metrics/configure-otel-metrics.md b/content/nginx-one/agent/metrics/configure-otel-metrics.md index 094c03adc..0f639a1b5 100644 --- a/content/nginx-one/agent/metrics/configure-otel-metrics.md +++ b/content/nginx-one/agent/metrics/configure-otel-metrics.md @@ -26,7 +26,7 @@ You can validate that metrics are successfully exported by using the methods bel - **NGINX One dashboard** - - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/nginx-configs/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. + - When an instance has connected to NGINX One Console [See: Connect to NGINX One Console]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}), you should see metrics showing on the NGINX One Dashboard. - **Agent logs** diff --git a/content/nginx-one/connect-instances/add-instance.md b/content/nginx-one/connect-instances/add-instance.md index d9143d0ec..6bc8b768f 100644 --- a/content/nginx-one/connect-instances/add-instance.md +++ b/content/nginx-one/connect-instances/add-instance.md @@ -19,15 +19,9 @@ Before you add an instance to NGINX One Console, ensure: - You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. - You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. - You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). -<<<<<<<< HEAD:content/nginx-one/nginx-configs/add-instance.md -- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} -======== - You have or are ready to set up [managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}). {{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} ->>>>>>>> origin:content/nginx-one/connect-instances/add-instance.md ## Add an instance @@ -59,9 +53,5 @@ Once you've completed the process, NGINX One reassigns this as a managed certifi ## Add an instance to a Config Sync Group -<<<<<<<< HEAD:content/nginx-one/nginx-configs/add-instance.md -When you [Manage Config Sync Group membership]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -======== When you [Manage Config Sync Group membership]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. ->>>>>>>> origin:content/nginx-one/connect-instances/add-instance.md -That instance inherits the setup of that Config Sync Group. +That instance inherits the setup of that Config Sync Group. \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/add-instance.md b/content/nginx-one/nginx-configs/add-instance.md deleted file mode 100644 index d9143d0ec..000000000 --- a/content/nginx-one/nginx-configs/add-instance.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -description: '' -title: Add an NGINX instance -toc: true -weight: 100 -type: -- how-to ---- - -## Overview - -This guide explains how to add an F5 NGINX instance in F5 NGINX One Console. You can add an instance from the NGINX One Console individually, or as part of a [Config Sync Group]({{< ref "/nginx-one/glossary.md" >}}). In either case, you need -to set up a data plane key to connect your instances to NGINX One. - -## Before you start - -Before you add an instance to NGINX One Console, ensure: - -- You have [administrator access]({{< ref "/nginx-one/rbac/roles.md" >}}) to NGINX One Console. -- You have [configured instances of NGINX]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}) that you want to manage through NGINX One Console. -- You have or are ready to configure a [data plane key]({{< ref "/nginx-one/getting-started.md#generate-data-plane-key" >}}). -<<<<<<<< HEAD:content/nginx-one/nginx-configs/add-instance.md -- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}). - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} -======== -- You have or are ready to set up [managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}). - -{{< note >}}If this is the first time an instance is being added to a Config Sync Group, and you have not yet defined the configuration for that Config Sync Group, that instance provides the template for that group. For more information, see [Configuration management]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#configuration-management" >}}).{{< /note >}} ->>>>>>>> origin:content/nginx-one/connect-instances/add-instance.md - -## Add an instance - -{{< include "/nginx-one/how-to/add-instance.md" >}} - -## Managed and Unmanaged Certificates - -If you add an instance with SSL/TLS certificates, those certificates can match an existing managed SSL certificate/CA bundle. - -### If the certificate is already managed - -If you add an instance with a managed certificate, as described in [Add your NGINX instances to NGINX One]({{< ref "/nginx-one/getting-started.md#add-your-nginx-instances-to-nginx-one" >}}), these certificates are added to your list of **Managed Certificates**. - -NGINX One Console can manage your instances along with those certificates. - -### If the certificate is not managed - -These certificates appear in the list of **Unmanaged Certificates**. - -To take full advantage of NGINX One, you can convert these to **Managed Certificates**. You can then manage, update, and deploy a certificate to all of your NGINX instances in a Config Sync Group. - -To convert these cerificates, start with the Certificates menu, and select **Unmanaged**. You should see a list of **Unmanaged Certificates or CA Bundles**. Then: - -- Select a certificate -- Select **Convert to Managed** -- In the window that appears, you can now include the same information as shown in the [Add a new certificate](#add-a-new-certificate) section - -Once you've completed the process, NGINX One reassigns this as a managed certificate, and assigns it to the associated instance or Config Sync Group. - -## Add an instance to a Config Sync Group - -<<<<<<<< HEAD:content/nginx-one/nginx-configs/add-instance.md -When you [Manage Config Sync Group membership]({{< ref "nginx-one/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. -======== -When you [Manage Config Sync Group membership]({{< ref "nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups#manage-config-sync-group-membership" >}}), you can add an existing or new instance to the group of your choice. ->>>>>>>> origin:content/nginx-one/connect-instances/add-instance.md -That instance inherits the setup of that Config Sync Group. diff --git a/content/nginx-one/nginx-configs/certificates/manage-certificates.md b/content/nginx-one/nginx-configs/certificates/manage-certificates.md index 1f215a982..56d3d159c 100644 --- a/content/nginx-one/nginx-configs/certificates/manage-certificates.md +++ b/content/nginx-one/nginx-configs/certificates/manage-certificates.md @@ -35,11 +35,7 @@ From the NGINX One Console you can: You can manage the certificates for: - [Unique instances]({{< ref "/nginx-one/nginx-configs/add-file.md#new-ssl-certificate-or-ca-bundle" >}}) -<<<<<<<< HEAD:content/nginx-one/certificates/manage-certificates.md -- For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) -======== - For all instances that are members of a [Config Sync Group]({{< ref "/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups/#configuration-management" >}}) ->>>>>>>> origin:content/nginx-one/nginx-configs/certificates/manage-certificates.md {{< tip >}} @@ -197,11 +193,6 @@ To convert these cerificates to managed, start with the Certificates menu, and s ## See also -<<<<<<<< HEAD:content/nginx-one/certificates/manage-certificates.md -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) -======== - [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}) - [Add an instance]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) ->>>>>>>> origin:content/nginx-one/nginx-configs/certificates/manage-certificates.md -- [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) +- [Add a file in a configuration]({{< ref "/nginx-one/nginx-configs/add-file.md" >}}) \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md index 080439b11..4cb161450 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md @@ -58,20 +58,10 @@ Enter the name of the desired configuration file, such as `abc.conf` and select ### Existing SSL Certificate or CA Bundle {{< include "nginx-one/add-file/existing-ssl-bundle.md" >}} -<<<<<<<< HEAD:content/nginx-one/config-sync-groups/add-file-csg.md -With this option, You can incorporate [Managed certificates]({{< ref "/nginx-one/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). - -## See also - -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/certificates/manage-certificates.md" >}}) -======== With this option, you can incorporate [Managed certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md#managed-and-unmanaged-certificates" >}}). ## See also - [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}) - [Add an NGINX instance]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) -- [Manage certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}) ->>>>>>>> origin:content/nginx-one/nginx-configs/config-sync-groups/add-file-csg.md +- [Manage certificates]({{< ref "/nginx-one/nginx-configs/certificates/manage-certificates.md" >}}) \ No newline at end of file diff --git a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md index e4b287355..3bb24b6a9 100644 --- a/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +++ b/content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md @@ -257,10 +257,5 @@ Monitor the **Config Sync Status** column. It can help you ensure that your conf ## See also -<<<<<<<< HEAD:content/nginx-one/config-sync-groups/manage-config-sync-groups.md -- [Create and manage data plane keys]({{< ref "/nginx-one/how-to/data-plane-keys/create-manage-data-plane-keys.md" >}}) -- [View and edit NGINX configurations]({{< ref "/nginx-one/nginx-configs/view-edit-nginx-configurations.md" >}}) -======== - [Create and manage data plane keys]({{< ref "/nginx-one/connect-instances/create-manage-data-plane-keys.md" >}}) -- [Add an NGINX instance]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) ->>>>>>>> origin:content/nginx-one/nginx-configs/config-sync-groups/manage-config-sync-groups.md +- [Add an NGINX instance]({{< ref "/nginx-one/connect-instances/add-instance.md" >}}) \ No newline at end of file From 0fd7cc491e45d40a13acaaf6b3afd73152aff6d7 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 30 May 2025 16:39:58 +0100 Subject: [PATCH 56/63] remove double F --- layouts/partials/list-main.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/list-main.html b/layouts/partials/list-main.html index 6bde790d7..dbf078802 100644 --- a/layouts/partials/list-main.html +++ b/layouts/partials/list-main.html @@ -19,7 +19,7 @@

      - {{ if or (lt .WordCount 1) (eq $PageTitle "fF5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }} + {{ if or (lt .WordCount 1) (eq $PageTitle "F5 NGINX One Console") (eq $PageTitle "F5 NGINX App Protect DoS") (eq $PageTitle "F5 NGINX Plus") }}
      From 37ca1e13850cbc575c0c8a84ea0b2efe47a381d7 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Fri, 30 May 2025 16:53:51 +0100 Subject: [PATCH 57/63] use new banner functionality for Agent announcement --- _banners/agent-v3-release.md | 7 +++ content/agent/_index.md | 7 ++- layouts/agent-v2-migration/list.html | 10 ---- layouts/agent-v2-migration/single.html | 50 ----------------- .../agent-v2-migration/list-main.html | 54 ------------------- 5 files changed, 13 insertions(+), 115 deletions(-) create mode 100644 _banners/agent-v3-release.md delete mode 100644 layouts/agent-v2-migration/list.html delete mode 100644 layouts/agent-v2-migration/single.html delete mode 100644 layouts/partials/agent-v2-migration/list-main.html diff --git a/_banners/agent-v3-release.md b/_banners/agent-v3-release.md new file mode 100644 index 000000000..7cf262443 --- /dev/null +++ b/_banners/agent-v3-release.md @@ -0,0 +1,7 @@ +{{< banner "notice" "NGINX Agent v3.0 is now available" >}} + + This documentation is for **NGINX Agent v2**. Visit the [Update NGINX Agent]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) topic to learn how to upgrade your instances to the latest version. + + For NGINX Agent v3 documentation, visit the [NGINX One Console docs]({{< ref "/nginx-one/agent/" >}}). + +{{< /banner >}} \ No newline at end of file diff --git a/content/agent/_index.md b/content/agent/_index.md index ee41678ad..457595727 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -5,5 +5,10 @@ description: NGINX Agent is a companion daemon for your NGINX Open Source or NGI url: /nginx-agent/ cascade: logo: NGINX-product-icon.png - type: agent-v2-migration + banner: + enabled: true + type: deprecation + start-date: 2025-05-29 + end-date: 2025-09-09 + md: /_banners/agent-v3-release.md --- diff --git a/layouts/agent-v2-migration/list.html b/layouts/agent-v2-migration/list.html deleted file mode 100644 index 54b0b0f66..000000000 --- a/layouts/agent-v2-migration/list.html +++ /dev/null @@ -1,10 +0,0 @@ -{{ 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 deleted file mode 100644 index faeed088a..000000000 --- a/layouts/agent-v2-migration/single.html +++ /dev/null @@ -1,50 +0,0 @@ -{{ 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. Follow the Update NGINX Agent topic to learn how to upgrade your instances to the latest version. -

      For NGINX Agent v3 documentation, visit the NGINX One Console docs. -
      -
      - -

      {{ .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 deleted file mode 100644 index 4a0369e8c..000000000 --- a/layouts/partials/agent-v2-migration/list-main.html +++ /dev/null @@ -1,54 +0,0 @@ -
      -
      -
      -

      - {{ .Title }} -

      - {{ if .Description }} -

      - {{ .Description | markdownify }} -

      - {{ end}} -
      -
      - NGINX Agent v3 is available!

      - This documentation is for NGINX Agent v2. Follow the Update NGINX Agent topic to learn how to upgrade your instances to the latest version. -

      For NGINX Agent v3 documentation, visit the NGINX One Console docs. -
      -
      - {{ if .Content }} -

      - {{ .Content | markdownify }} -

      - {{ end }} -
      -
      - -
      -
      -
      - {{ range .Pages.GroupBy "Section" }} - - {{ range .Pages.ByWeight }} -
      -
      -

      - - {{ .Title }} -

      - {{/*}}

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

      {{*/}} - -
      -
      - - {{ end }} -
      -
      - {{ end }} - - -
      - -
      \ No newline at end of file From d686ed33b11dc5fe1f3a9357856a98bdb6868fcf Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 9 Jun 2025 13:46:02 +0100 Subject: [PATCH 58/63] add changelog --- content/nginx-one/agent/changelog.md | 231 ++++++++++++++++++++++++++- 1 file changed, 227 insertions(+), 4 deletions(-) diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md index 48677848e..9e707404d 100644 --- a/content/nginx-one/agent/changelog.md +++ b/content/nginx-one/agent/changelog.md @@ -1,7 +1,8 @@ --- -title: "NGINX Agent changelog" -weight: 10000 +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 >}} @@ -9,15 +10,237 @@ toc: true See the list of supported Operating Systems and architectures in the [Technical Specifications]({{< ref "/nginx-one/agent/overview/tech-specs.md" >}}). --- -## Release [v3.0.0](https//github.com/nginx/agent/releases/tag/v3.0.0) +## Release [v3.0.0](https://github.com/nginx/agent/releases/tag/v3.0.0) -{{< include "agent/v3-available.md" >}} +### 🌟 Highlights + +- **NGINX Agent v3 and Management Plane Interface (MPI)**: NGINX Agent v3 is here! This release is a major milestone aimed at simplifying the management, monitoring, and scaling of your NGINX instances. With enhanced integrations, improved observability features, and support for modern orchestrated environments like Kubernetes. + +### πŸš€ Features + +This release introduces the following new features: + +- **Enhanced Kubernetes Integration with Management Plane Interface (MPI)**: NGINX Agent now offers full integration with Kubernetes-native products, such as the [NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) and [NGINX Gateway Fabric](https://docs.nginx.com/nginx-gateway-fabric), enabling seamless fleet management, real-time observability, and smooth interoperability across Kubernetes deployments. This is powered by the Management Plane Interface (MPI), a standardized interface designed to provide a unified and consistent experience across NGINX solutions, with built-in support for Kubernetes-based applications. For detailed technical specifications, refer to the official Protocol Documentation . + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- [Official NGINX Agent documentation](https://docs.nginx.com/nginx-agent/) +- [F5 Support](https://my.f5.com/manage/s/) + +--- +## Release [v2.41.1](https://github.com/nginx/agent/releases/tag/v2.41.1) + +### πŸš€ Features + +This release introduces the following new features: + +- Fix remotely enabling/disabling features by [@dhurley](https://github.com/dhurley) in [#1088](https://github.com/nginx/agent/pull/1088) + +--- +## Release [v2.41.0](https://github.com/nginx/agent/releases/tag/v2.41.0) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Update agent landing page and readme by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#1017](https://github.com/nginx/agent/pull/1017) +- Update dependencies by [@dhurley](https://github.com/dhurley) in [#1026](https://github.com/nginx/agent/pull/1026) +- Update net and nats dependencies by [@dhurley](https://github.com/dhurley) in [#1070](https://github.com/nginx/agent/pull/1070) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Merge v2.40.1 back to main by [@dhurley](https://github.com/dhurley) in [#1049](https://github.com/nginx/agent/pull/1049) + +--- +## Release [v2.40.1](https://github.com/nginx/agent/releases/tag/v2.40.1) + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Add nil pointer check to GenerateMetricsReportBundle by [@dhurley](https://github.com/dhurley) in [#1047](https://github.com/nginx/agent/pull/1047) + +--- +## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0) + +### 🌟 Highlights + +- The source code for the [NGINX Agent documentation](https://docs.nginx.com/nginx-agent/) has moved to the [NGINX Documentation](https://github.com/nginx/documentation/) repository. We invite you to [contribute](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md), improve the Agent docs and report any issues you find in the documentation repository. + +### πŸ› Bug Fixes + +In this release we have resolved the following issues: + +- Lua config apply by [@oliveromahony](https://github.com/oliveromahony) in [#963](https://github.com/nginx/agent/pull/963) +- Fix release workflow by [@dhurley](https://github.com/dhurley) in [#991](https://github.com/nginx/agent/pull/991) + +### πŸ“ Documentation + +We have made the following updates to the documentation: + +- Docs: updating links from /nginx-management-suite/nim to /nginx-instance-manager by [@nginx-aoife](https://github.com/nginx-aoife) in [#927](https://github.com/nginx/agent/pull/927) +- Autodeploy main docs to production by [@nginx-jack](https://github.com/nginx-jack) in [#924](https://github.com/nginx/agent/pull/924) +- docs: remove docs by [@JTorreG](https://github.com/JTorreG) in [#976](https://github.com/nginx/agent/pull/976) +- Add a docs page to explain NGINX Agent features by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#941](https://github.com/nginx/agent/pull/941) +- docs: Fix NGINX install link and dockerfile section by [@JTorreG](https://github.com/JTorreG) in [#928](https://github.com/nginx/agent/pull/928) + +### πŸ”¨ Maintenance + +We have made the following maintenance-related minor changes: + +- Fail release job if packages fail to publish by [@dhurley](https://github.com/dhurley) in [#923](https://github.com/nginx/agent/pull/923) +- Update performance test Dockerfile to use NGINX R32 by [@dhurley](https://github.com/dhurley) in [#937](https://github.com/nginx/agent/pull/937) +- Updated golang.org/x/net version by [@oliveromahony](https://github.com/oliveromahony) in [#954](https://github.com/nginx/agent/pull/954) +- Update performance test dependencies by [@dhurley](https://github.com/dhurley) in [#984](https://github.com/nginx/agent/pull/984) +- Refactor integration tests by [@dhurley](https://github.com/dhurley) in [#985](https://github.com/nginx/agent/pull/985) +- Update dependencies by [@dhurley](https://github.com/dhurley) in [#98](https://github.com/nginx/agent/pull/98) +- Updated the crypto library version by [@oliveromahony](https://github.com/oliveromahony) in [#947](https://github.com/nginx/agent/pull/947) + +--- +## 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) + From 35432c6b23f36a77435a98c1f4e0ff2f244b5f86 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 9 Jun 2025 14:37:12 +0100 Subject: [PATCH 59/63] rename changelog to releases --- content/nginx-one/agent/changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md index 9e707404d..753caec3c 100644 --- a/content/nginx-one/agent/changelog.md +++ b/content/nginx-one/agent/changelog.md @@ -1,5 +1,5 @@ --- -title: "Changelog" +title: "Releases" weight: 1200 toc: true docs: "DOCS-1093" From 12fb9e015558a27561924d7d2b8bf2e2c879cc76 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 9 Jun 2025 14:38:17 +0100 Subject: [PATCH 60/63] update changelog --- content/nginx-one/agent/changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md index 753caec3c..2b22707ba 100644 --- a/content/nginx-one/agent/changelog.md +++ b/content/nginx-one/agent/changelog.md @@ -5,7 +5,7 @@ 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 >}} +{{< note >}}You can find the full list of NGINX Agent releases, 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]({{< ref "/nginx-one/agent/overview/tech-specs.md" >}}). From ee3a6752c137fae120ca6b9bf6d3a24af32d8ba4 Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Mon, 9 Jun 2025 14:52:45 +0100 Subject: [PATCH 61/63] add details for nginx agent card --- content/nginx-one/_index.md | 29 ++++++++++++++++------------- content/nginx-one/agent/_index.md | 6 +++--- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/content/nginx-one/_index.md b/content/nginx-one/_index.md index 12ff811af..a43857682 100644 --- a/content/nginx-one/_index.md +++ b/content/nginx-one/_index.md @@ -9,7 +9,7 @@ cascade: {{< card-layout >}} {{< card-section >}} {{< card title="Manage your NGINX fleet" >}} - Simplify, scale, secure, and collaborate with your NGINX fleet + Simplify, scale, secure, and collaborate with your NGINX fleet {{}} {{< card title="Get started" >}} See benefits from the NGINX One Console @@ -24,50 +24,53 @@ cascade: Work with Staged Configurations {{}} {{< card title="Set up metrics" >}} - Review your deployments in a dashboard + Review your deployments in a dashboard {{}} {{< card title="Organize users with RBAC" >}} - Assign responsibilities with role-based access control + Assign responsibilities with role-based access control {{}} {{< card title="Automate with the NGINX One API" >}} - Manage your NGINX fleet over REST + Manage your NGINX fleet over REST + {{}} + {{< card title="NGINX Agent" >}} + Learn about the NGINX Agent {{}} {{< card title="Glossary" >}} - Learn terms unique to NGINX One Console + Learn terms unique to NGINX One Console {{}} {{< card title="Changelog" >}} {{< changelog-dates >}} {{}} {{}} - # Other Products + # Other Products {{< card-section title="Kubernetes Solutions">}} {{< card title="NGINX Ingress Controller" titleUrl="/nginx-ingress-controller/" icon="NGINX-Ingress-Controller-product-icon">}} - Kubernetes traffic management with API gateway, identity, and observability features. + Kubernetes traffic management with API gateway, identity, and observability features. {{}} {{< card title="NGINX Gateway Fabric" titleUrl="/nginx-gateway-fabric" icon="NGINX-product-icon">}} - Next generation Kubernetes connectivity using the Gateway API. + Next generation Kubernetes connectivity using the Gateway API. {{}} {{}} {{< card-section title="Local Console Option">}} {{< card title="NGINX Instance Manager" titleUrl="/nginx-instance-manager" icon="NGINX-Instance-Manager-product-icon">}} - Track and control NGINX Open Source and NGINX Plus instances. + Track and control NGINX Open Source and NGINX Plus instances. {{}} {{}} {{< card-section title="Modern App Delivery">}} {{< card title="NGINX Plus" titleUrl="/nginx" icon="NGINX-Plus-product-icon-RGB">}} - The all-in-one load balancer, reverse proxy, web server, content cache, and API gateway. + The all-in-one load balancer, reverse proxy, web server, content cache, and API gateway. {{}} {{< card title="NGINX Open Source" titleUrl="https://nginx.org" icon="NGINX-product-icon">}} - The open source all-in-one load balancer, content cache, and web server + The open source all-in-one load balancer, content cache, and web server {{}} {{}} {{< card-section title="Security">}} {{< card title="NGINX App Protect WAF" titleUrl="/nginx-app-protect-waf" icon="NGINX-App-Protect-WAF-product-icon">}} - Lightweight, high-performance, advanced protection against Layer 7 attacks on your apps and APIs. + Lightweight, high-performance, advanced protection against Layer 7 attacks on your apps and APIs. {{}} {{< card title="NGINX App Protect DoS" titleUrl="/nginx-app-protect-dos" icon="NGINX-App-Protect-DoS-product-icon">}} - Defend, adapt, and mitigate against Layer 7 denial-of-service attacks on your apps and APIs. + Defend, adapt, and mitigate against Layer 7 denial-of-service attacks on your apps and APIs. {{}} {{}} {{}} \ No newline at end of file diff --git a/content/nginx-one/agent/_index.md b/content/nginx-one/agent/_index.md index 37e8b880d..159229def 100644 --- a/content/nginx-one/agent/_index.md +++ b/content/nginx-one/agent/_index.md @@ -1,6 +1,6 @@ --- title: NGINX Agent -description: -weight: 1100 -url: /nginx-one/agent +description: Learn about NGINX Agent, its features, and how to install it. +weight: 750 +url: /nginx-one/agent/ --- From 1683a6526ba05cd4be33e14e41e389df9d90609d Mon Sep 17 00:00:00 2001 From: Jon Cahill-Torre Date: Tue, 10 Jun 2025 15:34:50 +0100 Subject: [PATCH 62/63] remove v fromversions --- _banners/agent-v3-release.md | 6 +- content/nginx-one/agent/changelog.md | 246 +-------------------------- 2 files changed, 7 insertions(+), 245 deletions(-) diff --git a/_banners/agent-v3-release.md b/_banners/agent-v3-release.md index 7cf262443..124453428 100644 --- a/_banners/agent-v3-release.md +++ b/_banners/agent-v3-release.md @@ -1,7 +1,7 @@ -{{< banner "notice" "NGINX Agent v3.0 is now available" >}} +{{< banner "notice" "NGINX Agent 3.0 is now available" >}} - This documentation is for **NGINX Agent v2**. Visit the [Update NGINX Agent]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) topic to learn how to upgrade your instances to the latest version. + This documentation is for **NGINX Agent 2.x**. Visit the [Update NGINX Agent]({{< ref "/nginx-one/agent/install-upgrade/update.md" >}}) topic to learn how to upgrade your instances to the latest version. - For NGINX Agent v3 documentation, visit the [NGINX One Console docs]({{< ref "/nginx-one/agent/" >}}). + For NGINX Agent 3.x documentation, visit the [NGINX One Console docs]({{< ref "/nginx-one/agent/" >}}). {{< /banner >}} \ No newline at end of file diff --git a/content/nginx-one/agent/changelog.md b/content/nginx-one/agent/changelog.md index 2b22707ba..284cfea6a 100644 --- a/content/nginx-one/agent/changelog.md +++ b/content/nginx-one/agent/changelog.md @@ -1,246 +1,8 @@ --- -title: "Releases" +title: Agent changelog +toc: false +url: /nginx-one/agent/changelog weight: 1200 -toc: true -docs: "DOCS-1093" --- -{{< note >}}You can find the full list of NGINX Agent releases, 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]({{< ref "/nginx-one/agent/overview/tech-specs.md" >}}). - ---- -## Release [v3.0.0](https://github.com/nginx/agent/releases/tag/v3.0.0) - -### 🌟 Highlights - -- **NGINX Agent v3 and Management Plane Interface (MPI)**: NGINX Agent v3 is here! This release is a major milestone aimed at simplifying the management, monitoring, and scaling of your NGINX instances. With enhanced integrations, improved observability features, and support for modern orchestrated environments like Kubernetes. - -### πŸš€ Features - -This release introduces the following new features: - -- **Enhanced Kubernetes Integration with Management Plane Interface (MPI)**: NGINX Agent now offers full integration with Kubernetes-native products, such as the [NGINX Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/) and [NGINX Gateway Fabric](https://docs.nginx.com/nginx-gateway-fabric), enabling seamless fleet management, real-time observability, and smooth interoperability across Kubernetes deployments. This is powered by the Management Plane Interface (MPI), a standardized interface designed to provide a unified and consistent experience across NGINX solutions, with built-in support for Kubernetes-based applications. For detailed technical specifications, refer to the official Protocol Documentation . - -### πŸ“ Documentation - -We have made the following updates to the documentation: - -- [Official NGINX Agent documentation](https://docs.nginx.com/nginx-agent/) -- [F5 Support](https://my.f5.com/manage/s/) - ---- -## Release [v2.41.1](https://github.com/nginx/agent/releases/tag/v2.41.1) - -### πŸš€ Features - -This release introduces the following new features: - -- Fix remotely enabling/disabling features by [@dhurley](https://github.com/dhurley) in [#1088](https://github.com/nginx/agent/pull/1088) - ---- -## Release [v2.41.0](https://github.com/nginx/agent/releases/tag/v2.41.0) - -### πŸ“ Documentation - -We have made the following updates to the documentation: - -- Update agent landing page and readme by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#1017](https://github.com/nginx/agent/pull/1017) -- Update dependencies by [@dhurley](https://github.com/dhurley) in [#1026](https://github.com/nginx/agent/pull/1026) -- Update net and nats dependencies by [@dhurley](https://github.com/dhurley) in [#1070](https://github.com/nginx/agent/pull/1070) - -### πŸ”¨ Maintenance - -We have made the following maintenance-related minor changes: - -- Merge v2.40.1 back to main by [@dhurley](https://github.com/dhurley) in [#1049](https://github.com/nginx/agent/pull/1049) - ---- -## Release [v2.40.1](https://github.com/nginx/agent/releases/tag/v2.40.1) - -### πŸ› Bug Fixes - -In this release we have resolved the following issues: - -- Add nil pointer check to GenerateMetricsReportBundle by [@dhurley](https://github.com/dhurley) in [#1047](https://github.com/nginx/agent/pull/1047) - ---- -## Release [v2.40.0](https://github.com/nginx/agent/releases/tag/v2.40.0) - -### 🌟 Highlights - -- The source code for the [NGINX Agent documentation](https://docs.nginx.com/nginx-agent/) has moved to the [NGINX Documentation](https://github.com/nginx/documentation/) repository. We invite you to [contribute](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md), improve the Agent docs and report any issues you find in the documentation repository. - -### πŸ› Bug Fixes - -In this release we have resolved the following issues: - -- Lua config apply by [@oliveromahony](https://github.com/oliveromahony) in [#963](https://github.com/nginx/agent/pull/963) -- Fix release workflow by [@dhurley](https://github.com/dhurley) in [#991](https://github.com/nginx/agent/pull/991) - -### πŸ“ Documentation - -We have made the following updates to the documentation: - -- Docs: updating links from /nginx-management-suite/nim to /nginx-instance-manager by [@nginx-aoife](https://github.com/nginx-aoife) in [#927](https://github.com/nginx/agent/pull/927) -- Autodeploy main docs to production by [@nginx-jack](https://github.com/nginx-jack) in [#924](https://github.com/nginx/agent/pull/924) -- docs: remove docs by [@JTorreG](https://github.com/JTorreG) in [#976](https://github.com/nginx/agent/pull/976) -- Add a docs page to explain NGINX Agent features by [@nginx-seanmoloney](https://github.com/nginx-seanmoloney) in [#941](https://github.com/nginx/agent/pull/941) -- docs: Fix NGINX install link and dockerfile section by [@JTorreG](https://github.com/JTorreG) in [#928](https://github.com/nginx/agent/pull/928) - -### πŸ”¨ Maintenance - -We have made the following maintenance-related minor changes: - -- Fail release job if packages fail to publish by [@dhurley](https://github.com/dhurley) in [#923](https://github.com/nginx/agent/pull/923) -- Update performance test Dockerfile to use NGINX R32 by [@dhurley](https://github.com/dhurley) in [#937](https://github.com/nginx/agent/pull/937) -- Updated golang.org/x/net version by [@oliveromahony](https://github.com/oliveromahony) in [#954](https://github.com/nginx/agent/pull/954) -- Update performance test dependencies by [@dhurley](https://github.com/dhurley) in [#984](https://github.com/nginx/agent/pull/984) -- Refactor integration tests by [@dhurley](https://github.com/dhurley) in [#985](https://github.com/nginx/agent/pull/985) -- Update dependencies by [@dhurley](https://github.com/dhurley) in [#98](https://github.com/nginx/agent/pull/98) -- Updated the crypto library version by [@oliveromahony](https://github.com/oliveromahony) in [#947](https://github.com/nginx/agent/pull/947) - ---- -## 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) - + \ No newline at end of file From 75b30077875ec32a0c58e73a028b9a383b380707 Mon Sep 17 00:00:00 2001 From: Donal Hurley Date: Thu, 12 Jun 2025 13:51:31 +0100 Subject: [PATCH 63/63] Add NGINX Agent v3.0 SELinux configuration guide (#673) * Add SElinux page for NGINX Agent V3 * Add SElinux page for NGINX Agent V3 * Split agent SELinux include file --- .../installation/add-ports-agent-selinux.md | 17 ++++++++ .../includes/installation/agent-selinux.md | 11 ----- .../installation/enable-agent-selinux.md | 23 ++++++++++ .../configure-selinux.md | 43 +++++++++++++++++++ .../system-configuration/configure-selinux.md | 20 +-------- .../nms/nginx-agent/install-nginx-agent.md | 26 ++--------- 6 files changed, 88 insertions(+), 52 deletions(-) create mode 100644 content/includes/installation/add-ports-agent-selinux.md delete mode 100644 content/includes/installation/agent-selinux.md create mode 100644 content/includes/installation/enable-agent-selinux.md create mode 100644 content/nginx-one/agent/configure-instance-reporting/configure-selinux.md diff --git a/content/includes/installation/add-ports-agent-selinux.md b/content/includes/installation/add-ports-agent-selinux.md new file mode 100644 index 000000000..27c8e3429 --- /dev/null +++ b/content/includes/installation/add-ports-agent-selinux.md @@ -0,0 +1,17 @@ +--- +docs: +files: + - content/nginx-one/agent/configure-instance-reporting/configure-selinux.md + - content/nim/system-configuration/configure-selinux.md + - content/nms/nginx-agent/install-nginx-agent.md +--- + +Make sure to add external ports to the firewall exception list. + +To allow external ports outside the HTTPD context, run: + +```bash +sudo setsebool -P httpd_can_network_connect 1 +``` + +{{}}For more information, see [Using NGINX and NGINX Plus with SELinux](https://www.nginx.com/blog/using-nginx-plus-with-selinux/).{{}} \ No newline at end of file diff --git a/content/includes/installation/agent-selinux.md b/content/includes/installation/agent-selinux.md deleted file mode 100644 index 4a8cf0741..000000000 --- a/content/includes/installation/agent-selinux.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -docs: DOCS-1403 ---- - -```bash -sudo semodule -n -i /usr/share/selinux/packages/nginx_agent.pp -sudo /usr/sbin/load_policy -sudo restorecon -R /usr/bin/nginx-agent -sudo restorecon -R /var/log/nginx-agent -sudo restorecon -R /etc/nginx-agent -``` diff --git a/content/includes/installation/enable-agent-selinux.md b/content/includes/installation/enable-agent-selinux.md new file mode 100644 index 000000000..482ee61c1 --- /dev/null +++ b/content/includes/installation/enable-agent-selinux.md @@ -0,0 +1,23 @@ +--- +docs: +files: + - content/nginx-one/agent/configure-instance-reporting/configure-selinux.md + - content/nim/system-configuration/configure-selinux.md + - content/nms/nginx-agent/install-nginx-agent.md +--- + +The following SELinux files are added when you install the NGINX Agent package: + +- `/usr/share/selinux/packages/nginx_agent.pp` - loadable binary policy module +- `/usr/share/selinux/devel/include/contrib/nginx_agent.if` - interface definitions file +- `/usr/share/man/man8/nginx_agent_selinux.8.gz` - policy man page + +To load the NGINX Agent policy, run the following commands as root: + +```bash +sudo semodule -n -i /usr/share/selinux/packages/nginx_agent.pp +sudo /usr/sbin/load_policy +sudo restorecon -R /usr/bin/nginx-agent +sudo restorecon -R /var/log/nginx-agent +sudo restorecon -R /etc/nginx-agent +``` diff --git a/content/nginx-one/agent/configure-instance-reporting/configure-selinux.md b/content/nginx-one/agent/configure-instance-reporting/configure-selinux.md new file mode 100644 index 000000000..c954a7e42 --- /dev/null +++ b/content/nginx-one/agent/configure-instance-reporting/configure-selinux.md @@ -0,0 +1,43 @@ +--- +title: Configure SELinux +weight: 600 +toc: true +--- + +## Overview + +You can use the optional SELinux policy module included in the package to secure F5 NGINX Agent operations with flexible, mandatory access control that follows the principle of least privilege. + +{{< important >}}The SELinux policy module is optional. It is not loaded automatically during installation, even on SELinux-enabled systems. You must manually load the policy module using the steps below.{{< /important >}} + +## Before you begin + +Take these preparatory steps before configuring SELinux: + +1. Enable SELinux on your system. +2. Install the tools `load_policy`, `semodule`, and `restorecon`. +3. [Install NGINX Agent]({{< ref "/nginx-one/agent/install-upgrade/_index.md" >}}) with SELinux module files in place. + +{{< important >}}SELinux can use `permissive` mode, where policy violations are logged instead of enforced. Verify which mode your configuration uses.{{< /important >}} + +--- + +## Enable SELinux for NGINX Agent {#selinux-agent} + +{{< include "/installation/enable-agent-selinux.md" >}} + +### Add ports to NGINX Agent SELinux context + +{{< include "/installation/add-ports-agent-selinux.md" >}} + +--- + +## Recommended Resources + +- +- +- +- +- +- +- \ No newline at end of file diff --git a/content/nim/system-configuration/configure-selinux.md b/content/nim/system-configuration/configure-selinux.md index b9aa07184..9c906a3ad 100644 --- a/content/nim/system-configuration/configure-selinux.md +++ b/content/nim/system-configuration/configure-selinux.md @@ -118,27 +118,11 @@ sudo semanage port -d -t nms_t 11000 ## Enable SELinux for NGINX Agent {#selinux-agent} -The following SELinux files are added when you install the NGINX Agent package: - -- `/usr/share/selinux/packages/nginx_agent.pp` - loadable binary policy module -- `/usr/share/selinux/devel/include/contrib/nginx_agent.if` - interface definitions file -- `/usr/share/man/man8/nginx_agent_selinux.8.gz` - policy man page - -To load the NGINX Agent policy, run: - -{{< include "installation/agent-selinux.md" >}} +{{< include "/installation/enable-agent-selinux.md" >}} ### Add ports to NGINX Agent SELinux context -Make sure to add external ports to the firewall exception list. - -To allow external ports outside the HTTPD context, run: - -```bash -sudo setsebool -P httpd_can_network_connect 1 -``` - -{{}}For more information, see [Using NGINX and NGINX Plus with SELinux](https://www.nginx.com/blog/using-nginx-plus-with-selinux/).{{}} +{{< include "/installation/add-ports-agent-selinux.md" >}} --- diff --git a/content/nms/nginx-agent/install-nginx-agent.md b/content/nms/nginx-agent/install-nginx-agent.md index 0660ed391..e9a7552ec 100644 --- a/content/nms/nginx-agent/install-nginx-agent.md +++ b/content/nms/nginx-agent/install-nginx-agent.md @@ -400,31 +400,11 @@ Additionally, you can use the agent installation script to add these fields: ## SELinux for NGINX Agent -This section explains how to install and configure the SELinux policy for NGINX Agent. +{{< include "/installation/enable-agent-selinux.md" >}} -### Installing NGINX Agent SELinux Policy Module +### Add ports to NGINX Agent SELinux context -The NGINX Agent package includes the following SELinux files: - -- `/usr/share/man/man8/nginx_agent_selinux.8.gz` -- `/usr/share/selinux/devel/include/contrib/nginx_agent.if` -- `/usr/share/selinux/packages/nginx_agent.pp` - -To load the NGINX Agent policy, run the following commands: - -{{< include "installation/agent-selinux.md" >}} - -### Adding Ports for NGINX Agent SELinux Context - -You can configure NGINX Agent to work with SELinux. Make sure you add external ports to the firewall exception list. - -The following example shows how to allow external ports outside the HTTPD context. You may need to enable NGINX to connect to these ports. - -```bash -sudo setsebool -P httpd_can_network_connect 1 -``` - -For additional information on using NGINX with SELinux, refer to the guide [Using NGINX and NGINX Plus with SELinux](https://www.nginx.com/blog/using-nginx-plus-with-selinux/). +{{< include "/installation/add-ports-agent-selinux.md" >}} ---