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