making some formatting adjustments and adding per-page descriptions

Author: anupras-mohapatra-arm

content/learning-paths/servers-and-cloud-computing/nginx_tune/kernel_comp_lib.md

@@ -1,10 +1,11 @@
 ---
 title: Tune kernel, compiler, and library settings for performance
+description: Tune Linux network settings and evaluate compiler, OpenSSL, PCRE, and zlib choices that can affect NGINX performance on Arm-based platforms.
 weight: 3
 layout: "learningpathall"
 ---
 
-## Kernel configuration
+## Optimize kernel network stack settings
 
 NGINX tuning doesn't stop at `nginx.conf`. Foundational settings such as kernel network queues, socket buffers, compiler choices, and TLS libraries can affect throughput and latency. Treat these settings as part of the same measurement process you use for NGINX directives.
 
@@ -34,32 +35,25 @@ sudo sysctl -w net.ipv4.tcp_wmem="4096 8388608 8388608"
 
 These values are intentionally large. Size them for your expected connection rate, request pattern, and available memory.
 
-- `net.core.somaxconn`:
-  - Selects the maximum number of queued connections the kernel allows.
-  - If the NGINX server needs to support a large number of clients, it can be helpful to increase this parameter.
-  - A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of queued connections.
-- `net.core.rmem_max`:
-  -  Selects the maximum read socket buffer size.
-  - `8 MiB` is likely more than enough for most use cases.
-  - Use a tool such as `ss` to check socket buffer utilization and set a value for this parameter.
-- `net.core.wmem_max`:
-  - Selects the maximum write socket buffer size.
-  - `8 MiB` is likely more than enough for most use cases.
-  - Use a tool such as `ss` to check socket buffer utilization and set a value for this parameter.
-- `net.ipv4.tcp_max_syn_backlog`:
-  - Selects the maximum number of connection requests that are pending but not established yet.
-  - A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of pending connection requests.
-- `net.ipv4.ip_local_port_range`:
-  - Selects the range of local ports the kernel can use.
-  - The example expands the port range. The default range is sufficient for many deployments.
-- `net.ipv4.tcp_rmem`:
-  - Selects the TCP read socket buffer size.
-  - `8 MiB` is likely more than enough for most use cases.
-  - Use a tool such as `ss` to check TCP buffer utilization and set a value for this parameter.
-- `net.ipv4.tcp_wmem`:
-  - Selects the TCP write socket buffer size.
-  - `8 MiB` is likely more than enough for most use cases.
-  - Use a tool such as `ss` to check TCP buffer utilization and set a value for this parameter.
+- `net.core.somaxconn`: Selects the maximum number of queued connections the kernel allows. If the NGINX server needs to support a large number of clients, it can be helpful to increase this parameter.
+
+  A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of queued connections.
+- `net.core.rmem_max`:  Selects the maximum read socket buffer size. `8 MiB` is likely more than enough for most use cases.
+
+  Use a tool such as `ss` to check socket buffer utilization and set a value for this parameter.
+- `net.core.wmem_max`: Selects the maximum write socket buffer size. `8 MiB` is likely more than enough for most use cases.
+  
+  Use a tool such as `ss` to check socket buffer utilization and set a value for this parameter.
+- `net.ipv4.tcp_max_syn_backlog`: Selects the maximum number of connection requests that are pending but not established yet.
+  
+  A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of pending connection requests.
+- `net.ipv4.ip_local_port_range`: Selects the range of local ports the kernel can use. The example expands the port range. The default range is sufficient for many deployments.
+- `net.ipv4.tcp_rmem`: Selects the TCP read socket buffer size. `8 MiB` is likely more than enough for most use cases.
+  
+  Use a tool such as `ss` to check TCP buffer utilization and set a value for this parameter.
+- `net.ipv4.tcp_wmem`: Selects the TCP write socket buffer size. `8 MiB` is likely more than enough for most use cases.
+  
+  Use a tool such as `ss` to check TCP buffer utilization and set a value for this parameter.
 
 ## Compiler considerations
 
@@ -95,4 +89,4 @@ NGINX relies on [zlib](https://zlib.net/) for HTTP response compression when the
 
 You've now learned about different kernel, compiler, and library optimizations that you can make to tune NGINX performance.
 
-Next, you'll review the configuration for a static file server and learn about optimizations that you can make.
+Next, you'll review the configuration for a static file server and learn about optimizations that you can make.

content/learning-paths/servers-and-cloud-computing/nginx_tune/test_optimizations.md

@@ -1,5 +1,6 @@
 ---
 title: Test NGINX optimizations
+description: Build wrk and run repeatable load tests against NGINX workloads on Arm-based platforms to compare tuning results.
 weight: 6
 layout: "learningpathall"
 ---
@@ -47,7 +48,8 @@ You can also run `wrk` directly against NGINX file servers, or run `wrk` on the
 
 ### Run a wrk test
 
-The NGINX file servers need files to serve. If you are using the configuration files discussed in [Tune a static file server](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_static_file_server/) or [Tune a reverse proxy or API gateway](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_revprox_and_apigw/), run the following commands on each file server to create sample files. You do not need to create these files on reverse proxy or API gateway nodes because they do not serve files directly.
+The NGINX file servers need files to serve. If you're using the configuration files discussed in [Tune a static file server](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_static_file_server/) or [Tune a reverse proxy or API gateway](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_revprox_and_apigw/), run the following commands on each file server to create sample files:
+
 
 ```bash
 # Create 1 KB file in the reverse proxy use case directory
@@ -66,6 +68,8 @@ sudo cp /usr/share/nginx/html/5kb /usr/share/nginx/html/api_new
 sudo cp /usr/share/nginx/html/10kb /usr/share/nginx/html/api_new
 ```
 
+You don't need to create these files on reverse proxy or API gateway nodes because they don't serve files directly.
+
 Run the sample commands from the `wrk` build directory, or use the full path to the `wrk` binary.
 
 The following sample command tests a file server or reverse proxy. Select thread and connection values that load the NGINX server without causing connection, read, or write errors in `wrk` or NGINX. Because `wrk` does not use a fixed request-rate option, adjust `-t`, `-c`, and `-d` to scale load and keep the same values when comparing configurations.
@@ -86,4 +90,4 @@ The API gateway shown in [Tune a reverse proxy or API gateway](/learning-paths/s
 
 You've now used `wrk` to run an NGINX performance test.
 
-You can use the guidance in this Learning Path to optimize the performance of your NGINX workloads on Arm-based platforms.  
+You can use the guidance in this Learning Path to optimize the performance of your NGINX workloads on Arm-based platforms.  

content/learning-paths/servers-and-cloud-computing/nginx_tune/tune_revprox_and_apigw.md

@@ -1,5 +1,6 @@
 ---
-title: Tune a reverse proxy or API gateway for performance
+title: Tune an NGINX reverse proxy or API gateway 
+description: Tune NGINX reverse proxy and API gateway directives for Arm-based platforms so upstream keepalive, rewrites, and caching decisions match your workload.
 weight: 5
 layout: "learningpathall"
 ---
@@ -65,28 +66,23 @@ server {
 
 The following are performance-relevant directives that weren't discussed in the [static file server section](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_static_file_server/):
 
-- [`keepalive`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive):
-  - Controls the cache of idle connections to upstream servers.
-  - For NGINX 1.29.7 and later, upstream keepalive is enabled by default with a small cache. Set `keepalive` explicitly when you want to tune the upstream idle connection cache for your workload.
-  - For older NGINX versions, enable upstream keepalive with the `keepalive` directive. Also set [`proxy_http_version`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) to `1.1` and clear the `Connection` header with [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header).
-  - The value `1024` is a cache size for idle upstream connections per worker, not a total upstream connection limit. Keep this value small enough that upstream servers can still accept new connections.
-- [`rewrite`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#rewrite):
-  - Rewrites the old API path to the internal API path.
-  - Regular expression-heavy configurations can make PCRE performance more important, as discussed in [Kernel, compiler, and libraries](/learning-paths/servers-and-cloud-computing/nginx_tune/kernel_comp_lib/).
-- [`proxy_pass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass):
-  - Forwards matching requests to the upstream server group.
-  - Use the same upstream block for related locations when you want them to share the same upstream connection pool.
-- [`internal`](https://nginx.org/en/docs/http/ngx_http_core_module.html#internal) and [`limit_except`](https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_except):
-  - Included for request handling and access control, not as primary performance settings.
-- [`proxy_cache_path`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path):
-  - Not in the example configuration, but it's worth considering when responses can be cached by the reverse proxy or API gateway.
-  - When you use this directive, review [`proxy_cache_lock`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_lock) and [`proxy_cache_valid`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid).
-  - For more information, see the NGINX Admin Guide section on [content caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/).
-- NGINX variables:
-  - The example uses `$hostname` in `server_name`. For the full list of built-in variables, see the NGINX [variable index](https://nginx.org/en/docs/varindex.html) .
+- [`keepalive`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive): Controls the cache of idle connections to upstream servers. For NGINX 1.29.7 and later, upstream keepalive is enabled by default with a small cache. Set `keepalive` explicitly when you want to tune the upstream idle connection cache for your workload.
+
+  For older NGINX versions, enable upstream keepalive with the `keepalive` directive. Also set [`proxy_http_version`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) to `1.1` and clear the `Connection` header with [`proxy_set_header`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header).
+  
+  The value `1024` is a cache size for idle upstream connections per worker, not a total upstream connection limit. Keep this value small enough that upstream servers can still accept new connections.
+- [`rewrite`](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html#rewrite): Rewrites the old API path to the internal API path. Regular expression-heavy configurations can make PCRE performance more important, as discussed in [Kernel, compiler, and libraries](/learning-paths/servers-and-cloud-computing/nginx_tune/kernel_comp_lib/).
+- [`proxy_pass`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass): Forwards matching requests to the upstream server group. Use the same upstream block for related locations when you want them to share the same upstream connection pool.
+- [`internal`](https://nginx.org/en/docs/http/ngx_http_core_module.html#internal) and [`limit_except`](https://nginx.org/en/docs/http/ngx_http_core_module.html#limit_except): Included for request handling and access control, not as primary performance settings.
+- [`proxy_cache_path`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path): Not in the example configuration, but it's worth considering when responses can be cached by the reverse proxy or API gateway.
+  
+  When you use this directive, review [`proxy_cache_lock`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_lock) and [`proxy_cache_valid`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_valid).
+  
+  For more information, see the NGINX Admin Guide section on [content caching](https://docs.nginx.com/nginx/admin-guide/content-cache/content-caching/).
+- NGINX variables: The example uses `$hostname` in `server_name`. For the full list of built-in variables, see the NGINX [variable index](https://nginx.org/en/docs/varindex.html).
 
 ## What you've learned and what's next
 
 You've seen an example reverse proxy and API gateway configuration and learned about performance-relevant directives that you can optimize to tune NGINX performance. 
 
-Next, you'll test NGINX optimizations. 
+Next, you'll test NGINX optimizations.