diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 9f28ec942..3d6f1daf8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -37,6 +37,10 @@ content/includes/nginxaas-azure/* @nginx/n4a-docs-approvers content/ngf/* @nginx/nginx-gateway-fabric content/includes/ngf/* @nginx/nginx-gateway-fabric +# NGINX Ingress Controller +content/nic/* @nginx/kic +content/includes/nic/* @nginx/kic + # NGINX Instance Manager content/nms/nim/* @nginx/nim-docs-approvers content/nim/* @nginx/nim-docs-approvers diff --git a/.github/ISSUE_TEMPLATE/1-feature_request.md b/.github/ISSUE_TEMPLATE/1-feature_request.md index a0b4c03f7..8b2820beb 100644 --- a/.github/ISSUE_TEMPLATE/1-feature_request.md +++ b/.github/ISSUE_TEMPLATE/1-feature_request.md @@ -2,7 +2,7 @@ name: Feature request about: Suggest an idea for this project title: "" -labels: "" +labels: "enhancement" assignees: "" --- diff --git a/.github/ISSUE_TEMPLATE/2-bug_report.md b/.github/ISSUE_TEMPLATE/2-bug_report.md index 1d3d925c4..12a6c787b 100644 --- a/.github/ISSUE_TEMPLATE/2-bug_report.md +++ b/.github/ISSUE_TEMPLATE/2-bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Create a report to help us improve title: "" -labels: "" +labels: "bug" assignees: "" --- diff --git a/.github/about.txt b/.github/about.txt deleted file mode 100644 index d556164ce..000000000 --- a/.github/about.txt +++ /dev/null @@ -1,16 +0,0 @@ -# GitHub Configurations - -This directory contains settings used by GitHub for Actions, identifying code reviewers, issue and pull request templates, and more. - -## Workflows - -### check-broken-links - -The check-broken-links workflow relies on the following projects: - -- https://github.com/BoundfoxStudios/action-hugo-link-check -- https://github.com/fenneclab/hugo-bin/releases - -The hugo-bin project lets you add Hugo as a dependency in your npm package.json file. The action-hugo-link-check Action requires this, as that is how it identifies which version of Hugo to run to build your docs. - -> Note: The release version numbers in the hugo-bin project do not align with the actual Hugo releases. Check the README and versions in the hugo-bin repo to find out which releases correspond to Hugo releases. diff --git a/.github/labeler.yml b/.github/labeler.yml index 1887bf358..569c08be8 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -73,6 +73,12 @@ product/nginxaas: - 'content/nginxaas-azure/**' - 'content/includes/nginxaas-azure/**' +product/nic: + - changed-files: + - any-glob-to-any-file: + - 'content/nic/**' + - 'content/includes/nic/**' + product/nim: - changed-files: - any-glob-to-any-file: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 113d884bf..47978539f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -26,10 +26,10 @@ Before merging a pull request, run through this checklist and mark each as compl - [ ] I have rebased my branch onto main - [ ] I have ensured my PR is targeting the main branch and pulling from my branch from my own fork - [ ] I have ensured that the commit messages adhere to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) -- [ ] I have ensured that documentation content adheres to [the style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) +- [ ] I have ensured that documentation content adheres to [the style guide](/documentation/style-guide.md) - [ ] If the change involves potentially sensitive changes[^1], I have assessed the possible impact - [ ] If applicable, I have added tests that prove my fix is effective or that my feature works - [ ] I have ensured that existing tests pass after adding my changes -- [ ] If applicable, I have updated [`README.md`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md) +- [ ] If applicable, I have updated [`README.md`](/README.md) -[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content. \ No newline at end of file +[^1]: Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation. Please refer to [our style guide](/documentation/style-guide.md) for guidance about placeholder content. \ No newline at end of file diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml index e990e6afb..aedf4214e 100644 --- a/.github/workflows/build-push.yml +++ b/.github/workflows/build-push.yml @@ -58,7 +58,7 @@ jobs: call-docs-build-push: needs: prod-check-branch - uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@9c59fab05a8131f4d691ba6ea2b6a119f3ef832a # v1.0.7 + uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@04ed2db338ee08cc560a327f412684d0c8260de2 # v1.0.11 with: production_url_path: "" preview_url_path: "${{ vars.PREVIEW_URL_PATH }}" @@ -79,16 +79,37 @@ jobs: runs-on: ubuntu-latest permissions: read-all steps: - - name: Trigger 'Slack notification for new theme release' workflow in 'nginx-hugo-theme' repo. - run: | - curl -L \ - -X POST \ - -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer ${{ secrets.THEME_SLACK_FLOW_PAT }}" \ - -H "X-GitHub-Api-Version: 2022-11-28" \ - "https://api.github.com/repos/${{ secrets.OWNER }}/${{ secrets.REPO }}/dispatches" \ - -d "{\"event_type\": \"trigger-slack-notification\", \"client_payload\": {\"previewURL\": \"${{ env.PREVIEW_URL }}\", \"author\": \"${{ github.event.client_payload.author}}\", \"tag_name\": \"${{ github.event.client_payload.tag_name }}\", \"release_name\": \"${{ github.event.client_payload.release_name }}\"}}" + - name: Send notification + uses: 8398a7/action-slack@1750b5085f3ec60384090fb7c52965ef822e869e # v3.18.0 + with: + status: custom + custom_payload: | + { + username: 'Github', + mention: 'channel', + attachments: [{ + title: `New theme release - ${{ github.event.client_payload.release_name }}`, + color: '#009223', + fields: [ + { + title: 'Tag', + value: `${{ github.event.client_payload.tag_name }}`, + short: true + }, + { + title: 'Author', + value: `${{ github.event.client_payload.author }}`, + short: true + }, + { + title: 'Preview URL', + value: `${{ env.PREVIEW_URL }}`, + short: true + }] + }] + } env: + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL_FRIENDS_OF_DOCS }} PREVIEW_URL: ${{ needs.call-docs-build-push.outputs.PREVIEW_URL }} diff --git a/.github/workflows/check-broken-links.yml b/.github/workflows/check-broken-links.yml deleted file mode 100644 index 3a9bbdfbb..000000000 --- a/.github/workflows/check-broken-links.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: Check for Broken Links -# Generates the Hugo production site and checks for broken links -on: - workflow_dispatch: - # Run on pull requests with changed md files - # pull_request: - # paths: - # - 'content/**.md' - -jobs: - check-broken-links: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - uses: BoundfoxStudios/action-hugo-link-check@v2.0.3 - with: - hugo-root: ./ - hugo-content-dir: ./content - hugo-config: ./config/production/config.yaml - skip: github\.com\/nginxinc\/docs\/(tree|edit|new|issues\/new),twitter\.com\/nginx,linkedin\.com,facebook\.com,.*\/nginx-ingress-controller\/,.*\/nginxaas\/azure\/,.*\/nginx-amplify\/,.*\/nginx-agent\/,www\.nginx\.com,nginx\.com,www\.mywebsite\.com,example\.com - hugo-startup-wait-time: 60 - - diff --git a/.github/workflows/fossa.yml b/.github/workflows/fossa.yml index 1fb78fab3..7d94f92bb 100644 --- a/.github/workflows/fossa.yml +++ b/.github/workflows/fossa.yml @@ -25,6 +25,6 @@ jobs: uses: actions/checkout@85e6279cec87321a52edac9c87bce653a07cf6c2 # v4.2.2 - name: Scan - uses: fossas/fossa-action@c0a7d013f84c8ee5e910593186598625513cc1e4 # v1.6.0 + uses: fossas/fossa-action@3ebcea1862c6ffbd5cf1b4d0bd6b3fe7bd6f2cac # v1.7.0 with: api-key: ${{ secrets.FOSSA_TOKEN }} \ No newline at end of file diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml index e82efb09b..bf148bda9 100644 --- a/.github/workflows/linkchecker.yml +++ b/.github/workflows/linkchecker.yml @@ -31,7 +31,7 @@ env: --ignore-url ^https://lightstep.com --ignore-url ^https://www.owasp.org/ --ignore-url ^https://www.maxmind.com --ignore-url ^https://www.splunk.com/ --ignore-url ^https://oauth2.googleapis.com --ignore-url ^https://openidconnect.googleapis.com --ignore-url ^https://www.base64url.com/ --ignore-url ^https://go.googlesource.com/ --ignore-url ^https://go.googlesource.com/sync --ignore-url ^https://linkerd.io/2.13/ - --ignore-url ^http://www.redirectpage.com/ --ignore-url ^https://www.gnu.org/ + --ignore-url ^http://www.redirectpage.com/ --ignore-url ^https://www.gnu.org/ --ignore-url ^https://insert_your_tenant_name.console.ves.volterra.io/ --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginx-ingress-controller/css --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginxaas/azure/css --ignore-url ^https://\([a-zA-Z0-9-]+\).nginx.com/nginx-gateway-fabric/css diff --git a/.github/workflows/notification.yml b/.github/workflows/notification.yml index 076db92ca..810345ea2 100644 --- a/.github/workflows/notification.yml +++ b/.github/workflows/notification.yml @@ -75,4 +75,4 @@ jobs: }] } env: - SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} \ No newline at end of file + SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL_DOCS_INCIDENT }} \ No newline at end of file diff --git a/.github/workflows/ossf_scorecard.yml b/.github/workflows/ossf_scorecard.yml index 86cd9f9bc..864924b3a 100644 --- a/.github/workflows/ossf_scorecard.yml +++ b/.github/workflows/ossf_scorecard.yml @@ -56,6 +56,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: Upload SARIF results to code scanning - uses: github/codeql-action/upload-sarif@28deaeda66b76a05916b6923827895f2b14ab387 # v3.28.16 + uses: github/codeql-action/upload-sarif@181d5eefc20863364f96762470ba6f862bdef56b # v3.29.2 with: sarif_file: results.sarif diff --git a/.gitignore b/.gitignore index e0070f1b2..15fbca634 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,8 @@ # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. **/.DS_Store -# dependencies +# Log files +*.log # testing /coverage diff --git a/.gitlint b/.gitlint new file mode 100644 index 000000000..c776e9dbb --- /dev/null +++ b/.gitlint @@ -0,0 +1,15 @@ +[general] +ignore = body-is-missing +contrib = contrib-title-conventional-commits + +[title-max-length] +line-length = 50 + +[title-min-length] +min-length = 5 + +[body-max-line-length] +line-length= 72 + +[body-min-length] +min-length = 5 \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..d48d49e18 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,13 @@ +default_install_hook_types: + - pre-commit + - commit-msg + +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: no-commit-to-branch +- repo: https://github.com/jorisroovers/gitlint + rev: v0.19.1 + hooks: + - id: gitlint diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index b65b17fe4..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,5 +0,0 @@ -# Changelog - -## 1.0.0 (January 13, 2025) - -Initial open source release of the documentation repository for enterprise NGINX products. This is a filtered mirror of an internal repository. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c3f94a48..7a0af1f48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,78 +1,51 @@ # Contributing guidelines -The following is a set of guidelines for community contributions to this -project. We really appreciate your desire to contribute! +The following are a set of guidelines for contributing to this project. We appreciate your desire to get involved! -If you are an F5 employee, see the following additional guidance [For F5 Employees](./F5-NGINX-team-notes.md). +If you are an F5 employee, see the following additional guidance on [Maintainers etiquette](/documentation/maintainers-etiquette.md). ## Table of contents -- [Report a Bug](#report-a-bug) -- [Suggest a Feature or Enhancement](#suggest-a-feature-or-enhancement) -- [Open a Discussion](#open-a-discussion) -- [Submit a Pull Request](#submit-a-pull-request) - - Review our [Git style guide](#git-style-guide) - - Review our Documentation [style guide](./templates/style-guide.md) - - Review our [Contributing guidelines for writers](./CONTRIBUTING_DOCS.md) -- [Issue Lifecycle](#issue-lifecycle) +- [Create an issue](#create-an-issue) +- [Start a discussion](#start-a-discussion) +- [Submit a pull request](#submit-a-pull-request) +- [Issue lifecycle](#issue-lifecycle) - [Additional NGINX documentation](#additional-nginx-documentation) - [F5 Contributor License Agreement (CLA)](#f5-contributor-license-agreement) -## Report a bug +## Create an issue -To report a bug, open an issue on GitHub with the label `bug` using the -available bug report issue template. Before reporting a bug, make sure the -issue has not already been reported. +One way to contribute to the project is by [creating an issue](https://github.com/nginx/documentation/issues/new/choose). -## Suggest a feature or enhancement +The two most common are enhancements and bug reports. When using the issue templates, they will be automatically labelled. -To suggest a feature or enhancement, open an issue on GitHub with the label -`feature` or `enhancement` using the available feature request issue template. -Please ensure the feature or enhancement has not already been suggested. +- An enhancement is an improvement of some kind, such as a new document or additional detail for a product feature +- A bug report draws attention to an issue in documentation, such as an incorrect command or outdated information -## Open a Discussion +Before creating an issue, please check there is [no existing issue](https://github.com/nginx/documentation/issues?q=is%3Aissue) for the topic. -If you want to start a conversation with the community and maintainers, -we encourage you to use -[GitHub Discussions](https://github.com/nginx/documentation/discussions). +We encourage discussions within issues, since they act as a source of contextual truth and are linked to pull requests. -## Submit a Pull Request +## Start a discussion -To contribute to F5 NGINX documentation, follow these steps: +We encourage you to use [GitHub Discussions](https://github.com/nginx/documentation/discussions) for conversations with the community and maintainers. -- Fork the NGINX repository -- Create a branch -- Implement your changes in your branch -- Submit a pull request (PR) when your changes are ready for review - -Alternatively, you're welcome to suggest improvements to highlight problems with -our documentation as described in our [support](./SUPPORT.md) page. - -### Git style guide +If you'd like to discuss something NGINX-related that doesn't involve documentation, you should go to the [NGINX Community Forum](https://community.nginx.org/). -- Keep a clean, concise and meaningful Git commit history on your branch, rebasing locally and squashing before you submit a PR -- Follow the guidelines of writing a good commit message as described here - and summarized in the next few points: +## Submit a pull request - - In the subject line, use the present tense ("Add feature" not "Added feature") - - In the subject line, use the imperative mood ("Move cursor to..." not "Moves cursor to...") - - Limit the subject line to 72 characters or less - - Reference issues and pull requests liberally after the subject line - - Add more detailed description in the body of the git message (`git commit -a` to give you more space and time in - your text editor to write a good message instead of `git commit -am`) +Before making documentation changes, you should view the [documentation style guide](/documentation/style-guide.md) and [Managing content with Hugo](/documentation/writing-hugo.md). -#### Branch protection rules +To understand how we use Git in this repository, read our [Git conventions](/documentation/git-conventions.md) documentation. -This repository has the following branch protection rules in place: +The broad workflow is as follows: -- **Pushing branches that contain the "internal/" prefix is not allowed.** This ensures internal development branches are not accidentally or purposefully pushed to this repo. -- **Two approvers are required for all merges to main and release branches.** This ensures all code that is approved for release to production is appropriately reviewed. This rule applies to all branches with `*release*` in the branch name. -- **Only NGINX DocOps Team members can create release branches.** This ensures the docs team is aware of all branches supporting specific product releases. This rule applies to all branches with `*release*` in the branch name. -- **Pushes (force or otherwise) directly to main or release branches is not allowed.** Release branches serve as "main" for the release they are associated with. Restricting pushes directly to main and release branches ensures all content changes are reviewed and approved. This rule applies to all branches with `*release*` in the branch name and to "main". - -### Documentation style guide +- Fork the NGINX repository +- Create a branch +- Implement your changes in your branch +- Submit a pull request (PR) when your changes are ready for review -For detailed guidance, see our documentation [style guide](./templates/style-guide.md). +Alternatively, you're welcome to suggest improvements to highlight problems with our documentation as described in our [support](./SUPPORT.md) page. ## Issue lifecycle @@ -91,7 +64,6 @@ This repository does not include all of the source content for the NGINX documen - [NGINX Open Source](https://github.com/nginx/nginx) - source for [NGINX changelog](https://nginx.org/en/CHANGES) - [nginx.org](https://github.com/nginx/nginx.org) - source for https://nginx.org - [NGINX Unit](https://github.com/nginx/unit) - source for https://unit.nginx.org -- [NGINX Ingress Controller](https://github.com/nginxinc/kubernetes-ingress/) - source for https://docs.nginx.com/nginx-ingress-controller In those repositories, you can find documentation source code in the `docs` or `site` subdirectories. diff --git a/Makefile b/Makefile index 28c9379d7..9830d9e1e 100644 --- a/Makefile +++ b/Makefile @@ -1,16 +1,16 @@ HUGO?=hugo HUGO_VERSION?=$(shell hugo version 2>/dev/null | awk '{print $$2}' | cut -d '.' -f 2) -HUGO_IMG?=hugomods/hugo:std-go-git-0.134.3 +HUGO_IMG?=hugomods/hugo:std-go-git-0.147.8 THEME_MODULE = github.com/nginxinc/nginx-hugo-theme -ifeq ($(shell [ $(HUGO_VERSION) -gt 133 2>/dev/null ] && echo true || echo false), true) - $(info Hugo is available and has a version greater than 133. Proceeding with build.) +ifeq ($(shell [ $(HUGO_VERSION) -gt 146 2>/dev/null ] && echo true || echo false), true) + $(info Hugo is available and has a version greater than 146. Proceeding with build.) else - $(warning Hugo is not available or using a version less than 134. Attempting to use docker. HUGO_VERSION=$(HUGO_VERSION)) + $(warning Hugo is not available or using a version less than 147. Attempting to use docker. HUGO_VERSION=$(HUGO_VERSION)) HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} /src/hugo-entrypoint.sh ifeq (, $(shell docker version 2> /dev/null)) - $(error Hugo (>0.134) or Docker are required to build the local previews.) + $(error Hugo (>0.147) or Docker are required to build the local previews.) endif endif diff --git a/README.md b/README.md index 6143086f8..32acb02de 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,21 @@ [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/nginxinc/template-repository/main/CODE_OF_CONDUCT.md) ![Commercial Support](https://badgen.net/badge/support/commercial/green?icon=awesome) - - # NGINX documentation +This repository contains the user documentation for NGINX's products, as well as the requirements to build and publish the documentation website. + +Documentation is written in [Markdown](https://daringfireball.net/projects/markdown/basics), then transformed into HTML using the [Hugo](https://gohugo.io/) static site generator. + If you want to contribute to [F5 NGINX documentation](https://docs.nginx.com), you've come to the right place. We've organized a series of README-type files to help you get started: - [Contributing](/CONTRIBUTING.md) describes how you can contribute to our documentation. - - [Contributing guidelines for experts](/CONTRIBUTING_DOCS.md) describes how you can contribute (and check your work) with Hugo, our static site generator - [Code of Conduct](/CODE_OF_CONDUCT.md) describes expectations in the NGINX open source community. - [License](/LICENSE) shows the license associated with work on this repository. - [Security](/SECURITY.md) describes the procedures we would like you to follow if you find a security issue. - [Support](/SUPPORT.md) lists how you can get support as a customer or a community member. -## Explanation - -This repository contains user documentation for NGINX's products, as well as the requirements for linting, building, and publishing the documentation. - -Our documentation is written in Markdown, specifically the [Goldmark](https://github.com/yuin/goldmark) Markdown parser. -We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs on Azure. +You may also find the [documentation folder](/documentation/) for the repository interesting: it's where we store our process information. ## License @@ -30,7 +26,6 @@ We build our docs using [Hugo](https://gohugo.io) and host them in custom URLs o © [F5, Inc.](https://www.f5.com/) 2025 - ## Credits - [The Good Docs Project](https://www.thegooddocsproject.dev/), whose templates we've adapted for our use. diff --git a/_banners/agent-v3-release.md b/_banners/agent-v3-release.md new file mode 100644 index 000000000..87bd0021a --- /dev/null +++ b/_banners/agent-v3-release.md @@ -0,0 +1,10 @@ +{{< banner "notice" "NGINX Agent 3.0 is now available" >}} + +The documentation in this section is for **NGINX Agent version 2.x**. For NGINX Agent 3.x content visit the [NGINX One Console documentation]({{< ref "/nginx-one/agent/" >}}) + +F5 NGINX Instance Manager (NIM) does not currently support NGINX Agent 3.x. NGINX Instance Manager customers can upgrade to the latest NGINX Agent 2.x version by following the [Upgrade NGINX Agent](/nginx-agent/installation-upgrade/upgrade/) guide. + +Please see the [Technical specifications](/nginx-agent/technical-specifications/) for product compatibility. + + +{{< /banner >}} \ No newline at end of file diff --git a/_banners/eos-acm.md b/_banners/eos-acm.md new file mode 100644 index 000000000..e69f51b6b --- /dev/null +++ b/_banners/eos-acm.md @@ -0,0 +1,8 @@ +{{< banner "warning" "End of Sale Notice:" >}} +
+ F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024. +

+ F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024. +

+ See our End of Sale announcement for more details. +{{}} \ No newline at end of file diff --git a/_banners/eos-mesh.md b/_banners/eos-mesh.md index e69f51b6b..f2b11d535 100644 --- a/_banners/eos-mesh.md +++ b/_banners/eos-mesh.md @@ -1,8 +1,8 @@ {{< banner "warning" "End of Sale Notice:" >}} -
- F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024. -

- F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024. -

- See our End of Sale announcement for more details. +

+ Commercial support for NGINX Service Mesh is available to customers who currently have active NGINX Microservices Bundle subscriptions. F5 NGINX announced the End of Sale (EoS) for the NGINX Microservices Bundles as of July 1, 2023. +

+

+ See our End of Sale announcement for more details. +

{{}} \ No newline at end of file diff --git a/archetypes/landing-page.md b/archetypes/landing-page.md new file mode 100644 index 000000000..91c1ab0d2 --- /dev/null +++ b/archetypes/landing-page.md @@ -0,0 +1,49 @@ +--- +# The title is the product name +title: +# The URL is the base of the deployed path, becoming "docs.nginx.com//" +url: +# The cascade directive applies its nested parameters down the page tree until overwritten +cascade: + # The logo file is resolved from the theme, in the folder /static/images/icons/ + logo: +# The subtitle displays directly underneath the heading of a given page +nd-subtitle: +# Indicates that this is a custom landing page +nd-landing-page: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: landing-page +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: +--- + +## About +[//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections." +[//]: # "Use underscores for _italics_, and double asterisks for **bold**." +[//]: # "Backticks are for `monospace`, used sparingly and reserved mostly for executable names - they can cause formatting problems. Avoid them in tables: use italics instead." + +[//]: # "This initial section introduces the product to a reader: give a short 1-2 sentence summary of what the product does and its value to the reader." +[//]: # "Name specific functionality it provides: avoid ambiguous descriptions such as 'enables efficiency', focus on what makes it unique." + +## Featured content +[//]: # "You can add a maximum of three cards: any extra will not display." +[//]: # "One card will take full width page: two will take half width each. Three will stack like an inverse pyramid." +[//]: # "Some examples of content could be the latest release note, the most common install path, and a popular new feature." + +{{}} + {{}} + {{}} + + {{}} + + + {{}} + + {{}} + {{}} +{{}} + +## Other content + +[//]: # "You can add any extra content for the page here, such as additional cards, diagrams or text." \ No newline at end of file diff --git a/config/_default/config.toml b/config/_default/config.toml index 10337a908..54c29d430 100644 --- a/config/_default/config.toml +++ b/config/_default/config.toml @@ -7,18 +7,19 @@ pygmentsUseClasses = true enableGitInfo = true [permalinks] - amplify = '/nginx-amplify/:sections[1:]/:filename' - controller = '/nginx-controller/:sections[1:]/:filename' - mesh = '/nginx-service-mesh/:sections[1:]/:filename' - modsec-waf = '/nginx-waf/:sections[1:]/:filename' - nap-dos = '/nginx-app-protect-dos/:sections[1:]/:filename' - nap-waf = '/nginx-app-protect-waf/:sections[1:]/:filename' - ngf = '/nginx-gateway-fabric/:sections[1:]/:filename' - nim = '/nginx-instance-manager/:sections[1:]/:filename' - nms = '/nginx-management-suite/:sections[1:]/:filename' - unit = '/nginx-unit/:sections[1:]/:filename' - agent = '/nginx-agent/:sections[1:]/:filename' - nginxaas = '/nginxaas/azure/:sections[1:]/:filename' + agent = '/nginx-agent/:sections[1:]/:contentbasename' + amplify = '/nginx-amplify/:sections[1:]/:contentbasename' + controller = '/nginx-controller/:sections[1:]/:contentbasename' + mesh = '/nginx-service-mesh/:sections[1:]/:contentbasename' + modsec-waf = '/nginx-waf/:sections[1:]/:contentbasename' + nap-dos = '/nginx-app-protect-dos/:sections[1:]/:contentbasename' + nap-waf = '/nginx-app-protect-waf/:sections[1:]/:contentbasename' + nginxaas = '/nginxaas/azure/:sections[1:]/:contentbasename' + ngf = '/nginx-gateway-fabric/:sections[1:]/:contentbasename' + nic = '/nginx-ingress-controller/:sections[1:]/:contentbasename' + nim = '/nginx-instance-manager/:sections[1:]/:contentbasename' + nms = '/nginx-management-suite/:sections[1:]/:contentbasename' + unit = '/nginx-unit/:sections[1:]/:contentbasename' [caches] [caches.modules] diff --git a/config/production/config.toml b/config/production/config.toml index b367a4d63..f6b653af3 100644 --- a/config/production/config.toml +++ b/config/production/config.toml @@ -11,7 +11,7 @@ enableGitInfo = true useSessionStorage = false [privacy.instagram] disable = true - [privacy.twitter] + [privacy.x] disable = false enableDNT = true simple = false diff --git a/content/agent/_index.md b/content/agent/_index.md index 330490eb8..478ab4f4b 100644 --- a/content/agent/_index.md +++ b/content/agent/_index.md @@ -1,8 +1,58 @@ --- title: NGINX Agent -description: NGINX Agent is a companion daemon for your NGINX Open Source or NGINX - Plus instance. url: /nginx-agent/ cascade: logo: NGINX-product-icon.png + nd-banner: + enabled: true + type: deprecation + start-date: 2025-05-29 + end-date: 2025-09-09 + md: /_banners/agent-v3-release.md +# The subtitle displays directly underneath the heading of a given page +nd-subtitle: +# Indicates that this is a custom landing page +nd-landing-page: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: landing-page +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: Agent --- + +## About + +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, and notifications of NGINX events. + +[//]: # "This initial section introduces the product to a reader: give a short 1-2 sentence summary of what the product does and its value to the reader." +[//]: # "Name specific functionality it provides: avoid ambiguous descriptions such as 'enables efficiency', focus on what makes it unique." + +## Featured content +[//]: # "You can add a maximum of three cards: any extra will not display." +[//]: # "One card will take full width page: two will take half width each. Three will stack like an inverse pyramid." +[//]: # "Some examples of content could be the latest release note, the most common install path, and a popular new feature." + +{{}} + {{}} + {{}} + Learn everything you need to know about NGINX Agent + {{}} + + + {{}} + Install NGINX Agent and run a mock control plane + {{}} + {{}} +{{}} + +{{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} + {{}} +{{}} \ No newline at end of file diff --git a/content/agent/overview.md b/content/agent/about.md similarity index 94% rename from content/agent/overview.md rename to content/agent/about.md index 289b6ebab..19434fbb2 100644 --- a/content/agent/overview.md +++ b/content/agent/about.md @@ -1,16 +1,15 @@ --- -title: Overview +title: About draft: false weight: 100 toc: true -docs: DOCS-1091 -type: -- how-to +nd-docs: DOCS-1091 +nd-content-type: how-to --- ## Overview -NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables: +NGINX Agent version 2 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 @@ -47,7 +46,6 @@ For NGINX Agent to work properly with an NGINX Plus instance, the API needs to b 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 | | -------------------------------- | -------------------------------------------- | @@ -64,6 +62,6 @@ NGINX Agent allows a gRPC connected control system to register a listener for a | 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/changelog.md b/content/agent/changelog.md index b0f79ce37..666c29286 100644 --- a/content/agent/changelog.md +++ b/content/agent/changelog.md @@ -1,286 +1,10 @@ --- -title: "Changelog" +title: Changelog +toc: false +url: /agent/changelog weight: 1200 toc: true -docs: "DOCS-1093" +nd-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.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) - ---- -## 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) - + \ No newline at end of file diff --git a/content/agent/community.md b/content/agent/community.md new file mode 100644 index 000000000..932fb492b --- /dev/null +++ b/content/agent/community.md @@ -0,0 +1,20 @@ +--- +title: Community and contribution +toc: true +weight: 600 +nd-docs: DOCS-1884 +--- + +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 index 1c0c90128..ca784b6eb 100644 --- a/content/agent/configuration/_index.md +++ b/content/agent/configuration/_index.md @@ -1,6 +1,10 @@ --- -title: Configuration -description: Learn how to configure NGINX Agent. -weight: 400 +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/configuration/configuration-overview.md b/content/agent/configuration/configuration-overview.md index 51e724fa2..41086bd8a 100644 --- a/content/agent/configuration/configuration-overview.md +++ b/content/agent/configuration/configuration-overview.md @@ -3,9 +3,8 @@ 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. @@ -50,7 +49,7 @@ server: # host of the control plane host: grpcPort: 443 - backoff: # note: default values are prepopulated + backoff: # note: default values are prepopulated initial_interval: 100ms # Add the appropriate duration value here, for example, "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, for example, 0.10 multiplier: 1.5 # Add the appropriate float value here, for example, 1.5 @@ -88,7 +87,7 @@ metrics: report_interval: 1m collection_interval: 15s mode: aggregated - backoff: # note: default values are prepopulated + backoff: # note: default values are prepopulated initial_interval: 100ms # Add the appropriate duration value here, for example, "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, for example, 0.10 multiplier: 1.5 # Add the appropriate float value here, for example, 1.5 @@ -170,9 +169,9 @@ nginx-agent ### CLI Flags and Environment Variables -{{< warning >}} +{{< warning >}} -Before version 2.35.0, the environment variables were prefixed with `NMS_` instead of `NGINX_AGENT_`. +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. @@ -220,9 +219,9 @@ If you are upgrading from an older version, update your configuration accordingl
{{}} -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. +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 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: 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 486059eb4..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 -type: -- how-to -docs: DOCS-1678 ---- - -## 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/configuration/configure-nginx-agent-group.md b/content/agent/configuration/configure-nginx-agent-group.md index 47e6f15e0..bf3f1d0f7 100644 --- a/content/agent/configuration/configure-nginx-agent-group.md +++ b/content/agent/configuration/configure-nginx-agent-group.md @@ -1,11 +1,10 @@ --- -title: Add NGINX users to nginx-agent Group +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/configuration/encrypt-communication.md b/content/agent/configuration/encrypt-communication.md index a7cf75134..6a1503cf6 100644 --- a/content/agent/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/configuration/health-checks.md b/content/agent/configuration/health-checks.md index 16a9bf53d..ef087c9d5 100644 --- a/content/agent/configuration/health-checks.md +++ b/content/agent/configuration/health-checks.md @@ -3,9 +3,8 @@ title: Health checks draft: false weight: 400 toc: true -type: -- how-to -docs: DOCS-1677 +nd-content-type: how-to +nd-docs: DOCS-1677 --- ## Overview diff --git a/content/agent/contribute/_index.md b/content/agent/contribute/_index.md deleted file mode 100644 index a11203387..000000000 --- a/content/agent/contribute/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Contribute -description: Learn about the NGINX Agent community and contribute to the project. -weight: 500 -url: /nginx-agent/contribute/ ---- diff --git a/content/agent/contribute/community.md b/content/agent/contribute/community.md deleted file mode 100644 index da54b13b0..000000000 --- a/content/agent/contribute/community.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Community and contribution -draft: false -weight: 100 -toc: true -docs: DOCS-1087 -type: -- how-to ---- - -# 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 7f75df9d8..72827ceba 100644 --- a/content/agent/contribute/dev-environment-setup.md +++ b/content/agent/contribute/dev-environment-setup.md @@ -1,64 +1,61 @@ --- -title: Development environment setup -draft: false -weight: 200 +title: "Development environment setup" toc: true -docs: DOCS-1088 -type: -- how-to +nd-docs: DOCS-1088 +nd-content-type: how-to --- ## Overview -Learn how to setup a Development Environment for NGINX Agent. +This page describes how to configure a development environment for F5 NGINX Agent. -## Select an Operating System +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 packaged with most libraries required to build and run NGINX Agent, and is the recommended platform for NGINX Agent development. +Ubuntu is the recommended operating system for development, as it comes with most packages requires to build and run NGINX Agent. -## Install NGINX +## Before you begin -Follow the steps in the [Installation]({{< ref "/agent/installation-upgrade/" >}}) section to download, install, and run NGINX and NGINX Agent. +To begin this task, you will require the following: -## Clone the NGINX Agent Repository +- 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. -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. +You will also need a copy of the NGINX Agent repository, which you can clone using `git`: -## Installing Prerequisite Packages +```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 + +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. 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..9b338d09f --- /dev/null +++ b/content/agent/contribute/start-mock-interface.md @@ -0,0 +1,91 @@ +--- +title: Start mock control plane interface +toc: true +weight: 300 +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. + +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 "/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. + +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]({{< ref "/agent/how-to/enable-interfaces.md" >}}) topic. + +## Launch Swagger UI + +To launch the Swagger UI for the REST interface run the following command: + +```shell +make launch-swagger-ui +``` + +## Start NGINX Agent + +Open another terminal window and start NGINX Agent. Issue the following command from the `agent` source code root directory. + +```shell +sudo make run +``` +```text +WARN[0000] Log level is info +INFO[0000] setting displayName to XXX +INFO[0000] NGINX Agent at with pid 12345, clientID=XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX name=XXX +INFO[0000] NginxBinary initializing +INFO[0000] Commander initializing +INFO[0000] Comms initializing +INFO[0000] OneTimeRegistration initializing +INFO[0000] Registering XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX +INFO[0000] Metrics initializing +INFO[0000] MetricsThrottle initializing +INFO[0000] DataPlaneStatus initializing +INFO[0000] MetricsThrottle waiting for report ready +INFO[0000] Metrics waiting for handshake to be completed +INFO[0000] ProcessWatcher initializing +INFO[0000] Extensions initializing +INFO[0000] FileWatcher initializing +INFO[0000] FileWatchThrottle initializing +INFO[0001] Events initializing +INFO[0001] OneTimeRegistration completed +``` + +Open a web browser to view the mock control plane at [http://localhost:54790](http://localhost:54790). The following links will be shown in the web interface: + +- **registered** - shows registration information of the data plane +- **nginxes** - lists the nginx instances on the data plane +- **configs** - shows the protobuf payload for NGINX configuration sent to the management plane +- **configs/chunked** - shows the split-up payloads sent to the management plane +- **configs/raw** - shows the actual configuration as it would live on the data plane +- **metrics** - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API) + +For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/main/sdk/examples). \ No newline at end of file diff --git a/content/agent/installation-upgrade/_index.md b/content/agent/installation-upgrade/_index.md index 1d84d3ebc..d17ef4d5d 100644 --- a/content/agent/installation-upgrade/_index.md +++ b/content/agent/installation-upgrade/_index.md @@ -2,5 +2,8 @@ title: Installation and upgrade description: Learn how to install, upgrade, and uninstall NGINX Agent. weight: 300 -url: /nginx-agent/installation-upgrade/ +url: /nginx-agent/v2/installation-upgrade/ +cascade: + logo: NGINX-product-icon.png + type: agent-v2-migration --- diff --git a/content/agent/installation-upgrade/container-environments/_index.md b/content/agent/installation-upgrade/container-environments/_index.md index 35c6aa73f..bc1eeddd7 100644 --- a/content/agent/installation-upgrade/container-environments/_index.md +++ b/content/agent/installation-upgrade/container-environments/_index.md @@ -2,5 +2,8 @@ title: Container environments description: Learn how to build and run NGINX Agent docker images. weight: 800 -ur: /nginx-agent/installation-upgrade/container-environments/ +url: /nginx-agent/v2/installation-upgrade/container-environments/ +cascade: + logo: NGINX-product-icon.png + type: agent-v2-migration --- diff --git a/content/agent/installation-upgrade/container-environments/docker-images.md b/content/agent/installation-upgrade/container-environments/docker-images.md index d12f94e5e..f21c23929 100644 --- a/content/agent/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 diff --git a/content/agent/installation-upgrade/container-environments/docker-support.md b/content/agent/installation-upgrade/container-environments/docker-support.md index 2f9c5eafc..1a57cafab 100644 --- a/content/agent/installation-upgrade/container-environments/docker-support.md +++ b/content/agent/installation-upgrade/container-environments/docker-support.md @@ -3,8 +3,8 @@ title: Container support and troubleshooting draft: false toc: true weight: 200 -docs: DOCS-909 -type: +nd-docs: DOCS-909 +nd-content-type: - task --- @@ -12,7 +12,7 @@ type: 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/technical-specifications.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/installation-upgrade/getting-started.md b/content/agent/installation-upgrade/getting-started.md index e3dc9f3a2..c7ee427af 100644 --- a/content/agent/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 diff --git a/content/agent/installation-upgrade/installation-github.md b/content/agent/installation-upgrade/installation-github.md index 282f1e8d9..d1cbbb2d6 100644 --- a/content/agent/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/installation-upgrade/installation-oss.md b/content/agent/installation-upgrade/installation-oss.md index 92c3a3306..ab4016d08 100644 --- a/content/agent/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 diff --git a/content/agent/installation-upgrade/installation-plus.md b/content/agent/installation-upgrade/installation-plus.md index 6ee2482d4..add1272dc 100644 --- a/content/agent/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 diff --git a/content/agent/installation-upgrade/installation-unprivileged.md b/content/agent/installation-upgrade/installation-unprivileged.md index 137bdf752..4bf90c9f1 100644 --- a/content/agent/installation-upgrade/installation-unprivileged.md +++ b/content/agent/installation-upgrade/installation-unprivileged.md @@ -2,8 +2,10 @@ title: Run without root privileges weight: 450 toc: true -type: how-to +nd-content-type: + - how-to product: Agent +nd-docs: DOCS-1781 --- ## Overview diff --git a/content/agent/installation-upgrade/uninstall.md b/content/agent/installation-upgrade/uninstall.md index 2f783dbb6..56db538f0 100644 --- a/content/agent/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/installation-upgrade/upgrade.md b/content/agent/installation-upgrade/upgrade.md index 50477e94b..f942db01f 100644 --- a/content/agent/installation-upgrade/upgrade.md +++ b/content/agent/installation-upgrade/upgrade.md @@ -3,18 +3,15 @@ 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 Learn how to upgrade 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 >}} +## Upgrade NGINX Agent To upgrade NGINX Agent, follow these steps: @@ -41,43 +38,48 @@ To upgrade NGINX Agent, follow these steps: sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" ``` +## Upgrade NGINX Agent to a Specific Version +To upgrade NGINX Agent to a specific **v2.x version**, follow these steps: -## Upgrade NGINX Agent from a version less than v2.31.0 +#### Steps to Upgrade: -To upgrade NGINX Agent, take the following steps: +1. Open an SSH connection to the server running NGINX Agent and log in. -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: +1. Back up the following files and directories to ensure you can restore the environment in case of issues during the upgrade: - `/etc/nginx-agent` - - `config_dirs` values for any configuration specified in `/etc/nginx-agent/nginx-agent.conf` + - Any `config_dirs` directory specified in `/etc/nginx-agent/nginx-agent.conf`. -1. Stop NGINX Agent: +1. Perform the version-controlled upgrade. - ```shell - sudo systemctl stop nginx-agent - ``` + - Debian, Ubuntu, Deb-Based -1. Install the updated version of NGINX Agent: + ```shell + sudo apt-get update + sudo apt-get install -y nginx-agent= -o Dpkg::Options::="--force-confold" + ``` + + Example (to upgrade to version 2.41.1~noble): + + ```shell + sudo apt-get install -y nginx-agent=2.41.1~noble -o Dpkg::Options::="--force-confold" + ``` - CentOS, RHEL, RPM-Based ```shell - sudo yum -y makecache - sudo yum update -y nginx-agent + sudo yum install -y nginx-agent- ``` - - Debian, Ubuntu, Deb-Based + Example (to upgrade to version `2.41.1`): ```shell - sudo apt-get update - sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold" + sudo yum install -y nginx-agent-2.41.1 ``` -1. Start NGINX Agent: +1. Verify the installed version: ```shell - sudo systemctl start nginx-agent + sudo nginx-agent --version ``` diff --git a/content/agent/support.md b/content/agent/support.md new file mode 100644 index 000000000..363925c75 --- /dev/null +++ b/content/agent/support.md @@ -0,0 +1,21 @@ +--- +title: Support +weight: 800 +toc: false +nd-content-type: reference +product: Agent +nd-docs: DOCS-1883 +--- + +## Support policy +F5 NGINX Agent adheres to the support policy detailed in the following knowledge base article: [K000140156](https://my.f5.com/manage/s/article/K000140156). + + +## Contact F5 Support + +For questions and/or assistance with installing, troubleshooting, or using NGINX Agent, contact support via the [MyF5 Customer Portal](https://account.f5.com/myf5). + +## Community support + +- If you experience issues with NGINX Agent, please [open an issue in GitHub](https://github.com/nginx/agent/issues/new). +- If you have any suggestions or feature requests, please [open an idea in GitHub discussions](https://github.com/nginx/agent/discussions). diff --git a/content/agent/technical-specifications.md b/content/agent/technical-specifications.md index 7ecd18398..b4273c922 100644 --- a/content/agent/technical-specifications.md +++ b/content/agent/technical-specifications.md @@ -1,37 +1,46 @@ --- -title: Technical specifications -draft: false -weight: 200 +title: "Technical specifications" +weight: 100 toc: true -docs: DOCS-1092 -type: -- how-to +nd-docs: DOCS-1092 +nd-content-type: how-to --- -## Overview +This document describes the requirements for NGINX Agent version 2. This document provides technical specifications for NGINX Agent. It includes information on supported distributions, deployment environments, NGINX versions, sizing recommendations, and logging. +## NGINX Agent 3.0 Compatibility +{{< bootstrap-table "table table-striped table-bordered" >}} +| NGINX Product | Agent Version | +|------------------------------|----------------| +| **NGINX One Console** | 2.x | +| **NGINX Gateway Fabric** | 3.x | +| **NGINX Plus** | 2.x, 3.x | +| **NGINX Ingress Controller** | 2.x | +| **NGINX Instance Manager** | 2.x | +{{< /bootstrap-table >}} + ## 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.18
3.19
3.20
3.21| 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|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: @@ -40,12 +49,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" >}} diff --git a/content/amplify/additional-resources.md b/content/amplify/additional-resources.md index 554e6c8b3..f794475ce 100644 --- a/content/amplify/additional-resources.md +++ b/content/amplify/additional-resources.md @@ -2,7 +2,7 @@ title: Other NGINX Amplify Resources weight: 899 toc: true -docs: DOCS-977 +nd-docs: DOCS-977 --- If you are interested in learning more about F5 NGINX Amplify, visit the [NGINX Amplify Resources Page](https://amplify.nginx.com/docs/), where you will find links to: diff --git a/content/amplify/changelog.md b/content/amplify/changelog.md index 6024dcfad..b39e69e95 100644 --- a/content/amplify/changelog.md +++ b/content/amplify/changelog.md @@ -1,8 +1,9 @@ --- -title: "Changelog" -description: "These release notes list and describe the new features, enhancements, and resolved issues in F5 NGINX Amplify" +title: Changelog +description: These release notes list and describe the new features, enhancements, and resolved issues in F5 NGINX Amplify weight: 900 toc: true +nd-docs: DOCS-1691 --- ## Sept 21, 2023 diff --git a/content/amplify/faq/general.md b/content/amplify/faq/general.md index 5aab8c8f2..53d0775bd 100644 --- a/content/amplify/faq/general.md +++ b/content/amplify/faq/general.md @@ -3,7 +3,7 @@ title: General description: General questions about F5 NGINX Amplify weight: 10 toc: true -docs: DOCS-956 +nd-docs: DOCS-956 --- ### What Is F5 NGINX Amplify? diff --git a/content/amplify/faq/metrics-and-metadata.md b/content/amplify/faq/metrics-and-metadata.md index ea7820bd5..f91ae8dd8 100644 --- a/content/amplify/faq/metrics-and-metadata.md +++ b/content/amplify/faq/metrics-and-metadata.md @@ -3,7 +3,7 @@ title: NGINX Amplify Metrics and Metadata description: Questions about F5 NGINX Amplify's Metrics and Metadata weight: 40 toc: true -docs: DOCS-957 +nd-docs: DOCS-957 --- ### What Data Does F5 NGINX Amplify Agent Gather? diff --git a/content/amplify/faq/nginx-amplify-agent.md b/content/amplify/faq/nginx-amplify-agent.md index f6965a94b..eec52dc82 100644 --- a/content/amplify/faq/nginx-amplify-agent.md +++ b/content/amplify/faq/nginx-amplify-agent.md @@ -3,7 +3,7 @@ title: NGINX Amplify Agent description: Questions about F5 NGINX Amplify Agent weight: 20 toc: true -docs: DOCS-958 +nd-docs: DOCS-958 --- ### What Operating Systems are Supported? diff --git a/content/amplify/faq/user-interface.md b/content/amplify/faq/user-interface.md index 26277afee..5bad6022b 100644 --- a/content/amplify/faq/user-interface.md +++ b/content/amplify/faq/user-interface.md @@ -3,7 +3,7 @@ title: NGINX Amplify User Interface description: Questions about F5 NGINX Amplify's User Interface weight: 30 toc: true -docs: DOCS-959 +nd-docs: DOCS-959 --- ### What Browsers are Supported? diff --git a/content/amplify/known-issues.md b/content/amplify/known-issues.md index 667f24065..38b7db320 100644 --- a/content/amplify/known-issues.md +++ b/content/amplify/known-issues.md @@ -3,6 +3,7 @@ title: Known Issues weight: 1000 description: List of known issues in the latest release of F5 NGINX Amplify toc: true +nd-docs: DOCS-1692 --- {{}} diff --git a/content/amplify/metrics-metadata/metrics-overview.md b/content/amplify/metrics-metadata/metrics-overview.md index 6a6b34f2c..8a1970ed4 100644 --- a/content/amplify/metrics-metadata/metrics-overview.md +++ b/content/amplify/metrics-metadata/metrics-overview.md @@ -3,7 +3,7 @@ title: Metrics and Metadata Overview description: Learn about the metrics and metadata F5 NGINX Amplify collects. weight: 10 toc: true -docs: DOCS-972 +nd-docs: DOCS-972 --- Most metrics are collected by F5 NGINX Amplify Agent without requiring the user to perform any additional setup. For troubleshooting, see [Troubleshooting Metrics Collection]({{< ref "/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md" >}}). diff --git a/content/amplify/metrics-metadata/nginx-metrics.md b/content/amplify/metrics-metadata/nginx-metrics.md index 34971aab6..fd0e5e61c 100644 --- a/content/amplify/metrics-metadata/nginx-metrics.md +++ b/content/amplify/metrics-metadata/nginx-metrics.md @@ -3,7 +3,7 @@ title: NGINX Metrics description: List of NGINX Metrics weight: 30 toc: true -docs: DOCS-973 +nd-docs: DOCS-973 --- ## HTTP Connections and Requests @@ -48,7 +48,7 @@ docs: DOCS-973 ``` Type: gauge, integer - Description: Number of currently active requests (reading and writing). + Description: Number of currently active requests (reading and writing). Number of requests reading headers or writing responses to clients. Source: stub_status (or NGINX Plus status API) ``` @@ -127,7 +127,7 @@ docs: DOCS-973 ``` Type: counter, integer - Description: Number of requests finalized with status code 499 which is + Description: Number of requests finalized with status code 499 which is logged when the client closes the connection. Source: access.log ``` @@ -213,7 +213,7 @@ docs: DOCS-973 ``` Type: gauge, integer - Description: Hard limit on the number of file descriptors as seen + Description: Hard limit on the number of file descriptors as seen by NGINX worker processes. ``` diff --git a/content/amplify/metrics-metadata/os-metrics.md b/content/amplify/metrics-metadata/os-metrics.md index 6a204d0df..7de32fcb0 100644 --- a/content/amplify/metrics-metadata/os-metrics.md +++ b/content/amplify/metrics-metadata/os-metrics.md @@ -3,7 +3,7 @@ title: OS Metrics description: List of OS Metrics weight: 20 toc: true -docs: DOCS-974 +nd-docs: DOCS-974 --- ## System Metrics diff --git a/content/amplify/metrics-metadata/other-metrics.md b/content/amplify/metrics-metadata/other-metrics.md index 83b583573..2241f57e4 100644 --- a/content/amplify/metrics-metadata/other-metrics.md +++ b/content/amplify/metrics-metadata/other-metrics.md @@ -3,7 +3,7 @@ title: Other Metrics description: Learn about other metrics used by F5 NGINX Amplify weight: 40 toc: true -docs: DOCS-975 +nd-docs: DOCS-975 --- {{< note >}}Monitoring PHP-FPM and MySQL metrics is only supported by F5 NGINX Amplify Agent.{{< /note >}} diff --git a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md index 235fb15cd..51cc08ccb 100644 --- a/content/amplify/nginx-amplify-agent/amplify-agent-overview.md +++ b/content/amplify/nginx-amplify-agent/amplify-agent-overview.md @@ -3,7 +3,7 @@ title: NGINX Amplify Agent Overview description: Learn about F5 NGINX Amplify Agent. weight: 1 toc: true -docs: DOCS-960 +nd-docs: DOCS-960 --- F5 NGINX Amplify Agent is a compact application written in Python. Its role is to collect various metrics and metadata and send them securely to the backend for storage and visualization. diff --git a/content/amplify/nginx-amplify-agent/configuration-analysis.md b/content/amplify/nginx-amplify-agent/configuration-analysis.md index 0110f4a9b..0c227c3a9 100644 --- a/content/amplify/nginx-amplify-agent/configuration-analysis.md +++ b/content/amplify/nginx-amplify-agent/configuration-analysis.md @@ -3,7 +3,7 @@ title: NGINX Configuration Analysis description: Learn about F5 NGINX Amplify Agent's configuration analysis feature. weight: 600 toc: true -docs: DOCS-961 +nd-docs: DOCS-961 --- F5 NGINX Amplify Agent can automatically find all relevant NGINX configuration files, parse them, extract their logical structure, and send the associated JSON data to the Amplify backend for further analysis and reporting. For more information on configuration analysis, please see the [Analyzer]({{< ref "/amplify/user-interface/analyzer.md" >}})) documentation. diff --git a/content/amplify/nginx-amplify-agent/configuring-metric-collection.md b/content/amplify/nginx-amplify-agent/configuring-metric-collection.md index b3bf29981..311967d69 100644 --- a/content/amplify/nginx-amplify-agent/configuring-metric-collection.md +++ b/content/amplify/nginx-amplify-agent/configuring-metric-collection.md @@ -3,7 +3,7 @@ title: Configuring NGINX for Metric Collection description: Learn how to configure NGINX Instances to collect data. weight: 400 toc: true -docs: DOCS-963 +nd-docs: DOCS-963 --- To monitor an NGINX instance, F5 NGINX Amplify Agent must [find the relevant NGINX master process]({{< ref "/amplify/nginx-amplify-agent/detecting-monitoring-instances" >}}) and determine its key characteristics. diff --git a/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md b/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md index 1df04cd92..85508a998 100644 --- a/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md +++ b/content/amplify/nginx-amplify-agent/detecting-monitoring-instances.md @@ -3,7 +3,7 @@ title: Detecting and Monitoring NGINX Instances description: Learn how F5 NGINX Amplify Agent detects NGINX Instances. weight: 300 toc: true -docs: DOCS-962 +nd-docs: DOCS-962 --- F5 NGINX Amplify Agent is capable of detecting several types of NGINX instances: diff --git a/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md index b8d5e3f41..572725403 100644 --- a/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/configuring-amplify-agent.md @@ -3,7 +3,7 @@ title: Configuring NGINX Amplify Agent description: Learn how to configure F5 NGINX Amplify Agent. weight: 300 toc: true -docs: DOCS-967 +nd-docs: DOCS-967 --- F5 NGINX Amplify Agent keeps its configuration in `/etc/amplify-agent/agent.conf`. The NGINX Amplify Agent configuration is a text-based file. diff --git a/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md index dea514179..1dcbb9241 100644 --- a/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/installing-amplify-agent.md @@ -3,7 +3,7 @@ title: Install NGINX Amplify Agent description: Learn how to install F5 NGINX Amplify Agent. weight: 100 toc: true -docs: DOCS-968 +nd-docs: DOCS-968 --- To use F5 NGINX Amplify to monitor your infrastructure, you need to install NGINX Amplify Agent on each system you wish to monitor. diff --git a/content/amplify/nginx-amplify-agent/install/uninstalling-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/uninstalling-amplify-agent.md index 341d5d1bb..702c0ff87 100644 --- a/content/amplify/nginx-amplify-agent/install/uninstalling-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/uninstalling-amplify-agent.md @@ -3,7 +3,7 @@ title: Uninstall NGINX Amplify Agent description: Learn how to uninstall F5 NGINX Amplify Agent. weight: 400 toc: true -docs: DOCS-969 +nd-docs: DOCS-969 --- To completely delete a previously monitored object, perform the following steps: diff --git a/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md b/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md index a616bccdf..e7c0f2c57 100644 --- a/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md +++ b/content/amplify/nginx-amplify-agent/install/updating-amplify-agent.md @@ -3,7 +3,7 @@ title: Update NGINX Amplify Agent description: Learn how to update F5 NGINX Amplify Agent. weight: 200 toc: true -docs: DOCS-970 +nd-docs: DOCS-970 --- {{< important >}} diff --git a/content/amplify/nginx-amplify-agent/install/using-amplify-agent-docker.md b/content/amplify/nginx-amplify-agent/install/using-amplify-agent-docker.md index 6b979affb..ee91d9b50 100644 --- a/content/amplify/nginx-amplify-agent/install/using-amplify-agent-docker.md +++ b/content/amplify/nginx-amplify-agent/install/using-amplify-agent-docker.md @@ -3,7 +3,7 @@ title: Use NGINX Amplify Agent with Docker description: Learn how to use F5 NGINX Amplify Agent with Docker. weight: 500 toc: true -docs: DOCS-971 +nd-docs: DOCS-971 --- You can use F5 NGINX Amplify Agent in a Docker environment. Although it's still work-in-progress, NGINX Amplify Agent can collect most of the metrics and send them over to the Amplify backend in either "standalone" or "aggregate" mode. The standalone mode of operation is the simplest one, with a separate "host" created for each Docker container. Alternatively, the metrics from NGINX Amplify Agents running in different containers can be aggregated on a "per-image" basis β€” this is the aggregate mode of deploying NGINX Amplify Agent with Docker. diff --git a/content/amplify/nginx-amplify-agent/metadata-metrics-collection.md b/content/amplify/nginx-amplify-agent/metadata-metrics-collection.md index 0263c68f6..b5ea87f65 100644 --- a/content/amplify/nginx-amplify-agent/metadata-metrics-collection.md +++ b/content/amplify/nginx-amplify-agent/metadata-metrics-collection.md @@ -3,7 +3,7 @@ title: Metadata and Metrics Collection description: Learn how F5 NGINX Amplify Agent collects data. weight: 200 toc: true -docs: DOCS-964 +nd-docs: DOCS-964 --- F5 NGINX Amplify Agent collects the following types of data: diff --git a/content/amplify/nginx-amplify-agent/source-code.md b/content/amplify/nginx-amplify-agent/source-code.md index 4730d4d2c..6aa36975e 100644 --- a/content/amplify/nginx-amplify-agent/source-code.md +++ b/content/amplify/nginx-amplify-agent/source-code.md @@ -3,7 +3,7 @@ title: NGINX Amplify Agent Source Code description: Learn where to find F5 NGINX Amplify Agent's source code. weight: 700 toc: true -docs: DOCS-965 +nd-docs: DOCS-965 --- F5 NGINX Amplify Agent is an open source application. It is licensed under the [2-clause BSD license](https://github.com/nginxinc/nginx-amplify-agent/blob/master/LICENSE), and is available here: diff --git a/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md b/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md index 5501b2fbe..d15fbe0f9 100644 --- a/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md +++ b/content/amplify/nginx-amplify-agent/troubleshooting-metrics-collection.md @@ -3,7 +3,7 @@ title: Troubleshooting Metrics Collection description: Learn what to check if F5 NGINX Amplify Agent isn't reporting metrics. weight: 500 toc: true -docs: DOCS-966 +nd-docs: DOCS-966 --- After you [install and start]({{< ref "/amplify/nginx-amplify-agent/install/installing-amplify-agent" >}}) F5 NGINX Amplify Agent, it should start reporting right away, pushing aggregated data to the Amplify backend at regular 1 minute intervals. It'll take about a minute for a new system to appear in the Amplify web interface. diff --git a/content/amplify/overview/overview-main-components.md b/content/amplify/overview/overview-main-components.md index 3ae2416ee..ecb453b6e 100644 --- a/content/amplify/overview/overview-main-components.md +++ b/content/amplify/overview/overview-main-components.md @@ -3,7 +3,7 @@ title: Overview and Main Components description: Learn about F5 NGINX Amplify and its main components. weight: 10 toc: true -docs: DOCS-976 +nd-docs: DOCS-976 --- ## What Is F5 NGINX Amplify? diff --git a/content/amplify/user-interface/account-settings.md b/content/amplify/user-interface/account-settings.md index bef423f0b..d39312e95 100644 --- a/content/amplify/user-interface/account-settings.md +++ b/content/amplify/user-interface/account-settings.md @@ -3,7 +3,7 @@ title: Account Settings description: Learn about the Account settings for the User Interface. weight: 70 toc: true -docs: DOCS-978 +nd-docs: DOCS-978 --- The **Account** option in the user menu at the top right corner of the user interface povides access to several user settings. diff --git a/content/amplify/user-interface/alerts.md b/content/amplify/user-interface/alerts.md index f89818d48..490cc6eb7 100644 --- a/content/amplify/user-interface/alerts.md +++ b/content/amplify/user-interface/alerts.md @@ -3,7 +3,7 @@ title: Alerts description: Learn about the Alerts page of the User Interface. weight: 60 toc: false -docs: DOCS-979 +nd-docs: DOCS-979 --- The **Alerts** page describes the configuration of the alert rules used to notify you of any anomalies in the behavior of your systems. diff --git a/content/amplify/user-interface/analyzer.md b/content/amplify/user-interface/analyzer.md index 054790cdd..40ce6d0b5 100644 --- a/content/amplify/user-interface/analyzer.md +++ b/content/amplify/user-interface/analyzer.md @@ -3,7 +3,7 @@ title: Analyzer description: Learn about the Analyzer page of the User Interface. weight: 50 toc: false -docs: DOCS-980 +nd-docs: DOCS-980 --- F5 NGINX Amplify Agent parses NGINX configuration files and transmits them to the backend component for further analysis. NGINX Amplify offers configuration recommendations to help improve the performance, reliability, and security of your applications. With well-thought-out and detailed recommendations, you’ll know exactly where the problem is, why it is a problem, and how to fix it. diff --git a/content/amplify/user-interface/dashboards.md b/content/amplify/user-interface/dashboards.md index eef3fcd73..24dd0814d 100644 --- a/content/amplify/user-interface/dashboards.md +++ b/content/amplify/user-interface/dashboards.md @@ -3,7 +3,7 @@ title: Dashboards description: Learn about the Dashboards page of the User Interface. weight: 40 toc: false -docs: DOCS-981 +nd-docs: DOCS-981 --- You can create your own dashboards populated with highly customizable graphs of NGINX and system-level metrics. diff --git a/content/amplify/user-interface/graphs.md b/content/amplify/user-interface/graphs.md index 701138cb7..d33421876 100644 --- a/content/amplify/user-interface/graphs.md +++ b/content/amplify/user-interface/graphs.md @@ -3,7 +3,7 @@ title: Graphs description: Learn about the Graphs page of the User Interface. weight: 20 toc: false -docs: DOCS-982 +nd-docs: DOCS-982 --- On the **Graphs** page, you can find a collection of predefined graphs. Here you can see an overview of the key metric stats, such as CPU, memory, and disk usage for all your systems. diff --git a/content/amplify/user-interface/inventory.md b/content/amplify/user-interface/inventory.md index f57cc399a..dc7e4d198 100644 --- a/content/amplify/user-interface/inventory.md +++ b/content/amplify/user-interface/inventory.md @@ -3,7 +3,7 @@ title: Inventory description: Learn about the Inventory page of the User Interface. weight: 30 toc: false -docs: DOCS-983 +nd-docs: DOCS-983 --- You can access the inventory by selecting the first icon on the top menu. The inventory gives an overview of the systems that are being monitored. When F5 NGINX Amplify Agent is running and reporting on a new system, it's listed in the system index on the left side of the user interface and in the **Inventory** section. diff --git a/content/amplify/user-interface/overview.md b/content/amplify/user-interface/overview.md index 5fbb45d7e..02437219d 100644 --- a/content/amplify/user-interface/overview.md +++ b/content/amplify/user-interface/overview.md @@ -3,7 +3,7 @@ title: Overview description: Learn about the Overview page of the User Interface. weight: 10 toc: true -docs: DOCS-984 +nd-docs: DOCS-984 --- The Overview page is designed to provide a quick summary of the state of your NGINX infrastructure. Here you can quickly check the total sum of HTTP 5xx errors over the past 24 hours and compare it to the previous 24 hours. diff --git a/content/controller/_index.md b/content/controller/_index.md index e14138efd..de4760e6f 100644 --- a/content/controller/_index.md +++ b/content/controller/_index.md @@ -6,7 +6,7 @@ weight: 2100 cascade: logo: "NGINX-Controller-product-icon-RGB.svg" noindex: true - banner: + nd-banner: enabled: true type: deprecation md: _banners/eos-cltr.md diff --git a/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md b/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md index 93dfdad4b..146217e3b 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-cluster-config.md @@ -1,7 +1,7 @@ --- description: Learn how to back up your F5 NGINX Controller cluster configuration and encryption keys. -docs: DOCS-247 +nd-docs: DOCS-247 title: Back Up & Restore Cluster Config and Encryption Keys toc: true weight: 97 diff --git a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md index f4cdadd2f..a1d53cf56 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-embedded-config-db.md @@ -1,7 +1,7 @@ --- description: Learn how to back up and restore the embedded F5 NGINX Controller config database. -docs: DOCS-248 +nd-docs: DOCS-248 title: Back Up & Restore an Embedded Config Database toc: true weight: 98 diff --git a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md b/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md index 983ec1321..bc2adbeeb 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-external-config-db.md @@ -1,7 +1,7 @@ --- description: Learn how to back up and restore the external F5 NGINX Controller config database. -docs: DOCS-249 +nd-docs: DOCS-249 title: Back Up & Restore an External Config Database toc: true weight: 99 diff --git a/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md b/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md index bce77e9f2..bd372ded2 100644 --- a/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md +++ b/content/controller/admin-guides/backup-restore/backup-restore-metrics-db.md @@ -1,6 +1,6 @@ --- description: Learn how to back up and restore the F5 NGINX Controller analytics database. -docs: DOCS-250 +nd-docs: DOCS-250 title: Back Up & Restore the Analytics Database toc: true weight: 100 diff --git a/content/controller/admin-guides/config-agent/about-controller-agent.md b/content/controller/admin-guides/config-agent/about-controller-agent.md index 3976422ab..2ab44950d 100644 --- a/content/controller/admin-guides/config-agent/about-controller-agent.md +++ b/content/controller/admin-guides/config-agent/about-controller-agent.md @@ -1,6 +1,6 @@ --- description: Learn about the NGINX Controller Agent. -docs: DOCS-508 +nd-docs: DOCS-508 title: Get to Know the F5 NGINX Controller Agent toc: true weight: 100 diff --git a/content/controller/admin-guides/config-agent/configure-metrics-collection.md b/content/controller/admin-guides/config-agent/configure-metrics-collection.md index 492cbd5e1..6fadc382c 100644 --- a/content/controller/admin-guides/config-agent/configure-metrics-collection.md +++ b/content/controller/admin-guides/config-agent/configure-metrics-collection.md @@ -1,7 +1,7 @@ --- description: Contains instructions for setting up the F5 NGINX Controller Agent to collect metrics for NGINX Plus instances. -docs: DOCS-509 +nd-docs: DOCS-509 title: Set up Metrics Collection toc: true weight: 120 diff --git a/content/controller/admin-guides/config-agent/configure-the-agent.md b/content/controller/admin-guides/config-agent/configure-the-agent.md index 37a7d5c7b..468755759 100644 --- a/content/controller/admin-guides/config-agent/configure-the-agent.md +++ b/content/controller/admin-guides/config-agent/configure-the-agent.md @@ -1,6 +1,6 @@ --- description: Customize the F5 NGINX Controller Agent configuration. -docs: DOCS-510 +nd-docs: DOCS-510 title: Configure the NGINX Controller Agent toc: true weight: 110 diff --git a/content/controller/admin-guides/config-agent/use-agent-with-docker.md b/content/controller/admin-guides/config-agent/use-agent-with-docker.md index 3c5980a2b..12a1786b8 100644 --- a/content/controller/admin-guides/config-agent/use-agent-with-docker.md +++ b/content/controller/admin-guides/config-agent/use-agent-with-docker.md @@ -1,6 +1,6 @@ --- description: Learn how to use the F5 NGINX Controller Agent in a Docker environment. -docs: DOCS-511 +nd-docs: DOCS-511 title: Use the NGINX Controller Agent with Docker toc: true weight: 200 diff --git a/content/controller/admin-guides/install/agent-restart.md b/content/controller/admin-guides/install/agent-restart.md index 103b35573..acc3e9173 100644 --- a/content/controller/admin-guides/install/agent-restart.md +++ b/content/controller/admin-guides/install/agent-restart.md @@ -1,7 +1,7 @@ --- description: How to start, stop, and verify the state of the F5 NGINX Controller Agent service. -docs: DOCS-251 +nd-docs: DOCS-251 title: Manage the NGINX Controller Agent Service toc: true weight: 210 diff --git a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md b/content/controller/admin-guides/install/get-n-plus-cert-and-key.md index 48a9ecef5..55a141570 100644 --- a/content/controller/admin-guides/install/get-n-plus-cert-and-key.md +++ b/content/controller/admin-guides/install/get-n-plus-cert-and-key.md @@ -1,7 +1,7 @@ --- description: How to download the F5 NGINX Plus nginx.crt and nginx.key files using the NGINX Controller API. -docs: DOCS-252 +nd-docs: DOCS-252 title: Download the NGINX Plus Cert and Key Bundle toc: true weight: 105 diff --git a/content/controller/admin-guides/install/install-agent-non-root.md b/content/controller/admin-guides/install/install-agent-non-root.md index 51934094a..7d4dd31bf 100644 --- a/content/controller/admin-guides/install/install-agent-non-root.md +++ b/content/controller/admin-guides/install/install-agent-non-root.md @@ -1,6 +1,6 @@ --- description: How to install the F5 NGINX Controller Agent to run as a non-root user. -docs: DOCS-253 +nd-docs: DOCS-253 title: Install NGINX Controller Agent for Non-root Users toc: true weight: 205 diff --git a/content/controller/admin-guides/install/install-for-controller.md b/content/controller/admin-guides/install/install-for-controller.md index b359e637d..bd104db9f 100644 --- a/content/controller/admin-guides/install/install-for-controller.md +++ b/content/controller/admin-guides/install/install-for-controller.md @@ -1,7 +1,7 @@ --- description: Take the steps in this guide to deploy F5 NGINX App Protect WAF as a datapath instance for use with NGINX Controller. -docs: DOCS-645 +nd-docs: DOCS-645 title: Using NGINX App Protect WAF with NGINX Controller toc: true weight: 500 diff --git a/content/controller/admin-guides/install/install-nginx-controller-agent.md b/content/controller/admin-guides/install/install-nginx-controller-agent.md index 594f865c1..2ee592106 100644 --- a/content/controller/admin-guides/install/install-nginx-controller-agent.md +++ b/content/controller/admin-guides/install/install-nginx-controller-agent.md @@ -1,6 +1,6 @@ --- description: How to install, upgrade, and uninstall the F5 Controller Agent. -docs: DOCS-254 +nd-docs: DOCS-254 title: Install NGINX Controller Agent toc: true weight: 150 diff --git a/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md b/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md index 82d4e9651..34431a5a2 100644 --- a/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md +++ b/content/controller/admin-guides/install/install-nginx-controller-rhel-8.md @@ -1,7 +1,7 @@ --- description: This guide explains how to prepare your RHEL 8 system to install F5 NGINX Controller and the NGINX Controller Agent. -docs: DOCS-342 +nd-docs: DOCS-342 title: Install NGINX Controller on RHEL 8 (experimental) toc: true weight: 200 diff --git a/content/controller/admin-guides/install/install-nginx-controller.md b/content/controller/admin-guides/install/install-nginx-controller.md index d6d6eb972..0607d2240 100644 --- a/content/controller/admin-guides/install/install-nginx-controller.md +++ b/content/controller/admin-guides/install/install-nginx-controller.md @@ -1,6 +1,6 @@ --- description: This guide explains how to install and update F5 NGINX Controller. -docs: DOCS-255 +nd-docs: DOCS-255 title: Install NGINX Controller toc: true weight: 120 diff --git a/content/controller/admin-guides/install/nginx-controller-tech-specs.md b/content/controller/admin-guides/install/nginx-controller-tech-specs.md index 1940cf75d..39b8a7da6 100644 --- a/content/controller/admin-guides/install/nginx-controller-tech-specs.md +++ b/content/controller/admin-guides/install/nginx-controller-tech-specs.md @@ -1,6 +1,6 @@ --- description: Guidelines and recommendations for configuring F5 NGINX Controller. -docs: DOCS-256 +nd-docs: DOCS-256 title: NGINX Controller Tech Specs toc: true weight: 100 diff --git a/content/controller/admin-guides/install/resilient-cluster-aws.md b/content/controller/admin-guides/install/resilient-cluster-aws.md index f544492e6..240c0edc5 100644 --- a/content/controller/admin-guides/install/resilient-cluster-aws.md +++ b/content/controller/admin-guides/install/resilient-cluster-aws.md @@ -1,7 +1,7 @@ --- description: This guide explains how to deploy F5 NGINX Controller as a multi-node resilient cluster on AWS. -docs: DOCS-257 +nd-docs: DOCS-257 title: Deploy NGINX Controller as a Resilient Cluster on AWS toc: true weight: 310 diff --git a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md b/content/controller/admin-guides/install/resilient-cluster-private-cloud.md index 22cc5e1db..cb2339eb0 100644 --- a/content/controller/admin-guides/install/resilient-cluster-private-cloud.md +++ b/content/controller/admin-guides/install/resilient-cluster-private-cloud.md @@ -1,7 +1,7 @@ --- description: This guide explains how to deploy F5 NGINX Controller as a multi-node resilient cluster on a private cloud. -docs: DOCS-258 +nd-docs: DOCS-258 title: Deploy NGINX Controller as a Resilient Cluster on a Private Cloud toc: true weight: 300 diff --git a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md b/content/controller/admin-guides/install/try-nginx-controller-app-sec.md index 74b41240b..ecba8d0f9 100644 --- a/content/controller/admin-guides/install/try-nginx-controller-app-sec.md +++ b/content/controller/admin-guides/install/try-nginx-controller-app-sec.md @@ -1,7 +1,7 @@ --- description: This quick-start tutorial shows you how to get started using F5 NGINX Controller with the Application Security Add-on. -docs: DOCS-259 +nd-docs: DOCS-259 title: Trial NGINX Controller with App Security toc: true weight: 115 diff --git a/content/controller/admin-guides/install/try-nginx-controller.md b/content/controller/admin-guides/install/try-nginx-controller.md index c5565c412..dd2883d56 100644 --- a/content/controller/admin-guides/install/try-nginx-controller.md +++ b/content/controller/admin-guides/install/try-nginx-controller.md @@ -1,7 +1,7 @@ --- description: This quick-start tutorial shows you how to get started using F5 NGINX Controller with NGINX Plus. -docs: DOCS-260 +nd-docs: DOCS-260 title: Trial NGINX Controller with NGINX Plus toc: true weight: 110 diff --git a/content/controller/admin-guides/install/using-helper-script.md b/content/controller/admin-guides/install/using-helper-script.md index 2a880d7ce..382332f63 100644 --- a/content/controller/admin-guides/install/using-helper-script.md +++ b/content/controller/admin-guides/install/using-helper-script.md @@ -1,7 +1,7 @@ --- description: Learn how to update F5 NGINX Controller installation settings and manage the NGINX Controller service using the helper.sh script. -docs: DOCS-261 +nd-docs: DOCS-261 title: Update NGINX Controller Settings with helper.sh toc: true weight: 200 diff --git a/content/controller/analytics/alerts/about-alerts.md b/content/controller/analytics/alerts/about-alerts.md index c870c9a75..af1813eba 100644 --- a/content/controller/analytics/alerts/about-alerts.md +++ b/content/controller/analytics/alerts/about-alerts.md @@ -1,6 +1,6 @@ --- description: Learn about NGINX Controller Alerts and Notifications. -docs: DOCS-520 +nd-docs: DOCS-520 title: About Alerts toc: true weight: 100 diff --git a/content/controller/analytics/alerts/manage-alerts.md b/content/controller/analytics/alerts/manage-alerts.md index de167234f..839506968 100644 --- a/content/controller/analytics/alerts/manage-alerts.md +++ b/content/controller/analytics/alerts/manage-alerts.md @@ -1,6 +1,6 @@ --- description: Learn how to view, add, mute, and delete Alerts. -docs: DOCS-521 +nd-docs: DOCS-521 title: Manage Alerts toc: true weight: 200 diff --git a/content/controller/analytics/alerts/manage-registered-emails.md b/content/controller/analytics/alerts/manage-registered-emails.md index 81131b9da..6a0bb6bbf 100644 --- a/content/controller/analytics/alerts/manage-registered-emails.md +++ b/content/controller/analytics/alerts/manage-registered-emails.md @@ -1,7 +1,7 @@ --- description: Learn how to manage the email addresses that receive automatic alert notifications. -docs: DOCS-522 +nd-docs: DOCS-522 title: Manage Registered Email Addresses toc: true weight: 310 diff --git a/content/controller/analytics/alerts/service-now-notifications.md b/content/controller/analytics/alerts/service-now-notifications.md index 8e857b14e..fe4ca3c43 100644 --- a/content/controller/analytics/alerts/service-now-notifications.md +++ b/content/controller/analytics/alerts/service-now-notifications.md @@ -1,6 +1,6 @@ --- description: Set up Alerts Integration with ServiceNow. Deprecated in v3.13. -docs: DOCS-523 +nd-docs: DOCS-523 title: ServiceNow Alerts Integration toc: true weight: 600 diff --git a/content/controller/analytics/catalogs/dimensions.md b/content/controller/analytics/catalogs/dimensions.md index db1629c2d..4ed5ea5b4 100644 --- a/content/controller/analytics/catalogs/dimensions.md +++ b/content/controller/analytics/catalogs/dimensions.md @@ -1,7 +1,7 @@ --- description: Information about all of the Dimensions collected by F5 NGINX Controller Agent. -docs: DOCS-524 +nd-docs: DOCS-524 title: NGINX Controller Dimensions Catalog toc: false weight: 20 diff --git a/content/controller/analytics/catalogs/metrics.md b/content/controller/analytics/catalogs/metrics.md index 3e457a0a9..ff4c9b25b 100644 --- a/content/controller/analytics/catalogs/metrics.md +++ b/content/controller/analytics/catalogs/metrics.md @@ -1,7 +1,7 @@ --- description: Information about all of the Metrics collected by F5 NGINX Controller Agent. -docs: DOCS-525 +nd-docs: DOCS-525 title: NGINX Controller Metrics Catalog toc: false weight: 20 diff --git a/content/controller/analytics/dashboards/application-health-score.md b/content/controller/analytics/dashboards/application-health-score.md index 5ec0bd4f0..1a4940ffd 100644 --- a/content/controller/analytics/dashboards/application-health-score.md +++ b/content/controller/analytics/dashboards/application-health-score.md @@ -1,6 +1,6 @@ --- description: View and understand the Application Health Score for your application. -docs: DOCS-526 +nd-docs: DOCS-526 title: Understanding the Application Health Score toc: true weight: 20 diff --git a/content/controller/analytics/dashboards/custom-dashboards.md b/content/controller/analytics/dashboards/custom-dashboards.md index 8a4913194..a7593369d 100644 --- a/content/controller/analytics/dashboards/custom-dashboards.md +++ b/content/controller/analytics/dashboards/custom-dashboards.md @@ -1,6 +1,6 @@ --- description: Create custom dashboards to view custom graphs. -docs: DOCS-527 +nd-docs: DOCS-527 title: Create Custom Dashboards toc: true weight: 20 diff --git a/content/controller/analytics/dashboards/overview-dashboard.md b/content/controller/analytics/dashboards/overview-dashboard.md index c16a87cc3..e3c9c2073 100644 --- a/content/controller/analytics/dashboards/overview-dashboard.md +++ b/content/controller/analytics/dashboards/overview-dashboard.md @@ -1,7 +1,7 @@ --- description: Learn about the Dashboards that displays cumulative metrics for your NGINX Instances. -docs: DOCS-528 +nd-docs: DOCS-528 title: Analytics Overview toc: true weight: 10 diff --git a/content/controller/analytics/data-explorer/how-to-use.md b/content/controller/analytics/data-explorer/how-to-use.md index 2d9129225..2efebdc8a 100644 --- a/content/controller/analytics/data-explorer/how-to-use.md +++ b/content/controller/analytics/data-explorer/how-to-use.md @@ -1,7 +1,7 @@ --- description: Use the Data Explorer to examine the metrics that F5 NGINX Controller collects. -docs: DOCS-529 +nd-docs: DOCS-529 title: How To Use the Data Explorer toc: true weight: 20 diff --git a/content/controller/analytics/events/view-events.md b/content/controller/analytics/events/view-events.md index 39babcac8..a2baabfbe 100644 --- a/content/controller/analytics/events/view-events.md +++ b/content/controller/analytics/events/view-events.md @@ -1,6 +1,6 @@ --- description: View the audit log of system and user actions. -docs: DOCS-530 +nd-docs: DOCS-530 title: View Events toc: true weight: 20 diff --git a/content/controller/analytics/forwarders/forward-analytics-to-datadog.md b/content/controller/analytics/forwarders/forward-analytics-to-datadog.md index 93527425e..852b44b7b 100644 --- a/content/controller/analytics/forwarders/forward-analytics-to-datadog.md +++ b/content/controller/analytics/forwarders/forward-analytics-to-datadog.md @@ -1,6 +1,6 @@ --- description: How to forward Analytics data to Datadog. -docs: DOCS-531 +nd-docs: DOCS-531 title: Forward Analytics Data to Datadog toc: true weight: 100 diff --git a/content/controller/analytics/forwarders/forward-analytics-to-otlp.md b/content/controller/analytics/forwarders/forward-analytics-to-otlp.md index ea705f2d9..838073a53 100644 --- a/content/controller/analytics/forwarders/forward-analytics-to-otlp.md +++ b/content/controller/analytics/forwarders/forward-analytics-to-otlp.md @@ -1,6 +1,6 @@ --- description: How to forward Analytics Metrics to OpenTelemetry Collector. -docs: DOCS-532 +nd-docs: DOCS-532 title: Forward Analytics Metrics to OpenTelemetry Collector toc: true weight: 201 diff --git a/content/controller/analytics/forwarders/forward-analytics-to-splunk.md b/content/controller/analytics/forwarders/forward-analytics-to-splunk.md index 81d2cfcd2..5c48c0e73 100644 --- a/content/controller/analytics/forwarders/forward-analytics-to-splunk.md +++ b/content/controller/analytics/forwarders/forward-analytics-to-splunk.md @@ -1,6 +1,6 @@ --- description: How to forward Analytics data to Splunk. -docs: DOCS-533 +nd-docs: DOCS-533 title: Forward Analytics Data to Splunk toc: true weight: 200 diff --git a/content/controller/analytics/forwarders/forward-analytics-to-syslog.md b/content/controller/analytics/forwarders/forward-analytics-to-syslog.md index 669046a4d..f135c3322 100644 --- a/content/controller/analytics/forwarders/forward-analytics-to-syslog.md +++ b/content/controller/analytics/forwarders/forward-analytics-to-syslog.md @@ -1,6 +1,6 @@ --- description: How to forward Analytics Events to Syslog. -docs: DOCS-534 +nd-docs: DOCS-534 title: Forward Analytics Events to Syslog toc: true weight: 201 diff --git a/content/controller/analytics/metrics/metrics-api.md b/content/controller/analytics/metrics/metrics-api.md index 29f5cef7b..867c62308 100644 --- a/content/controller/analytics/metrics/metrics-api.md +++ b/content/controller/analytics/metrics/metrics-api.md @@ -1,7 +1,7 @@ --- description: Tips and tricks for using the Metrics API query parameters to refine your data. -docs: DOCS-535 +nd-docs: DOCS-535 title: Using the Metrics API toc: true weight: 50 diff --git a/content/controller/analytics/metrics/overview-metrics-metadata.md b/content/controller/analytics/metrics/overview-metrics-metadata.md index cec6969a1..72e0382a6 100644 --- a/content/controller/analytics/metrics/overview-metrics-metadata.md +++ b/content/controller/analytics/metrics/overview-metrics-metadata.md @@ -1,7 +1,7 @@ --- description: Understanding how the F5 NGINX Controller Agent collects and reports metrics and metadata. -docs: DOCS-536 +nd-docs: DOCS-536 title: 'Overview: Metrics and Metadata' toc: true weight: 20 diff --git a/content/controller/analytics/metrics/overview-traffic-metrics.md b/content/controller/analytics/metrics/overview-traffic-metrics.md index b1d871a6d..7df193b20 100644 --- a/content/controller/analytics/metrics/overview-traffic-metrics.md +++ b/content/controller/analytics/metrics/overview-traffic-metrics.md @@ -1,6 +1,6 @@ --- description: Understanding how traffic metrics are collected, aggregated, and reported. -docs: DOCS-537 +nd-docs: DOCS-537 title: 'Overview: Traffic Metrics' toc: true weight: 100 diff --git a/content/controller/analytics/metrics/view-traffic-metrics.md b/content/controller/analytics/metrics/view-traffic-metrics.md index b63268ff9..055658de3 100644 --- a/content/controller/analytics/metrics/view-traffic-metrics.md +++ b/content/controller/analytics/metrics/view-traffic-metrics.md @@ -1,6 +1,6 @@ --- description: How to view the traffic metrics gathered by NGINX Controller Analytics. -docs: DOCS-538 +nd-docs: DOCS-538 title: View Traffic Metrics toc: true weight: 150 diff --git a/content/controller/analytics/view-app-security-analytics.md b/content/controller/analytics/view-app-security-analytics.md index c26533250..2d9407d5b 100644 --- a/content/controller/analytics/view-app-security-analytics.md +++ b/content/controller/analytics/view-app-security-analytics.md @@ -1,6 +1,6 @@ --- description: How to view App Security Analytics. -docs: DOCS-539 +nd-docs: DOCS-539 title: View App Security Analytics toc: true weight: 500 diff --git a/content/controller/api-management/manage-apis.md b/content/controller/api-management/manage-apis.md index a16e213ac..1ee149fb0 100644 --- a/content/controller/api-management/manage-apis.md +++ b/content/controller/api-management/manage-apis.md @@ -1,7 +1,7 @@ --- description: Use the F5 NGINX Controller API Manager to add APIs and control how your APIs are exposed and consumed. -docs: DOCS-569 +nd-docs: DOCS-569 title: Manage Your APIs toc: true weight: 110 diff --git a/content/controller/api-management/manage-dev-portals.md b/content/controller/api-management/manage-dev-portals.md index 3caa8b685..6bf5fdc68 100644 --- a/content/controller/api-management/manage-dev-portals.md +++ b/content/controller/api-management/manage-dev-portals.md @@ -1,6 +1,6 @@ --- description: Learn how to create and manage Developer Portals for your API documentation. -docs: DOCS-570 +nd-docs: DOCS-570 title: Manage Developer Portals toc: true weight: 120 diff --git a/content/controller/api/overview.md b/content/controller/api/overview.md index c5812a63e..1610f6021 100644 --- a/content/controller/api/overview.md +++ b/content/controller/api/overview.md @@ -1,6 +1,6 @@ --- description: Provides information about the F5 NGINX Controller API. -docs: DOCS-343 +nd-docs: DOCS-343 layout: docs title: API Overview toc: true diff --git a/content/controller/api/reference/ctlr-adc-api.md b/content/controller/api/reference/ctlr-adc-api.md index 4683b5e48..e1226fa0f 100644 --- a/content/controller/api/reference/ctlr-adc-api.md +++ b/content/controller/api/reference/ctlr-adc-api.md @@ -1,7 +1,7 @@ --- description: Represents the state of the F5 NGINX Controller Application Delivery REST API. -docs: DOCS-1280 +nd-docs: DOCS-1280 type: - reference doctypes: diff --git a/content/controller/api/reference/ctlr-analytics-api.md b/content/controller/api/reference/ctlr-analytics-api.md index b01f0fdbf..b1d69e9bb 100644 --- a/content/controller/api/reference/ctlr-analytics-api.md +++ b/content/controller/api/reference/ctlr-analytics-api.md @@ -1,6 +1,6 @@ --- description: Represents the state of the F5 NGINX Controller Analytics REST API. -docs: DOCS-1279 +nd-docs: DOCS-1279 type: - reference doctypes: diff --git a/content/controller/api/reference/ctlr-apim-api.md b/content/controller/api/reference/ctlr-apim-api.md index b4dfa40ce..0b673cb8d 100644 --- a/content/controller/api/reference/ctlr-apim-api.md +++ b/content/controller/api/reference/ctlr-apim-api.md @@ -1,6 +1,6 @@ --- description: Represents the state of the F5 NGINX Controller API Management REST API. -docs: DOCS-1281 +nd-docs: DOCS-1281 type: - reference doctypes: diff --git a/content/controller/api/reference/ctlr-platform-api.md b/content/controller/api/reference/ctlr-platform-api.md index c999e18d1..d64ad61f5 100644 --- a/content/controller/api/reference/ctlr-platform-api.md +++ b/content/controller/api/reference/ctlr-platform-api.md @@ -1,6 +1,6 @@ --- description: Represents the state of the F5 NGINX Controller Platform REST API. -docs: DOCS-1278 +nd-docs: DOCS-1278 doctypes: - reference type: redoc diff --git a/content/controller/app-delivery/about-app-delivery.md b/content/controller/app-delivery/about-app-delivery.md index e63b24722..81e50b6fb 100644 --- a/content/controller/app-delivery/about-app-delivery.md +++ b/content/controller/app-delivery/about-app-delivery.md @@ -1,6 +1,6 @@ --- description: Learn about F5 NGINX Controller Application Delivery concepts. -docs: DOCS-474 +nd-docs: DOCS-474 title: About Application Delivery toc: true weight: 100 diff --git a/content/controller/app-delivery/about-caching.md b/content/controller/app-delivery/about-caching.md index e4b39ef17..3a58056ad 100644 --- a/content/controller/app-delivery/about-caching.md +++ b/content/controller/app-delivery/about-caching.md @@ -1,7 +1,7 @@ --- description: Learn how F5 NGINX Controller handles caching configurations and what NGINX cache directives are supported. -docs: DOCS-339 +nd-docs: DOCS-339 title: About Caching toc: true weight: 200 diff --git a/content/controller/app-delivery/about-snippets.md b/content/controller/app-delivery/about-snippets.md index 8afb6b974..21eb1e83b 100644 --- a/content/controller/app-delivery/about-snippets.md +++ b/content/controller/app-delivery/about-snippets.md @@ -1,5 +1,5 @@ --- -docs: DOCS-340 +nd-docs: DOCS-340 title: About Snippets toc: true weight: 300 diff --git a/content/controller/app-delivery/deploy-simple-app.md b/content/controller/app-delivery/deploy-simple-app.md index 999742480..37e36fe58 100644 --- a/content/controller/app-delivery/deploy-simple-app.md +++ b/content/controller/app-delivery/deploy-simple-app.md @@ -1,6 +1,6 @@ --- description: Overview of the steps required to deploy a simple App. -docs: DOCS-477 +nd-docs: DOCS-477 title: Deploy a Simple Application toc: true weight: 400 diff --git a/content/controller/app-delivery/manage-apps.md b/content/controller/app-delivery/manage-apps.md index da56c055d..1462c8f25 100644 --- a/content/controller/app-delivery/manage-apps.md +++ b/content/controller/app-delivery/manage-apps.md @@ -1,6 +1,6 @@ --- description: Create, view, and edit Apps and Components. -docs: DOCS-478 +nd-docs: DOCS-478 title: Manage Apps & Components toc: true weight: 300 diff --git a/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md b/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md index 12105faae..f701a423d 100644 --- a/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md +++ b/content/controller/app-delivery/security/concepts/app-sec-default-policy-original.md @@ -1,7 +1,7 @@ --- description: Learn about the default protections provided by F5 NGINX Controller App Security. -docs: DOCS-479 +nd-docs: DOCS-479 title: Default WAF Policy toc: true weight: 200 diff --git a/content/controller/app-delivery/security/concepts/app-sec-metrics.md b/content/controller/app-delivery/security/concepts/app-sec-metrics.md index 99ce76f41..fe7798b33 100644 --- a/content/controller/app-delivery/security/concepts/app-sec-metrics.md +++ b/content/controller/app-delivery/security/concepts/app-sec-metrics.md @@ -1,7 +1,7 @@ --- description: Learn about the F5 NGINX Controller Application Security metrics and events. -docs: DOCS-480 +nd-docs: DOCS-480 title: App Security Metrics toc: true weight: 400 diff --git a/content/controller/app-delivery/security/concepts/bring-your-own-policy.md b/content/controller/app-delivery/security/concepts/bring-your-own-policy.md index 2441867ff..f14497b08 100644 --- a/content/controller/app-delivery/security/concepts/bring-your-own-policy.md +++ b/content/controller/app-delivery/security/concepts/bring-your-own-policy.md @@ -1,7 +1,7 @@ --- description: Learn how to use your own F5 NGINX App Protect WAF policies with NGINX Controller. -docs: DOCS-481 +nd-docs: DOCS-481 title: Bring Your Own WAF Policy toc: true weight: 300 diff --git a/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md b/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md index 761e2f779..9933ec89a 100644 --- a/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md +++ b/content/controller/app-delivery/security/concepts/extend-app-security-snippets.md @@ -1,7 +1,7 @@ --- description: Learn how to extend your App Security configurations using F5 NGINX Controller Snippets. -docs: DOCS-338 +nd-docs: DOCS-338 title: Extend App Security with Snippets toc: true weight: 400 diff --git a/content/controller/app-delivery/security/concepts/what-is-waf.md b/content/controller/app-delivery/security/concepts/what-is-waf.md index 51e8214ae..3aede1a1a 100644 --- a/content/controller/app-delivery/security/concepts/what-is-waf.md +++ b/content/controller/app-delivery/security/concepts/what-is-waf.md @@ -1,6 +1,6 @@ --- description: Overview of the App Security module's WAF feature. -docs: DOCS-483 +nd-docs: DOCS-483 title: About App Security toc: true weight: 100 diff --git a/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md b/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md index e2b31f6e4..29fbc7280 100644 --- a/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md +++ b/content/controller/app-delivery/security/tutorials/add-app-security-with-waf.md @@ -1,6 +1,6 @@ --- description: How to add F5 NGINX Controller App Security to your applications. -docs: DOCS-484 +nd-docs: DOCS-484 title: Manage App Security toc: true weight: 100 diff --git a/content/controller/app-delivery/security/tutorials/set-waf-monitor-mode.md b/content/controller/app-delivery/security/tutorials/set-waf-monitor-mode.md index aa4788632..616aa7070 100644 --- a/content/controller/app-delivery/security/tutorials/set-waf-monitor-mode.md +++ b/content/controller/app-delivery/security/tutorials/set-waf-monitor-mode.md @@ -1,7 +1,7 @@ --- description: How to use F5 NGINX Controller App Security to monitor or block security violations. -docs: DOCS-485 +nd-docs: DOCS-485 title: Set Up App Security Monitor Mode toc: true weight: 200 diff --git a/content/controller/app-delivery/security/tutorials/tune-waf-for-app.md b/content/controller/app-delivery/security/tutorials/tune-waf-for-app.md index 87de7192e..0a28a751e 100644 --- a/content/controller/app-delivery/security/tutorials/tune-waf-for-app.md +++ b/content/controller/app-delivery/security/tutorials/tune-waf-for-app.md @@ -1,6 +1,6 @@ --- description: How to tune WAF for your App. -docs: DOCS-486 +nd-docs: DOCS-486 title: Manage WAF Tuning for App Components toc: true weight: 300 diff --git a/content/controller/app-delivery/security/tutorials/using-rbac-with-app-security.md b/content/controller/app-delivery/security/tutorials/using-rbac-with-app-security.md index dc043934d..6249fe5b9 100644 --- a/content/controller/app-delivery/security/tutorials/using-rbac-with-app-security.md +++ b/content/controller/app-delivery/security/tutorials/using-rbac-with-app-security.md @@ -1,6 +1,6 @@ --- description: How to use Role Based Access Control with App Security. -docs: DOCS-845 +nd-docs: DOCS-845 title: Using RBAC with the App Security Add-On toc: true weight: 400 diff --git a/content/controller/app-delivery/security/tutorials/view-app-security-analytics.md b/content/controller/app-delivery/security/tutorials/view-app-security-analytics.md index ae20f8d92..2bdafffd0 100644 --- a/content/controller/app-delivery/security/tutorials/view-app-security-analytics.md +++ b/content/controller/app-delivery/security/tutorials/view-app-security-analytics.md @@ -1,6 +1,6 @@ --- description: How to view App Security Analytics. -docs: DOCS-487 +nd-docs: DOCS-487 title: View App Security Analytics toc: true weight: 500 diff --git a/content/controller/infrastructure/instances/add-aws-instance.md b/content/controller/infrastructure/instances/add-aws-instance.md index 1f558cc5a..fc8dacba6 100644 --- a/content/controller/infrastructure/instances/add-aws-instance.md +++ b/content/controller/infrastructure/instances/add-aws-instance.md @@ -1,6 +1,6 @@ --- description: Learn how to deploy an AWS F5 NGINX instance using NGINX Controller. -docs: DOCS-768 +nd-docs: DOCS-768 title: Add an AWS NGINX Instance toc: true weight: 30 diff --git a/content/controller/infrastructure/instances/add-azure-instance.md b/content/controller/infrastructure/instances/add-azure-instance.md index a537cee78..c5b222733 100644 --- a/content/controller/infrastructure/instances/add-azure-instance.md +++ b/content/controller/infrastructure/instances/add-azure-instance.md @@ -1,6 +1,6 @@ --- description: Learn how to deploy an Azure NGINX instance using F5 NGINX Controller. -docs: DOCS-769 +nd-docs: DOCS-769 title: Add an Azure NGINX Instance toc: true weight: 35 diff --git a/content/controller/infrastructure/instances/add-nap-instance.md b/content/controller/infrastructure/instances/add-nap-instance.md index 6a18eb991..9d6c5f63f 100644 --- a/content/controller/infrastructure/instances/add-nap-instance.md +++ b/content/controller/infrastructure/instances/add-nap-instance.md @@ -1,7 +1,7 @@ --- description: Learn how to register an F5 NGINX App Protect instance with NGINX Controller for use with the ADC module. -docs: DOCS-770 +nd-docs: DOCS-770 title: Add an NGINX App Protect Instance toc: true weight: 20 diff --git a/content/controller/infrastructure/instances/add-vsphere-instance.md b/content/controller/infrastructure/instances/add-vsphere-instance.md index 1a2ae31eb..30ec206ed 100644 --- a/content/controller/infrastructure/instances/add-vsphere-instance.md +++ b/content/controller/infrastructure/instances/add-vsphere-instance.md @@ -1,6 +1,6 @@ --- description: Learn how to deploy a vSphere NGINX instance using F5 NGINX Controller. -docs: DOCS-771 +nd-docs: DOCS-771 title: Add a vSphere NGINX Instance toc: true weight: 35 diff --git a/content/controller/infrastructure/instances/analyzer.md b/content/controller/infrastructure/instances/analyzer.md index 2afeaf0e3..b98aecdc4 100644 --- a/content/controller/infrastructure/instances/analyzer.md +++ b/content/controller/infrastructure/instances/analyzer.md @@ -1,6 +1,6 @@ --- description: View graphs and system reports for your Instances. -docs: DOCS-772 +nd-docs: DOCS-772 title: View Performance Reports for Your Instances toc: true weight: 60 diff --git a/content/controller/infrastructure/instances/graphs.md b/content/controller/infrastructure/instances/graphs.md index 96d4e7440..a2d43805c 100644 --- a/content/controller/infrastructure/instances/graphs.md +++ b/content/controller/infrastructure/instances/graphs.md @@ -1,6 +1,6 @@ --- description: View key metrics for all of your monitored systems. -docs: DOCS-773 +nd-docs: DOCS-773 title: View System Metrics Graphs toc: true weight: 70 diff --git a/content/controller/infrastructure/instances/ha-data-plane.md b/content/controller/infrastructure/instances/ha-data-plane.md index 7420a7e59..2d7c1e757 100644 --- a/content/controller/infrastructure/instances/ha-data-plane.md +++ b/content/controller/infrastructure/instances/ha-data-plane.md @@ -1,7 +1,7 @@ --- description: Learn how to configure a high-availability data plane for your apps in on-premises deployments using F5 NGINX Controller, NGINX Plus, and keepalived. -docs: DOCS-774 +nd-docs: DOCS-774 title: Set Up Data Plane High Availability toc: true weight: 40 diff --git a/content/controller/infrastructure/instances/manage-containerized-instances.md b/content/controller/infrastructure/instances/manage-containerized-instances.md index 83329e067..68a4796be 100644 --- a/content/controller/infrastructure/instances/manage-containerized-instances.md +++ b/content/controller/infrastructure/instances/manage-containerized-instances.md @@ -1,7 +1,7 @@ --- description: How to set up Kubernetes-native API Gateways using Instance Groups (requires the API Management module). -docs: DOCS-775 +nd-docs: DOCS-775 title: Manage Containerized Instances toc: true weight: 15 diff --git a/content/controller/infrastructure/instances/manage-instance-templates.md b/content/controller/infrastructure/instances/manage-instance-templates.md index cb55716d2..5af936c72 100644 --- a/content/controller/infrastructure/instances/manage-instance-templates.md +++ b/content/controller/infrastructure/instances/manage-instance-templates.md @@ -1,6 +1,6 @@ --- description: Create and manage templates for your F5 NGINX Plus instances. -docs: DOCS-776 +nd-docs: DOCS-776 title: Manage Your Instance Templates toc: true weight: 50 diff --git a/content/controller/infrastructure/instances/manage-instances.md b/content/controller/infrastructure/instances/manage-instances.md index 402215ce1..9042b12c5 100644 --- a/content/controller/infrastructure/instances/manage-instances.md +++ b/content/controller/infrastructure/instances/manage-instances.md @@ -1,6 +1,6 @@ --- description: Use the Instance Overview page to view and manage your F5 NGINX Instances. -docs: DOCS-777 +nd-docs: DOCS-777 title: Manage Your NGINX Instances toc: true weight: 10 diff --git a/content/controller/infrastructure/locations/manage-locations.md b/content/controller/infrastructure/locations/manage-locations.md index e9bfa813d..d9dbd175c 100644 --- a/content/controller/infrastructure/locations/manage-locations.md +++ b/content/controller/infrastructure/locations/manage-locations.md @@ -1,6 +1,6 @@ --- description: Create and manage Locations for your F5 NGINX Instances. -docs: DOCS-778 +nd-docs: DOCS-778 title: Manage Locations toc: true weight: 10 diff --git a/content/controller/platform/about/get-controller-version.md b/content/controller/platform/about/get-controller-version.md index 32df5daf1..39cd5840c 100644 --- a/content/controller/platform/about/get-controller-version.md +++ b/content/controller/platform/about/get-controller-version.md @@ -1,6 +1,6 @@ --- description: How to look up the version details for F5 NGINX Controller and its components. -docs: DOCS-780 +nd-docs: DOCS-780 title: Look Up Version Information toc: true weight: 130 diff --git a/content/controller/platform/about/what-is-controller.md b/content/controller/platform/about/what-is-controller.md index 8f3089c4b..fa5ee4c8e 100644 --- a/content/controller/platform/about/what-is-controller.md +++ b/content/controller/platform/about/what-is-controller.md @@ -1,6 +1,6 @@ --- description: Overview of F5 NGINX Controller. -docs: DOCS-781 +nd-docs: DOCS-781 title: Get to Know NGINX Controller toc: true weight: 100 diff --git a/content/controller/platform/access-management/manage-active-directory-auth-provider.md b/content/controller/platform/access-management/manage-active-directory-auth-provider.md index b5ef6a79d..8eeedb348 100644 --- a/content/controller/platform/access-management/manage-active-directory-auth-provider.md +++ b/content/controller/platform/access-management/manage-active-directory-auth-provider.md @@ -1,7 +1,7 @@ --- description: Set up Active Directory authentication for F5 NGINX Controller using OIDC with Microsoft Entra or LDAP, LDAPs, and StartTLS with Windows Active Directory. -docs: DOCS-782 +nd-docs: DOCS-782 title: Configure Active Directory Integration toc: true weight: 10 diff --git a/content/controller/platform/access-management/manage-roles.md b/content/controller/platform/access-management/manage-roles.md index bffb8654e..166fb8e77 100644 --- a/content/controller/platform/access-management/manage-roles.md +++ b/content/controller/platform/access-management/manage-roles.md @@ -1,6 +1,6 @@ --- description: Create and manage Roles and Role Groups. -docs: DOCS-783 +nd-docs: DOCS-783 title: Manage Roles and Role Groups toc: true weight: 30 diff --git a/content/controller/platform/access-management/manage-users.md b/content/controller/platform/access-management/manage-users.md index fa3f8b087..4ff0d6fd0 100644 --- a/content/controller/platform/access-management/manage-users.md +++ b/content/controller/platform/access-management/manage-users.md @@ -1,6 +1,6 @@ --- description: Create and manage User resources. -docs: DOCS-784 +nd-docs: DOCS-784 title: Manage Users toc: true weight: 20 diff --git a/content/controller/platform/integrations/aws-integration.md b/content/controller/platform/integrations/aws-integration.md index 9d4a2e0e9..98f44a9eb 100644 --- a/content/controller/platform/integrations/aws-integration.md +++ b/content/controller/platform/integrations/aws-integration.md @@ -1,6 +1,6 @@ --- description: Integrate F5 NGINX Controller with Amazon Web Services. -docs: DOCS-785 +nd-docs: DOCS-785 title: AWS Integration toc: true weight: 20 diff --git a/content/controller/platform/integrations/big-ip-self-service.md b/content/controller/platform/integrations/big-ip-self-service.md index adb9e1d0b..66acd46c5 100644 --- a/content/controller/platform/integrations/big-ip-self-service.md +++ b/content/controller/platform/integrations/big-ip-self-service.md @@ -1,6 +1,6 @@ --- description: Integrate F5 NGINX Controller with a BIG-IP cluster. -docs: DOCS-786 +nd-docs: DOCS-786 title: BIG-IP Integration toc: true weight: 20 diff --git a/content/controller/platform/integrations/datadog-integration.md b/content/controller/platform/integrations/datadog-integration.md index 18f41e82b..47ceb8bc8 100644 --- a/content/controller/platform/integrations/datadog-integration.md +++ b/content/controller/platform/integrations/datadog-integration.md @@ -1,6 +1,6 @@ --- description: Create a Datadog Integration for F5 NGINX Controller. -docs: DOCS-564 +nd-docs: DOCS-564 title: Datadog Integration weight: 30 --- diff --git a/content/controller/platform/integrations/otlp-integration.md b/content/controller/platform/integrations/otlp-integration.md index 95f66b7a0..4f898317e 100644 --- a/content/controller/platform/integrations/otlp-integration.md +++ b/content/controller/platform/integrations/otlp-integration.md @@ -1,6 +1,6 @@ --- description: Create an OpenTelemetry Protocol (OTLP) Integration for F5 NGINX Controller. -docs: DOCS-565 +nd-docs: DOCS-565 title: OTLP Integration weight: 30 --- diff --git a/content/controller/platform/integrations/splunk-integration.md b/content/controller/platform/integrations/splunk-integration.md index 81bcdd06a..5ae9b7b8f 100644 --- a/content/controller/platform/integrations/splunk-integration.md +++ b/content/controller/platform/integrations/splunk-integration.md @@ -1,5 +1,5 @@ --- -docs: DOCS-566 +nd-docs: DOCS-566 title: Splunk Integration weight: 40 --- diff --git a/content/controller/platform/integrations/syslog-integration.md b/content/controller/platform/integrations/syslog-integration.md index 939dff7c2..00f5787ce 100644 --- a/content/controller/platform/integrations/syslog-integration.md +++ b/content/controller/platform/integrations/syslog-integration.md @@ -1,5 +1,5 @@ --- -docs: DOCS-567 +nd-docs: DOCS-567 title: Syslog Integration weight: 30 --- diff --git a/content/controller/platform/licensing-controller.md b/content/controller/platform/licensing-controller.md index d302723bd..a1b5c8602 100644 --- a/content/controller/platform/licensing-controller.md +++ b/content/controller/platform/licensing-controller.md @@ -1,6 +1,6 @@ --- description: Follow these steps to license your F5 NGINX Controller. -docs: DOCS-787 +nd-docs: DOCS-787 title: License NGINX Controller toc: true weight: 120 diff --git a/content/controller/platform/maintenance/changing-ip-address.md b/content/controller/platform/maintenance/changing-ip-address.md index 5377f8752..8d4cf28a2 100644 --- a/content/controller/platform/maintenance/changing-ip-address.md +++ b/content/controller/platform/maintenance/changing-ip-address.md @@ -1,6 +1,6 @@ --- description: Learn how to safely change the management IP of F5 NGINX Controller. -docs: DOCS-779 +nd-docs: DOCS-779 title: Changing the IP address toc: true weight: 135 diff --git a/content/controller/platform/manage-cluster.md b/content/controller/platform/manage-cluster.md index c187e0c3e..b5e2bf6ef 100644 --- a/content/controller/platform/manage-cluster.md +++ b/content/controller/platform/manage-cluster.md @@ -1,7 +1,7 @@ --- description: Learn how to add and manage additional F5 NGINX Controller nodes to create a resilient cluster. -docs: DOCS-788 +nd-docs: DOCS-788 title: Manage Your Cluster toc: true weight: 140 diff --git a/content/controller/releases/adc/adc-release-notes-3.20.1.md b/content/controller/releases/adc/adc-release-notes-3.20.1.md index 3d3d02852..d9ee49128 100644 --- a/content/controller/releases/adc/adc-release-notes-3.20.1.md +++ b/content/controller/releases/adc/adc-release-notes-3.20.1.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-362 +nd-docs: DOCS-362 title: Release Notes 3.20.1 toc: true weight: 99 diff --git a/content/controller/releases/adc/adc-release-notes-3.20.md b/content/controller/releases/adc/adc-release-notes-3.20.md index eeb4b45ac..9c446f0af 100644 --- a/content/controller/releases/adc/adc-release-notes-3.20.md +++ b/content/controller/releases/adc/adc-release-notes-3.20.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-363 +nd-docs: DOCS-363 title: Release Notes 3.20.0 toc: true weight: 100 diff --git a/content/controller/releases/adc/adc-release-notes-3.21.md b/content/controller/releases/adc/adc-release-notes-3.21.md index 1f8fdacc4..6356e2b1b 100644 --- a/content/controller/releases/adc/adc-release-notes-3.21.md +++ b/content/controller/releases/adc/adc-release-notes-3.21.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-364 +nd-docs: DOCS-364 title: Release Notes 3.21.0 toc: true weight: 98 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.1.md b/content/controller/releases/adc/adc-release-notes-3.22.1.md index be4725b06..1edfce2a2 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.1.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.1.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-834 +nd-docs: DOCS-834 title: Release Notes 3.22.1 toc: true weight: 96 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.2.md b/content/controller/releases/adc/adc-release-notes-3.22.2.md index 5c34ef08d..be60921c1 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.2.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.2.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-844 +nd-docs: DOCS-844 title: Release Notes 3.22.2 toc: true weight: 95 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.3.md b/content/controller/releases/adc/adc-release-notes-3.22.3.md index 2e5b929a0..f2cd355dd 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.3.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.3.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-903 +nd-docs: DOCS-903 title: Release Notes 3.22.3 toc: true weight: 94 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.4.md b/content/controller/releases/adc/adc-release-notes-3.22.4.md index d9a643241..b3e57e438 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.4.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.4.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-904 +nd-docs: DOCS-904 title: Release Notes 3.22.4 toc: true weight: 93 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.5.md b/content/controller/releases/adc/adc-release-notes-3.22.5.md index 1a2d67d64..62d7320f4 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.5.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.5.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-945 +nd-docs: DOCS-945 title: Release Notes 3.22.5 toc: true weight: 92 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.6.md b/content/controller/releases/adc/adc-release-notes-3.22.6.md index 75d6bd8ac..ccc955ea1 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.6.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.6.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-1086 +nd-docs: DOCS-1086 title: Release Notes 3.22.6 toc: true weight: 91 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.7.md b/content/controller/releases/adc/adc-release-notes-3.22.7.md index a1883fb55..4c6c304d9 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.7.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.7.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-1388 +nd-docs: DOCS-1388 title: Release Notes 3.22.7 toc: true weight: 90 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.8.md b/content/controller/releases/adc/adc-release-notes-3.22.8.md index 43d27fea1..2b5615851 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.8.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.8.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-1128 +nd-docs: DOCS-1128 title: Release Notes 3.22.8 toc: true weight: 89 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.9.md b/content/controller/releases/adc/adc-release-notes-3.22.9.md index 7a073233a..dc2273c0a 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.9.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.9.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-1341 +nd-docs: DOCS-1341 title: Release Notes 3.22.9 toc: true weight: 88 diff --git a/content/controller/releases/adc/adc-release-notes-3.22.md b/content/controller/releases/adc/adc-release-notes-3.22.md index 3aa65aa56..c6766cdb9 100644 --- a/content/controller/releases/adc/adc-release-notes-3.22.md +++ b/content/controller/releases/adc/adc-release-notes-3.22.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller Application Delivery Module. -docs: DOCS-833 +nd-docs: DOCS-833 title: Release Notes 3.22.0 toc: true weight: 97 diff --git a/content/controller/releases/apim/apim-release-notes-3.18.1.md b/content/controller/releases/apim/apim-release-notes-3.18.1.md index daa7f82d4..95a88a006 100644 --- a/content/controller/releases/apim/apim-release-notes-3.18.1.md +++ b/content/controller/releases/apim/apim-release-notes-3.18.1.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-365 +nd-docs: DOCS-365 title: Release Notes 3.18.1 toc: true weight: 99 diff --git a/content/controller/releases/apim/apim-release-notes-3.18.md b/content/controller/releases/apim/apim-release-notes-3.18.md index 4e165a625..c76b7d9ab 100644 --- a/content/controller/releases/apim/apim-release-notes-3.18.md +++ b/content/controller/releases/apim/apim-release-notes-3.18.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-366 +nd-docs: DOCS-366 title: Release Notes 3.18.0 toc: true weight: 100 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.1.md b/content/controller/releases/apim/apim-release-notes-3.19.1.md index 6bb063f3e..a1861b9f2 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.1.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.1.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-367 +nd-docs: DOCS-367 title: Release Notes 3.19.1 toc: true weight: 96 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.2.md b/content/controller/releases/apim/apim-release-notes-3.19.2.md index 8767ed6f3..02d25e6f8 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.2.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.2.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-368 +nd-docs: DOCS-368 title: Release Notes 3.19.2 toc: true weight: 95 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.3.md b/content/controller/releases/apim/apim-release-notes-3.19.3.md index 111d667e4..58766df89 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.3.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.3.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-887 +nd-docs: DOCS-887 title: Release Notes 3.19.3 toc: true weight: 94 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.4.md b/content/controller/releases/apim/apim-release-notes-3.19.4.md index a836bb66f..6ac037e35 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.4.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.4.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-888 +nd-docs: DOCS-888 title: Release Notes 3.19.4 toc: true weight: 93 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.5.md b/content/controller/releases/apim/apim-release-notes-3.19.5.md index 2a8d44b63..f426e942b 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.5.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.5.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-1113 +nd-docs: DOCS-1113 title: Release Notes 3.19.5 toc: true weight: 92 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.6.md b/content/controller/releases/apim/apim-release-notes-3.19.6.md index caa74a837..cc69889cd 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.6.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.6.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-1282 +nd-docs: DOCS-1282 title: Release Notes 3.19.6 toc: true weight: 91 diff --git a/content/controller/releases/apim/apim-release-notes-3.19.md b/content/controller/releases/apim/apim-release-notes-3.19.md index d443b7f00..fb1077f9b 100644 --- a/content/controller/releases/apim/apim-release-notes-3.19.md +++ b/content/controller/releases/apim/apim-release-notes-3.19.md @@ -1,7 +1,7 @@ --- description: These release notes contain information about new features, improvements, known issues, and bug fixes in the NGINX Controller API Management Module. -docs: DOCS-369 +nd-docs: DOCS-369 title: Release Notes 3.19.0 toc: true weight: 97 diff --git a/content/controller/releases/release-notes.md b/content/controller/releases/release-notes.md index f5d74c780..139e644d2 100644 --- a/content/controller/releases/release-notes.md +++ b/content/controller/releases/release-notes.md @@ -1,7 +1,7 @@ --- description: Learn about the new features, enhancements, resolved issues, and known issues in F5 NGINX Controller. -docs: DOCS-370 +nd-docs: DOCS-370 title: NGINX Controller v3.0.0–3.18.3 toc: true weight: 10 diff --git a/content/controller/services/available-policies.md b/content/controller/services/available-policies.md index e8d81dbea..17b49ec6f 100644 --- a/content/controller/services/available-policies.md +++ b/content/controller/services/available-policies.md @@ -1,6 +1,6 @@ --- description: Learn about the policies available for use in the F5 NGINX Controller. -docs: DOCS-568 +nd-docs: DOCS-568 title: Learn About Policies toc: true weight: 130 diff --git a/content/controller/services/manage-certs.md b/content/controller/services/manage-certs.md index 32fcf9bc1..d87d72aab 100644 --- a/content/controller/services/manage-certs.md +++ b/content/controller/services/manage-certs.md @@ -1,6 +1,6 @@ --- description: Create, apply, and mange Certs to use with your environments. -docs: DOCS-371 +nd-docs: DOCS-371 title: Manage Certs toc: true weight: 120 diff --git a/content/controller/services/manage-environments.md b/content/controller/services/manage-environments.md index c381c88b6..5ffa5a3f6 100644 --- a/content/controller/services/manage-environments.md +++ b/content/controller/services/manage-environments.md @@ -1,6 +1,6 @@ --- description: Create and manage environments to use with your apps, gateways, and certs. -docs: DOCS-372 +nd-docs: DOCS-372 title: Manage Environments toc: true weight: 100 diff --git a/content/controller/services/manage-gateways.md b/content/controller/services/manage-gateways.md index 2eb87b8ec..e99d66ae9 100644 --- a/content/controller/services/manage-gateways.md +++ b/content/controller/services/manage-gateways.md @@ -1,6 +1,6 @@ --- description: Create, view, and edit Gateways. -docs: DOCS-373 +nd-docs: DOCS-373 title: Manage Gateways toc: true weight: 120 diff --git a/content/controller/services/manage-identity-providers.md b/content/controller/services/manage-identity-providers.md index 3df64f6d7..e234ca0e5 100644 --- a/content/controller/services/manage-identity-providers.md +++ b/content/controller/services/manage-identity-providers.md @@ -1,6 +1,6 @@ --- description: Create and Manage Identity Providers. -docs: DOCS-571 +nd-docs: DOCS-571 title: Manage Identity Providers toc: true weight: 140 diff --git a/content/controller/services/overview.md b/content/controller/services/overview.md index a073c6a04..caf809da7 100644 --- a/content/controller/services/overview.md +++ b/content/controller/services/overview.md @@ -1,7 +1,7 @@ --- description: Learn about the common tasks and resources that are required to deploy and manage Services using F5 NGINX Controller. -docs: DOCS-374 +nd-docs: DOCS-374 title: Set Up NGINX Controller Services toc: true weight: 10 diff --git a/content/controller/support/contact-support.md b/content/controller/support/contact-support.md index c526b6fed..f440bac71 100644 --- a/content/controller/support/contact-support.md +++ b/content/controller/support/contact-support.md @@ -1,6 +1,6 @@ --- description: Contact information and knowledge resources for F5 NGINX Support. -docs: DOCS-375 +nd-docs: DOCS-375 title: Where to Go for Support toc: true weight: 10 diff --git a/content/controller/support/troubleshooting-controller.md b/content/controller/support/troubleshooting-controller.md index 09cf2eac5..3f0c11e05 100644 --- a/content/controller/support/troubleshooting-controller.md +++ b/content/controller/support/troubleshooting-controller.md @@ -1,7 +1,7 @@ --- description: Steps to take to investigate and fix issues with F5 NGINX Controller and the Controller Agent. -docs: DOCS-376 +nd-docs: DOCS-376 title: Troubleshoot NGINX Controller and the Controller Agent toc: true weight: 100 diff --git a/content/controller/support/troubleshooting-forwarders.md b/content/controller/support/troubleshooting-forwarders.md index ce2ae120f..235579408 100644 --- a/content/controller/support/troubleshooting-forwarders.md +++ b/content/controller/support/troubleshooting-forwarders.md @@ -1,6 +1,6 @@ --- description: Steps to take to investigate and fix issues with data forwarders. -docs: DOCS-377 +nd-docs: DOCS-377 title: Troubleshoot Data Forwarders toc: true weight: 200 diff --git a/content/includes/acm/about/global-policies.md b/content/includes/acm/about/global-policies.md index 6d4e66500..5c5c47df3 100644 --- a/content/includes/acm/about/global-policies.md +++ b/content/includes/acm/about/global-policies.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1283 +nd-docs: DOCS-1283 --- The following table shows the available Global Policies you can use when creating a new cluster. diff --git a/content/includes/acm/how-to/policies-proxy-cluster-intro.md b/content/includes/acm/how-to/policies-proxy-cluster-intro.md index 066e5d1bf..d109bfcf3 100644 --- a/content/includes/acm/how-to/policies-proxy-cluster-intro.md +++ b/content/includes/acm/how-to/policies-proxy-cluster-intro.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1285 +nd-docs: DOCS-1285 --- In API Connectivity Manager, you can apply cluster policies to API Gateways and Developer Portals to further enhance their configuration to meet your requirements. A proxy cluster is a group of instances configured as API Gateways or Developer Portals. Any cluster policy will apply to all instances in a group. diff --git a/content/includes/acm/how-to/policies-proxy-intro.md b/content/includes/acm/how-to/policies-proxy-intro.md index 79053568f..63f57ba84 100644 --- a/content/includes/acm/how-to/policies-proxy-intro.md +++ b/content/includes/acm/how-to/policies-proxy-intro.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1286 +nd-docs: DOCS-1286 --- In API Connectivity Manager, you can apply policies to an API Gateway to further enhance their configuration to meet your requirements. diff --git a/content/includes/acm/openapi-support.md b/content/includes/acm/openapi-support.md index 382b55d4e..1d4393653 100644 --- a/content/includes/acm/openapi-support.md +++ b/content/includes/acm/openapi-support.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1188 +nd-docs: DOCS-1188 --- {{< note >}}API Connectivity Manager supports the [OpenAPI Specification version 3.0 and 3.1](https://swagger.io/specification/). If your spec uses the 2.0 standard, you must convert it before uploading it.{{< /note >}} diff --git a/content/includes/acm/webui-acm-login.md b/content/includes/acm/webui-acm-login.md index ce33502dc..bd38ca740 100644 --- a/content/includes/acm/webui-acm-login.md +++ b/content/includes/acm/webui-acm-login.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1189 +nd-docs: DOCS-1189 --- In a web browser, go to the FQDN for your NGINX Instance Manager host and log in. Then, from the Launchpad menu, select **API Connectivity Manager**. diff --git a/content/includes/agent/about.md b/content/includes/agent/about.md new file mode 100644 index 000000000..abca6d4bb --- /dev/null +++ b/content/includes/agent/about.md @@ -0,0 +1,43 @@ +--- +docs: +files: + - content/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. + +## 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 "/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 "/nginx-one/agent/metrics/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. + +By default, the OpenTelemetry Collector is configured to send metrics to NGINX One Console. \ No newline at end of file diff --git a/content/includes/agent/architecture.md b/content/includes/agent/architecture.md new file mode 100644 index 000000000..d09a138be --- /dev/null +++ b/content/includes/agent/architecture.md @@ -0,0 +1,22 @@ +--- +docs: +files: + - content/agent/about.md + - content/nginx-one/agent/overview/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/includes/agent/installation/install-agent-api.md b/content/includes/agent/installation/install-agent-api.md index 15009d21f..5474f995b 100644 --- a/content/includes/agent/installation/install-agent-api.md +++ b/content/includes/agent/installation/install-agent-api.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1031 +nd-docs: DOCS-1031 files: - content/nim/nginx-app-protect/setup-waf-config-management.md --- 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..dc00015bd --- /dev/null +++ b/content/includes/agent/installation/manually-connect-to-console.md @@ -0,0 +1,42 @@ +--- +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. + +1. Ensure NGINX Agent is installed + + ```shell + nginx-agent -v + ``` + +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 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/content/includes/agent/installation/oss/oss-alpine.md b/content/includes/agent/installation/oss/oss-alpine.md new file mode 100644 index 000000000..41f4d734a --- /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-upgrade/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..3a3f326b8 --- /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-upgrade/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..1d8913352 --- /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-upgrade/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: 2027-05-24] + 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..31014d5e1 --- /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-upgrade/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..50ae65222 --- /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-upgrade/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..d6e41c15d --- /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-upgrade/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: 2027-05-24] + 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..b1f5127c9 --- /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-upgrade/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: 2027-05-24] + 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..6b07cae37 --- /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-upgrade/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..505c5c910 --- /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-upgrade/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..81e453656 --- /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-upgrade/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..3cb6442e8 --- /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-upgrade/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..8db68e5aa --- /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-upgrade/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..d9e1cd3f0 --- /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-upgrade/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: 2027-05-24] + 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..e14f84ee7 --- /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-upgrade/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..9a91bf9cb --- /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-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/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 new file mode 100644 index 000000000..fdbbbce62 --- /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-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: + +```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..47e6e8d7c --- /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/install-upgrade/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..8fc2c7eab --- /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/install-upgrade/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..5a25674d5 --- /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/install-upgrade/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..ef18d978b --- /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/install-upgrade/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..4d0a01405 --- /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/install-upgrade/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..c46fef3d9 --- /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/install-upgrade/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..5a25674d5 --- /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/install-upgrade/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/update-container.md b/content/includes/agent/installation/update-container.md new file mode 100644 index 000000000..a974cfbce --- /dev/null +++ b/content/includes/agent/installation/update-container.md @@ -0,0 +1,24 @@ +--- +docs: +files: + - content/agent/install-upgrade/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) + +To upgrade the configuration, you can follow this example: + +```shell +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 +``` + +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/nginx-configs/config-sync-groups/manage-config-sync-groups.md" >}}) for more information. + +### Rolling back from NGINX Agent v3 to v2 + +If you need to roll back your environment to NGINX Agent v2, the upgrade process creates a backup of the NGINX Agent v2 config in the file `/etc/nginx-agent/nginx-agent-v2-backup.conf`. + +Replace the 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/agent/installation/update.md b/content/includes/agent/installation/update.md new file mode 100644 index 000000000..6b6834ae7 --- /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/install-upgrade/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..77facea04 --- /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-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 +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/includes/agent/tech-specs.md b/content/includes/agent/tech-specs.md new file mode 100644 index 000000000..129745c66 --- /dev/null +++ b/content/includes/agent/tech-specs.md @@ -0,0 +1,23 @@ +--- +docs: +files: + - content/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 +hardware requirements for running NGINX Plus itself. This ensures compatibility, stability, +and performance aligned with the NGINX core platform: + +### Supported distributions + +{{< include "nginx-plus/supported-distributions.md" >}} + +To see the detailed technical specifications for NGINX Plus, refer to the official +[NGINX Plus documentation]({{< ref "/nginx/technical-specs.md" >}}). + + +### 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). \ No newline at end of file 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/includes/config-snippets/enable-nplus-api-dashboard.md b/content/includes/config-snippets/enable-nplus-api-dashboard.md new file mode 100644 index 000000000..0aaf4b750 --- /dev/null +++ b/content/includes/config-snippets/enable-nplus-api-dashboard.md @@ -0,0 +1,37 @@ +--- +docs: +files: +- content/nginx-one/workshops/lab5/upgrade-nginx-plus-to-latest-version.md +- content/includes/use-cases/monitoring/enable-nginx-plus-api.md +--- + +```nginx +# This block enables the NGINX Plus API and dashboard +# For configuration and security recommendations, see: +# https://docs.nginx.com/nginx/admin-guide/monitoring/live-activity-monitoring/#configuring-the-api +server { + # Change the listen port if 9000 conflicts + # (8080 is the conventional API port) + listen 9000; + + location /api/ { + # To restrict write methods (POST, PATCH, DELETE), uncomment: + # limit_except GET { + # auth_basic "NGINX Plus API"; + # auth_basic_user_file /path/to/passwd/file; + # } + + # Enable API in write mode + api write=on; + + # To restrict access by network, uncomment and set your network: + # allow 192.0.2.0/24 # replace with your network + # deny all; + } + + # Serve the built-in dashboard at /dashboard.html + location = /dashboard.html { + root /usr/share/nginx/html; + } +} +``` \ No newline at end of file diff --git a/content/includes/controller/apim-rn-preamble.md b/content/includes/controller/apim-rn-preamble.md index fbd0ea643..85429019e 100644 --- a/content/includes/controller/apim-rn-preamble.md +++ b/content/includes/controller/apim-rn-preamble.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1306 +nd-docs: DOCS-1306 --- We encourage you to install the latest version of the NGINX Controller APIM module to take advantage of the newest features and updates. diff --git a/content/includes/installation/access-web-ui.md b/content/includes/installation/access-web-ui.md index 4f0199cc7..d51fe6f73 100644 --- a/content/includes/installation/access-web-ui.md +++ b/content/includes/installation/access-web-ui.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1241 +nd-docs: DOCS-1241 --- To access the NGINX Instance Manager web interface, open a web browser and go to `https://`, replacing `` with the Fully Qualified Domain Name of your NGINX Instance Manager host. diff --git a/content/includes/installation/add-nms-repo.md b/content/includes/installation/add-nms-repo.md index fec0ae06f..05639f135 100644 --- a/content/includes/installation/add-nms-repo.md +++ b/content/includes/installation/add-nms-repo.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1243 +nd-docs: DOCS-1243 --- Select the tab matching your Linux distribution, then follow the instructions to add the NGINX Instance Manager repository. @@ -36,23 +36,39 @@ Add the NGINX Instance Manager repository: {{%tab name="Debian, Ubuntu, Deb-Based"%}} -Add the NGINX Instance Manager repository: - -- **Debian** +1. Add the NGINX signing key: ```shell - printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list - sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx + wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key \ + | gpg --dearmor \ + | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null ``` -
+2. Add the NGINX Instance Manager repository: -- **Ubuntu** + - **Debian** - ```shell - printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nms/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nms.list - sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx https://cs.nginx.com/static/files/90pkgs-nginx - ``` + ```shell + printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://pkgs.nginx.com/nms/debian $(lsb_release -cs) nginx-plus\n" | \ + sudo tee /etc/apt/sources.list.d/nms.list + + sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx \ + https://cs.nginx.com/static/files/90pkgs-nginx + ``` + +
+ + - **Ubuntu** + + ```shell + printf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ + https://pkgs.nginx.com/nms/ubuntu $(lsb_release -cs) nginx-plus\n" | \ + sudo tee /etc/apt/sources.list.d/nms.list + + sudo wget -q -O /etc/apt/apt.conf.d/90pkgs-nginx \ + https://cs.nginx.com/static/files/90pkgs-nginx + ``` {{%/tab%}} {{}} 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/clickhouse-defaults.md b/content/includes/installation/clickhouse-defaults.md deleted file mode 100644 index 0921b6ebb..000000000 --- a/content/includes/installation/clickhouse-defaults.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -docs: DOCS-1238 ---- - -{{}} - -| Configuration | Default | Notes | -|--------------------------|------------------------------------|-------| -| clickhouse.address | tcp://localhost:9000 | | -| clickhouse.username | | | -| clickhouse.password | | | -| clickhouse.tls_mode | false | | -| clickhouse.tls.address | tcp://localhost:9440 | | -| clickhouse.tls.skip_verify | false |`clickhouse.tls.skip_verify` should be used only for self-signed certificates and is never recommended for production use. When set to `true`, certificates are not verified, which exposes the connection to man-in-the-middle attacks. | -| clickhouse.tls.key_path | | | -| clickhouse.tls.cert_path | | | -| clickhouse.tls.ca_path | /etc/ssl/certs/ca-certificates.crt |The default value for `clickhouse.tls.ca_path` works out-of-the-box for Ubuntu and Debian. You'll need to [configure a different Certificate Authority](#tls) for other distributions. Refer to your distribution's documentation for additional information.| - -{{}} - -
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/includes/installation/helm/acm/dev-portal-helm-configurations/configuration-options.md b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configuration-options.md index e2b41be4c..6cea14a5c 100644 --- a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configuration-options.md +++ b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configuration-options.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1308 +nd-docs: DOCS-1308 --- The `values.yaml` file within the `nginx-devportal` Helm chart contains the deployment configuration for the Developer Portal. diff --git a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-api-mtls.md b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-api-mtls.md index a7f7d99ac..1d7358f1e 100644 --- a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-api-mtls.md +++ b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-api-mtls.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1309 +nd-docs: DOCS-1309 --- When deploying the Developer Portal using a helm chart, you can configure TLS to secure communication between the NGINX API Gateway and backend API service. diff --git a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-embedded-postgres.md b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-embedded-postgres.md index 694a88c1d..b14932a4e 100644 --- a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-embedded-postgres.md +++ b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-embedded-postgres.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1311 +nd-docs: DOCS-1311 --- You can use an embedded PostgreSQL database for backend API service storage when deploying the Developer Portal from a Helm chart. This configuration uses a [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for storage of the the PostgreSQL data files. Access between the backend API service and the database is secured using auto-generated client TLS certificates. diff --git a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-external-postgres.md b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-external-postgres.md index a2acc97df..54bdc7396 100644 --- a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-external-postgres.md +++ b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-devportal-helm-external-postgres.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1307 +nd-docs: DOCS-1307 --- You can use an external PostgreSQL database for backend API service storage when deploying the Developer Portal from a Helm chart. Access between the backend API service and the database can be secured using TLS server certificates and optional client TLS certificates. diff --git a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-helm-devportal-sqlite.md b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-helm-devportal-sqlite.md index 2edd94094..d1a4b970a 100644 --- a/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-helm-devportal-sqlite.md +++ b/content/includes/installation/helm/acm/dev-portal-helm-configurations/configure-helm-devportal-sqlite.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1312 +nd-docs: DOCS-1312 --- You can use an SQLite database for backend API service storage when deploying the Developer Portal from a Helm chart. This configuration uses a [PersistentVolumeClaim (PVC)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for storage of the SQLite data files. diff --git a/content/includes/installation/nms-prerequisites.md b/content/includes/installation/nms-prerequisites.md index da6a17fd7..db01872ea 100644 --- a/content/includes/installation/nms-prerequisites.md +++ b/content/includes/installation/nms-prerequisites.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1242 +nd-docs: DOCS-1242 --- {{< important >}} diff --git a/content/includes/installation/optional-installation-steps.md b/content/includes/installation/optional-installation-steps.md index d8051f7d3..71674e85b 100644 --- a/content/includes/installation/optional-installation-steps.md +++ b/content/includes/installation/optional-installation-steps.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1030 +nd-docs: DOCS-1030 --- The following steps may be necessary depending on your installation configuration. diff --git a/content/includes/installation/secure-installation.md b/content/includes/installation/secure-installation.md index 35a08c963..509d72e65 100644 --- a/content/includes/installation/secure-installation.md +++ b/content/includes/installation/secure-installation.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1405 +nd-docs: DOCS-1405 --- To ensure that your NGINX Instance Manager deployment remains secure, follow the recommendations in this section: diff --git a/content/includes/nap-waf/build-from-official-nginx-image.md b/content/includes/nap-waf/build-from-official-nginx-image.md index 9946fefd5..e6b0e4c8d 100644 --- a/content/includes/nap-waf/build-from-official-nginx-image.md +++ b/content/includes/nap-waf/build-from-official-nginx-image.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1509" +nd-docs: "DOCS-1509" --- {{< note >}} diff --git a/content/includes/nap-waf/build-nginx-image-cmd.md b/content/includes/nap-waf/build-nginx-image-cmd.md index fcb89d363..4e7e2387f 100644 --- a/content/includes/nap-waf/build-nginx-image-cmd.md +++ b/content/includes/nap-waf/build-nginx-image-cmd.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1512" +nd-docs: "DOCS-1512" --- {{< note >}} diff --git a/content/includes/nap-waf/bundles-volume-mount.md b/content/includes/nap-waf/bundles-volume-mount.md index c42242fee..c65050849 100644 --- a/content/includes/nap-waf/bundles-volume-mount.md +++ b/content/includes/nap-waf/bundles-volume-mount.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1511" +nd-docs: "DOCS-1511" --- To work with custom policy and logging profile bundles, these files must be accessible to the `waf-config-mgr` container. diff --git a/content/includes/nap-waf/concept/apreload.md b/content/includes/nap-waf/concept/apreload.md index cfd5f6fd0..2da2e366c 100644 --- a/content/includes/nap-waf/concept/apreload.md +++ b/content/includes/nap-waf/concept/apreload.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- apreload is a tool that can update that can update the NGINX App Protect WAF configuration without having to reload NGINX if only the App Protect configuration is changed and the `nginx.conf` file remains unchanged. apreload does not affect the existing NGINX reload process and it functions in the same manner as before. diff --git a/content/includes/nap-waf/concept/attack-signatures.md b/content/includes/nap-waf/concept/attack-signatures.md index dbdf294b7..1b56c1a9b 100644 --- a/content/includes/nap-waf/concept/attack-signatures.md +++ b/content/includes/nap-waf/concept/attack-signatures.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- Attack signatures are rules or patterns that identify attack sequences or classes of attacks on a web application and its components. You can apply attack signatures to both requests and responses. App Protect includes predefined attack signatures to protect your application against all attack types identified by the system. \ No newline at end of file diff --git a/content/includes/nap-waf/concept/basic-config-default-policy.md b/content/includes/nap-waf/concept/basic-config-default-policy.md index fc56a65c7..3854b5a45 100644 --- a/content/includes/nap-waf/concept/basic-config-default-policy.md +++ b/content/includes/nap-waf/concept/basic-config-default-policy.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- The base template is the common starting point to any policy you write. The default policy just reflects that template without any further modifications, thus we use the terms **base template** and **default policy** interchangeably. The default policy appears as follows diff --git a/content/includes/nap-waf/concept/external-references.md b/content/includes/nap-waf/concept/external-references.md index 5de006331..d0c2cdf31 100644 --- a/content/includes/nap-waf/concept/external-references.md +++ b/content/includes/nap-waf/concept/external-references.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- External references in policy are defined as any code blocks that can be used as part of the policy without being explicitly pasted within the policy file. This means that you can have a set of pre-defined configurations for parts of the policy, and you can incorporate them as part of the policy by simply referencing them. This would save a lot of overhead having to concentrate everything into a single policy file. diff --git a/content/includes/nap-waf/concept/global-directives.md b/content/includes/nap-waf/concept/global-directives.md index 46dd8852c..d3b998312 100644 --- a/content/includes/nap-waf/concept/global-directives.md +++ b/content/includes/nap-waf/concept/global-directives.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- Global configuration consists of a series of `nginx.conf` directives at the `http` context controlling aspects that are not specific to a specific application. diff --git a/content/includes/nap-waf/concept/graphql-profile.md b/content/includes/nap-waf/concept/graphql-profile.md index da2e0bc23..c23175f8d 100644 --- a/content/includes/nap-waf/concept/graphql-profile.md +++ b/content/includes/nap-waf/concept/graphql-profile.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- The GraphQL Profile defines the GraphQL properties that are enforced by the security policy. diff --git a/content/includes/nap-waf/concept/grpc-logging.md b/content/includes/nap-waf/concept/grpc-logging.md index b4c7c826d..bcce1d690 100644 --- a/content/includes/nap-waf/concept/grpc-logging.md +++ b/content/includes/nap-waf/concept/grpc-logging.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- Security log for gRPC requests has unique fields: `uri`, `grpc_method`, and `grpc_service`. Also, since the content of gRPC requests is binary (Protocol Buffers), it is better transferred in Base64 encoding. Hence, it is recommended to use the `headers` and `request_body_base64` fields instead of the `request` field. A new predefined log format called `grpc` should be used in all gRPC locations that also use policies with gRPC Content Profiles. diff --git a/content/includes/nap-waf/config/common/additional-config-options.md b/content/includes/nap-waf/config/common/additional-config-options.md index 80e253d6c..d9bdd6b10 100644 --- a/content/includes/nap-waf/config/common/additional-config-options.md +++ b/content/includes/nap-waf/config/common/additional-config-options.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1552" +nd-docs: "DOCS-1552" --- #### XFF Headers and Trust diff --git a/content/includes/nap-waf/config/common/additional-policy-features.md b/content/includes/nap-waf/config/common/additional-policy-features.md index 190c24a06..ce5395a0e 100644 --- a/content/includes/nap-waf/config/common/additional-policy-features.md +++ b/content/includes/nap-waf/config/common/additional-policy-features.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1592" +nd-docs: "DOCS-1592" --- {{}} diff --git a/content/includes/nap-waf/config/common/anti-automation.md b/content/includes/nap-waf/config/common/anti-automation.md index 229037e39..93459aaba 100644 --- a/content/includes/nap-waf/config/common/anti-automation.md +++ b/content/includes/nap-waf/config/common/anti-automation.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1575" +nd-docs: "DOCS-1575" --- Anti Automation provides basic bot protection by detecting bot signatures and clients that falsely claim to be browsers or search engines. The `bot-defense` section in the policy is enabled by default. Anti Automation encompasses both Bot Signatures and Header Anomalies, each of which can be disabled separately. diff --git a/content/includes/nap-waf/config/common/associating-graphql-profiles.md b/content/includes/nap-waf/config/common/associating-graphql-profiles.md index 60b86bfa8..6956777bc 100644 --- a/content/includes/nap-waf/config/common/associating-graphql-profiles.md +++ b/content/includes/nap-waf/config/common/associating-graphql-profiles.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1607" +nd-docs: "DOCS-1607" --- The last step is to associate the GraphQL profiles with the URLs. As with JSON and XML profiles, in order for a GraphQL Profile to become effective, it has to be associated with a URL that represents the service. Add the GraphQL profile name which you defined previously under the GraphQL profiles in the name field. For example, here we have defined two GraphQL profiles with the "name": "Default" and "My Custom Profile" under the urlContentProfiles. Later we also associated these profiles in "graphql-profiles". diff --git a/content/includes/nap-waf/config/common/associating-profiles-urls.md b/content/includes/nap-waf/config/common/associating-profiles-urls.md index 4afe9e486..32759a008 100644 --- a/content/includes/nap-waf/config/common/associating-profiles-urls.md +++ b/content/includes/nap-waf/config/common/associating-profiles-urls.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1555" +nd-docs: "DOCS-1555" --- As with JSON and XML profiles, in order for a gRPC Content Profile to become effective, it has to be associated with a URL that represents the service. However, in the sample policy above, the profile was apparently not associated with any URL and yet the profile is active. How did this happen? By setting `associateUrls` with `true`, App Protect **implicitly** creates the URL based on the package and service name as defined in the IDL file and associates the profile with that URL. In this example, the URL is `/myorg.services.photo_album/*`. Note it is a wildcard URL so that all methods in this service match it in its suffix; for example `/myorg.services.photo_album/get_photos` represents the `get_photos` RPC method. diff --git a/content/includes/nap-waf/config/common/attack-types.md b/content/includes/nap-waf/config/common/attack-types.md index fff386874..520850bd6 100644 --- a/content/includes/nap-waf/config/common/attack-types.md +++ b/content/includes/nap-waf/config/common/attack-types.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1570" +nd-docs: "DOCS-1570" --- Each signature, factory or user-defined, and violation has an **Attack Type**, the attack vector it protects from. When you create a user-defined signature you associate it with the most appropriate attack type from the list below. If you do not find an Attack Type that matches the threat for which your signature was written, use `Other Application Activity` Attack Type. Attach Types are also useful as part of the filter in user-defined signature **sets**. diff --git a/content/includes/nap-waf/config/common/basic-signature-sets-included-in-app-protect.md b/content/includes/nap-waf/config/common/basic-signature-sets-included-in-app-protect.md index ebdf79117..43d69be2d 100644 --- a/content/includes/nap-waf/config/common/basic-signature-sets-included-in-app-protect.md +++ b/content/includes/nap-waf/config/common/basic-signature-sets-included-in-app-protect.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1568" +nd-docs: "DOCS-1568" --- These signatures sets are included but are not part of the default template. diff --git a/content/includes/nap-waf/config/common/bidirectional-streaming-overview.md b/content/includes/nap-waf/config/common/bidirectional-streaming-overview.md index 950cf9c7b..f55ad2820 100644 --- a/content/includes/nap-waf/config/common/bidirectional-streaming-overview.md +++ b/content/includes/nap-waf/config/common/bidirectional-streaming-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1565" +nd-docs: "DOCS-1565" --- A gRPC service can have a stream of messages on each side: client, server, or both. Bidirectional Streaming leverages HTTP/2 streaming capability, namely the ability to send multiple gRPC messages from either side ended by the message having the `END_STREAM` flag set to 1. diff --git a/content/includes/nap-waf/config/common/clickjacking-protection.md b/content/includes/nap-waf/config/common/clickjacking-protection.md index 3bde2ddca..c73c94b8e 100644 --- a/content/includes/nap-waf/config/common/clickjacking-protection.md +++ b/content/includes/nap-waf/config/common/clickjacking-protection.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1611" +nd-docs: "DOCS-1611" --- Clickjacking refers to a technique used by malicious actors to embed remote website content into their malicious websites, tricking the end users to click on the embedded frames triggering actions the users were not aware of, such as liking a certain Facebook page or giving a restaurant a 5 star rating. To protect against such attacks, NGINX App Protect WAF uses the `X-Frame-Options` header capabilities. The `X-Frame-Options` header is injected by NGINX App Protect WAF to indicate to the browser whether it should embed the content or not. Please note that this additional layer of security is available only in browsers that support the `X-Frame-Options` headers. diff --git a/content/includes/nap-waf/config/common/configure-client-authorization.md b/content/includes/nap-waf/config/common/configure-client-authorization.md index 1fdd8cf30..81388383d 100644 --- a/content/includes/nap-waf/config/common/configure-client-authorization.md +++ b/content/includes/nap-waf/config/common/configure-client-authorization.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1571" +nd-docs: "DOCS-1571" --- ```nginx diff --git a/content/includes/nap-waf/config/common/configure-nginx-mirror.md b/content/includes/nap-waf/config/common/configure-nginx-mirror.md index a50e33357..1a5f75833 100644 --- a/content/includes/nap-waf/config/common/configure-nginx-mirror.md +++ b/content/includes/nap-waf/config/common/configure-nginx-mirror.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1561" +nd-docs: "DOCS-1561" --- ```nginx diff --git a/content/includes/nap-waf/config/common/configure-njs.md b/content/includes/nap-waf/config/common/configure-njs.md index 8e5949b18..266180b6a 100644 --- a/content/includes/nap-waf/config/common/configure-njs.md +++ b/content/includes/nap-waf/config/common/configure-njs.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1579" +nd-docs: "DOCS-1579" --- ```nginx diff --git a/content/includes/nap-waf/config/common/configure-ranges.md b/content/includes/nap-waf/config/common/configure-ranges.md index 73f5773cd..1e13c9e84 100644 --- a/content/includes/nap-waf/config/common/configure-ranges.md +++ b/content/includes/nap-waf/config/common/configure-ranges.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1544" +nd-docs: "DOCS-1544" --- ```nginx diff --git a/content/includes/nap-waf/config/common/configure-slice.md b/content/includes/nap-waf/config/common/configure-slice.md index 07b4f0ab2..413a113bf 100644 --- a/content/includes/nap-waf/config/common/configure-slice.md +++ b/content/includes/nap-waf/config/common/configure-slice.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1613" +nd-docs: "DOCS-1613" --- ```nginx diff --git a/content/includes/nap-waf/config/common/configure-static-location.md b/content/includes/nap-waf/config/common/configure-static-location.md index a1f4d39e6..750905c70 100644 --- a/content/includes/nap-waf/config/common/configure-static-location.md +++ b/content/includes/nap-waf/config/common/configure-static-location.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1581" +nd-docs: "DOCS-1581" --- ```nginx diff --git a/content/includes/nap-waf/config/common/csrf-protection.md b/content/includes/nap-waf/config/common/csrf-protection.md index 9720eaada..f17fd9dd0 100644 --- a/content/includes/nap-waf/config/common/csrf-protection.md +++ b/content/includes/nap-waf/config/common/csrf-protection.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1590" +nd-docs: "DOCS-1590" --- CSRF (Cross-Site Request Forgery) is an attack vector in which the victim user that visits a sensitive site such as a bank account, is lured to click on a malicious link attempting a fraudulent operation on that sensitive site. The link may be sent over email or in a hidden frame in another site. NGINX App Protect WAF provides protection against CSRF attacks by validating the Origin header for AJAX POST requests (default configuration). diff --git a/content/includes/nap-waf/config/common/custom-log-configuration.md b/content/includes/nap-waf/config/common/custom-log-configuration.md index e24115d26..59a231191 100644 --- a/content/includes/nap-waf/config/common/custom-log-configuration.md +++ b/content/includes/nap-waf/config/common/custom-log-configuration.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1585" +nd-docs: "DOCS-1585" --- A new directive `app_protect_custom_log_attribute` will be added to the `nginx.conf` file. You can set this directive at all scopes: http, server and location. The setting at the location scope overrides the setting in the server and/or http scopes and the server scope overrides the http scope. The `app_protect_custom_log_attribute` directive syntax will consist of a **name/value** or **key/value** pair i.e. "app_protect_custom_log_attribute ". diff --git a/content/includes/nap-waf/config/common/custom-log-errors-warnings.md b/content/includes/nap-waf/config/common/custom-log-errors-warnings.md index c0a0f521d..b9684fee0 100644 --- a/content/includes/nap-waf/config/common/custom-log-errors-warnings.md +++ b/content/includes/nap-waf/config/common/custom-log-errors-warnings.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1560" +nd-docs: "DOCS-1560" --- An error message "`app_protect_custom_log_attribute` directive is invalid" will be displayed in the Security Log if the below conditions are met: diff --git a/content/includes/nap-waf/config/common/custom-log-logging-reporting.md b/content/includes/nap-waf/config/common/custom-log-logging-reporting.md index 3497a3ccb..0e2ba3e01 100644 --- a/content/includes/nap-waf/config/common/custom-log-logging-reporting.md +++ b/content/includes/nap-waf/config/common/custom-log-logging-reporting.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1609" +nd-docs: "DOCS-1609" --- When `app_protect_custom_log_attribute` is assigned to a particular location/server/http context, it will appear in the `json_log` field as a new JSON property called "customLogAttributes" at the top level. The property will not appear if no `app_protect_custom_log_attribute` directive was assigned. diff --git a/content/includes/nap-waf/config/common/custom-log-overview.md b/content/includes/nap-waf/config/common/custom-log-overview.md index 20015b968..3ae13b711 100644 --- a/content/includes/nap-waf/config/common/custom-log-overview.md +++ b/content/includes/nap-waf/config/common/custom-log-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1614" +nd-docs: "DOCS-1614" --- Custom dimensions log entries feature refers to the new configuration in NGINX App Protect WAF, where the new directive called `app_protect_custom_log_attribute` is assigned to a particular location or server or http level in the `nginx.conf` file. The need is to be able to add custom identifiers to the respective location and/or server and identify requests in the Security Log by those identifiers. diff --git a/content/includes/nap-waf/config/common/custom-log-things-to-remember.md b/content/includes/nap-waf/config/common/custom-log-things-to-remember.md index 46a472e88..97e18eae5 100644 --- a/content/includes/nap-waf/config/common/custom-log-things-to-remember.md +++ b/content/includes/nap-waf/config/common/custom-log-things-to-remember.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1589" +nd-docs: "DOCS-1589" --- The `app_protect_custom_log_attribute` directive has a few limitations which should be kept in mind while configuring this directive: diff --git a/content/includes/nap-waf/config/common/deny-allow-never-log-lists.md b/content/includes/nap-waf/config/common/deny-allow-never-log-lists.md index 4e5d8398e..7c7e7a847 100644 --- a/content/includes/nap-waf/config/common/deny-allow-never-log-lists.md +++ b/content/includes/nap-waf/config/common/deny-allow-never-log-lists.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1604" +nd-docs: "DOCS-1604" --- It is possible to define IP addresses or ranges for which the traffic will always be allowed or denied or never logged despite the rest of the configuration settings in the policy. diff --git a/content/includes/nap-waf/config/common/detect-base64-string-values.md b/content/includes/nap-waf/config/common/detect-base64-string-values.md index 7ab9b1e2a..56e58f6a7 100644 --- a/content/includes/nap-waf/config/common/detect-base64-string-values.md +++ b/content/includes/nap-waf/config/common/detect-base64-string-values.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1563" +nd-docs: "DOCS-1563" --- The Detect Base64 feature allows NGINX App Protect WAF to detect whether values in string fields in gRPC payload are Base64 encoded. When a value is detected as Base64 encoded NGINX App Protect WAF will enforce the configured signatures on the decoded value __and__ on the original value. diff --git a/content/includes/nap-waf/config/common/detect-base64.md b/content/includes/nap-waf/config/common/detect-base64.md index 28a89ba16..c80861c63 100644 --- a/content/includes/nap-waf/config/common/detect-base64.md +++ b/content/includes/nap-waf/config/common/detect-base64.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1593" +nd-docs: "DOCS-1593" --- The Detect Base64 feature allows NGINX App Protect WAF to detect whether values in headers, cookies, and parameters are Base64 encoded. When an entity is detected as Base64 encoded NGINX App Protect WAF will enforce the configured signatures on the decoded value, instead of on the original value. diff --git a/content/includes/nap-waf/config/common/disallow-application-use-geolocation.md b/content/includes/nap-waf/config/common/disallow-application-use-geolocation.md index 6ba14cc0d..9d605a922 100644 --- a/content/includes/nap-waf/config/common/disallow-application-use-geolocation.md +++ b/content/includes/nap-waf/config/common/disallow-application-use-geolocation.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1547" +nd-docs: "DOCS-1547" --- For applications protected by app protect, you can use Geolocation enforcement to restrict or allow application use in specific countries. You can adjust the lists of which countries or locations are allowed or disallowed in a app protect security policy. If the user tries to access the web application from a location that is not allowed, the `VIOL_GEOLOCATION` violation will be triggered. By default, all locations are allowed, and the alarm and block flags are enabled. diff --git a/content/includes/nap-waf/config/common/disallowed-file-types.md b/content/includes/nap-waf/config/common/disallowed-file-types.md index f253018dd..a2466410d 100644 --- a/content/includes/nap-waf/config/common/disallowed-file-types.md +++ b/content/includes/nap-waf/config/common/disallowed-file-types.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1556" +nd-docs: "DOCS-1556" --- The following file types are disallowed by default: diff --git a/content/includes/nap-waf/config/common/do-nothing-and-user-defined-parameters.md b/content/includes/nap-waf/config/common/do-nothing-and-user-defined-parameters.md index 570801a7d..5627e1b85 100644 --- a/content/includes/nap-waf/config/common/do-nothing-and-user-defined-parameters.md +++ b/content/includes/nap-waf/config/common/do-nothing-and-user-defined-parameters.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1586" +nd-docs: "DOCS-1586" --- The do-nothing in urlContentProfiles allows the user to avoid inspecting or parsing the content in a policy, and instead handle the request's header according to the specifications outlined in the security policy. diff --git a/content/includes/nap-waf/config/common/enforcer-cookie-settings.md b/content/includes/nap-waf/config/common/enforcer-cookie-settings.md index 27e5857a5..0b66474af 100644 --- a/content/includes/nap-waf/config/common/enforcer-cookie-settings.md +++ b/content/includes/nap-waf/config/common/enforcer-cookie-settings.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1608" +nd-docs: "DOCS-1608" --- NGINX App Protect WAF generates its own cookies and adds them on top of the application cookies. diff --git a/content/includes/nap-waf/config/common/evasion-techniques-subviolations.md b/content/includes/nap-waf/config/common/evasion-techniques-subviolations.md index bcdb34373..f485fcb9a 100644 --- a/content/includes/nap-waf/config/common/evasion-techniques-subviolations.md +++ b/content/includes/nap-waf/config/common/evasion-techniques-subviolations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1542" +nd-docs: "DOCS-1542" --- The following table specifies the Evasion Techniques sub-violation settings. All are supported in NGINX App Protect WAF. diff --git a/content/includes/nap-waf/config/common/filetypes-and-responses.md b/content/includes/nap-waf/config/common/filetypes-and-responses.md index 51624683c..c65c0aa33 100644 --- a/content/includes/nap-waf/config/common/filetypes-and-responses.md +++ b/content/includes/nap-waf/config/common/filetypes-and-responses.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1617" +nd-docs: "DOCS-1617" --- A user can enable/disable specific file types in the policy. diff --git a/content/includes/nap-waf/config/common/first-match-principle.md b/content/includes/nap-waf/config/common/first-match-principle.md index 309f7dd2e..60caf2f69 100644 --- a/content/includes/nap-waf/config/common/first-match-principle.md +++ b/content/includes/nap-waf/config/common/first-match-principle.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1572" +nd-docs: "DOCS-1572" --- The policy enforcement operates on the **first match** principle. This principle is applied when multiple conditions match or are similar, indicating that any incoming requests that match the first condition will be processed. In the following example, the "override_rules_example2" policy uses two override rules: "this_rule_will_match" and "non_matching_rule". Since both conditions match, the first match principle will be applied, and requests with "api" in the URI will be processed. It will reference an external policy file named "NginxStrictPolicy.json" to override the current policy. . diff --git a/content/includes/nap-waf/config/common/forward-proxy-conf.md b/content/includes/nap-waf/config/common/forward-proxy-conf.md new file mode 100644 index 000000000..eca8f09bc --- /dev/null +++ b/content/includes/nap-waf/config/common/forward-proxy-conf.md @@ -0,0 +1,20 @@ +Enable Forward Proxy Settings for IP Intelligence Client. + +To configure proxy settings, edit the client configuration file: +Path: +```shell +/etc/app_protect/tools/iprepd.cfg +``` +Example configuration: +```shell +EnableProxy=True +ProxyHost=5.1.2.4 +ProxyPort=8080 +ProxyUsername=admin # Optional +ProxyPassword=admin # Optional +CACertPath=/etc/ssl/certs/ca-certificates.crt # Optional +``` +After saving the changes, restart the client to apply the new settings. +```shell +/opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & +``` diff --git a/content/includes/nap-waf/config/common/geolocation-override-rules.md b/content/includes/nap-waf/config/common/geolocation-override-rules.md index d35f33d28..56394ded4 100644 --- a/content/includes/nap-waf/config/common/geolocation-override-rules.md +++ b/content/includes/nap-waf/config/common/geolocation-override-rules.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1567" +nd-docs: "DOCS-1567" --- The below example represents a security policy for a web application. The policy named as "override_rule_example" is based on a template called "POLICY_TEMPLATE_NGINX_BASE." The policy is set to operate in "blocking" mode, which means it will prevent certain activities. diff --git a/content/includes/nap-waf/config/common/geolocation-overview.md b/content/includes/nap-waf/config/common/geolocation-overview.md index 44c0b29a6..4cf2e1833 100644 --- a/content/includes/nap-waf/config/common/geolocation-overview.md +++ b/content/includes/nap-waf/config/common/geolocation-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1615" +nd-docs: "DOCS-1615" --- Geolocation refers to the process of assessing or determining the geographic location of an object. This feature helps in identifying the geographic location of a client or web application user. diff --git a/content/includes/nap-waf/config/common/graphql-advanced-config.md b/content/includes/nap-waf/config/common/graphql-advanced-config.md index 51e62e079..30221b397 100644 --- a/content/includes/nap-waf/config/common/graphql-advanced-config.md +++ b/content/includes/nap-waf/config/common/graphql-advanced-config.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1551" +nd-docs: "DOCS-1551" --- The below sections provides details about enabling GraphQL with advanced configuration. diff --git a/content/includes/nap-waf/config/common/graphql-define-url-settings.md b/content/includes/nap-waf/config/common/graphql-define-url-settings.md index 76541f335..9a4e59b5b 100644 --- a/content/includes/nap-waf/config/common/graphql-define-url-settings.md +++ b/content/includes/nap-waf/config/common/graphql-define-url-settings.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1588" +nd-docs: "DOCS-1588" --- The second step to configure GraphQL is to define the URL settings. Set the values for "isAllowed": **true**, "name": **/graphql** in the URLs section, which means URLs with **/graphql** name are permitted. This path will be used for all GraphQL API requests. diff --git a/content/includes/nap-waf/config/common/graphql-overview.md b/content/includes/nap-waf/config/common/graphql-overview.md index db60fb1cd..f06189e83 100644 --- a/content/includes/nap-waf/config/common/graphql-overview.md +++ b/content/includes/nap-waf/config/common/graphql-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1595" +nd-docs: "DOCS-1595" --- GraphQL is an API technology that has grown rapidly in recent years and is continuing to gain traction. GraphQL is a query language designed for APIs to use in the development of client applications that access large data sets with intricate relations among themselves. It provides an intuitive application and flexible syntax for describing data requirements.
diff --git a/content/includes/nap-waf/config/common/graphql-response-pages.md b/content/includes/nap-waf/config/common/graphql-response-pages.md index 511058ef9..73ed50f16 100644 --- a/content/includes/nap-waf/config/common/graphql-response-pages.md +++ b/content/includes/nap-waf/config/common/graphql-response-pages.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1557" +nd-docs: "DOCS-1557" --- A GraphQL error response page is returned when a request is blocked. This GraphQL response page, like other blocking response pages, can be customized, but the GraphQL JSON syntax must be preserved for them to be displayed correctly. The default page returns the GraphQL status code Blocking Response Page (BRP) and a short JSON error message which includes the support ID. diff --git a/content/includes/nap-waf/config/common/graphql-security.md b/content/includes/nap-waf/config/common/graphql-security.md index 2342ca0f9..067eb4833 100644 --- a/content/includes/nap-waf/config/common/graphql-security.md +++ b/content/includes/nap-waf/config/common/graphql-security.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1566" +nd-docs: "DOCS-1566" --- Securing GraphQL APIs with NGINX App Protect WAF involves using WAF to monitor and protect against security threats and attacks. GraphQL, like REST, is usually [served over HTTP](http://graphql.org/learn/serving-over-http/), using GET and POST requests and a proprietary [query language](https://graphql.org/learn/schema/#the-query-and-mutation-types). It is prone to the typical Web APIs security vulnerabilities, such as injection attacks, Denial of Service (DoS) attacks and abuse of flawed authorization. diff --git a/content/includes/nap-waf/config/common/graphql-violations.md b/content/includes/nap-waf/config/common/graphql-violations.md index 0045ec2c1..288fa29a4 100644 --- a/content/includes/nap-waf/config/common/graphql-violations.md +++ b/content/includes/nap-waf/config/common/graphql-violations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1578" +nd-docs: "DOCS-1578" --- NGINX App Protect WAF introduces four new violations specific to GraphQL: `VIOL_GRAPHQL_FORMAT`, `VIOL_GRAPHQL_MALFORMED`, `VIOL_GRAPHQL_INTROSPECTION_QUERY` and `VIOL_GRAPHQL_ERROR_RESPONSE`.
diff --git a/content/includes/nap-waf/config/common/grpc-bidirectional-stream-enforcement.md b/content/includes/nap-waf/config/common/grpc-bidirectional-stream-enforcement.md index d8d14d0f6..468da8b55 100644 --- a/content/includes/nap-waf/config/common/grpc-bidirectional-stream-enforcement.md +++ b/content/includes/nap-waf/config/common/grpc-bidirectional-stream-enforcement.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1606" +nd-docs: "DOCS-1606" --- #### Client Request Flow diff --git a/content/includes/nap-waf/config/common/grpc-content-profiles.md b/content/includes/nap-waf/config/common/grpc-content-profiles.md index 2f5ec344c..dbdffe203 100644 --- a/content/includes/nap-waf/config/common/grpc-content-profiles.md +++ b/content/includes/nap-waf/config/common/grpc-content-profiles.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1616" +nd-docs: "DOCS-1616" --- The gRPC Content Profile contains all the definitions for protecting a gRPC service. It is similar in nature to the **JSON and XML profiles** handling JSON and XML traffic respectively. Roughly it includes: diff --git a/content/includes/nap-waf/config/common/grpc-handling-slow-post-attacks.md b/content/includes/nap-waf/config/common/grpc-handling-slow-post-attacks.md index 1a7189010..78c430827 100644 --- a/content/includes/nap-waf/config/common/grpc-handling-slow-post-attacks.md +++ b/content/includes/nap-waf/config/common/grpc-handling-slow-post-attacks.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1599" +nd-docs: "DOCS-1599" --- Slow POST attack mitigation - A client sending messages very slowly for a long time may be cut off by resetting the connection. diff --git a/content/includes/nap-waf/config/common/grpc-message-compression.md b/content/includes/nap-waf/config/common/grpc-message-compression.md index 7fdf1b923..ff28c8674 100644 --- a/content/includes/nap-waf/config/common/grpc-message-compression.md +++ b/content/includes/nap-waf/config/common/grpc-message-compression.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1574" +nd-docs: "DOCS-1574" --- Currently, Message Compression is not supported. Therefore, a violation `VIOL_GRPC_MALFORMED` will be raised and the connection will be blocked if a compressed message is sent. \ No newline at end of file diff --git a/content/includes/nap-waf/config/common/grpc-protection-unary-traffic.md b/content/includes/nap-waf/config/common/grpc-protection-unary-traffic.md index a9de83d0e..dac89ee48 100644 --- a/content/includes/nap-waf/config/common/grpc-protection-unary-traffic.md +++ b/content/includes/nap-waf/config/common/grpc-protection-unary-traffic.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1558" +nd-docs: "DOCS-1558" --- gRPC is a remote API standard and is an alternative to OpenAPI. If your applications expose gRPC APIs, NGINX App Protect WAF can protect them by parsing the messages; making sure they comply with the API definition; and enforcing security restrictions - such as size limits, detecting attack signatures, threat campaigns, and suspicious metacharacters in message string field values. diff --git a/content/includes/nap-waf/config/common/grpc-response-pages.md b/content/includes/nap-waf/config/common/grpc-response-pages.md index 14529e719..11f7efc51 100644 --- a/content/includes/nap-waf/config/common/grpc-response-pages.md +++ b/content/includes/nap-waf/config/common/grpc-response-pages.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1597" +nd-docs: "DOCS-1597" --- A gRPC error response page is returned when a request is blocked. The default page returns gRPC status code `UNKNOWN` (numeric value of 2) and a short textual message that includes the support ID. You can customize any of these two by configuring a custom gRPC response page in your policy. diff --git a/content/includes/nap-waf/config/common/grpc-server-reflection.md b/content/includes/nap-waf/config/common/grpc-server-reflection.md index 0d27f1f8e..e8cab8f9e 100644 --- a/content/includes/nap-waf/config/common/grpc-server-reflection.md +++ b/content/includes/nap-waf/config/common/grpc-server-reflection.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1610" +nd-docs: "DOCS-1610" --- [gRPC Server Reflection](https://grpc.github.io/grpc/core/md_doc_server_reflection_tutorial.html) provides information about publicly-accessible gRPC services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. gRPC Server reflection is not currently supported in App Protect. If Server Reflection support is required, App Protect must be disabled on the reflection URIs by adding a location block such as this: diff --git a/content/includes/nap-waf/config/common/grpc-size-limits.md b/content/includes/nap-waf/config/common/grpc-size-limits.md index bb9439081..407f6cb2c 100644 --- a/content/includes/nap-waf/config/common/grpc-size-limits.md +++ b/content/includes/nap-waf/config/common/grpc-size-limits.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1619" +nd-docs: "DOCS-1619" --- The maximum total request size is applied to each message on its own, rather than to the total stream messages. By default, the maximum gRPC message size is 4MB. diff --git a/content/includes/nap-waf/config/common/grpc-slow-post-attacks.md b/content/includes/nap-waf/config/common/grpc-slow-post-attacks.md index 744878c1c..55dc41ed9 100644 --- a/content/includes/nap-waf/config/common/grpc-slow-post-attacks.md +++ b/content/includes/nap-waf/config/common/grpc-slow-post-attacks.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1637" +nd-docs: "DOCS-1637" --- A Slow POST attack or Slow HTTP POST attack is a type of denial of service attack. The attacker sends a legitimate HTTP POST request with the header Content-Length specified. The attacker then proceeds to send this content slowly. The server establishes a connection to the client and keeps it open to receive the request that it thinks is legitimate. diff --git a/content/includes/nap-waf/config/common/grpc-violations.md b/content/includes/nap-waf/config/common/grpc-violations.md index 9eb2d75bf..e93bac516 100644 --- a/content/includes/nap-waf/config/common/grpc-violations.md +++ b/content/includes/nap-waf/config/common/grpc-violations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1562" +nd-docs: "DOCS-1562" --- There are three violations that are specific to gRPC. They are all enabled in the default policy. See also the [Violations](#violations) section. diff --git a/content/includes/nap-waf/config/common/handling-xml-and-json-content.md b/content/includes/nap-waf/config/common/handling-xml-and-json-content.md index 32285a4e2..a8a54c409 100644 --- a/content/includes/nap-waf/config/common/handling-xml-and-json-content.md +++ b/content/includes/nap-waf/config/common/handling-xml-and-json-content.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1545" +nd-docs: "DOCS-1545" --- #### XML and JSON Content Profiles diff --git a/content/includes/nap-waf/config/common/http-compliance-subviolations.md b/content/includes/nap-waf/config/common/http-compliance-subviolations.md index 77f6f144d..c9482ea62 100644 --- a/content/includes/nap-waf/config/common/http-compliance-subviolations.md +++ b/content/includes/nap-waf/config/common/http-compliance-subviolations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1576" +nd-docs: "DOCS-1576" --- The following table specifies the HTTP Compliance sub-violation settings. All are supported in NGINX App Protect WAF, but not all are enabled in the default App Protect security template. The table specifies which. Some of the checks are enforced by NGINX Plus and App Protect only gets a notification. **Note:** In this case, the request is **always** blocked regardless of the App Protect policy. diff --git a/content/includes/nap-waf/config/common/important-things-override-rules.md b/content/includes/nap-waf/config/common/important-things-override-rules.md index dd17232f5..c065639cb 100644 --- a/content/includes/nap-waf/config/common/important-things-override-rules.md +++ b/content/includes/nap-waf/config/common/important-things-override-rules.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1549" +nd-docs: "DOCS-1549" --- Here are some key points to remember regarding the Override Rules feature: diff --git a/content/includes/nap-waf/config/common/ip-groups-override-rules.md b/content/includes/nap-waf/config/common/ip-groups-override-rules.md new file mode 100644 index 000000000..e9c2ff0f5 --- /dev/null +++ b/content/includes/nap-waf/config/common/ip-groups-override-rules.md @@ -0,0 +1,62 @@ +#### IP-Address-Lists feature as part of Override Rules feature. + +The Override Rules feature allows you to override original or parent policy settings. + +Rules are defined using specific conditions, which can include an IP Address Lists based on the declarative policy JSON schema. + +When triggered, the rule is applied to the _clientIp_ attribute using the _matches_ function. + +'clientIp.matches(ipAddressLists["standalone"])' + +Here is a policy example: + +```json +{ + "policy": { + "name": "ip_group_override_rule", + "template": { + "name": "POLICY_TEMPLATE_NGINX_BASE" + }, + "applicationLanguage": "utf-8", + "caseInsensitive": false, + "enforcementMode": "blocking", + "ip-address-lists": [ + { + "name": "standalone", + "ipAddresses": [ + { + "ipAddress": "1.1.1.1/32" + } + ] + } + ], + "override-rules": [ + { + "name": "myRule1", + "condition": "clientIp.matches(ipAddressLists['standalone'])", + "actionType": "extend-policy", + "override": { + "policy": { + "enforcementMode": "transparent" + } + } + } + ] + } +} +``` + +The previous example policy contains an IP address lists with the name "standalone", used for the override rule condition "clientIp.matches(ipAddressLists['standalone'])". +The condition means that the rule enforcement is applied and override base policy enforcement when clientIp is matched to one of ipAddresses in ipAddressList with name "standalone". +The value used for the override condition must exist and exactly match the name in "ip-address-lists". + +#### Possible errors + +| Error text | Input | Explanation | +| -----------| ------------- | ------------ | +| _Invalid field invalidList_ | _clientIp.matches(invalidList['standalone']);_ | An incorrect keyword was used instead of _ipAddressLists_ | +| _Invalid value empty string_ | _clientIp.matches(ipAddressLists['']_ | An empty name was provided | +| _Failed to compile policy - 'ipGroupOverridePolicy'_ | _uri.matches(ipAddressLists['standalone']);_ | Used _ipAddressLists_ without the _clientIP_ attribute | + + + diff --git a/content/includes/nap-waf/config/common/ip-groups-overview.md b/content/includes/nap-waf/config/common/ip-groups-overview.md new file mode 100644 index 000000000..d1729a7d0 --- /dev/null +++ b/content/includes/nap-waf/config/common/ip-groups-overview.md @@ -0,0 +1,81 @@ +IP address lists is a feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes. + +This allows you to control unique policy settings for incoming requests based on specific IP addresses. + +Each IP address list contains a unique name, enforcement type (_always_, _never_ and _policy-default_), and list of IP addresses. + + +Anβ€―example of a declarative policy using IP address lists configuration: + +```json +{ + "policy": { + "name": "IpGroups_policy", + "template": { + "name": "POLICY_TEMPLATE_NGINX_BASE" + }, + "applicationLanguage": "utf-8", + "caseInsensitive": false, + "enforcementMode": "blocking", + "ip-address-lists": [ + { + "name": "Standalone", + "description": "Optional Description", + "blockRequests": "policy-default", + "setGeolocation": "IN", + "ipAddresses": [ + { + "ipAddress": "1.2.3.4/32" + }, + { + "ipAddress": "1111:fc00:0:112::2" + } + ] + } + ] + } +} + +``` +The example with IP-Group definition in external file external_ip_groups.json: + +```json +{ + "policy": { + "name": "IpGroups_policy2", + "template": { + "name": "POLICY_TEMPLATE_NGINX_BASE" + }, + "applicationLanguage": "utf-8", + "caseInsensitive": false, + "enforcementMode": "blocking", + "ip-address-lists": [ + { + "name": "external_ip_groups", + "description": "Optional Description", + "blockRequests": "always", + "setGeolocation": "IL", + "$ref": "file:///tmp/policy/external_ip_groups.json" + } + ] + } +} +``` +Example of the file external_ip_groups.json + +```json +{ + "name": "External IP address lists", + "description": "Optional Description", + "blockRequests": "always", + "setGeolocation": "IR", + "ipAddresses": [ + { + "ipAddress": "66.51.41.21" + }, + { + "ipAddress": "66.52.42.22" + } + ] +} +``` diff --git a/content/includes/nap-waf/config/common/ip-intelligence-conf.md b/content/includes/nap-waf/config/common/ip-intelligence-conf.md new file mode 100644 index 000000000..094b42cb6 --- /dev/null +++ b/content/includes/nap-waf/config/common/ip-intelligence-conf.md @@ -0,0 +1,121 @@ + + +NGINX App Protect WAF provides an IP Intelligence feature, which allows customizing the enforcement based on the source IP of the request to limit access from IP addresses with questionable reputation. Please note that: +- The IP intelligence feature is **disabled** by default and needs to be installed, enabled, and configured within the policy. +- To review the installation steps, please refer to the administration guide: [App Protect v4]({{< ref "/nap-waf/v4/admin-guide/install.md#Prerequisites" >}}) / [App Protect v5]({{< ref "/nap-waf/v5/admin-guide/install.md#Prerequisites" >}}) +- The system must have an active Internet connection and a working DNS. +- If NGINX App Protect is behind a firewall, ensure external access to vector.brightcloud.com over port 443 - this is the IP Intelligence server used for data retrieval. +- If NGINX App Protect accesses the Internet through a forward proxy server, ensure that it is configured correctly [App Protect v4]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-forward-proxy-configuration" >}}) / [App Protect v5]({{< ref "/nap-waf/v5/configuration-guide/configuration.md##ip-intelligence-forward-proxy-configuration" >}}). + +Once installed, make sure to enable the feature in the two relevant sections of the policy: +1. By enabling the corresponding violation in the violation list: `"name": "VIOL_MALICIOUS_IP"` and assigning the appropriate `block` and `alarm` values to the violation. + +2. By enabling the feature in the corresponding IP Intelligence JSON section: `"ip-intelligence": {"enabled": true}` and defining actions for the IP Intelligence categories listed below. + +An example policy where both elements are enabled, and all the IP intelligence categories are configured to `block` and `alarm` can be found here: + +```json +{ + "policy": { + "name": "ip_intelligency_policy", + "template": { + "name": "POLICY_TEMPLATE_NGINX_BASE" + }, + "applicationLanguage": "utf-8", + "caseInsensitive": false, + "enforcementMode": "blocking", + "blocking-settings": { + "violations": [ + { + "name": "VIOL_MALICIOUS_IP", + "alarm": true, + "block": true + } + ] + }, + "ip-intelligence": { + "enabled": true, + "ipIntelligenceCategories": [ + { + "category": "Anonymous Proxy", + "alarm": true, + "block": true + }, + { + "category": "BotNets", + "alarm": true, + "block": true + }, + { + "category": "Cloud-based Services", + "alarm": true, + "block": true + }, + { + "category": "Denial of Service", + "alarm": true, + "block": true + }, + { + "category": "Infected Sources", + "alarm": true, + "block": true + }, + { + "category": "Mobile Threats", + "alarm": true, + "block": true + }, + { + "category": "Phishing Proxies", + "alarm": true, + "block": true + }, + { + "category": "Scanners", + "alarm": true, + "block": true + }, + { + "category": "Spam Sources", + "alarm": true, + "block": true + }, + { + "category": "Tor Proxies", + "alarm": true, + "block": true + }, + { + "category": "Web Attacks", + "alarm": true, + "block": true + }, + { + "category": "Windows Exploits", + "alarm": true, + "block": true + } + ] + } + } +} +``` + +This policy will basically block `"block": true` all IP addresses that are part of any threat category and add a log entry `"alarm": true` for the transaction. + +The IP address database is managed by an external provider and is constantly updated (every 1 minute by default). The database also categorizes IP addresses into one or more threat categories. These are the same categories that can be configured individually in the IP intelligence section: +- Anonymous Proxy +- BotNets +- Cloud-based Services +- Denial of Service +- Infected Sources +- Mobile Threats +- Phishing Proxies +- Scanners +- Spam Sources +- Tor Proxies +- Web Attacks +- Windows Exploits + +Note that since the IP address database is constantly updated, IP address enforcement is also expected to change. IP Addresses may be added, removed, or moved from one category to another based on the reported activity of the IP address. diff --git a/content/includes/nap-waf/config/common/json-web-token-overview.md b/content/includes/nap-waf/config/common/json-web-token-overview.md index 9e5ee5741..76cf116ba 100644 --- a/content/includes/nap-waf/config/common/json-web-token-overview.md +++ b/content/includes/nap-waf/config/common/json-web-token-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1550" +nd-docs: "DOCS-1550" --- JSON Web Token (JWT) is a compact and self-contained way to represent information between two parties in a JSON (JavaScript Object Notation) format and is commonly used for authentication and authorization. With NGINX App Protect now it is possible to control access to its application using JWT validation. NGINX App Protect WAF validates the authenticity and well-formedness of JWTs coming from a client, denying access to the service exclusively when the validation process fails. JWT is mainly used for API access. diff --git a/content/includes/nap-waf/config/common/json-web-tokens-attack-sigs.md b/content/includes/nap-waf/config/common/json-web-tokens-attack-sigs.md index 76e8255a2..4ad55d12e 100644 --- a/content/includes/nap-waf/config/common/json-web-tokens-attack-sigs.md +++ b/content/includes/nap-waf/config/common/json-web-tokens-attack-sigs.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1602" +nd-docs: "DOCS-1602" --- Attack signatures are detected within the JSON values of the token, i.e. the header and claims parts, but not on the digital signature part of the token. The detection of signatures, and specifically which signatures are recognized, depends on the configuration entity within the Policy. Typically, this configuration entity is the Authorization HTTP header or else, the header or parameter entity configured as the location of the token in the access profile. diff --git a/content/includes/nap-waf/config/common/json-web-tokens-other-references.md b/content/includes/nap-waf/config/common/json-web-tokens-other-references.md index e07b94a20..c79eb0dd0 100644 --- a/content/includes/nap-waf/config/common/json-web-tokens-other-references.md +++ b/content/includes/nap-waf/config/common/json-web-tokens-other-references.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1573" +nd-docs: "DOCS-1573" --- For more information about JSON Web Token (JWT) see below reference links: diff --git a/content/includes/nap-waf/config/common/json-web-tokens-violation-rating.md b/content/includes/nap-waf/config/common/json-web-tokens-violation-rating.md index f0ef872b8..67875b1b9 100644 --- a/content/includes/nap-waf/config/common/json-web-tokens-violation-rating.md +++ b/content/includes/nap-waf/config/common/json-web-tokens-violation-rating.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1584" +nd-docs: "DOCS-1584" --- The default violation rating is set to the level of **5** regardless of any violation. Any changes to these violation settings here will override the default settings. The details regarding logs will be recorded in the security log. All violations will be disabled on upgrade. diff --git a/content/includes/nap-waf/config/common/json-web-tokens-violations.md b/content/includes/nap-waf/config/common/json-web-tokens-violations.md index c161e93b4..b04d82780 100644 --- a/content/includes/nap-waf/config/common/json-web-tokens-violations.md +++ b/content/includes/nap-waf/config/common/json-web-tokens-violations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1594" +nd-docs: "DOCS-1594" --- NGINX App Protect WAF introduces three new violations specific to JWT: `VIOL_ACCESS_INVALID`, `VIOL_ACCESS_MISSING` and `VIOL_ACCESS_MALFORMED`. diff --git a/content/includes/nap-waf/config/common/modifying-configurations.md b/content/includes/nap-waf/config/common/modifying-configurations.md index 41341a7ad..557d97eae 100644 --- a/content/includes/nap-waf/config/common/modifying-configurations.md +++ b/content/includes/nap-waf/config/common/modifying-configurations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1591" +nd-docs: "DOCS-1591" --- What we have been seeing so far has been related to making changes by actually overriding specific configuration values. What would happen in the case we wanted to remove a specific configuration entity from the policy. For example, let's say we have added file types "aaa", "bbb", and "ccc", and now we wish to remove "bbb" from the list of disallowed file types. Deleting this entity from the declarative configuration file will simply mean that this entity will be left intact when the policy is rebuilt, meaning that the entity is still in the disallowed file types list. To resolve such situations, we have a `modifications` section where we can force modification where otherwise it is not possible using direct declarative configuration. diff --git a/content/includes/nap-waf/config/common/nginx-app-protect-waf-terminology.md b/content/includes/nap-waf/config/common/nginx-app-protect-waf-terminology.md index 54db35538..2630c54ec 100644 --- a/content/includes/nap-waf/config/common/nginx-app-protect-waf-terminology.md +++ b/content/includes/nap-waf/config/common/nginx-app-protect-waf-terminology.md @@ -1,5 +1,8 @@ --- -docs: "DOCS-1605" +nd-docs: "DOCS-1605" +files: + - content/nap-waf/v5/configuration-guide/configuration.md + - content/nginx-one/glossary.md --- This guide assumes that you have some familiarity with various Layer 7 (L7) Hypertext Transfer Protocol (HTTP) concepts, such as Uniform Resource Identifier (URI)/Uniform Resource Locator (URL), method, header, cookie, status code, request, response, and parameters. @@ -26,4 +29,4 @@ This guide assumes that you have some familiarity with various Layer 7 (L7) Hype |Tuning | Making manual changes to an existing security policy to reduce false positives and increase the policy’s security level. | |URI/URL | The Uniform Resource Identifier (URI) specifies the name of a web object in a request. A Uniform Resource Locator (URL) specifies the location of an object on the Internet. For example, in the web address, `http://www.siterequest.com/index.html`, index.html is the URI, and the URL is `http://www.siterequest.com/index.html`. In NGINX App Protect WAF, the terms URI and URL are used interchangeably. | |Violation | Violations occur when some aspect of a request or response does not comply with the security policy. You can configure the blocking settings for any violation in a security policy. When a violation occurs, the system can Alarm or Block a request (blocking is only available when the enforcement mode is set to Blocking). | -{{}} \ No newline at end of file +{{}} diff --git a/content/includes/nap-waf/config/common/override-rules-errors-warnings.md b/content/includes/nap-waf/config/common/override-rules-errors-warnings.md index d0795f339..cea216022 100644 --- a/content/includes/nap-waf/config/common/override-rules-errors-warnings.md +++ b/content/includes/nap-waf/config/common/override-rules-errors-warnings.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1600" +nd-docs: "DOCS-1600" --- #### Missing Policy Name diff --git a/content/includes/nap-waf/config/common/override-rules-logging-reporting.md b/content/includes/nap-waf/config/common/override-rules-logging-reporting.md index 814d95b17..250065b66 100644 --- a/content/includes/nap-waf/config/common/override-rules-logging-reporting.md +++ b/content/includes/nap-waf/config/common/override-rules-logging-reporting.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1583" +nd-docs: "DOCS-1583" --- If a request matches an override rule, the `json_log` field will include a new block named 'overrideRule'. However, if no rules match the request, the log will not contain any related information. When the 'actionType' flag is set to "replace-policy", the 'originalPolicyName' field in the log will reflect the name of the original policy name (the one that contains override rules), and the `policy_name` field will reflect the policy that was enforced. diff --git a/content/includes/nap-waf/config/common/override-rules-overview.md b/content/includes/nap-waf/config/common/override-rules-overview.md index d67e14240..59d547719 100644 --- a/content/includes/nap-waf/config/common/override-rules-overview.md +++ b/content/includes/nap-waf/config/common/override-rules-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1553" +nd-docs: "DOCS-1553" --- The **Override Rules** feature allows overriding of the **default policy** settings. Each override rule consists of a condition followed by changes to the original policy applied to requests that meet the respective condition. This feature provides the ability to include the override rules within a declarative policy such that all incoming requests are verified against those rules. diff --git a/content/includes/nap-waf/config/common/parameters-and-user-defined-urls.md b/content/includes/nap-waf/config/common/parameters-and-user-defined-urls.md index de4214a29..53aa7f98d 100644 --- a/content/includes/nap-waf/config/common/parameters-and-user-defined-urls.md +++ b/content/includes/nap-waf/config/common/parameters-and-user-defined-urls.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1618" +nd-docs: "DOCS-1618" --- When configuring handling of parameters, it is a bit different from other configurations we have dealt with earlier, where we enable a violation and configure its details. With parameters, there are a number of independent violations that need to be enabled on their own, as well as a parameter section to define further customization. The full list of parameter violations can be extracted from the above violation list. diff --git a/content/includes/nap-waf/config/common/partial-masking-of-data.md b/content/includes/nap-waf/config/common/partial-masking-of-data.md index 207e04921..86769895e 100644 --- a/content/includes/nap-waf/config/common/partial-masking-of-data.md +++ b/content/includes/nap-waf/config/common/partial-masking-of-data.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1559" +nd-docs: "DOCS-1559" --- Here is an example showing partial masking on custom patterns. Custom patterns are specified in `customPatternsList`, number of unmasked leading and trailing characters are defined in `firstCustomCharactersToExpose` and `lastCustomCharactersToExpose` parameters. diff --git a/content/includes/nap-waf/config/common/policy-authoring-and-tuning.md b/content/includes/nap-waf/config/common/policy-authoring-and-tuning.md index ca16dc85f..59d7b39cb 100644 --- a/content/includes/nap-waf/config/common/policy-authoring-and-tuning.md +++ b/content/includes/nap-waf/config/common/policy-authoring-and-tuning.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1564" +nd-docs: "DOCS-1564" --- The policy JSON file specifies the settings that are different from the base template, such as enabling more signatures, disabling some violations, adding server technologies, etc. These will be shown in the next sections. diff --git a/content/includes/nap-waf/config/common/policy-configuration.md b/content/includes/nap-waf/config/common/policy-configuration.md index 9ef118bdc..a58c4464e 100644 --- a/content/includes/nap-waf/config/common/policy-configuration.md +++ b/content/includes/nap-waf/config/common/policy-configuration.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1548" +nd-docs: "DOCS-1548" --- The NGINX App Protect WAF ships with two reference policies, both with a default enforcement mode set to Blocking: diff --git a/content/includes/nap-waf/config/common/protocol-buffers-supported-version.md b/content/includes/nap-waf/config/common/protocol-buffers-supported-version.md index c71632671..1e17edc7d 100644 --- a/content/includes/nap-waf/config/common/protocol-buffers-supported-version.md +++ b/content/includes/nap-waf/config/common/protocol-buffers-supported-version.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1598" +nd-docs: "DOCS-1598" --- The supported Protocol Buffer version is 3 i.e. only proto3 is supported. Version 2 is not supported. Hence any obsolete feature of version 2, such as message extensions in the IDL files, will be rejected. IDL files that have the `syntax = "proto2";` statement is also rejected. \ No newline at end of file diff --git a/content/includes/nap-waf/config/common/signature-sets-in-default-policy.md b/content/includes/nap-waf/config/common/signature-sets-in-default-policy.md index 0beb9f005..39fe22e09 100644 --- a/content/includes/nap-waf/config/common/signature-sets-in-default-policy.md +++ b/content/includes/nap-waf/config/common/signature-sets-in-default-policy.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1587" +nd-docs: "DOCS-1587" --- The following signature sets are included in the default policy. Most of the sets are defined by the Attack Type they protect from. In all sets the **Alarm** flag is enabled and **Block** disabled except High Accuracy Signatures, which are set to **blocked** (`block` parameter is enabled). diff --git a/content/includes/nap-waf/config/common/signature-sets.md b/content/includes/nap-waf/config/common/signature-sets.md index 4afb8fe65..fb07dca5e 100644 --- a/content/includes/nap-waf/config/common/signature-sets.md +++ b/content/includes/nap-waf/config/common/signature-sets.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1580" +nd-docs: "DOCS-1580" --- The default and strict policies include and enable common signature sets, which are categorized groups of [signatures](#attack-signatures-overview) applied to the policy. However, you may wish to modify the list of signature sets and their logging and enforcement settings via the `signature-sets` array property. There are several ways to configure the enforced signature sets. diff --git a/content/includes/nap-waf/config/common/signature-settings.md b/content/includes/nap-waf/config/common/signature-settings.md index 9f2121af7..39fff1ce4 100644 --- a/content/includes/nap-waf/config/common/signature-settings.md +++ b/content/includes/nap-waf/config/common/signature-settings.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1554" +nd-docs: "DOCS-1554" --- {{}} diff --git a/content/includes/nap-waf/config/common/supported-violations.md b/content/includes/nap-waf/config/common/supported-violations.md index bf1b4c882..7fcf200b5 100644 --- a/content/includes/nap-waf/config/common/supported-violations.md +++ b/content/includes/nap-waf/config/common/supported-violations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1582" +nd-docs: "DOCS-1582" --- The following violations are supported and can be enabled by turning on the **alarm** and/or **block** flags. @@ -31,39 +31,39 @@ The following violations are supported and can be enabled by turning on the **al |VIOL_GRAPHQL_FORMAT | GraphQL format data does not comply with format settings | Alarm & Block | This violation will be issued when the GraphQL profile settings are not satisfied, for example the length is too long, depth is too deep, a specific value is too long or too many batched queries.
The violation details will note what happened and the found length, depth or which value is too long and by what.
The depth violation is not learnable. The reason is that we don't know the actual depth of the query - we stop parsing at the max depth.
Note that the values will be used on the variables JSON part as well as the query. In a way, we can see these values as a JSON profile attributes just for the variables. | | |VIOL_GRAPHQL_INTROSPECTION_QUERY| GraphQL introspection Query | Alarm & Block | This violation will be issued when an introspection query was seen. | | |VIOL_GRAPHQL_ERROR_RESPONSE | GraphQL Error Response | Alarm & Block | GraphQL disallowed pattern in response. | | -|VIOL_GRPC_FORMAT | gRPC data does not comply with format settings | Alarm | The system checks that the request contains gRPC content and complies with the various request limits within the defense configuration in the security policy's gRPC Content Profile. Enforces valid gRPC requests and protects the server from Protocol Buffers parser attacks. This violation is generated when a gRPC request does not meet restrictive conditions in the gRPC Content Profile, such as the message length or existence of unknown fields. | | -|VIOL_GRPC_MALFORMED | Malformed gRPC data | Alarm & Block | The system checks that the request contains gRPC content that is well-formed. Enforces parsable gRPC requests. | | -|VIOL_GRPC_METHOD | Illegal gRPC method | Alarm | The system checks that the gRPC service method invoked matches one of the methods defined in the IDL file. The violation is triggered if the method does not appear there. | | -|VIOL_HEADER_LENGTH | Illegal header length | Alarm | The system checks that the request includes a total HTTP header length that does not exceed the length specified in the security policy. | The actual size in default policy is 4 KB | -|VIOL_HEADER_METACHAR | Illegal meta character in header | Alarm | The system checks that the values of all headers within the request only contain meta characters defined as allowed in the security policy. | | -|VIOL_HTTP_PROTOCOL | HTTP protocol compliance failed | Alarm | This category contains a list of validation checks that the system performs on HTTP requests to ensure that the requests are formatted properly. | | -|VIOL_HTTP_RESPONSE_STATUS | Illegal HTTP response status | Alarm | The server response contains an HTTP status code that is not defined as valid in the security policy. | | -|VIOL_JSON_FORMAT | JSON data does not comply with format settings | Alarm | The system checks that the request contains JSON content and complies with the various request limits within the defense configuration in the security policy's JSON profile. Enforces valid JSON requests and protects the server from JSON parser attacks. This violation is generated when a problem is detected in a JSON request, generally checking the message according to boundaries such as the message's size and meta characters in parameter value. | Controlled from the default JSON profile. | -|VIOL_JSON_MALFORMED | Malformed JSON data | Alarm & Block | The system checks that the request contains JSON content that is well-formed. Enforces parsable JSON requests. | | -|VIOL_JSON_SCHEMA | JSON data does not comply with JSON schema | Alarm | The system checks that the incoming request contains JSON data that matches the schema file that is part of a JSON profile configured in the security policy. Enforces proper JSON requests defined by the schema. | | -|VIOL_MANDATORY_PARAMETER | Mandatory parameter is missing | Alarm | The system checks that parameter marked as mandatory exists in the request. | | -|VIOL_MANDATORY_REQUEST_BODY | Mandatory request body is missing | Alarm | The system checks that the body exists in the request | | -|VIOL_METHOD | Illegal method | Alarm | The system checks that the request references an HTTP request method that is found in the security policy. Enforces desired HTTP methods; GET and POST are always allowed. | These HTTP methods are supported:
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS
| -|VIOL_PARAMETER | Illegal parameter | Alarm | The system checks that every parameter in the request is defined in the security policy. | | -|VIOL_PARAMETER_ARRAY_VALUE | Illegal parameter array value | Alarm | The value of an item in an array parameter is not according to the defined data type. | | -|VIOL_PARAMETER_DATA_TYPE | Illegal parameter data type | Alarm | The system checks that the request contains a parameter whose data type matches the data type defined in the security policy. The data types that this violation applies to are integer, email, and phone. | | -|VIOL_PARAMETER_EMPTY_VALUE | Illegal empty parameter value | Alarm | The system checks that the request contains a parameter whose value is not empty when it must contain a value. | | -|VIOL_PARAMETER_LOCATION | Illegal parameter location | Alarm | The parameter was found in a different location than it was configured in the policy. | | -|VIOL_PARAMETER_MULTIPART_NULL_VALUE | Null in multi-part parameter value | Disabled | The system checks that the multi-part request has a parameter value that does not contain the NULL character (0x00). If a multipart parameter with binary content type contains NULL in its value, the Enforcer issues this violation. The exceptions to this are:
  • If that parameter is configured in the policy as `Ignore value`.
  • If that parameter is configured in the security policy as `user-input file-upload`.
  • If the parameter has a content-type that contains the string 'XML' and the parameter value contains a valid UTF16 encoded XML document (the encoding is valid). In this case NULL is allowed as it is part of the UTF16 encoding.
| | -|VIOL_PARAMETER_NAME_METACHAR | Illegal meta character in parameter name | Alarm | The system checks that all parameter names within the incoming request only contain meta characters defined as allowed in the security policy. | | -|VIOL_PARAMETER_NUMERIC_VALUE | Illegal parameter numeric value | Alarm | The system checks that the incoming request contains a parameter whose value is in the range of decimal or integer values defined in the security policy. | | -|VIOL_PARAMETER_REPEATED | Illegal repeated parameter name | Alarm | Detected multiple parameters of the same name in a single HTTP request. | | -|VIOL_PARAMETER_STATIC_VALUE | Illegal static parameter value | Alarm | The system checks that the request contains a static parameter whose value is defined in the security policy. Prevents static parameter change. NGINX App Protect WAF can be configured to block parameter values that are not in a predefined list. Parameters can be defined on each of the following levels: file type, URL, and flow. Each parameter can be one of the following types: explicit or wildcard. | | -|VIOL_PARAMETER_VALUE_BASE64 | Illegal Base64 value | Alarm | The system checks that the value is a valid Base64 string. If the value is indeed Base64, the system decodes this value and continues with its security checks. | | -|VIOL_PARAMETER_VALUE_LENGTH | Illegal parameter value length | Alarm | The system checks that the request contains a parameter whose value length (in bytes) matches the value length defined in the security policy. | | -|VIOL_PARAMETER_VALUE_METACHAR | Illegal meta character in value | Alarm | The system checks that all parameter values, XML element/attribute values, or JSON values within the request only contain meta characters defined as allowed in the security policy. Enforces proper input values. In case of a violation, the reported value represents the decimal ASCII value (metachar_index), or, in case of using "json_log" the hexadecimal ASCII value (metachar) of the violating character. | | -|VIOL_PARAMETER_VALUE_REGEXP | Parameter value does not comply with regular expression | Alarm | The system checks that the request contains an alphanumeric parameter value that matches the expected pattern specified by the regular-expression field for that parameter. Prevents HTTP requests which do not comply with a defined pattern. NGINX App Protect WAF lets you set up a regular expression to block requests where a parameter value does not match the regular expression. | | -|VIOL_POST_DATA_LENGTH | Illegal POST data length | Alarm | The system checks that the request contains POST data whose length does not exceed the acceptable length specified in the security policy. | In * file type entity. This check is disabled by default. | -|VIOL_QUERY_STRING_LENGTH | Illegal query string length | Alarm | The system checks that the request contains a query string whose length does not exceed the acceptable length specified in the security policy. | In * file type entity. Actual size is 2 KB. | -|VIOL_RATING_THREAT | Request is likely a threat | Alarm & Block | The combination of violations in this request determined that the request is likely to be a threat. | For VR = 4 or 5 | -|VIOL_RATING_NEED_EXAMINATION | Request needs further examination | Disabled | The combination of violations could not determine whether the request is a threat or violations are false positives thus requiring more examination. | For VR = 3 | -|VIOL_REQUEST_LENGTH | Illegal request length | Alarm | The system checks that the request length does not exceed the acceptable length specified in the security policy per the requested file type. | In * file type entity. This check is disabled by default. | -|VIOL_REQUEST_MAX_LENGTH | Request length exceeds defined buffer size | Alarm & Block| The system checks that the request length is not larger than the maximum memory buffer size. Note that this protects NGINX App Protect WAF from consuming too much memory across all security policies which are active on the device. | Default is 10MB | +|VIOL_GRPC_FORMAT | gRPC data does not comply with format settings | Alarm | The system checks that the request contains gRPC content and complies with the various request limits within the defense configuration in the security policy's gRPC Content Profile. Enforces valid gRPC requests and protects the server from Protocol Buffers parser attacks. This violation is generated when a gRPC request does not meet restrictive conditions in the gRPC Content Profile, such as the message length or existence of unknown fields. | | +|VIOL_GRPC_MALFORMED | Malformed gRPC data | Alarm & Block | The system checks that the request contains gRPC content that is well-formed. Enforces parsable gRPC requests. | | +|VIOL_GRPC_METHOD | Illegal gRPC method | Alarm | The system checks that the gRPC service method invoked matches one of the methods defined in the IDL file. The violation is triggered if the method does not appear there. | | +|VIOL_HEADER_LENGTH | Illegal header length | Alarm | The system checks that the request includes a total HTTP header length that does not exceed the length specified in the security policy. | The actual size in default policy is 4 KB | +|VIOL_HEADER_METACHAR | Illegal meta character in header | Alarm | The system checks that the values of all headers within the request only contain meta characters defined as allowed in the security policy. | | +|VIOL_HTTP_PROTOCOL | HTTP protocol compliance failed | Alarm | This category contains a list of validation checks that the system performs on HTTP requests to ensure that the requests are formatted properly. | | +|VIOL_HTTP_RESPONSE_STATUS | Illegal HTTP response status | Alarm | The server response contains an HTTP status code that is not defined as valid in the security policy. | | +|VIOL_JSON_FORMAT | JSON data does not comply with format settings | Alarm | The system checks that the request contains JSON content and complies with the various request limits within the defense configuration in the security policy's JSON profile. Enforces valid JSON requests and protects the server from JSON parser attacks. This violation is generated when a problem is detected in a JSON request, generally checking the message according to boundaries such as the message's size and meta characters in parameter value. | Controlled from the default JSON profile. | +|VIOL_JSON_MALFORMED | Malformed JSON data | Alarm & Block | The system checks that the request contains JSON content that is well-formed. Enforces parsable JSON requests. | | +|VIOL_JSON_SCHEMA | JSON data does not comply with JSON schema | Alarm | The system checks that the incoming request contains JSON data that matches the schema file that is part of a JSON profile configured in the security policy. Enforces proper JSON requests defined by the schema. | | +|VIOL_MANDATORY_PARAMETER | Mandatory parameter is missing | Alarm | The system checks that parameter marked as mandatory exists in the request. | | +|VIOL_MANDATORY_REQUEST_BODY | Mandatory request body is missing | Alarm | The system checks that the body exists in the request | | +|VIOL_METHOD | Illegal method | Alarm | The system checks that the request references an HTTP request method that is found in the security policy. Enforces desired HTTP methods; GET and POST are always allowed. | These HTTP methods are supported:
  • GET
  • HEAD
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS
| +|VIOL_PARAMETER | Illegal parameter | Alarm | The system checks that every parameter in the request is defined in the security policy. | | +|VIOL_PARAMETER_ARRAY_VALUE | Illegal parameter array value | Alarm | The value of an item in an array parameter is not according to the defined data type. | | +|VIOL_PARAMETER_DATA_TYPE | Illegal parameter data type | Alarm | The system checks that the request contains a parameter whose data type matches the data type defined in the security policy. The data types that this violation applies to are integer, email, and phone. | | +|VIOL_PARAMETER_EMPTY_VALUE | Illegal empty parameter value | Alarm | The system checks that the request contains a parameter whose value is not empty when it must contain a value. | | +|VIOL_PARAMETER_LOCATION | Illegal parameter location | Alarm | The parameter was found in a different location than it was configured in the policy. | | +|VIOL_PARAMETER_MULTIPART_NULL_VALUE | Null in multi-part parameter value | Disabled | The system checks that the multi-part request has a parameter value that does not contain the NULL character (0x00). If a multipart parameter with binary content type contains NULL in its value, the Enforcer issues this violation. The exceptions to this are:
  • If that parameter is configured in the policy as `Ignore value`.
  • If that parameter is configured in the security policy as `user-input file-upload`.
  • If the parameter has a content-type that contains the string 'XML' and the parameter value contains a valid UTF16 encoded XML document (the encoding is valid). In this case NULL is allowed as it is part of the UTF16 encoding.
| | +|VIOL_PARAMETER_NAME_METACHAR | Illegal meta character in parameter name | Alarm | The system checks that all parameter names within the incoming request only contain meta characters defined as allowed in the security policy. | | +|VIOL_PARAMETER_NUMERIC_VALUE | Illegal parameter numeric value | Alarm | The system checks that the incoming request contains a parameter whose value is in the range of decimal or integer values defined in the security policy. | | +|VIOL_PARAMETER_REPEATED | Illegal repeated parameter name | Alarm | Detected multiple parameters of the same name in a single HTTP request. | | +|VIOL_PARAMETER_STATIC_VALUE | Illegal static parameter value | Alarm | The system checks that the request contains a static parameter whose value is defined in the security policy. Prevents static parameter change. NGINX App Protect WAF can be configured to block parameter values that are not in a predefined list. Parameters can be defined on each of the following levels: file type, URL, and flow. Each parameter can be one of the following types: explicit or wildcard. | | +|VIOL_PARAMETER_VALUE_BASE64 | Illegal Base64 value | Alarm | The system checks that the value is a valid Base64 string. If the value is indeed Base64, the system decodes this value and continues with its security checks. | | +|VIOL_PARAMETER_VALUE_LENGTH | Illegal parameter value length | Alarm | The system checks that the request contains a parameter whose value length (in bytes) matches the value length defined in the security policy. | | +|VIOL_PARAMETER_VALUE_METACHAR | Illegal meta character in value | Alarm | The system checks that all parameter values, XML element/attribute values, or JSON values within the request only contain meta characters defined as allowed in the security policy. Enforces proper input values. In case of a violation, the reported value represents the decimal ASCII value (metachar_index), or, in case of using "json_log" the hexadecimal ASCII value (metachar) of the violating character. | | +|VIOL_PARAMETER_VALUE_REGEXP | Parameter value does not comply with regular expression | Alarm | The system checks that the request contains an alphanumeric parameter value that matches the expected pattern specified by the regular-expression field for that parameter. Prevents HTTP requests which do not comply with a defined pattern. NGINX App Protect WAF lets you set up a regular expression to block requests where a parameter value does not match the regular expression. | | +|VIOL_POST_DATA_LENGTH | Illegal POST data length | Alarm | The system checks that the request contains POST data whose length does not exceed the acceptable length specified in the security policy. | In * file type entity. This check is disabled by default. | +|VIOL_QUERY_STRING_LENGTH | Illegal query string length | Alarm | The system checks that the request contains a query string whose length does not exceed the acceptable length specified in the security policy. | In * file type entity. Actual size is 2 KB. | +|VIOL_RATING_THREAT | Request is likely a threat | Alarm & Block | The combination of violations in this request determined that the request is likely to be a threat. | For VR = 4 or 5 | +|VIOL_RATING_NEED_EXAMINATION | Request needs further examination | Disabled | The combination of violations could not determine whether the request is a threat or violations are false positives thus requiring more examination. | For VR = 3 | +|VIOL_REQUEST_LENGTH | Illegal request length | Alarm | The system checks that the request length does not exceed the acceptable length specified in the security policy per the requested file type. | In * file type entity. This check is disabled by default. | +|VIOL_REQUEST_MAX_LENGTH | Request length exceeds defined buffer size | Alarm & Block| The system checks that the request length is not larger than the maximum memory buffer size. Note that this protects NGINX App Protect WAF from consuming too much memory across all security policies which are active on the device. | Default is 10MB | |VIOL_RULE | Actionable override rule was triggered. | Disabled |A policy override rule with an action was triggered.| | |VIOL_THREAT_CAMPAIGN | Threat Campaign detected | Alarm & Block | The system examines the HTTP message for known threat campaigns by matching it against known attack patterns. | | |VIOL_URL | Illegal URL | Alarm | The system checks that the requested URL is configured as a valid URL, or not configured as an invalid URL, within the security policy. | | diff --git a/content/includes/nap-waf/config/common/time-based-sig-config.md b/content/includes/nap-waf/config/common/time-based-sig-config.md index 1c636970c..6c5427e39 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-config.md +++ b/content/includes/nap-waf/config/common/time-based-sig-config.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1491 +nd-docs: DOCS-1491 --- A new property known as `stagingCertificationDatetime` is added to `signature-settings` section. All signatures that were created or modified in a signature update that is later than that time are in staging while all the rest are enforced and not in staging. diff --git a/content/includes/nap-waf/config/common/time-based-sig-enforce-mod-sig.md b/content/includes/nap-waf/config/common/time-based-sig-enforce-mod-sig.md index f7994084d..cfd8d0534 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-enforce-mod-sig.md +++ b/content/includes/nap-waf/config/common/time-based-sig-enforce-mod-sig.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1495 +nd-docs: DOCS-1495 --- All signatures are considered to be in staging if their creation or modification time is later than the `stagingCertificationDatetime`. diff --git a/content/includes/nap-waf/config/common/time-based-sig-latest-cert-time.md b/content/includes/nap-waf/config/common/time-based-sig-latest-cert-time.md index 8e4841a36..01af06ac1 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-latest-cert-time.md +++ b/content/includes/nap-waf/config/common/time-based-sig-latest-cert-time.md @@ -1,9 +1,9 @@ --- -docs: DOCS-1490 +nd-docs: DOCS-1490 --- The latest signatures certification time is the timestamp (in date-time ISO format) as the time the signatures in the policy are considered as β€œtrusted” by the user and separates enforced signatures from signatures in staging. -When this value is not defined and the staging flag is enabled, it means that all the signatures in the policy are in staging. If the signature was added to the policy but was created and last modified before the certification date-time then it will not be in staging. +When this value is not defined and the staging flag is enabled, it means that all the signatures in the policy are in staging. If the signature was added to the policy but was created and last modified before the certification date-time then it will not be in staging. A signature is considered new if it was introduced by a recent signature update that was applied to the respective policy. Note that signatures that were added later to the policy (by adding a new signature set) are not considered new unless they were added in the recent signature update. These signatures will not be in staging. \ No newline at end of file diff --git a/content/includes/nap-waf/config/common/time-based-sig-log-report.md b/content/includes/nap-waf/config/common/time-based-sig-log-report.md index b340c819e..bd7711a9b 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-log-report.md +++ b/content/includes/nap-waf/config/common/time-based-sig-log-report.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1494 +nd-docs: DOCS-1494 --- Time-based Signature will be logged and reported in the Security log without blocking the request as discussed in the above section. @@ -7,7 +7,7 @@ Time-based Signature will be logged and reported in the Security log without blo Security log will have the following new fields under the enforcementState: - The Violation Rating if there was no staging - `ratingIncludingViolationsInStaging` - The `stagingCertificationDatetime` from the policy -- The specific staging state of the signature +- The specific staging state of the signature - The `lastUpdateTime` of the signature - for the user to be able to determine why the signature was (or was not) in staging. ```json diff --git a/content/includes/nap-waf/config/common/time-based-sig-new-policy.md b/content/includes/nap-waf/config/common/time-based-sig-new-policy.md index b1ec698a5..23a19ee97 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-new-policy.md +++ b/content/includes/nap-waf/config/common/time-based-sig-new-policy.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1493 +nd-docs: DOCS-1493 --- When a new policy is deployed, the user prefers to have all its signatures present in the staging environment. To facilitate this, the `performStaging` flag is configured to true at the signature settings level. \ No newline at end of file diff --git a/content/includes/nap-waf/config/common/time-based-sig-overview.md b/content/includes/nap-waf/config/common/time-based-sig-overview.md index 30970d3ba..e3b89949f 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-overview.md +++ b/content/includes/nap-waf/config/common/time-based-sig-overview.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1498 +nd-docs: DOCS-1498 --- When new attack signatures are introduced in an App Protect policy, the policy is tested in a staging environment first before being promoted to production. However, in some instances where it is challenging to replicate real traffic accurately in the staging environment, the detection of genuine attacks becomes difficult. There can be false positives and expose the application to attacks. For such cases, we need to deploy the new signatures in staging environment in β€œstaging” mode. diff --git a/content/includes/nap-waf/config/common/time-based-sig-update-sig.md b/content/includes/nap-waf/config/common/time-based-sig-update-sig.md index 557b2ec5a..191dfdc52 100644 --- a/content/includes/nap-waf/config/common/time-based-sig-update-sig.md +++ b/content/includes/nap-waf/config/common/time-based-sig-update-sig.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1492 +nd-docs: DOCS-1492 --- After applying a signature update (F5 or user-defined), and assuming the update creation time is later than the previous signature update applied to the policy (in other words, the signatures are upgraded, not downgraded), then all the signatures that were affected by the update (created or modified) are automatically put in staging. That's because their modification time is newer than the current `stagingCertificationDatetime`. Signatures that were not affected by the update will **not** be in staging. \ No newline at end of file diff --git a/content/includes/nap-waf/config/common/types-of-openapi-references.md b/content/includes/nap-waf/config/common/types-of-openapi-references.md index c04f0c2c2..8316e15fc 100644 --- a/content/includes/nap-waf/config/common/types-of-openapi-references.md +++ b/content/includes/nap-waf/config/common/types-of-openapi-references.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1636" +nd-docs: "DOCS-1636" --- There are different ways of referencing OpenAPI Specification files. The configuration is similar to [External References](#external-references). diff --git a/content/includes/nap-waf/config/common/types-of-references.md b/content/includes/nap-waf/config/common/types-of-references.md index 44c116c73..dfc5403c3 100644 --- a/content/includes/nap-waf/config/common/types-of-references.md +++ b/content/includes/nap-waf/config/common/types-of-references.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1601" +nd-docs: "DOCS-1601" --- There are different implementations based on the type of references that are being made. diff --git a/content/includes/nap-waf/config/common/unsupported-configuration.md b/content/includes/nap-waf/config/common/unsupported-configuration.md index edc358d1d..b378143df 100644 --- a/content/includes/nap-waf/config/common/unsupported-configuration.md +++ b/content/includes/nap-waf/config/common/unsupported-configuration.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1569" +nd-docs: "DOCS-1569" --- There are some NGINX features that don't work well with NGINX App Protect WAF. Modules that use subrequest do not work when calling or being called from a scope that contains `app_protect_enable on`. Other modules that expect to receive the Range header (Slice for example) are also unsupported in the same scope as `app_protect_enable on`. For example, the following configuration is unsupported, but in the examples above you can find examples of work arounds for these features. diff --git a/content/includes/nap-waf/config/common/user-defined-browser-control.md b/content/includes/nap-waf/config/common/user-defined-browser-control.md index 788ee9d8a..90ffce2c3 100644 --- a/content/includes/nap-waf/config/common/user-defined-browser-control.md +++ b/content/includes/nap-waf/config/common/user-defined-browser-control.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1543" +nd-docs: "DOCS-1543" --- The User-Defined Browser Control feature allows a user to define new custom browsers, and create a list of allowed or disallowed browsers (both user-defined and factory preset browsers) used by the client application. It mainly provides the opportunity: diff --git a/content/includes/nap-waf/config/common/user-defined-signature-sets.md b/content/includes/nap-waf/config/common/user-defined-signature-sets.md index 230bcb52f..f9c2f0a76 100644 --- a/content/includes/nap-waf/config/common/user-defined-signature-sets.md +++ b/content/includes/nap-waf/config/common/user-defined-signature-sets.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1596" +nd-docs: "DOCS-1596" --- NGINX App Protect WAF comes with pre-defined signatures and signature sets. Also, the user can create their own user-defined signatures (as we have seen above) as well as user-defined signature sets. User-defined Signature sets are suitable for organizing the sheer number of pre-defined and user-defined signatures into logical sets for better use in the policy. For pre-defined signatures, there are two ways of managing signature sets: manual addition of signatures using the signature unique IDs, or filtering signatures based on specific criteria, like request/response, risk level, accuracy level, attack type, systems, etc. For the user-defined signatures, signature IDs are automatically generated, and they cannot be used in manual addition of signatures. Therefore, only one way is possible: filtering based on tag, request/response, risk level, accuracy level, attack type, systems, etc. diff --git a/content/includes/nap-waf/config/common/user-defined-signatures.md b/content/includes/nap-waf/config/common/user-defined-signatures.md index 98c3dc4dc..f98ad16dd 100644 --- a/content/includes/nap-waf/config/common/user-defined-signatures.md +++ b/content/includes/nap-waf/config/common/user-defined-signatures.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1603" +nd-docs: "DOCS-1603" --- Another useful expansion to the customization capabilities is the ability to create user-defined signatures. This capability allows the user to define new signatures, configure how they behave in terms of enforcement, and categorize them in user-defined signature sets (using tags) for ease of management. diff --git a/content/includes/nap-waf/config/common/violations.md b/content/includes/nap-waf/config/common/violations.md index 38ddf9b57..7feaabc9d 100644 --- a/content/includes/nap-waf/config/common/violations.md +++ b/content/includes/nap-waf/config/common/violations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1577" +nd-docs: "DOCS-1577" --- App Protect violations are rated by the App Protect algorithms to help distinguish between attacks and potential false positive alerts. A violation rating is a numerical rating that our algorithms give to requests based on the presence of violation(s). Each violation type and severity contributes to the calculation of the final rating. The final rating then defines the action taken for the specific request. As per the default policy, any violation rating of 1, 2 and 3 will not cause the request to be blocked and only a log will be generated with **alerted** status. If the violation rating is 4 or 5, the request is blocked: a blocking page is displayed and a log generated for the transaction with **blocked** status. Violation ratings are displayed in the logs by default. \ No newline at end of file diff --git a/content/includes/nap-waf/config/v5/build-nginx-image-oss/build-rocky.md b/content/includes/nap-waf/config/v5/build-nginx-image-oss/build-rocky.md new file mode 100644 index 000000000..00f2fcd65 --- /dev/null +++ b/content/includes/nap-waf/config/v5/build-nginx-image-oss/build-rocky.md @@ -0,0 +1,41 @@ +```dockerfile +# syntax=docker/dockerfile:1 + +# Base Image +FROM rockylinux:9 + +# Install NGINX OSS and NGINX App Protect WAF v5 module +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf -y install wget ca-certificates yum-utils \ + && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \ + && echo "[nginx-mainline]" > /etc/yum.repos.d/nginx.repo \ + && echo "name=nginx mainline repo" >> /etc/yum.repos.d/nginx.repo \ + && echo "baseurl=http://nginx.org/packages/mainline/centos/\$releasever/\$basearch/" >> /etc/yum.repos.d/nginx.repo \ + && echo "gpgcheck=1" >> /etc/yum.repos.d/nginx.repo \ + && echo "enabled=1" >> /etc/yum.repos.d/nginx.repo \ + && echo "gpgkey=https://nginx.org/keys/nginx_signing.key" >> /etc/yum.repos.d/nginx.repo \ + && echo "module_hotfixes=true" >> /etc/yum.repos.d/nginx.repo \ + && echo "[app-protect-x-oss]" > /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "name=nginx-app-protect repo" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "baseurl=https://pkgs.nginx.com/app-protect-x-oss/centos/${UBI_VERSION}/\$basearch/" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "sslclientcert=/etc/ssl/nginx/nginx-repo.crt" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "sslclientkey=/etc/ssl/nginx/nginx-repo.key" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "gpgcheck=0" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && echo "enabled=1" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-oss.repo \ + && dnf clean all \ + && dnf install -y app-protect-module-oss \ + && dnf clean all \ + && rm -rf /var/cache/dnf \ + && ln -sf /dev/stdout /var/log/nginx/access.log \ + && ln -sf /dev/stderr /var/log/nginx/error.log + +# Expose port +EXPOSE 80 + +# Define stop signal +STOPSIGNAL SIGQUIT + +# Set default command +CMD ["nginx", "-g", "daemon off;"] +``` diff --git a/content/includes/nap-waf/config/v5/build-nginx-image-plus/build-rocky.md b/content/includes/nap-waf/config/v5/build-nginx-image-plus/build-rocky.md new file mode 100644 index 000000000..e0362cd74 --- /dev/null +++ b/content/includes/nap-waf/config/v5/build-nginx-image-plus/build-rocky.md @@ -0,0 +1,35 @@ +```dockerfile +# syntax=docker/dockerfile:1 + +# Base Image +FROM rockylinux:9 + +# Install NGINX Plus and NGINX App Protect WAF v5 module +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf -y install wget ca-certificates \ + && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \ + && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/${NGINX_PLUS_REPO} \ + && echo "[app-protect-x-plus]" > /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "name=nginx-app-protect repo" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "baseurl=https://pkgs.nginx.com/app-protect-x-plus/centos/${UBI_VERSION}/\$basearch/" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "sslclientcert=/etc/ssl/nginx/nginx-repo.crt" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "sslclientkey=/etc/ssl/nginx/nginx-repo.key" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "gpgcheck=0" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && echo "enabled=1" >> /etc/yum.repos.d/app-protect-${UBI_VERSION}-x-plus.repo \ + && dnf clean all \ + && dnf install -y app-protect-module-plus \ + && dnf clean all \ + && rm -rf /var/cache/dnf \ + && ln -sf /dev/stdout /var/log/nginx/access.log \ + && ln -sf /dev/stderr /var/log/nginx/error.log + +# Expose port +EXPOSE 80 + +# Define stop signal +STOPSIGNAL SIGQUIT + +# Set default command +CMD ["nginx", "-g", "daemon off;"] +``` diff --git a/content/includes/nap-waf/default-conf-hostname.md b/content/includes/nap-waf/default-conf-hostname.md index 406d6b92e..9dc5316fb 100644 --- a/content/includes/nap-waf/default-conf-hostname.md +++ b/content/includes/nap-waf/default-conf-hostname.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1514" +nd-docs: "DOCS-1514" --- ```nginx diff --git a/content/includes/nap-waf/default-conf-localhost.md b/content/includes/nap-waf/default-conf-localhost.md index 24d2fb837..070afb43a 100644 --- a/content/includes/nap-waf/default-conf-localhost.md +++ b/content/includes/nap-waf/default-conf-localhost.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1515" +nd-docs: "DOCS-1515" --- ```nginx diff --git a/content/includes/nap-waf/download-certificates.md b/content/includes/nap-waf/download-certificates.md index 16dd460a0..f4d83ff12 100644 --- a/content/includes/nap-waf/download-certificates.md +++ b/content/includes/nap-waf/download-certificates.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1517" +nd-docs: "DOCS-1517" --- Log in to [My F5](https://my.f5.com) and download the following two files from your active NGINX App Protect WAF subscription: diff --git a/content/includes/nap-waf/how-to/bidirectional-configuration.md b/content/includes/nap-waf/how-to/bidirectional-configuration.md index f9db4a918..8ef9c6dd6 100644 --- a/content/includes/nap-waf/how-to/bidirectional-configuration.md +++ b/content/includes/nap-waf/how-to/bidirectional-configuration.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- The only configuration related to streaming is the IDL file or more specifically the `rpc` declaration. The keyword `stream` indicates that the message on the respective side is streaming.

For example: diff --git a/content/includes/nap-waf/ip-intelligence.md b/content/includes/nap-waf/ip-intelligence.md new file mode 100644 index 000000000..31f173479 --- /dev/null +++ b/content/includes/nap-waf/ip-intelligence.md @@ -0,0 +1,67 @@ +If the deployment intends to use the IP intelligence Feature (available from version 5.7.0), then the IP intelligence container needs to be added to the deployment in the docker compose file. + +Modify the original `docker-compose.yml` file to include the additional IP Intelligence container: + +```yaml +services: + waf-enforcer: + container_name: waf-enforcer + image: private-registry.nginx.com/nap/waf-enforcer:5.7.0 + environment: + - ENFORCER_PORT=50000 + ports: + - "50000:50000" + volumes: + - /opt/app_protect/bd_config:/opt/app_protect/bd_config + - /var/IpRep:/var/IpRep + networks: + - waf_network + restart: always + user: "101:101" + depends_on: + - waf-ip-intelligence + + waf-config-mgr: + container_name: waf-config-mgr + image: private-registry.nginx.com/nap/waf-config-mgr:5.7.0 + volumes: + - /opt/app_protect/bd_config:/opt/app_protect/bd_config + - /opt/app_protect/config:/opt/app_protect/config + - /etc/app_protect/conf:/etc/app_protect/conf + restart: always + user: "101:101" + network_mode: none + depends_on: + waf-enforcer: + condition: service_started + + waf-ip-intelligence: + container_name: waf-ip-intelligence + image: private-registry.nginx.com/nap/waf-ip-intelligence:5.7.0 + volumes: + - /var/IpRep:/var/IpRep + networks: + - waf_network + restart: always + user: "101:101" + +networks: + waf_network: + driver: bridge +``` + +Notes: +- Replace `waf-config-mgr`, `waf-enforcer` and `waf-ip-intelligence` tags with the actual release version tag you are deploying. We are using version 5.7.0 for this example deployment. +- By default, the containers `waf-config-mgr`, `waf-enforcer` and `waf-ip-intelligence` operate with the user and group IDs set to 101:101. Ensure that the folders and files are accessible to these IDs. + +Before creating the deployment in docker compose, create the required directories: + +```shell +sudo mkdir -p /opt/app_protect/config /opt/app_protect/bd_config /var/IpRep +``` + +Then set correct ownership: + +```shell +sudo chown -R 101:101 /opt/app_protect/ /var/IpRep +``` diff --git a/content/includes/nap-waf/nginx-conf-hostname-docker.md b/content/includes/nap-waf/nginx-conf-hostname-docker.md index f4e4dea4b..301738d44 100644 --- a/content/includes/nap-waf/nginx-conf-hostname-docker.md +++ b/content/includes/nap-waf/nginx-conf-hostname-docker.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1516" +nd-docs: "DOCS-1516" --- ```nginx diff --git a/content/includes/nap-waf/nginx-conf-localhost.md b/content/includes/nap-waf/nginx-conf-localhost.md index a87a5b16a..018bcba33 100644 --- a/content/includes/nap-waf/nginx-conf-localhost.md +++ b/content/includes/nap-waf/nginx-conf-localhost.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1518" +nd-docs: "DOCS-1518" --- ```nginx diff --git a/content/includes/nap-waf/policy.html b/content/includes/nap-waf/policy.html index de530f555..0d84e0c67 100644 --- a/content/includes/nap-waf/policy.html +++ b/content/includes/nap-waf/policy.html @@ -270,153 +270,160 @@

policy

+ip-intelligence +Yes +object + + + + json-profiles Yes array of objects - + json-validation-files Yes array of objects - + login-enforcement Yes object - + login-pages Yes array of objects A login page is a URL in a web application that requests must pass through to get to the authenticated URLs. Use login pages, for example, to prevent forceful browsing of restricted parts of the web application, by defining access permissions for users. Login pages also allow session tracking of user sessions. - + methods Yes array of objects - + name No string The unique user-given name of the policy. Policy names cannot contain spaces or special characters. Allowed characters are a-z, A-Z, 0-9, dot, dash (-), colon (:) and underscore (_). - + open-api-files Yes array of objects - + override-rules Yes array of objects This section defines policy override rules. - + parameters Yes array of objects This section defines parameters that the security policy permits in requests. - + performStaging No boolean Determines staging handling for all applicable entities in the policy, such as signatures, URLs, parameters, and cookies. If disabled, all entities will be enforced and any violations triggered will be considered illegal. - + response-pages Yes array of objects The Security Policy has a default blocking response page that it returns to the client when the client request, or the web server response, is blocked by the security policy. You can change the way the system responds to blocked requests. All default response pages contain a variable, <%TS.request.ID()%>, that the system replaces with a support ID number when it issues the page. - + sensitive-parameters Yes array of objects This section defines sensitive parameters. The contents of these parameters are not visible in logs nor in the user interfaces. Instead of actual values a string of asterisks is shown for these parameters. Use these parameters to protect sensitive user input, such as a password or a credit card number, in a validated request. A parameter name of "password" is always defined as sensitive by default. - + server-technologies Yes array of objects The server technology is a server-side application, framework, web server or operating system type that is configured in the policy in order to adapt the policy to the checks needed for the respective technology. - + signature-requirements Yes array of objects - + signature-sets Yes array of objects Defines behavior when signatures found within a signature-set are detected in a request. Settings are culmulative, so if a signature is found in any set with block enabled, that signature will have block enabled. - + signature-settings Yes object - + signatures Yes array of objects This section defines the properties of a signature on the policy. - + template Yes object Specifies the template to populate the default attributes of a new policy. - + threat-campaigns Yes array of objects This section defines the enforcement state for the threat campaigns in the security policy. - + urls Yes array of objects In a security policy, you can manually specify the HTTP URLs that are allowed (or disallowed) in traffic to the web application being protected. When you create a security policy, wildcard URLs of * (representing all HTTP URLs) are added to the Allowed HTTP URLs lists. - + wafEngineVersion No string - + xml-profiles Yes array of objects @@ -2849,13 +2856,13 @@

ip-address-lists

Specifies how the system responds to blocking requests sent from this IP address list.
    -
  • Policy Default: Specifies that the Policy Blocking Settings will be used for requests from this IP address list.
    • +
  • Policy Default: Specifies that the policy enforcementMode will be used for requests from this IP address list.
  • Never Block: Specifies that the system does not block requests sent from this IP address list, even if your security policy is configured to block all traffic.
  • Always Block: Specifies that the system blocks requests sent from this IP address list.
-

Optional

+

Optional, if absent Policy Default is used.

  • always
  • never
    • @@ -2871,13 +2878,13 @@

    ip-address-lists

    ipAddresses array of objects -Specifies the IP addresses. +Specifies the IP addresses. Use CIDR notation for subnet definition. matchOrder integer -Specifies the order index for IP Address List matching. If unspecified, the order is implicitly as the lists appear in the policy. IP Address Groups with a lower matchOrder will be checked for a match prior to items with higher matchOrder. +Specifies the order matching index between different IP Address Lists. If unspecified, the order is implicitly as the lists appear in the policy. IP Address Lists with a lower matchOrder will be checked for a match prior to items with higher matchOrder. @@ -2889,13 +2896,13 @@

    ip-address-lists

    neverLogRequests boolean -Specifies when enabled that the system does not log requests or responses sent from this IP address list, even if the traffic is illegal, and even if your security policy is configured to log all traffic. +Specifies when enabled that the system does not log requests or responses sent from this IP address list, even if the traffic is illegal, and even if your security policy is configured to log all traffic. Optional, if absent default value is false. setGeolocation string -Specifies a geolocation to be associated for this IP address list. Optional +Specifies a geolocation to be associated for this IP address list. This will force the IP addresses in the list to be considered as though they are in that geolocation. This applies to blocking via "disallowed-geolocations" and to logging. Optional @@ -2920,11 +2927,92 @@

    ipAddresses

    ipAddress string +Specifies the IP address. Use CIDR notation for subnet definition. + + + + +

    ip-intelligence

    + ++++++ + + + + + + + + + + + + + + + + + +
    Field NameTypeDescriptionAllowed Values
    enabledboolean
    ipIntelligenceCategoriesarray of objects
    +

    ipIntelligenceCategories

    + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Field NameTypeDescriptionAllowed Values
    alarmboolean
    blockboolean
    categorystring
      +
    • Anonymous Proxy
      • +
    • BotNets
      • +
    • Cloud-based Services
      • +
    • Denial of Service
      • +
    • Infected Sources
      • +
    • Mobile Threats
      • +
    • Phishing Proxies
      • +
    • Scanners
      • +
    • Spam Sources
      • +
    • Tor Proxies
      • +
    • Web Attacks
      • +
    • Windows Exploits
      • +

    json-profiles

    @@ -3359,6 +3447,7 @@

    login-pages

  • http-digest: The web server performs the authentication; user names and passwords are not transmitted over the network, nor are they stored in plain text.
  • ntlm: Microsoft LAN Manager authentication (also called Integrated Windows Authentication) does not transmit credentials in plain text, but requires a continuous TCP connection between the server and client.
  • ajax-or-json-request: The web server uses JSON and AJAX requests to authenticate users trying to access the web application through the login URL. For this option, you also need to type the name of the JSON element containing the user name and password.
    • +
  • request-body: The web server uses the request body to authenticate users trying to access the web application through the login URL. This allows brute force login detection using, for example, SAML authentication used on Microsoft Federation Services for SSO which uses SOAP API to login.
    • - + @@ -3398,7 +3487,7 @@

    login-pages

    - + @@ -3605,7 +3694,7 @@

    override-rules

    Request Attributes:

      -
    • clientIp: Client IP address in canonical IPv4 or IPv6 format. Use CIDR notation for subnet definition. Example: 192.168.1.2 or fd00:1::/48. If trustXff (X-Forwarded-For) is enabled in the containing policy, then the value is taken from the configured header (XFF or other). The only supported boolean function for the clientIP attribute is matches.
      • +
    • clientIp: Client IP address in canonical IPv4 or IPv6 format or ip-address-list. Use CIDR notation for subnet definition. Example: 192.168.1.2 or fd00:1::/48. If trustXff (X-Forwarded-For) is enabled in the containing policy, then the value is taken from the configured header (XFF or other). The only supported boolean function for the clientIP attribute is matches.
    • host: The value of the Host header
    • method: The HTTP method in the request
    • uri: The URI (path part) of the request
      • @@ -3616,7 +3705,7 @@

      override-rules

    • headers['<name>']: (map-type) The value of the specified header name. Example: "headers['Accept'].startsWith('application')"
    -

    Note: The "headers['<name>']" attribute does not support 'Cookie' as a header name.

    +

    Note: The "headers['<name>']" attribute does not support 'Cookie' as a header name. Attribute "clientIp" supports using "ipAddressLists" in condition: "clientIp.matches(ipAddressLists[''])

    @@ -6414,6 +6503,7 @@

    violations

  • VIOL_XML_MALFORMED
  • VIOL_GEOLOCATION
  • VIOL_WEBSOCKET_BAD_REQUEST
    • +
  • VIOL_MALICIOUS_IP
    • diff --git a/content/includes/nap-waf/setup-docker-registry.md b/content/includes/nap-waf/setup-docker-registry.md index fc2896154..9ace0cb63 100644 --- a/content/includes/nap-waf/setup-docker-registry.md +++ b/content/includes/nap-waf/setup-docker-registry.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1508" +nd-docs: "DOCS-1508" --- Configure Docker to interact with the F5 Container Registry at `private-registry.nginx.com`: diff --git a/content/includes/nap-waf/upgrade-recompile-warning.md b/content/includes/nap-waf/upgrade-recompile-warning.md index aeb993e2a..970b58e72 100644 --- a/content/includes/nap-waf/upgrade-recompile-warning.md +++ b/content/includes/nap-waf/upgrade-recompile-warning.md @@ -1,10 +1,10 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- {{< warning >}} -When upgrading, you must recompile all policy and log bundles using the latest WAF compiler. +When upgrading, you must recompile all policy and log bundles using the latest WAF compiler. Older bundles will be detected and disallowed. diff --git a/content/includes/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md b/content/includes/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md index b22a14342..5979df586 100644 --- a/content/includes/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md +++ b/content/includes/ngf/installation/delay-pod-termination/delay-pod-termination-overview.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1441" +nd-docs: "DOCS-1441" --- To avoid client service interruptions when upgrading NGINX Gateway Fabric, you can configure [`PreStop` hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) to delay terminating the NGINX Gateway Fabric pod, allowing the pod to complete certain actions before shutting down. This ensures a smooth upgrade without any downtime, also known as a zero downtime upgrade. diff --git a/content/includes/ngf/installation/delay-pod-termination/termination-grace-period.md b/content/includes/ngf/installation/delay-pod-termination/termination-grace-period.md index 8b2b3f473..6f21d5702 100644 --- a/content/includes/ngf/installation/delay-pod-termination/termination-grace-period.md +++ b/content/includes/ngf/installation/delay-pod-termination/termination-grace-period.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1440" +nd-docs: "DOCS-1440" --- Set `terminationGracePeriodSeconds` to a value that is equal to or greater than the `sleep` duration specified in the `preStop` hook (default is `30`). This setting prevents Kubernetes from terminating the pod before before the `preStop` hook has completed running. diff --git a/content/includes/ngf/installation/expose-nginx-gateway-fabric.md b/content/includes/ngf/installation/expose-nginx-gateway-fabric.md index 85d2f4f4c..7820399a0 100644 --- a/content/includes/ngf/installation/expose-nginx-gateway-fabric.md +++ b/content/includes/ngf/installation/expose-nginx-gateway-fabric.md @@ -1,7 +1,7 @@ --- title: "Expose NGINX Gateway Fabric" weight: 300 -docs: "DOCS-1427" +nd-docs: "DOCS-1427" --- There are two options for accessing NGINX Gateway Fabric depending on the type of LoadBalancer service you chose during installation: @@ -50,4 +50,4 @@ There are two options for accessing NGINX Gateway Fabric depending on the type o NGINX Gateway Fabric uses the created service to update the **Addresses** field in the **Gateway Status** resource. Using a **LoadBalancer** service sets this field to the IP address and/or hostname of that service. Without a service, the pod IP address is used. -This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a **GatewayClass** with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< ref "/ngf/reference/cli-help.md#static-mode">}}). +This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a **GatewayClass** with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< ref "/ngf/reference/cli-help.md#controller">}}). diff --git a/content/includes/ngf/installation/helm/pulling-the-chart.md b/content/includes/ngf/installation/helm/pulling-the-chart.md index b82b2f809..e42fb7f6a 100644 --- a/content/includes/ngf/installation/helm/pulling-the-chart.md +++ b/content/includes/ngf/installation/helm/pulling-the-chart.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1439" +nd-docs: "DOCS-1439" --- ```shell diff --git a/content/includes/ngf/installation/install-gateway-api-experimental-features.md b/content/includes/ngf/installation/install-gateway-api-experimental-features.md index aa95d1eb9..aec27817e 100644 --- a/content/includes/ngf/installation/install-gateway-api-experimental-features.md +++ b/content/includes/ngf/installation/install-gateway-api-experimental-features.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- To use Gateway API experimental resources, the Gateway API resources from the experimental channel must be installed before deploying NGINX Gateway Fabric. Additionally, NGINX Gateway Fabric must have experimental features enabled. diff --git a/content/includes/ngf/installation/install-gateway-api-resources.md b/content/includes/ngf/installation/install-gateway-api-resources.md index 3932dad32..bab5a44bd 100644 --- a/content/includes/ngf/installation/install-gateway-api-resources.md +++ b/content/includes/ngf/installation/install-gateway-api-resources.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1438" +nd-docs: "DOCS-1438" --- {{< note >}} The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) from the standard channel must be installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure they are the correct version as supported by the NGINX Gateway Fabric - [see the Technical Specifications](https://github.com/nginx/nginx-gateway-fabric/blob/v{{< version-ngf >}}/README.md#technical-specifications). {{}} diff --git a/content/includes/ngf/installation/jwt-password-note.md b/content/includes/ngf/installation/jwt-password-note.md index 4cfeec8b9..6cc40d962 100644 --- a/content/includes/ngf/installation/jwt-password-note.md +++ b/content/includes/ngf/installation/jwt-password-note.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- {{< note >}} For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history: diff --git a/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md b/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md index c6d666b6d..0ad007efa 100644 --- a/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md +++ b/content/includes/ngf/installation/nginx-plus/docker-registry-secret.md @@ -1,8 +1,8 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- -{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/install/nginx-plus.md#pulling-an-image-for-local-use" >}}). {{< /note >}} +{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/install/nginx-plus.md#pull-an-image-for-local-use" >}}). {{< /note >}} If the `nginx-gateway` namespace does not yet exist, create it: diff --git a/content/includes/ngf/installation/nginx-plus/download-jwt.md b/content/includes/ngf/installation/nginx-plus/download-jwt.md index d89c65a43..78ad1cbf8 100644 --- a/content/includes/ngf/installation/nginx-plus/download-jwt.md +++ b/content/includes/ngf/installation/nginx-plus/download-jwt.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- 1. Log in to [MyF5](https://my.f5.com/manage/s/). diff --git a/content/includes/ngf/installation/nginx-plus/nginx-plus-secret.md b/content/includes/ngf/installation/nginx-plus/nginx-plus-secret.md index 1a5beb474..be8a0b9f4 100644 --- a/content/includes/ngf/installation/nginx-plus/nginx-plus-secret.md +++ b/content/includes/ngf/installation/nginx-plus/nginx-plus-secret.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- Place the JWT in a file called `license.jwt`. Create a Kubernetes Secret using the contents of the JWT file. diff --git a/content/includes/ngf/installation/uninstall-gateway-api-resources.md b/content/includes/ngf/installation/uninstall-gateway-api-resources.md index d5631d1f5..92a857ff6 100644 --- a/content/includes/ngf/installation/uninstall-gateway-api-resources.md +++ b/content/includes/ngf/installation/uninstall-gateway-api-resources.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1436" +nd-docs: "DOCS-1436" --- {{< warning >}} This will remove all corresponding custom resources in your entire cluster, across all namespaces. Double-check to make sure you don't have any custom resources you need to keep, and confirm that there are no other Gateway API implementations active in your cluster. {{}} diff --git a/content/includes/ngf/installation/upgrade-api-resources.md b/content/includes/ngf/installation/upgrade-api-resources.md index c8ad3d706..adaed0b1a 100644 --- a/content/includes/ngf/installation/upgrade-api-resources.md +++ b/content/includes/ngf/installation/upgrade-api-resources.md @@ -1,10 +1,10 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- To upgrade your Gateway API resources, take the following steps: -- Use [Technical specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) to verify your Gateway API resources are compatible with your NGINX Gateway Fabric version. +- Use [Technical specifications]({{< ref "/ngf/reference/technical-specifications.md" >}}) to verify your Gateway API resources are compatible with your NGINX Gateway Fabric version. - Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information. To upgrade the Gateway API resources, run the following command: 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/content/includes/nginx-one/cloud-access-nginx.md b/content/includes/nginx-one/cloud-access-nginx.md new file mode 100644 index 000000000..7756edc80 --- /dev/null +++ b/content/includes/nginx-one/cloud-access-nginx.md @@ -0,0 +1,11 @@ +--- +files: + - content/nginx-one/secure-your-fleet/secure.md + - content/nginx-one/getting-started.md +--- + +Once you've logged in with your password, you should be able to see and select the NGINX One tile. + +1. Select the **NGINX One** tile +1. If needed, select **Enable Service** +1. After the service has been enables, select **Visit Service** to load NGINX One Console diff --git a/content/includes/nginx-one/cloud-access.md b/content/includes/nginx-one/cloud-access.md new file mode 100644 index 000000000..c50a1289b --- /dev/null +++ b/content/includes/nginx-one/cloud-access.md @@ -0,0 +1,11 @@ +--- +files: + - content/nginx-one/secure-your-fleet/secure.md + - content/nginx-one/getting-started.md +--- + +Confirm an F5 Distributed Cloud tenant has been provisioned for you. Log in to MyF5 and review your subscriptions. You should see within one of your subscriptions "Distributed Cloud". This could be in either an NGINX subscription or a Distributed Cloud. If the above does not appear in any of your subscriptions, reach out to either your F5 Account Team or Customer Success Manager. + +With access, you or someone in your organization should have an email from no-reply@cloud.f5.com asking you to update your password when the tenant was created. The account name referenced in the E-Mail in bold is the tenant name. + +Navigate to https://INSERT_YOUR_TENANT_NAME.console.ves.volterra.io/ to access F5 Distributed Cloud. If you have never logged in, select the **Forgot Password?** option in the log in screen. Alternatively, if someone within your organization has access, ask them to add you as a user within your tenant with a role providing permissions for NGINX One. diff --git a/content/includes/nginx-one/conf/nginx-agent-conf.md b/content/includes/nginx-one/conf/nginx-agent-conf.md new file mode 100644 index 000000000..0fcbc57ea --- /dev/null +++ b/content/includes/nginx-one/conf/nginx-agent-conf.md @@ -0,0 +1,22 @@ +--- +docs: DOCS-000 +files: + - content/nginx-one/getting-started.md + - content/nginx-one/agent/containers/run-agent-container.md +--- + +```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, typically https://INSERT_YOUR_TENANT_NAME.console.ves.volterra.io/ . +- ``: Your Data Plane key. diff --git a/content/includes/nginx-one/install-nginx.md b/content/includes/nginx-one/install-nginx.md new file mode 100644 index 000000000..cfc3863bf --- /dev/null +++ b/content/includes/nginx-one/install-nginx.md @@ -0,0 +1,10 @@ +--- +files: + - content/nginx-one/secure-your-fleet/secure.md + - content/nginx-one/getting-started.md +--- + +If you need to set up an instance of NGINX, you can do so in one of the following ways: + +- Install [NGINX Open Source or NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/" >}}). You can use the linked guide to install NGINX in a Linux environment, in a VM or on bare-metal hardware. +- [Deploy NGINX and NGINX Plus with Docker]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-docker.md" >}}) with NGINX and the NGINX Agent installed. diff --git a/content/includes/nginx-one/staged-config-overview.md b/content/includes/nginx-one/staged-config-overview.md index 9d5a6fe35..f47aec5d5 100644 --- a/content/includes/nginx-one/staged-config-overview.md +++ b/content/includes/nginx-one/staged-config-overview.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 files: - content/nginx-one/how-to/staged-configs/add-staged-config.md - content/nginx-one/how-to/staged-configs/edit-staged-config.md diff --git a/content/includes/nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md b/content/includes/nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md index 126379d99..4f082614c 100644 --- a/content/includes/nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md +++ b/content/includes/nginx-plus/install/pin-to-version/pin-debian-ubuntu-R32.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- To pin NGINX Plus to a specific version (for example, R33): diff --git a/content/includes/nginx-plus/install/pin-to-version/pin-rhel7-R32.md b/content/includes/nginx-plus/install/pin-to-version/pin-rhel7-R32.md index 763f8f7d3..6e38a6922 100644 --- a/content/includes/nginx-plus/install/pin-to-version/pin-rhel7-R32.md +++ b/content/includes/nginx-plus/install/pin-to-version/pin-rhel7-R32.md @@ -1,11 +1,11 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- To pin NGINX Plus to a specific version (for example, R32): 1. Edit the `/etc/yum.repos.d/nginx-plus-7.4.repo` file. -1. Update the repository base URL to the desired version: +1. Update the repository base URL to the desired version: ```shell baseurl=https://pkgs.nginx.com/plus/R32/centos/7/$basearch/ diff --git a/content/includes/nginx-plus/install/pin-to-version/pin-rhel8-R32.md b/content/includes/nginx-plus/install/pin-to-version/pin-rhel8-R32.md index 369a9ebb9..d970d82c2 100644 --- a/content/includes/nginx-plus/install/pin-to-version/pin-rhel8-R32.md +++ b/content/includes/nginx-plus/install/pin-to-version/pin-rhel8-R32.md @@ -1,11 +1,11 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- To pin NGINX Plus to a specific version (for example, R33): 1. Edit the `/etc/yum.repos.d/nginx-plus-8.repo` file. -1. Update the repository base URL to the desired version: +1. Update the repository base URL to the desired version: ```shell baseurl=https://pkgs.nginx.com/plus/R33/centos/8/$basearch/ diff --git a/content/includes/nginx-plus/install/pin-to-version/pin-rhel9-R32.md b/content/includes/nginx-plus/install/pin-to-version/pin-rhel9-R32.md index 6085a8c7d..80b5571db 100644 --- a/content/includes/nginx-plus/install/pin-to-version/pin-rhel9-R32.md +++ b/content/includes/nginx-plus/install/pin-to-version/pin-rhel9-R32.md @@ -1,11 +1,11 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 --- To pin NGINX Plus to a specific version (for example, R33): 1. Edit the `/etc/yum.repos.d/plus-9.repo` file. -1. Update the repository base URL to the desired version: +1. Update the repository base URL to the desired version: ```shell baseurl=https://pkgs.nginx.com/plus/R33/centos/9/$basearch/ 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/includes/nginx-plus/usage-tracking/agentless-reporting.md b/content/includes/nginx-plus/usage-tracking/agentless-reporting.md index 0cbdce2f4..55af846c6 100644 --- a/content/includes/nginx-plus/usage-tracking/agentless-reporting.md +++ b/content/includes/nginx-plus/usage-tracking/agentless-reporting.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1408 +nd-docs: DOCS-1408 --- Since [Release 31]({{< ref "/nginx/releases.md#nginxplusrelease-31-r31" >}}), NGINX Plus provides a built-in support for reporting of your NGINX Plus instances to NGINX Instance Manager without the need of installing NGINX Agent or tuning HTTP Health checks. If you participate in the [F5 Flex Consumption Program](https://www.f5.com/products/get-f5/flex-consumption-program), you will no longer need to manually track your NGINX Plus instances. diff --git a/content/includes/nginx-plus/usage-tracking/get-list-k8s-deployments.md b/content/includes/nginx-plus/usage-tracking/get-list-k8s-deployments.md index 41caaa2d1..2f8a092b1 100644 --- a/content/includes/nginx-plus/usage-tracking/get-list-k8s-deployments.md +++ b/content/includes/nginx-plus/usage-tracking/get-list-k8s-deployments.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1352 +nd-docs: DOCS-1352 --- To report your NGINX Ingress Controller clusters to F5, follow these steps: diff --git a/content/includes/nginx-plus/usage-tracking/http-health-check.md b/content/includes/nginx-plus/usage-tracking/http-health-check.md index 0a0e0a90d..7cf3e8cd6 100644 --- a/content/includes/nginx-plus/usage-tracking/http-health-check.md +++ b/content/includes/nginx-plus/usage-tracking/http-health-check.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1351 +nd-docs: DOCS-1351 --- You can track NGINX Plus instances using an [HTTP Health Check]({{< ref "nginx/admin-guide/load-balancer/http-health-check" >}}) without installing NGINX Agent. This involves updating the NGINX Plus configuration file. Follow these steps: diff --git a/content/includes/nginx-plus/usage-tracking/install-nginx-agent.md b/content/includes/nginx-plus/usage-tracking/install-nginx-agent.md index 9779c6c38..855a4b90d 100644 --- a/content/includes/nginx-plus/usage-tracking/install-nginx-agent.md +++ b/content/includes/nginx-plus/usage-tracking/install-nginx-agent.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1354 +nd-docs: DOCS-1354 --- When you install NGINX Agent on an NGINX Plus instance, it will establish a connection with Instance Manager and begin transmitting usage data. diff --git a/content/includes/nginx-plus/usage-tracking/install-nim.md b/content/includes/nginx-plus/usage-tracking/install-nim.md index b5d048227..cdbb7f7b4 100644 --- a/content/includes/nginx-plus/usage-tracking/install-nim.md +++ b/content/includes/nginx-plus/usage-tracking/install-nim.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1355 +nd-docs: DOCS-1355 --- {{}}A separate license for NGINX Instance Manager is not required to track your NGINX product usage.{{}} diff --git a/content/includes/nginx-plus/usage-tracking/overview.md b/content/includes/nginx-plus/usage-tracking/overview.md index 3a048abf9..d903d54a1 100644 --- a/content/includes/nginx-plus/usage-tracking/overview.md +++ b/content/includes/nginx-plus/usage-tracking/overview.md @@ -1,10 +1,10 @@ --- -docs: DOCS-1349 +nd-docs: DOCS-1349 --- Start by installing NGINX Instance Manager on a dedicated host. Then, configure your NGINX Plus systems to report back to Instance Manager. Once connected, you can easily view and report on your NGINX Plus inventory using the NGINX Instance Manager REST API or web interface. You can send these reports to your F5 contact as needed. {{}} -To set up automatic reporting, [add your JWT-based license to NGINX Instance Manager]({{< ref "/nim/admin-guide/license/add-license.md#apply-jwt-license" >}}). This license can be downloaded from [MyF5](https://account.f5.com/myf5) if needed. +To set up automatic reporting, [add your JWT-based license to NGINX Instance Manager]({{< ref "/nim/admin-guide/add-license.md#apply-jwt-license" >}}). This license can be downloaded from [MyF5](https://account.f5.com/myf5) if needed. {{}} diff --git a/content/includes/nginx-plus/usage-tracking/view-nginx-plus-count.md b/content/includes/nginx-plus/usage-tracking/view-nginx-plus-count.md index 9ddc0a2ef..4b63bbdfd 100644 --- a/content/includes/nginx-plus/usage-tracking/view-nginx-plus-count.md +++ b/content/includes/nginx-plus/usage-tracking/view-nginx-plus-count.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1350 +nd-docs: DOCS-1350 --- Follow these steps to view and export the list of NGINX Plus instances that have successfully registered with Instance Manager: diff --git a/content/includes/nginxaas-azure/logging-analysis-azure-storage.md b/content/includes/nginxaas-azure/logging-analysis-azure-storage.md index 67bc3f358..54e2cc824 100644 --- a/content/includes/nginxaas-azure/logging-analysis-azure-storage.md +++ b/content/includes/nginxaas-azure/logging-analysis-azure-storage.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- If the diagnostic setting destination details included a storage account, logs show up in the storage container "insights-logs-nginxlogs" with the following format: `resourceID=//y=/m=/d=
    /h=/PT1H.json` diff --git a/content/includes/nginxaas-azure/logging-analysis-logs-analytics.md b/content/includes/nginxaas-azure/logging-analysis-logs-analytics.md index 8809a824d..418c8edfc 100644 --- a/content/includes/nginxaas-azure/logging-analysis-logs-analytics.md +++ b/content/includes/nginxaas-azure/logging-analysis-logs-analytics.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- If the diagnostic setting destination details included a Logs Analytics workspace, logs show up in the table "NGXOperationLogs" with the following non-standard attributes: diff --git a/content/includes/nginxaas-azure/logging-config-access-logs.md b/content/includes/nginxaas-azure/logging-config-access-logs.md index 01fba8215..63e7c12ec 100644 --- a/content/includes/nginxaas-azure/logging-config-access-logs.md +++ b/content/includes/nginxaas-azure/logging-config-access-logs.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- NGINX access logs are disabled by default. You can enable access logs by adding **access_log** directives to your NGINX configuration to specify the location of the logs and formats. The log path should always be configured to be inside **/var/log/nginx**. diff --git a/content/includes/nginxaas-azure/logging-config-error-logs.md b/content/includes/nginxaas-azure/logging-config-error-logs.md index c27d8ace8..149a960ac 100644 --- a/content/includes/nginxaas-azure/logging-config-error-logs.md +++ b/content/includes/nginxaas-azure/logging-config-error-logs.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- By default, NGINXaaS for Azure puts the error log at **/var/log/nginx/error.log**. It includes messages with severity **error** and above. diff --git a/content/includes/nginxaas-azure/logging-limitations.md b/content/includes/nginxaas-azure/logging-limitations.md index a6b636d66..8e4f9722a 100644 --- a/content/includes/nginxaas-azure/logging-limitations.md +++ b/content/includes/nginxaas-azure/logging-limitations.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- 1. File-based logs must be configured to use the path **/var/log/nginx**. diff --git a/content/includes/nginxaas-azure/ncu-description.md b/content/includes/nginxaas-azure/ncu-description.md index 138b593e6..17c015e54 100644 --- a/content/includes/nginxaas-azure/ncu-description.md +++ b/content/includes/nginxaas-azure/ncu-description.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1476" +nd-docs: "DOCS-1476" --- An NGINX Capacity Unit (NCU) quantifies the capacity of an NGINX instance based on the underlying compute resources. This abstraction allows you to specify the desired capacity in NCUs without having to consider the regional hardware differences. diff --git a/content/includes/nginxaas-azure/ssl-tls-prerequisites.md b/content/includes/nginxaas-azure/ssl-tls-prerequisites.md index 1d95d498d..def7a9e97 100644 --- a/content/includes/nginxaas-azure/ssl-tls-prerequisites.md +++ b/content/includes/nginxaas-azure/ssl-tls-prerequisites.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- NGINXaaS natively integrates with [Azure Key Vault (AKV)](https://azure.microsoft.com/en-us/products/key-vault), so you can bring your own certificates and manage them in a centralized location. You will need: diff --git a/content/includes/nginxaas-azure/terraform-prerequisites.md b/content/includes/nginxaas-azure/terraform-prerequisites.md index a0267168b..aafb6908f 100644 --- a/content/includes/nginxaas-azure/terraform-prerequisites.md +++ b/content/includes/nginxaas-azure/terraform-prerequisites.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- - Confirm that you meet the [NGINXaaS Prerequisites]({{< ref "/nginxaas-azure/getting-started/prerequisites.md" >}}). diff --git a/content/includes/nginxaas-azure/terraform-resources.md b/content/includes/nginxaas-azure/terraform-resources.md index f45c36671..0a830ca19 100644 --- a/content/includes/nginxaas-azure/terraform-resources.md +++ b/content/includes/nginxaas-azure/terraform-resources.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-000" +nd-docs: "DOCS-000" --- - [NGINXaaS Managed Identity Documentation]({{< ref "/nginxaas-azure/getting-started/managed-identity-portal.md" >}}) diff --git a/content/includes/nic/compatibility-tables/nic-nap.md b/content/includes/nic/compatibility-tables/nic-nap.md new file mode 100644 index 000000000..aaf914ca1 --- /dev/null +++ b/content/includes/nic/compatibility-tables/nic-nap.md @@ -0,0 +1,10 @@ +The following table shows compatibility between NGINX Ingress Controller (NIC) and NGINX App Protect WAF (NAP-WAF) versions: + +{{< bootstrap-table "table table-striped table-responsive" >}} +| NIC Version | NAP-WAF Version | Config Manager | Enforcer | +| ------------------- | --------------- | -------------- | -------- | +| {{< nic-version >}} | 34+5.332 | 5.6.0 | 5.6.0 | +| 4.0.1 | 33+5.264 | 5.5.0 | 5.5.0 | +| 3.7.2 | 32+5.1 | 5.3.0 | 5.3.0 | +| 3.6.2 | 32+5.48 | 5.2.0 | 5.2.0 | +{{% /bootstrap-table %}} diff --git a/content/includes/nic/configuration/_index.md b/content/includes/nic/configuration/_index.md new file mode 100644 index 000000000..7e1500973 --- /dev/null +++ b/content/includes/nic/configuration/_index.md @@ -0,0 +1,8 @@ +--- +title: Configuration +description: +weight: 1400 +menu: + docs: + parent: NGINX Ingress Controller +--- diff --git a/content/includes/nic/configuration/access-control.md b/content/includes/nic/configuration/access-control.md new file mode 100644 index 000000000..769bfbabf --- /dev/null +++ b/content/includes/nic/configuration/access-control.md @@ -0,0 +1,120 @@ +--- +title: Deploy a Policy for access control +weight: 900 +toc: true +nd-docs: DOCS-000 +--- + +This topic describes how to use F5 NGINX Ingress Controller to apply and update a Policy for access control. It demonstrates it using an example application and a [VirtualServer custom resource]({{< ref "/configuration/virtualserver-and-virtualserverroute-resources.md" >}}). + +--- + +## Before you begin + +You should have a [working NGINX Ingress Controller]({{< ref "/installation/installing-nic/installation-with-helm.md" >}}) instance. + +For ease of use in shell commands, set two shell variables: + +1. The public IP address for your NGINX Ingress Controller instance. + +```shell +IC_IP= +``` + +2. The HTTP port of the same instance. + +```shell +IC_HTTP_PORT= +``` + +--- + +## Deploy the example application + +Create the file _webapp.yaml_ with the following contents: + +{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/webapp.yaml" >}} + +Apply it using `kubectl`: + +```shell +kubectl apply -f webapp.yaml +``` + +--- + +## Deploy a Policy to create a deny rule + +Create a file named _access-control-policy-deny.yaml_. The highlighted _deny_ field will be used by the example application, and should be changed to the subnet of your machine. + +{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/access-control-policy-deny.yaml" "hl_lines=7-8" >}} + +Apply the policy: + +```shell +kubectl apply -f access-control-policy-deny.yaml +``` + +--- + +## Configure load balancing + +Create a file named _virtual-server.yaml_ for the VirtualServer resource. The _policies_ field references the access control Policy created in the previous section. + +{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/virtual-server.yaml" "hl_lines=7-8" >}} + +Apply the policy: + +```shell +kubectl apply -f virtual-server.yaml +``` + +--- + +## Test the example application + +Use `curl` to attempt to access the application: + +```shell +curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT +``` +```text + +403 Forbidden + +

    403 Forbidden

    + + +``` + +The *403* response is expected, successfully blocking your machine. + +--- + +## Update the Policy to create an allow rule + +Update the Policy with the file _access-control-policy-allow.yaml_, setting the _allow_ field to the subnet of your machine. + +{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/access-control-policy-allow.yaml" "hl_lines=7-8" >}} + +Apply the Policy: + +```shell +kubectl apply -f access-control-policy-allow.yaml +``` + +---- + +## Verify the Policy update + +Attempt to access the application again: + +```shell +curl --resolve webapp.example.com:$IC_HTTP_PORT:$IC_IP http://webapp.example.com:$IC_HTTP_PORT +``` +```text +Server address: 10.64.0.13:8080 +Server name: webapp-5cbbc7bd78-wf85w +``` + +The successful response demonstrates that the policy has been updated. diff --git a/content/includes/nic/configuration/configuration-examples.md b/content/includes/nic/configuration/configuration-examples.md new file mode 100644 index 000000000..c49c0790e --- /dev/null +++ b/content/includes/nic/configuration/configuration-examples.md @@ -0,0 +1,13 @@ +--- +nd-docs: DOCS-584 +doctypes: +- '' +title: Configuration examples +toc: true +weight: 400 +--- + +Our [GitHub repo](https://github.com/nginx/kubernetes-ingress) includes a number of configuration examples: + +- [*Examples of Custom Resources*](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources) show how to advanced NGINX features by using VirtualServer, VirtualServerRoute, TransportServer and Policy Custom Resources. +- [*Examples of Ingress Resources*](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources) show how to use advanced NGINX features in Ingress resources with annotations. diff --git a/content/includes/nic/configuration/global-configuration/_index.md b/content/includes/nic/configuration/global-configuration/_index.md new file mode 100644 index 000000000..4f71e2f5f --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/_index.md @@ -0,0 +1,8 @@ +--- +title: Global configuration +description: +weight: 100 +menu: + docs: + parent: NGINX Ingress Controller +--- diff --git a/content/includes/nic/configuration/global-configuration/command-line-arguments.md b/content/includes/nic/configuration/global-configuration/command-line-arguments.md new file mode 100644 index 000000000..552bba1be --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/command-line-arguments.md @@ -0,0 +1,685 @@ +--- +nd-docs: DOCS-585 +doctypes: +- '' +title: Command-line arguments +toc: true +weight: 100 +--- + +F5 NGINX Ingress Controller supports several command-line arguments, which are set based on installation method: + +- If you're using *Kubernetes Manifests* to install NGINX Ingress Controller, modify the Manifests to set the command-line arguments. View the [Installation with Manifests]({{}}) topic for more information. +- If you're using *Helm* to install NGINX Ingress Controller, modify the parameters of the Helm chart to set the command-line arguments. View the [Installation with Helm]({{}}) topic for more information. + + + +### -enable-snippets + +Enable custom NGINX configuration snippets in Ingress, VirtualServer, VirtualServerRoute and TransportServer resources. + +Default `false`. + + + +--- + +### -default-server-tls-secret `` + +Secret with a TLS certificate and key for TLS termination of the default server. + +- If not set, certificate and key in the file `/etc/nginx/secrets/default` are used. +- If `/etc/nginx/secrets/default` doesn't exist, NGINX Ingress Controller will configure NGINX to reject TLS connections to the default server. +- If a secret is set, but NGINX Ingress Controller is not able to fetch it from Kubernetes API, or it is not set and NGINX Ingress Controller fails to read the file "/etc/nginx/secrets/default", NGINX Ingress Controller will fail to start. + +Format: `/` + + + +--- + +### -wildcard-tls-secret `` + +A Secret with a TLS certificate and key for TLS termination of every Ingress/VirtualServer host for which TLS termination is enabled but the Secret is not specified. + +- If the argument is not set, for such Ingress/VirtualServer hosts NGINX will break any attempt to establish a TLS connection +- If the argument is set, but NGINX Ingress Controller is not able to fetch the Secret from Kubernetes API, NGINX Ingress Controller will fail to start. + +Format: `/` + + + +--- + +### -enable-custom-resources + +Enables custom resources. + +Default `true`. + + + + +--- + +### -enable-oidc + +Enables OIDC policies. + +Default `false`. + + + +--- + +### -enable-leader-election + +Enables Leader election to avoid multiple replicas of the controller reporting the status of Ingress, VirtualServer and VirtualServerRoute resources -- only one replica will report status. +Default `true`. + +See [-report-ingress-status](#cmdoption-report-ingress-status) flag. + + + +--- + +### -enable-tls-passthrough + +Enable TLS Passthrough on port 443. + +Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). + + + +--- + +### -tls-passthrough-port `` + +Set the port for TLS Passthrough. +Format: `[1024 - 65535]` (default `443`) + +Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). + + + +--- + +### -enable-cert-manager + +Enable x509 automated certificate management for VirtualServer resources using cert-manager (cert-manager.io). + +Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). + + + +--- + +### -enable-external-dns + +Enable integration with ExternalDNS for configuring public DNS entries for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). + +Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). + + +--- + +### -external-service `` + +Specifies the name of the service with the type LoadBalancer through which the NGINX Ingress Controller pods are exposed externally. The external address of the service is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. + +For Ingress resources only: Requires [-report-ingress-status](#cmdoption-report-ingress-status). + + + +--- + +### -ingresslink `` + +Specifies the name of the IngressLink resource, which exposes the NGINX Ingress Controller pods via a BIG-IP system. The IP of the BIG-IP system is used when reporting the status of Ingress, VirtualServer and VirtualServerRoute resources. + +For Ingress resources only: Requires [-report-ingress-status](#cmdoption-report-ingress-status). + + + +--- + +### -global-configuration `` + +A GlobalConfiguration resource for global configuration of NGINX Ingress Controller. + +Format: `/` + +Requires [-enable-custom-resources](#cmdoption-enable-custom-resources). + + + +--- + +### -health-status + +Adds a location "/nginx-health" to the default server. The location responds with the 200 status code for any request. + +Useful for external health-checking of NGINX Ingress Controller. + + + +--- + +### -health-status-uri `` + +Sets the URI of health status location in the default server. Requires [-health-status](#cmdoption-health-status). (default `/nginx-health`) + + + +--- + +### -ingress-class `` + +The `-ingress-class` argument refers to the name of the resource `kind: IngressClass`. An IngressClass resource with a name equal to the class must be deployed. Otherwise, NGINX Ingress Controller will fail to start. +NGINX Ingress Controller will only process Ingress resources that belong to its class (Whose `ingressClassName` value matches the value of `-ingress-class`), skipping the ones without it. It will also process all the VirtualServer/VirtualServerRoute/TransportServer resources that do not have the `ingressClassName` field. + +Default `nginx`. + + + +--- + +### -ingress-template-path `` + +Path to the ingress NGINX configuration template for an ingress resource. Default for NGINX is `nginx.ingress.tmpl`; default for NGINX Plus is `nginx-plus.ingress.tmpl`. + + + +--- + +### -leader-election-lock-name `` + +Specifies the name of the ConfigMap, within the same namespace as the controller, used as the lock for leader election. + +Requires [-enable-leader-election](#cmdoption-enable-leader-election). + + + +--- + +### -log_backtrace_at `` + +When logging hits line `file:N`, emit a stack trace. + + + +--- + +### -main-template-path `` + +Path to the main NGINX configuration template. + +- Default for NGINX is `nginx.tmpl`. +- Default for NGINX Plus is `nginx-plus.tmpl`. + + + +--- + +### -nginx-configmaps `` + +A ConfigMap resource for customizing NGINX configuration. If a ConfigMap is set, but NGINX Ingress Controller is not able to fetch it from Kubernetes API, NGINX Ingress Controller will fail to start. + +Format: `/` + + + +--- + +### -mgmt-configmap `` + +The Management ConfigMap resource is used for customizing the NGINX mgmt block. If using NGINX Plus, a Management ConfigMap must be set. If NGINX Ingress Controller is not able to fetch it from Kubernetes API, NGINX Ingress Controller will fail to start. + +Format: `/` + + + +--- + +### -nginx-debug + +Enable debugging for NGINX. Uses the nginx-debug binary. Requires 'error-log-level: debug' in the ConfigMap. + + + +--- + +### -nginx-plus + +Enable support for NGINX Plus. + + + +--- + +### -nginx-reload-timeout `` + +Timeout in milliseconds which NGINX Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. + +Default is 60000. + + + +--- + +### -nginx-status + +Enable the NGINX stub_status, or the NGINX Plus API. + +Default `true`. + + + +--- + +### -nginx-status-allow-cidrs `` + +Add IP/CIDR blocks to the allow list for NGINX stub_status or the NGINX Plus API. + +Separate multiple IP/CIDR by commas. (default `127.0.0.1,::1`) + + + +--- + +### -nginx-status-port `` + +Set the port where the NGINX stub_status or the NGINX Plus API is exposed. + +Format: `[1024 - 65535]` (default `8080`) + + + +--- + +### -proxy `` + +{{< warning >}} This argument is intended for testing purposes only. {{< /warning >}} + +Use a proxy server to connect to Kubernetes API started with `kubectl proxy`. + +NGINX Ingress Controller does not start NGINX and does not write any generated NGINX configuration files to disk. + + + +--- + +### -report-ingress-status + +Updates the address field in the status of Ingress resources. + +Requires the [-external-service](#cmdoption-external-service) or [-ingresslink](#cmdoption-ingresslink) flag, or the `external-status-address` key in the ConfigMap. + + + +--- + +### -transportserver-template-path `` + +Path to the TransportServer NGINX configuration template for a TransportServer resource. + +- Default for NGINX is `nginx.transportserver.tmpl`. +- Default for NGINX Plus is `nginx-plus.transportserver.tmpl`. + + + +--- + +### -log-level `` + +Log level for Ingress Controller logs. Allowed values: fatal, error, warn, info, debug, trace. + +- Default is `info`. + + + +--- + +### -log-format `` + +Log format for Ingress Controller logs. Allowed values: glog, json, text. + +- Default is `glog`. + + + +--- + +### -version + +Print the version, git-commit hash and build date and exit. + + + +--- + +### -virtualserver-template-path `` + +Path to the VirtualServer NGINX configuration template for a VirtualServer resource. + +- Default for NGINX is `nginx.virtualserver.tmpl`. +- Default for NGINX Plus is `nginx-plus.virtualserver.tmpl`. + + + + +--- + +### -vmodule `` + +A comma-separated list of pattern=N settings for file-filtered logging. + + + +--- + +### -watch-namespace `` + +Comma separated list of namespaces NGINX Ingress Controller should watch for resources. By default NGINX Ingress Controller watches all namespaces. Mutually exclusive with "watch-namespace-label". + + + +--- + +### -watch-namespace-label `` + +Configures NGINX Ingress Controller to watch only those namespaces with label foo=bar. By default NGINX Ingress Controller watches all namespaces. Mutually exclusive with "watch-namespace". + + + +--- + +### -watch-secret-namespace `` + +Comma separated list of namespaces NGINX Ingress Controller should watch for secrets. If this arg is not configured, NGINX Ingress Controller watches the same namespaces for all resources, see "watch-namespace" and "watch-namespace-label". All namespaces included with this argument must be part of either `-watch-namespace` or `-watch-namespace-label`. + + + +--- + +### -enable-prometheus-metrics + +Enables exposing NGINX or NGINX Plus metrics in the Prometheus format. + + + +--- + +### -prometheus-metrics-listen-port `` + +Sets the port where the Prometheus metrics are exposed. + +Format: `[1024 - 65535]` (default `9113`) + + + +--- + +### -prometheus-tls-secret `` + +A Secret with a TLS certificate and key for TLS termination of the Prometheus metrics endpoint. + +- If the argument is not set, the Prometheus endpoint will not use a TLS connection. +- If the argument is set, but NGINX Ingress Controller is not able to fetch the Secret from Kubernetes API, NGINX Ingress Controller will fail to start. + + + +--- + +### -enable-service-insight + +Exposes the Service Insight endpoint for Ingress Controller. + + + +--- + +### -service-insight-listen-port `` + +Sets the port where the Service Insight is exposed. + +Format: `[1024 - 65535]` (default `9114`) + + + +--- + +### -service-insight-tls-secret `` + +A Secret with a TLS certificate and key for TLS termination of the Service Insight endpoint. + +- If the argument is not set, the Service Insight endpoint will not use a TLS connection. +- If the argument is set, but NGINX Ingress Controller is not able to fetch the Secret from Kubernetes API, NGINX Ingress Controller will fail to start. + +Format: `/` + + + +--- + +### -spire-agent-address `` + +Specifies the address of a running Spire agent. **For use with NGINX Service Mesh only**. + +- If the argument is set, but NGINX Ingress Controller is unable to connect to the Spire Agent, NGINX Ingress Controller will fail to start. + + + + +--- + +### -enable-internal-routes + +Enable support for internal routes with NGINX Service Mesh. **For use with NGINX Service Mesh only**. + +Requires [-spire-agent-address](#cmdoption-spire-agent-address). + +- If the argument is set, but `spire-agent-address` is not provided, NGINX Ingress Controller will fail to start. + + + +--- + +### -enable-latency-metrics + +Enable collection of latency metrics for upstreams. +Requires [-enable-prometheus-metrics](#cmdoption-enable-prometheus-metrics). + + + +--- + +### -enable-app-protect + +Enables support for App Protect. + +Requires [-nginx-plus](#cmdoption-nginx-plus). + +- If the argument is set, but `nginx-plus` is set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -app-protect-log-level `` + +Sets log level for App Protect. Allowed values: fatal, error, warn, info, debug, trace. + +Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect](#cmdoption-enable-app-protect). + +- If the argument is set, but `nginx-plus` and `enable-app-protect` are set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -enable-app-protect-dos + +Enables support for App Protect DoS. + +Requires [-nginx-plus](#cmdoption-nginx-plus). + +- If the argument is set, but `nginx-plus` is set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -app-protect-dos-debug + +Enable debugging for App Protect DoS. + +Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmdoption-enable-app-protect-dos). + +- If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -app-protect-dos-max-daemons + +Max number of ADMD instances. + +Default `1`. + +Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmdoption-enable-app-protect-dos). + +- If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -app-protect-dos-max-workers + +Max number of nginx processes to support. + +Default `Number of CPU cores in the machine`. + +Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmdoption-enable-app-protect-dos). + +- If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -app-protect-dos-memory + +RAM memory size to consume in MB + +Default `50% of free RAM in the container or 80MB, the smaller`. + +Requires [-nginx-plus](#cmdoption-nginx-plus) and [-enable-app-protect-dos](#cmdoption-enable-app-protect-dos). + +- If the argument is set, but `nginx-plus` and `enable-app-protect-dos` are set to false, NGINX Ingress Controller will fail to start. + + + +--- + +### -ready-status + +Enables the readiness endpoint `/nginx-ready`. The endpoint returns a success code when NGINX has loaded all the config after the startup. + +Default `true`. + + + +--- + +### -ready-status-port + +The HTTP port for the readiness endpoint. + +Format: `[1024 - 65535]` (default `8081`) + +--- + +### -disable-ipv6 + +Disable IPV6 listeners explicitly for nodes that do not support the IPV6 stack. + +Default `false`. + + + +--- + +### -default-http-listener-port + +Sets the port for the HTTP `default_server` listener. + +Default `80`. + + + +--- + +### -default-https-listener-port + +Sets the port for the HTTPS `default_server` listener. + +Default `443`. + + + +--- + +### -ssl-dynamic-reload + +Used to activate or deactivate lazy loading for SSL Certificates. + +The default value is `true`. + + + +--- + +### -weight-changes-dynamic-reload + +Enables the ability to change the weight distribution of two-way split clients without reloading NGINX. + +Requires [-nginx-plus](#cmdoption-nginx-plus). + +Using this feature may require increasing `map_hash_bucket_size`, `map_hash_max_size`, `variable_hash_bucket_size`, and `variable_hash_max_size` in the ConfigMap based on the number of two-way splits. + +The default value is `false`. + +- If the argument is set, but `nginx-plus` is set to false, NGINX Ingress Controller will ignore the flag. + + + +--- + +### -enable-telemetry-reporting + +Enable gathering and reporting of software telemetry. + +The default value is `true`. + + + +--- + +### -agent + +Enable NGINX Agent which can used with `-enable-app-protect` to send events to Security Monitoring. + +The default value is `false`. + + + +--- + +### -agent-instance-group + +Specify the instance group name to use for the NGINX Ingress Controller deployment when using `-agent`. + + diff --git a/content/includes/nic/configuration/global-configuration/configmap-resource.md b/content/includes/nic/configuration/global-configuration/configmap-resource.md new file mode 100644 index 000000000..28296e291 --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/configmap-resource.md @@ -0,0 +1,250 @@ +--- +title: ConfigMap resources +weight: 300 +toc: true +type: how-to +product: NIC +nd-docs: DOCS-586 +--- + +When using F5 NGINX Ingress Controller, you can customize or fine tune NGINX behavior using ConfigMap resources. Examples include setting the number of worker processes or customizing the access log format. + +## Using ConfigMap + +1. The [Installation with Manifests]({{< relref "installation/installing-nic/installation-with-manifests.md" >}}) documentation deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress Controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments" >}}) of NGINX Ingress Controller. + +1. Create a ConfigMap file with the name *nginx-config.yaml* and set the values +that make sense for your setup: + + ```yaml + kind: ConfigMap + apiVersion: v1 + metadata: + name: nginx-config + namespace: nginx-ingress + data: + proxy-connect-timeout: "10s" + proxy-read-timeout: "10s" + client-max-body-size: "2m" + ``` + + See the section [Summary of ConfigMap Keys](#summary-of-configmap-keys) for the explanation of the available ConfigMap keys (such as `proxy-connect-timeout` in this example). + +1. Create a new (or update the existing) ConfigMap resource: + + ```shell + kubectl apply -f nginx-config.yaml + ``` + + The NGINX configuration will be updated. + +--- + +## ConfigMap and Ingress annotations + +ConfigMap applies globally, meaning that it affects every Ingress resource. In contrast, annotations always apply to their Ingress resource. Annotations can override some ConfigMap keys: an example is that the `nginx.org/proxy-connect-timeout` annotations overrides the `proxy-connect-timeout` ConfigMap key. + +For more information, view the [Advanced configuration with annotations]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations" >}}) topic. + +--- + +## ConfigMap and VirtualServer/VirtualServerRoute resources + +The ConfigMap affects every VirtualServer and VirtualServerRoute resources. However, the fields of those resources allow overriding some ConfigMap keys. For example, the `connect-timeout` field of the `upstream` overrides the `proxy-connect-timeout` ConfigMap key. + +For more information, view the [VirtualServer and VirtualServerRoute resources]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources" >}}) topic. + +--- + +## ConfigMap keys + +### Ingress Controller (Unrelated to NGINX Configuration) + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*external-status-address* | Sets the address to be reported in the status of Ingress resources. Requires the *-report-status* command-line argument. Overrides the *-external-service* argument. | N/A | [Reporting resource status]({{< ref "/nic/configuration/global-configuration/reporting-resources-status" >}}) | +{{}} + +--- + +### General customization + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*proxy-connect-timeout* | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | *60s* | | +|*proxy-read-timeout* | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | *60s* | | +|*proxy-send-timeout* | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | *60s* | | +|*client-max-body-size* | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | *1m* | | +|*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | +|*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | +|*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | +|*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | +|*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | +|*real-ip-recursive* | Enables or disables the [real_ip_recursive](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive) directive. | *False* | | +|*default-server-return* | Configures the [return](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#return) directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, *default-server-return: 302 https://nginx.org* will redirect a client to *https://nginx.org*. | *404* | | +|*server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the β€œServer” field. | *True* | | +|*worker-processes* | Sets the value of the [worker_processes](https://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive. | *auto* | | +|*worker-rlimit-nofile* | Sets the value of the [worker_rlimit_nofile](https://nginx.org/en/docs/ngx_core_module.html#worker_rlimit_nofile) directive. | N/A | | +|*worker-connections* | Sets the value of the [worker_connections](https://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive. | *1024* | | +|*worker-cpu-affinity* | Sets the value of the [worker_cpu_affinity](https://nginx.org/en/docs/ngx_core_module.html#worker_cpu_affinity) directive. | N/A | | +|*worker-shutdown-timeout* | Sets the value of the [worker_shutdown_timeout](https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout) directive. | N/A | | +|*server-names-hash-bucket-size* | Sets the value of the [server_names_hash_bucket_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_bucket_size) directive. | *256* | | +|*server-names-hash-max-size* | Sets the value of the [server_names_hash_max_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_names_hash_max_size) directive. | *1024* | | +|*map-hash-bucket-size* | Sets the value of the [map_hash_bucket_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_bucket_size) directive.| *256* | | +|*map-hash-max-size* | Sets the value of the [map_hash_max_size](http://nginx.org/en/docs/http/ngx_http_map_module.html#map_hash_max_size) directive. | *2048* | | +|*resolver-addresses* | Sets the value of the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) addresses. Note: If you use a DNS name (for example, *kube-dns.kube-system.svc.cluster.local* ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. If the name cannot be resolved or the DNS server doesn't respond, NGINX Plus will fail to start or reload. To avoid this, we recommend using IP addresses as resolver addresses instead of DNS names. Supported in NGINX Plus only. | N/A | [Support for Type ExternalName Services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/externalname-services). | +|*resolver-ipv6* | Enables IPv6 resolution in the resolver. Supported in NGINX Plus only. | *True* | [Support for Type ExternalName Services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/externalname-services). | +|*resolver-valid* | Sets the time NGINX caches the resolved DNS records. Supported in NGINX Plus only. | TTL value of a DNS record | [Support for Type ExternalName Services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/externalname-services). | +|*resolver-timeout* | Sets the [resolver_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver_timeout) for name resolution. Supported in NGINX Plus only. | *30s* | [Support for Type ExternalName Services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/externalname-services). | +|*keepalive-timeout* | Sets the value of the [keepalive_timeout](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout) directive. | *75s* | | +|*keepalive-requests* | Sets the value of the [keepalive_requests](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests) directive. | *1000* | | +|*variables-hash-bucket-size* | Sets the value of the [variables_hash_bucket_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_bucket_size) directive. | *256* | | +|*variables-hash-max-size* | Sets the value of the [variables-hash-max-size](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables_hash_max_size) directive. | *1024* | | +{{}} + +--- + +### Logging + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*error-log-level* | Sets the global [error log level](https://nginx.org/en/docs/ngx_core_module.html#error_log) for NGINX. | *notice* | | +|*access-log* | Sets the directive [access log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log). A syslog destination is the only valid value. The value will be set to its default in-case user tries to configure it with location other than a syslog. +| ``/dev/stdout main`` | ``syslog:server=localhost:514`` | +|*access-log-off* | Disables the [access log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log). | *False* | | +|*default-server-access-log-off* | Disables the [access log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log) for the default server. If access log is disabled globally (*access-log-off: "True"*), then the default server access log is always disabled. | *False* | | +|*log-format* | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for HTTP and HTTPS traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by *\n*). In that case, the Ingress Controller will replace every *\n* character with a space character. All *'* characters must be escaped. | See the [template file](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/internal/configs/version1/nginx.tmpl) for the access log. | [Custom Log Format](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/shared-examples/custom-log-format). | +|*log-format-escaping* | Sets the characters escaping for the variables of the log format. Supported values: *json* (JSON escaping), *default* (the default escaping) *none* (disables escaping). | *default* | | +|*stream-log-format* | Sets the custom [log format](https://nginx.org/en/docs/stream/ngx_stream_log_module.html#log_format) for TCP, UDP, and TLS Passthrough traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by *\n*). In that case, the Ingress Controller will replace every *\n* character with a space character. All *'* characters must be escaped. | See the [template file](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/internal/configs/version1/nginx.tmpl). | | +|*stream-log-format-escaping* | Sets the characters escaping for the variables of the stream log format. Supported values: *json* (JSON escaping), *default* (the default escaping) *none* (disables escaping). | *default* | | +{{}} + +--- + +### Request URI/Header manipulation + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*proxy-hide-headers* | Sets the value of one or more [proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directives. Example: *"nginx.org/proxy-hide-headers": "header-a,header-b"* | N/A | | +|*proxy-pass-headers* | Sets the value of one or more [proxy_pass_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directives. Example: *"nginx.org/proxy-pass-headers": "header-a,header-b"* | N/A | | +{{}} + +--- + +### Auth and SSL/TLS + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*redirect-to-https* | Sets the 301 redirect rule based on the value of the *http_x_forwarded_proto* header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller β€” see [115](https://github.com/nginx/kubernetes-ingress/issues/115) | *False* | | +|*ssl-redirect* | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | *True* | | +|*hsts* | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/) : the HSTS header is added to the responses from backends. The *preload* directive is included in the header. | *False* | | +|*hsts-max-age* | Sets the value of the *max-age* directive of the HSTS header. | *2592000* (1 month) | | +|*hsts-include-subdomains* | Adds the *includeSubDomains* directive to the HSTS header. | *False* | | +|*hsts-behind-proxy* | Enables HSTS based on the value of the *http_x_forwarded_proto* request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the *nginx.org/redirect-to-https* annotation. | *False* | | +|*ssl-protocols* | Sets the value of the [ssl_protocols](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_protocols) directive. | *TLSv1 TLSv1.1 TLSv1.2* | | +|*ssl-prefer-server-ciphers* | Enables or disables the [ssl_prefer_server_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_prefer_server_ciphers) directive. | *False* | | +|*ssl-ciphers* | Sets the value of the [ssl_ciphers](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers) directive. | *HIGH:!aNULL:!MD5* | | +|*ssl-dhparam-file* | Sets the content of the dhparam file. The controller will create the file and set the value of the [ssl_dhparam](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_dhparam) directive with the path of the file. | N/A | | +{{}} + +--- + +### Listeners + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*http2* | Enables HTTP/2 in servers with SSL enabled. | *False* | | +|*proxy-protocol* | Enables PROXY Protocol for incoming connections. | *False* | [Proxy Protocol](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/shared-examples/proxy-protocol). | +{{}} + +--- + +### Backend services (Upstreams) + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*lb-method* | Sets the [load balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify *"round_robin"*. | *"random two least_conn"* | | +|*max-fails* | Sets the value of the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the *server* directive. | *1* | | +|*upstream-zone-size* | Sets the size of the shared memory [zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone) for upstreams. For NGINX, the special value 0 disables the shared memory zones. For NGINX Plus, shared memory zones are required and cannot be disabled. The special value 0 will be ignored. | *256k* for NGINX, *512k* for NGINX Plus | | +|*fail-timeout* | Sets the value of the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the *server* directive. | *10s* | | +|*keepalive* | Sets the value of the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. Note that *proxy_set_header Connection "";* is added to the generated configuration when the value > 0. | *0* | | +{{}} + +--- + +### Zone Sync + +Zone Sync enables the [ngx_stream_zone_sync_module](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html) in NGINX Ingress Controller when NGINX Plus is used. Multiple replicas are required to effectively utililise this functionality. More information is available in the [How NGINX Plus Performs Zone Synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync_details/) topic. + +Zone synchronization with TLS for NGINX Ingress Controller is not yet available with ConfigMap. If you would like to enable Zone Sync with TLS, please remove `zone-sync` from ConfigMap and add Zone Sync parameters via [`stream-snippets`]({{< ref "/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) similar to [this example](https://github.com/nginx/kubernetes-ingress/blob/v4.0.1/examples/custom-resources/oidc/nginx-config.yaml) and adding the [zone_sync_ssl directive](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_ssl) along with any other TLS parameters to the `stream-snippets`. + +You will also need to manually add the headless service, such as in [this example](https://github.com/nginx/kubernetes-ingress/blob/v4.0.1/examples/custom-resources/oidc/nginx-ingress-headless.yaml). + +{{< caution >}} +If you previously installed OIDC or used the `zone_sync` directive with `stream-snippets` in [v4.0.1](https://github.com/nginx/kubernetes-ingress/tree/v4.0.1) or earlier, and you plan to enable the `zone-sync` ConfigMap key, the `zone_sync` directive should be removed from `stream-snippets`. + +If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplicate in /etc/nginx/nginx.conf:164` it is likely due to `zone_sync` being enabled in both `stream-snippets` and the ConfigMap. Once upgraded, remove the [old headless service](https://github.com/nginx/kubernetes-ingress/blob/v4.0.1/examples/custom-resources/oidc/nginx-ingress-headless.yaml) deployed for OIDC. +{{< /caution >}} + + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet` or `DaemonSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | | +|*zone-sync-port* | Specifies the optional port on which NGINX Ingress Controller listens for zone sync traffic. NGINX Plus & `zone-sync` Required. | *12345* | | +|*zone-sync-resolver-addresses* | Configures optional addresses used in the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync. This field takes a comma separated list of addresses. NGINX Plus & `zone-sync` Required | `kube-dns.kube-system.svc.cluster.local` | | +|*zone-sync-resolver-ipv6* | Configures whether the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will look up IPv6 addresses. NGINX Plus & `zone-sync` Required | `true` | | +|*zone-sync-resolver-valid* | Configures an [NGINX time](https://nginx.org/en/docs/syntax.html) that the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will override the TTL value of responses from nameservers with. NGINX Plus & `zone-sync` Required | `5s` | | +{{}} + +--- + +### Snippets and custom templates + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*main-snippets* | Sets a custom snippet in main context. | N/A | | +|*http-snippets* | Sets a custom snippet in http context. | N/A | | +|*location-snippets* | Sets a custom snippet in location context. | N/A | | +|*server-snippets* | Sets a custom snippet in server context. | N/A | | +|*stream-snippets* | Sets a custom snippet in stream context. | N/A | [Support for TCP/UDP Load Balancing](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/tcp-udp). | +|*main-template* | Sets the main NGINX configuration template. | By default the template is read from the file in the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | +|*ingress-template* | Sets the NGINX configuration template for an Ingress resource. | By default the template is read from the file on the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | +|*virtualserver-template* | Sets the NGINX configuration template for an VirtualServer resource. | By default the template is read from the file on the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | +|*transportserver-template* | Sets the NGINX configuration template for a TransportServer resource. | By default the template is read from the file on the container. | [Custom Templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). | +{{}} + +--- + +### Modules + +{{}} +|ConfigMap Key | Description | Default | Example | +| ---| ---| ---| --- | +|*otel-exporter-endpoint* | OTLP/gRPC endpoint that will accept [OpenTelemetry](https://opentelemetry.io) data. Set `otel-trace-in-http` to *"true"* to enable OpenTelemetry at the global level. | N/A | *"https://otel-collector:4317"* | +|*otel-exporter-header-name* | The name of a custom HTTP header to add to telemetry export request. `otel-exporter-endpoint` and `otel-exporter-header-value` required. | N/A | *"X-custom-header"* | +|*otel-exporter-header-value* | The value of a custom HTTP header to add to telemetry export request. `otel-exporter-endpoint` and `otel-exporter-header-name` required. | N/A | *"custom-value"* | +|*otel-service-name* | Sets the `service.name` attribute of the OTel resource. `otel-exporter-endpoint` required. | N/A | *"nginx-ingress-controller:nginx"* | +| *otel-trace-in-http* | Enables [OpenTelemetry](https://opentelemetry.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Set this to *"false"* to enable OpenTelemetry for individual routes with snippets. `otel-exporter-endpoint` required. | *"false"* | *"true"* | +|*opentracing* | Removed in v5.0.0. Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs]({{< relref "/installation/integrations/opentracing.md" >}}) for more information. | *False* | | +|*opentracing-tracer* | Removed in v5.0.0. Sets the path to the vendor tracer binary plugin. | N/A | | +|*opentracing-tracer-config* | Removed in v5.0.0. Sets the tracer configuration in JSON format. | N/A | | +|*app-protect-compressed-requests-action* | Sets the *app_protect_compressed_requests_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *drop* | | +|*app-protect-cookie-seed* | Sets the *app_protect_cookie_seed* [global directive](/nginx-app-protect/configuration/#global-directives). | Random automatically generated string | | +|*app-protect-failure-mode-action* | Sets the *app_protect_failure_mode_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *pass* | | +|*app-protect-cpu-thresholds* | Sets the *app_protect_cpu_thresholds* [global directive](/nginx-app-protect/configuration/#global-directives). | *high=100 low=100* | | +|*app-protect-physical-memory-util-thresholds* | Sets the *app_protect_physical_memory_util_thresholds* [global directive](/nginx-app-protect/configuration/#global-directives). | *high=100 low=100* | | +|`app-protect-reconnect-period-seconds` | Sets the `app_protect_reconnect_period_seconds` [global directive](/nginx-app-protect/configuration/#global-directives). | `5` | | +|*app-protect-dos-log-format* | Sets the custom [log format](https://nginx.org/en/docs/http/ngx_http_log_module.html#log_format) for Dos Access log traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by *\n*). In that case, the Ingress Controller will replace every *\n* character with a space character. All *'* characters must be escaped. | `, vs_name_al=$app_protect_dos_vs_name, ip=$remote_addr, tls_fp=$app_protect_dos_tls_fp, outcome=$app_protect_dos_outcome, reason=$app_protect_dos_outcome_reason, policy_name=$app_protect_dos_policy_name, dos_version=$app_protect_dos_version, ip_tls=$remote_addr:$app_protect_dos_tls_fp,` | | +|*app-protect-dos-log-format-escaping* | Sets the characters escaping for the variables of the stream log format. Supported values: *json* (JSON escaping), *default* (the default escaping) *none* (disables escaping). | *default* | | +|*app-protect-dos-arb-fqdn* | Sets the *app-protect-dos-arb-fqdn* [directive](/nginx-app-protect-dos/directives-and-policy/learn-about-directives-and-policy/#arbitrator-fqdn-directive-app_protect_dos_arb_fqdn). | *svc-appprotect-dos-arb* | | +{{}} diff --git a/content/includes/nic/configuration/global-configuration/custom-templates.md b/content/includes/nic/configuration/global-configuration/custom-templates.md new file mode 100644 index 000000000..6bb99f87f --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/custom-templates.md @@ -0,0 +1,11 @@ +--- +nd-docs: DOCS-587 +doctypes: +- '' +title: Custom templates +toc: true +weight: 500 +--- + + +F5 NGINX Ingress Controller uses templates to generate NGINX configuration for Ingress resources, VirtualServer resources and the main NGINX configuration file. You can customize the templates and apply them via the ConfigMap. See the [corresponding example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/shared-examples/custom-templates). diff --git a/content/includes/nic/configuration/global-configuration/globalconfiguration-resource.md b/content/includes/nic/configuration/global-configuration/globalconfiguration-resource.md new file mode 100644 index 000000000..b5f88b689 --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/globalconfiguration-resource.md @@ -0,0 +1,183 @@ +--- +nd-docs: DOCS-588 +doctypes: +- '' +title: GlobalConfiguration resource +toc: true +weight: 200 +--- + +This page explains how to use the GlobalConfiguration resource to define the global configuration parameters of F5 NGINX Ingress Controller. + +The resource supports configuring listeners for TCP and UDP load balancing, and is implemented as a [Custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +Listeners are required by [TransportServer resources]({{< relref "/configuration/transportserver-resource.md" >}}) and can be used to [configure custom listeners for VirtualServers]({{< relref "tutorials/virtual-server-with-custom-listener-ports.md" >}}). + +--- + +## Prerequisites + +When [installing NGINX Ingress Controller using Manifests]({{< relref "/installation/installing-nic/installation-with-manifests.md" >}}), you need to reference a GlobalConfiguration resource in the [`-global-configuration`](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-global-configuration) command-line argument. NGINX Ingress Controller only needs one GlobalConfiguration resource. + +--- + +## GlobalConfiguration specification + +The GlobalConfiguration resource defines the global configuration parameters of the Ingress Controller. Below is an example: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: GlobalConfiguration +metadata: + name: nginx-configuration + namespace: nginx-ingress +spec: + listeners: + - name: dns-udp + port: 5353 + protocol: UDP + - name: dns-tcp + port: 5353 + protocol: TCP + - name: http-8083 + port: 8083 + protocol: HTTP + - name: https-8443 + port: 8443 + protocol: HTTP + ssl: true +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +| *listeners* | A list of listeners. | [listener](#listener) | No | +{{}} + +### Listener + +The `listeners:` key defines a listener (a combination of a protocol and a port) that NGINX will use to accept traffic for a [TransportServer]({{< relref "/configuration/transportserver-resource.md" >}}) and a [VirtualServer]({{< relref "/configuration/virtualserver-and-virtualserverroute-resources.md" >}}): + +```yaml +- name: dns-tcp + port: 5353 + protocol: TCP +- name: http-8083 + port: 8083 + protocol: HTTP +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +| *name* | The name of the listener. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``listener-123`` are valid. The name must be unique among all listeners. The name ``tls-passthrough`` is reserved for the built-in TLS Passthrough listener and cannot be used. | *string* | Yes | +| *port* | The port of the listener. The port must fall into the range ``1..65535`` with the following exceptions: ``80``, ``443``, the [status port](/nginx-ingress-controller/logging-and-monitoring/status-page), the [Prometheus metrics port](/nginx-ingress-controller/logging-and-monitoring/prometheus). Among all listeners, only a single combination of a port-protocol is allowed. | *int* | Yes | +| *protocol* | The protocol of the listener. Supported values: ``TCP``, ``UDP`` and ``HTTP``. | *string* | Yes | +| *ssl* | Configures the listener with SSL. This is currently only supported for ``HTTP`` listeners. Default value is ``false`` | *bool* | No | +| *ipv4* | Specifies the IPv4 address to listen on. | *string* | No | +| *ipv6* | Specifies the IPv6 address to listen on. | *string* | No | + +{{}} + +--- + +## Using GlobalConfiguration + +You can use the usual `kubectl` commands to work with a GlobalConfiguration resource. + +For example, the following command creates a GlobalConfiguration resource defined in `global-configuration.yaml` with the name `nginx-configuration`: + +```shell +kubectl apply -f global-configuration.yaml +``` +```shell +globalconfiguration.k8s.nginx.org/nginx-configuration created +``` + +Assuming the namespace of the resource is `nginx-ingress`, you can get the resource by running: + +```shell +kubectl get globalconfiguration nginx-configuration -n nginx-ingress +``` +```shell +NAME AGE +nginx-configuration 13s +``` + +With `kubectl get` and similar commands, you can use the short name `gc` instead of `globalconfiguration`. + +--- + +### Validation + +Two types of validation are available for the GlobalConfiguration resource: + +- *Structural validation* by `kubectl` and Kubernetes API server. +- *Comprehensive validation* by NGINX Ingress Controller. + + +#### Structural validation + +The custom resource definition for the GlobalConfiguration includes structural OpenAPI schema which describes the type of every field of the resource. + +If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for the port field of a listener), `kubectl` and Kubernetes API server will reject such a resource: + +- Example of `kubectl` validation: + + ```shell + kubectl apply -f global-configuration.yaml + ``` + ```text + error: error validating "global-configuration.yaml": error validating data: ValidationError(GlobalConfiguration.spec.listeners[0].port): invalid type for org.nginx.k8s.v1.GlobalConfiguration.spec.listeners.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + +- Example of Kubernetes API server validation: + + ```shell + kubectl apply -f global-configuration.yaml --validate=false + ``` + ```text + The GlobalConfiguration "nginx-configuration" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.listeners.port in body must be of type integer: "string" + ``` + +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. + +#### Comprehensive validation + +NGINX Ingress Controller validates the fields of a GlobalConfiguration resource. If a GlobalConfiguration resource is partially invalid, NGINX Ingress Controller use the valid listeners and emit events about invalid listeners. + +You can check if the Ingress Controller successfully applied the configuration for a GlobalConfiguration. For our `nginx-configuration` GlobalConfiguration, we can run: + +```shell +kubectl describe gc nginx-configuration -n nginx-ingress +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Updated 11s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration was updated +``` + +The events section includes a Normal event with the Updated reason that informs us that the configuration was successfully applied. + +If you create a GlobalConfiguration `nginx-configuration` with two or more listeners that have the same protocol UDP and port 53, you will get: + +```shell +kubectl describe gc nginx-configuration -n nginx-ingress +``` +```text +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Updated 55s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration was updated + Warning AddedOrUpdatedWithError 6s nginx-ingress-controller GlobalConfiguration nginx-ingress/nginx-configuration is invalid and was rejected: spec.listeners: Duplicate value: "Duplicated port/protocol combination 53/UDP" +``` + +The events section includes a Warning event with the AddedOrUpdatedWithError reason. + + +## Using IPV4 and IPV6 Addresses with GlobalConfiguration + +You can customize the IPv4 and IPv6 Address listeners in the global configuration and apply them to your VirtualServer resources. See the corresponding example [here](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/custom-ip-listeners/virtualserver/) diff --git a/content/includes/nic/configuration/global-configuration/mgmt-configmap-resource.md b/content/includes/nic/configuration/global-configuration/mgmt-configmap-resource.md new file mode 100644 index 000000000..e291de510 --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/mgmt-configmap-resource.md @@ -0,0 +1,50 @@ +--- +nd-docs: DOCS-586 +doctypes: +- '' +title: Management ConfigMap resource +toc: true +weight: 300 +--- + +When using F5 NGINX Ingress Controller with NGINX Plus, it is required to pass a [command line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments" >}}) to NGINX Ingress Controller, `--mgmt-configmap=` which specifies the ConfigMap to use. The minimal required ConfigMap must have a `license-token-secret-name` key. Helm users will not need to create this map or pass the argument, it will be created with a Helm install. + +--- + +1. Create a ConfigMap file with the name *nginx-config-mgmt.yaml* and set the values +that make sense for your setup: + + ```yaml + apiVersion: v1 + kind: ConfigMap + metadata: + name: nginx-config-mgmt + namespace: nginx-ingress + data: + license-token-secret-name: "license-token" + ``` +1. Create a new (or update the existing) ConfigMap resource: + + ```shell + kubectl apply -f nginx-config-mgmt.yaml + ``` + + The [NGINX Management](https://nginx.org/en/docs/ngx_mgmt_module.html) block configuration will be updated. +--- +## Management ConfigMap keys + +{{}} +|ConfigMap Key | Description | Default | +| ---| ---| ---| +|*license-token-secret-name* | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | N/A | +|*ssl-verify* | Configures the [ssl_verify](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_verify) directive, which enables or disables verification of the usage reporting endpoint certificate. | `true` | +|*enforce-initial-report* | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | `false` | +|*usage-report-endpoint* | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NIM. | `product.connect.nginx.com` | +|*usage-report-interval* | Configures the interval of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This specifies the frequency that usage reports are sent. This field takes an [NGINX time](https://nginx.org/en/docs/syntax.html). | `1h` | +|*usage-report-proxy-host* | Configures the host name of the [proxy](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directive with optional port. | N/A | +|*ssl-trusted-certificate-secret-name* | Configures the secret used to create the file(s) referenced the in [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.org/ca`, where the `ca.crt` key contains a base64 encoded trusted cert, and the optional `ca.crl` key can contain a base64 encoded CRL. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | +|*ssl-certificate-secret-name* | Configures the secret used to create the `ssl_certificate` and `ssl_certificate_key` directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `kubernetes.io/tls`| N/A | +|*resolver-addresses* | Configures addresses used in the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive. This field takes a comma separated list of addresses. | N/A | +|*resolver-ipv6* | Configures whether the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive will look up IPv6 addresses. | `true` | +|*resolver-valid* | Configures an [NGINX time](https://nginx.org/en/docs/syntax.html) that the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive will override the TTL value of responses from nameservers with. | N/A | +{{}} diff --git a/content/includes/nic/configuration/global-configuration/reporting-resources-status.md b/content/includes/nic/configuration/global-configuration/reporting-resources-status.md new file mode 100644 index 000000000..f2e72fb03 --- /dev/null +++ b/content/includes/nic/configuration/global-configuration/reporting-resources-status.md @@ -0,0 +1,195 @@ +--- +nd-docs: DOCS-589 +doctypes: +- '' +title: Reporting resource status +toc: true +weight: 600 +--- + +This page describes how to view the status of resources managed by F5 NGINX Ingress Controller. + +## Ingress resources + +An Ingress resource status includes the address (an IP address or a DNS name), through which the hosts of that Ingress resource are publicly accessible. + +You can see the address in the output of the `kubectl get ingress` command, in the ADDRESS column, as shown below: + +```shell +kubectl get ingresses +``` +```text +NAME HOSTS ADDRESS PORTS AGE +cafe-ingress cafe.example.com 12.13.23.123 80, 443 2m +``` + +NGINX Ingress Controller must be configured to report an Ingress status: + +1. Use the command-line flag `-report-ingress-status`. +1. Define a source for an external address. This can be either of: + 1. A user defined address, specified in the `external-status-address` ConfigMap key. + 1. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. + +View the [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) topics for more information. + +{{< note >}} NGINX Ingress Controller does not clear the status of Ingress resources when it is being shut down. {{< /note >}} + +## VirtualServer and VirtualServerRoute resources + +A VirtualServer or VirtualServerRoute resource includes the status field with information about the state of the resource and the IP address, through which the hosts of that resource are publicly accessible. + +You can see the status in the output of the `kubectl get virtualservers` or `kubectl get virtualserverroutes` commands as shown below: + +```shell +kubectl get virtualservers +``` +```text + NAME STATE HOST IP PORTS AGE + cafe Valid cafe.example.com 12.13.23.123 [80,443] 34s +``` + +To see an external hostname address associated with a VirtualServer resource, use the `-o wide` option: + +```shell +kubectl get virtualservers -o wide +``` +```text + NAME STATE HOST IP EXTERNALHOSTNAME PORTS AGE + cafe Valid cafe.example.com ae430f41a1a0042908655abcdefghijkl-12345678.eu-west-2.elb.amazonaws.com [80,443] 106s +``` + +{{< note >}} If there are multiple addresses, only the first one is shown. {{< /note >}} + +In order to see additional addresses or extra information about the `Status` of the resource, use the following command: + +```shell +kubectl describe virtualserver +``` +```text +... +Status: + External Endpoints: + Ip: 12.13.23.123 + Ports: [80,443] + Message: Configuration for cafe/cafe was added or updated + Reason: AddedOrUpdated + State: Valid +``` + +### Status specification + +The following fields are reported in both VirtualServer and VirtualServerRoute status: + +{{}} +|Field | Description | Type | +| ---| ---| --- | +|*State* | Current state of the resource. Can be ``Valid``, ``Warning`` an ``Invalid``. For more information, refer to the ``message`` field. | *string* | +|*Reason* | The reason of the last update. | *string* | +|*Message* | Additional information about the state. | *string* | +|*ExternalEndpoints* | A list of external endpoints for which the hosts of the resource are publicly accessible. | *[externalEndpoint](#externalendpoint)* | +{{}} + +The *ReferencedBy* field is reported for the VirtualServerRoute status only: + +{{}} +|Field | Description | Type | +| ---| ---| --- | +| *ReferencedBy* | The VirtualServer that references this VirtualServerRoute. Format as ``namespace/name`` | *string* | +{{}} + +### externalEndpoint + +{{}} +|Field | Description | Type | +| ---| ---| --- | +|``IP`` | The external IP address. | ``string`` | +|``Hostname`` | The external LoadBalancer Hostname address. | ``string`` | +|``Ports`` | A list of external ports. | ``string`` | +{{}} + +NGINX Ingress Controller must be configured to report a VirtualServer or VirtualServerRoute status: + +1. If you want NGINX Ingress Controller to report the `externalEndpoints`, define a source for an external address (The rest of the fields will be reported without the external address configured). This can be: + 1. A user defined address, specified in the `external-status-address` ConfigMap key. + 1. A Service of the type LoadBalancer configured with an external IP or address and specified by the `-external-service` command-line flag. + +View the [ConfigMap keys](/nginx-ingress-controller/configuration/global-configuration/configmap-resource) and [Command-line arguments](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments) topics for more information. + +{{< note >}} NGINX Ingress Controller does not clear the status of VirtualServer and VirtualServerRoute resources when it is being shut down. {{< /note >}} + +## Policy resources + +A Policy resource includes the status field with information about the state of the resource. + +You can see the status in the output of the `kubectl get policy` command as shown below: + +```shell +kubectl get policy +``` +```text + NAME STATE AGE + webapp-policy Valid 30s +``` + +In order to see additional addresses or extra information about the `Status` of the resource, use the following command: + +```shell +kubectl describe policy +``` +```text +... +Status: + Message: Configuration for default/webapp-policy was added or updated + Reason: AddedOrUpdated + State: Valid +``` + +### Status specification + +The following fields are reported in Policy status: + +{{}} +|Field | Description | Type | +| ---| ---| --- | +|``State`` | Current state of the resource. Can be ``Valid`` or ``Invalid``. For more information, refer to the ``message`` field. | ``string`` | +|``Reason`` | The reason of the last update. | ``string`` | +|``Message`` | Additional information about the state. | ``string`` | +{{}} + +## TransportServer resources + +A TransportServer resource includes the status field with information about the state of the resource. + +You can see the status in the output of the `kubectl get transportserver` command as shown below: + +```shell +kubectl get transportserver +``` +```text + NAME STATE REASON AGE + dns-tcp Valid AddedOrUpdated 47m +``` + +To see additional addresses or extra information about the `Status` of the resource, use the following command: + +```shell +kubectl describe transportserver +``` +```text +Status: + Message: Configuration for default/dns-tcp was added or updated + Reason: AddedOrUpdated + State: Valid +``` + +### Status specification + +The following fields are reported in TransportServer status: + +{{}} +|Field | Description | Type | +| ---| ---| --- | +| *State* | Current state of the resource. Can be ``Valid``, ``Warning`` or ``Invalid``. For more information, refer to the ``message`` field. | *string* | +| *Reason* | The reason of the last update. | *string* | +| *Message* | Additional information about the state. | *string* | +{{}} diff --git a/content/includes/nic/configuration/host-and-listener-collisions.md b/content/includes/nic/configuration/host-and-listener-collisions.md new file mode 100644 index 000000000..3336bb21e --- /dev/null +++ b/content/includes/nic/configuration/host-and-listener-collisions.md @@ -0,0 +1,168 @@ +--- +title: Host and Listener collisions +toc: true +weight: 800 +nd-docs: DOCS-590 +--- + +This document explains how F5 NGINX Ingress Controller handles host and listener collisions between resources. + +--- + +## Winner Selection Algorithm + +If multiple resources contend for the same host or listener, NGINX Ingress Controller will pick the winner based on the `creationTimestamp` of the resources: the oldest resource will win. In case there are more than one oldest resource (their `creationTimestamp` is the same), NGINX Ingress Controller will choose the resource with the lexicographically smallest `uid`. + +{{< note >}} The `creationTimestamp` and `uid` fields are part of the [ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/) resource. {{< /note >}} + +--- + +## Host collisions + +A host collision occurs when multiple Ingress, VirtualServer, and TransportServer (configured for TLS Passthrough) resources configure the same `host`. NGINX Ingress Controller has two strategies for handling host collisions: + +- Choosing a single "winner" resource to handle the host. +- Merging the configuration of the conflicting resources. + +--- + +### Choosing the winner + +Consider the following two resources: + +- `cafe-ingress` Ingress: + + ```yaml + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: cafe-ingress + spec: + ingressClassName: nginx + rules: + - host: cafe.example.com + . . . + ``` + +- `cafe-virtual-server` VirtualServer: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: VirtualServer + metadata: + name: cafe-virtual-server + spec: + host: cafe.example.com + . . . + ``` + +If a user creates both resources in the cluster, a host collision will occur. NGINX Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). + +If `cafe-virtual-server` was created first, it will win the host `cafe.example.com` and NGINX Ingress Controller will reject `cafe-ingress`. This will be reflected in the events and in the resource's status field: + +```shell +kubectl describe vs cafe-virtual-server +``` +```text +... +Status: + ... + Message: Configuration for default/cafe-virtual-server was added or updated + Reason: AddedOrUpdated + State: Valid +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 9s nginx-ingress-controller Configuration for default/cafe-virtual-server was added or updated +``` + +```shell +kubectl describe ingress cafe-ingress +``` +```text +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 66s nginx-ingress-controller All hosts are taken by other resources +``` + +Similarly, if `cafe-ingress` was created first, it will win `cafe.example.com` and NGINX Ingress Controller will reject `cafe-virtual-server`. + +{{< note >}} You can configure multiple hosts for Ingress resources, and its possible that an Ingress resource can be the winner for some of its hosts and a loser for the others. + +For example, if `cafe-ingress` had an additional rule host rule for `pub.example.com`, NGINX Ingress Controller would not reject the Ingress. Instead, it would allow `cafe-ingress` to handle `pub.example.com`. {{< /note >}} + +--- + +### Merging configuration for the same host + +It is possible to merge configuration for multiple Ingress resources for the same host. One common use case for this approach is distributing resources across multiple namespaces. + +The [Cross-namespace configuration]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md">}}) topic has more information. + +It is *not* possible to merge the configurations for multiple VirtualServer resources for the same host. However, you can split the VirtualServers into multiple VirtualServerRoute resources, which a single VirtualServer can then reference. See the [corresponding example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/cross-namespace-configuration) on GitHub. + +It is *not* possible to merge configuration for multiple TransportServer resources. + +--- + +## Listener/Host collisions + +Listener/Host collisions occur when multiple TransportServer resources (configured for TCP/UDP load balancing) specify the same combination of `spec.listener.name` and `spec.host`. + +The combination of `spec.listener.name` and `spec.host` must be unique among all TransportServer resources. If two TransportServer resources specify the same spec.listener.name and spec.host, one of them will be rejected to prevent conflicts. In the case where spec.host is not specified, it is considered an empty string. + +NGINX Ingress Controller will choose the winner, which will own that listener and host combination. + +--- + +### Choosing the winner + +Consider the following two resources: + +- `tcp-1` TransportServer: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: TransportServer + metadata: + name: tcp-1 + spec: + host: dns.example.com + listener: + name: dns-tcp + protocol: TCP + . . . + ``` + +- `tcp-2` TransportServer: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: TransportServer + metadata: + name: tcp-2 + spec: + host: dns.example.com + listener: + name: dns-tcp + protocol: TCP + . . . + ``` + +If a user creates both resources in the cluster, a listener collision will occur. As a result, NGINX Ingress Controller will pick the winner using the [winner selection algorithm](#winner-selection-algorithm). + +In our example, if `tcp-1` was created first, it will win the listener `dns-tcp` and NGINX Ingress Controller will reject `tcp-2`. This will be reflected in the events and in the resource's status field: + +```shell +kubectl describe ts tcp-2 +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 10s nginx-ingress-controller Listener dns-tcp is taken by another resource +``` + +Similarly, if `tcp-2` was created first, it will win `dns-tcp` and NGINX Ingress Controller will reject `tcp-1`. diff --git a/content/includes/nic/configuration/ingress-resources/_index.md b/content/includes/nic/configuration/ingress-resources/_index.md new file mode 100644 index 000000000..8a2b5b282 --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/_index.md @@ -0,0 +1,8 @@ +--- +title: Ingress resources +description: +weight: 200 +menu: + docs: + parent: NGINX Ingress Controller +--- diff --git a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md new file mode 100644 index 000000000..952b8ebb1 --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -0,0 +1,225 @@ +--- +nd-docs: DOCS-591 +doctypes: +- '' +title: Advanced configuration with Annotations +toc: true +weight: 200 +--- + +This topic explains how to enable advanced features in F5 NGINX Ingress Controller with Annotations. + +The Ingress resource can use basic NGINX features such as host or path-based routing and TLS termination. Advanced features like rewriting the request URI or inserting additional response headers can be enabled with Annotations. + +Outside of advanced features, Annotations are necessary for customizing NGINX behavior such as setting the value of connection timeouts. + +Customization is also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md" >}}) resources: Annotations take priority. + +## Using Annotations + +This example uses Annotations to customize the configuration for an Ingress resource: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: cafe-ingress-with-annotations + annotations: + nginx.org/proxy-connect-timeout: "30s" + nginx.org/proxy-read-timeout: "20s" + nginx.org/client-max-body-size: "4m" + nginx.org/server-snippets: | + location / { + return 302 /coffee; + } +spec: + rules: + - host: cafe.example.com + http: + paths: + - path: /tea + pathType: Prefix + backend: + service: + name: tea-svc + port: + number: 80 + - path: /coffee + pathType: Prefix + backend: + service: + name: coffee-svc + port: + number: 80 +``` + +## Validation + +NGINX Ingress Controller validates the annotations of Ingress resources. If an Ingress is invalid, NGINX Ingress Controller will reject it: the Ingress will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. + +You can check if NGINX Ingress Controller successfully applied the configuration for an Ingress resource. For the example `cafe-ingress-with-annotations` Ingress, you can run: + +```shell +kubectl describe ing cafe-ingress-with-annotations +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 3s nginx-ingress-controller Configuration for default/cafe-ingress-with-annotations was added or updated +``` + +The events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. + +If you create an invalid Ingress, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create an Ingress `cafe-ingress-with-annotations`, with an annotation `nginx.org/redirect-to-https` set to `yes please` instead of `true`, you will get: + +```shell +kubectl describe ing cafe-ingress-with-annotations +``` +```text +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 13s nginx-ingress-controller annotations.nginx.org/redirect-to-https: Invalid value: "yes please": must be a boolean +``` + +Note how the events section includes a Warning event with the Rejected reason. + +{{< note >}} If you make an existing Ingress invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. {{< /note >}} + +The `nginx.com/jwt-token` Ingress annotation has limited validation. + +## Summary of Annotations + +The table below summarizes the available annotations. + +{{< note >}} Annotations that start with `nginx.com` are only supported with NGINX Plus. {{< /note >}} + +### General customization + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/proxy-connect-timeout* | *proxy-connect-timeout* | Sets the value of the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) and [grpc_connect_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_connect_timeout) directive. | *60s* | | +| *nginx.org/proxy-read-timeout* | *proxy-read-timeout* | Sets the value of the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) and [grpc_read_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_read_timeout) directive. | *60s* | | +| *nginx.org/proxy-send-timeout* | *proxy-send-timeout* | Sets the value of the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) and [grpc_send_timeout](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_send_timeout) directive. | *60s* | | +| *nginx.org/client-max-body-size* | *client-max-body-size* | Sets the value of the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. | *1m* | | +| *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | +| *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | +| *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | +| *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#server_tokens) directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the β€œServer” field. | *True* | | +| *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/path-regex) | +{{}} + +### Request URI/Header Manipulation + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/proxy-hide-headers* | *proxy-hide-headers* | Sets the value of one or more [proxy_hide_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directives. Example: ``"nginx.org/proxy-hide-headers": "header-a,header-b"* | N/A | | +| *nginx.org/proxy-pass-headers* | *proxy-pass-headers* | Sets the value of one or more [proxy_pass_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directives. Example: ``"nginx.org/proxy-pass-headers": "header-a,header-b"* | N/A | | +| *nginx.org/rewrites* | N/A | Configures URI rewriting using [proxy_pass](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive. | N/A | [rewrites](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/rewrites) | +|*nginx.org/proxy-set-headers* | N/A | Enables customization of proxy headers and values using the [proxy_set_header](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive. Example: ``"nginx.org/proxy-set-headers": "header-a: valueA,header-b: valueB,header-c: valueC"`` | N/A | [Proxy Set Headers](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/proxy-set-headers). | +{{}} + +### Auth and SSL/TLS + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/redirect-to-https* | *redirect-to-https* | Sets the 301 redirect rule based on the value of the ``http_x_forwarded_proto* header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of NGINX Ingress Controller β€” see [115](https://github.com/nginx/kubernetes-ingress/issues/115) | *False* | | +| *ingress.kubernetes.io/ssl-redirect* | *ssl-redirect* | Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. | *True* | | +| *nginx.org/hsts* | *hsts* | Enables [HTTP Strict Transport Security (HSTS)](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/)\ : the HSTS header is added to the responses from backends. The ``preload* directive is included in the header. | *False* | | +| *nginx.org/hsts-max-age* | *hsts-max-age* | Sets the value of the ``max-age* directive of the HSTS header. | *2592000* (1 month) | | +| *nginx.org/hsts-include-subdomains* | *hsts-include-subdomains* | Adds the ``includeSubDomains* directive to the HSTS header. | *False* | | +| *nginx.org/hsts-behind-proxy* | *hsts-behind-proxy* | Enables HSTS based on the value of the ``http_x_forwarded_proto* request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of NGINX Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the ``nginx.org/redirect-to-https* annotation. | *False* | | +| *nginx.org/basic-auth-secret* | N/A | Specifies a Secret resource with a user list for HTTP Basic authentication. | N/A | | +| *nginx.org/basic-auth-realm* | N/A | Specifies a realm. | N/A | | +| *nginx.com/jwt-key* | N/A | Specifies a Secret resource with keys for validating JSON Web Tokens (JWTs). | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/jwt). | +| *nginx.com/jwt-realm* | N/A | Specifies a realm. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/jwt). | +| *nginx.com/jwt-token* | N/A | Specifies a variable that contains a JSON Web Token. | By default, a JWT is expected in the ``Authorization* header as a Bearer Token. | [Support for JSON Web Tokens (JWTs)](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/jwt). | +| *nginx.com/jwt-login-url* | N/A | Specifies a URL to which a client is redirected in case of an invalid or missing JWT. | N/A | [Support for JSON Web Tokens (JWTs)](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/jwt). | +{{}} + +### Listeners + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/listen-ports* | N/A | Configures HTTP ports that NGINX will listen on. | *[80]* | | +| *nginx.org/listen-ports-ssl* | N/A | Configures HTTPS ports that NGINX will listen on. | *[443]* | | +{{}} + +### Backend services (Upstreams) + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/lb-method* | *lb-method* | Sets the [load balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify ``"round_robin"``. | *"random two least_conn"* | | +| *nginx.org/ssl-services* | N/A | Enables HTTPS or gRPC over SSL when connecting to the endpoints of services. | N/A | [ssl-services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/ssl-services) | +| *nginx.org/grpc-services* | N/A | Enables gRPC for services. Note: requires HTTP/2 (see ``http2* ConfigMap key); only works for Ingresses with TLS termination enabled. | N/A | [grpc-services](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/grpc-services) | +| *nginx.org/websocket-services* | N/A | Enables WebSocket for services. | N/A | [websocket](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/websocket) | +| *nginx.org/max-fails* | *max-fails* | Sets the value of the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the ``server* directive. | *1* | | +| *nginx.org/max-conns* | N\A | Sets the value of the [max_conns](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns) parameter of the ``server* directive. | *0* | | +| *nginx.org/upstream-zone-size* | *upstream-zone-size* | Sets the size of the shared memory [zone](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone) for upstreams. For NGINX, the special value 0 disables the shared memory zones. For NGINX Plus, shared memory zones are required and cannot be disabled. The special value 0 will be ignored. | *256K* | | +| *nginx.org/fail-timeout* | *fail-timeout* | Sets the value of the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the ``server* directive. | *10s* | | +| *nginx.com/sticky-cookie-services* | N/A | Configures session persistence. | N/A | [session-persistence](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/session-persistence) | +| *nginx.org/keepalive* | *keepalive* | Sets the value of the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. Note that ``proxy_set_header Connection "";* is added to the generated configuration when the value > 0. | *0* | | +| *nginx.com/health-checks* | N/A | Enables active health checks. | *False* | [health-checks](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/health-checks) | +| *nginx.com/health-checks-mandatory* | N/A | Configures active health checks as mandatory. | *False* | [health-checks](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/health-checks) | +| *nginx.com/health-checks-mandatory-queue* | N/A | When active health checks are mandatory, creates a queue where incoming requests are temporarily stored while NGINX Plus is checking the health of the endpoints after a configuration reload. | *0* | [health-checks](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/health-checks) | +| *nginx.com/slow-start* | N/A | Sets the upstream server [slow-start period](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#server-slow-start). By default, slow-start is activated after a server becomes [available](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#passive-health-checks) or [healthy](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To enable slow-start for newly-added servers, configure [mandatory active health checks](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/health-checks). | *"0s"* | | +| *nginx.org/use-cluster-ip* | N/A | Enables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like ``lb-method* and ``next-upstream``) will have no effect, as NGINX Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | *False* | | +{{}} + +### Rate limiting + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/limit-req-rate* | N/A | Enables request-rate-limiting for this ingress by creating a [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) and matching [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) for each location. All servers/locations of one ingress share the same zone. Must have unit r/s or r/m. | N/A | 200r/s | +| *nginx.org/limit-req-key* | N/A | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ${}. | ${binary_remote_addr} | ${binary_remote_addr} | +| *nginx.org/limit-req-zone-size* | N/A | Configures the size of the created [limit_req_zone](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone). | 10m | 20m | +| *nginx.org/limit-req-delay* | N/A | Configures the delay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | 0 | 100 | +| *nginx.org/limit-req-no-delay* | N/A | Configures the nodelay-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | false | true | +| *nginx.org/limit-req-burst* | N/A | Configures the burst-parameter of the [limit_req](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req) directive. | N/A | 100 | +| *nginx.org/limit-req-dry-run* | N/A | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the number of excessive requests is accounted as usual in the shared memory zone. | false | true | +| *nginx.org/limit-req-log-level* | N/A | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are info, notice, warn or error. | error | info | +| *nginx.org/limit-req-reject-code* | N/A | Sets the status code to return in response to rejected requests. Must fall into the range 400..599. | 429 | 503 | +| *nginx.org/limit-req-scale* | N/A | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. Note: This will not work properly if requests from a client are not evenly distributed accross all ingress pods (sticky sessions, long lived TCP-Connections with many requests etc.). In such cases using [zone-sync]({{< ref "/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) instead would give better results. Enabling `zone-sync` will suppress this setting. | false | true | +{{}} + +### Snippets and custom templates + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *nginx.org/location-snippets* | *location-snippets* | Sets a custom snippet in location context. | N/A | | +| *nginx.org/server-snippets* | *server-snippets* | Sets a custom snippet in server context. | N/A | | +{{}} + +### App Protect WAF {#app-protect} + +{{< note >}} The App Protect annotations only work if the App Protect WAF module is [installed]({{< relref "installation/integrations/app-protect-waf/installation.md" >}}). {{< /note >}} + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *appprotect.f5.com/app-protect-policy* | N/A | The name of the App Protect Policy for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace of the Ingress Resource is used. If not specified but ``appprotect.f5.com/app-protect-enable* is true, a default policy id applied. If the referenced policy resource does not exist, or policy is invalid, this annotation will be ignored, and the default policy will be applied. | N/A | [app-protect-waf](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf) | +| *appprotect.f5.com/app-protect-enable* | N/A | Enable App Protect for the Ingress Resource. | *False* | [app-protect-waf](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf) | +| *appprotect.f5.com/app-protect-security-log-enable* | N/A | Enable the [security log](/nginx-app-protect/troubleshooting/#app-protect-logging-overview) for App Protect. | *False* | [app-protect-waf](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf) | +| *appprotect.f5.com/app-protect-security-log* | N/A | The App Protect log configuration for the Ingress Resource. Format is ``namespace/name``. If no namespace is specified, the same namespace as the Ingress Resource is used. If not specified the default is used which is: filter: ``illegal``, format: ``default``. Multiple configurations can be specified in a comma separated list. Both log configurations and destinations list (see below) must be of equal length. Configs and destinations are paired by the list indices. | N/A | [app-protect-waf](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf) | +| *appprotect.f5.com/app-protect-security-log-destination* | N/A | The destination of the security log. For more information check the [DESTINATION argument](/nginx-app-protect/troubleshooting/#app-protect-logging-overview). Multiple destinations can be specified in a comma-separated list. Both log configurations and destinations list (see above) must be of equal length. Configs and destinations are paired by the list indices. | *syslog:server=localhost:514* | [app-protect-waf](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-waf) | +{{}} + +### App Protect DoS + +{{< note >}} The App Protect DoS annotations only work if the App Protect DoS module is [installed]({{< relref "installation/integrations/app-protect-dos/installation.md" >}}). {{< /note >}} + +{{}} +|Annotation | ConfigMap Key | Description | Default | Example | +| ---| ---| ---| ---| --- | +| *appprotectdos.f5.com/app-protect-dos-resource* | N/A | Enable App Protect DoS for the Ingress Resource by specifying a [DosProtectedResource]({{< relref "installation/integrations/app-protect-dos/dos-protected.md" >}}). | N/A | [app-protect-dos](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/app-protect-dos) | +{{}} diff --git a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md new file mode 100644 index 000000000..f31e7057b --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md @@ -0,0 +1,128 @@ +--- +nd-docs: DOCS-592 +doctypes: +- '' +title: Advanced configuration with Snippets +toc: true +weight: 400 +--- + +Snippets allow you to insert raw NGINX config into different contexts of the NGINX configurations that F5 NGINX Ingress Controller generates. + +Snippets are intended for advanced NGINX users who need more control over the generated NGINX configuration, and can be used in cases where Annotations and ConfigMap entries would not apply. + + + +## Disadvantages of snippets + +Snippets are configured [using Annotations]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#snippets-and-custom-templates" >}}), but are disabled by default due to their complexity. They are also available through the [ConfigMap]({{< relref "/configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) resource. + +To use snippets, set the [`enable-snippets`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-snippets" >}}) command-line argument. + +Snippets have the following disadvantages: + +- *Complexity*. Snippets require you to: + - Understand NGINX configuration primitives and implement a correct NGINX configuration. + - Understand how NGINX Ingress Controller generates NGINX configuration so that a snippet doesn't interfere with the other features in the configuration. +- *Decreased robustness*. An incorrect snippet can invalidate NGINX configuration, causing reload failures. Until the snippet is fixed, it will prevent any new configuration updates, including updates for the other Ingress resources. +- *Security implications*. Snippets give access to NGINX configuration primitives, which are not validated by NGINX Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress resources. + +{{< note >}} If the NGINX configuration includes an invalid snippet, NGINX will continue to operate with the last valid configuration. {{< /note >}} + +## Using snippets + +The example below shows how to use snippets to customize the NGINX configuration template using annotations. + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: cafe-ingress-with-snippets + annotations: + nginx.org/server-snippets: | + location / { + return 302 /coffee; + } + nginx.org/location-snippets: | + add_header my-test-header test-value; +spec: + rules: + - host: cafe.example.com + http: + paths: + - path: /tea + pathType: Prefix + backend: + service: + name: tea-svc + port: + number: 80 + - path: /coffee + pathType: Prefix + backend: + service: + name: coffee-svc + port: + number: 80 +``` + +These snippets generate the following NGINX configuration: + +{{< note >}} The example is shortened for conciseness. {{< /note >}} + +```nginx +server { + listen 80; + + + location / { + return 302 /coffee; + } + + + location /coffee { + proxy_http_version 1.1; + + + add_header my-test-header test-value; + ... + proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-coffee-svc-80; + } + + location /tea { + proxy_http_version 1.1; + + add_header my-test-header test-value; + ... + proxy_pass http://default-cafe-ingress-with-snippets-cafe.example.com-tea-svc-80; + } +} +``` + +## Troubleshooting + +If a snippet includes an invalid NGINX configuration, NGINX Ingress Controller will fail to reload NGINX. The error will be reported in NGINX Ingress Controller logs and an event with the error will be associated with the Ingress resource: + +An example of an error from the logs: + +```text +[emerg] 31#31: unknown directive "badd_header" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54 +Event(v1.ObjectReference{Kind:"Ingress", Namespace:"default", Name:"cafe-ingress-with-snippets", UID:"f9656dc9-63a6-41dd-a499-525b0e0309bb", APIVersion:"extensions/v1beta1", ResourceVersion:"2322030", FieldPath:""}): type: 'Warning' reason: 'AddedOrUpdatedWithError' Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: "" +stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n" +finished with error: exit status 1 +``` + +An example of an event with an error (you can view events associated with the Ingress by running `kubectl describe -n nginx-ingress ingress nginx-ingress`): + +```text +Events: +Type Reason Age From Message +---- ------ ---- ---- ------- +Normal AddedOrUpdated 52m (x3 over 61m) nginx-ingress-controller Configuration for default/cafe-ingress-with-snippets was added or updated +finished with error: exit status 1 +Warning AddedOrUpdatedWithError 54s (x2 over 89s) nginx-ingress-controller Configuration for default/cafe-ingress-with-snippets was added or updated, but not applied: Error reloading NGINX for default/cafe-ingress-with-snippets: nginx reload failed: Command /usr/sbin/nginx -s reload stdout: "" +stderr: "nginx: [emerg] unknown directive \"badd_header\" in /etc/nginx/conf.d/default-cafe-ingress-with-snippets.conf:54\n" +finished with error: exit status 1 +``` + +Additionally, to help troubleshoot snippets, a number of Prometheus metrics show the stats about failed reloads – `controller_nginx_last_reload_status` and `controller_nginx_reload_errors_total`. diff --git a/content/includes/nic/configuration/ingress-resources/basic-configuration.md b/content/includes/nic/configuration/ingress-resources/basic-configuration.md new file mode 100644 index 000000000..6884e42b5 --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/basic-configuration.md @@ -0,0 +1,107 @@ +--- +title: Basic configuration +weight: 100 +toc: true +type: reference +product: NIC +nd-docs: DOCS-593 +--- + +This document shows a basic Ingress resource definition for F5 NGINX Ingress Controller. It load balances requests for two services as part of a single application. + +{{< ghcode `https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/ingress-resources/complete-example/cafe-ingress.yaml`>}} + +Here is a breakdown of what this Ingress resource definition means: + +- The `metadata.name` field defines the name of the resource `cafe‑ingress`. +- The `spec.tls` field sets up SSL/TLS termination: + - The `hosts` field applies the certificate and key to the `cafe.example.com` host. + - The `secretName` references a secret resource by its name, `cafe‑secret`. The secret must belong to the same namespace as the Ingress, of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that hold the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls>). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the hosts to which the secret is applied. +- The `spec.rules` field defines a host with the domain name `cafe.example.com`. +- The `paths` field defines two path‑based rules: + - The rule with the path `/tea` instructs NGINX to distribute the requests with the `/tea` URI among the pods of the *tea* service, which is deployed with the name `tea‑svc` in the cluster. + - The rule with the path `/coffee` instructs NGINX to distribute the requests with the `/coffee` URI among the pods of the *coffee* service, which is deployed with the name `coffee‑svc` in the cluster. + - Both rules instruct NGINX to distribute the requests to `port 80` of the corresponding service (the `servicePort` field). + +To learn more about the Ingress resource, view [the official Kubernetes documentation for Ingress resources](https://kubernetes.io/docs/concepts/services-networking/ingress/). + +{{< note >}} For complete instructions on deploying Ingress and Secret resources in the cluster, see the [complete example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/complete-example) in the GitHub repository. {{< /note >}} + +--- + +## New features available in Kubernetes 1.18 + +Starting from Kubernetes 1.18, you can use the following new features: + +- The host field supports wildcard domain names, such as `*.example.com`. +- The path supports different matching rules with the new field `pathType`, which takes the following values: `Prefix` for prefix-based matching, `Exact` for exact matching and `ImplementationSpecific`, which is the default type and is the same as `Prefix`. For example: + + ```yaml {hl_lines=[2, 7, 14]} + - path: /tea + pathType: Prefix + backend: + serviceName: tea-svc + servicePort: 80 + - path: /tea/green + pathType: Exact + backend: + service: + name: tea-svc + port: + number: 80 + - path: /coffee + pathType: ImplementationSpecific + backend: + service: + name: coffee-svc + port: + number: 80 + ``` + +- The `ingressClassName` field is now supported: + + ```yaml {hl_lines=[6]} + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: cafe-ingress + spec: + ingressClassName: nginx + tls: + - hosts: + - cafe.example.com + secretName: cafe-secret + rules: + - host: cafe.example.com + . . . + ``` + + When using this field you need to create the `IngressClass` resource with the corresponding `name`. View the [Create common resources]({{< relref "installation/installing-nic/installation-with-manifests.md#create-common-resources" >}}) section of the Installation with Manifests topic for more information. + +--- + +## Restrictions + +NGINX Ingress Controller imposes the following restrictions on Ingress resources: + +- When defining an Ingress resource, the `host` field is required. +- The `host` value needs to be unique among all Ingress and VirtualServer resources unless the Ingress resource is a [mergeable minion]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}). View the [Host and Listener collisions]({{< ref "/nic/configuration/host-and-listener-collisions.md" >}}) topic for more information. +- The `path` field in `spec.rules[].http.paths[]` is required for `Exact` and `Prefix` `pathTypes`. +- The ImplementationSpecific `pathType` is treated as equivalent to `Prefix` `pathType`, with the exception that when this `pathType` is configured, the `path` field in `spec.rules[].http.paths[]` is not mandatory. `path` defaults to `/` if not set but the `pathType` is set to ImplementationSpecific. + +--- + +## Advanced configuration + +NGINX Ingress Controller generates NGINX configuration by executing a template file that contains the configuration options. + +These options are set with the Ingress resource and NGINX Ingress Controller's ConfigMap. + +The Ingress resource only allows you to use basic NGINX features: host and path-based routing and TLS termination. + +For advanced configuration, you have two options: + +- [Annotations]({{< ref "/configuration/ingress-resources/advanced-configuration-with-annotations.md" >}}) can be used to rewrite request URIs or inserting additional response headers. +- [Snippets]({{< ref "/configuration/ingress-resources/advanced-configuration-with-snippets" >}}) can be used to insert raw NGINX configuration, changing generated files. + +Additionally, it is possible to customize the template, described in the [Custom templates]({{< relref "/configuration/global-configuration/custom-templates.md" >}}) topic. diff --git a/content/includes/nic/configuration/ingress-resources/cross-namespace-configuration.md b/content/includes/nic/configuration/ingress-resources/cross-namespace-configuration.md new file mode 100644 index 000000000..e877c906a --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/cross-namespace-configuration.md @@ -0,0 +1,14 @@ +--- +nd-docs: DOCS-594 +doctypes: +- '' +title: Cross-namespace configuration +toc: true +weight: 500 +--- + +This topic explains how to spread Ingress configuration across different namespaces in F5 NGINX Ingress Controller. + +You can spread the Ingress configuration for a common host across multiple Ingress resources using Mergeable Ingress resources. Such resources can belong to the *same* or *different* namespaces. This enables easier management when using a large number of paths. See the [Mergeable Ingress Resources](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/mergeable-ingress-types) example in our GitHub repo. + +As an alternative to Mergeable Ingress resources, you can use [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/) for cross-namespace configuration. See the [Cross-Namespace Configuration](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/cross-namespace-configuration) example in our GitHub repo. diff --git a/content/includes/nic/configuration/ingress-resources/custom-annotations.md b/content/includes/nic/configuration/ingress-resources/custom-annotations.md new file mode 100644 index 000000000..9cd6621de --- /dev/null +++ b/content/includes/nic/configuration/ingress-resources/custom-annotations.md @@ -0,0 +1,146 @@ +--- +nd-docs: DOCS-595 +doctypes: +- '' +title: Custom annotations +toc: true +weight: 300 +--- + +This topic explains how you can use custom annotations with F5 NGINX Ingress Controller. + +Custom annotations enable you to quickly extend the Ingress resource to support many advanced features of NGINX, such as rate limiting, caching, etc. + +## Overview + +NGINX Ingress Controller supports a number of annotations for the Ingress resource that fine tune NGINX configuration (for example, connection timeouts) or enable additional features (for example, JWT validation). The complete list of annotations is available [here](/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations). + +The annotations are provided only for the most common features and use cases, meaning that not every NGINX feature or a customization option is available through the annotations. Additionally, even if an annotation is available, it might not give you the satisfactory level of control of a particular NGINX feature. + +Custom annotations allow you to add an annotation for an NGINX feature that is not available as a regular annotation. In contrast with regular annotations, to add a custom annotation, you don't need to modify the Ingress Controller source code -- just modify the template. Additionally, with a custom annotation, you get full control of how the feature is implemented in NGINX configuration. + +## Usage + +The Ingress Controller generates NGINX configuration for Ingress resources by executing a configuration template. See [NGINX template](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/internal/configs/version1/nginx.ingress.tmpl) or [NGINX Plus template](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/internal/configs/version1/nginx-plus.ingress.tmpl). + +To support custom annotations, the template has access to the information about the Ingress resource - its *name*, *namespace* and *annotations*. It is possible to check if a particular annotation present in the Ingress resource and conditionally insert NGINX configuration directives at multiple NGINX contexts - `http`, `server`, `location` or `upstream`. Additionally, you can get the value that is set to the annotation. + +Consider the following excerpt from the template, which was extended to support two custom annotations: + +```jinja2 +# This is the configuration for {{$.Ingress.Name}}/{{$.Ingress.Namespace}} + +{{if index $.Ingress.Annotations "custom.nginx.org/feature-a"}} +# Insert config for feature A if the annotation is set +{{end}} + +{{with $value := index $.Ingress.Annotations "custom.nginx.org/feature-b"}} +# Insert config for feature B if the annotation is set +# Print the value assigned to the annotation: {{$value}} +{{end}} +``` + +Consider the following Ingress resource and note how we set two annotations: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: example-ingress + namespace: production + annotations: + custom.nginx.org/feature-a: "on" + custom.nginx.org/feature-b: "512" +spec: + rules: + - host: example.com + . . . +``` + +Assuming that the Ingress Controller is using that customized template, it will generate a config for the Ingress resource that will include the following part, generated by our template excerpt: + +```yaml +# This is the configuration for cafe-ingress/default + +# Insert config for feature A if the annotation is set + + + +# Insert config for feature B if the annotation is set +# Print the value assigned to the annotation: 512 +``` + +**Notes**: + +- You can customize the template to insert you custom annotations via [custom templates](/nginx-ingress-controller/configuration/global-configuration/custom-templates). +- The Ingress Controller uses go templates to generate NGINX config. You can read more information about go templates [here](https://golang.org/pkg/text/template/). + +See the examples in the next section that use custom annotations to configure NGINX features. + +### Custom Annotations with Mergeable Ingress Resources + +A Mergeable Ingress resource consists of multiple Ingress resources - one master and one or several minions. Read more about Mergeable Ingress resources [here](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration). + +If you'd like to use custom annotations with Mergeable Ingress resources, please keep the following in mind: + +- Custom annotations can be used in the Master and in Minions. For Minions, you can access them in the template only when processing locations. + + If you access `$.Ingress` anywhere in the Ingress template, you will get the master Ingress resource. To access a Minion Ingress resource, use `$location.MinionIngress`. However, it is only available when processing locations: + + ```jinja2 + {{range $location := $server.Locations}} + location {{$location.Path}} { + {{with $location.MinionIngress}} + # location for minion {{$location.MinionIngress.Namespace}}/{{$location.MinionIngress.Name}} + {{end}} + } {{end}} + ``` + + **Note**: `$location.MinionIngress` is a pointer. When a regular Ingress resource is processed in the template, the value of the pointer is `nil`. Thus, it is important that you check that `$location.MinionIngress` is not `nil` as in the example above using the `with` action. + +- Minions do not inherent custom annotations of the master. + +### Helper Functions + +Helper functions can be used in the Ingress template to parse the values of custom annotations. + +{{% table %}} +| Function | Input Arguments | Return Arguments | Description | +| ---| ---| ---| --- | +| ``split`` | ``s, sep string`` | ``[]string`` | Splits the string ``s`` into a slice of strings separated by the ``sep``. | +| ``trim`` | ``s string`` | ``string`` | Trims the trailing and leading whitespace from the string ``s``. | +| ``contains`` | ``s, substr string`` | ``bool`` | Tests whether the string ``substr`` is a substring of the string ``s``. | +| ``hasPrefix`` | ``s, prefix string`` | ``bool`` | Tests whether the string ``prefix`` is a prefix of the string ``s``. | +| ``hasSuffix`` | ``s, suffix string`` | ``bool`` | Tests whether the string ``suffix`` is a suffix of the string ``s``. | +| ``toLower`` | ``s string`` | ``bool`` | Converts all letters in the string ``s`` to their lower case. | +| ``toUpper`` | ``s string`` | ``bool`` | Converts all letters in the string ``s`` to their upper case. | +| ``replaceAll`` | ``s, old, new string`` | ``string`` | Replaces all occurrences of ``old`` with ``new`` in the string ``s``. | +{{% /table %}} + +Consider the following custom annotation `custom.nginx.org/allowed-ips`, which expects a comma-separated list of IP addresses: + +```yaml +annotations: + custom.nginx.org/allowed-ips: "192.168.1.3, 10.0.0.13" +``` + + The helper functions can parse the value of the `custom.nginx.org/allowed-ips` annotation, so that in the template you can use each IP address separately. Consider the following template excerpt: + +```jinja2 +{{range $ip := split (index $.Ingress.Annotations "custom.nginx.org/allowed-ips") ","}} + allow {{trim $ip}}; +{{end}} +deny all; +``` + +The template excerpt will generate the following configuration: + +``` +allow 192.168.1.3; +allow 10.0.0.13; +deny all; +``` + +## Example + +See the [custom annotations example](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/ingress-resources/custom-annotations). diff --git a/content/includes/nic/configuration/policy-resource.md b/content/includes/nic/configuration/policy-resource.md new file mode 100644 index 000000000..5de80b1c1 --- /dev/null +++ b/content/includes/nic/configuration/policy-resource.md @@ -0,0 +1,945 @@ +--- +title: Policy resources +weight: 500 +toc: true +type: how-to +product: NIC +nd-docs: DOCS-596 +--- + +The Policy resource allows you to configure features like access control and rate-limiting, which you can add to your [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/). + +The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +This document is the reference documentation for the Policy resource. An example of a Policy for access control is available in our [GitHub repository](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/custom-resources/access-control). + +## Prerequisites + +Policies work together with [VirtualServer and VirtualServerRoute resources](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/), which you need to create separately. + +## Policy Specification + +Below is an example of a policy that allows access for clients from the subnet `10.0.0.0/8` and denies access for any other clients: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: allow-localhost +spec: + accessControl: + allow: + - 10.0.0.0/8 +``` + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``accessControl`` | The access control policy based on the client IP address. | [accessControl](#accesscontrol) | No | +|``ingressClassName`` | Specifies which instance of NGINX Ingress Controller must handle the Policy resource. | ``string`` | No | +|``rateLimit`` | The rate limit policy controls the rate of processing requests per a defined key. | [rateLimit](#ratelimit) | No | +|``apiKey`` | The API Key policy configures NGINX to authorize requests which provide a valid API Key in a specified header or query param. | [apiKey](#apikey) | No | +|``basicAuth`` | The basic auth policy configures NGINX to authenticate client requests using HTTP Basic authentication credentials. | [basicAuth](#basicauth) | No | +|``jwt`` | The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. | [jwt](#jwt) | No | +|``ingressMTLS`` | The IngressMTLS policy configures client certificate verification. | [ingressMTLS](#ingressmtls) | No | +|``egressMTLS`` | The EgressMTLS policy configures upstreams authentication and certificate verification. | [egressMTLS](#egressmtls) | No | +|``waf`` | The WAF policy configures WAF and log configuration policies for [NGINX AppProtect]({{< relref "installation/integrations/app-protect-waf/configuration.md" >}}) | [WAF](#waf) | No | +{{% /table %}} + +\* A policy must include exactly one policy. + +### AccessControl + +The access control policy configures NGINX to deny or allow requests from clients with the specified IP addresses/subnets. + +For example, the following policy allows access for clients from the subnet `10.0.0.0/8` and denies access for any other clients: + +```yaml +accessControl: + allow: + - 10.0.0.0/8 +``` + +In contrast, the policy below does the opposite: denies access for clients from `10.0.0.0/8` and allows access for any other clients: + +```yaml +accessControl: + deny: + - 10.0.0.0/8 +``` +{{< note >}} + +The feature is implemented using the NGINX [ngx_http_access_module](http://nginx.org/en/docs/http/ngx_http_access_module.html). NGINX Ingress Controller access control policy supports either allow or deny rules, but not both (as the module does). + +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``allow`` | Allows access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | +|``deny`` | Denies access for the specified networks or addresses. For example, ``192.168.1.1`` or ``10.1.1.0/16``. | ``[]string`` | No | \* an accessControl must include either `allow` or `deny`. | +{{% /table %}} + +#### AccessControl Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple access control policies. For example, here we reference two policies, each with configured allow lists: + +```yaml +policies: +- name: allow-policy-one +- name: allow-policy-two +``` + +When you reference more than one access control policy, NGINX Ingress Controller will merge the contents into a single allow list or a single deny list. + +Referencing both allow and deny policies, as shown in the example below, is not supported. If both allow and deny lists are referenced, NGINX Ingress Controller uses just the allow list policies. + +```yaml +policies: +- name: deny-policy +- name: allow-policy-one +- name: allow-policy-two +``` + +### RateLimit + +The rate limit policy configures NGINX to limit the processing rate of requests. + +For example, the following policy will limit all subsequent requests coming from a single IP address once a rate of 10 requests per second is exceeded: + +```yaml +rateLimit: + rate: 10r/s + zoneSize: 10M + key: ${binary_remote_addr} +``` +{{< note >}} + +The feature is implemented using the NGINX [ngx_http_limit_req_module](https://nginx.org/en/docs/http/ngx_http_limit_req_module.html). + +{{< /note >}} + +{{< note >}} + +When the [Zone Sync feature]({{< ref "/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) is enabled with NGINX Plus, the rate limiting zone will be synchronized across all replicas in the cluster. This means all replicas are aware of the requests that have been rate limited by other replicas in the cluster. + +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``rate`` | The rate of requests permitted. The rate is specified in requests per second (r/s) or requests per minute (r/m). | ``string`` | Yes | +|``key`` | The key to which the rate limit is applied. Can contain text, variables, or a combination of them. Variables must be surrounded by ``${}``. For example: ``${binary_remote_addr}``. Accepted variables are ``$binary_remote_addr``, ``$request_uri``,``$request_method``, ``$url``, ``$http_``, ``$args``, ``$arg_``, ``$cookie_``, ``$jwt_claim_``. | ``string`` | Yes | +|``zoneSize`` | Size of the shared memory zone. Only positive values are allowed. Allowed suffixes are ``k`` or ``m``, if none are present ``k`` is assumed. | ``string`` | Yes | +|``delay`` | The delay parameter specifies a limit at which excessive requests become delayed. If not set all excessive requests are delayed. | ``int`` | No | +|``noDelay`` | Disables the delaying of excessive requests while requests are being limited. Overrides ``delay`` if both are set. | ``bool`` | No | +|``burst`` | Excessive requests are delayed until their number exceeds the ``burst`` size, in which case the request is terminated with an error. | ``int`` | No | +|``dryRun`` | Enables the dry run mode. In this mode, the rate limit is not actually applied, but the number of excessive requests is accounted as usual in the shared memory zone. | ``bool`` | No | +|``logLevel`` | Sets the desired logging level for cases when the server refuses to process requests due to rate exceeding, or delays request processing. Allowed values are ``info``, ``notice``, ``warn`` or ``error``. Default is ``error``. | ``string`` | No | +|``rejectCode`` | Sets the status code to return in response to rejected requests. Must fall into the range ``400..599``. Default is ``503``. | ``int`` | No | +|``scale`` | Enables a constant rate-limit by dividing the configured rate by the number of nginx-ingress pods currently serving traffic. This adjustment ensures that the rate-limit remains consistent, even as the number of nginx-pods fluctuates due to autoscaling. **This will not work properly if requests from a client are not evenly distributed across all ingress pods** (Such as with sticky sessions, long lived TCP Connections with many requests, and so forth). In such cases using [zone-sync]({{< ref "/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) instead would give better results. Enabling `zone-sync` will suppress this setting. | ``bool`` | No | +|``condition`` | Add a condition to a rate-limit policy. | [ratelimit.condition](#ratelimitcondition) | No | +{{% /table %}} + +{{< note >}} + +For each policy referenced in a VirtualServer and/or its VirtualServerRoutes, NGINX Ingress Controller will generate a single rate limiting zone defined by the [`limit_req_zone`](http://nginx.org/en/docs/http/ngx_http_limit_req_module.html#limit_req_zone) directive. If two VirtualServer resources reference the same policy, NGINX Ingress Controller will generate two different rate limiting zones, one zone per VirtualServer. + +{{< /note >}} + +#### RateLimit Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple rate limit policies. For example, here we reference two policies: + +```yaml +policies: +- name: rate-limit-policy-one +- name: rate-limit-policy-two +``` + +When you reference more than one rate limit policy, NGINX Ingress Controller will configure NGINX to use all referenced rate limits. When you define multiple policies, each additional policy inherits the `dryRun`, `logLevel`, and `rejectCode` parameters from the first policy referenced (`rate-limit-policy-one`, in the example above). + +### RateLimit.Condition + +RateLimit.Condition defines a condition for a rate limit policy. For example: + +```yaml +condition: + jwt: + claim: user_details.level + match: premium + default: true +``` + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``jwt`` | defines a JWT condition to rate limit against. | [ratelimit.condition.jwt](#ratelimitconditionjwt) | No | +|``default`` | sets the rate limit in this policy to be the default if no conditions are met. In a group of policies with the same JWT condition, only one policy can be the default. | ``bool`` | No | +{{% /table %}} + +The rate limit policy with condition is designed to be used in combination with one or more rate limit policies. For example, multiple rate limit policies with [RateLimit.Condition.JWT](#ratelimitconditionjwt) can be used to apply different tiers of rate limit based on the value of a JWT claim. For a practical example of tiered rate limiting by the value of a JWT claim, see the example in our [GitHub repository](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/rate-limit-tiered-jwt-claim/README.md). + +### RateLimit.Condition.JWT +{{< note >}} + +This feature is only available with NGINX Plus. + +{{< /note >}} + +RateLimit.Condition.JWT defines a condition for a rate limit by JWT claim. For example, here we define a condition for a rate limit policy that only applies to requests with a JWT claim `user_details.level` with a value `premium`: + +```yaml +jwt: + claim: user_details.level + match: premium +``` + +The rate limit policy will only apply to requests that contain a JWT with the specified claim and value. For example, the following JWT payload will match the JWT condition: + +```json +{ + "user_details": { + "level": "premium" + }, + "sub": "client1" +} +``` + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``claim`` | Claim is the JWT claim to be rate limit by. Nested claims should be separated by ".". | ``string`` | Yes | +|``match`` | the value of the claim to match against. | ``string`` | Yes | +{{% /table %}} + +### APIKey + +The API Key auth policy configures NGINX to authorize client requests based on the presence of a valid API Key in a header or query param specified in the policy. + +{{< note >}} + +The feature is implemented using NGINX [ngx_http_auth_request_module](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) and [NGINX JavaScript (NJS)](https://nginx.org/en/docs/njs/). + +{{< /note >}} + +The policies' API keys are securely stored using SHA-256 hashing. When a client sends an API Key, it is hashed by NJS and then compared to the hashed API Key in the NGINX config. + +If the hashed keys match, the NGINX JavaScript (NJS) subrequest issues a 204 No Content response to the `auth_request` directive, indicating successful authorization. Conversely, if no API Key is provided in the specified header or query parameter, a 401 Unauthorized response is returned. Similarly, if an invalid key is presented in the expected header or query parameter, a 403 Forbidden response is issued, denying access. + +It is possible to use the [errorPages](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#errorpage) property on a route, to change the default behaviour of 401 or 403 errors. + +At least one header or query param is required. + +The policy below configures NGINX Ingress Controller to require the API Key `password` in the header "my-header". + +```yaml +apiKey: + suppliedIn: + header: + - "my-header" + clientSecret: api-key-secret +``` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: api-key-secret +type: nginx.org/apikey +data: + client1: cGFzc3dvcmQ= # password +``` + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``suppliedIn`` | `header` or `query`. | | Yes | +|``suppliedIn.header`` | An array of headers that the API Key may appear in. | ``string[]`` | No | +|``suppliedIn.query`` | An array of query params that the API Key may appear in. | ``string[]`` | No | +|``clientSecret`` | The name of the Kubernetes secret that stores the API Key(s). It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/apikey``, and the API Key(s) must be stored in a key: val format where each key is a unique clientID and each value is a unique base64 encoded API Key | ``string`` | Yes | +{{% /table %}} + +{{}}An APIKey Policy must include a minimum of one of the `suppliedIn.header` or `suppliedIn.query` parameters. Both can also be supplied.{{}} + +#### APIKey Merging Behavior + +A VirtualServer or VirtualServerRoute can be associated with only one API Key policy per route or subroute. However, it is possible to replace an API Key policy from a higher-level with a different policy defined on a more specific route. + +For example, a VirtualServer can implement different API Key policies at various levels. In the configuration below, the server-wide api-key-policy-server applies to /backend1 for authorization, as it lacks a more specific policy. Meanwhile, /backend2 uses the api-key-policy-route defined at the route level. + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: virtual-server +spec: + host: virtual-server.example.com + policies: + - name: api-key-policy-server + upstreams: + - name: backend2 + service: backend2-svc + port: 80 + - name: backend1 + service: backend1-svc + port: 80 + routes: + - path: /backend1 + action: + pass: backend1 + - path: /backend2 + action: + pass: backend2 + policies: + - name: api-key-policy-route +``` + +### BasicAuth + +The basic auth policy configures NGINX to authenticate client requests using the [HTTP Basic authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). + +For example, the following policy will reject all requests that do not include a valid username/password combination in the HTTP header `Authentication` + +```yaml +basicAuth: + secret: htpasswd-secret + realm: "My API" +``` +{{< note >}} +The feature is implemented using the NGINX [ngx_http_auth_basic_module](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of the Kubernetes secret that stores the Htpasswd configuration. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/htpasswd``, and the config must be stored in the secret under the key ``htpasswd``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``realm`` | The realm for the basic authentication. | ``string`` | No | +{{% /table %}} + +#### BasicAuth Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple basic auth policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: basic-auth-policy-one +- name: basic-auth-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `basic-auth-policy-one`, and ignores `basic-auth-policy-two`. + +### JWT Using Local Kubernetes Secret + +{{< note >}} + +This feature is only available with NGINX Plus. + +{{< /note >}} + +The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens. + +The following example policy will reject all requests that do not include a valid JWT in the HTTP header `token`: + +```yaml +jwt: + secret: jwk-secret + realm: "My API" + token: $http_token +``` + +You can pass the JWT claims and JOSE headers to the upstream servers. For example: + +```yaml +action: + proxy: + upstream: webapp + requestHeaders: + set: + - name: user + value: ${jwt_claim_user} + - name: alg + value: ${jwt_header_alg} +``` + +We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#actionproxy) to set the values of two headers that NGINX will pass to the upstream servers. + +The value of the `${jwt_claim_user}` variable is the `user` claim of a JWT. For other claims, use `${jwt_claim_name}`, where `name` is the name of the claim. Note that nested claims and claims that include a period (`.`) are not supported. Similarly, use `${jwt_header_name}` where `name` is the name of a header. In our example, we use the `alg` header. + +{{< note >}} + +This feature is implemented using the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). + +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/jwk``, and the JWK must be stored in the secret under the key ``jwk``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``realm`` | The realm of the JWT. | ``string`` | Yes | +|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | +{{% /table %}} + +#### JWT Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple JWT policies. However, only one can be applied: every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: jwt-policy-one +- name: jwt-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `jwt-policy-one`, and ignores `jwt-policy-two`. + +### JWT Using JWKS From Remote Location + +{{< note >}} + +This feature is only available with NGINX Plus. + +{{< /note >}} + +The JWT policy configures NGINX Plus to authenticate client requests using JSON Web Tokens, allowing import of the keys (JWKS) for JWT policy by means of a URL (for a remote server or an identity provider) as a result they don't have to be copied and updated to the IC pod. + +The following example policy will reject all requests that do not include a valid JWT in the HTTP header fetched from the identity provider: + +```yaml +jwt: + realm: MyProductAPI + token: $http_token + jwksURI: + keyCache: 1h +``` + +{{< note >}} + +This feature is implemented using the NGINX Plus directive [auth_jwt_key_request](http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html#auth_jwt_key_request) under [ngx_http_auth_jwt_module](https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html). + +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | +|``keyCache`` | Enables in-memory caching of JWKS (JSON Web Key Sets) that are obtained from the ``jwksURI`` and sets a valid time for expiration. | ``string`` | Yes | +|``realm`` | The realm of the JWT. | ``string`` | Yes | +|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | +{{% /table %}} + +{{< note >}} + +Content caching is enabled by default for each JWT policy with a default time of 12 hours. + +This is done to ensure to improve resiliency by allowing the JWKS (JSON Web Key Set) to be retrieved from the cache even when it has expired. + +{{< /note >}} + +#### JWT Merging Behavior + +This behavior is similar to using a local Kubernetes secret where a VirtualServer/VirtualServerRoute can reference multiple JWT policies. However, only one can be applied: every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: jwt-policy-one +- name: jwt-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `jwt-policy-one`, and ignores `jwt-policy-two`. + +### IngressMTLS + +The IngressMTLS policy configures client certificate verification. + +For example, the following policy will verify a client certificate using the CA certificate specified in the `ingress-mtls-secret`: + +```yaml +ingressMTLS: + clientCertSecret: ingress-mtls-secret + verifyClient: "on" + verifyDepth: 1 +``` + +Below is an example of the `ingress-mtls-secret` using the secret type `nginx.org/ca` + +```yaml +kind: Secret +metadata: + name: ingress-mtls-secret +apiVersion: v1 +type: nginx.org/ca +data: + ca.crt: +``` + +A VirtualServer that references an IngressMTLS policy must: + +- Enable [TLS termination](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualservertls). +- Reference the policy in the VirtualServer [`spec`](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserver-specification). It is not allowed to reference an IngressMTLS policy in a [`route`](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserverroute) or in a VirtualServerRoute [`subroute`](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#virtualserverroutesubroute). + +If the conditions above are not met, NGINX will send the `500` status code to clients. + +You can pass the client certificate details, including the certificate, to the upstream servers. For example: + +```yaml +action: + proxy: + upstream: webapp + requestHeaders: + set: + - name: client-cert-subj-dn + value: ${ssl_client_s_dn} # subject DN + - name: client-cert + value: ${ssl_client_escaped_cert} # client certificate in the PEM format (urlencoded) +``` + +We use the `requestHeaders` of the [Action.Proxy](/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/#actionproxy) to set the values of the two headers that NGINX will pass to the upstream servers. See the [list of embedded variables](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables) that are supported by the `ngx_http_ssl_module`, which you can use to pass the client certificate details. + +{{< note >}} + + The feature is implemented using the NGINX [ngx_http_ssl_module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html). + + {{< /note >}} + +#### Using a Certificate Revocation List + +The IngressMTLS policy supports configuring at CRL for your policy. +This can be done in one of two ways. + +{{< note >}} + + Only one of these configurations options can be used at a time. + +{{< /note >}} + +1. Adding the `ca.crl` field to the `nginx.org/ca` secret type, which accepts a base64 encoded certificate revocation list (crl). + Example YAML: + +```yaml +kind: Secret +metadata: + name: ingress-mtls-secret +apiVersion: v1 +type: nginx.org/ca +data: + ca.crt: + ca.crl: +``` + +2. Adding the `crlFileName` field to your IngressMTLS policy spec with the name of the CRL file. + +{{< note >}} + +This configuration option should only be used when using a CRL that is larger than 1MiB. + +Otherwise we recommend using the `nginx.org/ca` secret type for managing your CRL. + +{{< /note >}} + +Example YAML: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: Policy +metadata: + name: ingress-mtls-policy +spec: +ingressMTLS: + clientCertSecret: ingress-mtls-secret + crlFileName: webapp.crl + verifyClient: "on" + verifyDepth: 1 +``` + +**IMPORTANT NOTE** +When configuring a CRL with the `ingressMTLS.crlFileName` field, there is additional context to keep in mind: + +1. NGINX Ingress Controller will expect the CRL, in this case `webapp.crl`, will be in `/etc/nginx/secrets`. A volume mount will need to be added to NGINX Ingress Controller deployment add your CRL to `/etc/nginx/secrets` +2. When updating the content of your CRL (e.g a new certificate has been revoked), NGINX will need to be reloaded to pick up the latest changes. Depending on your environment this may require updating the name of your CRL and applying this update to your `ingress-mtls.yaml` policy to ensure NGINX picks up the latest CRL. + +Please refer to the Kubernetes documentation on [volumes](https://kubernetes.io/docs/concepts/storage/volumes/) to find the best implementation for your environment. + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``verifyClient`` | Verification for the client. Possible values are ``"on"``, ``"off"``, ``"optional"``, ``"optional_no_ca"``. The default is ``"on"``. | ``string`` | No | +|``verifyDepth`` | Sets the verification depth in the client certificates chain. The default is ``1``. | ``int`` | No | +|``crlFileName`` | The file name of the Certificate Revocation List. NGINX Ingress Controller will look for this file in `/etc/nginx/secrets` | ``string`` | No | +{{% /table %}} + +#### IngressMTLS Merging Behavior + +A VirtualServer can reference only a single IngressMTLS policy. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: ingress-mtls-policy-one +- name: ingress-mtls-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `ingress-mtls-policy-one`, and ignores `ingress-mtls-policy-two`. + +### EgressMTLS + +The EgressMTLS policy configures upstreams authentication and certificate verification. + +For example, the following policy will use `egress-mtls-secret` to authenticate with the upstream application and `egress-trusted-ca-secret` to verify the certificate of the application: + +```yaml +egressMTLS: + tlsSecret: egress-mtls-secret + trustedCertSecret: egress-trusted-ca-secret + verifyServer: on + verifyDepth: 2 +``` + +{{< note >}} + +The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html). + +{{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. The secret must be of the type ``kubernetes.io/tls``, the certificate must be stored in the secret under the key ``tls.crt``, and the key must be stored under the key ``tls.key``, otherwise the secret will be rejected as invalid. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``, otherwise the secret will be rejected as invalid. | ``string`` | No | +|``verifyServer`` | Enables verification of the upstream HTTPS server certificate. | ``bool`` | No | +|``verifyDepth`` | Sets the verification depth in the proxied HTTPS server certificates chain. The default is ``1``. | ``int`` | No | +|``sessionReuse`` | Enables reuse of SSL sessions to the upstreams. The default is ``true``. | ``bool`` | No | +|``serverName`` | Enables passing of the server name through ``Server Name Indication`` extension. | ``bool`` | No | +|``sslName`` | Allows overriding the server name used to verify the certificate of the upstream HTTPS server. | ``string`` | No | +|``ciphers`` | Specifies the enabled ciphers for requests to an upstream HTTPS server. The default is ``DEFAULT``. | ``string`` | No | +|``protocols`` | Specifies the protocols for requests to an upstream HTTPS server. The default is ``TLSv1 TLSv1.1 TLSv1.2``. | ``string`` | No | > Note: the value of ``ciphers`` and ``protocols`` is not validated by NGINX Ingress Controller. As a result, NGINX can fail to reload the configuration. To ensure that the configuration for a VirtualServer/VirtualServerRoute that references the policy was successfully applied, check its [status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status/#virtualserver-and-virtualserverroute-resources). The validation will be added in the future releases. | +{{% /table %}} + +#### EgressMTLS Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple EgressMTLS policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: egress-mtls-policy-one +- name: egress-mtls-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `egress-mtls-policy-one`, and ignores `egress-mtls-policy-two`. + +### OIDC + +{{< tip >}} + +This feature is disabled by default. To enable it, set the [enable-oidc]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-oidc" >}}) command-line argument of NGINX Ingress Controller. + +{{< /tip >}} + +The OIDC policy configures NGINX Plus as a relying party for OpenID Connect authentication. + +For example, the following policy will use the client ID `nginx-plus` and the client secret `oidc-secret` to authenticate with the OpenID Connect provider `https://idp.example.com`: + +```yaml +spec: + oidc: + clientID: nginx-plus + clientSecret: oidc-secret + authEndpoint: https://idp.example.com/openid-connect/auth + tokenEndpoint: https://idp.example.com/openid-connect/token + jwksURI: https://idp.example.com/openid-connect/certs + endSessionEndpoint: https://idp.example.com/openid-connect/logout + postLogoutRedirectURI: / + accessTokenEnable: true +``` + +NGINX Plus will pass the ID of an authenticated user to the backend in the HTTP header `username`. + +{{< note >}} + +The feature is implemented using the [reference implementation](https://github.com/nginxinc/nginx-openid-connect/) of NGINX Plus as a relying party for OpenID Connect authentication. + +{{< /note >}} + +#### Prerequisites + +In order to use OIDC, you need to enable [zone synchronization](https://docs.nginx.com/nginx/admin-guide/high-availability/zone_sync/). If you don't set up zone synchronization, NGINX Plus will fail to reload. +You also need to configure a resolver, which NGINX Plus will use to resolve the IDP authorization endpoint. You can find an example configuration [in our GitHub repository](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/examples/custom-resources/oidc#step-7---configure-nginx-plus-zone-synchronization-and-resolver). + +{{< warning >}} + +The configuration in the example doesn't enable TLS and the synchronization between the replica happens in clear text. This could lead to the exposure of tokens. + +{{< /warning >}} + +#### Limitations + +The OIDC policy defines a few internal locations that can't be customized: `/_jwks_uri`, `/_token`, `/_refresh`, `/_id_token_validation`, `/logout`. In addition, as explained below, `/_codexch` is the default value for redirect URI, and `/_logout` is the default value for post logout redirect URI, both of which can be customized. Specifying one of these locations as a route in the VirtualServer or VirtualServerRoute will result in a collision and NGINX Plus will fail to reload. + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``clientID`` | The client ID provided by your OpenID Connect provider. | ``string`` | Yes | +|``clientSecret`` | The name of the Kubernetes secret that stores the client secret provided by your OpenID Connect provider. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/oidc``, and the secret under the key ``client-secret``, otherwise the secret will be rejected as invalid. | ``string`` | Yes | +|``authEndpoint`` | URL for the authorization endpoint provided by your OpenID Connect provider. | ``string`` | Yes | +|``authExtraArgs`` | A list of extra URL arguments to pass to the authorization endpoint provided by your OpenID Connect provider. Arguments must be URL encoded, multiple arguments may be included in the list, for example ``[ arg1=value1, arg2=value2 ]`` | ``string[]`` | No | +|``tokenEndpoint`` | URL for the token endpoint provided by your OpenID Connect provider. | ``string`` | Yes | +|``endSessionEndpoint`` | URL provided by your OpenID Connect provider to request the end user be logged out. | ``string`` | No | +|``jwksURI`` | URL for the JSON Web Key Set (JWK) document provided by your OpenID Connect provider. | ``string`` | Yes | +|``scope`` | List of OpenID Connect scopes. The scope ``openid`` always needs to be present and others can be added concatenating them with a ``+`` sign, for example ``openid+profile+email``, ``openid+email+userDefinedScope``. The default is ``openid``. | ``string`` | No | +|``redirectURI`` | Allows overriding the default redirect URI. The default is ``/_codexch``. | ``string`` | No | +|``postLogoutRedirectURI`` | URI to redirect to after the logout has been performed. Requires ``endSessionEndpoint``. The default is ``/_logout``. | ``string`` | No | +|``zoneSyncLeeway`` | Specifies the maximum timeout in milliseconds for synchronizing ID/access tokens and shared values between Ingress Controller pods. The default is ``200``. | ``int`` | No | +|``accessTokenEnable`` | Option of whether Bearer token is used to authorize NGINX to access protected backend. | ``boolean`` | No | +{{% /table %}} + +{{< note >}} + +Only one OIDC policy can be referenced in a VirtualServer and its VirtualServerRoutes. However, the same policy can still be applied to different routes in the VirtualServer and VirtualServerRoutes. + +{{< /note >}} + +#### OIDC Merging Behavior + +A VirtualServer/VirtualServerRoute can reference only a single OIDC policy. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: oidc-policy-one +- name: oidc-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `oidc-policy-one`, and ignores `oidc-policy-two`. + +## Using Policy + +You can use the usual `kubectl` commands to work with Policy resources, just as with built-in Kubernetes resources. + +For example, the following command creates a Policy resource defined in `access-control-policy-allow.yaml` with the name `webapp-policy`: + +```shell +kubectl apply -f access-control-policy-allow.yaml + +policy.k8s.nginx.org/webapp-policy configured +``` + +You can get the resource by running: + +```shell +kubectl get policy webapp-policy + +NAME AGE +webapp-policy 27m +``` + +For `kubectl get` and similar commands, you can also use the short name `pol` instead of `policy`. + +### WAF {#waf} + +{{< note >}} The feature is implemented using the NGINX Plus [NGINX App Protect WAF Module](https://docs.nginx.com/nginx-app-protect/configuration/). {{< /note >}} + +The WAF policy configures NGINX Plus to secure client requests using App Protect WAF policies. + +For example, the following policy will enable the referenced APPolicy. You can configure multiple APLogConfs with log destinations: + +```yaml +waf: + enable: true + apPolicy: "default/dataguard-alarm" + securityLogs: + - enable: true + apLogConf: "default/logconf" + logDest: "syslog:server=syslog-svc.default:514" + - enable: true + apLogConf: "default/logconf" + logDest: "syslog:server=syslog-svc-secondary.default:514" +``` + +{{< note >}} The field `waf.securityLog` is deprecated and will be removed in future releases.It will be ignored if `waf.securityLogs` is populated. {{< /note >}} + +{{% table %}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables NGINX App Protect WAF. | ``bool`` | Yes | +|``apPolicy`` | The [App Protect WAF policy]({{< relref "installation/integrations/app-protect-waf/configuration.md#waf-policies" >}}) of the WAF. Accepts an optional namespace. Mutually exclusive with ``apBundle``. | ``string`` | No | +|``apBundle`` | The [App Protect WAF policy bundle]({{< relref "installation/integrations/app-protect-waf/configuration.md#waf-bundles" >}}). Mutually exclusive with ``apPolicy``. | ``string`` | No | +|``securityLog.enable`` | Enables security log. | ``bool`` | No | +|``securityLog.apLogConf`` | The [App Protect WAF log conf]({{< relref "installation/integrations/app-protect-waf/configuration.md#waf-logs" >}}) resource. Accepts an optional namespace. Only works with ``apPolicy``. | ``string`` | No | +|``securityLog.apLogBundle`` | The [App Protect WAF log bundle]({{< relref "installation/integrations/app-protect-waf/configuration.md#waf-bundles" >}}) resource. Only works with ``apBundle``. | ``string`` | No | +|``securityLog.logDest`` | The log destination for the security log. Only accepted variables are ``syslog:server=:``, ``stderr``, ````. | ``string`` | No | +{{% /table %}} + +#### WAF Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple WAF policies. However, only one can be applied. Every subsequent reference will be ignored. For example, here we reference two policies: + +```yaml +policies: +- name: waf-policy-one +- name: waf-policy-two +``` + +In this example NGINX Ingress Controller will use the configuration from the first policy reference `waf-policy-one`, and ignores `waf-policy-two`. + +### Applying Policies + +You can apply policies to both VirtualServer and VirtualServerRoute resources. For example: + +- VirtualServer: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: VirtualServer + metadata: + name: cafe + namespace: cafe + spec: + host: cafe.example.com + tls: + secret: cafe-secret + policies: # spec policies + - name: policy1 + upstreams: + - name: coffee + service: coffee-svc + port: 80 + routes: + - path: /tea + policies: # route policies + - name: policy2 + namespace: cafe + route: tea/tea + - path: /coffee + policies: # route policies + - name: policy3 + namespace: cafe + action: + pass: coffee + ``` + + For VirtualServer, you can apply a policy: + * to all routes (spec policies) + * to a specific route (route policies) + + Route policies of the *same type* override spec policies. In the example above, if the type of the policies `policy-1` and `policy-3` is `accessControl`, then for requests to `cafe.example.com/coffee`, NGINX will apply `policy-3`. + + The overriding is enforced by NGINX: the spec policies are implemented in the `server` context of the config, and the route policies are implemented in the `location` context. As a result, the route policies of the same type win. + +- VirtualServerRoute, which is referenced by the VirtualServer above: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: VirtualServerRoute + metadata: + name: tea + namespace: tea + spec: + host: cafe.example.com + upstreams: + - name: tea + service: tea-svc + port: 80 + subroutes: # subroute policies + - path: /tea + policies: + - name: policy4 + namespace: tea + action: + pass: tea + ``` + + For VirtualServerRoute, you can apply a policy to a subroute (subroute policies). + + Subroute policies of the same type override spec policies. In the example above, if the type of the policies `policy-1` (in the VirtualServer) and `policy-4` is `accessControl`, then for requests to `cafe.example.com/tea`, NGINX will apply `policy-4`. As with the VirtualServer, the overriding is enforced by NGINX. + + Subroute policies always override route policies no matter the types. For example, the policy `policy-2` in the VirtualServer route will be ignored for the subroute `/tea`, because the subroute has its own policies (in our case, only one policy `policy4`). If the subroute didn't have any policies, then the `policy-2` would be applied. This overriding is enforced by NGINX Ingress Controller -- the `location` context for the subroute will either have route policies or subroute policies, but not both. + +### Invalid Policies + +NGINX will treat a policy as invalid if one of the following conditions is met: + +- The policy doesn't pass the [comprehensive validation](#comprehensive-validation). +- The policy isn't present in the cluster. +- The policy doesn't meet its type-specific requirements. For example, an `ingressMTLS` policy requires TLS termination enabled in the VirtualServer. + +For an invalid policy, NGINX returns the 500 status code for client requests with the following rules: + +- If a policy is referenced in a VirtualServer `route` or a VirtualServerRoute `subroute`, then NGINX will return the 500 status code for requests for the URIs of that route/subroute. +- If a policy is referenced in the VirtualServer `spec`, then NGINX will return the 500 status code for requests for all URIs of that VirtualServer. + +If a policy is invalid, the VirtualServer or VirtualServerRoute will have the [status](/nginx-ingress-controller/configuration/global-configuration/reporting-resources-status#virtualserver-and-virtualserverroute-resources) with the state `Warning` and the message explaining why the policy wasn't considered invalid. + +### Validation + +Two types of validation are available for the Policy resource: + +- *Structural validation*, done by `kubectl` and the Kubernetes API server. +- *Comprehensive validation*, done by NGINX Ingress Controller. + +#### Structural Validation + +The custom resource definition for the Policy includes a structural OpenAPI schema, which describes the type of every field of the resource. + +If you try to create (or update) a resource that violates the structural schema -- for example, the resource uses a string value instead of an array of strings in the `allow` field -- `kubectl` and the Kubernetes API server will reject the resource. + +- Example of `kubectl` validation: + + ```shell + kubectl apply -f access-control-policy-allow.yaml + + error: error validating "access-control-policy-allow.yaml": error validating data: ValidationError(Policy.spec.accessControl.allow): invalid type for org.nginx.k8s.v1.Policy.spec.accessControl.allow: got "string", expected "array"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + +- Example of Kubernetes API server validation: + + ```shell + kubectl apply -f access-control-policy-allow.yaml --validate=false + + The Policy "webapp-policy" is invalid: spec.accessControl.allow: Invalid value: "string": spec.accessControl.allow in body must be of type array: "string" + ``` + +If a resource passes structural validation, then NGINX Ingress Controller's comprehensive validation runs. + +#### Comprehensive Validation + +NGINX Ingress Controller validates the fields of a Policy resource. If a resource is invalid, NGINX Ingress Controller will reject it. The resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. + +You can use `kubectl` to check whether or not NGINX Ingress Controller successfully applied a Policy configuration. For our example `webapp-policy` Policy, we can run: + +```shell +kubectl describe pol webapp-policy + +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 11s nginx-ingress-controller Policy default/webapp-policy was added or updated +``` + +Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. + +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a Policy `webapp-policy` with an invalid IP `10.0.0.` in the `allow` field, you will get: + +```shell +kubectl describe policy webapp-policy + +. . . +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 7s nginx-ingress-controller Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP +``` + +Note how the events section includes a Warning event with the Rejected reason. + +Additionally, this information is also available in the `status` field of the Policy resource. Note the Status section of the Policy: + +```shell +kubectl describe pol webapp-policy + +. . . +Status: + Message: Policy default/webapp-policy is invalid and was rejected: spec.accessControl.allow[0]: Invalid value: "10.0.0.": must be a CIDR or IP + Reason: Rejected + State: Invalid +``` + +**Note**: If you make an existing resource invalid, NGINX Ingress Controller will reject it. diff --git a/content/includes/nic/configuration/security.md b/content/includes/nic/configuration/security.md new file mode 100644 index 000000000..7267eaa01 --- /dev/null +++ b/content/includes/nic/configuration/security.md @@ -0,0 +1,102 @@ +--- +nd-docs: DOCS-597 +doctypes: +- '' +title: Security recommendations +toc: true +weight: 300 +--- + +F5 NGINX Ingress Controller follows Kubernetes best practices: this page outlines configuration specific to NGINX Ingress Controller you may require, including links to examples in the [GitHub repository](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples). + +For general guidance, we recommend the official Kubernetes documentation for [Securing a Cluster](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/). + +## Kubernetes recommendations + +### RBAC and Service Accounts + +Kubernetes uses [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control the resources and operations available to different types of users. + +NGINX Ingress Controller requires RBAC to configure a [ServiceUser](https://kubernetes.io/docs/concepts/security/service-accounts/#default-service-accounts), and provides least privilege access in its standard deployment configurations: + +- [Helm](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/deployments/rbac/rbac.yaml) +- [Manifests](https://github.com/nginx/kubernetes-ingress/blob/v{{< nic-version >}}/deployments/rbac/rbac.yaml) + +By default, the ServiceAccount has access to all Secret resources in the cluster. + +### Secrets + +[Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) are required by NGINX Ingress Controller for certificates and privacy keys, which Kubernetes stores unencrypted by default. We recommend following the [Kubernetes documentation](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/) to store these Secrets using at-rest encryption. + + +## NGINX Ingress Controller recommendations + +### Configure root filesystem as read-only + +{{< caution >}} + This feature is compatible with [NGINX App Protect WAFv5](https://docs.nginx.com/nginx-app-protect-waf/v5/). It is not compatible with [NGINX App Protect WAFv4](https://docs.nginx.com/nginx-app-protect-waf/v4/) or [NGINX App Protect DoS](https://docs.nginx.com/nginx-app-protect-dos/). +{{< /caution >}} + +NGINX Ingress Controller is designed to be resilient against attacks in various ways, such as running the service as non-root to avoid changes to files. We recommend setting filesystems on all containers to read-only, this includes `nginx-ingress-controller`, though also includes `waf-enforcer` and `waf-config-mgr` when NGINX App Protect WAFv5 is in use. This is so that the attack surface is further reduced by limiting changes to binaries and libraries. + +This is not enabled by default, but can be enabled with **Helm** using the [**readOnlyRootFilesystem**]({{< relref "installation/installing-nic/installation-with-helm.md#configuration" >}}) argument in security contexts on all containers: `nginx-ingress-controller`, `waf_enforcer` and `waf_config_mgr`. + +For **Manifests**, uncomment the following sections of the deployment and add sections for `waf-enforcer` and `waf-config-mgr` containers: + +- `readOnlyRootFilesystem: true` +- The entire **volumeMounts** section +- The entire **initContainers** section + +The block below shows the code you will look for: + +```yaml +# volumes: +# - name: nginx-etc +# emptyDir: {} +# - name: nginx-cache +# emptyDir: {} +# - name: nginx-lib +# emptyDir: {} +# - name: nginx-log +# emptyDir: {} +. +. +. +# readOnlyRootFilesystem: true +. +. +. +# volumeMounts: +# - mountPath: /etc/nginx +# name: nginx-etc +# - mountPath: /var/cache/nginx +# name: nginx-cache +# - mountPath: /var/lib/nginx +# name: nginx-lib +# - mountPath: /var/log/nginx +# name: nginx-log +``` + +- Add **waf-enforcer** and **waf-config-mgr** container sections +- Add `readOnlyFilesystem: true` in both containers security context sections + +### Prometheus + +If Prometheus metrics are [enabled]({{< relref "/logging-and-monitoring/prometheus.md" >}}), we recommend [using HTTPS]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-prometheus-tls-secret" >}}). + +### Snippets + +Snippets allow raw NGINX configuration to be inserted into resources. They are intended for advanced NGINX users and could create vulnerabilities in a cluster if misused. + +Snippets are disabled by default. To use snippets, set the [**enable-snippets**]({{< relref"configuration/global-configuration/command-line-arguments.md#cmdoption-enable-snippets" >}}) command-line argument. + +{{< caution >}} + Snippets are **always** enabled for ConfigMap. +{{< /caution >}} + +For more information, read the following: + +- [Advanced configuration using Snippets]({{< relref "/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) +- [Using Snippets with VirtualServer/VirtualServerRoute]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md#using-snippets" >}}) +- [Using Snippets with TransportServer]({{< relref "/configuration/transportserver-resource.md#using-snippets" >}}) +- [ConfigMap snippets and custom templates]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#snippets-and-custom-templates" >}}) diff --git a/content/includes/nic/configuration/transportserver-resource.md b/content/includes/nic/configuration/transportserver-resource.md new file mode 100644 index 000000000..ea2f3c688 --- /dev/null +++ b/content/includes/nic/configuration/transportserver-resource.md @@ -0,0 +1,416 @@ +--- +title: TransportServer resources +toc: true +weight: 600 +nd-docs: DOCS-598 +--- + +This document is reference material for the TransportServer resource used by F5 NGINX Ingress Controller. + +The TransportServer resource allows you to configure TCP, UDP, and TLS Passthrough load balancing. The resource is implemented as a [Custom Resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +The GitHub repository has [examples of the resources](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources) for specific use cases. + +## Prerequisites + +- For TCP and UDP, the TransportServer resource must be used in conjunction with the [GlobalConfiguration resource]({{< ref "/nic/configuration/global-configuration/globalconfiguration-resource.md" >}}), which must be created separately. +- For TLS Passthrough, make sure to enable the [`-enable-tls-passthrough`]({{< ref "/nic/configuration/global-configuration/command-line-arguments#cmdoption-enable-tls-passthrough.md" >}}) command-line argument of NGINX Ingress Controller. + +## TransportServer Specification + +The TransportServer resource defines load balancing configuration for TCP, UDP, or TLS Passthrough traffic. Below are a few examples: + +- TCP load balancing: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: TransportServer + metadata: + name: dns-tcp + spec: + host: dns.example.com + listener: + name: dns-tcp + protocol: TCP + tls: + secret: cafe-secret + upstreams: + - name: dns-app + service: dns-service + port: 5353 + action: + pass: dns-app + ``` + +- UDP load balancing: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: TransportServer + metadata: + name: dns-udp + spec: + listener: + name: dns-udp + protocol: UDP + upstreams: + - name: dns-app + service: dns-service + port: 5353 + upstreamParameters: + udpRequests: 1 + udpResponses: 1 + action: + pass: dns-app + ``` + +- TLS passthrough load balancing: + + ```yaml + apiVersion: k8s.nginx.org/v1 + kind: TransportServer + metadata: + name: secure-app + spec: + listener: + name: tls-passthrough + protocol: TLS_PASSTHROUGH + host: app.example.com + upstreams: + - name: secure-app + service: secure-app + port: 8443 + action: + pass: secure-app + ``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``listener`` | The listener on NGINX that will accept incoming connections/datagrams. | [listener](#listener) | Yes | +|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. Wildcard domains like ``*.example.com`` are not allowed. When specified, NGINX will use this host for SNI-based routing. For TLS Passthrough, this field is required. For TCP with TLS termination, specifying the host enables SNI routing and requires specifying a TLS secret.| ``string`` | No | +|``tls`` | The TLS termination configuration. Not supported for TLS Passthrough load balancing. | [tls](#tls) | No | +|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | Yes | +|``upstreamParameters`` | The upstream parameters. | [upstreamParameters](#upstreamparameters) | No | +|``action`` | The action to perform for a client connection/datagram. | [action](#action) | Yes | +|``ingressClassName`` | Specifies which Ingress Controller must handle the TransportServer resource. | ``string`` | No | +|``streamSnippets`` | Sets a custom snippet in the ``stream`` context. | ``string`` | No | +|``serverSnippets`` | Sets a custom snippet in the ``server`` context. | ``string`` | No | +{{}} + +\* -- Required for TLS Passthrough load balancing. + +### Listener + +The listener field references a listener that NGINX will use to accept incoming traffic for the TransportServer. For TCP and UDP, the listener must be defined in the [GlobalConfiguration resource]({{< ref "/nic/configuration/global-configuration/globalconfiguration-resource.md" >}}). When referencing a listener, both the name and the protocol must match. For TLS Passthrough, use the built-in listener with the name `tls-passthrough` and the protocol `TLS_PASSTHROUGH`. + +The combination of ``spec.listener.name`` and ``spec.host`` must be unique among all TransportServers. If two TransportServers specify the same combination of ``spec.listener.name`` and ``spec.host``, one of them will be rejected to prevent conflicts. In the case where no host is specified, it is considered an empty string. + +An example: + +```yaml +listener: + name: dns-udp + protocol: UDP +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the listener. | ``string`` | Yes | +|``protocol`` | The protocol of the listener. | ``string`` | Yes | +{{}} + +### TLS + +The tls field defines TLS configuration for a TransportServer. When using TLS termination (not TLS Passthrough), you can specify the host field to enable SNI-based routing, allowing multiple applications to share the same listener port and be distinguished by the TLS SNI hostname. Each application can use its own TLS certificate and key specified via the secret field. + +```yaml +secret: cafe-secret +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the TransportServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). | ``string`` | No | +{{}} + +### Upstream + +The upstream defines a destination for the TransportServer. For example: + +```yaml +name: secure-app +service: secure-app +port: 8443 +maxFails: 3 +maxConns: 100 +failTimeout: 30s +loadBalancingMethod: least_conn +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``upstream-123`` are valid. The name must be unique among all upstreams of the resource. | ``string`` | Yes | +|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and close client connections/ignore datagrams. | ``string`` | Yes | +|``port`` | The port of the service. If the service doesn't define that port, NGINX will assume the service has zero endpoints and close client connections/ignore datagrams. The port must fall into the range ``1..65535``. | ``int`` | Yes | +|``maxFails`` | Sets the [number](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_fails) of unsuccessful attempts to communicate with the server that should happen in the duration set by the failTimeout parameter to consider the server unavailable. The default ``1``. | ``int`` | No | +|``maxConns`` | Sets the [number](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#max_conns) of maximum connections to the proxied server. Default value is zero, meaning there is no limit. The default is ``0``. | ``int`` | No | +|``failTimeout`` | Sets the [time](https://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#fail_timeout) during which the specified number of unsuccessful attempts to communicate with the server should happen to consider the server unavailable and the period of time the server will be considered unavailable. The default is ``10s``. | ``string`` | No | +|``healthCheck`` | The health check configuration for the Upstream. See the [health_check](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check) directive. Note: this feature is supported only in NGINX Plus. | [healthcheck](#upstreamhealthcheck) | No | +|``loadBalancingMethod`` | The method used to load balance the upstream servers. By default, connections are distributed between the servers using a weighted round-robin balancing method. See the [upstream](http://nginx.org/en/docs/stream/ngx_stream_upstream_module.html#upstream) section for available methods and their details. | ``string`` | No | +|``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | +|``backupPort`` | The port of the backup service. The backup port is required if the backup service name is provided. The port must fall into the range ``1..65535``. | ``uint16`` | No | +{{}} + +### Upstream.Healthcheck + +The Healthcheck defines an [active health check](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html?#health_check). In the example below we enable a health check for an upstream and configure all the available parameters: + +```yaml +name: secure-app +service: secure-app +port: 8443 +healthCheck: + enable: true + interval: 20s + timeout: 30s + jitter: 3s + fails: 5 + passes: 5 + port: 8080 +``` + +{{< note >}} This feature is only supported with NGINX Plus. {{< /note >}} + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | +|``interval`` | The interval between two consecutive health checks. The default is ``5s``. | ``string`` | No | +|``timeout`` | This overrides the timeout set by [proxy_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout) which is set in `SessionParameters` for health checks. The default value is ``5s``. | ``string`` | No | +|``jitter`` | The time within which each health check will be randomly delayed. By default, there is no delay. | ``string`` | No | +|``fails`` | The number of consecutive failed health checks of a particular upstream server after which this server will be considered unhealthy. The default is ``1``. | ``integer`` | No | +|``passes`` | The number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is ``1``. | ``integer`` | No | +|``port`` | The port used for health check requests. By default, the [server port is used](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#health_check_port). Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod. | ``integer`` | No | +|``match`` | Controls the data to send and the response to expect for the healthcheck. | [match](#upstreamhealthcheckmatch) | No | +{{}} + +### Upstream.Healthcheck.Match + +The match controls the data to send and the response to expect for the healthcheck: + +```yaml +match: + send: 'GET / HTTP/1.0\r\nHost: localhost\r\n\r\n' + expect: "~200 OK" +``` + +Both `send` and `expect` fields can contain hexadecimal literals with the prefix `\x` followed by two hex digits, for example, `\x80`. + +See the [match](https://nginx.org/en/docs/stream/ngx_stream_upstream_hc_module.html#match) directive for details. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``send`` | A string to send to an upstream server. | ``string`` | No | +|``expect`` | A literal string or a regular expression that the data obtained from the server should match. The regular expression is specified with the preceding ``~*`` modifier (for case-insensitive matching), or the ``~`` modifier (for case-sensitive matching). NGINX Ingress Controller validates a regular expression using the RE2 syntax. | ``string`` | No | +{{}} + +### UpstreamParameters + +The upstream parameters define various parameters for the upstreams: + +```yaml +upstreamParameters: + udpRequests: 1 + udpResponses: 1 + connectTimeout: 60s + nextUpstream: true + nextUpstreamTimeout: 50s + nextUpstreamTries: 1 +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``udpRequests`` | The number of datagrams, after receiving which, the next datagram from the same client starts a new session. See the [proxy_requests](https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_requests) directive. The default is ``0``. | ``int`` | No | +|``udpResponses`` | The number of datagrams expected from the proxied server in response to a client datagram. See the [proxy_responses](https://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_responses) directive. By default, the number of datagrams is not limited. | ``int`` | No | +|``connectTimeout`` | The timeout for establishing a connection with a proxied server. See the [proxy_connect_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_connect_timeout) directive. The default is ``60s``. | ``string`` | No | +|``nextUpstream`` | If a connection to the proxied server cannot be established, determines whether a client connection will be passed to the next server. See the [proxy_next_upstream](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream) directive. The default is ``true``. | bool | No | +|``nextUpstreamTries`` | The number of tries for passing a connection to the next server. See the [proxy_next_upstream_tries](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_tries) directive. The default is ``0``. | ``int`` | No | +|``nextUpstreamTimeout`` | The time allowed to pass a connection to the next server. See the [proxy_next_upstream_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_next_upstream_timeout) directive. The default us ``0``. | ``string`` | No | +{{}} + +### SessionParameters + +The session parameters define various parameters for TCP connections and UDP sessions. + +```yaml +sessionParameters: + timeout: 50s +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``timeout`` | The timeout between two successive read or write operations on client or proxied server connections. See [proxy_timeout](http://nginx.org/en/docs/stream/ngx_stream_proxy_module.html#proxy_timeout) directive. The default is ``10m``. | ``string`` | No | +{{}} + +### Action + +The action defines an action to perform for a client connection/datagram. + +In the example below, client connections/datagrams are passed to an upstream `dns-app`: + +```yaml +action: + pass: dns-app +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``pass`` | Passes connections/datagrams to an upstream. The upstream with that name must be defined in the resource. | ``string`` | Yes | +{{}} + +## Using TransportServer + +You can use the usual `kubectl` commands to work with TransportServer resources, similar to Ingress resources. + +For example, the following command creates a TransportServer resource defined in `transport-server-passthrough.yaml` with the name `secure-app`: + +```shell +kubectl apply -f transport-server-passthrough.yaml +``` +```text +transportserver.k8s.nginx.org/secure-app created +``` + +You can get the resource by running: + +```shell +kubectl get transportserver secure-app +``` +```text +NAME AGE +secure-app 46sm +``` + +In the kubectl get and similar commands, you can also use the short name `ts` instead of `transportserver`. + +### Using Snippets + +Snippets allow you to insert raw NGINX config into different contexts of NGINX configuration. In the example below, we use snippets to configure [access control](http://nginx.org/en/docs/stream/ngx_stream_access_module.html) in a TransportServer: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: TransportServer +metadata: + name: cafe +spec: + host: cafe.example.com + serverSnippets: | + deny 192.168.1.1; + allow 192.168.1.0/24; + upstreams: + - name: tea + service: tea-svc + port: 80 +``` + +Snippets can also be specified for a stream. In the example below, we use snippets to [limit the number of connections](https://nginx.org/en/docs/stream/ngx_stream_limit_conn_module.html): + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: TransportServer +metadata: + name: cafe +spec: + host: cafe.example.com + streamSnippets: limit_conn_zone $binary_remote_addr zone=addr:10m; + serverSnippets: limit_conn addr 1; + upstreams: + - name: tea + service: tea-svc + port: 80 +``` + +{{< note >}} To configure snippets in the `stream` context, use `stream-snippets` ConfigMap key. {{< /note >}} + +For additional information, view the [Advanced configuration with Snippets]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) topic. + +### Validation + +Two types of validation are available for the TransportServer resource: + +- *Structural validation* by the `kubectl` and Kubernetes API server. +- *Comprehensive validation* by NGINX Ingress Controller. + +#### Structural Validation + +The custom resource definition for the TransportServer includes structural OpenAPI schema which describes the type of every field of the resource. + +If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for the port field of an upstream), `kubectl` and Kubernetes API server will reject such a resource: + +- Example of `kubectl` validation: + + ```shell + kubectl apply -f transport-server-passthrough.yaml + ``` + ```text + error: error validating "transport-server-passthrough.yaml": error validating data: ValidationError(TransportServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.TransportServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + +- Example of Kubernetes API server validation: + + ```shell + kubectl apply -f transport-server-passthrough.yaml --validate=false + ``` + ```text + The TransportServer "secure-app" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.upstreams.port in body must be of type integer: "string" + ``` + +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. + +#### Comprehensive Validation + +NGINX Ingress Controller validates the fields of a TransportServer resource. If a resource is invalid, NGINX Ingress Controller will reject it: the resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. + +You can check if NGINX Ingress Controller successfully applied the configuration for a TransportServer. For our example `secure-app` TransportServer, we can run: + +```shell +kubectl describe ts secure-app +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 3s nginx-ingress-controller Configuration for default/secure-app was added or updated +``` + +Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. + +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a TransportServer `secure-app` with a pass action that references a non-existing upstream, you will get : + +```shell +kubectl describe ts secure-app +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 2s nginx-ingress-controller TransportServer default/secure-app is invalid and was rejected: spec.action.pass: Not found: "some-app" +``` + +Note how the events section includes a Warning event with the Rejected reason. + +**Note**: If you make an existing resource invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. + +## Customization via ConfigMap + +The [ConfigMap]({{< ref "/nic/configuration/global-configuration/configmap-resource.md" >}}) keys (except for `stream-snippets`, `stream-log-format`, `resolver-addresses`, `resolver-ipv6`, `resolver-valid` and `resolver-timeout`) do not affect TransportServer resources. diff --git a/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md new file mode 100644 index 000000000..a129629ed --- /dev/null +++ b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md @@ -0,0 +1,1101 @@ +--- +title: VirtualServer and VirtualServerRoute resources +toc: true +weight: 700 +nd-docs: DOCS-599 +--- + +This document is reference material for the VirtualServer and VirtualServerRoute resources used by F5 NGINX Ingress Controller. + +VirtualServer and VirtualServerRoute resources are load balancing configurations recommended as an alternative to the Ingress resource. + +They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. The resources are implemented as [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). + +The GitHub repository has [examples of the resources](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources) for specific use cases. + +--- + +## VirtualServer specification + +The VirtualServer resource defines load balancing configuration for a domain name, such as `example.com`. Below is an example of such configuration: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: cafe +spec: + host: cafe.example.com + listener: + http: http-8083 + https: https-8443 + tls: + secret: cafe-secret + gunzip: on + upstreams: + - name: tea + service: tea-svc + port: 80 + - name: coffee + service: coffee-svc + port: 80 + routes: + - path: /tea + action: + pass: tea + - path: /coffee + action: + pass: coffee + - path: ~ ^/decaf/.*\\.jpg$ + action: + pass: coffee + - path: = /green/tea + action: + pass: tea +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. When using a wildcard domain like ``*.example.com`` the domain must be contained in double quotes. The ``host`` value needs to be unique among all Ingress and VirtualServer resources. See also [Handling Host and Listener Collisions](/nginx-ingress-controller/configuration/host-and-listener-collisions). | ``string`` | Yes | +|``listener`` | Sets a custom HTTP and/or HTTPS listener. Valid fields are `listener.http` and `listener.https`. Each field must reference the name of a valid listener defined in a GlobalConfiguration resource | [listener](#virtualserverlistener) | No | +|``tls`` | The TLS termination configuration. | [tls](#virtualservertls) | No | +|``gunzip`` | Enables or disables [decompression](https://docs.nginx.com/nginx/admin-guide/web-server/compression/) of gzipped responses for clients. Allowed values β€œon”/β€œoff”, β€œtrue”/β€œfalse” or β€œyes”/β€œno”. If the ``gunzip`` value is not set, it defaults to ``off``. | ``boolean`` | No | +|``externalDNS`` | The externalDNS configuration for a VirtualServer. | [externalDNS](#virtualserverexternaldns) | No | +|``dos`` | A reference to a DosProtectedResource, setting this enables DOS protection of the VirtualServer. | ``string`` | No | +|``policies`` | A list of policies. | [[]policy](#virtualserverpolicy) | No | +|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | +|``routes`` | A list of routes. | [[]route](#virtualserverroute) | No | +|``ingressClassName`` | Specifies which Ingress Controller must handle the VirtualServer resource. | ``string`` | No | +|``internalRoute`` | Specifies if the VirtualServer resource is an internal route or not. | ``boolean`` | No | +|``http-snippets`` | Sets a custom snippet in the http context. | ``string`` | No | +|``server-snippets`` | Sets a custom snippet in server context. Overrides the ``server-snippets`` ConfigMap key. | ``string`` | No | +{{}} + +### VirtualServer.TLS + +The tls field defines TLS configuration for a VirtualServer. For example: + +```yaml +secret: cafe-secret +redirect: + enable: true +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``secret`` | The name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type ``kubernetes.io/tls`` and contain keys named ``tls.crt`` and ``tls.key`` that contain the certificate and private key as described [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). If the secret doesn't exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer. If the secret is not specified but [wildcard TLS secret](/nginx-ingress-controller/configuration/global-configuration/command-line-arguments#cmdoption-wildcard-tls-secret) is configured, NGINX will use the wildcard secret for TLS termination. | ``string`` | No | +|``redirect`` | The redirect configuration of the TLS for a VirtualServer. | [tls.redirect](#virtualservertlsredirect) | No | ### VirtualServer.TLS.Redirect | +|``cert-manager`` | The cert-manager configuration of the TLS for a VirtualServer. | [tls.cert-manager](#virtualservertlscertmanager) | No | ### VirtualServer.TLS.CertManager | +{{}} + +### VirtualServer.TLS.Redirect + +The redirect field configures a TLS redirect for a VirtualServer: + +```yaml +enable: true +code: 301 +basedOn: scheme +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables a TLS redirect for a VirtualServer. The default is ``False``. | ``boolean`` | No | +|``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | +|``basedOn`` | The attribute of a request that NGINX will evaluate to send a redirect. The allowed values are ``scheme`` (the scheme of the request) or ``x-forwarded-proto`` (the ``X-Forwarded-Proto`` header of the request). The default is ``scheme``. | ``string`` | No | ### VirtualServer.Policy | +{{}} + +### VirtualServer.TLS.CertManager + +The cert-manager field configures x509 automated Certificate management for VirtualServer resources using cert-manager (cert-manager.io). Please see the [cert-manager configuration documentation](https://cert-manager.io/docs/configuration/) for more information on deploying and configuring Issuers. Example: + +```yaml +cert-manager: + cluster-issuer: "my-issuer-name" +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``issuer`` | the name of an Issuer. An Issuer is a cert-manager resource which describes the certificate authority capable of signing certificates. The Issuer must be in the same namespace as the VirtualServer resource. Please note that one of `issuer` and `cluster-issuer` are required, but they are mutually exclusive - one and only one must be defined. | ``string`` | No | +|``cluster-issuer`` | the name of a ClusterIssuer. A ClusterIssuer is a cert-manager resource which describes the certificate authority capable of signing certificates. It does not matter which namespace your VirtualServer resides, as ClusterIssuers are non-namespaced resources. Please note that one of `issuer` and `cluster-issuer` are required, but they are mutually exclusive - one and only one must be defined. | ``string`` | No | +|``issuer-kind`` | The kind of the external issuer resource, for example AWSPCAIssuer. This is only necessary for out-of-tree issuers. This cannot be defined if `cluster-issuer` is also defined. | ``string`` | No | +|``issuer-group`` | The API group of the external issuer controller, for example awspca.cert-manager.io. This is only necessary for out-of-tree issuers. This cannot be defined if `cluster-issuer` is also defined. | ``string`` | No | +|``common-name`` | This field allows you to configure spec.commonName for the Certificate to be generated. This configuration adds a CN to the x509 certificate. | ``string`` | No | +|``duration`` | This field allows you to configure spec.duration field for the Certificate to be generated. Must be specified using a [Go time.Duration](https://pkg.go.dev/time#ParseDuration) string format, which does not allow the d (days) suffix. You must specify these values using s, m, and h suffixes instead. | ``string`` | No | +|``renew-before`` | this annotation allows you to configure spec.renewBefore field for the Certificate to be generated. Must be specified using a [Go time.Duration](https://pkg.go.dev/time#ParseDuration) string format, which does not allow the d (days) suffix. You must specify these values using s, m, and h suffixes instead. | ``string`` | No | +|``usages`` | This field allows you to configure spec.usages field for the Certificate to be generated. Pass a string with comma-separated values i.e. ``key agreement,digital signature, server auth``. An exhaustive list of supported key usages can be found in the [the cert-manager api documentation](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.KeyUsage). | ``string`` | No | +|``issue-temp-cert`` | When ``true``, ask cert-manager for a [temporary self-signed certificate](https://cert-manager.io/docs/usage/certificate/#temporary-certificates-while-issuing) pending the issuance of the Certificate. This allows HTTPS-only servers to use ACME HTTP01 challenges when the TLS secret does not exist yet. | ``boolean`` | No | +{{}} + +### VirtualServer.Listener +The listener field defines a custom HTTP and/or HTTPS listener. +The respective listeners used must reference the name of a listener defined using a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. +For example: +```yaml +http: http-8083 +https: https-8443 +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``http`` | The name of am HTTP listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No | +|``https`` | The name of an HTTPS listener defined in a [GlobalConfiguration](/nginx-ingress-controller/configuration/global-configuration/globalconfiguration-resource/) resource. | ``string`` | No | +{{}} + +### VirtualServer.ExternalDNS + +The externalDNS field configures controlling DNS records dynamically for VirtualServer resources using [ExternalDNS](https://github.com/kubernetes-sigs/external-dns). Please see the [ExternalDNS configuration documentation](https://kubernetes-sigs.github.io/external-dns/) for more information on deploying and configuring ExternalDNS and Providers. Example: + +```yaml +enable: true +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables ExternalDNS integration for a VirtualServer resource. The default is ``false``. | ``string`` | No | +|``labels`` | Configure labels to be applied to the Endpoint resources that will be consumed by ExternalDNS. | ``map[string]string`` | No | +|``providerSpecific`` | Configure provider specific properties which holds the name and value of a configuration which is specific to individual DNS providers. | [[]ProviderSpecific](#virtualserverexternaldnsproviderspecific) | No | +|``recordTTL`` | TTL for the DNS record. This defaults to 0 if not defined. See [the ExternalDNS TTL documentation for provider-specific defaults](https://kubernetes-sigs.github.io/external-dns/v0.14.2/ttl/#providers) | ``int64`` | No | +|``recordType`` | The record Type that should be created, e.g. "A", "AAAA", "CNAME". This is automatically computed based on the external endpoints if not defined. | ``string`` | No | +{{}} + +### VirtualServer.ExternalDNS.ProviderSpecific + +The providerSpecific field of the externalDNS block allows the specification of provider specific properties which is a list of key value pairs of configurations which are specific to individual DNS providers. Example: + +```yaml +- name: my-name + value: my-value +- name: my-name2 + value: my-value2 +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the key value pair. | ``string`` | Yes | +|``value`` | The value of the key value pair. | ``string`` | Yes | +{{}} + +### VirtualServer.Policy + +The policy field references a [Policy resource](/nginx-ingress-controller/configuration/policy-resource/) by its name and optional namespace. For example: + +```yaml +name: access-control +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of a policy. If the policy doesn't exist or invalid, NGINX will respond with an error response with the `500` status code. | ``string`` | Yes | +|``namespace`` | The namespace of a policy. If not specified, the namespace of the VirtualServer resource is used. | ``string`` | No | +{{}} + +### VirtualServer.Route + +The route defines rules for matching client requests to actions like passing a request to an upstream. For example: + +```yaml + path: /tea + action: + pass: tea +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``path`` | The path of the route. NGINX will match it against the URI of a request. Possible values are: a prefix ( ``/`` , ``/path`` ), an exact match ( ``=/exact/match`` ), a case insensitive regular expression ( ``~*^/Bar.*\.jpg`` ) or a case sensitive regular expression ( ``~^/foo.*\.jpg`` ). In the case of a prefix (must start with ``/`` ) or an exact match (must start with ``=`` ), the path must not include any whitespace characters, ``{`` , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all routes of the VirtualServer. Check the [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive for more information. | ``string`` | Yes | +|``policies`` | A list of policies. The policies override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | +|``action`` | The default action to perform for a request. | [action](#action) | No | +|``dos`` | A reference to a DosProtectedResource, setting this enables DOS protection of the VirtualServer route. | ``string`` | No | +|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | +|``route`` | The name of a VirtualServerRoute resource that defines this route. If the VirtualServerRoute belongs to a different namespace than the VirtualServer, you need to include the namespace. For example, ``tea-namespace/tea``. | ``string`` | No | +|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | +|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` ConfigMap key. | ``string`` | No | +{{}} + +\* -- a route must include exactly one of the following: `action`, `splits`, or `route`. + +## VirtualServerRoute specification + +The VirtualServerRoute resource defines a route for a VirtualServer. It can consist of one or multiple subroutes. The VirtualServerRoute is an alternative to [Mergeable Ingress types](/nginx-ingress-controller/configuration/ingress-resources/cross-namespace-configuration). + +In the example below, the VirtualServer `cafe` from the namespace `cafe-ns` defines a route with the path `/coffee`, which is further defined in the VirtualServerRoute `coffee` from the namespace `coffee-ns`. + +VirtualServer: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: cafe + namespace: cafe-ns +spec: + host: cafe.example.com + upstreams: + - name: tea + service: tea-svc + port: 80 + routes: + - path: /tea + action: + pass: tea + - path: /coffee + route: coffee-ns/coffee +``` + +VirtualServerRoute: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServerRoute +metadata: + name: coffee + namespace: coffee-ns +spec: + host: cafe.example.com + upstreams: + - name: latte + service: latte-svc + port: 80 + - name: espresso + service: espresso-svc + port: 80 + subroutes: + - path: /coffee/latte + action: + pass: latte + - path: /coffee/espresso + action: + pass: espresso +``` + +Note that each subroute must have a `path` that starts with the same prefix (here `/coffee`), which is defined in the route of the VirtualServer. Additionally, the `host` in the VirtualServerRoute must be the same as the `host` of the VirtualServer. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``host`` | The host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as ``my-app`` or ``hello.example.com``. When using a wildcard domain like ``*.example.com`` the domain must be contained in double quotes. Must be the same as the ``host`` of the VirtualServer that references this resource. | ``string`` | Yes | +|``upstreams`` | A list of upstreams. | [[]upstream](#upstream) | No | +|``subroutes`` | A list of subroutes. | [[]subroute](#virtualserverroutesubroute) | No | +|``ingressClassName`` | Specifies which Ingress Controller must handle the VirtualServerRoute resource. Must be the same as the ``ingressClassName`` of the VirtualServer that references this resource. | ``string``_ | No | +{{}} + +### VirtualServerRoute.Subroute + +The subroute defines rules for matching client requests to actions like passing a request to an upstream. For example: + +```yaml +path: /coffee +action: + pass: coffee +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``path`` | The path of the subroute. NGINX will match it against the URI of a request. Possible values are: a prefix ( ``/`` , ``/path`` ), an exact match ( ``=/exact/match`` ), a case insensitive regular expression ( ``~*^/Bar.*\.jpg`` ) or a case sensitive regular expression ( ``~^/foo.*\.jpg`` ). In the case of a prefix, the path must start with the same path as the path of the route of the VirtualServer that references this resource. In the case of an exact or regex match, the path must be the same as the path of the route of the VirtualServer that references this resource. A matching path of the route of the VirtualServer but in different type is not accepted, e.g. a regex path (`~/match`) cannot be used with a prefix path in VirtualServer (`/match`) In the case of a prefix or an exact match, the path must not include any whitespace characters, ``{`` , ``}`` or ``;``. In the case of the regex matches, all double quotes ``"`` must be escaped and the match can't end in an unescaped backslash ``\``. The path must be unique among the paths of all subroutes of the VirtualServerRoute. | ``string`` | Yes | +|``policies`` | A list of policies. The policies override *all* policies defined in the route of the VirtualServer that references this resource. The policies also override the policies of the same type defined in the ``spec`` of the VirtualServer. See [Applying Policies](/nginx-ingress-controller/configuration/policy-resource/#applying-policies) for more details. | [[]policy](#virtualserverpolicy) | No | +|``action`` | The default action to perform for a request. | [action](#action) | No | +|``dos`` | A reference to a DosProtectedResource, setting this enables DOS protection of the VirtualServerRoute subroute. | ``string`` | No | +|``splits`` | The default splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +|``matches`` | The matching rules for advanced content-based routing. Requires the default ``action`` or ``splits``. Unmatched requests will be handled by the default ``action`` or ``splits``. | [matches](#match) | No | +|``errorPages`` | The custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code. | [[]errorPage](#errorpage) | No | +|``location-snippets`` | Sets a custom snippet in the location context. Overrides the ``location-snippets`` of the VirtualServer (if set) or the ``location-snippets`` ConfigMap key. | ``string`` | No | +{{}} + +\* -- a subroute must include exactly one of the following: `action` or `splits`. + +## Common VirtualServer and VirtualServerRoute specifications + +### Upstream + +The upstream defines a destination for the routing configuration. For example: + +```yaml +name: tea +service: tea-svc +subselector: + version: canary +port: 80 +lb-method: round_robin +fail-timeout: 10s +max-fails: 1 +max-conns: 32 +keepalive: 32 +connect-timeout: 30s +read-timeout: 30s +send-timeout: 30s +next-upstream: "error timeout non_idempotent" +next-upstream-timeout: 5s +next-upstream-tries: 10 +client-max-body-size: 2m +tls: + enable: true +``` + +**Note**: The WebSocket protocol is supported without any additional configuration. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, ``hello`` and ``upstream-123`` are valid. The name must be unique among all upstreams of the resource. | ``string`` | Yes | +|``service`` | The name of a [service](https://kubernetes.io/docs/concepts/services-networking/service/). The service must belong to the same namespace as the resource. If the service doesn't exist, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. For NGINX Plus only, services of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) are also supported (check the [prerequisites](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/externalname-services#prerequisites) ). | ``string`` | Yes | +|``subselector`` | Selects the pods within the service using label keys and values. By default, all pods of the service are selected. Note: the specified labels are expected to be present in the pods when they are created. If the pod labels are updated, NGINX Ingress Controller will not see that change until the number of the pods is changed. | ``map[string]string`` | No | +|``use-cluster-ip`` | Enables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like ``lb-method`` and ``next-upstream``) will have no effect, as NGINX Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP. | ``boolean`` | No | +|``port`` | The port of the service. If the service doesn't define that port, NGINX will assume the service has zero endpoints and return a ``502`` response for requests for this upstream. The port must fall into the range ``1..65535``. | ``uint16`` | Yes | +|``lb-method`` | The load [balancing method](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-load-balancer/#choosing-a-load-balancing-method). To use the round-robin method, specify ``round_robin``. The default is specified in the ``lb-method`` ConfigMap key. | ``string`` | No | +|``fail-timeout`` | The time during which the specified number of unsuccessful attempts to communicate with an upstream server should happen to consider the server unavailable. See the [fail_timeout](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#fail_timeout) parameter of the server directive. The default is set in the ``fail-timeout`` ConfigMap key. | ``string`` | No | +|``max-fails`` | The number of unsuccessful attempts to communicate with an upstream server that should happen in the duration set by the ``fail-timeout`` to consider the server unavailable. See the [max_fails](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_fails) parameter of the server directive. The default is set in the ``max-fails`` ConfigMap key. | ``int`` | No | +|``max-conns`` | The maximum number of simultaneous active connections to an upstream server. See the [max_conns](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#max_conns) parameter of the server directive. By default there is no limit. Note: if keepalive connections are enabled, the total number of active and idle keepalive connections to an upstream server may exceed the ``max_conns`` value. | ``int`` | No | +|``keepalive`` | Configures the cache for connections to upstream servers. The value ``0`` disables the cache. See the [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) directive. The default is set in the ``keepalive`` ConfigMap key. | ``int`` | No | +|``connect-timeout`` | The timeout for establishing a connection with an upstream server. See the [proxy_connect_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) directive. The default is specified in the ``proxy-connect-timeout`` ConfigMap key. | ``string`` | No | +|``read-timeout`` | The timeout for reading a response from an upstream server. See the [proxy_read_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) directive. The default is specified in the ``proxy-read-timeout`` ConfigMap key. | ``string`` | No | +|``send-timeout`` | The timeout for transmitting a request to an upstream server. See the [proxy_send_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) directive. The default is specified in the ``proxy-send-timeout`` ConfigMap key. | ``string`` | No | +|``next-upstream`` | Specifies in which cases a request should be passed to the next upstream server. See the [proxy_next_upstream](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) directive. The default is ``error timeout``. | ``string`` | No | +|``next-upstream-timeout`` | The time during which a request can be passed to the next upstream server. See the [proxy_next_upstream_timeout](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_timeout) directive. The ``0`` value turns off the time limit. The default is ``0``. | ``string`` | No | +|``next-upstream-tries`` | The number of possible tries for passing a request to the next upstream server. See the [proxy_next_upstream_tries](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream_tries) directive. The ``0`` value turns off this limit. The default is ``0``. | ``int`` | No | +|``client-max-body-size`` | Sets the maximum allowed size of the client request body. See the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. The default is set in the ``client-max-body-size`` ConfigMap key. | ``string`` | No | +|``tls`` | The TLS configuration for the Upstream. | [tls](#upstreamtls) | No | +|``healthCheck`` | The health check configuration for the Upstream. See the [health_check](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check) directive. Note: this feature is supported only in NGINX Plus. | [healthcheck](#upstreamhealthcheck) | No | +|``slow-start`` | The slow start allows an upstream server to gradually recover its weight from 0 to its nominal value after it has been recovered or became available or when the server becomes available after a period of time it was considered unavailable. By default, the slow start is disabled. See the [slow_start](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start) parameter of the server directive. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods and will be ignored. | ``string`` | No | +|``queue`` | Configures a queue for an upstream. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request. By default, no queue is configured. Note: this feature is supported only in NGINX Plus. | [queue](#upstreamqueue) | No | +|``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | +|``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | +|``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +|``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | +|``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#listeners) and configure TLS termination in the VirtualServer. | ``string`` | No | +|``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | +|``backupPort`` | The port of the backup service. The backup port is required if the backup service name is provided. The port must fall into the range ``1..65535``. | ``uint16`` | No | +{{}} + +### Upstream.Buffers + +The buffers field configures the buffers used for reading a response from the upstream server for a single connection: + +```yaml +number: 4 +size: 8K +``` + +See the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive for additional information. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``number`` | Configures the number of buffers. The default is set in the ``proxy-buffers`` ConfigMap key. | ``int`` | Yes | +|``size`` | Configures the size of a buffer. The default is set in the ``proxy-buffers`` ConfigMap key. | ``string`` | Yes | +{{}} + +### Upstream.TLS + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables HTTPS for requests to upstream servers. The default is ``False`` , meaning that HTTP will be used. Note: by default, NGINX will not verify the upstream server certificate. To enable the verification, configure an [EgressMTLS Policy](/nginx-ingress-controller/configuration/policy-resource/#egressmtls). | ``boolean`` | No | +{{}} + +### Upstream.Queue + +The queue field configures a queue. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request: + +```yaml +size: 10 +timeout: 60s +``` + +See [`queue`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue) directive for additional information. + +Note: This feature is supported only in NGINX Plus. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``size`` | The size of the queue. | ``int`` | Yes | +|``timeout`` | The timeout of the queue. A request cannot be queued for a period longer than the timeout. The default is ``60s``. | ``string`` | No | +{{}} + +### Upstream.Healthcheck + +The Healthcheck defines an [active health check](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/). In the example below we enable a health check for an upstream and configure all the available parameters, including the `slow-start` parameter combined with [`mandatory` and `persistent`](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#mandatory-health-checks): + +```yaml +name: tea +service: tea-svc +port: 80 +slow-start: 30s +healthCheck: + enable: true + path: /healthz + interval: 20s + jitter: 3s + fails: 5 + passes: 5 + port: 8080 + tls: + enable: true + connect-timeout: 10s + read-timeout: 10s + send-timeout: 10s + headers: + - name: Host + value: my.service + statusMatch: "! 500" + mandatory: true + persistent: true + keepalive-time: 60s +``` + +Note: This feature is supported only in NGINX Plus. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables a health check for an upstream server. The default is ``false``. | ``boolean`` | No | +|``path`` | The path used for health check requests. The default is ``/``. This not configurable for gRPC type upstreams. | ``string`` | No | +|``interval`` | The interval between two consecutive health checks. The default is ``5s``. | ``string`` | No | +|``jitter`` | The time within which each health check will be randomly delayed. By default, there is no delay. | ``string`` | No | +|``fails`` | The number of consecutive failed health checks of a particular upstream server after which this server will be considered unhealthy. The default is ``1``. | ``integer`` | No | +|``passes`` | The number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is ``1``. | ``integer`` | No | +|``port`` | The port used for health check requests. By default, the [server port is used](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html#health_check_port). Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod. | ``integer`` | No | +|``tls`` | The TLS configuration used for health check requests. By default, the ``tls`` field of the upstream is used. | [upstream.tls](#upstreamtls) | No | +|``connect-timeout`` | The timeout for establishing a connection with an upstream server. By default, the ``connect-timeout`` of the upstream is used. | ``string`` | No | +|``read-timeout`` | The timeout for reading a response from an upstream server. By default, the ``read-timeout`` of the upstream is used. | ``string`` | No | +|``send-timeout`` | The timeout for transmitting a request to an upstream server. By default, the ``send-timeout`` of the upstream is used. | ``string`` | No | +|``headers`` | The request headers used for health check requests. NGINX Plus always sets the ``Host`` , ``User-Agent`` and ``Connection`` headers for health check requests. | [[]header](#header) | No | +|``statusMatch`` | The expected response status codes of a health check. By default, the response should have status code 2xx or 3xx. Examples: ``"200"`` , ``"! 500"`` , ``"301-303 307"``. See the documentation of the [match](https://nginx.org/en/docs/http/ngx_http_upstream_hc_module.html?#match) directive. This not supported for gRPC type upstreams. | ``string`` | No | +|``grpcStatus`` | The expected [gRPC status code](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc) of the upstream server response to the [Check method](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). Configure this field only if your gRPC services do not implement the gRPC health checking protocol. For example, configure ``12`` if the upstream server responds with `12 (UNIMPLEMENTED)` status code. Only valid on gRPC type upstreams. | ``int`` | No | +|``grpcService`` | The gRPC service to be monitored on the upstream server. Only valid on gRPC type upstreams. | ``string`` | No | +|``mandatory`` | Require every newly added server to pass all configured health checks before NGINX Plus sends traffic to it. If this is not specified, or is set to false, the server will be initially considered healthy. When combined with [slow-start](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#slow_start), it gives a new server more time to connect to databases and β€œwarm up” before being asked to handle their full share of traffic. | ``bool`` | No | +|``persistent`` | Set the initial β€œup” state for a server after reload if the server was considered healthy before reload. Enabling persistent requires that the mandatory parameter is also set to `true`. | ``bool`` | No | +|``keepalive-time`` | Enables [keepalive](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive) connections for health checks and specifies the time during which requests can be processed through one keepalive connection. The default is ``60s``. | ``string`` | No | +{{}} + +### Upstream.SessionCookie + +The SessionCookie field configures session persistence which allows requests from the same client to be passed to the same upstream server. The information about the designated upstream server is passed in a session cookie generated by NGINX Plus. + +In the example below, we configure session persistence with a session cookie for an upstream and configure all the available parameters: + +```yaml +name: tea +service: tea-svc +port: 80 +sessionCookie: + enable: true + name: srv_id + path: / + expires: 1h + domain: .example.com + httpOnly: false + secure: true + samesite: strict +``` + +See the [`sticky`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html?#sticky) directive for additional information. The session cookie corresponds to the `sticky cookie` method. + +Note: This feature is supported only in NGINX Plus. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``enable`` | Enables session persistence with a session cookie for an upstream server. The default is ``false``. | ``boolean`` | No | +|``name`` | The name of the cookie. | ``string`` | Yes | +|``path`` | The path for which the cookie is set. | ``string`` | No | +|``expires`` | The time for which a browser should keep the cookie. Can be set to the special value ``max`` , which will cause the cookie to expire on ``31 Dec 2037 23:55:55 GMT``. | ``string`` | No | +|``domain`` | The domain for which the cookie is set. | ``string`` | No | +|``httpOnly`` | Adds the ``HttpOnly`` attribute to the cookie. | ``boolean`` | No | +|``secure`` | Adds the ``Secure`` attribute to the cookie. | ``boolean`` | No | +|``samesite`` | Adds the ``SameSite`` attribute to the cookie. The allowed values are: ``strict``, ``lax``, ``none`` | ``string`` | No | +{{}} + +### Header + +The header defines an HTTP Header: + +```yaml +name: Host +value: example.com +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. | ``string`` | No | +{{}} + +### Action + +The action defines an action to perform for a request. + +In the example below, client requests are passed to an upstream `coffee`: + +```yaml + path: /coffee + action: + pass: coffee +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``pass`` | Passes requests to an upstream. The upstream with that name must be defined in the resource. | ``string`` | No | +|``redirect`` | Redirects requests to a provided URL. | [action.redirect](#actionredirect) | No | +|``return`` | Returns a preconfigured response. | [action.return](#actionreturn) | No | +|``proxy`` | Passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers). | [action.proxy](#actionproxy) | No | +{{}} + +\* -- an action must include exactly one of the following: `pass`, `redirect`, `return` or `proxy`. + +### Action.Redirect + +The redirect action defines a redirect to return for a request. + +In the example below, client requests are passed to a url `http://www.nginx.com`: + +```yaml +redirect: + url: http://www.nginx.com + code: 301 +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme`` , ``$http_x_forwarded_proto`` , ``$request_uri`` , ``$host``. Variables must be enclosed in curly braces. For example: ``${host}${request_uri}``. | ``string`` | Yes | +|``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | +{{}} + +### Action.Return + +The return action defines a preconfigured response for a request. + +In the example below, NGINX will respond with the preconfigured response for every request: + +```yaml +return: + code: 200 + type: text/plain + body: "Hello World\n" + headers: + - name: x-coffee + value: espresso +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of the response. The allowed values are: ``2XX``, ``4XX`` or ``5XX``. The default is ``200``. | ``int`` | No | +|``type`` | The MIME type of the response. The default is ``text/plain``. | ``string`` | No | +|``body`` | The body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``Request is ${request_uri}\n``. | ``string`` | Yes | +|``headers`` | The custom headers of the response. | [[]Action.Return.Header](#actionreturnheader) | No | +{{}} + +\* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing` and `$connections_waiting`. + +### Action.Return.Header + +The header defines an HTTP Header for a canned response in an actionReturn: + +```yaml +name: x-coffee +value: espresso +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. | ``string`` | Yes | +{{}} + +### Action.Proxy + +The proxy action passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers). + +In the example below, the request URI is rewritten to `/`, and the request and the response headers are modified: + +```yaml +proxy: + upstream: coffee + requestHeaders: + pass: true + set: + - name: My-Header + value: Value + - name: Client-Cert + value: ${ssl_client_escaped_cert} + responseHeaders: + add: + - name: My-Header + value: Value + - name: IC-Nginx-Version + value: ${nginx_version} + always: true + hide: + - x-internal-version + ignore: + - Expires + - Set-Cookie + pass: + - Server + rewritePath: / +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``upstream`` | The name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource. | ``string`` | Yes | +|``requestHeaders`` | The request headers modifications. | [action.Proxy.RequestHeaders](#actionproxyrequestheaders) | No | +|``responseHeaders`` | The response headers modifications. | [action.Proxy.ResponseHeaders](#actionproxyresponseheaders) | No | +|``rewritePath`` | The rewritten URI. If the route path is a regular expression -- starts with `~` -- the `rewritePath` can include capture groups with ``$1-9``. For example `$1` for the first group, and so on. For more information, check the [rewrite](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/rewrites) example. | ``string`` | No | +{{}} + +### Action.Proxy.RequestHeaders + +The RequestHeaders field modifies the headers of the request to the proxied upstream server. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``pass`` | Passes the original request headers to the proxied upstream server. See the [proxy_pass_request_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_request_headers) directive for more information. Default is true. | ``bool`` | No | +|``set`` | Allows redefining or appending fields to present request headers passed to the proxied upstream servers. See the [proxy_set_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header) directive for more information. | [[]header](#actionproxyrequestheaderssetheader) | No | +{{}} + +### Action.Proxy.RequestHeaders.Set.Header + +The header defines an HTTP Header: + +```yaml +name: My-Header +value: My-Value +``` + +It is possible to override the default value of the `Host` header, which NGINX Ingress Controller sets to [`$host`](https://nginx.org/en/docs/http/ngx_http_core_module.html#var_host): + +```yaml +name: Host +value: example.com +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | +{{}} + +\* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). + +### Action.Proxy.ResponseHeaders + +The ResponseHeaders field modifies the headers of the response to the client. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``hide`` | The headers that will not be passed* in the response to the client from a proxied upstream server. See the [proxy_hide_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_hide_header) directive for more information. | ``[]string`` | No | +|``pass`` | Allows passing the hidden header fields* to the client from a proxied upstream server. See the [proxy_pass_header](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass_header) directive for more information. | ``[]string`` | No | +|``ignore`` | Disables processing of certain headers** to the client from a proxied upstream server. See the [proxy_ignore_headers](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_headers) directive for more information. | ``[]string`` | No | +|``add`` | Adds headers to the response to the client. | [[]addHeader](#addheader) | No | +{{}} + +\* -- Default hidden headers are: `Date`, `Server`, `X-Pad` and `X-Accel-...`. + +\** -- The following fields can be ignored: `X-Accel-Redirect`, `X-Accel-Expires`, `X-Accel-Limit-Rate`, `X-Accel-Buffering`, `X-Accel-Charset`, `Expires`, `Cache-Control`, `Set-Cookie` and `Vary`. + +### AddHeader + +The addHeader defines an HTTP Header with an optional `always` field: + +```yaml +name: My-Header +value: My-Value +always: true +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ``${scheme}``. | ``string`` | No | +|``always`` | If set to true, add the header regardless of the response status code**. Default is false. See the [add_header](http://nginx.org/en/docs/http/ngx_http_headers_module.html#add_header) directive for more information. | ``bool`` | No | +{{}} + +\* -- Supported NGINX variables: `$request_uri`, `$request_method`, `$request_body`, `$scheme`, `$http_`, `$args`, `$arg_`, `$cookie_`, `$host`, `$request_time`, `$request_length`, `$nginx_version`, `$pid`, `$connection`, `$remote_addr`, `$remote_port`, `$time_iso8601`, `$time_local`, `$server_addr`, `$server_port`, `$server_name`, `$server_protocol`, `$connections_active`, `$connections_reading`, `$connections_writing`, `$connections_waiting`, `$ssl_cipher`, `$ssl_ciphers`, `$ssl_client_cert`, `$ssl_client_escaped_cert`, `$ssl_client_fingerprint`, `$ssl_client_i_dn`, `$ssl_client_i_dn_legacy`, `$ssl_client_raw_cert`, `$ssl_client_s_dn`, `$ssl_client_s_dn_legacy`, `$ssl_client_serial`, `$ssl_client_v_end`, `$ssl_client_v_remain`, `$ssl_client_v_start`, `$ssl_client_verify`, `$ssl_curves`, `$ssl_early_data`, `$ssl_protocol`, `$ssl_server_name`, `$ssl_session_id`, `$ssl_session_reused`, `$jwt_claim_` (NGINX Plus only) and `$jwt_header_` (NGINX Plus only). + +{{< note >}} If `always` is false, the response header is added only if the response status code is any of `200`, `201`, `204`, `206`, `301`, `302`, `303`, `304`, `307` or `308`. {{< /note >}} + +### Split + +The split defines a weight for an action as part of the splits configuration. + +In the example below NGINX passes 80% of requests to the upstream `coffee-v1` and the remaining 20% to `coffee-v2`: + +```yaml +splits: +- weight: 80 + action: + pass: coffee-v1 +- weight: 20 + action: + pass: coffee-v2 +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``weight`` | The weight of an action. Must fall into the range ``0..100``. The sum of the weights of all splits must be equal to ``100``. | ``int`` | Yes | +|``action`` | The action to perform for a request. | [action](#action) | Yes | +{{}} + +### Match + +The match defines a match between conditions and an action or splits. + +In the example below, NGINX routes requests with the path `/coffee` to different upstreams based on the value of the cookie `user`: + +- `user=john` -> `coffee-future` +- `user=bob` -> `coffee-deprecated` +- If the cookie is not set or not equal to either `john` or `bob`, NGINX routes to `coffee-stable` + +```yaml +path: /coffee +matches: +- conditions: + - cookie: user + value: john + action: + pass: coffee-future +- conditions: + - cookie: user + value: bob + action: + pass: coffee-deprecated +action: + pass: coffee-stable +``` + +In the next example, NGINX routes requests based on the value of the built-in [`$request_method` variable](https://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_method), which represents the HTTP method of a request: + +- all POST requests -> `coffee-post` +- all non-POST requests -> `coffee` + +```yaml +path: /coffee +matches: +- conditions: + - variable: $request_method + value: POST + action: + pass: coffee-post +action: + pass: coffee +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``conditions`` | A list of conditions. Must include at least 1 condition. | [[]condition](#condition) | Yes | +|``action`` | The action to perform for a request. | [action](#action) | No | +|``splits`` | The splits configuration for traffic splitting. Must include at least 2 splits. | [[]split](#split) | No | +{{}} + +{{< note >}} A match must include exactly one of the following: `action` or `splits`. {{< /note >}} + +### Condition + +The condition defines a condition in a match. + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``header`` | The name of a header. Must consist of alphanumeric characters or ``-``. | ``string`` | No | +|``cookie`` | The name of a cookie. Must consist of alphanumeric characters or ``_``. | ``string`` | No | +|``argument`` | The name of an argument. Must consist of alphanumeric characters or ``_``. | ``string`` | No | +|``variable`` | The name of an NGINX variable. Must start with ``$``. See the list of the supported variables below the table. | ``string`` | No | +|``value`` | The value to match the condition against. How to define a value is shown below the table. | ``string`` | Yes | +{{}} + +{{< note >}} a condition must include exactly one of the following: `header`, `cookie`, `argument` or `variable`. {{< /note >}} + +Supported NGINX variables: `$args`, `$http2`, `$https`, `$remote_addr`, `$remote_port`, `$query_string`, `$request`, `$request_body`, `$request_uri`, `$request_method`, `$scheme`. Find the documentation for each variable [here](https://nginx.org/en/docs/varindex.html). + +The value supports two kinds of matching: + +- *Case-insensitive string comparison*. For example: + - `john` -- case-insensitive matching that succeeds for strings, such as `john`, `John`, `JOHN`. + - `!john` -- negation of the case-insensitive matching for john that succeeds for strings, such as `bob`, `anything`, `''` (empty string). +- *Matching with a regular expression*. Note that NGINX supports regular expressions compatible with those used by the Perl programming language (PCRE). For example: + - `~^yes` -- a case-sensitive regular expression that matches any string that starts with `yes`. For example: `yes`, `yes123`. + - `!~^yes` -- negation of the previous regular expression that succeeds for strings like `YES`, `Yes123`, `noyes`. (The negation mechanism is not part of the PCRE syntax). + - `~*no$` -- a case-insensitive regular expression that matches any string that ends with `no`. For example: `no`, `123no`, `123NO`. + +{{< note >}} A value must not include any unescaped double quotes (`"`) and must not end with an unescaped backslash (`\`). For example, the following are invalid values: `some"value`, `somevalue\`. {{< /note >}} + +### ErrorPage + +The errorPage defines a custom response for a route for the case when either an upstream server responds with (or NGINX generates) an error status code. The custom response can be a redirect or a canned response. See the [error_page](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page) directive for more information. + +```yaml +path: /coffee +errorPages: +- codes: [502, 503] + redirect: + code: 301 + url: https://nginx.org +- codes: [404] + return: + code: 200 + body: "Original resource not found, but success!" +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``codes`` | A list of error status codes. | ``[]int`` | Yes | +|``redirect`` | The redirect action for the given status codes. | [errorPage.Redirect](#errorpageredirect) | No | +|``return`` | The canned response action for the given status codes. | [errorPage.Return](#errorpagereturn) | No | +{{}} + +{{< note >}} An errorPage must include exactly one of the following: `return` or `redirect`. {{< /note >}} + +### ErrorPage.Redirect + +The redirect defines a redirect for an errorPage. + +In the example below, NGINX responds with a redirect when a response from an upstream server has a 404 status code. + +```yaml +codes: [404] +redirect: + code: 301 + url: ${scheme}://cafe.example.com/error.html +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of a redirect. The allowed values are: ``301`` , ``302`` , ``307`` , ``308``. The default is ``301``. | ``int`` | No | +|``url`` | The URL to redirect the request to. Supported NGINX variables: ``$scheme`` and ``$http_x_forwarded_proto``. Variables must be enclosed in curly braces. For example: ``${scheme}``. | ``string`` | Yes | +{{}} + +### ErrorPage.Return + +The return defines a canned response for an errorPage. + +In the example below, NGINX responds with a canned response when a response from an upstream server has either 401 or 403 status code. + +```yaml +codes: [401, 403] +return: + code: 200 + type: application/json + body: | + {\"msg\": \"You don't have permission to do this\"} + headers: + - name: x-debug-original-statuses + value: ${upstream_status} +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``code`` | The status code of the response. The default is the status code of the original response. | ``int`` | No | +|``type`` | The MIME type of the response. The default is ``text/html``. | ``string`` | No | +|``body`` | The body of the response. Supported NGINX variable: ``$upstream_status`` . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | Yes | +|``headers`` | The custom headers of the response. | [[]errorPage.Return.Header](#errorpagereturnheader) | No | +{{}} + +### ErrorPage.Return.Header + +The header defines an HTTP Header for a canned response in an errorPage: + +```yaml +name: x-debug-original-statuses +value: ${upstream_status} +``` + +{{}} +|Field | Description | Type | Required | +| ---| ---| ---| --- | +|``name`` | The name of the header. | ``string`` | Yes | +|``value`` | The value of the header. Supported NGINX variable: ``$upstream_status`` . Variables must be enclosed in curly braces. For example: ``${upstream_status}``. | ``string`` | No | +{{}} + +## Using VirtualServer and VirtualServerRoute + +You can use the usual `kubectl` commands to work with VirtualServer and VirtualServerRoute resources, similar to Ingress resources. + +For example, the following command creates a VirtualServer resource defined in `cafe-virtual-server.yaml` with the name `cafe`: + +```shell +kubectl apply -f cafe-virtual-server.yaml +``` +```text +virtualserver.k8s.nginx.org "cafe" created +``` + +You can get the resource by running: + +```shell +kubectl get virtualserver cafe +``` +```text +NAME STATE HOST IP PORTS AGE +cafe Valid cafe.example.com 12.13.23.123 [80,443] 3m +``` + +In `kubectl get` and similar commands, you can use the short name `vs` instead of `virtualserver`. + +Similarly, for VirtualServerRoute you can use `virtualserverroute` or the short name `vsr`. + +### Using Snippets + +Snippets allow you to insert raw NGINX config into different contexts of NGINX configuration. In the example below, we use snippets to configure several NGINX features in a VirtualServer: + +```yaml +apiVersion: k8s.nginx.org/v1 +kind: VirtualServer +metadata: + name: cafe + namespace: cafe +spec: + http-snippets: | + limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s; + proxy_cache_path /tmp keys_zone=one:10m; + host: cafe.example.com + tls: + secret: cafe-secret + server-snippets: | + limit_req zone=mylimit burst=20; + upstreams: + - name: tea + service: tea-svc + port: 80 + - name: coffee + service: coffee-svc + port: 80 + routes: + - path: /tea + location-snippets: | + proxy_cache one; + proxy_cache_valid 200 10m; + action: + pass: tea + - path: /coffee + action: + pass: coffee +``` + +For additional information, view the [Advanced configuration with Snippets]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) topic. + +### Validation + +Two types of validation are available for VirtualServer and VirtualServerRoute resources: + +- *Structural validation* by the `kubectl` and Kubernetes API server. +- *Comprehensive validation* by NGINX Ingress Controller. + +#### Structural Validation + +The custom resource definitions for VirtualServer and VirtualServerRoute include structural OpenAPI schema which describes the type of every field of those resources. + +If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for the port field of an upstream), `kubectl` and Kubernetes API server will reject such a resource: + +- Example of `kubectl` validation: + + ```shell + kubectl apply -f cafe-virtual-server.yaml + ``` + ```text + error: error validating "cafe-virtual-server.yaml": error validating data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.VirtualServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=false + ``` + +- Example of Kubernetes API server validation: + + ```shell + kubectl apply -f cafe-virtual-server.yaml --validate=false + ``` + ```text + The VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list: + spec.upstreams.port in body must be of type integer: "string" + ``` + +If a resource is not rejected (it doesn't violate the structural schema), NGINX Ingress Controller will validate it further. + +#### Comprehensive Validation + +NGINX Ingress Controller validates the fields of the VirtualServer and VirtualServerRoute resources. If a resource is invalid, NGINX Ingress Controller will reject it: the resource will continue to exist in the cluster, but NGINX Ingress Controller will ignore it. + +You can check if NGINX Ingress Controller successfully applied the configuration for a VirtualServer. For our example `cafe` VirtualServer, we can run: + +```shell +kubectl describe vs cafe +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal AddedOrUpdated 16s nginx-ingress-controller Configuration for default/cafe was added or updated +``` + +Note how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied. + +If you create an invalid resource, NGINX Ingress Controller will reject it and emit a Rejected event. For example, if you create a VirtualServer `cafe` with two upstream with the same name `tea`, you will get: + +```shell +kubectl describe vs cafe +``` +```text +... +Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Warning Rejected 12s nginx-ingress-controller VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea" +``` + +Note how the events section includes a Warning event with the Rejected reason. + +Additionally, this information is also available in the `status` field of the VirtualServer resource. Note the Status section of the VirtualServer: + +```shell +kubectl describe vs cafe +``` +```text +... +Status: + External Endpoints: + Ip: 12.13.23.123 + Ports: [80,443] + Message: VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea" + Reason: Rejected + State: Invalid +``` + +NGINX Ingress Controller validates VirtualServerRoute resources in a similar way. + +**Note**: If you make an existing resource invalid, NGINX Ingress Controller will reject it and remove the corresponding configuration from NGINX. + +## Customization using ConfigMap + +You can customize the NGINX configuration for VirtualServer and VirtualServerRoutes resources using the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource). Most of the ConfigMap keys are supported, with the following exceptions: + +- `proxy-hide-headers` +- `proxy-pass-headers` +- `hsts` +- `hsts-max-age` +- `hsts-include-subdomains` +- `hsts-behind-proxy` +- `redirect-to-https` +- `ssl-redirect` diff --git a/content/includes/nic/installation/create-common-resources.md b/content/includes/nic/installation/create-common-resources.md new file mode 100644 index 000000000..db3ef05ea --- /dev/null +++ b/content/includes/nic/installation/create-common-resources.md @@ -0,0 +1,27 @@ +--- +nd-docs: DOCS-1464 +--- + +In this section, you'll create resources that most NGINX Ingress Controller installations require: + +1. (Optional) Create a secret for the default NGINX server's TLS certificate and key. Complete this step only if you're using the [default server TLS secret]({{< ref "/nic/configuration/global-configuration/command-line-arguments#cmdoption-default-server-tls-secret.md" >}}) command-line argument. If you're not, feel free to skip this step. + + By default, the server returns a _404 Not Found_ page for all requests when no ingress rules are set up. Although we provide a self-signed certificate and key for testing purposes, we recommend using your own certificate. + + ```shell + kubectl apply -f examples/shared-examples/default-server-secret/default-server-secret.yaml + ``` + +2. Create a ConfigMap to customize your NGINX settings: + + ```shell + kubectl apply -f deployments/common/nginx-config.yaml + ``` + +3. Create an `IngressClass` resource. NGINX Ingress Controller won't start without an `IngressClass` resource. + + ```shell + kubectl apply -f deployments/common/ingress-class.yaml + ``` + + If you want to make this NGINX Ingress Controller instance your cluster's default, uncomment the `ingressclass.kubernetes.io/is-default-class` annotation. This action will auto-assign `IngressClass` to new ingresses that don't specify an `ingressClassName`. diff --git a/content/includes/nic/installation/create-custom-resources.md b/content/includes/nic/installation/create-custom-resources.md new file mode 100644 index 000000000..dbdbf6065 --- /dev/null +++ b/content/includes/nic/installation/create-custom-resources.md @@ -0,0 +1,49 @@ +--- +nd-docs: DOCS-1463 +--- + +To make sure your NGINX Ingress Controller pods reach the `Ready` state, you'll need to create custom resource definitions (CRDs) for various components. + +Alternatively, you can disable this requirement by setting the `-enable-custom-resources` command-line argument to `false`. + +There are two ways you can install the custom resource definitions: + +1. Using a URL to apply a single CRD yaml file, which we recommend. +1. Applying your local copy of the CRD yaml files, which requires you to clone the repository. + +The core custom CRDs are the following: + +- [VirtualServer and VirtualServerRoute]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources.md" >}}) +- [TransportServer]({{< ref "/nic/configuration/transportserver-resource.md" >}}) +- [Policy]({{< ref "/nic/configuration/policy-resource.md" >}}) +- [GlobalConfiguration]({{< ref "/nic/configuration/global-configuration/globalconfiguration-resource.md" >}}) + +{{}} + +{{%tab name="Install CRDs from single YAML"%}} + +```shell +kubectl apply -f https://raw.githubusercontent.com/nginx/kubernetes-ingress/v{{< nic-version >}}/deploy/crds.yaml +``` + +{{%/tab%}} + +{{%tab name="Install CRDs after cloning the repo"%}} + +{{< note >}} If you are installing the CRDs this way, ensure you have first cloned the repository. {{< /note >}} + +{{< note >}} Please make sure to read the steps outlined in [Upgrade to V4](https://docs.nginx.com/nginx-ingress-controller/installation/installing-nic/upgrade-to-v4/#update-custom-resource-apiversion) before running the CRD upgrade and perform the steps if applicable. +{{< /note >}} + + +```shell +kubectl apply -f config/crd/bases/k8s.nginx.org_virtualservers.yaml +kubectl apply -f config/crd/bases/k8s.nginx.org_virtualserverroutes.yaml +kubectl apply -f config/crd/bases/k8s.nginx.org_transportservers.yaml +kubectl apply -f config/crd/bases/k8s.nginx.org_policies.yaml +kubectl apply -f config/crd/bases/k8s.nginx.org_globalconfigurations.yaml +``` + +{{%/tab%}} + +{{}} diff --git a/content/includes/nic/installation/deploy-controller.md b/content/includes/nic/installation/deploy-controller.md new file mode 100644 index 000000000..7dcec97bd --- /dev/null +++ b/content/includes/nic/installation/deploy-controller.md @@ -0,0 +1,10 @@ +--- +nd-docs: DOCS-1462 +--- + +You have two options for deploying NGINX Ingress Controller: + +- **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. +- **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. + +Before you start, update the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements. diff --git a/content/includes/nic/installation/download-jwt.md b/content/includes/nic/installation/download-jwt.md new file mode 100644 index 000000000..78ad1cbf8 --- /dev/null +++ b/content/includes/nic/installation/download-jwt.md @@ -0,0 +1,10 @@ +--- +nd-docs: "DOCS-000" +--- + +1. Log in to [MyF5](https://my.f5.com/manage/s/). +2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. +3. Find your NGINX products or services subscription, and select the **Subscription ID** for details. +4. Download the **JSON Web Token (JWT)** from the subscription page. + +{{< note >}} The Connectivity Stack for Kubernetes JWT does not work with NGINX Plus reporting. A regular NGINX Plus instance JWT must be used. {{< /note >}} diff --git a/content/includes/nic/installation/jwt-password-note.md b/content/includes/nic/installation/jwt-password-note.md new file mode 100644 index 000000000..040a3e142 --- /dev/null +++ b/content/includes/nic/installation/jwt-password-note.md @@ -0,0 +1,11 @@ +--- +nd-docs: +--- + +{{< note >}} For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history: + +1. **JWTs:** JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access. + +1. **Shell history:** Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your `~/.bash_history` file. Alternatively, you can run the `history -c` command to erase your shell history. + +Follow these practices to help ensure the security of your system and data. {{< /note >}} diff --git a/content/includes/nic/installation/manifests/daemonset.md b/content/includes/nic/installation/manifests/daemonset.md new file mode 100644 index 000000000..ff9cb072b --- /dev/null +++ b/content/includes/nic/installation/manifests/daemonset.md @@ -0,0 +1,21 @@ +--- +nd-docs: DOCS-1465 +--- + +For additional context on managing containers using Kubernetes DaemonSets, refer to the official Kubernetes [DaemonSets](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/) documentation. + +When you deploy NGINX Ingress Controller as a DaemonSet, Kubernetes creates an Ingress Controller pod on every node in the cluster. + +- For NGINX, run: + + ```shell + kubectl apply -f deployments/daemon-set/nginx-ingress.yaml + ``` + +- For NGINX Plus, run: + + ```shell + kubectl apply -f deployments/daemon-set/nginx-plus-ingress.yaml + ``` + + Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image. diff --git a/content/includes/nic/installation/manifests/deployment.md b/content/includes/nic/installation/manifests/deployment.md new file mode 100644 index 000000000..1c0f4932f --- /dev/null +++ b/content/includes/nic/installation/manifests/deployment.md @@ -0,0 +1,21 @@ +--- +nd-docs: DOCS-1467 +--- + +For additional context on managing containers using Kubernetes Deployments, refer to the official Kubernetes [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) documentation. + +When you deploy NGINX Ingress Controller as a Deployment, Kubernetes automatically sets up a single NGINX Ingress Controller pod. + +- For NGINX, run: + + ```shell + kubectl apply -f deployments/deployment/nginx-ingress.yaml + ``` + +- For NGINX Plus, run: + + ```shell + kubectl apply -f deployments/deployment/nginx-plus-ingress.yaml + ``` + + Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image. diff --git a/content/includes/nic/installation/manifests/verify-pods-are-running.md b/content/includes/nic/installation/manifests/verify-pods-are-running.md new file mode 100644 index 000000000..79976859f --- /dev/null +++ b/content/includes/nic/installation/manifests/verify-pods-are-running.md @@ -0,0 +1,10 @@ +--- +nd-docs: DOCS-1466 +--- + + +To confirm the NGINX Ingress Controller pods are operational, run: + +```shell +kubectl get pods --namespace=nginx-ingress +``` diff --git a/content/includes/nic/rbac/set-up-rbac.md b/content/includes/nic/rbac/set-up-rbac.md new file mode 100644 index 000000000..eaf9a6c6f --- /dev/null +++ b/content/includes/nic/rbac/set-up-rbac.md @@ -0,0 +1,33 @@ +--- +nd-docs: DOCS-1468 +--- + +{{}}To complete these steps you need admin access to your cluster. Refer to to your Kubernetes platform's documentation to set up admin access. For Google Kubernetes Engine (GKE), you can refer to their [Role-Based Access Control guide](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control).{{}} + +1. Create a namespace and a service account: + + ```shell + kubectl apply -f deployments/common/ns-and-sa.yaml + ``` + +2. Create a cluster role and binding for the service account: + + ```shell + kubectl apply -f deployments/rbac/rbac.yaml + ``` + +
    + +If you're planning to use NGINX App Protect or NGINX App Protect DoS, additional roles and bindings are needed. + +1. (NGINX App Protect only) Create the *App Protect* role and binding: + + ```shell + kubectl apply -f deployments/rbac/ap-rbac.yaml + ``` + +2. (NGINX App Protect DoS only) Create the *App Protect DoS* role and binding: + + ```shell + kubectl apply -f deployments/rbac/apdos-rbac.yaml + ``` diff --git a/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md b/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md index 6e94ced35..fd850214f 100644 --- a/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md +++ b/content/includes/nim/admin-guide/auth/basic-auth-api-requests.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1295 +nd-docs: DOCS-1295 --- To use basic authentication for API requests, include your base64-encoded credentials as a "Basic" token in the "Authorization" header. To create the base64-encoded credentials, run the following command: diff --git a/content/includes/nim/admin-guide/license/add-license-webui.md b/content/includes/nim/admin-guide/license/add-license-webui.md index 805615b34..709d58e38 100644 --- a/content/includes/nim/admin-guide/license/add-license-webui.md +++ b/content/includes/nim/admin-guide/license/add-license-webui.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1660" +nd-docs: "DOCS-1660" --- 1. Go to the FQDN of your NGINX Instance Manager host and log in. diff --git a/content/includes/nim/admin-guide/license/connected-install-license-note.md b/content/includes/nim/admin-guide/license/connected-install-license-note.md index 251043df4..9490e3fe3 100644 --- a/content/includes/nim/admin-guide/license/connected-install-license-note.md +++ b/content/includes/nim/admin-guide/license/connected-install-license-note.md @@ -4,4 +4,4 @@ docs: A valid license is required to make full use of all the features in NGINX Instance Manager. -Refer to the [Add a License]({{< ref "nim/admin-guide/license/add-license.md" >}}) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license. \ No newline at end of file +Refer to the [Add a License]({{< ref "nim/admin-guide/add-license.md" >}}) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license. \ No newline at end of file diff --git a/content/includes/nim/clickhouse/cli-skip-clickhouse.md b/content/includes/nim/clickhouse/cli-skip-clickhouse.md new file mode 100644 index 000000000..f4228b125 --- /dev/null +++ b/content/includes/nim/clickhouse/cli-skip-clickhouse.md @@ -0,0 +1,10 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +If you skip installing ClickHouse, you need NGINX Agent {{< lightweight-nim-nginx-agent-version >}}. + +After installation, make sure to [disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}) in the `/etc/nms/nms.conf` file. diff --git a/content/includes/nim/clickhouse/clickhouse-defaults.md b/content/includes/nim/clickhouse/clickhouse-defaults.md new file mode 100644 index 000000000..0fcb4cfd8 --- /dev/null +++ b/content/includes/nim/clickhouse/clickhouse-defaults.md @@ -0,0 +1,23 @@ +--- +nd-docs: DOCS-1238 +files: +- content/nim/system-configuration/configure-clickhouse.md +- content/nim/deploy/vm-bare-metal/install-nim-manual.md +--- + +{{}} + +| Configuration | Default | Notes | +|------------------------------|------------------------------------|-------| +| clickhouse.enable | true | Set to `false` to disable metrics collection and run NGINX Instance Manager in lightweight mode. Requires a service restart. | +| clickhouse.address | tcp://localhost:9000 | The address of the ClickHouse database. | +| clickhouse.username | | The username NGINX Instance Manager uses to connect to ClickHouse, if authentication is enabled. | +| clickhouse.password | | The password for the specified ClickHouse user. | +| clickhouse.tls_mode | false | Set to `true` to enable TLS for the ClickHouse connection. This setting will be deprecated in a future release. Use the `clickhouse.tls` section instead. | +| clickhouse.tls.address | tcp://localhost:9440 | The address NGINX Instance Manager uses to connect to ClickHouse over TLS. Format: `:`. | +| clickhouse.tls.skip_verify | false | Set to `true` to skip TLS certificate verification. Use only for self-signed certificates in non-production environments. | +| clickhouse.tls.key_path | | Path to the client TLS key file in PEM format. Required for client authentication. | +| clickhouse.tls.cert_path | | Path to the client TLS certificate file in PEM format. Required for client authentication. | +| clickhouse.tls.ca_path | /etc/ssl/certs/ca-certificates.crt | Path to the system Certificate Authority used to verify the server certificate. The default path works for Ubuntu and Debian. Use a CA bundle appropriate to your system. See [TLS configuration](#tls) for details. | + +{{}} diff --git a/content/includes/nim/clickhouse/clickhouse-install.md b/content/includes/nim/clickhouse/clickhouse-install.md new file mode 100644 index 000000000..961aed96b --- /dev/null +++ b/content/includes/nim/clickhouse/clickhouse-install.md @@ -0,0 +1,70 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install-nim-manual.md +--- + +NGINX Instance Manager uses [ClickHouse](https://clickhouse.com) to store metrics, events, alerts, and configuration settings. + +If you install ClickHouse and choose to set a password (the default is an empty string), you must add it to the `clickhouse.password` setting in the `/etc/nms/nms.conf` file. If the password is missing or incorrect, NGINX Instance Manager **will not start**. + +For instructions and additional configuration options, including TLS settings, see [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}). + +NGINX Instance Manager requires ClickHouse version {{< clickhouse-version >}} or later. + + +Follow these steps to install and enable ClickHouse on supported Linux distributions. + +1. First, set up the repository. + + - For RPM-based systems (CentOS, RHEL): + + ```shell + sudo yum install -y yum-utils + sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo + ``` + + - For Debian-based systems (Debian, Ubuntu): + + ```shell + sudo apt-get install -y apt-transport-https ca-certificates dirmngr + GNUPGHOME=$(mktemp -d) + sudo GNUPGHOME="$GNUPGHOME" gpg --no-default-keyring --keyring /usr/share/keyrings/clickhouse-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 8919F6BD2B48D754 + sudo rm -r "$GNUPGHOME" + sudo chmod +r /usr/share/keyrings/clickhouse-keyring.gpg + + echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list + sudo apt-get update + ``` + +2. Next, install the ClickHouse server and client: + + - For RPM-based systems (CentOS, RHEL): + + ```shell + sudo yum install -y clickhouse-server clickhouse-client + ``` + + - For Debian-based systems (Debian, Ubuntu): + + ```shell + sudo apt-get install -y clickhouse-server clickhouse-client + ``` + +3. Then, enable the ClickHouse service so it starts automatically on reboot: + + ```shell + sudo systemctl enable clickhouse-server + ``` + +4. Start the ClickHouse service: + + ```shell + sudo systemctl start clickhouse-server + ``` + +5. Finally, confirm the service is running: + + ```shell + sudo systemctl status clickhouse-server + ``` diff --git a/content/includes/nim/decoupling/note-legacy-nms-references.md b/content/includes/nim/decoupling/note-legacy-nms-references.md index 2f2263f25..89c87b10e 100644 --- a/content/includes/nim/decoupling/note-legacy-nms-references.md +++ b/content/includes/nim/decoupling/note-legacy-nms-references.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1661" +nd-docs: "DOCS-1661" --- {{}}Some commands, file paths, and configuration references still use `nms` due to the ongoing transition from NGINX Management Suite (NMS) to NGINX Instance Manager (NIM). These will be updated in future releases.{{}} \ No newline at end of file diff --git a/content/includes/nim/disconnected/license-usage-offline-script.md b/content/includes/nim/disconnected/license-usage-offline-script.md index 6f3578cea..72a5e49e0 100644 --- a/content/includes/nim/disconnected/license-usage-offline-script.md +++ b/content/includes/nim/disconnected/license-usage-offline-script.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1662" +nd-docs: "DOCS-1662" ---
    @@ -26,13 +26,13 @@ if [ "$1" = "-h" ] || [ "$1" = "--help" ]; then echo echo "For Licensing in Disconnected Mode:" echo "$0 -j my-jwt.jwt -i -u admin -p -o report.zip -s initial" - echo + echo echo "For Usage Reporting in Disconnected Mode:" echo "$0 -j my-jwt.jwt -i -u admin -p -o report.zip -s telemetry" - echo - echo "Note: Since NGINX Instance Manager comes with self-signed certificates by default, the --insecure flag is set in this script to run specific Curl commands." + echo + echo "Note: Since NGINX Instance Manager comes with self-signed certificates by default, the --insecure flag is set in this script to run specific Curl commands." echo "You can alter this script if you wish to change from self-signed to verified certificates in Instance Manager." - echo + echo exit 1 fi diff --git a/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md b/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md index 327fd7f18..066afb1b8 100644 --- a/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md +++ b/content/includes/nim/disconnected/set-mode-of-operation-disconnected.md @@ -1,5 +1,5 @@ --- -docs: "DOCS-1663" +nd-docs: "DOCS-1663" --- 1. Open the `/etc/nms/nms.conf` file and add the following in the `integrations:license` section: diff --git a/content/includes/nim/docker/docker-compose-env-vars.md b/content/includes/nim/docker/docker-compose-env-vars.md index c34e6e767..5fb837435 100644 --- a/content/includes/nim/docker/docker-compose-env-vars.md +++ b/content/includes/nim/docker/docker-compose-env-vars.md @@ -4,14 +4,15 @@ docs: {{}} | Variable | Category | Description | -|----------|----------|------------| +|----------|----------|-------------| +| **ENABLE_METRICS** | General | Enables or disables metrics collection and storage. Set to `false` to run in lightweight mode without ClickHouse. Defaults to `true`. | +| **NIM_MAINTENANCE** | General | Enables maintenance mode for backup, restore, and troubleshooting (`true` or `false`). | +| **NIM_LICENSE_MODE_OF_OPERATION** | General | Sets the license mode to either `connected` (default) or `disconnected`. | | **NIM_LOG_LEVEL** | General | Sets the logging level for NGINX Instance Manager. | | **NIM_METRICS_TTL** | General | Specifies the number of days to retain metrics. | | **NIM_EVENTS_TTL** | General | Specifies the number of days to retain event logs. | | **NIM_SECURITY_TTL** | General | Specifies the number of days to retain security violation logs. | -| **NIM_MAINTENANCE** | General | Enables maintenance mode for backup, restore, and troubleshooting (`true` or `false`). | | **NIM_WATCHDOG_TIMEOUT** | General | Sets the timeout (in seconds) for the Data Plane Monitoring (DPM) watchdog. | -| **NIM_LICENSE_MODE_OF_OPERATION** | General | Sets the license mode to either `connected` (default) or `disconnected`. | | **PROXY_ENABLE** | Forward Proxy | Enables or disables the use of a forward proxy (`true` or `false`). | | **PROXY_HOST** | Forward Proxy | The IP address or hostname of the proxy server. | | **PROXY_PORT** | Forward Proxy | The port number of the proxy server. | @@ -20,7 +21,6 @@ docs: | **PROXY_USERNAME** | Forward Proxy | (Required if `PROXY_AUTH_REQUIRED=true`) The username for proxy authentication. | | **PROXY_PASSWORD** | Forward Proxy | (Required if `PROXY_AUTH_REQUIRED=true`) The password for proxy authentication. | | **PROXY_SSL_VERIFY** | Forward Proxy | Enables or disables SSL verification when `PROXY_PROTOCOL=https`. Default is `true`, meaning the proxy must have a valid certificate issued by a trusted Certificate Authority (CA). Set to `false` to allow self-signed or untrusted certificates (not recommended). | - {{}} diff --git a/content/includes/nim/docker/docker-registry-login.md b/content/includes/nim/docker/docker-registry-login.md index 05de77a8a..961380426 100644 --- a/content/includes/nim/docker/docker-registry-login.md +++ b/content/includes/nim/docker/docker-registry-login.md @@ -1,12 +1,12 @@ --- -docs: "DOCS-1666" +nd-docs: "DOCS-1666" --- 1. Download your NGINX Instance Manager subscription's JSON Web Token from MyF5. You can use the same JSON Web Token as NGINX Plus in your MyF5 portal. {{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} -1. Open the JSON Web Token file you downloaded from [MyF5](https://my.f5.com/manage/s/subscriptions) and copy its contents. +1. Open the JSON Web Token file you downloaded from [MyF5](https://my.f5.com/manage/s/subscriptions) and copy its contents. {{}} Make sure there are **no extra characters or spaces** when copying the contents of the JWT token: they can invalidate the token and cause 401 errors during authentication.{{}} diff --git a/content/includes/nim/how-to-access-api-docs.md b/content/includes/nim/how-to-access-api-docs.md index 26a1e6d8a..4375880e2 100644 --- a/content/includes/nim/how-to-access-api-docs.md +++ b/content/includes/nim/how-to-access-api-docs.md @@ -1,5 +1,5 @@ --- -docs: DOCS-991 +nd-docs: DOCS-991 --- You can access the NGINX Instance Manager API documentation from the web interface: diff --git a/content/includes/nim/how-to-access-nim-api.md b/content/includes/nim/how-to-access-nim-api.md index d5af8cac6..66cea5c68 100644 --- a/content/includes/nim/how-to-access-nim-api.md +++ b/content/includes/nim/how-to-access-nim-api.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1050 +nd-docs: DOCS-1050 --- You can use tools like `curl` or [Postman](https://www.postman.com) to interact with the NGINX Instance Manager REST API. The API URL is `https:///api/[nim|platform]/`, and each request requires authentication. For more details on authentication options, see the [API Overview]({{< ref "/nim/fundamentals/api-overview.md" >}}). diff --git a/content/includes/nim/installation/install-script-flags/cert.md b/content/includes/nim/installation/install-script-flags/cert.md new file mode 100644 index 000000000..578f9ff2c --- /dev/null +++ b/content/includes/nim/installation/install-script-flags/cert.md @@ -0,0 +1,8 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +`-c `: Path to the SSL certificate file. (default: `/etc/ssl/nginx`) \ No newline at end of file diff --git a/content/includes/nim/installation/install-script-flags/clickhouse-version.md b/content/includes/nim/installation/install-script-flags/clickhouse-version.md new file mode 100644 index 000000000..aaf5e1849 --- /dev/null +++ b/content/includes/nim/installation/install-script-flags/clickhouse-version.md @@ -0,0 +1,8 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +`-v `: Install a specific version of ClickHouse. If not set, version `{{< clickhouse-version >}}` is installed by default. diff --git a/content/includes/nim/installation/install-script-flags/distribution.md b/content/includes/nim/installation/install-script-flags/distribution.md new file mode 100644 index 000000000..7132ad0e0 --- /dev/null +++ b/content/includes/nim/installation/install-script-flags/distribution.md @@ -0,0 +1,14 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +`-d `: Target Linux distribution (for example, `ubuntu22.04`, `rhel8`) + +To see the list of supported distributions, run: + +```shell +install-nim-bundle.sh -l +``` \ No newline at end of file diff --git a/content/includes/nim/installation/install-script-flags/key.md b/content/includes/nim/installation/install-script-flags/key.md new file mode 100644 index 000000000..366786c45 --- /dev/null +++ b/content/includes/nim/installation/install-script-flags/key.md @@ -0,0 +1,8 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +`-k `: Path to the private key file. (default: `/etc/ssl/nginx`) diff --git a/content/includes/nim/installation/install-script-flags/skip-clickhouse.md b/content/includes/nim/installation/install-script-flags/skip-clickhouse.md new file mode 100644 index 000000000..93a61aeb7 --- /dev/null +++ b/content/includes/nim/installation/install-script-flags/skip-clickhouse.md @@ -0,0 +1,10 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide.md +--- + +`-s`: Skip installing ClickHouse. This lightweight mode reduces system requirements and simplifies installation for users who do not need metrics. + +{{< include "nim/clickhouse/cli-skip-clickhouse.md" >}} \ No newline at end of file diff --git a/content/includes/nim/installation/optional-steps/configure-clickhouse.md b/content/includes/nim/installation/optional-steps/configure-clickhouse.md new file mode 100644 index 000000000..c2a086cd5 --- /dev/null +++ b/content/includes/nim/installation/optional-steps/configure-clickhouse.md @@ -0,0 +1,23 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/deploy/vm-bare-metal/install-nim-manual.md +- content/nim/disconnected/offline-install-guide.md +- content/nim/disconnected/offline-install-guide-manual.md +--- + +If you installed ClickHouse and set a password (the default is an empty string), you must add it to the `clickhouse.password` setting in the `/etc/nms/nms.conf` file after installing NGINX Instance Manager. If the password is missing or incorrect, NGINX Instance Manager will not start. + +You can also configure additional ClickHouse settings in the same section: + +- `clickhouse.username` – the username used to connect to ClickHouse +- `clickhouse.address` – the address of the ClickHouse server (default is `tcp://localhost:9000`) +- `clickhouse.tls_mode` – set to `true` to enable TLS +- TLS certificate settings, such as: + - `clickhouse.tls.cert_path` + - `clickhouse.tls.key_path` + - `clickhouse.tls.ca_path` + - `clickhouse.tls.skip_verify` + +For more details, see [Configure ClickHouse]({{< ref "nim/system-configuration/configure-clickhouse.md" >}}). \ No newline at end of file diff --git a/content/includes/nim/installation/optional-steps/configure-selinux.md b/content/includes/nim/installation/optional-steps/configure-selinux.md new file mode 100644 index 000000000..730c97811 --- /dev/null +++ b/content/includes/nim/installation/optional-steps/configure-selinux.md @@ -0,0 +1,12 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install-nim-manual.md +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide-manual.md +- content/nim/disconnected/offline-install-guide.md +--- + +SELinux helps secure your deployment by enforcing mandatory access control policies. + +If you use SELinux, follow the steps in the [Configure SELinux]({{< ref "/nim/system-configuration/configure-selinux.md" >}}) guide to restore SELinux contexts (`restorecon`) for the files and directories related to NGINX Instance Manager. diff --git a/content/includes/nim/installation/optional-steps/disable-metrics-collection.md b/content/includes/nim/installation/optional-steps/disable-metrics-collection.md new file mode 100644 index 000000000..3204e6299 --- /dev/null +++ b/content/includes/nim/installation/optional-steps/disable-metrics-collection.md @@ -0,0 +1,11 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide-manual.md +- content/nim/disconnected/offline-install-guide.md +--- + +If you’re not collecting metrics β€” because you didn’t install ClickHouse or don’t plan to use it β€” you must disable metrics collection in the `/etc/nms/nms.conf` and `/etc/nms/nms-sm-conf.yaml` files. This setup requires NGINX Agent version {{< lightweight-nim-nginx-agent-version >}}. + +For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}). \ No newline at end of file diff --git a/content/includes/nim/installation/optional-steps/install-configure-vault.md b/content/includes/nim/installation/optional-steps/install-configure-vault.md new file mode 100644 index 000000000..6d39a002a --- /dev/null +++ b/content/includes/nim/installation/optional-steps/install-configure-vault.md @@ -0,0 +1,16 @@ +--- +docs: +files: +- content/nim/deploy/vm-bare-metal/install-nim-manual.md +- content/nim/deploy/vm-bare-metal/install.md +- content/nim/disconnected/offline-install-guide-manual.md +- content/nim/disconnected/offline-install-guide.md +--- + +NGINX Instance Manager can use [Vault](https://www.vaultproject.io/) as a datastore for secrets. + +To install and enable Vault, follow these steps: + +- Follow Vault's instructions to [install Vault 1.8.8 or later](https://www.vaultproject.io/docs/install) for your distribution. +- Ensure you're running Vault in a [production-hardened environment](https://learn.hashicorp.com/tutorials/vault/production-hardening). +- After installing NGINX Instance Manager, follow the steps to [configure Vault for storing secrets]({{< ref "/nim/system-configuration/configure-vault.md" >}}). diff --git a/content/includes/nim/kubernetes/access-webui-helm.md b/content/includes/nim/kubernetes/access-webui-helm.md index f64a81072..76e22288e 100644 --- a/content/includes/nim/kubernetes/access-webui-helm.md +++ b/content/includes/nim/kubernetes/access-webui-helm.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1323 +nd-docs: DOCS-1323 --- You can access the NGINX Instance Manager web interface using the external IP address for the API Gateway. @@ -7,10 +7,10 @@ You can access the NGINX Instance Manager web interface using the external IP ad 1. To look up the external IP address for the API Gateway, run the following command: ```bash - kubectl -n nms get svc apigw + kubectl -n nim get svc apigw ``` - This `kubectl` command retrieves the service named `apigw` from the namespace `nms`. It outputs the details of the service, such as its type, port, cluster and external IP addresses. + This `kubectl` command shows details for the `apigw` service in the `nim` namespace. You’ll see the service type, port, cluster IP, and external IP addresses. The default service type is `ClusterIP` and the output looks similar to the following example: diff --git a/content/includes/nim/kubernetes/nms-chart-supported-module-versions.md b/content/includes/nim/kubernetes/nms-chart-supported-module-versions.md index f55e661b5..ab9779cf4 100644 --- a/content/includes/nim/kubernetes/nms-chart-supported-module-versions.md +++ b/content/includes/nim/kubernetes/nms-chart-supported-module-versions.md @@ -1,39 +1,24 @@ --- -docs: DOCS-1324 +nd-docs: DOCS-1324 --- {{}} -| NGINX Instance Manager chart | Instance Manager | -|------------------------------|------------------| -| 1.15.0 | 2.18.0 | -| 1.14.4 | 2.17.4 | -| 1.14.0 | 2.17.0 | -| 1.13.0 | 2.16.0 | -| 1.12.1 | 2.15.1 | -| 1.12.0 | 2.15.0 | -| 1.11.0 | 2.14.0 | -| 1.10.1 | 2.13.1 | -| 1.10.0 | 2.13.1 | -| 1.9.0 | 2.13.0 | -| 1.8.2 | 2.12.0 | -| 1.8.1 | 2.12.0 | -| 1.8.0 | 2.12.0 | -| 1.7.2 | 2.11.0 | -| 1.7.1 | 2.11.0 | -| 1.7.0 | 2.11.0 | -| 1.6.0 | 2.10.1 | -| 1.5.2 | 2.10.0 | -| 1.5.1 | 2.10.0 | -| 1.5.0 | 2.10.0 | -| 1.4.0 | 2.9.1 | -| 1.3.1 | 2.9.0 | -| 1.3.0 | 2.9.0 | -| 1.2.1 | 2.8.0 | -| 1.2.0 | 2.8.0 | -| 1.1.2 | 2.7.0 | -| 1.1.1 | 2.7.0 | -| 1.1.0 | 2.7.0 | -| 1.0.0 | 2.6.0 | +| NGINX Instance Manager chart | Chart | Instance Manager | +|------------------------------|----------------------------|------------------| +| 2.0.0 | nginx-stable/nim | 2.20.0 | +| 2.19.2 | nginx-stable/nms-hybrid | 2.19.2 | +| 2.19.1 | nginx-stable/nms-hybrid | 2.19.1 | +| 2.19.0 | nginx-stable/nms-hybrid | 2.19.0 | +| 1.15.0 | ngnx-stable/nms | 2.18.0 | +| 1.14.4 | ngnx-stable/nms | 2.17.4 | +| 1.14.0 | ngnx-stable/nms | 2.17.0 | +| 1.13.0 | ngnx-stable/nms | 2.16.0 | +| 1.12.1 | ngnx-stable/nms | 2.15.1 | +| 1.12.0 | ngnx-stable/nms | 2.15.0 | +| 1.11.0 | ngnx-stable/nms | 2.14.0 | +| 1.10.1 | ngnx-stable/nms | 2.13.1 | +| 1.10.0 | ngnx-stable/nms | 2.13.1 | +| 1.9.0 | ngnx-stable/nms | 2.13.0 | {{}} diff --git a/content/includes/nim/nap-waf/restart-nms-integrations.md b/content/includes/nim/nap-waf/restart-nms-integrations.md index bca3636f9..e0e0a7f64 100644 --- a/content/includes/nim/nap-waf/restart-nms-integrations.md +++ b/content/includes/nim/nap-waf/restart-nms-integrations.md @@ -1,5 +1,5 @@ --- -docs: DOCS-000 +nd-docs: DOCS-000 files: - content/nim/nginx-app-protect/setup-waf-config-management.md --- diff --git a/content/includes/nim/rbac/assign-roles-to-user-groups.md b/content/includes/nim/rbac/assign-roles-to-user-groups.md index 961de496a..9c3b03292 100644 --- a/content/includes/nim/rbac/assign-roles-to-user-groups.md +++ b/content/includes/nim/rbac/assign-roles-to-user-groups.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1301 +nd-docs: DOCS-1301 --- {{< call-out "important" "User groups require an OIDC identity provider" >}}User groups require an external identity provider configured for OpenID Connect (OIDC) authentication, as described in [Getting started with OIDC]({{< ref "/nim/admin-guide/authentication/oidc/getting-started.md" >}}). Users from an external identity provider cannot be assigned roles directly in NGINX Instance Manager. Instead, they inherit roles based on their group membership.{{< /call-out >}} diff --git a/content/includes/nim/rbac/assign-roles-to-users.md b/content/includes/nim/rbac/assign-roles-to-users.md index 4c50bb72c..040a4cf52 100644 --- a/content/includes/nim/rbac/assign-roles-to-users.md +++ b/content/includes/nim/rbac/assign-roles-to-users.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1025 +nd-docs: DOCS-1025 --- To assign roles to a user in NGINX Instance Manager, follow these steps: diff --git a/content/includes/nim/rbac/create-roles.md b/content/includes/nim/rbac/create-roles.md index 174ed3057..1fd1d37f8 100644 --- a/content/includes/nim/rbac/create-roles.md +++ b/content/includes/nim/rbac/create-roles.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1028 +nd-docs: DOCS-1028 --- Roles in NGINX Instance Manager are a critical part of [role-based access control (RBAC)]({{< ref "/nim/admin-guide/rbac/overview-rbac.md" >}}). By creating roles, you define the access levels and permissions for different user groups that correspond to groups in your Identity Provider (IdP). diff --git a/content/includes/nim/rbac/create-user-groups.md b/content/includes/nim/rbac/create-user-groups.md index 2504af468..9c9c1db12 100644 --- a/content/includes/nim/rbac/create-user-groups.md +++ b/content/includes/nim/rbac/create-user-groups.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1027 +nd-docs: DOCS-1027 --- {{< call-out "important" "Group names must match with your IdP" >}}To ensure that NGINX Instance Manager and your IdP work together seamlessly, group names must exactly match between the two systems. If the group names don’t match, the OIDC integration will fail, preventing users from accessing NGINX Instance Manager. For example, if you have a group called "app-developers" in your IdP, you must create a user group called "app-developers" in NGINX Instance Manager. The group claim must also be part of the token your IdP generates. Refer to your IdP's documentation for guidance on adding group claims.{{}} diff --git a/content/includes/nim/rbac/what-is-rbac.md b/content/includes/nim/rbac/what-is-rbac.md index c30034a9f..93fb5b72c 100644 --- a/content/includes/nim/rbac/what-is-rbac.md +++ b/content/includes/nim/rbac/what-is-rbac.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1179 +nd-docs: DOCS-1179 --- RBAC (Role-Based Access Control) is a security framework that provides access control based on roles assigned to users or user groups. This framework defines the roles and responsibilities of users within the system and restricts access to resources according to the user’s role. RBAC ensures only authorized users have access to specific resources and prevents unauthorized access. diff --git a/content/includes/nim/tech-specs/nim-app-protect-support.md b/content/includes/nim/tech-specs/nim-app-protect-support.md index cf6a03365..203e7c2ef 100644 --- a/content/includes/nim/tech-specs/nim-app-protect-support.md +++ b/content/includes/nim/tech-specs/nim-app-protect-support.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1068 +nd-docs: DOCS-1068 --- NGINX Instance Manager supports the following versions of [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/): @@ -8,7 +8,7 @@ NGINX Instance Manager supports the following versions of [NGINX App Protect WAF | NGINX Instance Manager | NGINX App Protect WAF | |------------------------|------------------------------------| -| 2.17.0–2.19.2 | Release 4.8.0–4.14.0, 5.1.0–5.6.0 | +| 2.17.0–2.20.0 | Release 4.8.0–4.15.0, 5.1.0–5.7.0 | | 2.15.1–2.16.0 | Release 4.8.0–4.10.0 | | 2.14.1–2.15.0 | Release 4.4.0–4.7.0 | | 2.13.0–2.14.0 | Release 4.3.0–4.5.0 | diff --git a/content/includes/nim/tech-specs/security-data-plane-dependencies.md b/content/includes/nim/tech-specs/security-data-plane-dependencies.md index 9b841627a..010ad835b 100644 --- a/content/includes/nim/tech-specs/security-data-plane-dependencies.md +++ b/content/includes/nim/tech-specs/security-data-plane-dependencies.md @@ -1,5 +1,10 @@ The Security Monitoring module requires the following versions of [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/) and [NGINX Plus](https://www.f5.com/products/nginx/nginx-plus) for the **data plane**: +{{< note >}} +In NGINX Instance Manager 2.18.0 and under, the Security Monitoring module was a separate package that was installed manually. +From NGINX Instance Manager 2.19.0 onward, Security Monitoring is part of the NGINX Instance Manager feature-set and is packaged by default; no manual installation or upgrade is needed. +{{< /note >}} + {{}} | Security Monitoring | NGINX App Protect WAF | diff --git a/content/includes/nim/tech-specs/security-management-plane-dependencies.md b/content/includes/nim/tech-specs/security-management-plane-dependencies.md index e135ae6dc..25eb8f0fc 100644 --- a/content/includes/nim/tech-specs/security-management-plane-dependencies.md +++ b/content/includes/nim/tech-specs/security-management-plane-dependencies.md @@ -1,6 +1,8 @@ The Security Monitoring module requires the following versions of NGINX Instance Manager to be installed on the **management plane**. -{{< note >}}The Security Monitoring module doesn’t automatically install or upgrade NGINX Instance Manager. You’ll need to manually install or upgrade NGINX Instance Manager to a supported version. +{{< note >}} +In NGINX Instance Manager 2.18.0 and under, the Security Monitoring module was a separate package that was installed manually. +From NGINX Instance Manager 2.19.0 onward, Security Monitoring is part of the NGINX Instance Manager feature-set and is packaged by default; no manual installation or upgrade is needed. {{< /note >}} {{}} diff --git a/content/includes/nim/tech-specs/supported-distros.md b/content/includes/nim/tech-specs/supported-distros.md index 35e62cdc2..7ede72fc3 100644 --- a/content/includes/nim/tech-specs/supported-distros.md +++ b/content/includes/nim/tech-specs/supported-distros.md @@ -1,5 +1,7 @@ --- -docs: DOCS-1071 +nd-docs: DOCS-1071 +files: +- content/nim/fundamentals/tech-specs.md --- The following table lists the Linux distributions supported by NGINX Instance Manager and NGINX App Protect: diff --git a/content/includes/nim/tech-specs/supported-nginx-versions.md b/content/includes/nim/tech-specs/supported-nginx-versions.md index cc6d9d4f9..9e13fa2ef 100644 --- a/content/includes/nim/tech-specs/supported-nginx-versions.md +++ b/content/includes/nim/tech-specs/supported-nginx-versions.md @@ -1,5 +1,7 @@ --- -docs: DOCS-1075 +nd-docs: DOCS-1075 +files: +- content/nim/fundamentals/tech-specs.md --- NGINX Instance Manager supports the following NGINX Open Source and NGINX Plus versions: @@ -8,7 +10,7 @@ NGINX Instance Manager supports the following NGINX Open Source and NGINX Plus v | NGINX Instance Manager | NGINX OSS | NGINX Plus | | ---------------------- | ----------- | ---------- | -| 2.18.0 and later | 1.18–1.25.1 | R31–R33 | +| 2.18.0 and later | 1.18–1.28.0 | R31–R34 | | 2.16.0–2.17.x | 1.18–1.25.1 | R31–R32 | | 2.7.0–2.15.x | 1.18–1.25.1 | R21–R30 | | 2.0.0–2.6.0 | 1.18–1.21.6 | R21–R27 | diff --git a/content/includes/nim/templates/additional-templating-resources.md b/content/includes/nim/templates/additional-templating-resources.md index cd21b7d82..9eae64a38 100644 --- a/content/includes/nim/templates/additional-templating-resources.md +++ b/content/includes/nim/templates/additional-templating-resources.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1500 +nd-docs: DOCS-1500 ---
    diff --git a/content/includes/nim/webui-nim-login.md b/content/includes/nim/webui-nim-login.md index 65b5bfd19..85bbf101d 100644 --- a/content/includes/nim/webui-nim-login.md +++ b/content/includes/nim/webui-nim-login.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1334 +nd-docs: DOCS-1334 --- In a web browser, go to the FQDN for your NGINX Instance Manager host and log in. Then, select **Instance Manager** from the Launchpad menu. diff --git a/content/includes/nms/services/platform-services.md b/content/includes/nms/services/platform-services.md index 33224eeea..4c9a58d6a 100644 --- a/content/includes/nms/services/platform-services.md +++ b/content/includes/nms/services/platform-services.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1186 +nd-docs: DOCS-1186 --- {{}} diff --git a/content/includes/security/jwt-password-note.md b/content/includes/security/jwt-password-note.md index d7c1640a3..69a32ad80 100644 --- a/content/includes/security/jwt-password-note.md +++ b/content/includes/security/jwt-password-note.md @@ -1,12 +1,12 @@ --- -docs: +nd-docs: --- {{}} To protect your system and data, follow these security practices: - + 1. **JWTs:** Treat JSON Web Tokens (JWTs) as sensitive data. Store them securely and delete them after use to prevent unauthorized access. - + 2. **Shell history:** Commands with JWTs or passwords are saved in plain text in your shell history. After running such commands, clear the history to protect credentials. For example: - Edit your shell history file (such as ~/.bash_history or ~/.zsh_history) to remove specific commands. - Use `history -c` to clear all shell history in bash or zsh. diff --git a/content/includes/security/rbac-intro.md b/content/includes/security/rbac-intro.md index 7122c1110..e45dce9c5 100644 --- a/content/includes/security/rbac-intro.md +++ b/content/includes/security/rbac-intro.md @@ -2,7 +2,7 @@ files: - content/nginx-one/rbac/overview.md - content/nim/admin-guide/rbac/overview-rbac.md -docs: DOCS-000 +nd-docs: DOCS-000 --- Role-based access control (RBAC) is a security system that governs access to resources within a software application. By assigning specific roles to users or groups, RBAC ensures that only authorized individuals have the ability to perform certain actions or access particular areas. diff --git a/content/includes/support/how-to-get-support.md b/content/includes/support/how-to-get-support.md index e03f3a791..570d29774 100644 --- a/content/includes/support/how-to-get-support.md +++ b/content/includes/support/how-to-get-support.md @@ -1,5 +1,5 @@ --- -docs: DOCS-1225 +nd-docs: DOCS-1225 --- If you need additional assistance, refer to the following topics for guidance on how to contact Support and create a Support Package: diff --git a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md index d9dd46dc0..50fbd5be7 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md @@ -4,30 +4,15 @@ files: - content/nim/monitoring/overview-metrics.md - content/nginx-one/getting-started.md --- - -To collect comprehensive metrics for NGINX Plus--including bytes streamed, information about upstream systems and caches, and counts of all HTTP status codes--add the following to your NGINX Plus configuration file (for example, `/etc/nginx/nginx.conf` or an included file): -```nginx -# Enable the /api/ location with appropriate access control -# to use the NGINX Plus API. -# -location /api/ { - api write=on; - allow 127.0.0.1; - deny all; -} -``` +To collect comprehensive metrics for NGINX Plus, including bytes streamed, information about upstream systems and caches, and counts of all HTTP status codes, add the following to your NGINX Plus configuration file, for example `/etc/nginx/nginx.conf` or an included file: -This configuration: +{{< include "config-snippets/enable-nplus-api-dashboard.md" >}} -- Enables the NGINX Plus API. -- Allows requests only from `127.0.0.1` (localhost). -- Blocks all other requests for security. +{{< call-out "note" "Security tip" >}} +- By default, all clients can call the API. +- To limit who can access the API, uncomment the `allow` and `deny` lines under `api write=on` and replace the example CIDR with your trusted network. +- To restrict write methods (`POST`, `PATCH`, `DELETE`), uncomment and configure the `limit_except GET` block and set up [HTTP basic authentication](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html). +{{}} -For more details, see the [NGINX Plus API module documentation](https://nginx.org/en/docs/http/ngx_http_api_module.html). - -After saving the changes, reload NGINX to apply the new configuration: - -```shell -nginx -s reload -``` +For more details, see the [NGINX Plus API module](https://nginx.org/en/docs/http/ngx_http_api_module.html) documentation and [Configuring the NGINX Plus API]({{< ref "/nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api" >}}). \ No newline at end of file diff --git a/content/mesh/_index.md b/content/mesh/_index.md index 5cda71545..e28e00d61 100644 --- a/content/mesh/_index.md +++ b/content/mesh/_index.md @@ -8,7 +8,7 @@ description: 'NGINX Service Mesh is a fully integrated lightweight service mesh url: /nginx-service-mesh/ cascade: noindex: true - banner: + nd-banner: enabled: true type: deprecation md: _banners/eos-mesh.md diff --git a/content/mesh/about/architecture.md b/content/mesh/about/architecture.md index c5db8f34f..1d0fb6fc1 100644 --- a/content/mesh/about/architecture.md +++ b/content/mesh/about/architecture.md @@ -3,7 +3,7 @@ title: Architecture weight: 200 description: Learn about F5 NGINX Service Mesh Architecture. toc: true -docs: DOCS-676 +nd-docs: DOCS-676 type: - concept - reference diff --git a/content/mesh/about/mesh-tech-specs.md b/content/mesh/about/mesh-tech-specs.md index 737a6b493..7bcc87d8a 100644 --- a/content/mesh/about/mesh-tech-specs.md +++ b/content/mesh/about/mesh-tech-specs.md @@ -3,7 +3,7 @@ title: Technical Specifications weight: 110 description: Cluster requirements and F5 NGINX Service Mesh footprint. toc: true -docs: DOCS-677 +nd-docs: DOCS-677 type: - reference --- diff --git a/content/mesh/about/what-is-nsm.md b/content/mesh/about/what-is-nsm.md index 1b212f4e0..1ae385795 100644 --- a/content/mesh/about/what-is-nsm.md +++ b/content/mesh/about/what-is-nsm.md @@ -3,7 +3,7 @@ title: What is NGINX Service Mesh? weight: 100 description: Learn about F5 NGINX Service Mesh fundamentals. toc: true -docs: DOCS-678 +nd-docs: DOCS-678 type: - concept --- diff --git a/content/mesh/get-started/install/configuration.md b/content/mesh/get-started/install/configuration.md index 4c801a585..7d8605389 100644 --- a/content/mesh/get-started/install/configuration.md +++ b/content/mesh/get-started/install/configuration.md @@ -3,7 +3,7 @@ title: Configuration Options weight: 100 description: Learn about F5 NGINX Service Mesh features and deployment options. toc: true -docs: DOCS-679 +nd-docs: DOCS-679 type: - concept --- diff --git a/content/mesh/get-started/install/install-with-helm.md b/content/mesh/get-started/install/install-with-helm.md index d3c8154bc..e11f34b93 100644 --- a/content/mesh/get-started/install/install-with-helm.md +++ b/content/mesh/get-started/install/install-with-helm.md @@ -4,7 +4,7 @@ draft: false toc: true description: This guide explains how to install F5 NGINX Service Mesh using Helm. weight: 300 -docs: DOCS-680 +nd-docs: DOCS-680 type: - how-to --- diff --git a/content/mesh/get-started/install/install.md b/content/mesh/get-started/install/install.md index 4d6a4a5d4..a58a337e7 100644 --- a/content/mesh/get-started/install/install.md +++ b/content/mesh/get-started/install/install.md @@ -3,7 +3,7 @@ title: Install with nginx-meshctl draft: false toc: true weight: 200 -docs: DOCS-681 +nd-docs: DOCS-681 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/gke.md b/content/mesh/get-started/platform-setup/gke.md index 5ee197288..fd6e977c9 100644 --- a/content/mesh/get-started/platform-setup/gke.md +++ b/content/mesh/get-started/platform-setup/gke.md @@ -3,7 +3,7 @@ title: Google Kubernetes Engine description: Learn how to set up Google Kubernetes Engine (GKE) for use with F5 NGINX Service Mesh. toc: true -docs: DOCS-683 +nd-docs: DOCS-683 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/kubeadm.md b/content/mesh/get-started/platform-setup/kubeadm.md index 971db529a..6f892b73c 100644 --- a/content/mesh/get-started/platform-setup/kubeadm.md +++ b/content/mesh/get-started/platform-setup/kubeadm.md @@ -2,7 +2,7 @@ title: Kubeadm description: Learn how to set up Kubeadm for use with F5 NGINX Service Mesh. toc: true -docs: DOCS-684 +nd-docs: DOCS-684 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/kubespray.md b/content/mesh/get-started/platform-setup/kubespray.md index ee99ce369..24f49fead 100644 --- a/content/mesh/get-started/platform-setup/kubespray.md +++ b/content/mesh/get-started/platform-setup/kubespray.md @@ -2,7 +2,7 @@ title: Kubespray description: Learn how to set up Kubespray for use with F5 NGINX Service Mesh. toc: true -docs: DOCS-685 +nd-docs: DOCS-685 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/openshift.md b/content/mesh/get-started/platform-setup/openshift.md index b2cc39ce9..ba5bfb5c6 100644 --- a/content/mesh/get-started/platform-setup/openshift.md +++ b/content/mesh/get-started/platform-setup/openshift.md @@ -3,7 +3,7 @@ title: OpenShift description: Learn what is different in OpenShift, and the considerations a user must make. toc: true -docs: DOCS-689 +nd-docs: DOCS-689 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/persistent-storage.md b/content/mesh/get-started/platform-setup/persistent-storage.md index 06051f8ca..aa6310f39 100644 --- a/content/mesh/get-started/platform-setup/persistent-storage.md +++ b/content/mesh/get-started/platform-setup/persistent-storage.md @@ -4,7 +4,7 @@ description: Learn how to set up persistent storage for use with F5 NGINX Servic Mesh. weight: 101 toc: true -docs: DOCS-686 +nd-docs: DOCS-686 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/rke.md b/content/mesh/get-started/platform-setup/rke.md index 2e4bd98e0..f67b55d94 100644 --- a/content/mesh/get-started/platform-setup/rke.md +++ b/content/mesh/get-started/platform-setup/rke.md @@ -3,7 +3,7 @@ title: Rancher Kubernetes Engine description: Learn how to set up Rancher Kubernetes Engine (RKE) for use with F5 NGINX Service Mesh. toc: true -docs: DOCS-687 +nd-docs: DOCS-687 type: - how-to --- diff --git a/content/mesh/get-started/platform-setup/supported-platforms.md b/content/mesh/get-started/platform-setup/supported-platforms.md index 67f5b13a6..d5966a1d2 100644 --- a/content/mesh/get-started/platform-setup/supported-platforms.md +++ b/content/mesh/get-started/platform-setup/supported-platforms.md @@ -4,7 +4,7 @@ description: Find out which platforms are supported for use with F5 NGINX Servic Mesh. weight: 100 toc: true -docs: DOCS-688 +nd-docs: DOCS-688 --- ## Kubernetes diff --git a/content/mesh/get-started/uninstall/uninstall-with-helm.md b/content/mesh/get-started/uninstall/uninstall-with-helm.md index b2b2af62d..5df1a2085 100644 --- a/content/mesh/get-started/uninstall/uninstall-with-helm.md +++ b/content/mesh/get-started/uninstall/uninstall-with-helm.md @@ -4,7 +4,7 @@ draft: false toc: true description: This topic explains how to uninstall F5 NGINX Service Mesh using Helm. weight: 300 -docs: DOCS-699 +nd-docs: DOCS-699 type: - how-to --- diff --git a/content/mesh/get-started/uninstall/uninstall.md b/content/mesh/get-started/uninstall/uninstall.md index 32ae4838e..59c7f8149 100644 --- a/content/mesh/get-started/uninstall/uninstall.md +++ b/content/mesh/get-started/uninstall/uninstall.md @@ -3,7 +3,7 @@ title: Uninstall with nginx-meshctl draft: false toc: true weight: 200 -docs: DOCS-1481 +nd-docs: DOCS-1481 type: - how-to --- diff --git a/content/mesh/get-started/upgrade/upgrade-with-helm.md b/content/mesh/get-started/upgrade/upgrade-with-helm.md index 5519d9446..ad8cf6c73 100644 --- a/content/mesh/get-started/upgrade/upgrade-with-helm.md +++ b/content/mesh/get-started/upgrade/upgrade-with-helm.md @@ -4,7 +4,7 @@ draft: false toc: true description: This guide explains how to upgrade F5 NGINX Service Mesh using Helm. weight: 300 -docs: DOCS-700 +nd-docs: DOCS-700 type: - how-to --- diff --git a/content/mesh/get-started/upgrade/upgrade.md b/content/mesh/get-started/upgrade/upgrade.md index 5d1ac3e68..744974dec 100644 --- a/content/mesh/get-started/upgrade/upgrade.md +++ b/content/mesh/get-started/upgrade/upgrade.md @@ -4,7 +4,7 @@ draft: false toc: true description: This guide explains how to upgrade F5 NGINX Service Mesh using nginx-meshctl. weight: 200 -docs: DOCS-1482 +nd-docs: DOCS-1482 type: - how-to --- diff --git a/content/mesh/guides/inject-sidecar-proxy.md b/content/mesh/guides/inject-sidecar-proxy.md index 9ddd2d3bf..99f1d6a77 100644 --- a/content/mesh/guides/inject-sidecar-proxy.md +++ b/content/mesh/guides/inject-sidecar-proxy.md @@ -4,7 +4,7 @@ toc: true description: Learn about the configuration options for F5 NGINX Service Mesh sidecar proxy injection. weight: 10 -docs: DOCS-692 +nd-docs: DOCS-692 type: - how-to --- diff --git a/content/mesh/guides/monitoring-and-tracing.md b/content/mesh/guides/monitoring-and-tracing.md index dec5da3c0..b2ce80d04 100644 --- a/content/mesh/guides/monitoring-and-tracing.md +++ b/content/mesh/guides/monitoring-and-tracing.md @@ -4,7 +4,7 @@ toc: true description: Learn about the monitoring and tracing features available in F5 NGINX Service Mesh. weight: 20 -docs: DOCS-693 +nd-docs: DOCS-693 type: - how-to --- diff --git a/content/mesh/guides/private-registry.md b/content/mesh/guides/private-registry.md index 8d97f4565..821f86b43 100644 --- a/content/mesh/guides/private-registry.md +++ b/content/mesh/guides/private-registry.md @@ -3,7 +3,7 @@ title: Private Registry description: How to set up access to a private registry weight: 70 toc: true -docs: DOCS-694 +nd-docs: DOCS-694 type: - how-to --- diff --git a/content/mesh/guides/production-tuning.md b/content/mesh/guides/production-tuning.md index 15be7ee28..4dc90023d 100644 --- a/content/mesh/guides/production-tuning.md +++ b/content/mesh/guides/production-tuning.md @@ -2,7 +2,7 @@ title: Production Tuning weight: 80 toc: true -docs: DOCS-695 +nd-docs: DOCS-695 type: - how-to --- diff --git a/content/mesh/guides/prometheus-metrics.md b/content/mesh/guides/prometheus-metrics.md index 84a829ddf..2574e480d 100644 --- a/content/mesh/guides/prometheus-metrics.md +++ b/content/mesh/guides/prometheus-metrics.md @@ -3,7 +3,7 @@ title: Prometheus Metrics description: How to set up and view prometheus metrics for valuable workload insights weight: 40 toc: true -docs: DOCS-840 +nd-docs: DOCS-840 type: - how-to --- diff --git a/content/mesh/guides/secure-traffic-mtls.md b/content/mesh/guides/secure-traffic-mtls.md index 2bd7b30c9..ba6ca46fd 100644 --- a/content/mesh/guides/secure-traffic-mtls.md +++ b/content/mesh/guides/secure-traffic-mtls.md @@ -3,7 +3,7 @@ title: Secure Mesh Traffic using mTLS toc: true description: Learn about the mTLS options available in F5 NGINX Service Mesh. weight: 30 -docs: DOCS-696 +nd-docs: DOCS-696 type: - how-to --- diff --git a/content/mesh/guides/smi-traffic-metrics.md b/content/mesh/guides/smi-traffic-metrics.md index 6421adbcb..9c07ed559 100644 --- a/content/mesh/guides/smi-traffic-metrics.md +++ b/content/mesh/guides/smi-traffic-metrics.md @@ -3,7 +3,7 @@ title: SMI Traffic Metrics description: How to set up and view SMI traffic metrics weight: 50 toc: true -docs: DOCS-697 +nd-docs: DOCS-697 type: - how-to --- diff --git a/content/mesh/guides/smi-traffic-policies.md b/content/mesh/guides/smi-traffic-policies.md index 16bf93a3f..8053f5d9b 100644 --- a/content/mesh/guides/smi-traffic-policies.md +++ b/content/mesh/guides/smi-traffic-policies.md @@ -4,7 +4,7 @@ toc: true description: Learn about the traffic policies supported by F5 NGINX Service Mesh and how to configure them. weight: 60 -docs: DOCS-698 +nd-docs: DOCS-698 type: - how-to --- diff --git a/content/mesh/guides/v1alpha1-ratelimit.md b/content/mesh/guides/v1alpha1-ratelimit.md index 38735b6a3..dfc4e0d62 100644 --- a/content/mesh/guides/v1alpha1-ratelimit.md +++ b/content/mesh/guides/v1alpha1-ratelimit.md @@ -1,6 +1,6 @@ --- title: v1alpha1 RateLimit Documentation -docs: DOCS-701 +nd-docs: DOCS-701 description: v1alpha1 RateLimit documentation. --- @@ -53,10 +53,10 @@ The rate limit spec contains the following fields: Each Pod in the destination accepts the total rate defined in a rate limit policy. If a policy has a rate of 100 r/m, and the destination consists of 3 Pods, each Pod accepts 100 r/m. - + If a single rate limit policy contains multiple sources, the rate divides evenly amongst them. For example, a policy defined with - + ```yaml destination: name: destService @@ -65,7 +65,7 @@ The rate limit spec contains the following fields: - name: source2 rate: 100 r/m ``` - + would result in `destService` accepting 50 requests per minute from `source1`, and 50 requests per minute from `source2`, for a total rate of 100 requests per minute. If two separate policies are defined for the same destination, then the rate is not divided amongst the sources. diff --git a/content/mesh/reference/api-usage.md b/content/mesh/reference/api-usage.md index c68955b8e..558a693e8 100644 --- a/content/mesh/reference/api-usage.md +++ b/content/mesh/reference/api-usage.md @@ -3,7 +3,7 @@ title: NGINX Service Mesh API description: Instructions for interacting with the F5 NGINX Service Mesh API. toc: true weight: 200 -docs: DOCS-702 +nd-docs: DOCS-702 type: - reference --- diff --git a/content/mesh/reference/nginx-meshctl.md b/content/mesh/reference/nginx-meshctl.md index cf6f21812..46a68e55d 100644 --- a/content/mesh/reference/nginx-meshctl.md +++ b/content/mesh/reference/nginx-meshctl.md @@ -4,7 +4,7 @@ description: Man page and instructions for using the F5 NGINX Service Mesh CLI draft: false weight: 300 toc: true -docs: DOCS-704 +nd-docs: DOCS-704 type: - reference --- diff --git a/content/mesh/reference/permissions.md b/content/mesh/reference/permissions.md index ee54c919b..b4e9af739 100644 --- a/content/mesh/reference/permissions.md +++ b/content/mesh/reference/permissions.md @@ -3,7 +3,7 @@ title: NGINX Service Mesh Permissions weight: 100 draft: false toc: true -docs: DOCS-883 +nd-docs: DOCS-883 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.5.0.md b/content/mesh/releases/release-notes-0.5.0.md index 4a1f859df..b1428bf96 100644 --- a/content/mesh/releases/release-notes-0.5.0.md +++ b/content/mesh/releases/release-notes-0.5.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -500 -docs: DOCS-705 +nd-docs: DOCS-705 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.6.0.md b/content/mesh/releases/release-notes-0.6.0.md index e5cdabf49..015ae0ef6 100644 --- a/content/mesh/releases/release-notes-0.6.0.md +++ b/content/mesh/releases/release-notes-0.6.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -600 -docs: DOCS-706 +nd-docs: DOCS-706 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.7.0.md b/content/mesh/releases/release-notes-0.7.0.md index 82314c63d..4f09ce78f 100644 --- a/content/mesh/releases/release-notes-0.7.0.md +++ b/content/mesh/releases/release-notes-0.7.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -700 -docs: DOCS-707 +nd-docs: DOCS-707 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.8.0.md b/content/mesh/releases/release-notes-0.8.0.md index a7e25c1eb..e42c5934c 100644 --- a/content/mesh/releases/release-notes-0.8.0.md +++ b/content/mesh/releases/release-notes-0.8.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -800 -docs: DOCS-708 +nd-docs: DOCS-708 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.9.0.md b/content/mesh/releases/release-notes-0.9.0.md index 15e672b6e..e288cf92f 100644 --- a/content/mesh/releases/release-notes-0.9.0.md +++ b/content/mesh/releases/release-notes-0.9.0.md @@ -7,7 +7,7 @@ description: Release information for F5 GINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -900 -docs: DOCS-709 +nd-docs: DOCS-709 type: - reference --- diff --git a/content/mesh/releases/release-notes-0.9.1.md b/content/mesh/releases/release-notes-0.9.1.md index 64f893130..c16f5f20e 100644 --- a/content/mesh/releases/release-notes-0.9.1.md +++ b/content/mesh/releases/release-notes-0.9.1.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -901 -docs: DOCS-710 +nd-docs: DOCS-710 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.0.0.md b/content/mesh/releases/release-notes-1.0.0.md index bb042d2dc..c6b7d211c 100644 --- a/content/mesh/releases/release-notes-1.0.0.md +++ b/content/mesh/releases/release-notes-1.0.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1000 -docs: DOCS-711 +nd-docs: DOCS-711 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.0.1.md b/content/mesh/releases/release-notes-1.0.1.md index 3a34c347a..4075f2ffe 100644 --- a/content/mesh/releases/release-notes-1.0.1.md +++ b/content/mesh/releases/release-notes-1.0.1.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1001 -docs: DOCS-712 +nd-docs: DOCS-712 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.1.0.md b/content/mesh/releases/release-notes-1.1.0.md index 5eb066f52..52a5075b9 100644 --- a/content/mesh/releases/release-notes-1.1.0.md +++ b/content/mesh/releases/release-notes-1.1.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1100 -docs: DOCS-713 +nd-docs: DOCS-713 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.2.0.md b/content/mesh/releases/release-notes-1.2.0.md index b1cfbb9b0..d94655a4f 100644 --- a/content/mesh/releases/release-notes-1.2.0.md +++ b/content/mesh/releases/release-notes-1.2.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1200 -docs: DOCS-714 +nd-docs: DOCS-714 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.2.1.md b/content/mesh/releases/release-notes-1.2.1.md index 1515a829d..8ebe77cb5 100644 --- a/content/mesh/releases/release-notes-1.2.1.md +++ b/content/mesh/releases/release-notes-1.2.1.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1201 -docs: DOCS-715 +nd-docs: DOCS-715 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.3.0.md b/content/mesh/releases/release-notes-1.3.0.md index 94fd659fd..e4af48714 100644 --- a/content/mesh/releases/release-notes-1.3.0.md +++ b/content/mesh/releases/release-notes-1.3.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1300 -docs: DOCS-716 +nd-docs: DOCS-716 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.3.1.md b/content/mesh/releases/release-notes-1.3.1.md index b44e30f8a..561253f38 100644 --- a/content/mesh/releases/release-notes-1.3.1.md +++ b/content/mesh/releases/release-notes-1.3.1.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1301 -docs: DOCS-717 +nd-docs: DOCS-717 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.4.0.md b/content/mesh/releases/release-notes-1.4.0.md index f34791b3c..bfca72bfe 100644 --- a/content/mesh/releases/release-notes-1.4.0.md +++ b/content/mesh/releases/release-notes-1.4.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1400 -docs: DOCS-1488 +nd-docs: DOCS-1488 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.4.1.md b/content/mesh/releases/release-notes-1.4.1.md index 89cbbaaae..dc220dea2 100644 --- a/content/mesh/releases/release-notes-1.4.1.md +++ b/content/mesh/releases/release-notes-1.4.1.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1401 -docs: DOCS-1484 +nd-docs: DOCS-1484 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.5.0.md b/content/mesh/releases/release-notes-1.5.0.md index a203ae1d2..a17a2b63f 100644 --- a/content/mesh/releases/release-notes-1.5.0.md +++ b/content/mesh/releases/release-notes-1.5.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1500 -docs: DOCS-1487 +nd-docs: DOCS-1487 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.6.0.md b/content/mesh/releases/release-notes-1.6.0.md index 78269f6ca..77e9d4c4d 100644 --- a/content/mesh/releases/release-notes-1.6.0.md +++ b/content/mesh/releases/release-notes-1.6.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1600 -docs: DOCS-1486 +nd-docs: DOCS-1486 type: - reference --- diff --git a/content/mesh/releases/release-notes-1.7.0.md b/content/mesh/releases/release-notes-1.7.0.md index 83dad0860..d28676239 100644 --- a/content/mesh/releases/release-notes-1.7.0.md +++ b/content/mesh/releases/release-notes-1.7.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1700 -docs: DOCS-1483 +nd-docs: DOCS-1483 type: - reference --- diff --git a/content/mesh/releases/release-notes-2.0.0.md b/content/mesh/releases/release-notes-2.0.0.md index d9273f36d..64a49211d 100644 --- a/content/mesh/releases/release-notes-2.0.0.md +++ b/content/mesh/releases/release-notes-2.0.0.md @@ -7,7 +7,7 @@ description: Release information for F5 NGINX Service Mesh, a configurable, low communication among application infrastructure services using application programming interfaces (APIs). Lists of new features and known issues are provided. weight: -1800 -docs: DOCS-1485 +nd-docs: DOCS-1485 type: - reference --- diff --git a/content/mesh/support/contact-support.md b/content/mesh/support/contact-support.md index 132facbc9..17e6e5772 100644 --- a/content/mesh/support/contact-support.md +++ b/content/mesh/support/contact-support.md @@ -4,7 +4,7 @@ weight: 100 description: Learn where to go for F5 NGINX Service Mesh support. toc: true draft: false -docs: DOCS-718 +nd-docs: DOCS-718 type: - task --- diff --git a/content/mesh/tutorials/accesscontrol-walkthrough.md b/content/mesh/tutorials/accesscontrol-walkthrough.md index 8672082c8..0ea9af63e 100644 --- a/content/mesh/tutorials/accesscontrol-walkthrough.md +++ b/content/mesh/tutorials/accesscontrol-walkthrough.md @@ -3,7 +3,7 @@ title: "Services using Access Control" description: "This article provides a guide for using access control between services." weight: 130 toc: true -docs: "DOCS-719" +nd-docs: "DOCS-719" --- ## Overview diff --git a/content/mesh/tutorials/deploy-example-app.md b/content/mesh/tutorials/deploy-example-app.md index 771bdd8c4..bbe048c50 100644 --- a/content/mesh/tutorials/deploy-example-app.md +++ b/content/mesh/tutorials/deploy-example-app.md @@ -5,7 +5,7 @@ toc: true description: This topic provides a walkthrough of deploying an App with F5 NGINX Service Mesh. weight: 100 -docs: DOCS-720 +nd-docs: DOCS-720 type: - tutorial --- diff --git a/content/mesh/tutorials/kic/deploy-with-kic.md b/content/mesh/tutorials/kic/deploy-with-kic.md index 1176823f1..2d79bb40b 100644 --- a/content/mesh/tutorials/kic/deploy-with-kic.md +++ b/content/mesh/tutorials/kic/deploy-with-kic.md @@ -5,7 +5,7 @@ description: This topic describes how to install and use F5 NGINX Ingress Contro weight: 200 draft: false toc: true -docs: DOCS-721 +nd-docs: DOCS-721 type: - tutorial --- diff --git a/content/mesh/tutorials/kic/egress-walkthrough.md b/content/mesh/tutorials/kic/egress-walkthrough.md index e245e7d91..fda82ee11 100644 --- a/content/mesh/tutorials/kic/egress-walkthrough.md +++ b/content/mesh/tutorials/kic/egress-walkthrough.md @@ -4,7 +4,7 @@ description: This topic provides a walkthrough of how to securely route egress t through F5 NGINX Ingress Controller for Kubernetes with NGINX Service Mesh. weight: 210 toc: true -docs: DOCS-722 +nd-docs: DOCS-722 type: - tutorial --- diff --git a/content/mesh/tutorials/kic/ingress-udp-walkthrough.md b/content/mesh/tutorials/kic/ingress-udp-walkthrough.md index 303bcc959..4470a9f91 100644 --- a/content/mesh/tutorials/kic/ingress-udp-walkthrough.md +++ b/content/mesh/tutorials/kic/ingress-udp-walkthrough.md @@ -4,7 +4,7 @@ description: This topic describes the steps to deploy F5 NGINX Ingress Controlle for Kubernetes, to expose a UDP application within NGINX Service Mesh. weight: 230 toc: true -docs: DOCS-841 +nd-docs: DOCS-841 type: - tutorial --- diff --git a/content/mesh/tutorials/kic/ingress-walkthrough.md b/content/mesh/tutorials/kic/ingress-walkthrough.md index 3360add08..578095f64 100644 --- a/content/mesh/tutorials/kic/ingress-walkthrough.md +++ b/content/mesh/tutorials/kic/ingress-walkthrough.md @@ -4,7 +4,7 @@ description: This topic provides a walkthrough of deploying F5 NGINX Ingress Con for Kubernetes to expose an application within NGINX Service Mesh. weight: 220 toc: true -docs: DOCS-723 +nd-docs: DOCS-723 type: - tutorial --- diff --git a/content/mesh/tutorials/observability.md b/content/mesh/tutorials/observability.md index 7bc39dfbd..e555409ed 100644 --- a/content/mesh/tutorials/observability.md +++ b/content/mesh/tutorials/observability.md @@ -5,7 +5,7 @@ toc: true description: This topic provides a walkthrough of deploying F5 NGINX Service Mesh with basic observability components. weight: 90 -docs: DOCS-886 +nd-docs: DOCS-886 type: - tutorial --- diff --git a/content/mesh/tutorials/ratelimit-walkthrough.md b/content/mesh/tutorials/ratelimit-walkthrough.md index 812903586..9d8488846 100644 --- a/content/mesh/tutorials/ratelimit-walkthrough.md +++ b/content/mesh/tutorials/ratelimit-walkthrough.md @@ -4,7 +4,7 @@ description: Learn how to configure rate limiting between workloads. draft: false toc: true weight: 140 -docs: DOCS-724 +nd-docs: DOCS-724 type: - tutorial --- diff --git a/content/mesh/tutorials/trafficsplit-deployments.md b/content/mesh/tutorials/trafficsplit-deployments.md index b578c79e3..1a2a5018e 100644 --- a/content/mesh/tutorials/trafficsplit-deployments.md +++ b/content/mesh/tutorials/trafficsplit-deployments.md @@ -4,7 +4,7 @@ description: This topic provides a guide for using traffic splits with different strategies. weight: 110 toc: true -docs: DOCS-725 +nd-docs: DOCS-725 type: - tutorial --- diff --git a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-installation-logging.md b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-installation-logging.md index 0c0e49a45..bf7cffa0d 100644 --- a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-installation-logging.md +++ b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-installation-logging.md @@ -1,5 +1,5 @@ --- -docs: DOCS-726 +nd-docs: DOCS-726 title: Installing the NGINX ModSecurity WAF toc: true weight: 100 diff --git a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-owasp-crs.md b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-owasp-crs.md index 9a688eb53..224acea09 100644 --- a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-owasp-crs.md +++ b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-owasp-crs.md @@ -1,5 +1,5 @@ --- -docs: DOCS-727 +nd-docs: DOCS-727 title: Using the OWASP CRS with the NGINX ModSecurity WAF toc: true weight: 200 diff --git a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-trustwave-spiderlabs-rules.md b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-trustwave-spiderlabs-rules.md index 3f29fa1de..2be3c5cef 100644 --- a/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-trustwave-spiderlabs-rules.md +++ b/content/modsec-waf/admin-guide/nginx-plus-modsecurity-waf-trustwave-spiderlabs-rules.md @@ -1,5 +1,5 @@ --- -docs: DOCS-728 +nd-docs: DOCS-728 title: Using the ModSecurity Rules from Trustwave SpiderLabs with the NGINX ModSecurity WAF toc: true diff --git a/content/modsec-waf/technical-specs.md b/content/modsec-waf/technical-specs.md index 6342fde0e..47266a3d6 100644 --- a/content/modsec-waf/technical-specs.md +++ b/content/modsec-waf/technical-specs.md @@ -1,5 +1,5 @@ --- -docs: DOCS-729 +nd-docs: DOCS-729 title: Technical Specifications toc: true weight: 300 diff --git a/content/nap-dos/deployment-guide/installing-nginx-plus-with-dos-and-waf-on-amazon-web-services.md b/content/nap-dos/deployment-guide/installing-nginx-plus-with-dos-and-waf-on-amazon-web-services.md index 694beb930..a3eae476c 100644 --- a/content/nap-dos/deployment-guide/installing-nginx-plus-with-dos-and-waf-on-amazon-web-services.md +++ b/content/nap-dos/deployment-guide/installing-nginx-plus-with-dos-and-waf-on-amazon-web-services.md @@ -3,7 +3,7 @@ description: Install F5 NGINX Plus, NGINX App Protect WAF + DoS on Amazon Web Se (AWS), to provide sophisticated Layer 7 load balancing, Modern app security solution, behavioral DoS detection and mitigation that works seamlessly in DevOps environments for your apps running on CentOS, RHEL, Debian and Ubuntu Linux OS. -docs: DOCS-1204 +nd-docs: DOCS-1204 title: NGINX App Protect WAF + DoS AMIs on Amazon EC2 toc: true weight: 110 diff --git a/content/nap-dos/deployment-guide/learn-about-deployment.md b/content/nap-dos/deployment-guide/learn-about-deployment.md index 430fd9e2e..8fe7c9059 100644 --- a/content/nap-dos/deployment-guide/learn-about-deployment.md +++ b/content/nap-dos/deployment-guide/learn-about-deployment.md @@ -1,6 +1,6 @@ --- description: Learn about F5 NGINX App Protect DoS Deployment. -docs: DOCS-666 +nd-docs: DOCS-666 title: NGINX App Protect DoS Deployment toc: true weight: 100 @@ -33,7 +33,7 @@ NGINX App Protect DoS supports the following operating systems: - [Ubuntu 22.04 (Jammy)](#debian--ubuntu-installation) - [Ubuntu 24.04 (Noble)](#debian--ubuntu-installation) - [Alpine 3.15](#alpine-315x--317x--319x-installation) - (Deprecated starting from NGINX Plus R30) -- [Alpine 3.17](#alpine-315x--317x--319x-installation) - (Deprecated starting from NGINX Plus R34) +- [Alpine 3.17](#alpine-315x--317x--319x-installation) - (Deprecated starting from NGINX Plus R34) - [Alpine 3.19](#alpine-315x--317x--319x-installation) - [AmazonLinux 2023](#amazonlinux-linux-2023-installation) @@ -402,7 +402,7 @@ When deploying App Protect DoS on NGINX Plus take the following precautions to s ``` 1. {{< include "nginx-plus/install/create-dir-for-crt-key.md" >}} - + 1. {{< include "nginx-plus/install/create-dir-for-jwt.md" >}} 1. {{< include "licensing-and-reporting/download-jwt-crt-from-myf5.md" >}} @@ -2621,7 +2621,7 @@ ${DIR}/appprotect-dos-arb/install_appprotect-dos-arb.sh ## App Protect DoS eBPF manager ### Overview -The eBPF Manager is a powerful and efficient tool designed to simplify and secure the deployment of eBPF (Extended Berkeley Packet Filter) programs for advanced networking use cases. +The eBPF Manager is a powerful and efficient tool designed to simplify and secure the deployment of eBPF (Extended Berkeley Packet Filter) programs for advanced networking use cases. Its primary responsibilities include program installation and managing client interactions to enable real-time packet processing and mitigation solutions. ### CLI Options for Flexible Configuration @@ -2632,4 +2632,4 @@ The eBPF Manager comes with configurable command-line flags for ease of use and * gRPC UDS Ownership: * -u, --user : Set the user ownership for the gRPC Unix Domain Socket (UDS). Defaults to nginx. * -g, --group : Set the group ownership for the gRPC Unix Domain Socket (UDS). Defaults to nginx. - + diff --git a/content/nap-dos/directives-and-policy/learn-about-directives-and-policy.md b/content/nap-dos/directives-and-policy/learn-about-directives-and-policy.md index 2d018750a..f1cca1a75 100644 --- a/content/nap-dos/directives-and-policy/learn-about-directives-and-policy.md +++ b/content/nap-dos/directives-and-policy/learn-about-directives-and-policy.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS Directives and Policy toc: true weight: 120 -docs: DOCS-667 +nd-docs: DOCS-667 --- ## Introduction diff --git a/content/nap-dos/monitoring/access-log.md b/content/nap-dos/monitoring/access-log.md index 61ef69359..296155491 100644 --- a/content/nap-dos/monitoring/access-log.md +++ b/content/nap-dos/monitoring/access-log.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Request Log Mechanism. -docs: DOCS-668 +nd-docs: DOCS-668 title: NGINX App Protect DoS Access Log Request Mechanism toc: true weight: 160 diff --git a/content/nap-dos/monitoring/live-activity-monitoring.md b/content/nap-dos/monitoring/live-activity-monitoring.md index bd9df7724..e28fb571b 100644 --- a/content/nap-dos/monitoring/live-activity-monitoring.md +++ b/content/nap-dos/monitoring/live-activity-monitoring.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Live Activity Monitoring. -docs: DOCS-1389 +nd-docs: DOCS-1389 title: NGINX App Protect DoS Live Activity Monitoring toc: true weight: 140 diff --git a/content/nap-dos/monitoring/operation-log.md b/content/nap-dos/monitoring/operation-log.md index 8439995da..2a12d5eaf 100644 --- a/content/nap-dos/monitoring/operation-log.md +++ b/content/nap-dos/monitoring/operation-log.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Operation Log. -docs: DOCS-669 +nd-docs: DOCS-669 title: NGINX App Protect DoS Operation Log toc: true weight: 180 diff --git a/content/nap-dos/monitoring/security-log.md b/content/nap-dos/monitoring/security-log.md index 6d2f3ce1a..642cde34e 100644 --- a/content/nap-dos/monitoring/security-log.md +++ b/content/nap-dos/monitoring/security-log.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Security Log. -docs: DOCS-670 +nd-docs: DOCS-670 title: NGINX App Protect DoS Security Log toc: true weight: 140 diff --git a/content/nap-dos/monitoring/types-of-logs.md b/content/nap-dos/monitoring/types-of-logs.md index ed0345d8b..0d6cc61ea 100644 --- a/content/nap-dos/monitoring/types-of-logs.md +++ b/content/nap-dos/monitoring/types-of-logs.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Logs Overview. -docs: DOCS-671 +nd-docs: DOCS-671 title: NGINX App Protect DoS Logs Overview toc: true weight: 130 diff --git a/content/nap-dos/releases/about-1.0.md b/content/nap-dos/releases/about-1.0.md index f4534665d..b3741d126 100644 --- a/content/nap-dos/releases/about-1.0.md +++ b/content/nap-dos/releases/about-1.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect 1.0 toc: true weight: 260 -docs: DOCS-672 +nd-docs: DOCS-672 --- Here you can find the release information for F5 NGINX App Protect DoS v1. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-1.1.0.md b/content/nap-dos/releases/about-1.1.0.md index 8fc5bff2a..f853f5843 100644 --- a/content/nap-dos/releases/about-1.1.0.md +++ b/content/nap-dos/releases/about-1.1.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS Arbitrator 1.1.0 toc: true weight: 220 -docs: DOCS-673 +nd-docs: DOCS-673 --- Here you can find the release information for F5 NGINX App Protect DoS Arbitrator v1.1.0. diff --git a/content/nap-dos/releases/about-1.1.1.md b/content/nap-dos/releases/about-1.1.1.md index c9f90779e..173b8e1cd 100644 --- a/content/nap-dos/releases/about-1.1.1.md +++ b/content/nap-dos/releases/about-1.1.1.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS Arbitrator 1.1.1 toc: true weight: 115 -docs: DOCS-1205 +nd-docs: DOCS-1205 --- Here you can find the release information for F5 NGINX App Protect DoS Arbitrator v1.1.1. diff --git a/content/nap-dos/releases/about-1.2.0.md b/content/nap-dos/releases/about-1.2.0.md index 8b147d81e..ed606e4e0 100644 --- a/content/nap-dos/releases/about-1.2.0.md +++ b/content/nap-dos/releases/about-1.2.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS Arbitrator 1.2.0 toc: true weight: 61 -docs: DOCS-000 +nd-docs: DOCS-1782 --- Here you can find the release information for F5 NGINX App Protect DoS Arbitrator v1.2.0 diff --git a/content/nap-dos/releases/about-2.0.md b/content/nap-dos/releases/about-2.0.md index 76d9385e5..7fb5b9005 100644 --- a/content/nap-dos/releases/about-2.0.md +++ b/content/nap-dos/releases/about-2.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 2.0 toc: true weight: 220 -docs: DOCS-674 +nd-docs: DOCS-674 --- Here you can find the release information for F5 NGINX App Protect DoS v2.0. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-2.1.md b/content/nap-dos/releases/about-2.1.md index 0590e9624..462ba2bbe 100644 --- a/content/nap-dos/releases/about-2.1.md +++ b/content/nap-dos/releases/about-2.1.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 2.1 toc: true weight: 200 -docs: DOCS-831 +nd-docs: DOCS-831 --- Here you can find the release information for F5 NGINX App Protect DoS v2.1. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-2.2.md b/content/nap-dos/releases/about-2.2.md index d18e23956..147cd6f51 100644 --- a/content/nap-dos/releases/about-2.2.md +++ b/content/nap-dos/releases/about-2.2.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 2.2 toc: true weight: 180 -docs: DOCS-839 +nd-docs: DOCS-839 --- Here you can find the release information for F5 NGINX App Protect DoS v2.2. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-2.3.md b/content/nap-dos/releases/about-2.3.md index 39e5ceb90..c98c7be28 100644 --- a/content/nap-dos/releases/about-2.3.md +++ b/content/nap-dos/releases/about-2.3.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 2.3 toc: true weight: 170 -docs: DOCS-856 +nd-docs: DOCS-856 --- Here you can find the release information for F5 NGINX App Protect DoS v2.3. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-2.4.md b/content/nap-dos/releases/about-2.4.md index a594409bd..bf8502638 100644 --- a/content/nap-dos/releases/about-2.4.md +++ b/content/nap-dos/releases/about-2.4.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 2.4 toc: true weight: 160 -docs: DOCS-890 +nd-docs: DOCS-890 --- Here you can find the release information for F5 NGINX App Protect DoS v2.4. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-3.0.md b/content/nap-dos/releases/about-3.0.md index c36756554..9310fa583 100644 --- a/content/nap-dos/releases/about-3.0.md +++ b/content/nap-dos/releases/about-3.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 3.0 toc: true weight: 150 -docs: DOCS-946 +nd-docs: DOCS-946 --- Here you can find the release information for F5 NGINX App Protect DoS v3.0. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-3.1.md b/content/nap-dos/releases/about-3.1.md index e3e7c6842..6c2311330 100644 --- a/content/nap-dos/releases/about-3.1.md +++ b/content/nap-dos/releases/about-3.1.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 3.1 toc: true weight: 140 -docs: DOCS-995 +nd-docs: DOCS-995 --- Here you can find the release information for F5 NGINX App Protect DoS v3.1. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.0.md b/content/nap-dos/releases/about-4.0.md index 0616d3350..5dab6acfd 100644 --- a/content/nap-dos/releases/about-4.0.md +++ b/content/nap-dos/releases/about-4.0.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 4.0 toc: true weight: 120 -docs: DOCS-1115 +nd-docs: DOCS-1115 --- Here you can find the release information for F5 NGINX App Protect DoS v4.0. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.1.md b/content/nap-dos/releases/about-4.1.md index b14bcbd77..442e20563 100644 --- a/content/nap-dos/releases/about-4.1.md +++ b/content/nap-dos/releases/about-4.1.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 4.1 toc: true weight: 110 -docs: DOCS-1203 +nd-docs: DOCS-1203 --- Here you can find the release information for F5 NGINX App Protect DoS v4.1. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.2.md b/content/nap-dos/releases/about-4.2.md index be4ee293b..03152db74 100644 --- a/content/nap-dos/releases/about-4.2.md +++ b/content/nap-dos/releases/about-4.2.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 4.2 toc: true weight: 100 -docs: DOCS-1254 +nd-docs: DOCS-1254 --- Here you can find the release information for F5 NGINX App Protect DoS v4.2. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.3.md b/content/nap-dos/releases/about-4.3.md index f571b0f47..5ae85ca28 100644 --- a/content/nap-dos/releases/about-4.3.md +++ b/content/nap-dos/releases/about-4.3.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 4.3 toc: true weight: 90 -docs: DOCS-1361 +nd-docs: DOCS-1361 --- Here you can find the release information for F5 NGINX App Protect DoS v4.3. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.4.md b/content/nap-dos/releases/about-4.4.md index d15c7b7b2..9bd7ac240 100644 --- a/content/nap-dos/releases/about-4.4.md +++ b/content/nap-dos/releases/about-4.4.md @@ -2,7 +2,7 @@ title: NGINX App Protect DoS 4.4 toc: true weight: 80 -docs: DOCS-1361 +nd-docs: DOCS-1785 --- Here you can find the release information for F5 NGINX App Protect DoS v4.4. NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. diff --git a/content/nap-dos/releases/about-4.5.md b/content/nap-dos/releases/about-4.5.md index ac889021e..969d4e6b1 100644 --- a/content/nap-dos/releases/about-4.5.md +++ b/content/nap-dos/releases/about-4.5.md @@ -2,10 +2,10 @@ title: NGINX App Protect DoS 4.5 toc: true weight: 70 -docs: DOCS-000 +nd-docs: DOCS-1784 --- -Here you can find the release information for F5 NGINX App Protect DoS v4.5 +Here you can find the release information for F5 NGINX App Protect DoS v4.5 NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. @@ -24,8 +24,8 @@ NGINX App Protect DoS 4.5 adds support for NGINX Plus R33. - Support for NGINX Plus R33 - Add support for Alpine 3.19 - Add support for Ubuntu 24.04 -- Remove support for CentOS 7 / RHEL 7 -- *eBPF Manager - Privileged Process for Secure Command Handling* +- Remove support for CentOS 7 / RHEL 7 +- *eBPF Manager - Privileged Process for Secure Command Handling* This feature introduces the eBPF Manager, a process that securely handles eBPF commands on behalf of other processes. By allowing certain processes to operate without elevated privileges, it enhances system security. As part of this enhancement, NGINX now runs under a non-root user account, which is required for deploying specific security solutions. --- diff --git a/content/nap-dos/releases/about-4.6.md b/content/nap-dos/releases/about-4.6.md index c03e1e42a..b45af1e0d 100644 --- a/content/nap-dos/releases/about-4.6.md +++ b/content/nap-dos/releases/about-4.6.md @@ -2,10 +2,10 @@ title: NGINX App Protect DoS 4.6 toc: true weight: 60 -docs: DOCS-000 +nd-docs: DOCS-1783 --- -Here you can find the release information for F5 NGINX App Protect DoS v4.6 +Here you can find the release information for F5 NGINX App Protect DoS v4.6 NGINX App Protect DoS provides behavioral protection against Denial of Service (DoS) for your web applications. @@ -21,7 +21,7 @@ April 1, 2025 - Support for NGINX Plus R34 - Add support for AmazonLinux 2023 -- Remove support for Alpine 3.17 +- Remove support for Alpine 3.17 - Bug fixes --- @@ -31,7 +31,7 @@ April 1, 2025 | Distribution name | Package file | |--------------------------|------------------------------------------------------| | Alpine 3.19 | _app-protect-dos-34+4.6.1-r1.apk_ | -| Amazon Linux 2023 | _app-protect-dos-34+4.6.1-1.amzn2023.ngx.x86_64.rpm_ | +| Amazon Linux 2023 | _app-protect-dos-34+4.6.1-1.amzn2023.ngx.x86_64.rpm_ | | RHEL 8 and Rocky Linux 8 | _app-protect-dos-34+4.6.1-1.el8.ngx.x86_64.rpm_ | | RHEL 9 | _app-protect-dos-34+4.6.1-1.el9.ngx.x86_64.rpm_ | | Debian 11 | _app-protect-dos_34+4.6.1-1\~bullseye_amd64.deb_ | diff --git a/content/nap-dos/troubleshooting-guide/how-to-troubleshoot.md b/content/nap-dos/troubleshooting-guide/how-to-troubleshoot.md index ed5b89c44..7ac06a6a7 100644 --- a/content/nap-dos/troubleshooting-guide/how-to-troubleshoot.md +++ b/content/nap-dos/troubleshooting-guide/how-to-troubleshoot.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect DoS Troubleshooting Guide. -docs: DOCS-675 +nd-docs: DOCS-675 title: NGINX App Protect DoS Troubleshooting Guide toc: true weight: 200 diff --git a/content/nap-waf/v4/admin-guide/install-nms.md b/content/nap-waf/v4/admin-guide/install-nms.md index ce95fd9e0..63b341b37 100644 --- a/content/nap-waf/v4/admin-guide/install-nms.md +++ b/content/nap-waf/v4/admin-guide/install-nms.md @@ -1,7 +1,7 @@ --- description: Learn how to get more from F5 NGINX App Protect WAF with the NGINX Management Suite Security Monitoring and Instance Manager modules. -docs: DOCS-1126 +nd-docs: DOCS-1126 title: Using NGINX App Protect WAF with NGINX Management Suite toc: true weight: 100 diff --git a/content/nap-waf/v4/admin-guide/install.md b/content/nap-waf/v4/admin-guide/install.md index c3e0575dc..67cfa0518 100644 --- a/content/nap-waf/v4/admin-guide/install.md +++ b/content/nap-waf/v4/admin-guide/install.md @@ -4,7 +4,7 @@ weight: 100 toc: true type: how-to product: NAP-WAF -docs: DOCS-646 +nd-docs: DOCS-646 --- @@ -17,7 +17,7 @@ This guide explains how to deploy NGINX App Protect WAF as well as upgrade App P ### Using NGINX App Protect with NGINX Instance Manager NGINX Instance Manager provides centralized configuration management and visibility for your NGINX App Protect WAF fleet. -After completing the NGINX App Protect WAF installation, refer to the [NGINX Instance Manager Installation Guide](https://docs.nginx.com/nginx-instance-manager/deploy/) for the deployment instructions. +After completing the NGINX App Protect WAF installation, refer to the [NGINX Instance Manager Installation Guide](https://docs.nginx.com/nginx-instance-manager/deploy/) for the deployment instructions. ## Prerequisites @@ -32,8 +32,8 @@ NGINX App Protect WAF supports the following operating systems: - [Debian 11 (Bullseye) & 12 (Bookworm)](#debian-10--debian-11--debian-12-installation) - [Oracle Linux 8.1.x and above](#oracle-linux-81-installation) - [RHEL 8.1.x and above](#rhel-81-installation) -- [RHEL 9 and above](#rhel-9-installation) -- [Ubuntu 20.04 (Focal), 22.04 (Jammy) & 24.04 (Noble)](#ubuntu-installation) +- [RHEL 9, Rocky Linux 9 and above](#rhel-9-installation) +- [Ubuntu 22.04 (Jammy) & 24.04 (Noble)](#ubuntu-installation) The NGINX App Protect WAF package has the following dependencies: @@ -51,6 +51,8 @@ The NGINX App Protect WAF package has the following dependencies: See the NGINX Plus full list of prerequisites for more details. NGINX App Protect WAF can be installed as a module to an existing NGINX Plus installation or as a complete NGINX Plus with App Protect installation in a clean environment. +Please note that an additional package **app-protect-ip-intelligence** is required if the customer intends to use the IP Intelligence feature. This package does not come as a dependency of App Protect and needs to be installed and maintained separately. This package installs the client that downloads and updates the database required for enforcing IP Intelligence. + ## Storage I/O Performance When deploying App Protect on NGINX Plus take into consideration the performance of storage on which it is going to be installed. @@ -214,6 +216,30 @@ If a user other than **nginx** is to be used, note the following: sudo service nginx start ``` +14. (Optional) A new feature, `IP Intelligence` is available (version 4.15.0 and above). The feature requires the installation of an additional package to function properly: + + ```shell + sudo apk add app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + + + --- ## Amazon Linux Installation @@ -328,6 +354,28 @@ If a user other than **nginx** is to be used, note the following: sudo systemctl start nginx ``` +1. (Optional) A new feature feature `IP Intelligence` is available (version 4.15.0 and above). The feature requires the installation of an additional package to function properly: + + ```shell + sudo dnf install -y app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + ## Debian Installation 1. If you already have NGINX packages in your system, back up your configs and logs: @@ -467,6 +515,28 @@ If a user other than **nginx** is to be used, note the following: sudo systemctl start nginx ``` +16. (Optional) A new feature feature `IP Intelligence` is available (version 4.15.0 and above). The feature requires the installation of an additional package to function properly: + + ```shell + sudo apt-get -y install app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + {{< warning >}} Debian enables **AppArmor** by default, but NGINX App Protect WAF will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for NGINX App Protect WAF, you will have to write your own AppArmor profile for NGINX App Protect WAF executables found in `/opt/app_protect/bin` such that it best suits your environment. {{< /warning >}} @@ -588,7 +658,29 @@ If a user other than **nginx** is to be used, note the following: sudo systemctl start nginx ``` ---- +17. (Optional) A new feature feature `IP Intelligence` is available (version 4.15.0 and above). The feature requires the installation of an additional package to function properly: + + ```shell + sudo dnf install -y app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + + --- ## RHEL 9+ Installation @@ -708,7 +800,29 @@ If a user other than **nginx** is to be used, note the following: sudo systemctl start nginx ``` ---- +1. (Optional) A new feature `IP Intelligence` is available (version 4.15.0 and above). The feature requires the installation of an additional package to function properly: + + ```shell + sudo dnf install -y app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + + --- ## Ubuntu Installation @@ -843,6 +957,28 @@ If a user other than **nginx** is to be used, note the following: sudo systemctl start nginx ``` +16. (Optional), a new feature `IP Intelligence` is supported (Check the release notes for the App Protect versions that support IP Intelligence). The feature requires the installation of an additional package to function properly: + + ```shell + sudo apt-get -y install app-protect-ip-intelligence + ``` + + After installing the package, run the client: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + + Verify the client is populating the database: + + ```shell + tail -f iprepd.log + ``` + + Update your policy to include the new configuration, then run [apreload]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#apreload" >}}) command to make changes take effect + + {{< note >}} For this capability to function properly, please follow the guidelines listed in the [configuration guide]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}){{< /note >}} + {{< note >}} Ubuntu 20.04 / Ubuntu 22.04 / Ubuntu 24.04 activates **AppArmor** by default, but NGINX App Protect WAF will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for NGINX App Protect WAF, you will have to write your own AppArmor profile for NGINX App Protect WAF executables found in `/opt/app_protect/bin` such that it best suits your environment. {{< /note >}} @@ -934,6 +1070,12 @@ If a user other than **nginx** is to be used, note the following: /usr/sbin/nginx -g 'daemon off;' ``` + If you want to use IP intelligence feature (Available from versions 4.15.0 and above), add this additional line to your `entrypoint.sh` file: + + ```shell + /opt/app_protect/bin/iprepd /etc/app_protect/tools/iprepd.cfg > ipi.log 2>&1 & + ``` + 7. Create a Docker image: - For Oracle Linux/Debian/Ubuntu/Alpine/Amazon Linux: @@ -996,6 +1138,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \ --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \ apk update && apk add app-protect +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \ + apk update && apk add app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1033,6 +1180,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && dnf clean all \ && rm -rf /var/cache/yum +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf -y install app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1085,6 +1237,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ apt-get update && apt-get install -y app-protect +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + apt-get install -y app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1125,6 +1282,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && dnf clean all \ && rm -rf /var/cache/dnf +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install -y app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1163,6 +1325,53 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && dnf clean all \ && rm -rf /var/cache/dnf +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install -y app-protect-ip-intelligence + +# Forward request logs to Docker log collector: +RUN ln -sf /dev/stdout /var/log/nginx/access.log \ + && ln -sf /dev/stderr /var/log/nginx/error.log + +# Copy configuration files: +COPY nginx.conf custom_log_format.json /etc/nginx/ +COPY entrypoint.sh /root/ + +CMD ["sh", "/root/entrypoint.sh"] +``` + +### Rocky Linux 9 Dockerfile example + +```dockerfile +# syntax=docker/dockerfile:1 +# For Rocky Linux 9: +FROM rockylinux:9 + +# Install prerequisite packages: +RUN dnf -y install wget ca-certificates 'dnf-command(config-manager)' + +# Add NGINX Plus repo to Yum: +RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/plus-9.repo + +# Add NGINX App-protect & dependencies repo to Yum: +RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-9.repo +RUN dnf config-manager --set-enabled crb \ + && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \ + && dnf clean all + +# Install NGINX App Protect WAF: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install --enablerepo=codeready-builder-for-rhel-9-x86_64-rpms -y app-protect \ + && dnf clean all \ + && rm -rf /var/cache/dnf + +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install -y app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1204,6 +1413,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && dnf clean all \ && rm -rf /var/cache/dnf +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install -y app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1256,6 +1470,11 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ apt-get update && DEBIAN_FRONTEND="noninteractive" apt-get install -y app-protect +# Only use if you want to install and use the IP intelligence feature: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + apt-get install -y app-protect-ip-intelligence + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1465,6 +1684,30 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && rm -rf /var/cache/dnf ``` +### Rocky Linux 9 Converter Docker Deployment Example + +```dockerfile +# syntax=docker/dockerfile:1 +# For Rocky Linux 9: +FROM rockylinux:9 + +# Install prerequisite packages: +RUN dnf -y install wget ca-certificates 'dnf-command(config-manager)' + +# Add NGINX App-protect & dependencies repo to Yum: +RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-9.repo +RUN dnf config-manager --set-enabled crb \ + && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \ + && dnf clean all + +# Install NGINX App Protect WAF: +RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \ + --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ + dnf install -y app-protect-compiler \ + && dnf clean all \ + && rm -rf /var/cache/dnf +``` + ### Oracle Linux 8 Converter Docker Deployment Example ```dockerfile @@ -1628,6 +1871,12 @@ On a host with access to the NGINX App Protect WAF repository: yum install --downloadonly --downloaddir=/etc/packages/ app-protect ``` + Only use if you want to install and use the IP intelligence feature: + + ```shell + yum install --downloadonly --downloaddir=/etc/packages/ app-protect-ip-intelligence + ``` + 3. Download the `epel-release` dependency package: For RHEL 8.1+ / Oracle Linux 8.1+: @@ -1656,6 +1905,12 @@ On an offline host: yum -y install app-protect ``` + Only use if you want to install and use the IP intelligence feature: + + ```shell + yum -y install app-protect-ip-intelligence + ``` + ### Example Deployment for Debian/Ubuntu #### Add the NGINX App Protect WAF Packages to an Internal Repository @@ -1671,6 +1926,13 @@ On a host with access to the NGINX App Protect WAF repository: for i in $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances app-protect | grep "^\w" | sort -u); do apt-get download $i 2>>errors.txt; done ``` + Only use if you want to install and use the IP intelligence feature: + + ```shell + cd /etc/packages/ + apt-get download app-protect-ip-intelligence + ``` + 2. Add the packages in `/etc/packages` to your local repository. @@ -1685,6 +1947,11 @@ On an offline host: apt-get update apt-get install -y app-protect ``` + Only use if you want to install and use the IP intelligence feature: + + ```shell + apt-get install -y app-protect-ip-intelligence + ``` ## Post-Installation Checks @@ -2434,12 +2701,28 @@ You can uninstall the App Protect in below Operating Systems by using the follow ### RHEL 8.1+ / Oracle Linux 8.1+ / RHEL 9+ +If you have previously installed `app-protect-ip-intelligence` package, please make sure to uninstall it first: + +```shell +sudo dnf remove app-protect-ip-intelligence +``` + +Then proceed with uninstalling App Protect packages: + ```shell sudo dnf remove app-protect app-protect-selinux ``` ### Debian 11 / Debian 12 / Ubuntu 20.04 / Ubuntu 22.04 / Ubuntu 24.04 +If you have previously installed `app-protect-ip-intelligence` package, please make sure to uninstall it first: + +```shell +sudo apt-get remove app-protect-ip-intelligence +``` + +Then proceed with uninstalling App Protect packages: + ```shell sudo apt-get remove app-protect \ app-protect-plugin \ @@ -2455,6 +2738,14 @@ app-protect-bot-signatures ### Alpine 3.16 / Alpine 3.17 / Alpine 3.19 +If you have previously installed `app-protect-ip-intelligence` package, please make sure to uninstall it first: + +```shell +sudo apk del app-protect-ip-intelligence +``` + +Then proceed with uninstalling App Protect packages: + ```shell sudo apk del app-protect \ app-protect-plugin \ @@ -2524,7 +2815,7 @@ app-protect=27+3.1088.2-1~[OS_CODENAME] ## Upgrading App Protect to the latest version -### RHEL 8.1+ / RHEL 9+ / Oracle Linux 8.1+ +### RHEL 8.1+ / RHEL 9+ / Oracle Linux 8.1+ Upgrade the NGINX App Protect WAF to the latest 4.x version: diff --git a/content/nap-waf/v4/admin-guide/upgrade-nap-waf.md b/content/nap-waf/v4/admin-guide/upgrade-nap-waf.md index c29b4b765..43e115650 100644 --- a/content/nap-waf/v4/admin-guide/upgrade-nap-waf.md +++ b/content/nap-waf/v4/admin-guide/upgrade-nap-waf.md @@ -3,7 +3,7 @@ title: Upgrade NGINX App Protect WAF on Managed Instances description: How to Upgrade F5 NGINX App Protect WAF on managed NGINX instances weight: 300 toc: true -docs: DOCS-1198 +nd-docs: DOCS-1198 --- ## Overview diff --git a/content/nap-waf/v4/configuration-guide/configuration.md b/content/nap-waf/v4/configuration-guide/configuration.md index 025870d05..a98931787 100644 --- a/content/nap-waf/v4/configuration-guide/configuration.md +++ b/content/nap-waf/v4/configuration-guide/configuration.md @@ -1,6 +1,6 @@ --- description: F5 NGINX App Protect WAF security features. -docs: DOCS-647 +nd-docs: DOCS-647 title: NGINX App Protect WAF Configuration Guide toc: true weight: 200 @@ -38,7 +38,9 @@ When configuring NGINX App Protect WAF, `app_protect_enable` should always be en |[Deny and Allow IP lists](#deny-and-allow-ip-lists) | Manually define denied & allowed IP addresses as well as IP addresses to never log. | |[XFF headers & trust](#xff-headers-and-trust) | Disabled by default. User can enable it and optionally add a list of custom XFF headers. | |[gRPC Protection](#grpc-protection-for-unary-traffic) | gRPC content profile detects malformed content, parses well-formed content, and extracts the text fields for detecting attack signatures and disallowed meta-characters. In addition, it enforces size restrictions and prohibition of unknown fields. The Interface Definition Language (IDL) files for the gRPC API must be attached to the profile. gRPC protection can be on [unary](#grpc-protection-for-unary-traffic) or [bidirectional](#grpc-protection-for-bidirectional-streaming) traffic.| -|[Brute Force Attack Preventions](#brute-force-attack-preventions) | Configure brute-force-attack-preventions parameters to secured areas of a web application from brute force attacks.|} +|[Brute Force Attack Preventions](#brute-force-attack-preventions) | Configure brute-force-attack-preventions parameters to secured areas of a web application from brute force attacks.| +|[IP Address Lists](#ip-address-lists) | Configure IP Address Lists feature to organize lists of allowed and forbidden IP addresses across several lists with common attributes.| +|[IP Intelligence](#ip-intelligence-configuration) | Configure the IP Intelligence feature to customize enforcement based on the source IP of the request, limiting access from IP addresses with questionable reputation.| ### Disallowed File Types {{< include "nap-waf/config/common/disallowed-file-types.md" >}} @@ -240,6 +242,14 @@ http { {{< include "nap-waf/config/common/enforcer-cookie-settings.md" >}} +### IP Intelligence Configuration + +{{< include "nap-waf/config/common/ip-intelligence-conf.md" >}} + +### IP Intelligence Forward Proxy Configuration + +{{< include "nap-waf/config/common/forward-proxy-conf.md" >}} + ### Additional Configuration Options @@ -478,6 +488,15 @@ For the full reference of Override Rules condition syntax and usage see the NGIN {{< include "nap-waf/config/common/geolocation-override-rules.md" >}} +## IP Address Lists + +### Overview + +{{< include "nap-waf/config/common/ip-groups-overview.md" >}} + +### IP Address Lists in Policy Override Rules Conditions + +{{< include "nap-waf/config/common/ip-groups-override-rules.md" >}} ## JSON Web Token Protection @@ -660,12 +679,23 @@ systematic, username/password combinations to discover legitimate authentication To prevent brute force attacks, NGINX App Protect WAF monitors IP addresses, usernames, and the number of failed login attempts beyond a maximum threshold. When brute force patterns are detected, the NGINX App Protect WAF policy either trigger an alarm or block the attack if the failed login attempts reached a maximum threshold for a specific username or coming from a specific IP address. -To enable brute force protection, at least one login page must be created. -The login page entity is created separately and is not included in the brute force configuration block. +In order to create a brute force configuration for a specific URL in NGINX App Protect you must first create a User-Defined URL, then a Login Page and finally define the URL element in the Brute Force configuration section. --- +### The User-Defined URL example -### Login page policy example +```json +"urls": [ + { + "method": "*", + "name": "/html_login", + "protocol": "http", + "type": "explicit" + } + ], +``` + +### Login pages example A login page specifies the login URL that users must pass through to get authenticated. The configuration of a login URL includes the URL itself, the username and passwords parameters and the validation criteria (how we know that a login was successful or failed) ```json @@ -690,18 +720,10 @@ A login page specifies the login URL that users must pass through to get authent {{< note >}} For further configuration details, see NGINX App Protect WAF Declarative Policy Guide [Declarative Policy guide]({{< ref "/nap-waf/v4/declarative-policy/policy/#policy/login-pages" >}}). {{< /note >}} --- -### Brute force policy example +### Brute force prevention example Example1: A single brute force configuration is applied universally to all login pages. ```json -{ - "policy": { - "name": "BruteForcePolicy", - "template": { - "name": "POLICY_TEMPLATE_NGINX_BASE" - }, - "applicationLanguage": "utf-8", - "enforcementMode": "blocking", "brute-force-attack-preventions" : [ { "bruteForceProtectionForAllLoginPages" : true, @@ -719,21 +741,11 @@ Example1: A single brute force configuration is applied universally to all login "sourceBasedProtectionDetectionPeriod" : 3600 } ] - } -} ``` Example2: Different brute force configurations can be defined for individual login pages, with each configuration referencing a specific login page. ```json -{ - "policy": { - "name": "BruteForcePolicySpec", - "template": { - "name": "POLICY_TEMPLATE_NGINX_BASE" - }, - "applicationLanguage": "utf-8", - "enforcementMode": "blocking", "brute-force-attack-preventions" : [ { "bruteForceProtectionForAllLoginPages" : false, @@ -753,13 +765,72 @@ Example2: Different brute force configurations can be defined for individual log "method": "*", "name": "/html_login", "protocol": "http" - } + } } ], +``` - } +The following example adds all three of the pieces for a complete example policy. + +```json +{ + "policy": { + "name": "BruteForcePolicy", + "template": { + "name": "POLICY_TEMPLATE_NGINX_BASE" + }, + "applicationLanguage": "utf-8", + "enforcementMode": "blocking", + "urls": [ + { + "method": "*", + "name": "/html_login", + "protocol": "http", + "type": "explicit" + } + ], + "login-pages": [ + { + "accessValidation": { + "responseContains": "Success" + }, + "authenticationType": "form", + "url": { + "method": "*", + "name": "/html_login", + "protocol": "http", + "type": "explicit" + }, + "usernameParameterName": "username", + "passwordParameterName": "password" + } + ], + "brute-force-attack-preventions": [ + { + "bruteForceProtectionForAllLoginPages": false, + "loginAttemptsFromTheSameIp": { + "action": "alarm", + "enabled": true, + "threshold": 20 + }, + "loginAttemptsFromTheSameUser": { + "action": "alarm", + "enabled": true, + "threshold": 3 + }, + "reEnableLoginAfter": 3600, + "sourceBasedProtectionDetectionPeriod": 3600, + "url": { + "method": "*", + "name": "/html_login", + "protocol": "http" + } + } + ] + } } ``` + {{< note >}} For further configuration details, see NGINX App Protect WAF Declarative Policy Guide [Declarative Policy guide]({{< ref "/nap-waf/v4/declarative-policy/policy/#policy/brute-force-attack-preventions" >}}). {{< /note >}} ## Custom Dimensions Log Entries diff --git a/content/nap-waf/v4/declarative-policy/policy.md b/content/nap-waf/v4/declarative-policy/policy.md index b5c71b808..10d28c6f1 100644 --- a/content/nap-waf/v4/declarative-policy/policy.md +++ b/content/nap-waf/v4/declarative-policy/policy.md @@ -2,7 +2,7 @@ title: NGINX App Protect WAF Declarative Policy toc: true weight: 300 -docs: DOCS-648 +nd-docs: DOCS-648 --- {{< include "nap-waf/policy.html" >}} diff --git a/content/nap-waf/v4/logging-overview/access-log.md b/content/nap-waf/v4/logging-overview/access-log.md index eaff647a6..bc9125538 100644 --- a/content/nap-waf/v4/logging-overview/access-log.md +++ b/content/nap-waf/v4/logging-overview/access-log.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect WAF Access Log Request Mechanism. -docs: DOCS-910 +nd-docs: DOCS-910 title: NGINX App Protect WAF Access Log toc: true weight: 550 diff --git a/content/nap-waf/v4/logging-overview/debug-logs.md b/content/nap-waf/v4/logging-overview/debug-logs.md index 154d95b5f..ef14ba848 100644 --- a/content/nap-waf/v4/logging-overview/debug-logs.md +++ b/content/nap-waf/v4/logging-overview/debug-logs.md @@ -1,6 +1,6 @@ --- description: Learn about the NGINX App Protect WAF Debug Log. -docs: DOCS-913 +nd-docs: DOCS-913 title: NGINX App Protect WAF Debug Log toc: true weight: 540 diff --git a/content/nap-waf/v4/logging-overview/logs-overview.md b/content/nap-waf/v4/logging-overview/logs-overview.md index 9e6ebdc5c..1ad2fd13d 100644 --- a/content/nap-waf/v4/logging-overview/logs-overview.md +++ b/content/nap-waf/v4/logging-overview/logs-overview.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect WAF Logs Overview. -docs: DOCS-911 +nd-docs: DOCS-911 title: NGINX App Protect WAF Logs Overview toc: true weight: 510 diff --git a/content/nap-waf/v4/logging-overview/operation-logs.md b/content/nap-waf/v4/logging-overview/operation-logs.md index bc51c423e..e84052974 100644 --- a/content/nap-waf/v4/logging-overview/operation-logs.md +++ b/content/nap-waf/v4/logging-overview/operation-logs.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect WAF Operation Log. -docs: DOCS-912 +nd-docs: DOCS-912 title: NGINX App Protect WAF Operation Log toc: true weight: 530 diff --git a/content/nap-waf/v4/logging-overview/security-log.md b/content/nap-waf/v4/logging-overview/security-log.md index d0211d06a..870950b77 100644 --- a/content/nap-waf/v4/logging-overview/security-log.md +++ b/content/nap-waf/v4/logging-overview/security-log.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect WAF Security Log. -docs: DOCS-915 +nd-docs: DOCS-915 title: NGINX App Protect WAF Security Log toc: true weight: 520 diff --git a/content/nap-waf/v4/releases/about-1.0.md b/content/nap-waf/v4/releases/about-1.0.md index a92eb466c..0d7ad81e4 100644 --- a/content/nap-waf/v4/releases/about-1.0.md +++ b/content/nap-waf/v4/releases/about-1.0.md @@ -4,7 +4,7 @@ weight: 1060 toc: true type: reference product: NAP-WAF -docs: DOCS-649 +nd-docs: DOCS-649 --- May 19, 2020 diff --git a/content/nap-waf/v4/releases/about-1.1.md b/content/nap-waf/v4/releases/about-1.1.md index 658adcae8..4799b4da9 100644 --- a/content/nap-waf/v4/releases/about-1.1.md +++ b/content/nap-waf/v4/releases/about-1.1.md @@ -4,7 +4,7 @@ weight: 1040 toc: true type: reference product: NAP-WAF -docs: DOCS-650 +nd-docs: DOCS-650 --- June 9, 2020 diff --git a/content/nap-waf/v4/releases/about-1.2.md b/content/nap-waf/v4/releases/about-1.2.md index ec7a3eb72..483b108a3 100644 --- a/content/nap-waf/v4/releases/about-1.2.md +++ b/content/nap-waf/v4/releases/about-1.2.md @@ -4,7 +4,7 @@ weight: 1020 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1791 --- June 30, 2020 diff --git a/content/nap-waf/v4/releases/about-1.3.md b/content/nap-waf/v4/releases/about-1.3.md index 949b826f0..9dc5f8788 100644 --- a/content/nap-waf/v4/releases/about-1.3.md +++ b/content/nap-waf/v4/releases/about-1.3.md @@ -4,7 +4,7 @@ weight: 1000 toc: true type: reference product: NAP-WAF -docs: DOCS-652 +nd-docs: DOCS-652 --- July 21, 2020 diff --git a/content/nap-waf/v4/releases/about-2.0.md b/content/nap-waf/v4/releases/about-2.0.md index 41d7edf01..af8deb50e 100644 --- a/content/nap-waf/v4/releases/about-2.0.md +++ b/content/nap-waf/v4/releases/about-2.0.md @@ -4,7 +4,7 @@ weight: 980 toc: true type: reference product: NAP-WAF -docs: DOCS-653 +nd-docs: DOCS-653 --- September 08, 2020 diff --git a/content/nap-waf/v4/releases/about-2.1.md b/content/nap-waf/v4/releases/about-2.1.md index 1043a365c..b06400d96 100644 --- a/content/nap-waf/v4/releases/about-2.1.md +++ b/content/nap-waf/v4/releases/about-2.1.md @@ -4,7 +4,7 @@ weight: 960 toc: true type: reference product: NAP-WAF -docs: DOCS-654 +nd-docs: DOCS-654 --- October 28, 2020 diff --git a/content/nap-waf/v4/releases/about-2.2.md b/content/nap-waf/v4/releases/about-2.2.md index b62160c1f..25664110f 100644 --- a/content/nap-waf/v4/releases/about-2.2.md +++ b/content/nap-waf/v4/releases/about-2.2.md @@ -4,7 +4,7 @@ weight: 940 toc: true type: reference product: NAP-WAF -docs: DOCS-655 +nd-docs: DOCS-655 --- December 09, 2020 diff --git a/content/nap-waf/v4/releases/about-2.3.md b/content/nap-waf/v4/releases/about-2.3.md index a3b527394..0b77716f3 100644 --- a/content/nap-waf/v4/releases/about-2.3.md +++ b/content/nap-waf/v4/releases/about-2.3.md @@ -4,7 +4,7 @@ weight: 920 toc: true type: reference product: NAP-WAF -docs: DOCS-656 +nd-docs: DOCS-656 --- December 30, 2020 diff --git a/content/nap-waf/v4/releases/about-3.0.md b/content/nap-waf/v4/releases/about-3.0.md index d8cb52787..d1a728e27 100644 --- a/content/nap-waf/v4/releases/about-3.0.md +++ b/content/nap-waf/v4/releases/about-3.0.md @@ -4,7 +4,7 @@ weight: 800 toc: true type: reference product: NAP-WAF -docs: DOCS-657 +nd-docs: DOCS-657 --- January 29, 2021 diff --git a/content/nap-waf/v4/releases/about-3.1.md b/content/nap-waf/v4/releases/about-3.1.md index 543004cba..ac627cc31 100644 --- a/content/nap-waf/v4/releases/about-3.1.md +++ b/content/nap-waf/v4/releases/about-3.1.md @@ -4,7 +4,7 @@ weight: 790 toc: true type: reference product: NAP-WAF -docs: DOCS-658 +nd-docs: DOCS-658 --- March 31, 2021 diff --git a/content/nap-waf/v4/releases/about-3.10.md b/content/nap-waf/v4/releases/about-3.10.md index 76bd2d094..b4ce69183 100644 --- a/content/nap-waf/v4/releases/about-3.10.md +++ b/content/nap-waf/v4/releases/about-3.10.md @@ -4,7 +4,7 @@ weight: 680 toc: true type: reference product: NAP-WAF -docs: DOCS-846 +nd-docs: DOCS-846 --- May 25, 2022 diff --git a/content/nap-waf/v4/releases/about-3.11.md b/content/nap-waf/v4/releases/about-3.11.md index fd7e40baf..72015ea43 100644 --- a/content/nap-waf/v4/releases/about-3.11.md +++ b/content/nap-waf/v4/releases/about-3.11.md @@ -4,7 +4,7 @@ weight: 660 toc: true type: reference product: NAP-WAF -docs: DOCS-891 +nd-docs: DOCS-891 --- June 28, 2022 diff --git a/content/nap-waf/v4/releases/about-3.12.2.md b/content/nap-waf/v4/releases/about-3.12.2.md index 579b98006..915e68336 100644 --- a/content/nap-waf/v4/releases/about-3.12.2.md +++ b/content/nap-waf/v4/releases/about-3.12.2.md @@ -4,7 +4,7 @@ weight: 620 toc: true type: reference product: NAP-WAF -docs: DOCS-988 +nd-docs: DOCS-988 --- November 17, 2022 diff --git a/content/nap-waf/v4/releases/about-3.12.md b/content/nap-waf/v4/releases/about-3.12.md index 80d60f15e..81ee0c65c 100644 --- a/content/nap-waf/v4/releases/about-3.12.md +++ b/content/nap-waf/v4/releases/about-3.12.md @@ -4,7 +4,7 @@ weight: 640 toc: true type: reference product: NAP-WAF -docs: DOCS-943 +nd-docs: DOCS-943 --- September 21, 2022 diff --git a/content/nap-waf/v4/releases/about-3.2.md b/content/nap-waf/v4/releases/about-3.2.md index 216030019..5abd54264 100644 --- a/content/nap-waf/v4/releases/about-3.2.md +++ b/content/nap-waf/v4/releases/about-3.2.md @@ -4,7 +4,7 @@ weight: 780 toc: true type: reference product: NAP-WAF -docs: DOCS-659 +nd-docs: DOCS-659 --- April 28, 2021 diff --git a/content/nap-waf/v4/releases/about-3.3.md b/content/nap-waf/v4/releases/about-3.3.md index 1321cf141..4ce5ac26b 100644 --- a/content/nap-waf/v4/releases/about-3.3.md +++ b/content/nap-waf/v4/releases/about-3.3.md @@ -4,7 +4,7 @@ weight: 770 toc: true type: reference product: NAP-WAF -docs: DOCS-660 +nd-docs: DOCS-660 --- July 7, 2021 diff --git a/content/nap-waf/v4/releases/about-3.4.md b/content/nap-waf/v4/releases/about-3.4.md index ae3880eed..1c2027f08 100644 --- a/content/nap-waf/v4/releases/about-3.4.md +++ b/content/nap-waf/v4/releases/about-3.4.md @@ -4,7 +4,7 @@ weight: 760 toc: true type: reference product: NAP-WAF -docs: DOCS-661 +nd-docs: DOCS-661 --- August 10, 2021 diff --git a/content/nap-waf/v4/releases/about-3.5.md b/content/nap-waf/v4/releases/about-3.5.md index 895f68c39..a21285446 100644 --- a/content/nap-waf/v4/releases/about-3.5.md +++ b/content/nap-waf/v4/releases/about-3.5.md @@ -4,7 +4,7 @@ weight: 750 toc: true type: reference product: NAP-WAF -docs: DOCS-662 +nd-docs: DOCS-662 --- September 6, 2021 diff --git a/content/nap-waf/v4/releases/about-3.6.md b/content/nap-waf/v4/releases/about-3.6.md index aff52b5b5..ba4d35512 100644 --- a/content/nap-waf/v4/releases/about-3.6.md +++ b/content/nap-waf/v4/releases/about-3.6.md @@ -4,7 +4,7 @@ weight: 740 toc: true type: reference product: NAP-WAF -docs: DOCS-663 +nd-docs: DOCS-663 --- October 13, 2021 diff --git a/content/nap-waf/v4/releases/about-3.7.md b/content/nap-waf/v4/releases/about-3.7.md index a9e4e2886..304d869c7 100644 --- a/content/nap-waf/v4/releases/about-3.7.md +++ b/content/nap-waf/v4/releases/about-3.7.md @@ -4,7 +4,7 @@ weight: 730 toc: true type: reference product: NAP-WAF -docs: DOCS-664 +nd-docs: DOCS-664 --- December 15, 2021 diff --git a/content/nap-waf/v4/releases/about-3.8.md b/content/nap-waf/v4/releases/about-3.8.md index 0511b6708..94acc1198 100644 --- a/content/nap-waf/v4/releases/about-3.8.md +++ b/content/nap-waf/v4/releases/about-3.8.md @@ -4,7 +4,7 @@ weight: 720 toc: true type: reference product: NAP-WAF -docs: DOCS-832 +nd-docs: DOCS-832 --- January 18, 2022 diff --git a/content/nap-waf/v4/releases/about-3.9.1.md b/content/nap-waf/v4/releases/about-3.9.1.md index e3356ba9f..7185041b9 100644 --- a/content/nap-waf/v4/releases/about-3.9.1.md +++ b/content/nap-waf/v4/releases/about-3.9.1.md @@ -4,7 +4,7 @@ weight: 700 toc: true type: reference product: NAP-WAF -docs: DOCS-842 +nd-docs: DOCS-842 --- March 9, 2022 diff --git a/content/nap-waf/v4/releases/about-3.9.md b/content/nap-waf/v4/releases/about-3.9.md index ffede02ad..73bd50c6c 100644 --- a/content/nap-waf/v4/releases/about-3.9.md +++ b/content/nap-waf/v4/releases/about-3.9.md @@ -4,7 +4,7 @@ weight: 710 toc: true type: reference product: NAP-WAF -docs: DOCS-838 +nd-docs: DOCS-838 --- February 15, 2022 diff --git a/content/nap-waf/v4/releases/about-4.0.md b/content/nap-waf/v4/releases/about-4.0.md index 61411fd29..e4c985f0d 100644 --- a/content/nap-waf/v4/releases/about-4.0.md +++ b/content/nap-waf/v4/releases/about-4.0.md @@ -4,7 +4,7 @@ weight: 410 toc: true type: reference product: NAP-WAF -docs: DOCS-994 +nd-docs: DOCS-994 --- November 29, 2022 diff --git a/content/nap-waf/v4/releases/about-4.1.md b/content/nap-waf/v4/releases/about-4.1.md index 63b806c94..e993f2425 100644 --- a/content/nap-waf/v4/releases/about-4.1.md +++ b/content/nap-waf/v4/releases/about-4.1.md @@ -4,7 +4,7 @@ weight: 400 toc: true type: reference product: NAP-WAF -docs: DOCS-1116 +nd-docs: DOCS-1116 --- January 31, 2023 diff --git a/content/nap-waf/v4/releases/about-4.10.md b/content/nap-waf/v4/releases/about-4.10.md index 8097546aa..7bdd5c45c 100644 --- a/content/nap-waf/v4/releases/about-4.10.md +++ b/content/nap-waf/v4/releases/about-4.10.md @@ -4,7 +4,7 @@ weight: 130 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1787 --- May 29, 2024 @@ -23,7 +23,7 @@ In this release, NGINX App Protect WAF supports NGINX Plus R32. #### App Protect -##### Alpine Linux 3.16 +##### Alpine Linux 3.16 - app-protect-32.5.48.0-r1.apk @@ -47,7 +47,7 @@ In this release, NGINX App Protect WAF supports NGINX Plus R32. - app-protect-32+5.48.0-1.el8.ngx.x86_64.rpm -##### RHEL 8.1+ +##### RHEL 8.1+ - app-protect-32+5.48.0-1.el8.ngx.x86_64.rpm diff --git a/content/nap-waf/v4/releases/about-4.11.md b/content/nap-waf/v4/releases/about-4.11.md index 438bd8c99..daf3c93ad 100644 --- a/content/nap-waf/v4/releases/about-4.11.md +++ b/content/nap-waf/v4/releases/about-4.11.md @@ -4,7 +4,7 @@ weight: 120 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1786 --- September 25, 2024 diff --git a/content/nap-waf/v4/releases/about-4.12.md b/content/nap-waf/v4/releases/about-4.12.md index e735023b9..61e77bb4c 100644 --- a/content/nap-waf/v4/releases/about-4.12.md +++ b/content/nap-waf/v4/releases/about-4.12.md @@ -4,7 +4,7 @@ weight: 110 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1788 --- November 19th, 2024 diff --git a/content/nap-waf/v4/releases/about-4.13.md b/content/nap-waf/v4/releases/about-4.13.md index b332f4aa9..e664466d3 100644 --- a/content/nap-waf/v4/releases/about-4.13.md +++ b/content/nap-waf/v4/releases/about-4.13.md @@ -4,7 +4,7 @@ weight: 100 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1790 --- January 30th, 2025 diff --git a/content/nap-waf/v4/releases/about-4.14.md b/content/nap-waf/v4/releases/about-4.14.md index 89ff9875d..ef20b99f6 100644 --- a/content/nap-waf/v4/releases/about-4.14.md +++ b/content/nap-waf/v4/releases/about-4.14.md @@ -4,7 +4,7 @@ weight: 90 toc: true type: reference product: NAP-WAF -docs: DOCS-000 +nd-docs: DOCS-1792 --- April 1st, 2025 diff --git a/content/nap-waf/v4/releases/about-4.15.md b/content/nap-waf/v4/releases/about-4.15.md new file mode 100644 index 000000000..1dba23851 --- /dev/null +++ b/content/nap-waf/v4/releases/about-4.15.md @@ -0,0 +1,44 @@ +--- +title: NGINX App Protect WAF 4.15 +weight: 80 +toc: true +nd-content-type: reference +nd-product: NAP-WAF +nd-docs: DOCS-1789 +--- + +June 24th, 2025 + +## New features + +- Added support for [IP Intelligence]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-intelligence-configuration" >}}) +- Added support for Rocky Linux 9 +- Added support for Override rules for [IP Address Lists]({{< ref "/nap-waf/v4/configuration-guide/configuration.md#ip-address-lists" >}}) + +## Important notes + +- Ubuntu 20.04 is no longer supported +- 12447 - Upgrade libk5crypto3 package +- 12520 - Upgrade Go compiler to 1.23.8 + +## Resolved issues + +- 12527 - Remove CPAN - installed certs and source files +- 11112 - Remove systemd/init.d leftovers in NAP WAF v5 pkgs +- 12400 - Cookie attributes are not added to a TS cookie when there is more than one TS cookie +- 12498 - Undefined behavior when using huge XFF +- 12731 - Multiple clean_resp_reset internal error messages in logs when loading NAP + +## Supported packages + +| Distribution name | Package file | +|--------------------------|----------------------------------------------------| +| Alpine 3.19 | _app-protect-34.5.442.0-r1.apk_ | +| Amazon Linux 2023 | _app-protect-34+5.442.0-1.amzn2023.ngx.x86_64.rpm_ | +| Debian 11 | _app-protect_34+5.442.0-1\~bullseye_amd64.deb_ | +| Debian 12 | _app-protect_34+5.442.0-1\~bookworm_amd64.deb_ | +| Oracle Linux 8.1 | _app-protect-34+5.442.0-1.el8.ngx.x86_64.rpm_ | +| Ubuntu 22.04 | _app-protect_34+5.442.0-1\~jammy_amd64.deb_ | +| Ubuntu 24.04 | _app-protect_34+5.442.0-1\~noble_amd64.deb_ | +| RHEL 8 and Rocky Linux 8 | _app-protect-34+5.442.0-1.el8.ngx.x86_64.rpm_ | +| RHEL 9 and Rocky Linux 9 | _app-protect-34+5.442.0-1.el9.ngx.x86_64.rpm_ | diff --git a/content/nap-waf/v4/releases/about-4.2.md b/content/nap-waf/v4/releases/about-4.2.md index ef9503d21..73d5d0f38 100644 --- a/content/nap-waf/v4/releases/about-4.2.md +++ b/content/nap-waf/v4/releases/about-4.2.md @@ -4,7 +4,7 @@ weight: 310 toc: true type: reference product: NAP-WAF -docs: DOCS-1172 +nd-docs: DOCS-1172 --- March 29, 2023 diff --git a/content/nap-waf/v4/releases/about-4.3.md b/content/nap-waf/v4/releases/about-4.3.md index d5f160777..a7820e169 100644 --- a/content/nap-waf/v4/releases/about-4.3.md +++ b/content/nap-waf/v4/releases/about-4.3.md @@ -4,7 +4,7 @@ weight: 210 toc: true type: reference product: NAP-WAF -docs: DOCS-1202 +nd-docs: DOCS-1202 --- May 2, 2023 diff --git a/content/nap-waf/v4/releases/about-4.4.md b/content/nap-waf/v4/releases/about-4.4.md index 47c0d4e34..98065a6d6 100644 --- a/content/nap-waf/v4/releases/about-4.4.md +++ b/content/nap-waf/v4/releases/about-4.4.md @@ -4,7 +4,7 @@ weight: 200 toc: true type: reference product: NAP-WAF -docs: DOCS-1252 +nd-docs: DOCS-1252 --- July 5, 2023 diff --git a/content/nap-waf/v4/releases/about-4.5.md b/content/nap-waf/v4/releases/about-4.5.md index 4ac361f74..752812849 100644 --- a/content/nap-waf/v4/releases/about-4.5.md +++ b/content/nap-waf/v4/releases/about-4.5.md @@ -4,7 +4,7 @@ weight: 190 toc: true type: reference product: NAP-WAF -docs: DOCS-1253 +nd-docs: DOCS-1253 --- August 15, 2023 diff --git a/content/nap-waf/v4/releases/about-4.6.md b/content/nap-waf/v4/releases/about-4.6.md index 100e4059f..9b71d7b58 100644 --- a/content/nap-waf/v4/releases/about-4.6.md +++ b/content/nap-waf/v4/releases/about-4.6.md @@ -4,7 +4,7 @@ weight: 180 toc: true type: reference product: NAP-WAF -docs: DOCS-1347 +nd-docs: DOCS-1347 --- October 17, 2023 diff --git a/content/nap-waf/v4/releases/about-4.7.md b/content/nap-waf/v4/releases/about-4.7.md index 62181c049..447cbb919 100644 --- a/content/nap-waf/v4/releases/about-4.7.md +++ b/content/nap-waf/v4/releases/about-4.7.md @@ -4,7 +4,7 @@ weight: 170 toc: true type: reference product: NAP-WAF -docs: DOCS-1360 +nd-docs: DOCS-1360 --- December 19, 2023 diff --git a/content/nap-waf/v4/releases/about-4.8.1.md b/content/nap-waf/v4/releases/about-4.8.1.md index ed85394d9..8a978fe6e 100644 --- a/content/nap-waf/v4/releases/about-4.8.1.md +++ b/content/nap-waf/v4/releases/about-4.8.1.md @@ -4,7 +4,7 @@ weight: 150 toc: true type: reference product: NAP-WAF -docs: DOCS-1477 +nd-docs: DOCS-1477 --- March 6, 2024 diff --git a/content/nap-waf/v4/releases/about-4.8.md b/content/nap-waf/v4/releases/about-4.8.md index 37efe6ae7..268dcd877 100644 --- a/content/nap-waf/v4/releases/about-4.8.md +++ b/content/nap-waf/v4/releases/about-4.8.md @@ -4,7 +4,7 @@ weight: 160 toc: true type: reference product: NAP-WAF -docs: DOCS-1391 +nd-docs: DOCS-1391 --- February 6, 2024 diff --git a/content/nap-waf/v4/releases/about-4.9.md b/content/nap-waf/v4/releases/about-4.9.md index 17b2af609..aeb44e88d 100644 --- a/content/nap-waf/v4/releases/about-4.9.md +++ b/content/nap-waf/v4/releases/about-4.9.md @@ -4,7 +4,7 @@ weight: 140 toc: true type: reference product: NAP-WAF -docs: DOCS-1478 +nd-docs: DOCS-1478 --- April 18, 2024 diff --git a/content/nap-waf/v4/troubleshooting-guide/troubleshooting.md b/content/nap-waf/v4/troubleshooting-guide/troubleshooting.md index f4971a732..cd5da81be 100644 --- a/content/nap-waf/v4/troubleshooting-guide/troubleshooting.md +++ b/content/nap-waf/v4/troubleshooting-guide/troubleshooting.md @@ -1,6 +1,6 @@ --- description: Learn about the F5 NGINX App Protect WAF Troubleshooting Guide. -docs: DOCS-665 +nd-docs: DOCS-665 title: NGINX App Protect WAF Troubleshooting Guide toc: true weight: 400 diff --git a/content/nap-waf/v5/admin-guide/compiler.md b/content/nap-waf/v5/admin-guide/compiler.md index ea0f28500..0e1a3564c 100644 --- a/content/nap-waf/v5/admin-guide/compiler.md +++ b/content/nap-waf/v5/admin-guide/compiler.md @@ -4,7 +4,7 @@ weight: 500 toc: true type: how-to product: NAP-WAF -docs: DOCS-1367 +nd-docs: DOCS-1367 --- ## Overview diff --git a/content/nap-waf/v5/admin-guide/deploy-on-docker.md b/content/nap-waf/v5/admin-guide/deploy-on-docker.md index 40ab5e5b3..a135e5a5f 100644 --- a/content/nap-waf/v5/admin-guide/deploy-on-docker.md +++ b/content/nap-waf/v5/admin-guide/deploy-on-docker.md @@ -4,7 +4,7 @@ weight: 500 toc: true type: how-to product: NAP-WAF -docs: DOCS-1365 +nd-docs: DOCS-1365 --- ## Prerequisites @@ -104,6 +104,11 @@ CMD ["nginx", "-g", "daemon off;"] {{< include "nap-waf/config/v5/build-nginx-image-oss/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-oss/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -183,6 +188,11 @@ CMD ["nginx", "-g", "daemon off;"] {{< include "nap-waf/config/v5/build-nginx-image-plus/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-plus/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -346,6 +356,11 @@ volumes: ``` +### Docker Compose File with IP Intelligence + +{{< include "nap-waf/ip-intelligence.md" >}} + + ### Docker Compose File with mTLS To secure traffic between NGINX and App Protect Enforcer using mTLS, create a `docker-compose.yml` with the following configuration: @@ -486,6 +501,11 @@ Proceed, by creating a `Dockerfile` using one of the examples provided below. {{< include "nap-waf/config/v5/build-nginx-image-oss/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-oss/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -518,6 +538,11 @@ You are ready to [Build the image](#build-image-sub) {{< include "nap-waf/config/v5/build-nginx-image-plus/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-plus/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -665,6 +690,11 @@ volumes: app_protect_config: app_protect_etc_config: ``` + +#### Docker Compose File with IP Intelligence + +{{< include "nap-waf/ip-intelligence.md" >}} + ### Start Deployment 1. To start the NGINX and WAF services, navigate to the directory that contains the `docker-compose.yml` file and run: diff --git a/content/nap-waf/v5/admin-guide/deploy-with-helm.md b/content/nap-waf/v5/admin-guide/deploy-with-helm.md index 32b3105be..3d2c81e9e 100644 --- a/content/nap-waf/v5/admin-guide/deploy-with-helm.md +++ b/content/nap-waf/v5/admin-guide/deploy-with-helm.md @@ -4,6 +4,7 @@ weight: 300 toc: true type: how-to product: NAP-WAF +nd-docs: DOCS-1793 --- ## Overview @@ -38,7 +39,7 @@ Next, create a `Dockerfile` using one of the examples provided below. {{}} {{%tab name="Alpine Linux"%}} - + {{< include "nap-waf/config/v5/build-nginx-image-oss/build-alpine.md" >}} {{%/tab%}} @@ -66,6 +67,11 @@ Next, create a `Dockerfile` using one of the examples provided below. {{< include "nap-waf/config/v5/build-nginx-image-oss/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-oss/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -80,7 +86,7 @@ You are ready to [Build the image](#build-image). {{}} {{%tab name="Alpine Linux"%}} - + {{< include "nap-waf/config/v5/build-nginx-image-plus/build-alpine.md" >}} {{%/tab%}} @@ -108,6 +114,11 @@ You are ready to [Build the image](#build-image). {{< include "nap-waf/config/v5/build-nginx-image-plus/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-plus/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -122,7 +133,7 @@ You are ready to [Build the image](#build-image). Next, push it to your private image repository, ensuring it's accessible to your Kubernetes cluster. ---- +--- ## Pull the chart @@ -231,6 +242,11 @@ To use the *mTLS Configuration* options, read the [Secure Traffic Between NGINX | | _appprotect.wafEnforcer.imagePullPolicy_ | Image pull policy. | IfNotPresent | | | _appprotect.wafEnforcer.env.enforcerPort_ | Port for the WAF Enforcer. | 50000 | | | _appprotect.wafEnforcer.resources_ | The resources of the WAF Enforcer container. | requests: cpu=20m,memory=256Mi | +| **WAF IP Intelligence** | _appprotect.wafIpIntelligence.enable | Enable or disable the use of the IP intelligence container | false | +| | _appprotect.wafIpIntelligence.image.repository_ | Docker image repository for the WAF IP Intelligence. | private-registry.nginx.com/nap/waf-ip-intelligence | +| | _appprotect.wafIpIntelligence.image.tag_ | Docker image tag for the WAF Enforcer. | 5.6.0 | +| | _appprotect.wafIpIntelligence.imagePullPolicy_ | Image pull policy. | IfNotPresent | +| | _appprotect.wafIpIntelligence.resources_ | The resources of the WAF Enforcer container. | requests: cpu=10m,memory=256Mi | | **Config** | _appprotect.config.name_ | The name of the ConfigMap used by the NGINX container. | nginx-config | | | _appprotect.config.annotations_ | The annotations of the ConfigMap. | {} | | | _appprotect.config.nginxJWT_ | JWT license for NGINX. | "" | diff --git a/content/nap-waf/v5/admin-guide/deploy-with-manifests.md b/content/nap-waf/v5/admin-guide/deploy-with-manifests.md index 310d5400b..751c778c8 100644 --- a/content/nap-waf/v5/admin-guide/deploy-with-manifests.md +++ b/content/nap-waf/v5/admin-guide/deploy-with-manifests.md @@ -4,7 +4,7 @@ weight: 400 toc: true type: how-to product: NAP-WAF -docs: DOCS-1366 +nd-docs: DOCS-1366 --- ## Prerequisites @@ -59,6 +59,11 @@ Proceed, by creating a `Dockerfile` using one of the examples provided below. {{< include "nap-waf/config/v5/build-nginx-image-oss/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-oss/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -101,6 +106,11 @@ You are ready to [Build the image](#build-image). {{< include "nap-waf/config/v5/build-nginx-image-plus/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-plus/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -281,6 +291,82 @@ spec: claimName: nap5-bundles-pvc ``` +An example `nap5-deployment-with-ip-intelligence.yaml` if you are using the IP Intelligence feature: + +Replace the `/nginx-app-protect-5:` with the actual image tag. + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nap5-deployment +spec: + selector: + matchLabels: + app: nap5 + replicas: 2 + template: + metadata: + labels: + app: nap5 + spec: + imagePullSecrets: + - name: regcred + containers: + - name: nginx + image: /nginx-app-protect-5: + imagePullPolicy: IfNotPresent + volumeMounts: + - name: app-protect-bd-config + mountPath: /opt/app_protect/bd_config + - name: app-protect-config + mountPath: /opt/app_protect/config + - name: waf-enforcer + image: private-registry.nginx.com/nap/waf-enforcer: + imagePullPolicy: IfNotPresent + env: + - name: ENFORCER_PORT + value: "50000" + volumeMounts: + - name: app-protect-bd-config + mountPath: /opt/app_protect/bd_config + - name: var-iprep + mountPath: /var/IpRep + - name: waf-config-mgr + image: private-registry.nginx.com/nap/waf-config-mgr: + imagePullPolicy: IfNotPresent + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: + - all + volumeMounts: + - name: app-protect-bd-config + mountPath: /opt/app_protect/bd_config + - name: app-protect-config + mountPath: /opt/app_protect/config + - name: app-protect-bundles + mountPath: /etc/app_protect/bundles + - name: waf-ip-intelligence + image: private-registry.nginx.com/napwaf-ip-intelligence: + imagePullPolicy: IfNotPresent + securityContext: + allowPrivilegeEscalation: false + volumeMounts: + - name: var-iprep + mountPath: /var/IpRep + volumes: + - name: app-protect-bd-config + emptyDir: {} + - name: app-protect-config + emptyDir: {} + - name: var-iprep + emptyDir: {} + - name: app-protect-bundles + persistentVolumeClaim: + claimName: nap5-bundles-pvc +``` + Finally, `nap5-service.yaml`: ```yaml @@ -371,8 +457,8 @@ spec: {{< include "/nap-waf/nap-k8s-readonly-paths.md" >}} ---- - +--- + ### Possible issues {{< include "/nap-waf/nap-k8s-readonly-issues.md" >}} @@ -436,6 +522,11 @@ Proceed, by creating a `Dockerfile` using one of the examples provided below. {{< include "nap-waf/config/v5/build-nginx-image-oss/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-oss/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} @@ -468,6 +559,11 @@ You are ready to [Build the image](#build-image-sub) {{< include "nap-waf/config/v5/build-nginx-image-plus/build-rhel.md" >}} +{{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/build-nginx-image-plus/build-rocky.md" >}} + {{%/tab%}} {{%tab name="Ubuntu"%}} diff --git a/content/nap-waf/v5/admin-guide/install.md b/content/nap-waf/v5/admin-guide/install.md index 3a125b0a9..b6263a507 100644 --- a/content/nap-waf/v5/admin-guide/install.md +++ b/content/nap-waf/v5/admin-guide/install.md @@ -4,7 +4,7 @@ weight: 200 toc: true type: how-to product: NAP-WAF -docs: DOCS-1363 +nd-docs: DOCS-1363 --- ## Prerequisites @@ -39,7 +39,7 @@ Please follow these steps before you install either NGINX Open Source or NGINX P {{}} {{%tab name="Alpine Linux"%}} - + {{< include "nap-waf/config/v5/host-based-nginx-instructions/common-steps-with-alpine" >}} {{%/tab%}} @@ -68,6 +68,12 @@ Please follow these steps before you install either NGINX Open Source or NGINX P {{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/host-based-nginx-instructions/common-steps-with-dnf.md" >}} + +{{%/tab%}} + {{%tab name="Ubuntu"%}} {{< include "nap-waf/config/v5/host-based-nginx-instructions/common-steps-with-ubuntu.md" >}} @@ -111,6 +117,12 @@ Please follow these steps before you install either NGINX Open Source or NGINX P {{%/tab%}} +{{%tab name="Rocky Linux 9"%}} + +{{< include "nap-waf/config/v5/host-based-nginx-instructions/nginx-oss-centos.md" >}} + +{{%/tab%}} + {{%tab name="Ubuntu"%}} {{< include "nap-waf/config/v5/host-based-nginx-instructions/nginx-oss-ubuntu.md" >}} @@ -166,7 +178,7 @@ sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.rep {{%/tab%}} -{{%tab name="RHEL 9"%}} +{{%tab name="RHEL 9 / Rocky Linux 9"%}} Download the NGINX Plus repository file [plus-9.repo](https://cs.nginx.com/static/files/plus-9.repo) to `/etc/yum.repos.d`: @@ -294,6 +306,10 @@ networks: In some operating systems, security mechanisms like **SELinux** or **AppArmor** are enabled by default, potentially blocking necessary file access for the `nginx` process and `waf-config-mgr` and `waf-enforcer` containers. To ensure NGINX App Protect WAF v5 operates smoothly without compromising security, consider setting up a custom SELinux policy or AppArmor profile. For short-term troubleshooting, you may use `permissive` (SELinux) or `complain` (AppArmor) mode to avoid these restrictions, but keep in mind that this lowers security and isn't advised for prolonged use. {{< /note >}} +### Docker Compose File with IP Intelligence + +{{< include "nap-waf/ip-intelligence.md" >}} + ## Start the Deployment 1. To start the WAF services, navigate to the directory that contains the `docker-compose.yml` file and run: @@ -314,6 +330,10 @@ In some operating systems, security mechanisms like **SELinux** or **AppArmor** curl "localhost/
      @@ -3380,7 +3469,7 @@

      login-pages

    passwordRegex stringPCRE regular expression for capturing the password. The regular expression must include exactly one capturing group (in rounded parentheses) for the value of the password. For example: "pwd=(w+)". The entered expression is validated and any invalid code is noted and must be corrected. Note: This setting is only relevant if authenticationType is request-body.
    usernameRegex stringPCRE regular expression for capturing the username. The regular expression must include exactly one capturing group (in rounded parentheses) for the value of the username. For example: "user_id=(w+)". The entered expression is validated and any invalid code is noted and must be corrected. Note: This setting is only relevant if authenticationType is request-body.