Skip to main content
Mapagam

Working with Content Modification

1. Using Sub Filter

Directive Description Values Default
sub_filter Defines the string to be replaced and the replacement string "search_string" "replacement_string" None
sub_filter_once Controls whether the replacement is applied only once per response on, off off
sub_filter_types Defines MIME types for which sub_filter is applied text/html, text/css, application/javascript text/html

Example: Basic sub_filter usage

location / {
    sub_filter "<title>" "<title>My Site";
    sub_filter_once on;
}

Example: Sub filter with multiple replacements

location / {
    sub_filter "old_text" "new_text";
    sub_filter "another_old" "another_new";
    sub_filter_once off;
}
Note: The sub_filter directive is applied to the response body and does not affect headers or other parts of the HTTP response.

2. Configuring Multiple Sub Filters

Filter Configuration Description
sub_filter sub_filter "old_text" "new_text" Replaces the first occurrence of old_text with new_text
sub_filter_once sub_filter_once on Ensures replacement happens only once per response
sub_filter_last_modified sub_filter_last_modified on Applies filter only if content is modified since last request

Example: Multiple Sub Filters Configuration

location / {
    sub_filter "old_text" "new_text";
    sub_filter "another_old" "another_new";
    sub_filter_once on;
}

3. Setting Sub Filter Types

Directive Values Description
sub_filter string Defines a string to be replaced in the response body.
sub_filter_types content-type Specifies the content types for which sub_filter should be applied.
sub_filter_once on | off If set to on, replaces only the first occurrence of the string.

Example: Basic sub_filter usage

location / {
    sub_filter "old_string" "new_string";
    sub_filter_once off;
}

Example: Using sub_filter_types

location / {
    sub_filter_types text/html application/json;
    sub_filter "<title>" "<title>Modified";
}

4. Using Addition Module

Directive Description Values
addition Enables content addition to responses on | off
addition_type Specifies the type of addition to perform text | html
addition_content Content to be added to the response String or file path

Example: Adding text to response

location / {
    addition on;
    addition_type text;
    addition_content "Added content";
}

Example: Adding HTML to response

location / {
    addition on;
    addition_type html;
    addition_content "<div>Additional HTML</div>";
}

5. Implementing SSI

Server Side Includes (SSI) allow you to embed dynamic content into static HTML pages. This feature is useful for including headers, footers, or other reusable components without requiring a full server-side language.

Directive Description Example
Includes the content of another file <!--#include file="header.html" -->
Includes content from a virtual path <!--#include virtual="footer.html" -->
Outputs the current date/time <!--#echo var="DATE_GMT" -->
Configures the time format <!--#config timefmt="%Y-%m-%d %H:%M" -->

Example: Basic SSI Include

<!--#include file="nav.html" -->
<h1>Welcome to My Site</h1>
<!--#include file="footer.html" -->

Example: Using Variables

<!--#config timefmt="%B %d, %Y" -->
<p>Today is <!--#echo var="DATE_GMT" --></p>
Note: SSI is disabled by default in Nginx. You must enable it using the ssi directive.
Warning: SSI can impact performance if overused. It's best to use it sparingly and for simple includes.

6. Configuring SSI Variables

Variable Description Example
$date_gmt Current date and time in GMT 1970-01-01 00:00:00
$document_root Root directory of the document /var/www/html
$host Host name from the request line or Host header example.com
$http_user_agent User agent string from the client request Mozilla/5.0...
$request_uri Original URI requested by the client /index.html?param=value
$server_name Name of the server as defined in the config nginx.example.com
$time_local Current date and time in local time zone 01/Jan/1970:00:00:00 +0000

Example: Using SSI Variables in Content

location / {
    ssi on;
    root /var/www/html;
}

location ~ \.shtml$ {
    ssi on;
}

Example: Inserting Date Using SSI Variable

<!--#echo var="date_gmt" -->

7. Using XSLT Module

Directive Description Values Notes
xslt_stylesheet Defines the XSLT stylesheet to be used for transformation path/to/stylesheet.xsl Can be used multiple times to define multiple stylesheets
xslt_param Sets a parameter to be passed to the XSLT stylesheet param_name=value Can be used multiple times to define multiple parameters
xslt_string_param Sets a string parameter to be passed to the XSLT stylesheet param_name=value Useful for dynamic content passing

Example: Basic XSLT Transformation

location /transformed {
    xslt_stylesheet /stylesheets/style.xsl;
    xslt_param "date" $date;
}
Note: The XSLT module requires the libxslt library to be installed on the system.
Warning: XSLT transformations can be CPU-intensive. Consider caching or limiting the use of complex transformations.

8. Implementing Charset Conversion

Directive Description Values
charset Sets the character set for the response utf-8, iso-8859-1, etc.
charset_map Defines a mapping between character sets Path to charset map file
source_charset Specifies the source character set utf-8, iso-8859-1
target_charset Specifies the target character set utf-8, iso-8859-1

Example: Setting charset for a location

location /api/ {
    charset utf-8;
    proxy_pass http://backend;
}

Example: Using charset_map

charset_map /etc/nginx/charset.map;

location / {
    charset utf-8;
    source_charset iso-8859-1;
    target_charset utf-8;
}

9. Configuring Content Substitution Patterns

Directive Description Values Notes
sub_filter Defines a string to be replaced in the response body string Can be used multiple times for different patterns
sub_filter_once Controls whether substitution is applied once or multiple times on, off Default is off
sub_filter_types Defines MIME types for which substitution is applied mime-type Defaults to text/html

Example: Basic content replacement

location / {
    sub_filter 'old_string' 'new_string';
    sub_filter_once on;
}

Example: Substitution in specific content types

location / {
    sub_filter_types text/html application/json;
    sub_filter 'example.com' 'newdomain.com';
}

10. Filtering Response Content

Directive Description Values Notes
proxy_pass Specifies the address of the proxied server http://backend Used in conjunction with content filtering modules
sub_filter Replaces a string in the response body <title> → <h1> Can be used for content modification
sub_filter_once Applies sub_filter only once per response on, off Default is off
sub_filter_types Defines MIME types to apply sub_filter to text/html, application/json Defaults to text/html

Example: Using sub_filter to modify content

location / {
    proxy_pass http://backend;
    sub_filter "<title>" "<h1>";
    sub_filter_once on;
}
Note: The sub_filter directive is part of the ngx_http_sub_module, which must be enabled for content filtering.
Warning: Content filtering can impact performance if not configured properly. Ensure that filters are applied only to necessary content types.

11. Adding Headers and Footers

Directive Description Example
add_header Adds a custom header to the response add_header X-Custom-Header "value";
add_header Can be used to set cache control headers add_header Cache-Control "public, max-age=31536000";
more_set_headers Part of the ngx_http_headers_more_module, allows setting headers with regex patterns more_set_headers -s 404 "X-Status: Not Found";

Example: Adding a Custom Header

location / {
    add_header X-Content-Type-Options "nosniff";
    add_header X-Frame-Options "DENY";
}

Example: Adding Headers Conditionally

location /api/ {
    add_header Access-Control-Allow-Origin "*";
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
}

12. Modifying Upstream Responses

Directive Description Values Notes
proxy_intercept_errors Intercepts error responses from upstream on | off Default: off
error_page Defines custom error pages for specific status codes status_code url Can be used with proxy_intercept_errors
post_action Executes a directive after the main request is processed url Can be used to modify response content or redirect

Example: Intercepting and Modifying Error Responses

location /api/ {
    proxy_pass http://backend;
    proxy_intercept_errors on;
    error_page 502 503 /custom_error.html;
}

Example: Modifying Response with post_action

location / {
    proxy_pass http://backend;
    post_action /modify_response;
}

location /modify_response {
    # Modify or log response
    return 200 "Response modified";
}

Was this article helpful?

Related Cheat Sheets