From c67d69253521379c86d4fa9b918d7feaa634b634 Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Wed, 25 Jun 2025 07:34:00 -0700 Subject: [PATCH 1/4] updated the nginx config snippet for enabling the NGINX Plus API and dashboard --- .../enable-nplus-api-dashboard.md | 43 +++++++++++++ .../monitoring/enable-nginx-plus-api.md | 62 +++---------------- 2 files changed, 51 insertions(+), 54 deletions(-) create mode 100644 content/includes/config-snippets/enable-nplus-api-dashboard.md 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..5d8c30935 --- /dev/null +++ b/content/includes/config-snippets/enable-nplus-api-dashboard.md @@ -0,0 +1,43 @@ +--- +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; + } + + # Redirect any request to the root path "/" to the dashboard + location / { + return 301 /dashboard.html; + } +} +``` \ No newline at end of file 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 c605d0c22..409bbf50b 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md @@ -4,61 +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 -# This block: -# - Enables the read-write NGINX Plus API under /api/ -# - Serves the built-in dashboard at /dashboard.html -# - Restricts write methods (POST, PATCH, DELETE) to authenticated users -# and a specified IP range -# Change the listen port if 9000 conflicts; 8080 is the conventional API port. -server { - # Listen on port 9000 for API and dashboard traffic - listen 9000 default_server; +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: - # Handle API calls under /api/ - location /api/ { - # Enable write operations (POST, PATCH, DELETE) - api write=on; +{{< include "config-snippets/enable-nplus-api-dashboard.md" >}} - # Allow GET requests from any IP - allow 0.0.0.0/0; - # Deny all other requests by default - deny all; +{{< call-out "note" "Security tip" >}} +- By default, all clients can call the API. +- To limit who can call **any** API method, uncomment the `allow`/`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. +{{}} - # For methods other than GET, require auth and restrict to a network - limit_except GET { - # Prompt for credentials with this realm - auth_basic "NGINX Plus API"; - # Path to the file with usernames and passwords - auth_basic_user_file /path/to/passwd/file; - - # Allow only this IP range (replace with your own) - allow 192.0.2.0/24; - # Deny all other IPs - deny all; - } - } - - # Serve the dashboard page at /dashboard.html - location = /dashboard.html { - # Files are located under this directory - root /usr/share/nginx/html; - } - - # Redirect any request for / to the dashboard - location / { - return 301 /dashboard.html; - } -} -``` - -For more details, see the [NGINX Plus API module documentation](https://nginx.org/en/docs/http/ngx_http_api_module.html) and [Configuring the NGINX Plus API]({{< ref "nginx/admin-guide/monitoring/live-activity-monitoring.md#configuring-the-api" >}}). - -After saving the changes, reload NGINX: - -```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 From 134158b76c32b1c05e111897d455c4c36f5996ed Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Wed, 25 Jun 2025 07:41:03 -0700 Subject: [PATCH 2/4] edits --- content/includes/config-snippets/enable-nplus-api-dashboard.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/includes/config-snippets/enable-nplus-api-dashboard.md b/content/includes/config-snippets/enable-nplus-api-dashboard.md index 5d8c30935..46f2b856a 100644 --- a/content/includes/config-snippets/enable-nplus-api-dashboard.md +++ b/content/includes/config-snippets/enable-nplus-api-dashboard.md @@ -5,7 +5,6 @@ files: - 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: From 07f8d78732e93bc0b1a7047563f270e51e9a095f Mon Sep 17 00:00:00 2001 From: Travis Martin <33876974+travisamartin@users.noreply.github.com> Date: Wed, 25 Jun 2025 07:54:01 -0700 Subject: [PATCH 3/4] Update content/includes/use-cases/monitoring/enable-nginx-plus-api.md Co-authored-by: Alan Dooley --- content/includes/use-cases/monitoring/enable-nginx-plus-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 409bbf50b..e533e357c 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md @@ -15,4 +15,4 @@ To collect comprehensive metrics for NGINX Plus, including bytes streamed, infor - To restrict write methods (`POST`, `PATCH`, `DELETE`), uncomment and configure the `limit_except GET` block. {{}} -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 +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 From 31957a54eec3f1e160dedc77b1a3d456883ae750 Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Wed, 25 Jun 2025 09:17:36 -0700 Subject: [PATCH 4/4] edits per tech review --- .../includes/config-snippets/enable-nplus-api-dashboard.md | 5 ----- .../includes/use-cases/monitoring/enable-nginx-plus-api.md | 4 ++-- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/content/includes/config-snippets/enable-nplus-api-dashboard.md b/content/includes/config-snippets/enable-nplus-api-dashboard.md index 46f2b856a..0aaf4b750 100644 --- a/content/includes/config-snippets/enable-nplus-api-dashboard.md +++ b/content/includes/config-snippets/enable-nplus-api-dashboard.md @@ -33,10 +33,5 @@ server { location = /dashboard.html { root /usr/share/nginx/html; } - - # Redirect any request to the root path "/" to the dashboard - location / { - return 301 /dashboard.html; - } } ``` \ No newline at end of file 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 e533e357c..50fbd5be7 100644 --- a/content/includes/use-cases/monitoring/enable-nginx-plus-api.md +++ b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md @@ -11,8 +11,8 @@ To collect comprehensive metrics for NGINX Plus, including bytes streamed, infor {{< call-out "note" "Security tip" >}} - By default, all clients can call the API. -- To limit who can call **any** API method, uncomment the `allow`/`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. +- 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](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