<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_ssi_module"
        link="/en/docs/http/ngx_http_ssi_module.html"
        lang="en"
        rev="12">

<section id="summary">

<para>
The <literal>ngx_http_ssi_module</literal> 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.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
location / {
    ssi on;
    ...
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="ssi">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Enables or disables processing of SSI commands in responses.
</para>

</directive>


<directive name="ssi_last_modified">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.1</appeared-in>

<para>
Allows preserving the <header>Last-Modified</header> header field
from the original response during SSI processing
to facilitate response caching.
</para>

<para>
By default, the header field is removed as contents of the response
are modified during processing and may contain dynamically generated elements
or parts that are changed independently of the original response.
</para>

</directive>


<directive name="ssi_min_file_chunk">
<syntax><literal>size</literal></syntax>
<default>1k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the minimum <value>size</value> for parts of a response stored on disk,
starting from which it makes sense to send them using
<link doc="ngx_http_core_module.xml" id="sendfile"/>.
</para>

</directive>


<directive name="ssi_silent_errors">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
If enabled, suppresses the output of the
“<literal>[an error occurred while processing the directive]</literal>”
string if an error occurred during SSI processing.
</para>

</directive>


<directive name="ssi_types">
<syntax><value>mime-type</value> ...</syntax>
<default>text/html</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="ssi_value_length">
<syntax><value>length</value></syntax>
<default>256</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Sets the maximum length of parameter values in SSI commands.
</para>

</directive>

</section>


<section id="commands" name="SSI Commands">

<para>
SSI commands have the following generic format:
<example>
&lt;!--# command parameter1=value1 parameter2=value2 ... --&gt;
</example>
</para>

<para>
The following commands are supported:
<list type="tag">

<tag-name><literal>block</literal></tag-name>
<tag-desc>
Defines a block that can be used as a stub
in the <literal>include</literal> command.
The block can contain other SSI commands.
The command has the following parameter:

<list type="tag">
<tag-name><literal>name</literal></tag-name>
<tag-desc>
block name.
</tag-desc>
</list>

Example:
<example>
&lt;!--# block name="one" --&gt;
stub
&lt;!--# endblock --&gt;
</example>

</tag-desc>


<tag-name><literal>config</literal></tag-name>
<tag-desc>
Sets some parameters used during SSI processing, namely:

<list type="tag">
<tag-name><literal>errmsg</literal></tag-name>
<tag-desc>
a string that is output if an error occurs during SSI processing.
By default, the following string is output:
<example>
[an error occurred while processing the directive]
</example>
</tag-desc>

<tag-name><literal>timefmt</literal></tag-name>
<tag-desc>
a format string passed to the <c-func>strftime</c-func> function
used to output date and time.
By default, the following format is used:
<example>
"%A, %d-%b-%Y %H:%M:%S %Z"
</example>
The “<literal>%s</literal>” format is suitable to output time in seconds.
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>echo</literal></tag-name>
<tag-desc>
Outputs the value of a variable.
The command has the following parameters:

<list type="tag">
<tag-name><literal>var</literal></tag-name>
<tag-desc>
the variable name.
</tag-desc>

<tag-name><literal>encoding</literal></tag-name>
<tag-desc>
the encoding method.
Possible values include <literal>none</literal>, <literal>url</literal>, and
<literal>entity</literal>.
By default, <literal>entity</literal> is used.
</tag-desc>

<tag-name><literal>default</literal></tag-name>
<tag-desc>
a non-standard parameter that sets a string to be output
if a variable is undefined.
By default, “<literal>(none)</literal>” is output.
The command
<example>
&lt;!--# echo var="name" default="<emphasis>no</emphasis>" --&gt;
</example>
replaces the following sequence of commands:
<example>
&lt;!--# if expr="$name" --&gt;&lt;!--# echo var="name" --&gt;&lt;!--#
       else --&gt;<emphasis>no</emphasis>&lt;!--# endif --&gt;
</example>
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>if</literal></tag-name>
<tag-desc>
Performs a conditional inclusion.
The following commands are supported:
<example>
&lt;!--# if expr="..." --&gt;
...
&lt;!--# elif expr="..." --&gt;
...
&lt;!--# else --&gt;
...
&lt;!--# endif --&gt;
</example>
Only one level of nesting is currently supported.
The command has the following parameter:

<list type="tag">
<tag-name><literal>expr</literal></tag-name>
<tag-desc>
expression.
An expression can be:

<list type="bullet">

<listitem>
variable existence check:
<example>
&lt;!--# if expr="$name" --&gt;
</example>
</listitem>

<listitem>
comparison of a variable with a text:
<example>
&lt;!--# if expr="$name = <value>text</value>" --&gt;
&lt;!--# if expr="$name != <value>text</value>" --&gt;
</example>
</listitem>

<listitem>
comparison of a variable with a regular expression:
<example>
&lt;!--# if expr="$name = /<value>text</value>/" --&gt;
&lt;!--# if expr="$name != /<value>text</value>/" --&gt;
</example>
</listitem>
</list>

If a <value>text</value> contains variables,
their values are substituted.
A regular expression can contain positional and named captures
that can later be used through variables, for example:
<example>
&lt;!--# if expr="$name = /(.+)@(?P&lt;domain&gt;.+)/" --&gt;
    &lt;!--# echo var="1" --&gt;
    &lt;!--# echo var="domain" --&gt;
&lt;!--# endif --&gt;
</example>
</tag-desc>
</list>

</tag-desc>


<tag-name><literal>include</literal></tag-name>
<tag-desc>
Includes the result of another request into a response.
The command has the following parameters:

<list type="tag">
<tag-name><literal>file</literal></tag-name>
<tag-desc>
specifies an included file, for example:
<example>
&lt;!--# include file="footer.html" --&gt;
</example>
</tag-desc>

<tag-name><literal>virtual</literal></tag-name>
<tag-desc>
specifies an included request, for example:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" --&gt;
</example>
Several requests specified on one page and processed by proxied or
FastCGI/uwsgi/SCGI/gRPC servers run in parallel.
If sequential processing is desired, the <literal>wait</literal>
parameter should be used.
</tag-desc>

<tag-name><literal>stub</literal></tag-name>
<tag-desc>
a non-standard parameter that names the block whose
content will be output if the included request results in an empty
body or if an error occurs during the request processing, for example:
<example>
&lt;!--# block name="one" --&gt;&amp;nbsp;&lt;!--# endblock --&gt;
&lt;!--# include virtual="/remote/body.php?argument=value" stub="one" --&gt;
</example>
The replacement block content is processed in the included request context.
</tag-desc>

<tag-name><literal>wait</literal></tag-name>
<tag-desc>
a non-standard parameter that instructs to wait for a request to fully
complete before continuing with SSI processing, for example:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" wait="yes" --&gt;
</example>
</tag-desc>

<tag-name id="ssi_include_set"><literal>set</literal></tag-name>
<tag-desc>
a non-standard parameter that instructs to write a successful result
of request processing to the specified variable,
for example:
<example>
&lt;!--# include virtual="/remote/body.php?argument=value" set="one" --&gt;
</example>
The maximum size of the response is set by the
<link doc="ngx_http_core_module.xml" id="subrequest_output_buffer_size"/>
directive (1.13.10):
<example>
location /remote/ {
    subrequest_output_buffer_size 64k;
    ...
}
</example>
Prior to version 1.13.10, only the results of responses obtained using the
<link doc="ngx_http_proxy_module.xml">ngx_http_proxy_module</link>,
<link doc="ngx_http_memcached_module.xml">ngx_http_memcached_module</link>,
<link doc="ngx_http_fastcgi_module.xml">ngx_http_fastcgi_module</link> (1.5.6),
<link doc="ngx_http_uwsgi_module.xml">ngx_http_uwsgi_module</link> (1.5.6),
and <link doc="ngx_http_scgi_module.xml">ngx_http_scgi_module</link> (1.5.6)
modules could be written into variables.
The maximum size of the response was set with the
<link doc="ngx_http_proxy_module.xml" id="proxy_buffer_size"/>,
<link doc="ngx_http_memcached_module.xml" id="memcached_buffer_size"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_buffer_size"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_buffer_size"/>,
and <link doc="ngx_http_scgi_module.xml" id="scgi_buffer_size"/>
directives.
</tag-desc>

</list>

</tag-desc>


<tag-name><literal>set</literal></tag-name>
<tag-desc>
Sets a value of a variable.
The command has the following parameters:

<list type="tag">
<tag-name><literal>var</literal></tag-name>
<tag-desc>
the variable name.
</tag-desc>

<tag-name><literal>value</literal></tag-name>
<tag-desc>
the variable value.
If an assigned value contains variables,
their values are substituted.
</tag-desc>
</list>

</tag-desc>

</list>
</para>

</section>


<section id="variables" name="Embedded Variables">

<para>
The <literal>ngx_http_ssi_module</literal> module supports
two embedded variables:
<list type="tag">

<tag-name id="var_date_local"><var>$date_local</var></tag-name>
<tag-desc>
current time in the local time zone.
The format is set by the <literal>config</literal> command
with the <literal>timefmt</literal> parameter.
</tag-desc>

<tag-name id="var_date_gmt"><var>$date_gmt</var></tag-name>
<tag-desc>
current time in GMT.
The format is set by the <literal>config</literal> command
with the <literal>timefmt</literal> parameter.
</tag-desc>

</list>
</para>

</section>

</module>