Content

Substitutions Filter

Regex find-and-replace in HTTP responses. A scalpel, not a chainsaw.

nginx-module-substitutions

Install

Make sure you have the official nginx.org repository configured first. These packages require nginx from nginx.org, not the distro-bundled version.

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

Then install this module:

$ sudo apt install nginx-module-substitutions

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

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

What it does

The substitutions filter module adds a subs_filter directive that performs regex find-and-replace on buffered response body content. nginx buffers the response, runs your substitution patterns, and forwards the modified result. Common uses: injecting tracking snippets into proxied HTML, rewriting absolute URLs in legacy applications, fixing hardcoded domain references in third-party content, applying content transforms across many endpoints without changing application code. The tradeoff is memory. The response is buffered while substitutions run, adding latency and memory pressure on large responses. Use it deliberately, not as a blanket config.

When to use it

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

Configuration

A starting-point configuration. Adjust to your setup.

# 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;

Replacing a Sury package?

This module replaces libnginx-mod-http-subs-filter from the Sury nginx repository. The package declares Replaces and Conflicts so apt handles the swap automatically in one transaction.

# If you were using Sury, this upgrades in place:
sudo apt install nginx-module-substitutions

See the full migration guide for the complete Sury-to-Blendbyte migration steps.

Upstream project

This module is packaged from the upstream open-source project. Bug reports about module behaviour (not packaging) should go upstream.

https://github.com/yaoweibin/ngx_http_substitutions_filter_module ↗

← All modules