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