Content

Substitutions Filter

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

nginx-module-substitutions

Install

You'll need nginx from nginx.org configured first. These packages won't load on the distro nginx.

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:

$ 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 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.

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

Replacing a Sury package?

This replaces libnginx-mod-http-subs-filter from the old Sury nginx repository. The package declares Replaces and Conflicts so apt handles the swap in one transaction. No manual cleanup needed.

# 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

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.

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

← All modules