| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_include</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Module mod_include</H1> |
| |
| This module is contained in the <code>mod_include.c</code> file, and |
| is compiled in by default. It provides for server-parsed html |
| documents. Several directives beyond the original NCSA definition have been |
| included in Apache 1.2 - these are flagged below with the phrase |
| "Apache 1.2 and above". Of particular significance are the new flow |
| control directives documented at the bottom. |
| |
| <H2>Enabling Server-Side Includes</H2> |
| |
| Any document with handler of "server-parsed" will be parsed by this |
| module, if the <CODE>Includes</CODE> option is set. 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>: |
| |
| <PRE> |
| AddType text/html .shtml |
| AddHandler server-parsed .shtml |
| </PRE> |
| |
| The following directive must be given for the directories containing |
| the shtml files (typically in a <CODE><Directory></CODE> section, |
| but this directive is also valid .htaccess files if <CODE>AllowOverride |
| Options</CODE> is set): |
| |
| <PRE> |
| Options +Includes |
| </PRE> |
| |
| Alternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A> |
| directive can be used to parse normal (<CODE>text/html</CODE>) files, |
| based on file permissions. <P> |
| |
| For backwards compatibility, documents with mime type |
| <code>text/x-server-parsed-html</code> or |
| <code>text/x-server-parsed-html3</code> will also be parsed |
| (and the resulting output given the mime type <code>text/html</code>). |
| |
| <h2>Basic Elements</h2> |
| |
| The document is parsed as an HTML document, with special commands embedded |
| as SGML comments. A command has the syntax: |
| |
| <blockquote><code> |
| <!--#</code><em>element attribute=value attribute=value ...</em> |
| <code> --> |
| </code></blockquote> |
| |
| The value will often be enclosed in double quotes; many commands only allow |
| a single attribute-value pair. Note that the comment terminator |
| (<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it |
| isn't considered part of an SSI token. |
| <p> |
| The allowed elements are:<p> |
| |
| <dl> |
| |
| <dt><strong>config</strong> |
| <dd> |
| This command controls various aspects of the parsing. The valid attributes |
| are: |
| <dl> |
| <dt>errmsg |
| <dd>The value is a message that is sent back to the client if an error occurs |
| whilst parsing the document. |
| <dt>sizefmt |
| <dd>The value sets the format to be used which 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. |
| <dt>timefmt |
| <dd>The value is a string to be used by the <code>strftime(3)</code> library |
| routine when printing dates. |
| </dl> |
| |
| <dt><strong>echo</strong> |
| <dd> |
| This command prints one of the include variables, defined below. |
| If the variable is unset, it is printed as <code>(none)</code>. |
| Any dates printed are subject to the currently configured <code>timefmt</code>. |
| Attributes: |
| <dl> |
| <dt>var |
| <dd>The value is the name of the variable to print. |
| </dl> |
| |
| <dt><strong>exec</strong> |
| <dd> |
| The exec command executes a given shell command or CGI script. |
| The IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command |
| completely. The valid attributes are: |
| <dl> |
| <dt>cgi |
| <dd> |
| The value specifies a (%-encoded) URL relative path to the CGI script. |
| If the path does not begin with a (/), 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 <A HREF="mod_alias.html#scriptalias">ScriptAlias</A> |
| or the ExecCGI <A HREF="core.html#options">Option</A>).<p> |
| The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the |
| original request from the client; these cannot 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> |
| If the script returns a Location: header instead of output, then this |
| will be translated into an HTML anchor.<p> |
| The <code>include virtual</code> element should be used in preference to |
| <code>exec cgi</code>. |
| <dt>cmd |
| <dd>The server will execute the given string using <code>/bin/sh</code>. |
| The include variables are available to the command. |
| </dl> |
| |
| <dt><strong>fsize</strong> |
| <dd> |
| This command prints the size of the specified file, subject to the |
| <code>sizefmt</code> format specification. Attributes: |
| <dl> |
| <dt>file |
| <dd>The value is a path relative to the directory containing the current |
| document being parsed. |
| <dt>virtual |
| <dd>The value is a (%-encoded) URL-path relative to the current document being |
| parsed. If it does not begin with a slash (/) then it is taken to be relative |
| to the current document. |
| </dl> |
| |
| <dt><strong>flastmod</strong> |
| <dd> |
| 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>fsize</code> command. |
| |
| <dt><strong>include</strong> |
| <dd> |
| 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 the |
| <A HREF="core.html#options">Option</A> |
| IncludesNOEXEC set, and the including the document would cause a program |
| to be executed, then it will not be included; this prevents the execution of |
| CGI scripts. Otherwise CGI scripts are invoked as normal using the complete |
| URL given in the command, including any query string. |
| <!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> |
| <p> |
| |
| An attribute defines the location of the document; the inclusion is done for |
| each attribute given to the include command. The valid attributes are: |
| <dl> |
| <dt>file |
| <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. The <code>virtual</code> attribute should always be used |
| in preference to this one. |
| <dt>virtual |
| <dd>The value is a (%-encoded) URL relative to the current document being |
| parsed. 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. |
| </dl> |
| 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. |
| |
| <dt><strong>printenv</strong> |
| <dd>This prints out a listing of all existing variables and their values. |
| No attributes. |
| <dd>For example: <code><!--#printenv --></code> |
| <dd>Apache 1.2 and above. |
| |
| <dt><strong>set</strong> |
| <dd>This sets the value of a variable. Attributes: |
| <dl> |
| <dt>var |
| <dd>The name of the variable to set. |
| <dt>value |
| <dd>The value to give a variable. |
| </dl> |
| For example: |
| <CODE><!--#set var="category" value="help" --></CODE> |
| <dd>Apache 1.2 and above. |
| |
| </dl> |
| |
| <h2>Include Variables</h2> |
| |
| 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. |
| |
| <dl> |
| <dt>DATE_GMT |
| <dd>The current date in Greenwich Mean Time. |
| <dt>DATE_LOCAL |
| <dd>The current date in the local time zone. |
| <dt>DOCUMENT_NAME |
| <dd>The filename (excluding directories) of the document requested by the |
| user. |
| <dt>DOCUMENT_URI |
| <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> then URL for the |
| current document. |
| <dt>LAST_MODIFIED |
| <dd>The last modification date of the document requested by the user. |
| </dl> |
| <p> |
| |
| <H2>Variable Substitution</H2> |
| <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 |
| <SAMP>config</SAMP>, |
| <SAMP>exec</SAMP>, |
| <SAMP>flastmod</SAMP>, |
| <SAMP>fsize</SAMP>, |
| <SAMP>include</SAMP>, and |
| <SAMP>set</SAMP> |
| directives, as well as the arguments to conditional operators. |
| You can insert a literal dollar sign into the string using backslash |
| quoting: |
| |
| <PRE> |
| <!--#if expr="$a = \$test" --> |
| </PRE> |
| |
| <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>à la</EM> shell substitution: |
| |
| <PRE> |
| <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" --> |
| </PRE> |
| |
| <P> This will result in the <SAMP>Zed</SAMP> variable being set to |
| "<SAMP>X_Y</SAMP>" if <SAMP>REMOTE_HOST</SAMP> is |
| "<SAMP>X</SAMP>" and <SAMP>REQUEST_METHOD</SAMP> is |
| "<SAMP>Y</SAMP>". |
| |
| <P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is |
| /foo/file.html, "in bar" if it is /bar/file.html and "in neither" |
| otherwise: |
| <PRE> |
| <!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" --> |
| in foo |
| <!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" --> |
| in bar |
| <!--#else --> |
| in neither |
| <!--#endif --> |
| </PRE> |
| |
| <H2>Flow Control Elements</H2> |
| |
| These are available in Apache 1.2 and above. The basic flow control |
| elements are: |
| |
| <PRE> |
| <!--#if expr="<I>test_condition</I>" --> |
| <!--#elif expr="<I>test_condition</I>" --> |
| <!--#else --> |
| <!--#endif --> |
| </PRE> |
| |
| <P> The <B><CODE>if</CODE></B> 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 <B><CODE>elif</CODE></B>, <B><CODE>else</CODE></B>. |
| or <B><CODE>endif</CODE></B> element is included in the |
| output stream. |
| |
| <P> The <B><CODE>elif</CODE></B> or <B><CODE>else</CODE></B> |
| statements are be used the put text into the output stream |
| if the original test_condition was false. These elements |
| are optional. |
| |
| <P> The <B><CODE>endif</CODE></B> element ends the |
| <B><CODE>if</CODE></B> element and is required. |
| |
| <P> <I>test_condition</I> is one of the following: |
| |
| <DL> |
| |
| <DT><I>string</I><DD>true if <I>string</I> is not empty |
| |
| <DT><I>string1</I> = <I>string2</I><BR> |
| <I>string1</I> != <I>string2</I> |
| |
| <DD>Compare string1 with string 2. If string2 has the form <I>/string/</I> |
| than it is compared as a regular expression. |
| Regular expressions have the same syntax as those found in the |
| Unix egrep command. |
| |
| <DT>( <I>test_condition</I> ) |
| <DD>true if <I>test_condition</I> is true |
| <DT>! <I>test_condition</I> |
| <DD>true if <I>test_condition</I> is false |
| <DT><I>test_condition1</I> && <I>test_condition2</I> |
| <DD>true if both <I>test_condition1</I> and |
| <I>test_condition2</I> are true |
| <DT><I>test_condition1</I> || <I>test_condition2</I> |
| <DD>true if either <I>test_condition1</I> or |
| <I>test_condition2</I> is true |
| </DL> |
| |
| <P> "<I>=</I>" and "<I>!=</I>" bind more tightly than "<I>&&</I>" and |
| "<I>||</I>". |
| "<I>!</I>" binds most tightly. Thus, the following are equivalent: |
| |
| <PRE> |
| <!--#if expr="$a = test1 && $b = test2" --> |
| <!--#if expr="($a = test1) && ($b = test2)" --> |
| </PRE> |
| |
| <P> Anything that's not recognized as a variable or an operator is |
| treated as a string. Strings can also be quoted: <I>'string'</I>. |
| 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, |
| |
| <PRE> |
| <I>string1 string2</I> results in <I>string1 string2</I> |
| <I>'string1 string2'</I> results in <I>string1 string2</I> |
| </PRE> |
| |
| <hr> |
| <h2>Directives</h2> |
| <ul> |
| <li><A HREF="#xbithack">XBitHack</A> |
| </ul> |
| <hr> |
| |
| |
| <h2><A name="xbithack">XBitHack</A></h2> |
| <!--%plaintext <?INDEX {\tt XBitHack} directive> --> |
| <strong>Syntax:</strong> XBitHack <em>status</em><br> |
| <strong>Default:</strong> <code>XBitHack off</code><br> |
| <Strong>Context:</strong> server config, virtual host, directory, .htaccess<br> |
| <Strong>Override:</strong> Options<br> |
| <strong>Status:</strong> Base<br> |
| <strong>Module:</strong> mod_include<p> |
| |
| The XBitHack directives controls the parsing of ordinary html documents. |
| This directive only affects files associated with the MIME type |
| <CODE>text/html</CODE>. |
| <em>Status</em> can have the following values: |
| <dl> |
| <dt>off |
| <dd>No special treatment of executable files. |
| <dt>on |
| <dd>Any file that has the user-execute bit set will be treated as a |
| server-parsed html document. |
| <dt>full |
| <dd>As for <code>on</code> but also test the group-execute bit. If it |
| is set, then set the Last-modified 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. |
| <p><b>Note:</b> you would not want to use this, for example, when you |
| <code>#include</code> a CGI that produces different output on each hit |
| (or potentially depends on the hit). |
| </dl> |
| <p> |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |