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