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