Substitutions Filter

The subs_filter directive does regex find-and-replace on response body content. nginx buffers the response, runs your patterns, and sends the modified result downstream. Common uses: injecting scripts into proxied HTML, rewriting absolute URLs in legacy apps, fixing hardcoded domains in third-party content, applying transforms across many endpoints without touching application code. The catch is memory. The response sits in a buffer while substitutions run, which adds latency and pressure on large responses. Use it where you need it, not everywhere.

• Inject analytics or monitoring scripts into proxied HTML at the proxy layer
• Rewrite absolute URLs in legacy or third-party proxied applications
• Fix hardcoded domain references without touching application code
• Apply content normalisation across many endpoints from one place

A starting point. Adjust to taste.

# Inside your location {} block:
# Rewrite old domain references in proxied content
subs_filter 'https://old-domain.example.com'
            'https://new-domain.example.com' g;

# Inject a script before </body>
subs_filter '</body>'
            '<script src="/analytics.js"></script></body>';

# Only apply to HTML responses
subs_filter_types text/html;

You'll need nginx from nginx.org configured first. These packages won't load on the distro nginx. Then add the Blendbyte repository if you haven't already:

sudo install -d -m 0755 /etc/apt/keyrings

curl -fsSL https://apt.blendbyte.net/nginx/blendbyte-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/blendbyte.gpg >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/blendbyte.gpg] https://apt.blendbyte.net/nginx $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/blendbyte.list

sudo apt update
sudo apt install nginx-module-substitutions

Most modules auto-enable on install. If yours didn't:

$ sudo ln -s /etc/nginx/modules-available/50-mod-substitutions.conf \
  /etc/nginx/modules-enabled/
$ sudo nginx -t && sudo systemctl reload nginx

This replaces libnginx-mod-http-subs-filter from the old Sury nginx repository. The package declares Replaces and Conflicts, so once your apt sources point at nginx.org and Blendbyte, a regular apt upgrade swaps it in. No manual cleanup.

Switching sources also moves you from Sury's nginx binary to nginx.org's. The migration guide walks through it in one go.

We package this from the upstream open-source project. If it's a bug in the module itself (not in our packaging), report it upstream at github.com/yaoweibin/ngx_http_substitutions_filter_module ↗