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/use-cases/monitoring/enable-nginx-plus-api.md b/content/includes/use-cases/monitoring/enable-nginx-plus-api.md index c605d0c22..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,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 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 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