granicus.if.org Git - apache/blob - docs/manual/mod/mod_include.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_include - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Module mod_include</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
  30 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
  31 </div>
  32 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Server-parsed html documents (Server Side Includes)</td></tr>
  33 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  34 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>include_module</td></tr>
  35 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_include.c</td></tr></table>
  36 <h3>Summary</h3>
  37
  38     <p>This module provides a filter which will process files
  39     before they are sent to the client. The processing is
  40     controlled by specially formatted SGML comments, referred to as
  41     <dfn>elements</dfn>. These elements allow conditional text, the
  42     inclusion of other files or programs, as well as the setting and
  43     printing of environment variables.</p>
  44 </div>
  45 <div id="quickview"><h3>Topics</h3>
  46 <ul id="topics">
  47 <li><img alt="" src="../images/down.gif" /> <a href="#enabling">Enabling Server-Side Includes</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#pathinfo">PATH_INFO with Server Side Includes</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#elements">Available Elements</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#includevars">Include Variables</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#substitution">Variable Substitution</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#flowctrl">Flow Control Elements</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#legacyexpr">Legacy expression syntax</a></li>
  54 </ul><h3 class="directives">Directives</h3>
  55 <ul id="toc">
  56 <li><img alt="" src="../images/down.gif" /> <a href="#ssiendtag">SSIEndTag</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#ssierrormsg">SSIErrorMsg</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#ssietag">SSIETag</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#ssilastmodified">SSILastModified</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#ssilegacyexprparser">SSILegacyExprParser</a></li>
  61 <li><img alt="" src="../images/down.gif" /> <a href="#ssistarttag">SSIStartTag</a></li>
  62 <li><img alt="" src="../images/down.gif" /> <a href="#ssitimeformat">SSITimeFormat</a></li>
  63 <li><img alt="" src="../images/down.gif" /> <a href="#ssiundefinedecho">SSIUndefinedEcho</a></li>
  64 <li><img alt="" src="../images/down.gif" /> <a href="#xbithack">XBitHack</a></li>
  65 </ul>
  66 <h3>See also</h3>
  67 <ul class="seealso">
  68 <li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li>
  69 <li><code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code></li>
  70 <li><a href="../filter.html">Filters</a></li>
  71 <li><a href="../howto/ssi.html">SSI Tutorial</a></li>
  72 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  73 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  74 <div class="section">
  75 <h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></h2>
  76
  77
  78     <p>Server Side Includes are implemented by the
  79     <code>INCLUDES</code> <a href="../filter.html">filter</a>. If
  80     documents containing server-side include directives are given
  81     the extension .shtml, the following directives will make Apache
  82     parse them and assign the resulting document the mime type of
  83     <code>text/html</code>:</p>
  84
  85     <pre class="prettyprint lang-config">AddType text/html .shtml
  86 AddOutputFilter INCLUDES .shtml</pre>
  87
  88
  89     <p>The following directive must be given for the directories
  90     containing the shtml files (typically in a
  91     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section,
  92     but this directive is also valid in <code>.htaccess</code> files if
  93     <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
  94     is set):</p>
  95
  96     <pre class="prettyprint lang-config">Options +Includes</pre>
  97
  98
  99     <p>For backwards compatibility, the <code>server-parsed</code>
 100     <a href="../handler.html">handler</a> also activates the
 101     INCLUDES filter. As well, Apache will activate the INCLUDES
 102     filter for any document with mime type
 103     <code>text/x-server-parsed-html</code> or
 104     <code>text/x-server-parsed-html3</code> (and the resulting
 105     output will have the mime type <code>text/html</code>).</p>
 106
 107     <p>For more information, see our <a href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
 108 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 109 <div class="section">
 110 <h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
 111
 112
 113     <p>Files processed for server-side includes no longer accept
 114     requests with <code>PATH_INFO</code> (trailing pathname information)
 115     by default.  You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
 116     configure the server to accept requests with <code>PATH_INFO</code>.</p>
 117 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 118 <div class="section">
 119 <h2><a name="elements" id="elements">Available Elements</a></h2>
 120     <p>The document is parsed as an HTML document, with special
 121     commands embedded as SGML comments. A command has the syntax: </p>
 122
 123     <div class="example"><p><code>
 124       &lt;!--#<var>element</var> <var>attribute</var>=<var>value</var>
 125       <var>attribute</var>=<var>value</var> ... --&gt;
 126     </code></p></div>
 127
 128     <p>The value will often be enclosed in double quotes, but single
 129     quotes (<code>'</code>) and backticks (<code>`</code>) are also
 130     possible. Many commands only allow a single attribute-value pair.
 131     Note that the comment terminator (<code>--&gt;</code>) should be
 132     preceded by whitespace to ensure that it isn't considered part of
 133     an SSI token. Note that the leading <code>&lt;!--#</code> is <em>one</em>
 134     token and may not contain any whitespaces.</p>
 135
 136     <p>The allowed elements are listed in the following table:</p>
 137
 138     <table class="bordered">
 139     <tr><th>Element</th><th>Description</th></tr>
 140     <tr><td><code><a href="#element.config">config</a></code></td>
 141         <td>configure output formats</td></tr>
 142     <tr><td><code><a href="#element.echo">echo</a></code></td>
 143         <td>print variables</td></tr>
 144     <tr><td><code><a href="#element.exec">exec</a></code></td>
 145         <td>execute external programs</td></tr>
 146     <tr><td><code><a href="#element.fsize">fsize</a></code></td>
 147         <td>print size of a file</td></tr>
 148     <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
 149         <td>print last modification time of a file</td></tr>
 150     <tr><td><code><a href="#element.include">include</a></code></td>
 151         <td>include a file</td></tr>
 152     <tr><td><code><a href="#element.printenv">printenv</a></code></td>
 153         <td>print all available variables</td></tr>
 154     <tr><td><code><a href="#element.set">set</a></code></td>
 155         <td>set a value of a variable</td></tr>
 156     </table>
 157
 158     <p>SSI elements may be defined by modules other than
 159     <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>. In fact, the <code><a href="#element.exec">exec</a></code> element is provided by
 160     <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
 161     module is loaded.</p>
 162
 163     <h3><a name="element.config" id="element.config">The config Element</a></h3>
 164       <p>This command controls various aspects of the parsing. The
 165       valid attributes are:</p>
 166
 167       <dl>
 168       <dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
 169       <dd><p>The value is a message that is sent back to the
 170       client if the <code><a href="#element.echo">echo</a></code> element
 171       attempts to echo an undefined variable. This overrides any <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directives.</p>
 172
 173       <div class="example"><p><code>
 174         &lt;!--#config echomsg="[Value Undefined]" --&gt;
 175       </code></p></div>
 176       </dd>
 177
 178       <dt><code>errmsg</code></dt>
 179       <dd><p>The value is a message that is sent back to the
 180       client if an error occurs while parsing the
 181       document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</p>
 182
 183       <div class="example"><p><code>
 184        &lt;!--#config errmsg="[Oops, something broke.]" --&gt;
 185       </code></p></div>
 186       </dd>
 187
 188       <dt><code>sizefmt</code></dt>
 189       <dd><p>The value sets the format to be used when displaying
 190       the size of a file. Valid values are <code>bytes</code>
 191       for a count in bytes, or <code>abbrev</code> for a count
 192       in Kb or Mb as appropriate, for example a size of 1024 bytes
 193       will be printed as "1K".</p>
 194
 195       <div class="example"><p><code>
 196       &lt;!--#config sizefmt="abbrev" --&gt;
 197       </code></p></div>
 198
 199       </dd>
 200
 201       <dt><code>timefmt</code></dt>
 202       <dd><p>The value is a string to be used by the
 203       <code>strftime(3)</code> library routine when printing
 204       dates.</p>
 205
 206       <div class="example"><p><code>
 207       &lt;!--#config timefmt=""%R, %B %d, %Y"" --&gt;
 208       </code></p></div>
 209
 210       </dd>
 211       </dl>
 212
 213
 214     <h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
 215       <p>This command prints one of the <a href="#includevars">include
 216       variables</a> defined below. If the variable is unset, the result is
 217       determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
 218       subject to the currently configured <code>timefmt</code>.</p>
 219
 220       <p>Attributes:</p>
 221
 222       <dl>
 223       <dt><code>var</code></dt>
 224       <dd>The value is the name of the variable to print.</dd>
 225
 226       <dt><code>decoding</code></dt>
 227       <dd><p>Specifies whether Apache should strip an encoding from
 228       the variable before processing the variable further. The default
 229       is <code>none</code>, where no decoding will be done. If set to
 230       <code>url</code>, then URL decoding (also known as %-encoding;
 231       this is appropriate for use within URLs in links, etc.) will be
 232       performed. If set to <code>urlencoded</code>,
 233       application/x-www-form-urlencoded compatible encoding (found in
 234       query strings) will be stripped. If set to <code>base64</code>,
 235       base64 will be decoded, and if set to <code>entity</code>, HTML
 236       entity encoding will be stripped. Decoding is done prior to any
 237       further encoding on the variable. Multiple encodings can be
 238       stripped by specifying more than one comma separated encoding.
 239       The decoding setting will remain in effect until the next decoding
 240       attribute is encountered, or the element ends.</p>
 241
 242       <p>The <code>decoding</code> attribute must <em>precede</em> the
 243       corresponding <code>var</code> attribute to be effective.</p>
 244       </dd>
 245
 246       <dt><code>encoding</code></dt>
 247       <dd><p>Specifies how Apache should encode special characters
 248       contained in the variable before outputting them. If set
 249       to <code>none</code>, no encoding will be done. If set to
 250       <code>url</code>, then URL encoding (also known as %-encoding;
 251       this is appropriate for use within URLs in links, etc.) will be
 252       performed. If set to <code>urlencoded</code>,
 253       application/x-www-form-urlencoded compatible encoding will be
 254       performed instead, and should be used with query strings. If set
 255       to <code>base64</code>, base64 encoding will be performed. At
 256       the start of an <code>echo</code> element, the default is set to
 257       <code>entity</code>, resulting in entity encoding (which is
 258       appropriate in the context of a block-level HTML element,
 259       <em>e.g.</em> a paragraph of text). This can be changed by adding
 260       an <code>encoding</code> attribute, which will remain in effect
 261       until the next <code>encoding</code> attribute is encountered or
 262       the element ends, whichever comes first.</p>
 263
 264       <p>The <code>encoding</code> attribute must <em>precede</em> the
 265       corresponding <code>var</code> attribute to be effective.</p>
 266
 267       <div class="warning">
 268         In order to avoid cross-site scripting issues, you should
 269         <em>always</em> encode user supplied data.
 270       </div>
 271
 272       <div class="example"><h3>Example</h3><p><code>
 273         &lt;!--#echo encoding="entity" var="QUERY_STRING" --&gt;
 274       </code></p></div>
 275       </dd>
 276       </dl>
 277
 278
 279     <h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
 280       <p>The <code>exec</code> command executes a given shell command or
 281       CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
 282       in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 283       <code>IncludesNOEXEC</code> is set, this command is completely
 284       disabled. The valid attributes are:</p>
 285
 286       <dl>
 287       <dt><code>cgi</code></dt>
 288       <dd><p>The value specifies a (%-encoded) URL-path to
 289       the CGI script. If the path does not begin with a slash (/),
 290       then it is taken to be relative to the current
 291       document. The document referenced by this path is
 292       invoked as a CGI script, even if the server would not
 293       normally recognize it as such. However, the directory
 294       containing the script must be enabled for CGI scripts
 295       (with <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
 296       or <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 297       <code>ExecCGI</code>).</p>
 298
 299       <p>The CGI script is given the <code>PATH_INFO</code> and query
 300       string (<code>QUERY_STRING</code>) of the original request from the
 301       client; these <em>cannot</em> be specified in the URL path. The
 302       include variables will be available to the script in addition to
 303       the standard <a href="mod_cgi.html">CGI</a> environment.</p>
 304
 305       <div class="example"><h3>Example</h3><p><code>
 306         &lt;!--#exec cgi="/cgi-bin/example.cgi" --&gt;
 307       </code></p></div>
 308
 309       <p>If the script returns a <code>Location:</code> header instead of
 310       output, then this will be translated into an HTML anchor.</p>
 311
 312       <p>The <code><a href="#includevirtual">include virtual</a></code>
 313       element should be used in preference to <code>exec cgi</code>. In
 314       particular, if you need to pass additional arguments to a CGI program,
 315       using the query string, this cannot be done with <code>exec
 316       cgi</code>, but can be done with <code>include virtual</code>, as
 317       shown here:</p>
 318
 319       <div class="example"><p><code>
 320         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 321       </code></p></div>
 322       </dd>
 323
 324       <dt><code>cmd</code></dt>
 325       <dd><p>The server will execute the given string using
 326       <code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
 327       to the usual set of CGI variables.</p>
 328
 329       <p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
 330       either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
 331       (<code>#include virtual</code>) uses the standard Apache sub-request
 332       mechanism to include files or scripts. It is much better tested and
 333       maintained.</p>
 334
 335       <p>In addition, on some platforms, like Win32, and on unix when
 336       using <a href="../suexec.html">suexec</a>, you cannot pass arguments
 337       to a command in an <code>exec</code> directive, or otherwise include
 338       spaces in the command. Thus, while the following will work under a
 339       non-suexec configuration on unix, it will not produce the desired
 340       result under Win32, or when running suexec:</p>
 341
 342       <div class="example"><p><code>
 343         &lt;!--#exec cmd="perl /path/to/perlscript arg1 arg2" --&gt;
 344       </code></p></div>
 345       </dd>
 346       </dl>
 347
 348
 349     <h3><a name="element.fsize" id="element.fsize">The fsize Element</a></h3>
 350       <p>This command prints the size of the specified file, subject
 351       to the <code>sizefmt</code> format specification. Attributes:</p>
 352
 353       <dl>
 354       <dt><code>file</code></dt>
 355       <dd>The value is a path relative to the directory
 356       containing the current document being parsed.
 357
 358     <div class="example"><p><code>
 359         This file is &lt;!--#fsize file="mod_include.html" --&gt; bytes.
 360     </code></p></div>
 361
 362     The value of <code>file</code> cannot start with a slash
 363     (<code>/</code>), nor can it contain <code>../</code> so as to
 364     refer to a file above the current directory or outside of the
 365     document root. Attempting to so will result in the error message:
 366     <code>The given path was above the root path</code>.
 367       </dd>
 368
 369       <dt><code>virtual</code></dt>
 370       <dd>The value is a (%-encoded) URL-path. If it does not begin with
 371       a slash (/) then it is taken to be relative to the current document.
 372       Note, that this does <em>not</em> print the size of any CGI output,
 373       but the size of the CGI script itself.</dd>
 374       </dl>
 375
 376     <div class="example"><p><code>
 377         This file is &lt;!--#fsize virtual="/docs/mod/mod_include.html" --&gt; bytes.
 378     </code></p></div>
 379
 380       <p>Note that in many cases these two are exactly the same thing.
 381       However, the <code>file</code> attribute doesn't respect URL-space
 382       aliases.</p>
 383
 384
 385     <h3><a name="element.flastmod" id="element.flastmod">The flastmod Element</a></h3>
 386       <p>This command prints the last modification date of the
 387       specified file, subject to the <code>timefmt</code> format
 388       specification. The attributes are the same as for the
 389       <code><a href="#element.fsize">fsize</a></code> command.</p>
 390
 391
 392     <h3><a name="element.include" id="element.include">The include Element</a></h3>
 393       <p>This command inserts the text of another document or file
 394       into the parsed file. Any included file is subject to the usual
 395       access control. If the directory containing the parsed file has
 396       <a href="core.html#options">Options</a>
 397       <code>IncludesNOEXEC</code> set, then only documents with a text
 398       <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> (<code>text/plain</code>,
 399       <code>text/html</code> etc.) will be included. Otherwise CGI
 400       scripts are invoked as normal using the complete URL given in
 401       the command, including any query string.</p>
 402
 403       <p>An attribute defines the location of the document, and may
 404       appear more than once in an include element; an inclusion is
 405       done for each attribute given to the include command in turn.
 406       The valid attributes are:</p>
 407
 408       <dl>
 409       <dt><code>file</code></dt>
 410       <dd>The value is a path relative to the directory
 411       containing the current document being parsed. It cannot
 412       contain <code>../</code>, nor can it be an absolute path.
 413       Therefore, you cannot include files that are outside of the
 414       document root, or above the current document in the directory
 415       structure. The <code>virtual</code> attribute should always be
 416       used in preference to this one.</dd>
 417
 418       <dt><code><a id="includevirtual" name="includevirtual">virtual</a></code></dt>
 419       <dd><p>The value is a (%-encoded) URL-path. The URL cannot contain a
 420       scheme or hostname, only a path and an optional query string. If it
 421       does not begin with a slash (/) then it is taken to be relative to the
 422       current document.</p>
 423
 424       <p>A URL is constructed from the attribute, and the output the
 425       server would return if the URL were accessed by the client is
 426       included in the parsed output. Thus included files can be nested.</p>
 427
 428       <p>If the specified URL is a CGI program, the program will be
 429       executed and its output inserted in place of the directive in the
 430       parsed file. You may include a query string in a CGI url:</p>
 431
 432       <div class="example"><p><code>
 433         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 434       </code></p></div>
 435
 436       <p><code>include virtual</code> should be used in preference
 437       to <code>exec cgi</code> to include the output of CGI programs
 438       into an HTML document.</p>
 439
 440       <p>If the <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code>
 441       directive is correctly configured and valid for this included
 442       file, attempts to POST requests to the enclosing HTML document
 443       will be passed through to subrequests as POST requests as well.
 444       Without the directive, all subrequests are processed as GET
 445       requests.</p>
 446
 447       </dd>
 448
 449       <dt><code>onerror</code></dt>
 450       <dd><p>The value is a (%-encoded) URL-path which is shown should a
 451       previous attempt to include a file or virtual attribute failed.
 452       To be effective, this attribute must be specified after the
 453       file or virtual attributes being covered. If the attempt to
 454       include the onerror path fails, or if onerror is not specified, the
 455       default error message will be included.</p>
 456
 457       <div class="example"><p><code>
 458         # Simple example<br />
 459         &lt;!--#include virtual="/not-exist.html" onerror="/error.html" --&gt;
 460       </code></p></div>
 461
 462       <div class="example"><p><code>
 463         # Dedicated onerror paths<br />
 464         &lt;!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" --&gt;
 465       </code></p></div>
 466
 467       </dd>
 468       </dl>
 469
 470
 471     <h3><a name="element.printenv" id="element.printenv">The printenv Element</a></h3>
 472       <p>This prints out a plain text listing of all existing variables and
 473       their values. Special characters are entity encoded (see the <code><a href="#element.echo">echo</a></code> element for details)
 474       before being output. There are no attributes.</p>
 475
 476       <div class="example"><h3>Example</h3><p><code>
 477         &lt;pre&gt;
 478           &lt;!--#printenv --&gt;
 479         &lt;/pre&gt;
 480       </code></p></div>
 481
 482
 483     <h3><a name="element.set" id="element.set">The set Element</a></h3>
 484       <p>This sets the value of a variable. Attributes:</p>
 485
 486       <dl>
 487       <dt><code>var</code></dt>
 488       <dd>The name of the variable to set.</dd>
 489
 490       <dt><code>value</code></dt>
 491       <dd>The value to give a variable.</dd>
 492
 493       <dt><code>decoding</code></dt>
 494       <dd><p>Specifies whether Apache should strip an encoding from
 495       the variable before processing the variable further. The default
 496       is <code>none</code>, where no decoding will be done. If set to
 497       <code>url</code>, <code>urlencoded</code>, <code>base64</code>
 498       or <code>entity</code>, URL decoding,
 499       application/x-www-form-urlencoded decoding, base64 decoding or HTML
 500       entity decoding will be performed respectively. More than one
 501       decoding can be specified by separating with commas. The decoding
 502       setting will remain in effect until the next decoding attribute
 503       is encountered, or the element ends. The <code>decoding</code>
 504       attribute must <em>precede</em> the corresponding
 505       <code>var</code> attribute to be effective.</p>
 506       </dd>
 507
 508       <dt><code>encoding</code></dt>
 509       <dd><p>Specifies how Apache should encode special characters
 510       contained in the variable before setting them. The default is
 511       <code>none</code>, where no encoding will be done. If set to
 512       <code>url</code>, <code>urlencoding</code>, <code>base64</code>
 513       or <code>entity</code>, URL encoding,
 514       application/x-www-form-urlencoded encoding, base64 encoding or
 515       HTML entity encoding will be performed respectively. More than
 516       one encoding can be specified by separating with commas. The
 517       encoding setting will remain in effect until the next encoding
 518       attribute is encountered, or the element ends. The
 519       <code>encoding</code> attribute must <em>precede</em> the
 520       corresponding <code>var</code> attribute to be effective.
 521       Encodings are applied after all decodings have been
 522       stripped.</p>
 523       </dd>
 524       </dl>
 525
 526       <div class="example"><h3>Example</h3><p><code>
 527         &lt;!--#set var="category" value="help" --&gt;
 528       </code></p></div>
 529
 530 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 531 <div class="section">
 532 <h2><a name="includevars" id="includevars">Include Variables</a></h2>
 533
 534
 535     <p>In addition to the variables in the standard CGI environment,
 536     these are available for the <code>echo</code> command, for
 537     <code>if</code> and <code>elif</code>, and to any program
 538     invoked by the document.</p>
 539
 540     <dl>
 541       <dt><code>DATE_GMT</code></dt>
 542       <dd>The current date in Greenwich Mean Time.</dd>
 543
 544       <dt><code>DATE_LOCAL</code></dt>
 545       <dd>The current date in the local time zone.</dd>
 546
 547       <dt><code>DOCUMENT_ARGS</code></dt>
 548       <dd>This variable contains the query string of the active SSI
 549       document, or the empty string if a query string is not
 550       included.  For subrequests invoked through the
 551       <code>include</code> SSI directive, <code>QUERY_STRING</code>
 552       will represent the query string of the subrequest and
 553       <code>DOCUMENT_ARGS</code> will represent the query string of
 554       the SSI document.  (Available in Apache HTTP Server 2.5.0 and
 555       later.)</dd>
 556
 557       <dt><code>DOCUMENT_NAME</code></dt>
 558       <dd>The filename (excluding directories) of the document
 559       requested by the user.</dd>
 560
 561       <dt><code>DOCUMENT_URI</code></dt>
 562       <dd>The (%-decoded) URL path of the document requested by the
 563       user. Note that in the case of nested include files, this is
 564       <em>not</em> the URL for the current document.  Note also that
 565       if the URL is modified internally (e.g. by an <code class="directive"><a href="../mod/mod_alias.html#alias">alias</a></code> or <code class="directive"><a href="../mod/mod_dir.html#directoryindex">directoryindex</a></code>), the modified
 566       URL is shown.</dd>
 567
 568       <dt><code>LAST_MODIFIED</code></dt>
 569       <dd>The last modification date of the document requested by
 570       the user.</dd>
 571
 572       <dt><code>QUERY_STRING_UNESCAPED</code></dt>
 573       <dd>If a query string is present in the request for the active
 574       SSI document, this variable contains the (%-decoded) query
 575       string, which is <em>escaped</em> for shell usage (special
 576       characters like <code>&amp;</code> etc. are preceded by
 577       backslashes).  It is not set if a query string is not
 578       present.  Use <code>DOCUMENT_ARGS</code> if shell escaping
 579       is not desired.</dd>
 580     </dl>
 581 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 582 <div class="section">
 583 <h2><a name="substitution" id="substitution">Variable Substitution</a></h2>
 584
 585     <p>Variable substitution is done within quoted strings in most
 586     cases where they may reasonably occur as an argument to an SSI
 587     directive. This includes the <code>config</code>,
 588     <code>exec</code>, <code>flastmod</code>, <code>fsize</code>,
 589     <code>include</code>, <code>echo</code>, and <code>set</code>
 590     directives. If <code class="directive"><a href="#ssilegacyexprparser">SSILegacyExprParser</a></code> is set to <code>on</code>,
 591     substitution also occurs in the arguments to conditional operators.
 592     You can insert a literal dollar sign into the string using backslash
 593     quoting:</p>
 594
 595     <div class="example"><p><code>
 596       &lt;!--#set var="cur" value="\$test" --&gt;
 597     </code></p></div>
 598
 599     <p>If a variable reference needs to be substituted in the
 600     middle of a character sequence that might otherwise be
 601     considered a valid identifier in its own right, it can be
 602     disambiguated by enclosing the reference in braces,
 603     <em>a la</em> shell substitution:</p>
 604
 605     <div class="example"><p><code>
 606       &lt;!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --&gt;
 607     </code></p></div>
 608
 609     <p>This will result in the <code>Zed</code> variable being set
 610     to "<code>X_Y</code>" if <code>REMOTE_HOST</code> is
 611     "<code>X</code>" and <code>REQUEST_METHOD</code> is
 612     "<code>Y</code>".</p>
 613 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 614 <div class="section">
 615 <h2><a name="flowctrl" id="flowctrl">Flow Control Elements</a></h2>
 616
 617
 618     <p>The basic flow control elements are:</p>
 619
 620     <div class="example"><p><code>
 621       &lt;!--#if expr="<var>test_condition</var>" --&gt;<br />
 622       &lt;!--#elif expr="<var>test_condition</var>" --&gt;<br />
 623       &lt;!--#else --&gt;<br />
 624       &lt;!--#endif --&gt;
 625     </code></p></div>
 626
 627     <p>The <code>if</code> element works like an if statement in a
 628     programming language. The test condition is evaluated and if
 629     the result is true, then the text until the next <code>elif</code>,
 630     <code>else</code> or <code>endif</code> element is included in the
 631     output stream.</p>
 632
 633     <p>The <code>elif</code> or <code>else</code> statements are used
 634     to put text into the output stream if the original
 635     <var>test_condition</var> was false. These elements are optional.</p>
 636
 637     <p>The <code>endif</code> element ends the <code>if</code> element
 638     and is required.</p>
 639
 640     <p><var>test_condition</var> is a boolean expression which follows the
 641     <a href="../expr.html">ap_expr</a> syntax. The syntax can be changed
 642     to be compatible with Apache HTTPD 2.2.x using <code class="directive"><a href="#ssilegacyexprparser">SSILegacyExprParser</a></code>.</p>
 643
 644     <p>The SSI variables set with the <code>var</code> element are exported
 645     into the request environment and can be accessed with the
 646     <code>reqenv</code> function. As a short-cut, the function name
 647     <code>v</code> is also available inside <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>.</p>
 648
 649     <p>The below example will print "from local net" if client IP address
 650     belongs to the 10.0.0.0/8 subnet.</p>
 651
 652     <div class="example"><p><code>
 653       &lt;!--#if expr='-R "10.0.0.0/8"' --&gt;<br />
 654       <span class="indent">
 655         from local net<br />
 656       </span>
 657       &lt;!--#else --&gt;<br />
 658       <span class="indent">
 659         from somewhere else<br />
 660       </span>
 661       &lt;!--#endif --&gt;
 662     </code></p></div>
 663
 664     <p>The below example will print "foo is bar" if the variable
 665     <code>foo</code> is set to the value "bar".</p>
 666
 667     <div class="example"><p><code>
 668       &lt;!--#if expr='v("foo") = "bar"' --&gt;<br />
 669       <span class="indent">
 670         foo is bar<br />
 671       </span>
 672       &lt;!--#endif --&gt;
 673     </code></p></div>
 674
 675     <div class="note"><h3>Reference Documentation</h3>
 676     <p>See also: <a href="../expr.html">Expressions in Apache HTTP Server</a>,
 677     for a complete reference and examples. The <em>restricted</em> functions
 678     are not available inside <code class="module"><a href="../mod/mod_include.html">mod_include</a></code></p>
 679     </div>
 680 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 681 <div class="section">
 682 <h2><a name="legacyexpr" id="legacyexpr">Legacy expression syntax</a></h2>
 683
 684
 685     <p>This section describes the syntax of the <code>#if expr</code>
 686     element if <code class="directive"><a href="#ssilegacyexprparser">SSILegacyExprParser</a></code>
 687     is set to <code>on</code>.</p>
 688
 689     <dl>
 690       <dt><code><var>string</var></code></dt>
 691       <dd>true if <var>string</var> is not empty</dd>
 692
 693       <dt><code><var>-A string</var></code></dt>
 694       <dd><p>true if the URL represented by the string is accessible by
 695       configuration, false otherwise. This is useful where content on a
 696       page is to be hidden from users who are not authorized to view the
 697       URL, such as a link to that URL. Note that the URL is only tested
 698       for whether access would be granted, not whether the URL exists.</p>
 699
 700       <div class="example"><h3>Example</h3><p><code>
 701         &lt;!--#if expr="-A /private" --&gt;<br />
 702         <span class="indent">
 703           Click &lt;a href="/private"&gt;here&lt;/a&gt; to access private
 704           information.<br />
 705         </span>
 706         &lt;!--#endif --&gt;
 707       </code></p></div>
 708       </dd>
 709
 710       <dt><code><var>string1</var> = <var>string2</var><br />
 711       <var>string1</var> == <var>string2</var><br />
 712       <var>string1</var> != <var>string2</var></code></dt>
 713
 714       <dd><p>Compare <var>string1</var> with <var>string2</var>. If
 715       <var>string2</var> has the form <code>/<var>string2</var>/</code>
 716       then it is treated as a regular expression. Regular expressions are
 717       implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
 718       have the same syntax as those in <a href="http://www.perl.com">perl
 719       5</a>. Note that <code>==</code> is just an alias for <code>=</code>
 720       and behaves exactly the same way.</p>
 721
 722       <p>If you are matching positive (<code>=</code> or <code>==</code>), you
 723       can capture grouped parts of the regular expression. The captured parts
 724       are stored in the special variables <code>$1</code> ..
 725       <code>$9</code>. The whole string matched by the regular expression is
 726       stored in the special variable <code>$0</code></p>
 727
 728       <div class="example"><h3>Example</h3><p><code>
 729         &lt;!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" --&gt;<br />
 730         <span class="indent">
 731           &lt;!--#set var="session" value="$1" --&gt;<br />
 732         </span>
 733         &lt;!--#endif --&gt;
 734       </code></p></div>
 735       </dd>
 736
 737       <dt><code><var>string1</var> &lt; <var>string2</var><br />
 738        <var>string1</var> &lt;= <var>string2</var><br />
 739        <var>string1</var> &gt; <var>string2</var><br />
 740        <var>string1</var> &gt;= <var>string2</var></code></dt>
 741
 742       <dd>Compare <var>string1</var> with <var>string2</var>. Note, that
 743       strings are compared <em>literally</em> (using
 744       <code>strcmp(3)</code>). Therefore the string "100" is less than
 745       "20".</dd>
 746
 747       <dt><code>( <var>test_condition</var> )</code></dt>
 748       <dd>true if <var>test_condition</var> is true</dd>
 749
 750       <dt><code>! <var>test_condition</var></code></dt>
 751       <dd>true if <var>test_condition</var> is false</dd>
 752
 753       <dt><code><var>test_condition1</var> &amp;&amp;
 754         <var>test_condition2</var></code></dt>
 755       <dd>true if both <var>test_condition1</var> and
 756       <var>test_condition2</var> are true</dd>
 757
 758       <dt><code><var>test_condition1</var> ||
 759         <var>test_condition2</var></code></dt>
 760       <dd>true if either <var>test_condition1</var> or
 761       <var>test_condition2</var> is true</dd>
 762     </dl>
 763
 764     <p>"<code>=</code>" and "<code>!=</code>" bind more tightly than
 765     "<code>&amp;&amp;</code>" and "<code>||</code>". "<code>!</code>" binds
 766     most tightly. Thus, the following are equivalent:</p>
 767
 768     <div class="example"><p><code>
 769       &lt;!--#if expr="$a = test1 &amp;&amp; $b = test2" --&gt;<br />
 770       &lt;!--#if expr="($a = test1) &amp;&amp; ($b = test2)" --&gt;
 771     </code></p></div>
 772
 773     <p>The boolean operators <code>&amp;&amp;</code> and <code>||</code>
 774     share the same priority. So if you want to bind such an operator more
 775     tightly, you should use parentheses.</p>
 776
 777     <p>Anything that's not recognized as a variable or an operator
 778     is treated as a string. Strings can also be quoted:
 779     <code>'string'</code>. Unquoted strings can't contain whitespace
 780     (blanks and tabs) because it is used to separate tokens such as
 781     variables. If multiple strings are found in a row, they are
 782     concatenated using blanks. So,</p>
 783
 784     <div class="example"><p><code><var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code> results in <code><var>string1</var>&nbsp;<var>string2</var></code><br />
 785       <br />
 786       and<br />
 787       <br />
 788       <code>'<var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var>'</code> results in <code><var>string1</var>&nbsp;&nbsp;&nbsp;&nbsp;<var>string2</var></code>.</p></div>
 789
 790     <div class="note"><h3>Optimization of Boolean Expressions</h3>
 791       <p>If the expressions become more complex and slow down processing
 792       significantly, you can try to optimize them according to the
 793       evaluation rules:</p>
 794       <ul>
 795       <li>Expressions are evaluated from left to right</li>
 796       <li>Binary boolean operators (<code>&amp;&amp;</code> and <code>||</code>)
 797           are short circuited wherever possible. In conclusion with the rule
 798           above that means, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> evaluates at first
 799           the left expression. If the left result is sufficient to determine
 800           the end result, processing stops here. Otherwise it evaluates the
 801           right side and computes the end result from both left and right
 802           results.</li>
 803       <li>Short circuit evaluation is turned off as long as there are regular
 804           expressions to deal with. These must be evaluated to fill in the
 805           backreference variables (<code>$1</code> .. <code>$9</code>).</li>
 806       </ul>
 807       <p>If you want to look how a particular expression is handled, you can
 808       recompile <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> using the
 809       <code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
 810       parsed expression tokenizer information, the parse tree and how it is
 811       evaluated into the output sent to the client.</p>
 812     </div>
 813
 814     <div class="note"><h3>Escaping slashes in regex strings</h3>
 815      <p>All slashes which are not intended to act as delimiters in your regex must
 816      be escaped.  This is regardless of their meaning to the regex engine.</p>
 817     </div>
 818
 819 </div>
 820 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 821 <div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>
 822 <table class="directive">
 823 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that ends an include element</td></tr>
 824 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEndTag <var>tag</var></code></td></tr>
 825 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEndTag "--&gt;"</code></td></tr>
 826 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 827 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 828 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 829 </table>
 830     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 831     looks for to mark the end of an include element.</p>
 832
 833     <pre class="prettyprint lang-config">SSIEndTag "%&gt;"</pre>
 834
 835
 836
 837 <h3>See also</h3>
 838 <ul>
 839 <li><code class="directive"><a href="#ssistarttag">SSIStartTag</a></code></li>
 840 </ul>
 841 </div>
 842 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 843 <div class="directive-section"><h2><a name="SSIErrorMsg" id="SSIErrorMsg">SSIErrorMsg</a> <a name="ssierrormsg" id="ssierrormsg">Directive</a></h2>
 844 <table class="directive">
 845 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Error message displayed when there is an SSI
 846 error</td></tr>
 847 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIErrorMsg <var>message</var></code></td></tr>
 848 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIErrorMsg "[an error occurred while processing this
 849 directive]"</code></td></tr>
 850 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 851 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 852 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 853 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 854 </table>
 855     <p>The <code class="directive">SSIErrorMsg</code> directive changes the error
 856     message displayed when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> encounters an
 857     error. For production servers you may consider changing the default
 858     error message to <code>"&lt;!-- Error --&gt;"</code> so that
 859     the message is not presented to the user.</p>
 860
 861     <p>This directive has the same effect as the <code>&lt;!--#config
 862     errmsg=<var>message</var> --&gt;</code> element.</p>
 863
 864     <pre class="prettyprint lang-config">SSIErrorMsg "&lt;!-- Error --&gt;"</pre>
 865
 866
 867 </div>
 868 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 869 <div class="directive-section"><h2><a name="SSIETag" id="SSIETag">SSIETag</a> <a name="ssietag" id="ssietag">Directive</a></h2>
 870 <table class="directive">
 871 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether ETags are generated by the server.</td></tr>
 872 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIETag on|off</code></td></tr>
 873 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIETag off</code></td></tr>
 874 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 875 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 876 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 877 </table>
 878       <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 879         may contain elements that are either dynamically generated, or that may
 880         have changed independently of the original file. As a result, by default
 881         the server is asked not to generate an <code>ETag</code> header for the
 882         response by adding <code>no-etag</code> to the request notes.</p>
 883
 884       <p>The <code class="directive">SSIETag</code> directive suppresses this
 885         behaviour, and allows the server to generate an <code>ETag</code> header.
 886         This can be used to enable caching of the output. Note that a backend server
 887         or dynamic content generator may generate an ETag of its own, ignoring
 888         <code>no-etag</code>, and this ETag will be passed by
 889         <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> regardless of the value of this setting.
 890         <code class="directive">SSIETag</code> can take on the following values:</p>
 891
 892       <dl>
 893
 894         <dt><code>off</code></dt>
 895         <dd><code>no-etag</code> will be added to the request notes, and the server
 896           is asked not to generate an ETag. Where a server ignores the value of
 897           <code>no-etag</code> and generates an ETag anyway, the ETag will be
 898           respected.</dd>
 899
 900         <dt><code>on</code></dt>
 901         <dd>Existing ETags will be respected, and ETags generated by the server will
 902           be passed on in the response.</dd>
 903
 904       </dl>
 905
 906
 907 </div>
 908 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 909 <div class="directive-section"><h2><a name="SSILastModified" id="SSILastModified">SSILastModified</a> <a name="ssilastmodified" id="ssilastmodified">Directive</a></h2>
 910 <table class="directive">
 911 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Controls whether <code>Last-Modified</code> headers are generated by the
 912 server.</td></tr>
 913 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILastModified on|off</code></td></tr>
 914 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILastModified off</code></td></tr>
 915 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 916 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 917 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 918 </table>
 919       <p>Under normal circumstances, a file filtered by <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 920         may contain elements that are either dynamically generated, or that may
 921         have changed independently of the original file. As a result, by default
 922         the <code>Last-Modified</code> header is stripped from the response.</p>
 923
 924       <p>The <code class="directive">SSILastModified</code> directive overrides this
 925         behaviour, and allows the <code>Last-Modified</code> header to be respected
 926         if already present, or set if the header is not already present. This can
 927         be used to enable caching of the output. <code class="directive">SSILastModified</code>
 928         can take on the following values:</p>
 929
 930       <dl>
 931
 932         <dt><code>off</code></dt>
 933         <dd>The <code>Last-Modified</code> header will be stripped from responses,
 934           unless the <code class="directive"><a href="#xbithack">XBitHack</a></code> directive
 935           is set to <code>full</code> as described below.</dd>
 936
 937         <dt><code>on</code></dt>
 938         <dd>The <code>Last-Modified</code> header will be respected if already
 939           present in a response, and added to the response if the response is a
 940           file and the header is missing. The
 941           <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> directive
 942           takes precedence over <code class="directive"><a href="#xbithack">XBitHack</a></code>.</dd>
 943
 944       </dl>
 945
 946
 947 </div>
 948 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 949 <div class="directive-section"><h2><a name="SSILegacyExprParser" id="SSILegacyExprParser">SSILegacyExprParser</a> <a name="ssilegacyexprparser" id="ssilegacyexprparser">Directive</a></h2>
 950 <table class="directive">
 951 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable compatibility mode for conditional expressions.</td></tr>
 952 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSILegacyExprParser on|off</code></td></tr>
 953 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSILegacyExprParser off</code></td></tr>
 954 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 955 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 956 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 957 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.3.13 and later.</td></tr>
 958 </table>
 959     <p>As of version 2.3.13, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> has switched to the
 960     new <a href="../expr.html">ap_expr</a> syntax for conditional expressions
 961     in <code>#if</code> flow control elements.  This directive allows to
 962     switch to the <a href="#legacyexpr">old syntax</a> which is compatible
 963     with Apache HTTPD version 2.2.x and earlier.
 964     </p>
 965
 966 </div>
 967 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 968 <div class="directive-section"><h2><a name="SSIStartTag" id="SSIStartTag">SSIStartTag</a> <a name="ssistarttag" id="ssistarttag">Directive</a></h2>
 969 <table class="directive">
 970 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that starts an include element</td></tr>
 971 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIStartTag <var>tag</var></code></td></tr>
 972 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIStartTag "&lt;!--#"</code></td></tr>
 973 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 974 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 975 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 976 </table>
 977     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 978     looks for to mark an include element to process.</p>
 979
 980     <p>You may want to use this option if you have 2 servers parsing the
 981     output of a file each processing different commands (possibly at
 982     different times).</p>
 983
 984     <pre class="prettyprint lang-config">      SSIStartTag "&lt;%"<br />
 985       SSIEndTag   "%&gt;"</pre>
 986
 987
 988     <p>The example given above, which also specifies a matching
 989     <code class="directive"><a href="#ssiendtag">SSIEndTag</a></code>, will
 990     allow you to use SSI directives as shown in the example
 991     below:</p>
 992
 993     <div class="example"><h3>SSI directives with alternate start and end tags</h3><p><code>
 994       &lt;%printenv %&gt;
 995     </code></p></div>
 996
 997 <h3>See also</h3>
 998 <ul>
 999 <li><code class="directive"><a href="#ssiendtag">SSIEndTag</a></code></li>
1000 </ul>
1001 </div>
1002 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1003 <div class="directive-section"><h2><a name="SSITimeFormat" id="SSITimeFormat">SSITimeFormat</a> <a name="ssitimeformat" id="ssitimeformat">Directive</a></h2>
1004 <table class="directive">
1005 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the format in which date strings are
1006 displayed</td></tr>
1007 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSITimeFormat <var>formatstring</var></code></td></tr>
1008 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</code></td></tr>
1009 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1010 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1011 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
1012 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
1013 </table>
1014 <p>This directive changes the format in which date strings are displayed
1015     when echoing <code>DATE</code> environment variables. The
1016     <var>formatstring</var> is as in <code>strftime(3)</code> from the
1017     C standard library.</p>
1018
1019     <p>This directive has the same effect as the <code>&lt;!--#config
1020     timefmt=<var>formatstring</var> --&gt;</code> element.</p>
1021
1022     <pre class="prettyprint lang-config">SSITimeFormat "%R, %B %d, %Y"</pre>
1023
1024
1025     <p>The above directive would cause times to be displayed in the
1026     format "22:26, June 14, 2002".</p>
1027
1028 </div>
1029 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1030 <div class="directive-section"><h2><a name="SSIUndefinedEcho" id="SSIUndefinedEcho">SSIUndefinedEcho</a> <a name="ssiundefinedecho" id="ssiundefinedecho">Directive</a></h2>
1031 <table class="directive">
1032 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String displayed when an unset variable is echoed</td></tr>
1033 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIUndefinedEcho <var>string</var></code></td></tr>
1034 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIUndefinedEcho "(none)"</code></td></tr>
1035 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1036 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
1037 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
1038 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
1039 </table>
1040     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
1041     displays when a variable is not set and "echoed".</p>
1042
1043     <pre class="prettyprint lang-config">SSIUndefinedEcho "&lt;!-- undef --&gt;"</pre>
1044
1045
1046 </div>
1047 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1048 <div class="directive-section"><h2><a name="XBitHack" id="XBitHack">XBitHack</a> <a name="xbithack" id="xbithack">Directive</a></h2>
1049 <table class="directive">
1050 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parse SSI directives in files with the execute bit
1051 set</td></tr>
1052 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>XBitHack on|off|full</code></td></tr>
1053 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>XBitHack off</code></td></tr>
1054 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
1055 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
1056 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
1057 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
1058 </table>
1059     <p>The <code class="directive">XBitHack</code> directive controls the parsing
1060     of ordinary html documents. This directive only affects files associated
1061     with the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> <code>text/html</code>. <code class="directive">XBitHack</code> can take on the following values:</p>
1062
1063     <dl>
1064       <dt><code>off</code></dt>
1065       <dd>No special treatment of executable files.</dd>
1066
1067       <dt><code>on</code></dt>
1068       <dd>Any <code>text/html</code> file that has the user-execute bit
1069       set will be treated as a server-parsed html document.</dd>
1070
1071       <dt><code>full</code></dt>
1072       <dd>As for <code>on</code> but also test the group-execute bit.
1073       If it is set, then set the <code>Last-modified</code> date of the
1074       returned file to be the last modified time of the file. If
1075       it is not set, then no last-modified date is sent. Setting
1076       this bit allows clients and proxies to cache the result of
1077       the request.
1078
1079       <div class="note"><h3>Note</h3>
1080       <p>You would not want to use the full option, unless you assure the
1081       group-execute bit is unset for every SSI script which might <code>#include</code> a CGI or otherwise produces different output on
1082       each hit (or could potentially change on subsequent requests).</p>
1083
1084       <p>The <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code>
1085       directive takes precedence over the
1086       <code class="directive"><a href="#xbithack">XBitHack</a></code> directive when
1087       <code class="directive"><a href="#ssilastmodified">SSILastModified</a></code> is set to
1088       <code>on</code>.</p>
1089       </div>
1090
1091       </dd>
1092     </dl>
1093
1094
1095 </div>
1096 </div>
1097 <div class="bottomlang">
1098 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
1099 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
1100 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
1101 <script type="text/javascript"><!--//--><![CDATA[//><!--
1102 var comments_shortname = 'httpd';
1103 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_include.html';
1104 (function(w, d) {
1105     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
1106         d.write('<div id="comments_thread"><\/div>');
1107         var s = d.createElement('script');
1108         s.type = 'text/javascript';
1109         s.async = true;
1110         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
1111         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
1112     }
1113     else {
1114         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
1115     }
1116 })(window, document);
1117 //--><!]]></script></div><div id="footer">
1118 <p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
1119 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
1120 if (typeof(prettyPrint) !== 'undefined') {
1121     prettyPrint();
1122 }
1123 //--><!]]></script>
1124 </body></html>