Module ngx_http_ssi_module

The ngx_http_ssi_module module is a filter that processes SSI (Server Side Includes) commands in responses passing through it. Currently, the list of supported SSI commands is incomplete.

Example Configuration

location / {
    ssi on;
    ...
}

Directives

ssi off;

Enables or disables processing of SSI commands in responses.

ssi_silent_errors off;

Allows to suppress output of the string “[an error occurred while processing the directive]” if an error occurred during SSI processing.

ssi_types text/html;

Enables processing of SSI commands in responses with the specified MIME types in addition to “text/html”. The special value “*” matches any MIME type (0.8.29).

SSI Commands

SSI commands have the following generic format:

<!--# command parameter1=value1 parameter2=value2 ... -->

The following commands are supported:

block

Defines a block that can be used as a stub in the include command. The block can contain other SSI commands. The command has the following parameter:

name

block name.

Example:

<!--# block name="one" -->
stub
<!--# endblock -->

config

Sets some parameters used during SSI processing, namely:

errmsg

a string that is output if an error occurs during SSI processing. By default, the following string is output:

[an error occurred while processing the directive]

timefmt

a format string passed to the strftime() function used to output date and time. By default, the following format is used:

"%A, %d-%b-%Y %H:%M:%S %Z"

The “%s” format is suitable to output time in seconds.

echo

Outputs the value of a variable. The command has the following parameters:

var

variable name.

encoding

encoding method. Possible values include none, url, and entity. By default, entity is used.

default

non-standard parameter that sets a string to be output if a variable is undefined. By default, “none” is output. The command

<!--# echo var="name" default="no" -->

replaces the following sequence of commands:

<!--# if expr="$name" --><!--# echo var="name" --><!--#
       else -->no<!--# endif -->

if

Performs a conditional inclusion. The following commands are supported:

<!--# if expr="..." -->
...
<!--# elif expr="..." -->
...
<!--# else -->
...
<!--# endif -->

Only one level of nesting is currently supported. The command has the following parameter:

expr

expression. An expression can be:

• variable existence check:

  <!--# if expr="$name" -->
  

• comparison of a variable with a text:

  <!--# if expr="$name = text" -->
  <!--# if expr="$name != text" -->
  

• comparison of a variable with a regular expression:

  <!--# if expr="$name = /text/" -->
  <!--# if expr="$name != /text/" -->
  

If a text contains variables, their values are substituted. A regular expression can contain positional and named captures that can later be used through variables, for example:

<!--# if expr="$name = /(.+)@(?P<domain>.+)/" -->
    <!--# echo var="1" -->
    <!--# echo var="domain" -->
<!--# endif -->

include

Includes the result of another request into a response. The command has the following parameters:

file

specifies an included file, for example:

<!--# include file="footer.html" -->

virtual

specifies an included request, for example:

<!--# include virtual="/remote/body.php?argument=value" -->

Several requests specified on one page and processed by proxied or FastCGI servers run in parallel. If sequential processing is desired, the wait parameter should be used.

stub

non-standard parameter that names the block whose content will be output if an included request results in an empty body or if an error occurs during request processing, for example:

<!--# block name="one" -->&nbsp;<!--# endblock -->
<!--# include virtual="/remote/body.php?argument=value" stub="one" -->

The replacement block content is processed in the included request context.

wait

non-standard parameter that instructs to wait for a request to fully complete before continuing with SSI processing, for example:

<!--# include virtual="/remote/body.php?argument=value" wait="yes" -->

set

non-standard parameter that instructs to write a successful result of request processing to the specified variable, for example:

<!--# include virtual="/remote/body.php?argument=value" set="one" -->

It should be noted that only the results of responses obtained using the ngx_http_proxy_module and ngx_http_memcached_module modules can be written into variables.

set

Sets a value of a variable. The command has the following parameters:

var

variable name.

value

variable value. If an assigned value contains variables, their values are substituted.

Embedded Variables

The ngx_http_ssi_module module supports two embedded variables:

$date_local

current time in local time zone. The format is set by the config command with the timefmt parameter.

$date_gmt

current time in GMT. The format is set by the config command with the timefmt parameter.