Page Discussion History


Revision as of 07:46, 23 August 2013 by AndreiBelov (Talk | contribs)

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.



This module provides a filter which processes Server-Side Includes (SSI) in the input. The list of the supported commands for SSI is currently incomplete.


location / {
  ssi  on;



Syntax: ssi on | off
Default: off
Context: http
if in location

Enables SSI processing.

Note that when SSI is enabled the Last-Modified and Content-Length headers are not sent.


Syntax: ssi_silent_errors on | off
Default: off
Context: http

Doesn't output "[an error occurred while processing the directive] ", if an error occurs while processing the SSI.


Syntax: ssi_types mime-type ...
Default: text/html
Context: http

Enables SSI processing for MIME-types in addition to "text/html" types.


syntax: ssi_value_length length

default: ssi_value_length 256

context: http, server, location

Defines the allowed length of values for parameters used in SSI.

SSI Commands

Instruction format is the following:

  <!--# command parameter1=value parameter2=value ... parameterN=value -->

Note that the hash ('#') must immediately follow the two dashes ('--').

The supported SSI commands are listed below.


This command creates a block, which can be used as a silencer in command include. Inside the block there can be other SSI commands.

  • name — the name of the block. For example:
  <!--# block name="one" -->
  the silencer
  <!--# endblock -->


Assigns some configuration parameter for SSI.

  • errmsg — the line which is used as the error during SSI processing. By default, this string is used: "[an error occurred while processing the directive] "
  • timefmt — the time formatting string, as used in strftime(3). By default, this string is used:
  "%A, %d-%b-%Y %H:%M:%S %Z"

To include time in seconds use the format "%s" as well.


Print a variable.

  • var — the name of the variable
  • encoding — the escape of the variable, there are none, url, entity. Defaults to entity
  • default - if the variable is empty, display this string. Defaults to "none". Example:
  <!--# echo var="name" default="no" -->

is the same as

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

if / elif / else / endif

Conditionally include text or other directives. Usage:

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

Only one level of nesting is possible.

  • expr — the expression to evaluate. It can be a variable:
  <!--# if expr="$name" -->

A string comparison:

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

Or a regex match:

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

If there are variables in the text, they will have their values substituted.


Include a document from another source.

  • file — include a file, e.g.
  <!--# include file="footer.html" -->
  • virtual — include a request, e.g.
  <!--# include virtual="/remote/body.php?argument=value" -->

The target of "file" or "virtual" must be a location in the server configuration.

The distinction between "file" and "virtual" is mostly historical. "file" is the same as "virtual" with implied "wait" option. At one point the directives mirrored the Apache equivalents but now they are basically the same operation. Both can handle a URI and both can serve a static file.

Multiple requests will be issued in parallel. If you need them issued sequentially, use the "wait" option.

  • stub — The name of the block to use as a default if the request is empty or returns an error.
  <!--# block name="one" --> <!--# endblock -->
  <!--# include virtual="/remote/body.php?argument=value" stub="one" -->
  • wait — when set to yes, the rest of the SSI will not be evaluated until the current request is finished. Example:
  <!--# include virtual="/remote/body.php?argument=value" wait="yes" -->
  • set — when set to a variable name, the output of the SSI will not be sent to the output, instead the output is set to the variable. Example:
  <!--# include virtual="/remote/body.php?argument=value" set="body" -->


Assign a variable.

  • var — the variable.
  • value — its value. If it contains variable names, these will be evaluated.



The current time in the local timezone. The config option "timefmt" controls the format.


The current time in GMT. The config option "timefmt" controls the format.


Original Documentation