FAQ

Page Discussion History

HttpSsiModule

Revision as of 11:13, 10 April 2014 by Thresh (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


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

Contents

Synopsis

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.

Example

location / {
  ssi  on;
}

Directives

ssi

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


Enables SSI processing.

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

ssi_silent_errors

Syntax: ssi_silent_errors on | off
Default: off
Context: http
server
location
Reference:ssi_silent_errors


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

ssi_types

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


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


ssi_value_length

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.

block

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

config

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.

echo

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

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" -->

set

Assign a variable.

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

Variables

$date_local

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

$date_gmt

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

References

Original Documentation