nginx

Module ngx_http_ssi_module


english
русский

简体中文
עברית
日本語
türkçe

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
This translation may be out of date. Check the English version for recent changes.
Example Configuration
Directives
     ssi
     ssi_silent_errors
     ssi_types
SSI Commands
Embedded Variables

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

syntax: ssi on | off;
default:
ssi off;
context: http, server, location, if in location

Enables or disables processing of SSI commands in responses.

syntax: ssi_silent_errors on | off;
default:
ssi_silent_errors off;
context: http, server, location

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

syntax: ssi_types mime-type ...;
default:
ssi_types text/html;
context: http, server, location

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.