From e74015064259fc980b30df1d598015febbca3ee4 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 15 Oct 2026 11:06:54 -0400 Subject: [PATCH 1/3] adding Custom NGINX info provided by Jacob. --- docs/howto_custom_nginx.md | 60 ++++++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 61 insertions(+) create mode 100644 docs/howto_custom_nginx.md diff --git a/docs/howto_custom_nginx.md b/docs/howto_custom_nginx.md new file mode 100644 index 0000000000..05d3cdc4a7 --- /dev/null +++ b/docs/howto_custom_nginx.md @@ -0,0 +1,60 @@ +--- +title: Add Custom NGINX Configuration +sidebar_label: Add Custom NGINX Configuration +--- + +Custom NGINX directives may be needed to support deployment-specific requirements or integrations without modifying the SSR-managed `nginx.conf` file. For example, custom directives can be used to integrate external authentication services such as CAC/PIV, add request handling behavior, or apply other supported NGINX settings. + +Use `/etc/nginx/default.d/` to add persistent custom NGINX directives to an SSR Conductor. + +Do not modify `/etc/nginx/nginx.conf` directly. SSR manages this file and may regenerate it during system startup or other operations. + +## Add the Configuration + +1. Create a `.conf` file in `/etc/nginx/default.d/` containing only the required NGINX directives. Do not add a `server` block. For example: + + ``` + sudo tee /etc/nginx/default.d/zz-custom.conf >/dev/null <<'EOF' + # Custom NGINX directives + auth_request /oauth2/auth; + error_page 401 = /oauth2/sign_in; + auth_request_set $auth_user $upstream_http_x_auth_request_user; + EOF + ``` + +2. Validate the configuration: + + ``` + sudo nginx -t + ``` + +3. If validation succeeds, reload NGINX: + + ``` + sudo systemctl reload nginx + ``` + +4. Confirm that the custom file is included: + + ``` + sudo nginx -T 2>&1 | grep -n "zz-custom.conf" + ``` + +## Remove the Configuration + +1. Remove the custom file: + + ``` + sudo rm -f /etc/nginx/default.d/zz-custom.conf + ``` + +2. Validate and reload NGINX: + + ``` + sudo nginx -t + sudo systemctl reload nginx + ``` + +:::note +If `nginx -t` reports an error, review the custom directives for invalid syntax, unsupported directives, or an incorrect configuration context. +::: diff --git a/sidebars.js b/sidebars.js index a5b63f73db..1eff00626f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -342,6 +342,7 @@ module.exports = { "config_in-memory_metrics", "howto_ms365", "howto_extend_gui_nav", + "howto_custom_nginx", ], }, { From 8276d29122dc705a73d2daa7027e83ac78e7dcc9 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 15 Oct 2026 14:55:49 -0400 Subject: [PATCH 2/3] adding config to preserve custom nginx file --- docs/howto_custom_nginx.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/howto_custom_nginx.md b/docs/howto_custom_nginx.md index 05d3cdc4a7..e532a0ebbe 100644 --- a/docs/howto_custom_nginx.md +++ b/docs/howto_custom_nginx.md @@ -40,6 +40,22 @@ Do not modify `/etc/nginx/nginx.conf` directly. SSR manages this file and may re sudo nginx -T 2>&1 | grep -n "zz-custom.conf" ``` +### Preserving Custom Files + +To preserve custom NGINX files across image-based upgrades, use the following config to transfer your file. + +``` +# /etc/ssr-upgrade/data-transfer.d/90-custom-nginx.yml +version: "2.1" +data: + - dataset: Custom NGINX configuration + operations: + - upgrade + - reinstall + files: + - /etc/nginx/default.d/zz-custom.conf +``` + ## Remove the Configuration 1. Remove the custom file: From 038d128981718b67bbdcaf49a926581af2f65e31 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 16 Oct 2026 09:37:44 -0400 Subject: [PATCH 3/3] updating instructions with info for saving the custom file. --- docs/howto_custom_nginx.md | 39 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/docs/howto_custom_nginx.md b/docs/howto_custom_nginx.md index e532a0ebbe..2e8b76b817 100644 --- a/docs/howto_custom_nginx.md +++ b/docs/howto_custom_nginx.md @@ -13,49 +13,46 @@ Do not modify `/etc/nginx/nginx.conf` directly. SSR manages this file and may re 1. Create a `.conf` file in `/etc/nginx/default.d/` containing only the required NGINX directives. Do not add a `server` block. For example: - ``` +``` sudo tee /etc/nginx/default.d/zz-custom.conf >/dev/null <<'EOF' # Custom NGINX directives auth_request /oauth2/auth; error_page 401 = /oauth2/sign_in; auth_request_set $auth_user $upstream_http_x_auth_request_user; EOF - ``` +``` +2. To preserve your custom NGINX file across image-based upgrades, create a data-transfer configuration file in `/etc/ssr-upgrade/data-transfer.d/`. For example: -2. Validate the configuration: +``` + sudo tee /etc/ssr-upgrade/data-transfer.d/90-custom-nginx.yml >/dev/null <<'EOF' + version: "2.1" + data: + - dataset: Custom NGINX configuration + operations: + - upgrade + - reinstall + files: + - /etc/nginx/default.d/zz-custom.conf + EOF +``` +3. Validate the configuration: ``` sudo nginx -t ``` -3. If validation succeeds, reload NGINX: +4. If validation succeeds, reload NGINX: ``` sudo systemctl reload nginx ``` -4. Confirm that the custom file is included: +5. Confirm that the custom file is included: ``` sudo nginx -T 2>&1 | grep -n "zz-custom.conf" ``` -### Preserving Custom Files - -To preserve custom NGINX files across image-based upgrades, use the following config to transfer your file. - -``` -# /etc/ssr-upgrade/data-transfer.d/90-custom-nginx.yml -version: "2.1" -data: - - dataset: Custom NGINX configuration - operations: - - upgrade - - reinstall - files: - - /etc/nginx/default.d/zz-custom.conf -``` - ## Remove the Configuration 1. Remove the custom file: