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