mod_include.xml revision 6345c3b5617ee187a43e4c9d778b84706c967be2
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<!-- $LastChangedRevision$ -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Licensed to the Apache Software Foundation (ASF) under one or more
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe contributor license agreements. See the NOTICE file distributed with
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe this work for additional information regarding copyright ownership.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe The ASF licenses this file to You under the Apache License, Version 2.0
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe (the "License"); you may not use this file except in compliance with
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the License. You may obtain a copy of the License at
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Unless required by applicable law or agreed to in writing, software
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe distributed under the License is distributed on an "AS IS" BASIS,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe See the License for the specific language governing permissions and
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe limitations under the License.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Server-parsed html documents (Server Side Includes)</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This module provides a filter which will process files
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe before they are sent to the client. The processing is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe controlled by specially formatted SGML comments, referred to as
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dfn>elements</dfn>. These elements allow conditional text, the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe inclusion of other files or programs, as well as the setting and
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe printing of environment variables.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<seealso><directive module="core">Options</directive></seealso>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<seealso><directive module="core">AcceptPathInfo</directive></seealso>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<seealso><a href="/howto/ssi.html">SSI Tutorial</a></seealso>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Server Side Includes are implemented by the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>INCLUDES</code> <a href="/filter.html">filter</a>. If
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe documents containing server-side include directives are given
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the extension .shtml, the following directives will make Apache
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe parse them and assign the resulting document the mime type of
ceaa05c302b4a0013174f4344c0907df84f7390dwroweAddOutputFilter INCLUDES .shtml
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The following directive must be given for the directories
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe containing the shtml files (typically in a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="core" type="section">Directory</directive> section,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe but this directive is also valid in <code>.htaccess</code> files if
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="core">AllowOverride</directive> <code>Options</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is set):</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Options +Includes
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>For backwards compatibility, the <code>server-parsed</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <a href="/handler.html">handler</a> also activates the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe INCLUDES filter. As well, Apache will activate the INCLUDES
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe filter for any document with mime type
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>text/x-server-parsed-html3</code> (and the resulting
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe output will have the mime type <code>text/html</code>).</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe href="/howto/ssi.html">Tutorial on Server Side Includes</a>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Files processed for server-side includes no longer accept
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe requests with <code>PATH_INFO</code> (trailing pathname information)
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe by default. You can use the <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe configure the server to accept requests with <code>PATH_INFO</code>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<section id="elements"><title>Available Elements</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The document is parsed as an HTML document, with special
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe commands embedded as SGML comments. A command has the syntax: </p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#<var>element</var> <var>attribute</var>=<var>value</var>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The value will often be enclosed in double quotes, but single
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe quotes (<code>'</code>) and backticks (<code>`</code>) are also
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe possible. Many commands only allow a single attribute-value pair.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Note that the comment terminator (<code>--></code>) should be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe preceded by whitespace to ensure that it isn't considered part of
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe an SSI token. Note that the leading <code><!--#</code> is <em>one</em>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe token and may not contain any whitespaces.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The allowed elements are listed in the following table:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.config">config</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.echo">echo</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.exec">exec</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.fsize">fsize</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.flastmod">flastmod</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.include">include</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <tr><td><code><a href="#element.printenv">printenv</a></code></td>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg <tr><td><code><a href="#element.set">set</a></code></td>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>SSI elements may be defined by modules other than
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe href="#element.exec">exec</a></code> element is provided by
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <module>mod_cgi</module>, and will only be available if this
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe module is loaded.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.config"><title>The config Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This command controls various aspects of the parsing. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe valid attributes are:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dt><code>echomsg</code> (<em>Apache 2.1 and later</em>)</dt>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>The value is a message that is sent back to the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe client if the <code><a href="#element.echo">echo</a></code> element
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe attempts to echo an undefined variable. This overrides any <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe module="mod_include">SSIUndefinedEcho</directive> directives.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#config errmsg="[Value Undefined]" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>The value is a message that is sent back to the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe client if an error occurs while parsing the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe document. This overrides any <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe module="mod_include">SSIErrorMsg</directive> directives.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#config errmsg="[Oops, something broke.]" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>The value sets the format to be used when displaying
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the size of a file. Valid values are <code>bytes</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe for a count in bytes, or <code>abbrev</code> for a count
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe in Kb or Mb as appropriate, for example a size of 1024 bytes
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe will be printed as "1K".</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#config sizefmt="abbrev" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>strftime(3)</code> library routine when printing
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.echo"><title>The echo Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This command prints one of the <a href="#includevars">include
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe variables</a> defined below. If the variable is unset, the result is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >SSIUndefinedEcho</directive> directive. Any dates printed are
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe subject to the currently configured <code>timefmt</code>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The value is the name of the variable to print.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>Specifies whether Apache should strip an encoding from
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the variable before processing the variable further. The default
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is <code>none</code>, where no decoding will be done. If set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>url</code>, then URL decoding (also known as %-encoding;
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe this is appropriate for use within URLs in links, etc.) will be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe application/x-www-form-urlencoded compatible encoding (found in
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe query strings) will be stripped. If set to <code>base64</code>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe base64 will be decoded, and if set to <code>entity</code>, HTML
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe entity encoding will be stripped. Decoding is done prior to any
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe further encoding on the variable. Multiple encodings can be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe stripped by specifying more than one comma separated encoding.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe The decoding setting will remain in effect until the next decoding
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe attribute is encountered, or the element ends.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>decoding</code> attribute must <em>precede</em> the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe corresponding <code>var</code> attribute to be effective.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>Specifies how Apache should encode special characters
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe contained in the variable before outputting them. If set
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to <code>none</code>, no encoding will be done. If set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>url</code>, then URL encoding (also known as %-encoding;
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe this is appropriate for use within URLs in links, etc.) will be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe application/x-www-form-urlencoded compatible encoding will be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe performed instead, and should be used with query strings. If set
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to <code>base64</code>, base64 encoding will be performed. At
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the start of an <code>echo</code> element, the default is set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>entity</code>, resulting in entity encoding (which is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe appropriate in the context of a block-level HTML element,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <em>e.g.</em> a paragraph of text). This can be changed by adding
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg an <code>encoding</code> attribute, which will remain in effect
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg until the next <code>encoding</code> attribute is encountered or
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg the element ends, whichever comes first.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>encoding</code> attribute must <em>precede</em> the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe corresponding <code>var</code> attribute to be effective.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe In order to avoid cross-site scripting issues, you should
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.exec"><title>The exec Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>exec</code> command executes a given shell command or
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe CGI script. It requires <module>mod_cgi</module> to be present
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe in the server. If <directive module="core">Options</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>IncludesNOEXEC</code> is set, this command is completely
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe disabled. The valid attributes are:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the CGI script. If the path does not begin with a slash (/),
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe then it is taken to be relative to the current
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg document. The document referenced by this path is
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg invoked as a CGI script, even if the server would not
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg normally recognize it as such. However, the directory
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe containing the script must be enabled for CGI scripts
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe (with <directive module="mod_alias">ScriptAlias</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The CGI script is given the <code>PATH_INFO</code> and query
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe string (<code>QUERY_STRING</code>) of the original request from the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe client; these <em>cannot</em> be specified in the URL path. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe include variables will be available to the script in addition to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the standard <a href="mod_cgi.html">CGI</a> environment.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If the script returns a <code>Location:</code> header instead of
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe output, then this will be translated into an HTML anchor.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code><a href="#includevirtual">include virtual</a></code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe element should be used in preference to <code>exec cgi</code>. In
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe particular, if you need to pass additional arguments to a CGI program,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe using the query string, this cannot be done with <code>exec
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe cgi</code>, but can be done with <code>include virtual</code>, as
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe shown here:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >include variables</a> are available to the command, in addition
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to the usual set of CGI variables.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >#include virtual</a></code> is almost always prefered to using
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe either <code>#exec cgi</code> or <code>#exec cmd</code>. The former
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe (<code>#include virtual</code>) uses the standard Apache sub-request
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe mechanism to include files or scripts. It is much better tested and
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe maintained.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>In addition, on some platforms, like Win32, and on unix when
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe using <a href="/suexec.html">suexec</a>, you cannot pass arguments
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to a command in an <code>exec</code> directive, or otherwise include
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe spaces in the command. Thus, while the following will work under a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe non-suexec configuration on unix, it will not produce the desired
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe result under Win32, or when running suexec:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#exec cmd="perl /path/to/perlscript arg1 arg2" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.fsize"><title>The fsize Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This command prints the size of the specified file, subject
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to the <code>sizefmt</code> format specification. Attributes:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The value is a path relative to the directory
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe containing the current document being parsed.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The value is a (%-encoded) URL-path. If it does not begin with
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe a slash (/) then it is taken to be relative to the current document.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Note, that this does <em>not</em> print the size of any CGI output,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe but the size of the CGI script itself.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.flastmod"><title>The flastmod Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This command prints the last modification date of the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe specified file, subject to the <code>timefmt</code> format
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe specification. The attributes are the same as for the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code><a href="#element.fsize">fsize</a></code> command.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.include"><title>The include Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This command inserts the text of another document or file
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe into the parsed file. Any included file is subject to the usual
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe access control. If the directory containing the parsed file has
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>IncludesNOEXEC</code> set, then only documents with a text
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <glossary>MIME-type</glossary> (<code>text/plain</code>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>text/html</code> etc.) will be included. Otherwise CGI
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe scripts are invoked as normal using the complete URL given in
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the command, including any query string.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>An attribute defines the location of the document, and may
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe appear more than once in an include element; an inclusion is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe done for each attribute given to the include command in turn.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe The valid attributes are:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The value is a path relative to the directory
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe containing the current document being parsed. It cannot
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe contain <code>../</code>, nor can it be an absolute path.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Therefore, you cannot include files that are outside of the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe document root, or above the current document in the directory
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe structure. The <code>virtual</code> attribute should always be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe used in preference to this one.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dt><code><a id="includevirtual" name="includevirtual"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>The value is a (%-encoded) URL-path. The URL cannot contain a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe scheme or hostname, only a path and an optional query string. If it
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe does not begin with a slash (/) then it is taken to be relative to the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe current document.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>A URL is constructed from the attribute, and the output the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe server would return if the URL were accessed by the client is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe included in the parsed output. Thus included files can be nested.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If the specified URL is a CGI program, the program will be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe executed and its output inserted in place of the directive in the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe parsed file. You may include a query string in a CGI url:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p><code>include virtual</code> should be used in preference
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to <code>exec cgi</code> to include the output of CGI programs
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe into an HTML document.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If the <directive module="mod_request">KeptBodySize</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe directive is correctly configured and valid for this included
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe file, attempts to POST requests to the enclosing HTML document
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe will be passed through to subrequests as POST requests as well.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Without the directive, all subrequests are processed as GET
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe requests.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>The value is a (%-encoded) URL-path which is shown should a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe previous attempt to include a file or virtual attribute failed.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe To be effective, this attribute must be specified after the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe file or virtual attributes being covered. If the attempt to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe include the onerror path fails, or if onerror is not specified, the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe default error message will be included.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe # Simple example<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#include virtual="/not-exist.html" onerror="/error.html" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe # Dedicated onerror paths<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#include virtual="/path-a.html" onerror="/error-a.html" virtual="/path-b.html" onerror="/error-b.html" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.printenv"><title>The printenv Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This prints out a listing of all existing variables and
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe their values. Special characters are entity encoded (see the <code><a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe href="#element.echo">echo</a></code> element for details)
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe before being output. There are no attributes.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#printenv -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <section id="element.set"><title>The set Element</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>Specifies whether Apache should strip an encoding from
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the variable before processing the variable further. The default
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is <code>none</code>, where no decoding will be done. If set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>url</code>, <code>urlencoded</code>, <code>base64</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe application/x-www-form-urlencoded decoding, base64 decoding or HTML
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe entity decoding will be performed respectively. More than one
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe decoding can be specified by separating with commas. The decoding
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe setting will remain in effect until the next decoding attribute
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is encountered, or the element ends. The <code>decoding</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>Specifies how Apache should encode special characters
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe contained in the variable before setting them. The default is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>none</code>, where no encoding will be done. If set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>url</code>, <code>urlencoding</code>, <code>base64</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe application/x-www-form-urlencoded encoding, base64 encoding or
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe HTML entity encoding will be performed respectively. More than
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe one encoding can be specified by separating with commas. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe encoding setting will remain in effect until the next encoding
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe attribute is encountered, or the element ends. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>encoding</code> attribute must <em>precede</em> the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe corresponding <code>var</code> attribute to be effective.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Encodings are applied after all decodings have been
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe stripped.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#set var="category" value="help" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>In addition to the variables in the standard CGI environment,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe these are available for the <code>echo</code> command, for
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>if</code> and <code>elif</code>, and to any program
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe invoked by the document.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The filename (excluding directories) of the document
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe requested by the user.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The (%-decoded) URL path of the document requested by the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe user. Note that in the case of nested include files, this is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <em>not</em> the URL for the current document. Note also that
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe if the URL is modified internally (e.g. by an <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe module="mod_dir">directoryindex</directive>), the modified
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe URL is shown.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The last modification date of the document requested by
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the user.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>If a query string is present, this variable contains the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe (%-decoded) query string, which is <em>escaped</em> for shell
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe usage (special characters like <code>&</code> etc. are
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe preceded by backslashes).</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<section id="substitution"><title>Variable Substitution</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Variable substitution is done within quoted strings in most
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe cases where they may reasonably occur as an argument to an SSI
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>exec</code>, <code>flastmod</code>, <code>fsize</code>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>include</code>, <code>echo</code>, and <code>set</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >SSILegacyExprParser</directive> is set to <code>on</code>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe substitution also occurs in the arguments to conditional operators.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe You can insert a literal dollar sign into the string using backslash
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe quoting:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#set var="cur" value="\$test" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If a variable reference needs to be substituted in the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe middle of a character sequence that might otherwise be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe considered a valid identifier in its own right, it can be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe disambiguated by enclosing the reference in braces,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This will result in the <code>Zed</code> variable being set
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr="<var>test_condition</var>" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#elif expr="<var>test_condition</var>" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#else --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#endif -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>if</code> element works like an if statement in a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe programming language. The test condition is evaluated and if
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the result is true, then the text until the next <code>elif</code>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>else</code> or <code>endif</code> element is included in the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe output stream.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>elif</code> or <code>else</code> statements are used
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to put text into the output stream if the original
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <var>test_condition</var> was false. These elements are optional.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <code>endif</code> element ends the <code>if</code> element
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe and is required.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p><var>test_condition</var> is a boolean expression tha follows the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <a href="/expr.html">ap_expr</a> syntax. The syntax can be changed
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe to be compatible with Apache HTTPD 2.2.x using <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe module="mod_include">SSILegacyExprParser</directive>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The SSI variables set with the <code>var</code> element are exported
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe into the request environment and can be accessed with the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>reqenv</code> function. As a short-cut, the function name
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>v</code> is also available inside <module>mod_include</module>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The below example will print "from local net" if client IP address
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe belongs to the 10.0.0.0/8 subnet.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr='-R "10.0.0.0/8"' --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe from local net<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#else --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe from somewhere else<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#endif -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The below example will print "foo is bar" if the variable
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr='v("foo") = "bar"' --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe foo is bar<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#endif -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>See also: <a href="/expr.html">Expressions in Apache HTTP Server</a>,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe for a complete reference and examples. The <em>restricted</em> functions
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe are not available inside <module>mod_include</module></p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This section describes the syntax of the <code>#if expr</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe element if <directive module="mod_include">SSILegacyExprParser</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>true if the URL represented by the string is accessible by
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe configuration, false otherwise. This is useful where content on a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe page is to be hidden from users who are not authorized to view the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe URL, such as a link to that URL. Note that the URL is only tested
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe for whether access would be granted, not whether the URL exists.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr="-A /private" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe Click <a href="/private">here</a> to access private
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe information.<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#endif -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dt><code><var>string1</var> = <var>string2</var><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><p>Compare <var>string1</var> with <var>string2</var>. If
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <var>string2</var> has the form <code>/<var>string2</var>/</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe then it is treated as a regular expression. Regular expressions are
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe implemented by the <a href="http://www.pcre.org">PCRE</a> engine and
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe have the same syntax as those in <a href="http://www.perl.com">perl
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe 5</a>. Note that <code>==</code> is just an alias for <code>=</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe and behaves exactly the same way.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If you are matching positive (<code>=</code> or <code>==</code>), you
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe can capture grouped parts of the regular expression. The captured parts
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe are stored in the special variables <code>$1</code> ..
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>$9</code>. The whole string matched by the regular expression is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#set var="session" value="$1" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#endif -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dt><code><var>string1</var> < <var>string2</var><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <var>string1</var> >= <var>string2</var></code></dt>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>Compare <var>string1</var> with <var>string2</var>. Note, that
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>strcmp(3)</code>). Therefore the string "100" is less than
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>"<code>=</code>" and "<code>!=</code>" bind more tightly than
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe "<code>&&</code>" and "<code>||</code>". "<code>!</code>" binds
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe most tightly. Thus, the following are equivalent:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr="$a = test1 && $b = test2" --><br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <!--#if expr="($a = test1) && ($b = test2)" -->
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The boolean operators <code>&&</code> and <code>||</code>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe share the same priority. So if you want to bind such an operator more
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe tightly, you should use parentheses.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Anything that's not recognized as a variable or an operator
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is treated as a string. Strings can also be quoted:
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>'string'</code>. Unquoted strings can't contain whitespace
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe (blanks and tabs) because it is used to separate tokens such as
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe variables. If multiple strings are found in a row, they are
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe concatenated using blanks. So,</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p><code><var>string1</var> <var
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >string2</var></code> results in <code><var>string1</var> <var
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >string1</var> <var>string2</var></code>.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <note><title>Optimization of Boolean Expressions</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If the expressions become more complex and slow down processing
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe significantly, you can try to optimize them according to the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe evaluation rules:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <li>Binary boolean operators (<code>&&</code> and <code>||</code>)
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe are short circuited wherever possible. In conclusion with the rule
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe above that means, <module>mod_include</module> evaluates at first
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the left expression. If the left result is sufficient to determine
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the end result, processing stops here. Otherwise it evaluates the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe right side and computes the end result from both left and right
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe results.</li>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <li>Short circuit evaluation is turned off as long as there are regular
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe expressions to deal with. These must be evaluated to fill in the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe backreference variables (<code>$1</code> .. <code>$9</code>).</li>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>If you want to look how a particular expression is handled, you can
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>-DDEBUG_INCLUDE</code> compiler option. This inserts for every
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe parsed expression tokenizer information, the parse tree and how it is
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe evaluated into the output sent to the client.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <note><title>Escaping slashes in regex strings</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>All slashes which are not intended to act as delimiters in your regex must
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe be escaped. This is regardless of their meaning to the regex engine.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>String that ends an include element</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>server config</context><context>virtual host</context>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This directive changes the string that <module>mod_include</module>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe looks for to mark the end of an include element.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSIEndTag "%>"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<seealso><directive module="mod_include">SSIStartTag</directive></seealso>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>String displayed when an unset variable is echoed</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>server config</context><context>virtual host</context>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This directive changes the string that <module>mod_include</module>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe displays when a variable is not set and "echoed".</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSIUndefinedEcho "<!-- undef -->"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Error message displayed when there is an SSI
ceaa05c302b4a0013174f4344c0907df84f7390dwroweerror</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<default>SSIErrorMsg "[an error occurred while processing this
ceaa05c302b4a0013174f4344c0907df84f7390dwrowedirective]"</default>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>server config</context><context>virtual host</context>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <directive>SSIErrorMsg</directive> directive changes the error
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe message displayed when <module>mod_include</module> encounters an
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe error. For production servers you may consider changing the default
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe error message to <code>"<!-- Error -->"</code> so that
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the message is not presented to the user.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This directive has the same effect as the <code><!--#config
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSIErrorMsg "<!-- Error -->"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>String that starts an include element</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>server config</context><context>virtual host</context>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This directive changes the string that <module>mod_include</module>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe looks for to mark an include element to process.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>You may want to use this option if you have 2 servers parsing the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe output of a file each processing different commands (possibly at
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe different times).</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSIStartTag "<%"<br />
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSIEndTag "%>"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The example given above, which also specifies a matching
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="mod_include">SSIEndTag</directive>, will
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe allow you to use SSI directives as shown in the example
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <example><title>SSI directives with alternate start and end tags</title>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <%printenv %>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<seealso><directive module="mod_include">SSIEndTag</directive></seealso>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Configures the format in which date strings are
ceaa05c302b4a0013174f4344c0907df84f7390dwrowedisplayed</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<default>SSITimeFormat "%A, %d-%b-%Y %H:%M:%S %Z"</default>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<context>server config</context><context>virtual host</context>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<p>This directive changes the format in which date strings are displayed
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe when echoing <code>DATE</code> environment variables. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <var>formatstring</var> is as in <code>strftime(3)</code> from the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe C standard library.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>This directive has the same effect as the <code><!--#config
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe timefmt=<var>formatstring</var> --></code> element.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe SSITimeFormat "%R, %B %d, %Y"
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe </highlight>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The above directive would cause times to be displayed in the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe format "22:26, June 14, 2002".</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Controls whether ETags are generated by the server.</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Under normal circumstances, a file filtered by <module>mod_include</module>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe may contain elements that are either dynamically generated, or that may
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe have changed independently of the original file. As a result, by default
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the server is asked not to generate an <code>ETag</code> header for the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe response by adding <code>no-etag</code> to the request notes.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <directive>SSIETag</directive> directive suppresses this
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe behaviour, and allows the server to generate an <code>ETag</code> header.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe This can be used to enable caching of the output. Note that a backend server
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe or dynamic content generator may generate an ETag of its own, ignoring
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <module>mod_include</module> regardless of the value of this setting.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive>SSIETag</directive> can take on the following values:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd><code>no-etag</code> will be added to the request notes, and the server
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe is asked not to generate an ETag. Where a server ignores the value of
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <code>no-etag</code> and generates an ETag anyway, the ETag will be
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe respected.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>Existing ETags will be respected, and ETags generated by the server will
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe be passed on in the response.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Controls whether <code>Last-Modified</code> headers are generated by the
ceaa05c302b4a0013174f4344c0907df84f7390dwroweserver.</description>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<contextlist><context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>Under normal circumstances, a file filtered by <module>mod_include</module>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe may contain elements that are either dynamically generated, or that may
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe have changed independently of the original file. As a result, by default
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the <code>Last-Modified</code> header is stripped from the response.</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <directive>SSILastModified</directive> directive overrides this
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe behaviour, and allows the <code>Last-Modified</code> header to be respected
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe if already present, or set if the header is not already present. This can
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe be used to enable caching of the output. <directive>SSILastModified</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe can take on the following values:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The <code>Last-Modified</code> header will be stripped from responses,
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe unless the <directive module="mod_include">XBitHack</directive> directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>The <code>Last-Modified</code> header will be respected if already
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe present in a response, and added to the response if the response is a
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe file and the header is missing. The
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="mod_include">SSILastModified</directive> directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe takes precedence over <directive module="mod_include">XBitHack</directive>.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe<description>Enable compatibility mode for conditional expressions.</description>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<contextlist><context>directory</context><context>.htaccess</context></contextlist>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<compatibility>Available in version 2.3.13 and later.</compatibility>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg <p>As of version 2.3.13, <module>mod_include</module> has switched to the
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg new <a href="/expr.html">ap_expr</a> syntax for conditional expressions
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg in <code>#if</code> flow control elements. This directive allows to
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg switch to the <a href="#legacyexpr">old syntax</a> which is compatible
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg with Apache HTTPD version 2.2.x and earlier.
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg</directivesynopsis>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<directivesynopsis>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<description>Parse SSI directives in files with the execute bit
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankgset</description>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<contextlist><context>server config</context><context>virtual host</context>
a985f6595e5da3e4b35bd91eab0a6eac3cbc8ae4fuankg<context>directory</context><context>.htaccess</context></contextlist>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <directive>XBitHack</directive> directive controls the parsing
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe of ordinary html documents. This directive only affects files associated
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe with the <glossary>MIME-type</glossary> <code>text/html</code>. <directive
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >XBitHack</directive> can take on the following values:</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>Any <code>text/html</code> file that has the user-execute bit
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe set will be treated as a server-parsed html document.</dd>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <dd>As for <code>on</code> but also test the group-execute bit.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe If it is set, then set the <code>Last-modified</code> date of the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe returned file to be the last modified time of the file. If
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe it is not set, then no last-modified date is sent. Setting
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe this bit allows clients and proxies to cache the result of
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe the request.
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>You would not want to use the full option, unless you assure the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe group-execute bit is unset for every SSI script which might <code
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe >#include</code> a CGI or otherwise produces different output on
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe each hit (or could potentially change on subsequent requests).</p>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <p>The <directive module="mod_include">SSILastModified</directive>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe directive takes precedence over the
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="mod_include">XBitHack</directive> directive when
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe <directive module="mod_include">SSILastModified</directive> is set to
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</directivesynopsis>
ceaa05c302b4a0013174f4344c0907df84f7390dwrowe</modulesynopsis>