1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 4<html xmlns="http://www.w3.org/1999/xhtml"> 5 <head> 6 <meta name="generator" content="HTML Tidy, see www.w3.org" /> 7 8 <title>Apache module mod_include</title> 9 </head> 10 <!-- Background white, links blue (unvisited), navy (visited), red (active) --> 11 12 <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" 13 vlink="#000080" alink="#FF0000"> 14 <div align="CENTER"> 15 <img src="../images/sub.gif" alt="[APACHE DOCUMENTATION]" /> 16 17 <h3>Apache HTTP Server Version 1.3</h3> 18 </div> 19 20 21 <h1 align="CENTER">Module mod_include</h1> 22 23 <p>This module provides for documents with Server Side Includes 24 (SSI).</p> 25 26 <p><a href="module-dict.html#Status" 27 rel="Help"><strong>Status:</strong></a> Base<br /> 28 <a href="module-dict.html#SourceFile" 29 rel="Help"><strong>Source File:</strong></a> 30 mod_include.c<br /> 31 <a href="module-dict.html#ModuleIdentifier" 32 rel="Help"><strong>Module Identifier:</strong></a> 33 includes_module</p> 34 35 <h2>Summary</h2> 36 37 <p>This module provides a handler which will process files 38 before they are sent to the client. The processing is 39 controlled by specially formated SGML comments, referred to as 40 <em>elements</em>. These elements allow conditional text, the 41 inclusion other files or programs, as well as the setting and 42 printing of environment variables.</p> 43 44 <p>For an introduction to this topic, we also provide a <a 45 href="../howto/ssi.html">tutorial on Server Side 46 Includes</a>.</p> 47 48 <h2>Directives</h2> 49 50 <ul> 51 <li><a href="#xbithack">XBitHack</a></li> 52 </ul> 53 54 <p>See also: <a href="core.html#options">Options</a> and <a 55 href="mod_mime.html#addhandler">AddHandler</a>.</p> 56 57 <h2>Enabling Server-Side Includes</h2> 58 Any document with handler of "server-parsed" will be parsed by 59 this module, if the <code>Includes</code> option is set. If 60 documents containing server-side include directives are given 61 the extension .shtml, the following directives will make Apache 62 parse them and assign the resulting document the mime type of 63 <code>text/html</code>: 64<pre> 65AddType text/html .shtml 66AddHandler server-parsed .shtml 67</pre> 68 The following directive must be given for the directories 69 containing the shtml files (typically in a 70 <code><Directory></code> section, but this directive is 71 also valid .htaccess files if <code>AllowOverride 72 Options</code> is set): 73<pre> 74Options +Includes 75</pre> 76 Alternatively the <a href="#xbithack"><code>XBitHack</code></a> 77 directive can be used to parse normal (<code>text/html</code>) 78 files, based on file permissions. 79 80 <p>For backwards compatibility, documents with mime type 81 <code>text/x-server-parsed-html</code> or 82 <code>text/x-server-parsed-html3</code> will also be parsed 83 (and the resulting output given the mime type 84 <code>text/html</code>).</p> 85 86 <h2>Basic Elements</h2> 87 The document is parsed as an HTML document, with special 88 commands embedded as SGML comments. A command has the syntax: 89 90 <blockquote> 91 <code><!--#</code><em>element attribute=value 92 attribute=value ...</em> <code>--></code> 93 </blockquote> 94 The value will often be enclosed in double quotes; many 95 commands only allow a single attribute-value pair. Note that 96 the comment terminator (<samp>--></samp>) should be preceded 97 by whitespace to ensure that it isn't considered part of an SSI 98 token. Note that the leading <samp><!--#</samp> is <em>one</em> 99 token and may not contain any whitespaces.</p> 100 101 <p>The allowed elements are:</p> 102 103 <dl> 104 <dt><strong>config</strong></dt> 105 106 <dd> 107 This command controls various aspects of the parsing. The 108 valid attributes are: 109 110 <dl> 111 <dt><strong>errmsg</strong></dt> 112 113 <dd>The value is a message that is sent back to the 114 client if an error occurs whilst parsing the 115 document.</dd> 116 117 <dt><strong>sizefmt</strong></dt> 118 119 <dd>The value sets the format to be used which displaying 120 the size of a file. Valid values are <code>bytes</code> 121 for a count in bytes, or <code>abbrev</code> for a count 122 in Kb or Mb as appropriate.</dd> 123 124 <dt><strong>timefmt</strong></dt> 125 126 <dd>The value is a string to be used by the 127 <code>strftime(3)</code> library routine when printing 128 dates.</dd> 129 </dl> 130 </dd> 131 132 <dt><strong><a id="echo" name="echo">echo</a></strong></dt> 133 134 <dd> 135 This command prints one of the <a href="#includevars">include 136 variables</a>, defined 137 below. If the variable is unset, it is printed as 138 <code>(none)</code>. Any dates printed are subject to the 139 currently configured <code>timefmt</code>. Attributes: 140 141 <dl> 142 <dt><strong>var</strong></dt> 143 144 <dd>The value is the name of the variable to print.</dd> 145 146 <dt><strong>encoding</strong></dt> 147 148 <dd>Specifies how Apache should encode special characters 149 contained in the variable before outputting them. If set 150 to "none", no encoding will be done. If set to "url", 151 then URL encoding (also known as %-encoding; this is 152 appropriate for use within URLs in links, etc.) will be 153 performed. At the start of an <code>echo</code> element, 154 the default is set to "entity", resulting in entity 155 encoding (which is appropriate in the context of a 156 block-level HTML element, eg. a paragraph of text). This 157 can be changed by adding an <code>encoding</code> 158 attribute, which will remain in effect until the next 159 <code>encoding</code> attribute is encountered or the 160 element ends, whichever comes first. Note that the 161 <code>encoding</code> attribute must <em>precede</em> the 162 corresponding <code>var</code> attribute to be effective, 163 and that only special characters as defined in the 164 ISO-8859-1 character encoding will be encoded. This 165 encoding process may not have the desired result if a 166 different character encoding is in use. Apache 1.3.12 and 167 above; previous versions do no encoding.</dd> 168 </dl> 169 </dd> 170 171 <dt><strong>exec</strong></dt> 172 173 <dd> 174 The exec command executes a given shell command or CGI 175 script. The IncludesNOEXEC <a 176 href="core.html#options">Option</a> disables this command 177 completely. The valid attributes are: 178 179 <dl> 180 <dt><strong>cgi</strong></dt> 181 182 <dd> 183 The value specifies a (%-encoded) URL relative path to 184 the CGI script. If the path does not begin with a (/), 185 then it is taken to be relative to the current 186 document. The document referenced by this path is 187 invoked as a CGI script, even if the server would not 188 normally recognize it as such. However, the directory 189 containing the script must be enabled for CGI scripts 190 (with <a 191 href="mod_alias.html#scriptalias">ScriptAlias</a> or 192 the ExecCGI <a href="core.html#options">Option</a>). 193 194 <p>The CGI script is given the PATH_INFO and query 195 string (QUERY_STRING) of the original request from the 196 client; these cannot be specified in the URL path. The 197 include variables will be available to the script in 198 addition to the standard <a href="mod_cgi.html">CGI</a> 199 environment.</p> 200 201 <p>For example:</p> 202 203 <code><!--#exec cgi="/cgi-bin/example.cgi" --></code> 204 205 <p>If the script returns a Location: header instead of 206 output, then this will be translated into an HTML 207 anchor.</p> 208 209 <p>The <code><a href="#includevirtual">include 210 virtual</a></code> element should be 211 used in preference to <code>exec cgi</code>. In particular, 212 if you need to pass additional arguments to a CGI program, 213 using the query string, this cannot be done with <code>exec 214 cgi</code>, but can be done with <code>include 215 virtual</code>, as shown here:</p> 216 217 <code><!--#include virtual="/cgi-bin/example.cgi?argument=value" --></code> 218 </dd> 219 220 <dt><strong>cmd</strong></dt> 221 222 <dd> 223 <p>The server will execute the given string using 224 <code>/bin/sh</code>. The <a 225 href="#includevars">include variables</a> are available 226 to the command, in addition to the usual set of CGI 227 variables.</p> 228 229 <p>The use of <code><a href="#includevirtual">#include 230 virtual</a></code> is almost always 231 prefered to using either <code>#exec cgi</code> or <code>#exec 232 cmd</code>. The former (<code>#include virtual</code>) used the 233 standard Apache sub-request mechanism to include files or 234 scripts. It is much better tested and maintained.</p> 235 236 <p>In addition, on some platforms, like Win32, and on unix 237 when using suexec, you cannot pass arguments to a command in 238 an <code>exec</code> directive, or otherwise include spaces in 239 the command. Thus, while the following will work under a 240 non-suexec configuration on unix, it will not produce the 241 desired result under Win32, or when running suexec:</p> 242 243 <code><!--#exec cmd="perl /path/to/perlscript arg1 arg2" --></code> 244 245 </dd> 246 </dl> 247 </dd> 248 249 <dt><strong>fsize</strong></dt> 250 251 <dd> 252 This command prints the size of the specified file, subject 253 to the <code>sizefmt</code> format specification. 254 Attributes: 255 256 <dl> 257 <dt><strong>file</strong></dt> 258 259 <dd>The value is a path relative to the directory 260 containing the current document being parsed.</dd> 261 262 <dt><strong>virtual</strong></dt> 263 264 <dd>The value is a (%-encoded) URL-path relative to the 265 current document being parsed. If it does not begin with 266 a slash (/) then it is taken to be relative to the 267 current document.</dd> 268 </dl> 269 </dd> 270 271 <dt><strong>flastmod</strong></dt> 272 273 <dd>This command prints the last modification date of the 274 specified file, subject to the <code>timefmt</code> format 275 specification. The attributes are the same as for the 276 <code>fsize</code> command.</dd> 277 278 <dt><strong>include</strong></dt> 279 280 <dd> 281 This command inserts the text of another document or file 282 into the parsed file. Any included file is subject to the 283 usual access control. If the directory containing the 284 parsed file has the <a href="core.html#options">Option</a> 285 IncludesNOEXEC set, and the including the document would 286 cause a program to be executed, then it will not be 287 included; this prevents the execution of CGI scripts. 288 Otherwise CGI scripts are invoked as normal using the 289 complete URL given in the command, including any query 290 string. 291 292 <p>An attribute defines the location of the document; the 293 inclusion is done for each attribute given to the include 294 command. The valid attributes are:</p> 295 296 <dl> 297 <dt><strong>file</strong></dt> 298 299 <dd>The value is a path relative to the directory 300 containing the current document being parsed. It cannot 301 contain <code>../</code>, nor can it be an absolute path. 302 Therefore, you cannot include files that are outside of the 303 document root, or above the current document in the directory 304 structure. 305 The <code>virtual</code> attribute should always be used 306 in preference to this one.</dd> 307 308 <dt><strong><a name="includevirtual">virtual</a></strong></dt> 309 310 <dd> 311 <p>The value is a (%-encoded) URL relative to the 312 current document being parsed. The URL cannot contain a 313 scheme or hostname, only a path and an optional query 314 string. If it does not begin with a slash (/) then it is 315 taken to be relative to the current document.</p> 316 317 <p>A URL is constructed from the attribute, and the output the 318 server would return if the URL were accessed by the client 319 is included in the parsed output. Thus included files can 320 be nested.</p> 321 322 <p>If the specified URL is a CGI program, the program will 323 be executed and its output inserted in place of the directive 324 in the parsed file. You may include a query string in a CGI 325 url:</p> 326 327 <code><!--#include virtual="/cgi-bin/example.cgi?argument=value" --></code> 328 329 <p><code>include virtual</code> should be used in preference 330 to <code>exec cgi</code> to include the output of CGI 331 programs into an HTML document. 332 </dd> 333 </dl> 334 </dd> 335 336 <dt><strong>printenv</strong></dt> 337 338 <dd> 339 <p>This prints out a listing of all existing variables and 340 their values. Starting with Apache 1.3.12, special characters 341 are entity encoded (see the <a 342 href="#echo"><code>echo</code></a> element for details) 343 before being output. There are no attributes.</p> 344 345 <p>For example:</p> 346 347 <p><code><!--#printenv --></code></p> 348 349 <p>The <strong>printenv</strong> element is available only in 350 Apache 1.2 and above.</p> 351 </dd> 352 <dt><strong>set</strong></dt> 353 354 <dd> 355 This sets the value of a variable. Attributes: 356 357 <dl> 358 <dt><strong>var</strong></dt> 359 360 <dd>The name of the variable to set.</dd> 361 362 <dt><strong>value</strong></dt> 363 364 <dd>The value to give a variable.</dd> 365 </dl> 366 <p> 367 For example: <code><!--#set var="category" value="help" 368 --></code></p> 369 370 <p>The <strong>set</strong> element is available only in 371 Apache 1.2 and above.</p> 372 </dd> 373 </dl> 374 375 <h2><a name="includevars">Include Variables</a></h2> 376 In addition to the variables in the standard CGI environment, 377 these are available for the <code>echo</code> command, for 378 <code>if</code> and <code>elif</code>, and to any program 379 invoked by the document. 380 381 <dl> 382 <dt>DATE_GMT</dt> 383 384 <dd>The current date in Greenwich Mean Time.</dd> 385 386 <dt>DATE_LOCAL</dt> 387 388 <dd>The current date in the local time zone.</dd> 389 390 <dt>DOCUMENT_NAME</dt> 391 392 <dd>The filename (excluding directories) of the document 393 requested by the user.</dd> 394 395 <dt>DOCUMENT_URI</dt> 396 397 <dd>The (%-decoded) URL path of the document requested by the 398 user. Note that in the case of nested include files, this is 399 <em>not</em> then URL for the current document.</dd> 400 401 <dt>LAST_MODIFIED</dt> 402 403 <dd>The last modification date of the document requested by 404 the user.</dd> 405 406 <dt>USER_NAME</dt> 407 408 <dd>Contains the owner of the file which included it.</dd> 409 410 </dl> 411 412 <h2>Variable Substitution</h2> 413 414 <p>Variable substitution is done within quoted strings in most 415 cases where they may reasonably occur as an argument to an SSI 416 directive. This includes the <samp>config</samp>, 417 <samp>exec</samp>, <samp>flastmod</samp>, <samp>fsize</samp>, 418 <samp>include</samp>, and <samp>set</samp> directives, as well 419 as the arguments to conditional operators. You can insert a 420 literal dollar sign into the string using backslash 421 quoting:</p> 422<pre> 423 <!--#if expr="$a = \$test" --> 424</pre> 425 426 <p>If a variable reference needs to be substituted in the 427 middle of a character sequence that might otherwise be 428 considered a valid identifier in its own right, it can be 429 disambiguated by enclosing the reference in braces, 430 <em>à la</em> shell substitution:</p> 431<pre> 432 <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> 433</pre> 434 435 <p>This will result in the <samp>Zed</samp> variable being set 436 to "<samp>X_Y</samp>" if <samp>REMOTE_HOST</samp> is 437 "<samp>X</samp>" and <samp>REQUEST_METHOD</samp> is 438 "<samp>Y</samp>".</p> 439 440 <p>EXAMPLE: the below example will print "in foo" if the 441 DOCUMENT_URI is /foo/file.html, "in bar" if it is 442 /bar/file.html and "in neither" otherwise:</p> 443<pre> 444 <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> 445 in foo 446 <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> 447 in bar 448 <!--#else --> 449 in neither 450 <!--#endif --> 451</pre> 452 453 <h2><a id="flowctrl" name="flowctrl">Flow Control 454 Elements</a></h2> 455 These are available in Apache 1.2 and above. The basic flow 456 control elements are: 457<pre> 458 <!--#if expr="<em>test_condition</em>" --> 459 <!--#elif expr="<em>test_condition</em>" --> 460 <!--#else --> 461 <!--#endif --> 462</pre> 463 464 <p>The <strong><code>if</code></strong> element works like an 465 if statement in a programming language. The test condition is 466 evaluated and if the result is true, then the text until the 467 next <strong><code>elif</code></strong>, 468 <strong><code>else</code></strong>. or 469 <strong><code>endif</code></strong> element is included in the 470 output stream.</p> 471 472 <p>The <strong><code>elif</code></strong> or 473 <strong><code>else</code></strong> statements are be used the 474 put text into the output stream if the original test_condition 475 was false. These elements are optional.</p> 476 477 <p>The <strong><code>endif</code></strong> element ends the 478 <strong><code>if</code></strong> element and is required.</p> 479 480 <p><em>test_condition</em> is one of the following:</p> 481 482 <dl> 483 <dt><em>string</em></dt> 484 485 <dd>true if <em>string</em> is not empty</dd> 486 487 <dt><em>string1</em> = <em>string2</em><br /> 488 <em>string1</em> != <em>string2</em><br /> 489 <em>string1</em> < <em>string2</em><br /> 490 <em>string1</em> <= <em>string2</em><br /> 491 <em>string1</em> > <em>string2</em><br /> 492 <em>string1</em> >= <em>string2</em></dt> 493 494 <dd>Compare string1 with string 2. If string2 has the form 495 <em>/string/</em> then it is compared as a regular 496 expression. Regular expressions have the same syntax as those 497 found in the Unix <samp>egrep</samp> command.</dd> 498 499 <dt>( <em>test_condition</em> )</dt> 500 501 <dd>true if <em>test_condition</em> is true</dd> 502 503 <dt>! <em>test_condition</em></dt> 504 505 <dd>true if <em>test_condition</em> is false</dd> 506 507 <dt><em>test_condition1</em> && 508 <em>test_condition2</em></dt> 509 510 <dd>true if both <em>test_condition1</em> and 511 <em>test_condition2</em> are true</dd> 512 513 <dt><em>test_condition1</em> || <em>test_condition2</em></dt> 514 515 <dd>true if either <em>test_condition1</em> or 516 <em>test_condition2</em> is true</dd> 517 </dl> 518 519 <p>"<em>=</em>" and "<em>!=</em>" bind more tightly than 520 "<em>&&</em>" and "<em>||</em>". "<em>!</em>" binds 521 most tightly. Thus, the following are equivalent:</p> 522<pre> 523 <!--#if expr="$a = test1 && $b = test2" --> 524 <!--#if expr="($a = test1) && ($b = test2)" --> 525</pre> 526 527 <p>Anything that's not recognized as a variable or an operator 528 is treated as a string. Strings can also be quoted: 529 <em>'string'</em>. Unquoted strings can't contain whitespace 530 (blanks and tabs) because it is used to separate tokens such as 531 variables. If multiple strings are found in a row, they are 532 concatenated using blanks. So,</p> 533<pre> 534 <em>string1 string2</em> results in <em>string1 string2</em> 535 <em>'string1 string2'</em> results in <em>string1 string2</em> 536</pre> 537 538 <h2>Using Server Side Includes for ErrorDocuments</h2> 539 There is <a href="../misc/custom_errordocs.html">a document</a> 540 which describes how to use the features of mod_include to offer 541 internationalized customized server error documents. 542 <hr /> 543 544 <h2><a id="xbithack" name="xbithack">XBitHack</a> 545 directive</h2> 546 547 <a href="directive-dict.html#Syntax" 548 rel="Help"><strong>Syntax:</strong></a> XBitHack 549 on|off|full<br /> 550 <a href="directive-dict.html#Default" 551 rel="Help"><strong>Default:</strong></a> <code>XBitHack 552 off</code><br /> 553 <a href="directive-dict.html#Context" 554 rel="Help"><strong>Context:</strong></a> server config, virtual 555 host, directory, .htaccess<br /> 556 <a href="directive-dict.html#Override" 557 rel="Help"><strong>Override:</strong></a> Options<br /> 558 <a href="directive-dict.html#Status" 559 rel="Help"><strong>Status:</strong></a> Base<br /> 560 <a href="directive-dict.html#Module" 561 rel="Help"><strong>Module:</strong></a> mod_include 562 563 <p>The XBitHack directives controls the parsing of ordinary 564 html documents. This directive only affects files associated 565 with the MIME type <code>text/html</code>. XBitHack can take on 566 the following values:</p> 567 568 <dl> 569 <dt>off</dt> 570 571 <dd>No special treatment of executable files.</dd> 572 573 <dt>on</dt> 574 575 <dd>Any file that has the user-execute bit set will be 576 treated as a server-parsed html document.</dd> 577 578 <dt>full</dt> 579 580 <dd> 581 As for <code>on</code> but also test the group-execute bit. 582 If it is set, then set the Last-modified date of the 583 returned file to be the last modified time of the file. If 584 it is not set, then no last-modified date is sent. Setting 585 this bit allows clients and proxies to cache the result of 586 the request. 587 588 <p><strong>Note:</strong> you would not want to use this, 589 for example, when you <code>#include</code> a CGI that 590 produces different output on each hit (or potentially 591 depends on the hit).</p> 592 </dd> 593 </dl> 594 595 <p> <hr /> 596 597 <h3 align="CENTER">Apache HTTP Server Version 1.3</h3> 598 <a href="./"><img src="../images/index.gif" alt="Index" /></a> 599 <a href="../"><img src="../images/home.gif" alt="Home" /></a> 600 601 </p> 602 </body> 603</html> 604
