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" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body>
  14 <div id="page-header">
  15 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  16 <p class="apache">Apache HTTP Server Version 2.3</p>
  17 <img alt="" src="../images/feather.gif" /></div>
  18 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  19 <div id="path">
  20 <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.3</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_include</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
  26 </div>
  27 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Server-parsed html documents (Server Side Includes)</td></tr>
  28 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  29 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>include_module</td></tr>
  30 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_include.c</td></tr>
  31 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Implemented as an output filter since Apache
  32 2.0</td></tr></table>
  33 <h3>Summary</h3>
  34
  35     <p>This module provides a filter which will process files
  36     before they are sent to the client. The processing is
  37     controlled by specially formatted SGML comments, referred to as
  38     <dfn>elements</dfn>. These elements allow conditional text, the
  39     inclusion of other files or programs, as well as the setting and
  40     printing of environment variables.</p>
  41 </div>
  42 <div id="quickview"><h3 class="directives">Directives</h3>
  43 <ul id="toc">
  44 <li><img alt="" src="../images/down.gif" /> <a href="#ssienableaccess">SSIEnableAccess</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#ssiendtag">SSIEndTag</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#ssierrormsg">SSIErrorMsg</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#ssistarttag">SSIStartTag</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#ssitimeformat">SSITimeFormat</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#ssiundefinedecho">SSIUndefinedEcho</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#xbithack">XBitHack</a></li>
  51 </ul>
  52 <h3>Topics</h3>
  53 <ul id="topics">
  54 <li><img alt="" src="../images/down.gif" /> <a href="#enabling">Enabling Server-Side Includes</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#pathinfo">PATH_INFO with Server Side Includes</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#elements">Basic Elements</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#includevars">Include Variables</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#substitution">Variable Substitution</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#flowctrl">Flow Control Elements</a></li>
  60 </ul><h3>See also</h3>
  61 <ul class="seealso">
  62 <li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li>
  63 <li><code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code></li>
  64 <li><a href="../filter.html">Filters</a></li>
  65 <li><a href="../howto/ssi.html">SSI Tutorial</a></li>
  66 </ul></div>
  67 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  68 <div class="section">
  69 <h2><a name="enabling" id="enabling">Enabling Server-Side Includes</a></h2>
  70
  71
  72     <p>Server Side Includes are implemented by the
  73     <code>INCLUDES</code> <a href="../filter.html">filter</a>. If
  74     documents containing server-side include directives are given
  75     the extension .shtml, the following directives will make Apache
  76     parse them and assign the resulting document the mime type of
  77     <code>text/html</code>:</p>
  78
  79     <div class="example"><p><code>
  80       AddType text/html .shtml<br />
  81       AddOutputFilter INCLUDES .shtml
  82     </code></p></div>
  83
  84     <p>The following directive must be given for the directories
  85     containing the shtml files (typically in a
  86     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section,
  87     but this directive is also valid in <code>.htaccess</code> files if
  88     <code class="directive"><a href="../mod/core.html#allowoverride">AllowOverride</a></code> <code>Options</code>
  89     is set):</p>
  90
  91     <div class="example"><p><code>
  92       Options +Includes
  93     </code></p></div>
  94
  95     <p>For backwards compatibility, the <code>server-parsed</code>
  96     <a href="../handler.html">handler</a> also activates the
  97     INCLUDES filter. As well, Apache will activate the INCLUDES
  98     filter for any document with mime type
  99     <code>text/x-server-parsed-html</code> or
 100     <code>text/x-server-parsed-html3</code> (and the resulting
 101     output will have the mime type <code>text/html</code>).</p>
 102
 103     <p>For more information, see our <a href="../howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
 104 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 105 <div class="section">
 106 <h2><a name="pathinfo" id="pathinfo">PATH_INFO with Server Side Includes</a></h2>
 107
 108
 109     <p>Files processed for server-side includes no longer accept
 110     requests with <code>PATH_INFO</code> (trailing pathname information)
 111     by default.  You can use the <code class="directive"><a href="../mod/core.html#acceptpathinfo">AcceptPathInfo</a></code> directive to
 112     configure the server to accept requests with <code>PATH_INFO</code>.</p>
 113 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 114 <div class="section">
 115 <h2><a name="elements" id="elements">Basic Elements</a></h2>
 116     <p>The document is parsed as an HTML document, with special
 117     commands embedded as SGML comments. A command has the syntax: </p>
 118
 119     <div class="example"><p><code>
 120       &lt;!--#<var>element</var> <var>attribute</var>=<var>value</var>
 121       <var>attribute</var>=<var>value</var> ... --&gt;
 122     </code></p></div>
 123
 124     <p>The value will often be enclosed in double quotes, but single
 125     quotes (<code>'</code>) and backticks (<code>`</code>) are also
 126     possible. Many commands only allow a single attribute-value pair.
 127     Note that the comment terminator (<code>--&gt;</code>) should be
 128     preceded by whitespace to ensure that it isn't considered part of
 129     an SSI token. Note that the leading <code>&lt;!--#</code> is <em>one</em>
 130     token and may not contain any whitespaces.</p>
 131
 132     <p>The allowed elements are listed in the following table:</p>
 133
 134     <table class="bordered">
 135     <tr><th>Element</th><th>Description</th></tr>
 136     <tr><td><code><a href="#element.config">config</a></code></td>
 137         <td>configure output formats</td></tr>
 138     <tr><td><code><a href="#element.echo">echo</a></code></td>
 139         <td>print variables</td></tr>
 140     <tr><td><code><a href="#element.exec">exec</a></code></td>
 141         <td>execute external programs</td></tr>
 142     <tr><td><code><a href="#element.fsize">fsize</a></code></td>
 143         <td>print size of a file</td></tr>
 144     <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
 145         <td>print last modification time of a file</td></tr>
 146     <tr><td><code><a href="#element.include">include</a></code></td>
 147         <td>include a file</td></tr>
 148     <tr><td><code><a href="#element.printenv">printenv</a></code></td>
 149         <td>print all available variables</td></tr>
 150     <tr><td><code><a href="#element.set">set</a></code></td>
 151         <td>set a value of a variable</td></tr>
 152     </table>
 153
 154     <p>SSI elements may be defined by modules other than
 155     <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
 156     <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code>, and will only be available if this
 157     module is loaded.</p>
 158
 159     <h3><a name="element.config" id="element.config">The config Element</a></h3>
 160       <p>This command controls various aspects of the parsing. The
 161       valid attributes are:</p>
 162
 163       <dl>
 164       <dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
 165       <dd>The value is a message that is sent back to the
 166       client if the <code><a href="#element.echo">echo</a></code> element
 167       attempts to echo an undefined variable. This overrides any <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directives.</dd>
 168
 169       <dt><code>errmsg</code></dt>
 170       <dd>The value is a message that is sent back to the
 171       client if an error occurs while parsing the
 172       document. This overrides any <code class="directive"><a href="#ssierrormsg">SSIErrorMsg</a></code> directives.</dd>
 173
 174       <dt><code>sizefmt</code></dt>
 175       <dd>The value sets the format to be used which displaying
 176       the size of a file. Valid values are <code>bytes</code>
 177       for a count in bytes, or <code>abbrev</code> for a count
 178       in Kb or Mb as appropriate, for example a size of 1024 bytes
 179       will be printed as "1K".</dd>
 180
 181       <dt><code>timefmt</code></dt>
 182       <dd>The value is a string to be used by the
 183       <code>strftime(3)</code> library routine when printing
 184       dates.</dd>
 185       </dl>
 186
 187
 188     <h3><a name="element.echo" id="element.echo">The echo Element</a></h3>
 189       <p>This command prints one of the <a href="#includevars">include
 190       variables</a>, defined below. If the variable is unset, the result is
 191       determined by the <code class="directive"><a href="#ssiundefinedecho">SSIUndefinedEcho</a></code> directive. Any dates printed are
 192       subject to the currently configured <code>timefmt</code>.</p>
 193
 194       <p>Attributes:</p>
 195
 196       <dl>
 197       <dt><code>var</code></dt>
 198       <dd>The value is the name of the variable to print.</dd>
 199
 200       <dt><code>encoding</code></dt>
 201       <dd><p>Specifies how Apache should encode special characters
 202       contained in the variable before outputting them. If set
 203       to <code>none</code>, no encoding will be done. If set to
 204       <code>url</code>, then URL encoding (also known as %-encoding;
 205       this is appropriate for use within URLs in links, etc.) will be
 206       performed. At the start of an <code>echo</code> element,
 207       the default is set to <code>entity</code>, resulting in entity
 208       encoding (which is appropriate in the context of a block-level
 209       HTML element, <em>e.g.</em> a paragraph of text). This can be
 210       changed by adding an <code>encoding</code> attribute, which will
 211       remain in effect until the next <code>encoding</code> attribute
 212       is encountered or the element ends, whichever comes first.</p>
 213
 214       <p>The <code>encoding</code> attribute must <em>precede</em> the
 215       corresponding <code>var</code> attribute to be effective, and
 216       only special characters as defined in the ISO-8859-1 character
 217       encoding will be encoded. This encoding process may not have the
 218       desired result if a different character encoding is in use.</p>
 219
 220       <div class="warning">
 221         In order to avoid cross-site scripting issues, you should
 222         <em>always</em> encode user supplied data.
 223       </div>
 224       </dd>
 225       </dl>
 226
 227
 228     <h3><a name="element.exec" id="element.exec">The exec Element</a></h3>
 229       <p>The <code>exec</code> command executes a given shell command or
 230       CGI script. It requires <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> to be present
 231       in the server. If <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 232       <code>IncludesNOEXEC</code> is set, this command is completely
 233       disabled. The valid attributes are:</p>
 234
 235       <dl>
 236       <dt><code>cgi</code></dt>
 237       <dd><p>The value specifies a (%-encoded) URL-path to
 238       the CGI script. If the path does not begin with a slash (/),
 239       then it is taken to be relative to the current
 240       document. The document referenced by this path is
 241       invoked as a CGI script, even if the server would not
 242       normally recognize it as such. However, the directory
 243       containing the script must be enabled for CGI scripts
 244       (with <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
 245       or <code class="directive"><a href="../mod/core.html#options">Options</a></code>
 246       <code>ExecCGI</code>).</p>
 247
 248       <p>The CGI script is given the <code>PATH_INFO</code> and query
 249       string (<code>QUERY_STRING</code>) of the original request from the
 250       client; these <em>cannot</em> be specified in the URL path. The
 251       include variables will be available to the script in addition to
 252       the standard <a href="mod_cgi.html">CGI</a> environment.</p>
 253
 254       <div class="example"><h3>Example</h3><p><code>
 255         &lt;!--#exec cgi="/cgi-bin/example.cgi" --&gt;
 256       </code></p></div>
 257
 258       <p>If the script returns a <code>Location:</code> header instead of
 259       output, then this will be translated into an HTML anchor.</p>
 260
 261       <p>The <code><a href="#includevirtual">include virtual</a></code>
 262       element should be used in preference to <code>exec cgi</code>. In
 263       particular, if you need to pass additional arguments to a CGI program,
 264       using the query string, this cannot be done with <code>exec
 265       cgi</code>, but can be done with <code>include virtual</code>, as
 266       shown here:</p>
 267
 268       <div class="example"><p><code>
 269         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 270       </code></p></div>
 271       </dd>
 272
 273       <dt><code>cmd</code></dt>
 274       <dd><p>The server will execute the given string using
 275       <code>/bin/sh</code>. The <a href="#includevars">include variables</a> are available to the command, in addition
 276       to the usual set of CGI variables.</p>
 277
 278       <p>The use of <code><a href="#includevirtual">#include virtual</a></code> is almost always prefered to using
 279       either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
 280       (<code>#include virtual</code>) uses the standard Apache sub-request
 281       mechanism to include files or scripts. It is much better tested and
 282       maintained.</p>
 283
 284       <p>In addition, on some platforms, like Win32, and on unix when
 285       using <a href="../suexec.html">suexec</a>, you cannot pass arguments
 286       to a command in an <code>exec</code> directive, or otherwise include
 287       spaces in the command. Thus, while the following will work under a
 288       non-suexec configuration on unix, it will not produce the desired
 289       result under Win32, or when running suexec:</p>
 290
 291       <div class="example"><p><code>
 292         &lt;!--#exec cmd="perl /path/to/perlscript arg1 arg2" --&gt;
 293       </code></p></div>
 294       </dd>
 295       </dl>
 296
 297
 298     <h3><a name="element.fsize" id="element.fsize">The fsize Element</a></h3>
 299       <p>This command prints the size of the specified file, subject
 300       to the <code>sizefmt</code> format specification. Attributes:</p>
 301
 302       <dl>
 303       <dt><code>file</code></dt>
 304       <dd>The value is a path relative to the directory
 305       containing the current document being parsed.</dd>
 306
 307       <dt><code>virtual</code></dt>
 308       <dd>The value is a (%-encoded) URL-path. If it does not begin with
 309       a slash (/) then it is taken to be relative to the current document.
 310       Note, that this does <em>not</em> print the size of any CGI output,
 311       but the size of the CGI script itself.</dd>
 312       </dl>
 313
 314
 315     <h3><a name="element.flastmod" id="element.flastmod">The flastmod Element</a></h3>
 316       <p>This command prints the last modification date of the
 317       specified file, subject to the <code>timefmt</code> format
 318       specification. The attributes are the same as for the
 319       <code><a href="#element.fsize">fsize</a></code> command.</p>
 320
 321
 322     <h3><a name="element.include" id="element.include">The include Element</a></h3>
 323       <p>This command inserts the text of another document or file
 324       into the parsed file. Any included file is subject to the usual
 325       access control. If the directory containing the parsed file has
 326       <a href="core.html#options">Options</a>
 327       <code>IncludesNOEXEC</code> set, then only documents with a text
 328       <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> (<code>text/plain</code>,
 329       <code>text/html</code> etc.) will be included. Otherwise CGI
 330       scripts are invoked as normal using the complete URL given in
 331       the command, including any query string.</p>
 332
 333       <p>An attribute defines the location of the document; the
 334       inclusion is done for each attribute given to the include
 335       command. The valid attributes are:</p>
 336
 337       <dl>
 338       <dt><code>file</code></dt>
 339       <dd>The value is a path relative to the directory
 340       containing the current document being parsed. It cannot
 341       contain <code>../</code>, nor can it be an absolute path.
 342       Therefore, you cannot include files that are outside of the
 343       document root, or above the current document in the directory
 344       structure. The <code>virtual</code> attribute should always be
 345       used in preference to this one.</dd>
 346
 347       <dt><code><a id="includevirtual" name="includevirtual">virtual</a></code></dt>
 348       <dd><p>The value is a (%-encoded) URL-path. The URL cannot contain a
 349       scheme or hostname, only a path and an optional query string. If it
 350       does not begin with a slash (/) then it is taken to be relative to the
 351       current document.</p>
 352
 353       <p>A URL is constructed from the attribute, and the output the
 354       server would return if the URL were accessed by the client is
 355       included in the parsed output. Thus included files can be nested.</p>
 356
 357       <p>If the specified URL is a CGI program, the program will be
 358       executed and its output inserted in place of the directive in the
 359       parsed file. You may include a query string in a CGI url:</p>
 360
 361       <div class="example"><p><code>
 362         &lt;!--#include virtual="/cgi-bin/example.cgi?argument=value" --&gt;
 363       </code></p></div>
 364
 365       <p><code>include virtual</code> should be used in preference
 366       to <code>exec cgi</code> to include the output of CGI programs
 367       into an HTML document.</p>
 368
 369       <p>If the <code class="directive"><a href="../mod/mod_request.html#keptbodysize">KeptBodySize</a></code>
 370       directive is correctly configured and valid for this included
 371       file, attempts to POST requests to the enclosing HTML document
 372       will be passed through to subrequests as POST requests as well.
 373       Without the directive, all subrequests are processed as GET
 374       requests.</p>
 375
 376       </dd>
 377       </dl>
 378
 379
 380     <h3><a name="element.printenv" id="element.printenv">The printenv Element</a></h3>
 381       <p>This prints out a listing of all existing variables and
 382       their values. Special characters are entity encoded (see the <code><a href="#element.echo">echo</a></code> element for details)
 383       before being output. There are no attributes.</p>
 384
 385       <div class="example"><h3>Example</h3><p><code>
 386         &lt;!--#printenv --&gt;
 387       </code></p></div>
 388
 389
 390     <h3><a name="element.set" id="element.set">The set Element</a></h3>
 391       <p>This sets the value of a variable. Attributes:</p>
 392
 393       <dl>
 394       <dt><code>var</code></dt>
 395       <dd>The name of the variable to set.</dd>
 396
 397       <dt><code>value</code></dt>
 398       <dd>The value to give a variable.</dd>
 399       </dl>
 400
 401       <div class="example"><h3>Example</h3><p><code>
 402         &lt;!--#set var="category" value="help" --&gt;
 403       </code></p></div>
 404
 405 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 406 <div class="section">
 407 <h2><a name="includevars" id="includevars">Include Variables</a></h2>
 408
 409
 410     <p>In addition to the variables in the standard CGI environment,
 411     these are available for the <code>echo</code> command, for
 412     <code>if</code> and <code>elif</code>, and to any program
 413     invoked by the document.</p>
 414
 415     <dl>
 416       <dt><code>DATE_GMT</code></dt>
 417       <dd>The current date in Greenwich Mean Time.</dd>
 418
 419       <dt><code>DATE_LOCAL</code></dt>
 420       <dd>The current date in the local time zone.</dd>
 421
 422       <dt><code>DOCUMENT_NAME</code></dt>
 423       <dd>The filename (excluding directories) of the document
 424       requested by the user.</dd>
 425
 426       <dt><code>DOCUMENT_URI</code></dt>
 427       <dd>The (%-decoded) URL path of the document requested by the
 428       user. Note that in the case of nested include files, this is
 429       <em>not</em> the URL for the current document.</dd>
 430
 431       <dt><code>LAST_MODIFIED</code></dt>
 432       <dd>The last modification date of the document requested by
 433       the user.</dd>
 434
 435       <dt><code>QUERY_STRING_UNESCAPED</code></dt>
 436       <dd>If a query string is present, this variable contains the
 437       (%-decoded) query string, which is <em>escaped</em> for shell
 438       usage (special characters like <code>&amp;</code> etc. are
 439       preceded by backslashes).</dd>
 440     </dl>
 441 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 442 <div class="section">
 443 <h2><a name="substitution" id="substitution">Variable Substitution</a></h2>
 444
 445     <p>Variable substitution is done within quoted strings in most
 446     cases where they may reasonably occur as an argument to an SSI
 447     directive. This includes the <code>config</code>,
 448     <code>exec</code>, <code>flastmod</code>, <code>fsize</code>,
 449     <code>include</code>, <code>echo</code>, and <code>set</code>
 450     directives, as well as the arguments to conditional operators.
 451     You can insert a literal dollar sign into the string using backslash
 452     quoting:</p>
 453
 454     <div class="example"><p><code>
 455       &lt;!--#if expr="$a = \$test" --&gt;
 456     </code></p></div>
 457
 458     <p>If a variable reference needs to be substituted in the
 459     middle of a character sequence that might otherwise be
 460     considered a valid identifier in its own right, it can be
 461     disambiguated by enclosing the reference in braces,
 462     <em>a la</em> shell substitution:</p>
 463
 464     <div class="example"><p><code>
 465       &lt;!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --&gt;
 466     </code></p></div>
 467
 468     <p>This will result in the <code>Zed</code> variable being set
 469     to "<code>X_Y</code>" if <code>REMOTE_HOST</code> is
 470     "<code>X</code>" and <code>REQUEST_METHOD</code> is
 471     "<code>Y</code>".</p>
 472
 473     <p>The below example will print "in foo" if the
 474     <code>DOCUMENT_URI</code> is <code>/foo/file.html</code>, "in bar"
 475     if it is <code>/bar/file.html</code> and "in neither" otherwise:</p>
 476
 477     <div class="example"><p><code>
 478       &lt;!--#if expr='"$DOCUMENT_URI" = "/foo/file.html"' --&gt;<br />
 479       <span class="indent">
 480         in foo<br />
 481       </span>
 482       &lt;!--#elif expr='"$DOCUMENT_URI" = "/bar/file.html"' --&gt;<br />
 483       <span class="indent">
 484         in bar<br />
 485       </span>
 486       &lt;!--#else --&gt;<br />
 487       <span class="indent">
 488         in neither<br />
 489       </span>
 490       &lt;!--#endif --&gt;
 491     </code></p></div>
 492 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 493 <div class="section">
 494 <h2><a name="flowctrl" id="flowctrl">Flow Control Elements</a></h2>
 495
 496
 497     <p>The basic flow control elements are:</p>
 498
 499     <div class="example"><p><code>
 500       &lt;!--#if expr="<var>test_condition</var>" --&gt;<br />
 501       &lt;!--#elif expr="<var>test_condition</var>" --&gt;<br />
 502       &lt;!--#else --&gt;<br />
 503       &lt;!--#endif --&gt;
 504     </code></p></div>
 505
 506     <p>The <code>if</code> element works like an if statement in a
 507     programming language. The test condition is evaluated and if
 508     the result is true, then the text until the next <code>elif</code>,
 509     <code>else</code> or <code>endif</code> element is included in the
 510     output stream.</p>
 511
 512     <p>The <code>elif</code> or <code>else</code> statements are be used
 513     to put text into the output stream if the original
 514     <var>test_condition</var> was false. These elements are optional.</p>
 515
 516     <p>The <code>endif</code> element ends the <code>if</code> element
 517     and is required.</p>
 518
 519     <p><var>test_condition</var> is one of the following:</p>
 520
 521     <dl>
 522       <dt><code><var>string</var></code></dt>
 523       <dd>true if <var>string</var> is not empty</dd>
 524
 525       <dt><code><var>-A string</var></code></dt>
 526       <dd><p>true if the URL represented by the string is accessible by
 527       configuration, false otherwise. This test only has an effect if
 528       <code class="directive">SSIEnableAccess</code> is on. This is useful
 529       where content on a page is to be hidden from users who are not
 530       authorized to view the URL, such as a link to that URL. Note
 531       that the URL is only tested for whether access would be granted,
 532       not whether the URL exists.</p>
 533
 534       <div class="example"><h3>Example</h3><p><code>
 535         &lt;!--#if expr="-A /private" --&gt;<br />
 536         <span class="indent">
 537           Click &lt;a href="/private"&gt;here&lt;/a&gt; to access private
 538           information.<br />
 539         </span>
 540         &lt;!--#endif --&gt;
 541       </code></p></div>
 542       </dd>
 543
 544       <dt><code><var>string1</var> = <var>string2</var><br />
 545       <var>string1</var> == <var>string2</var><br />
 546       <var>string1</var> != <var>string2</var></code></dt>
 547
 548       <dd><p>Compare <var>string1</var> with <var>string2</var>. If
 549       <var>string2</var> has the form <code>/<var>string2</var>/</code>
 550       then it is treated as a regular expression. Regular expressions are
 551       implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
 552       have the same syntax as those in <a href="http://www.perl.com">perl
 553       5</a>. Note that <code>==</code> is just an alias for <code>=</code>
 554       and behaves exactly the same way.</p>
 555
 556       <p>If you are matching positive (<code>=</code> or <code>==</code>), you
 557       can capture grouped parts of the regular expression. The captured parts
 558       are stored in the special variables <code>$1</code> ..
 559       <code>$9</code>.</p>
 560
 561       <div class="example"><h3>Example</h3><p><code>
 562         &lt;!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" --&gt;<br />
 563         <span class="indent">
 564           &lt;!--#set var="session" value="$1" --&gt;<br />
 565         </span>
 566         &lt;!--#endif --&gt;
 567       </code></p></div>
 568       </dd>
 569
 570       <dt><code><var>string1</var> &lt; <var>string2</var><br />
 571        <var>string1</var> &lt;= <var>string2</var><br />
 572        <var>string1</var> &gt; <var>string2</var><br />
 573        <var>string1</var> &gt;= <var>string2</var></code></dt>
 574
 575       <dd>Compare <var>string1</var> with <var>string2</var>. Note, that
 576       strings are compared <em>literally</em> (using
 577       <code>strcmp(3)</code>). Therefore the string "100" is less than
 578       "20".</dd>
 579
 580       <dt><code>( <var>test_condition</var> )</code></dt>
 581       <dd>true if <var>test_condition</var> is true</dd>
 582
 583       <dt><code>! <var>test_condition</var></code></dt>
 584       <dd>true if <var>test_condition</var> is false</dd>
 585
 586       <dt><code><var>test_condition1</var> &amp;&amp;
 587         <var>test_condition2</var></code></dt>
 588       <dd>true if both <var>test_condition1</var> and
 589       <var>test_condition2</var> are true</dd>
 590
 591       <dt><code><var>test_condition1</var> ||
 592         <var>test_condition2</var></code></dt>
 593       <dd>true if either <var>test_condition1</var> or
 594       <var>test_condition2</var> is true</dd>
 595     </dl>
 596
 597     <p>"<code>=</code>" and "<code>!=</code>" bind more tightly than
 598     "<code>&amp;&amp;</code>" and "<code>||</code>". "<code>!</code>" binds
 599     most tightly. Thus, the following are equivalent:</p>
 600
 601     <div class="example"><p><code>
 602       &lt;!--#if expr="$a = test1 &amp;&amp; $b = test2" --&gt;<br />
 603       &lt;!--#if expr="($a = test1) &amp;&amp; ($b = test2)" --&gt;
 604     </code></p></div>
 605
 606     <p>The boolean operators <code>&amp;&amp;</code> and <code>||</code>
 607     share the same priority. So if you want to bind such an operator more
 608     tightly, you should use parentheses.</p>
 609
 610     <p>Anything that's not recognized as a variable or an operator
 611     is treated as a string. Strings can also be quoted:
 612     <code>'string'</code>. Unquoted strings can't contain whitespace
 613     (blanks and tabs) because it is used to separate tokens such as
 614     variables. If multiple strings are found in a row, they are
 615     concatenated using blanks. So,</p>
 616
 617     <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 />
 618       <br />
 619       and<br />
 620       <br />
 621       <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>
 622
 623     <div class="note"><h3>Optimization of Boolean Expressions</h3>
 624       <p>If the expressions become more complex and slow down processing
 625       significantly, you can try to optimize them according to the
 626       evaluation rules:</p>
 627       <ul>
 628       <li>Expressions are evaluated from left to right</li>
 629       <li>Binary boolean operators (<code>&amp;&amp;</code> and <code>||</code>)
 630           are short circuited wherever possible. In conclusion with the rule
 631           above that means, <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> evaluates at first
 632           the left expression. If the left result is sufficient to determine
 633           the end result, processing stops here. Otherwise it evaluates the
 634           right side and computes the end result from both left and right
 635           results.</li>
 636       <li>Short circuit evaluation is turned off as long as there are regular
 637           expressions to deal with. These must be evaluated to fill in the
 638           backreference variables (<code>$1</code> .. <code>$9</code>).</li>
 639       </ul>
 640       <p>If you want to look how a particular expression is handled, you can
 641       recompile <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> using the
 642       <code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
 643       parsed expression tokenizer information, the parse tree and how it is
 644       evaluated into the output sent to the client.</p>
 645     </div>
 646
 647     <div class="note"><h3>Escaping slashes in regex strings</h3>
 648      <p>All slashes which are not intended to act as delimiters in your regex must
 649      be escaped.  This is regardless of their meaning to the regex engine.</p>
 650     </div>
 651 </div>
 652 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 653 <div class="directive-section"><h2><a name="SSIEnableAccess" id="SSIEnableAccess">SSIEnableAccess</a> <a name="ssienableaccess" id="ssienableaccess">Directive</a></h2>
 654 <table class="directive">
 655 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable the -A flag during conditional flow control processing.</td></tr>
 656 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEnableAccess on|off</code></td></tr>
 657 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEnableAccess off</code></td></tr>
 658 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
 659 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 660 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 661 </table>
 662     <p>The <code class="directive">SSIEnableAccess</code> directive controls whether
 663     the -A test is enabled during conditional flow control processing.
 664     <code class="directive">SSIEnableAccess</code> can take on the following values:</p>
 665
 666     <dl>
 667
 668       <dt><code>off</code></dt>
 669       <dd>&lt;!--#if expr="-A /foo"--&gt; will be interpreted as a series
 670       of string and regular expression tokens, the -A has no special
 671       meaning.</dd>
 672
 673       <dt><code>on</code></dt>
 674       <dd>&lt;!--#if expr="-A /foo"--&gt; will evaluate to false if the
 675       URL /foo is inaccessible by configuration, or true otherwise.</dd>
 676
 677     </dl>
 678
 679
 680 </div>
 681 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 682 <div class="directive-section"><h2><a name="SSIEndTag" id="SSIEndTag">SSIEndTag</a> <a name="ssiendtag" id="ssiendtag">Directive</a></h2>
 683 <table class="directive">
 684 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that ends an include element</td></tr>
 685 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIEndTag <var>tag</var></code></td></tr>
 686 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIEndTag "--&gt;"</code></td></tr>
 687 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 688 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 689 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 690 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 691 </table>
 692     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 693     looks for to mark the end of an include element.</p>
 694
 695     <div class="example"><h3>Example</h3><p><code>
 696       SSIEndTag "%&gt;"
 697     </code></p></div>
 698
 699
 700 <h3>See also</h3>
 701 <ul>
 702 <li><code class="directive"><a href="#ssistarttag">SSIStartTag</a></code></li>
 703 </ul>
 704 </div>
 705 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 706 <div class="directive-section"><h2><a name="SSIErrorMsg" id="SSIErrorMsg">SSIErrorMsg</a> <a name="ssierrormsg" id="ssierrormsg">Directive</a></h2>
 707 <table class="directive">
 708 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Error message displayed when there is an SSI
 709 error</td></tr>
 710 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIErrorMsg <var>message</var></code></td></tr>
 711 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIErrorMsg "[an error occurred while processing this
 712 directive]"</code></td></tr>
 713 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 714 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 715 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 716 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 717 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 718 </table>
 719     <p>The <code class="directive">SSIErrorMsg</code> directive changes the error
 720     message displayed when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> encounters an
 721     error. For production servers you may consider changing the default
 722     error message to <code>"&lt;!-- Error --&gt;"</code> so that
 723     the message is not presented to the user.</p>
 724
 725     <p>This directive has the same effect as the <code>&lt;!--#config
 726     errmsg=<var>message</var> --&gt;</code> element.</p>
 727
 728     <div class="example"><h3>Example</h3><p><code>
 729       SSIErrorMsg "&lt;!-- Error --&gt;"
 730     </code></p></div>
 731
 732 </div>
 733 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 734 <div class="directive-section"><h2><a name="SSIStartTag" id="SSIStartTag">SSIStartTag</a> <a name="ssistarttag" id="ssistarttag">Directive</a></h2>
 735 <table class="directive">
 736 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String that starts an include element</td></tr>
 737 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIStartTag <var>tag</var></code></td></tr>
 738 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIStartTag "&lt;!--#"</code></td></tr>
 739 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
 740 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 741 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 742 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 743 </table>
 744     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 745     looks for to mark an include element to process.</p>
 746
 747     <p>You may want to use this option if you have 2 servers parsing the
 748     output of a file each processing different commands (possibly at
 749     different times).</p>
 750
 751     <div class="example"><h3>Example</h3><p><code>
 752       SSIStartTag "&lt;%"<br />
 753       SSIEndTag   "%&gt;"
 754     </code></p></div>
 755
 756     <p>The example given above, which also specifies a matching
 757     <code class="directive"><a href="#ssiendtag">SSIEndTag</a></code>, will
 758     allow you to use SSI directives as shown in the example
 759     below:</p>
 760
 761     <div class="example"><h3>SSI directives with alternate start and end tags</h3><p><code>
 762       &lt;%printenv %&gt;
 763     </code></p></div>
 764
 765 <h3>See also</h3>
 766 <ul>
 767 <li><code class="directive"><a href="#ssiendtag">SSIEndTag</a></code></li>
 768 </ul>
 769 </div>
 770 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 771 <div class="directive-section"><h2><a name="SSITimeFormat" id="SSITimeFormat">SSITimeFormat</a> <a name="ssitimeformat" id="ssitimeformat">Directive</a></h2>
 772 <table class="directive">
 773 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configures the format in which date strings are
 774 displayed</td></tr>
 775 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSITimeFormat <var>formatstring</var></code></td></tr>
 776 <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>
 777 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 778 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 779 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 780 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 781 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later.</td></tr>
 782 </table>
 783 <p>This directive changes the format in which date strings are displayed
 784     when echoing <code>DATE</code> environment variables. The
 785     <var>formatstring</var> is as in <code>strftime(3)</code> from the
 786     C standard library.</p>
 787
 788     <p>This directive has the same effect as the <code>&lt;!--#config
 789     timefmt=<var>formatstring</var> --&gt;</code> element.</p>
 790
 791     <div class="example"><h3>Example</h3><p><code>
 792       SSITimeFormat "%R, %B %d, %Y"
 793     </code></p></div>
 794
 795     <p>The above directive would cause times to be displayed in the
 796     format "22:26, June 14, 2002".</p>
 797
 798 </div>
 799 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 800 <div class="directive-section"><h2><a name="SSIUndefinedEcho" id="SSIUndefinedEcho">SSIUndefinedEcho</a> <a name="ssiundefinedecho" id="ssiundefinedecho">Directive</a></h2>
 801 <table class="directive">
 802 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>String displayed when an unset variable is echoed</td></tr>
 803 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SSIUndefinedEcho <var>string</var></code></td></tr>
 804 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>SSIUndefinedEcho "(none)"</code></td></tr>
 805 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 806 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>All</td></tr>
 807 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 808 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 809 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.34 and later.</td></tr>
 810 </table>
 811     <p>This directive changes the string that <code class="module"><a href="../mod/mod_include.html">mod_include</a></code>
 812     displays when a variable is not set and "echoed".</p>
 813
 814     <div class="example"><h3>Example</h3><p><code>
 815       SSIUndefinedEcho "&lt;!-- undef --&gt;"
 816     </code></p></div>
 817
 818 </div>
 819 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 820 <div class="directive-section"><h2><a name="XBitHack" id="XBitHack">XBitHack</a> <a name="xbithack" id="xbithack">Directive</a></h2>
 821 <table class="directive">
 822 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Parse SSI directives in files with the execute bit
 823 set</td></tr>
 824 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>XBitHack on|off|full</code></td></tr>
 825 <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>XBitHack off</code></td></tr>
 826 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 827 <tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>
 828 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 829 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_include</td></tr>
 830 </table>
 831     <p>The <code class="directive">XBitHack</code> directive controls the parsing
 832     of ordinary html documents. This directive only affects files associated
 833     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>
 834
 835     <dl>
 836       <dt><code>off</code></dt>
 837       <dd>No special treatment of executable files.</dd>
 838
 839       <dt><code>on</code></dt>
 840       <dd>Any <code>text/html</code> file that has the user-execute bit
 841       set will be treated as a server-parsed html document.</dd>
 842
 843       <dt><code>full</code></dt>
 844       <dd>As for <code>on</code> but also test the group-execute bit.
 845       If it is set, then set the <code>Last-modified</code> date of the
 846       returned file to be the last modified time of the file. If
 847       it is not set, then no last-modified date is sent. Setting
 848       this bit allows clients and proxies to cache the result of
 849       the request.
 850
 851       <div class="note"><h3>Note</h3>
 852       <p>You would not want to use the full option, unless you assure the
 853       group-execute bit is unset for every SSI script which might <code>#include</code> a CGI or otherwise produces different output on
 854       each hit (or could potentially change on subsequent requests).</p>
 855       </div>
 856       </dd>
 857     </dl>
 858
 859
 860 </div>
 861 </div>
 862 <div class="bottomlang">
 863 <p><span>Available Languages: </span><a href="../en/mod/mod_include.html" title="English">&nbsp;en&nbsp;</a> |
 864 <a href="../ja/mod/mod_include.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a></p>
 865 </div><div id="footer">
 866 <p class="apache">Copyright 2008 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>
 867 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 868 </body></html>