688N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
688N/A<
TITLE>Apache module mod_include</
TITLE>
919N/A<!-- Background white, links blue (unvisited), navy (visited), red (active) --> 919N/A<
H1 ALIGN="CENTER">Module mod_include</
H1>
919N/A<
p>This module provides for server-parsed html documents.</
p>
1549N/A><
STRONG>Status:</
STRONG></
A> Base
1549N/A><
STRONG>Module Identifier:</
STRONG></
A> includes_module
1549N/A<
p>This module provides a handler which will process files before they
1549N/Aare sent to the client. The processing is controlled by specially
1549N/Aformated SGML comments, referred to as <
em>elements</
em>. These
1549N/Aelements allow conditional text, the inclusion other files or
688N/Aprograms, as well as the setting and printing of environment
688N/A<
LI><
A HREF="#xbithack">XBitHack</
A>
688N/A<
H2>Enabling Server-Side Includes</
H2>
688N/A<
p>Server Side Includes are implemented by the <
code>INCLUDES</
code>
688N/Aserver-side include directives are given the extension .shtml, the
1549N/Afollowing directives will make Apache parse them and assign the
1549N/A<FilesMatch "\.shtml[.$]"><
br>
1549N/A SetOutputFilter INCLUDES<
br>
688N/A<
p>The following directive must be given for the directories containing
986N/Athe shtml files (typically in a <
CODE><Directory></
CODE> section,
986N/Abut this directive is also valid .htaccess files if <
CODE>AllowOverride
688N/AOptions</
CODE> is set):</
p>
1549N/A<
p>Alternatively the <
A HREF="#xbithack"><
CODE>XBitHack</
CODE></
A>
1549N/Adirective can be used to parse normal (<
CODE>
text/
html</
CODE>) files,
1549N/Abased on file permissions.</
p>
1549N/A<
p>For backwards compatibility, documents with mime type
1549N/A(and the resulting output given the mime type <
CODE>
text/
html</
CODE>)
1549N/Aas will documents with the handler <
code>server-parsed</
code>.
688N/AThe document is parsed as an HTML document, with special commands embedded
688N/Aas SGML comments. A command has the syntax:
688N/A<!--#</
CODE><
EM>element attribute=value attribute=value ...</
EM>
688N/AThe value will often be enclosed in double quotes; many commands only allow
688N/Aa single attribute-value pair. Note that the comment terminator
688N/A(<
SAMP>--></
SAMP>) should be preceded by whitespace to ensure that it
688N/Aisn't considered part of an SSI token.
688N/AThe allowed elements are:<
P>
1549N/AThis command controls various aspects of the parsing. The valid attributes
688N/A<
DD>The value is a message that is sent back to the client if an error occurs
688N/Awhilst parsing the document.
688N/A<
DD>The value sets the format to be used which displaying the size of a file.
1549N/AValid values are <
CODE>bytes</
CODE> for a count in bytes, or
688N/A<
CODE>abbrev</
CODE> for a count in Kb or Mb as appropriate.
688N/A<
DD>The value is a string to be used by the <
CODE>strftime(3)</
CODE> library
688N/Aroutine when printing dates.
688N/A<
DT><
STRONG><
a name="echo">echo</
a></
STRONG>
688N/AThis command prints one of the include variables, defined below.
688N/AIf the variable is unset, it is printed as <
CODE>(none)</
CODE>.
1549N/AAny dates printed are subject to the currently configured <
CODE>timefmt</
CODE>.
688N/A<
DD>The value is the name of the variable to print.
688N/A<
DD>Specifies how Apache should encode special characters contained
1549N/Ain the variable before outputting them. If set to "none", no encoding
1549N/Awill be done. If set to "url", then URL encoding (also known as
688N/A%-encoding; this is appropriate for use within URLs in links, etc.)
688N/Awill be performed. At the start of an <
CODE>echo</
CODE> element,
688N/Athe default is set to "entity", resulting in entity encoding (which
688N/Ais appropriate in the context of a block-level HTML element, eg.
688N/Aa paragraph of text). This can be changed by adding an
688N/A<
CODE>encoding</
CODE> attribute, which will remain in effect until
688N/Athe next <
CODE>encoding</
CODE> attribute is encountered or the
1549N/Aelement ends, whichever comes first. Note that the
688N/A<
CODE>encoding</
CODE> attribute must <
EM>precede</
EM> the corresponding
688N/A<
CODE>var</
CODE> attribute to be effective, and that only special
688N/Acharacters as defined in the ISO-8859-1 character encoding will be
688N/Aencoded. This encoding process may not have the desired result if
688N/Aa different character encoding is in use.
688N/AApache 1.3.12 and above; previous versions do no encoding.
688N/A<
DT><
STRONG>exec</
STRONG>
688N/AThe exec command executes a given shell command or CGI script.
688N/AThe IncludesNOEXEC <
A HREF="core.html#options">Option</
A> disables this command
688N/Acompletely. The valid attributes are:
688N/AThe value specifies a (%-encoded) URL relative path to the CGI script.
688N/AIf the path does not begin with a (/), then it is taken to be relative to
688N/Athe current document. The document referenced by this path is invoked
688N/Aas a CGI script, even if the server would not normally recognize it as
688N/Asuch. However, the directory containing the script must be enabled for
688N/AThe CGI script is given the PATH_INFO and query string (QUERY_STRING) of the
688N/Aoriginal request from the client; these cannot be specified in the URL path.
688N/AThe include variables will be available to the script in addition to the
688N/AIf the script returns a Location: header instead of output, then this
688N/Awill be translated into an HTML anchor.<
P>
688N/AThe <
CODE>include virtual</
CODE> element should be used in preference to
688N/A<
DD>The server will execute the given string using <
CODE>/
bin/
sh</
CODE>.
688N/AThe include variables are available to the command.
688N/A<
DT><
STRONG>fsize</
STRONG>
688N/AThis command prints the size of the specified file, subject to the
688N/A<
CODE>sizefmt</
CODE> format specification. Attributes:
688N/A<
DD>The value is a path relative to the directory containing the current
688N/A<
DD>The value is a (%-encoded) URL-path relative to the current document being
688N/Aparsed. If it does not begin with a slash (/) then it is taken to be relative
688N/Ato the current document.
688N/A<
DT><
STRONG>flastmod</
STRONG>
1549N/AThis command prints the last modification date of the specified file,
688N/Asubject to the <
CODE>timefmt</
CODE> format specification. The attributes are
688N/Athe same as for the <
CODE>fsize</
CODE> command.
1549N/A<
DT><
STRONG>include</
STRONG>
688N/AThis command inserts the text of another document or file into the parsed
688N/Afile. Any included file is subject to the usual access control. If the
688N/Adirectory containing the parsed file has the
1549N/AIncludesNOEXEC set, and the including the document would cause a program
1549N/Ato be executed, then it will not be included; this prevents the execution of
688N/ACGI scripts. Otherwise CGI scripts are invoked as normal using the complete
688N/AURL given in the command, including any query string.
688N/A<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> 688N/AAn attribute defines the location of the document; the inclusion is done for
688N/Aeach attribute given to the include command. The valid attributes are:
688N/A<
DD>The value is a path relative to the directory containing the current
688N/Adocument being parsed. It cannot contain <
CODE>../</
CODE>, nor can it be an
688N/Aabsolute path. The <
CODE>virtual</
CODE> attribute should always be used
688N/Ain preference to this one.
688N/A<
DD>The value is a (%-encoded) URL relative to the current document being
688N/Aparsed. The URL cannot contain a scheme or hostname, only a path and
1549N/Aan optional query string. If it does not begin with a slash (/) then it
688N/Ais taken to be relative to the current document.
688N/AA URL is constructed from the attribute, and the output the server
688N/Awould return if the URL were accessed by the client is included in the parsed
688N/Aoutput. Thus included files can be nested.
688N/A<
DT><
STRONG>printenv</
STRONG>
688N/A<
DD>This prints out a listing of all existing variables and their values.
1549N/A Starting with Apache 1.3.12, special characters are entity encoded (see the
688N/A <
A HREF="#echo"><
CODE>echo</
CODE></
A> element for details) before being
688N/A<
DD>For example: <
CODE><!--#printenv --></
CODE>
688N/A<
DD>Apache 1.2 and above.
688N/A<
DT><
STRONG>set</
STRONG>
688N/A<
DD>This sets the value of a variable. Attributes:
688N/A<
DD>The name of the variable to set.
688N/A<
DD>The value to give a variable.
688N/A <
CODE><!--#set var="category" value="help" --></
CODE>
688N/A<
DD>Apache 1.2 and above.
688N/A<
H2>Include Variables</
H2>
688N/AIn addition to the variables in the standard CGI environment, these are
688N/Aavailable for the <
CODE>echo</
CODE> command, for <
CODE>if</
CODE> and
688N/A<
CODE>elif</
CODE>, and to any program invoked by the document.
688N/A<
DD>The current date in Greenwich Mean Time.
688N/A<
DD>The current date in the local time zone.
688N/A<
DD>The filename (excluding directories) of the document requested by the
1549N/A<
DD>The (%-decoded) URL path of the document requested by the user. Note that
688N/Ain the case of nested include files, this is <
EM>not</
EM> then URL for the
688N/A<
DD>The last modification date of the document requested by the user.
688N/A<
H2>Variable Substitution</
H2>
688N/A<
P> Variable substitution is done within quoted strings in most cases
688N/A where they may reasonably occur as an argument to an SSI directive.
688N/A <
SAMP>include</
SAMP>, and
688N/A directives, as well as the arguments to conditional operators.
688N/A You can insert a literal dollar sign into the string using backslash
688N/A <!--#if expr="$a = \$test" -->
688N/A<
P> If a variable reference needs to be substituted in the middle of a
688N/A character sequence that might otherwise be considered a valid
688N/A identifier in its own right, it can be disambiguated by enclosing
688N/A the reference in braces, <
EM>à la</
EM> shell substitution:
688N/A <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
688N/A<
P> This will result in the <
SAMP>Zed</
SAMP> variable being set to
688N/A "<
SAMP>X_Y</
SAMP>" if <
SAMP>REMOTE_HOST</
SAMP> is
688N/A "<
SAMP>X</
SAMP>" and <
SAMP>REQUEST_METHOD</
SAMP> is
688N/A "<
SAMP>Y</
SAMP>".
688N/A<
P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is
688N/A<
H2><
A NAME="flowctrl">Flow Control Elements</
A></
H2>
688N/AThese are available in Apache 1.2 and above. The basic flow control
688N/A <!--#if expr="<
EM>test_condition</
EM>" -->
688N/A <!--#elif expr="<
EM>test_condition</
EM>" -->
688N/A<
P> The <
STRONG><
CODE>if</
CODE></
STRONG> element works like an
688N/A if statement in a programming language. The test condition
688N/A is evaluated and if the result is true, then the text until
688N/A the next <
STRONG><
CODE>elif</
CODE></
STRONG>, <
STRONG><
CODE>else</
CODE></
STRONG>.
688N/A or <
STRONG><
CODE>endif</
CODE></
STRONG> element is included in the
688N/A<
P> The <
STRONG><
CODE>elif</
CODE></
STRONG> or <
STRONG><
CODE>else</
CODE></
STRONG>
688N/A statements are be used the put text into the output stream
688N/A if the original test_condition was false. These elements
688N/A<
P> The <
STRONG><
CODE>endif</
CODE></
STRONG> element ends the
688N/A <
STRONG><
CODE>if</
CODE></
STRONG> element and is required.
688N/A<
P> <
EM>test_condition</
EM> is one of the following:
688N/A<
DT><
EM>string</
EM><
DD>true if <
EM>string</
EM> is not empty
688N/A<
DT><
EM>string1</
EM> = <
EM>string2</
EM>
688N/A <
EM>string1</
EM> != <
EM>string2</
EM>
688N/A <
EM>string1</
EM> < <
EM>string2</
EM>
688N/A <
EM>string1</
EM> <= <
EM>string2</
EM>
688N/A <
EM>string1</
EM> > <
EM>string2</
EM>
688N/A <
EM>string1</
EM> >= <
EM>string2</
EM>
688N/A<
DD>Compare string1 with string 2. If string2 has the form <
EM>/string/</
EM>
688N/A then it is compared as a regular expression.
688N/A Regular expressions have the same syntax as those found in the
688N/A Unix <
SAMP>egrep</
SAMP> command.
688N/A<
DT>( <
EM>test_condition</
EM> )
688N/A <
DD>true if <
EM>test_condition</
EM> is true
688N/A<
DT>! <
EM>test_condition</
EM>
688N/A <
DD>true if <
EM>test_condition</
EM> is false
688N/A<
DT><
EM>test_condition1</
EM> && <
EM>test_condition2</
EM>
688N/A <
DD>true if both <
EM>test_condition1</
EM> and
688N/A <
EM>test_condition2</
EM> are true
688N/A<
DT><
EM>test_condition1</
EM> || <
EM>test_condition2</
EM>
1549N/A <
DD>true if either <
EM>test_condition1</
EM> or
688N/A <
EM>test_condition2</
EM> is true
688N/A<
P> "<
EM>=</
EM>" and "<
EM>!=</
EM>" bind more tightly than "<
EM>&&</
EM>" and
688N/A "<
EM>!</
EM>" binds most tightly. Thus, the following are equivalent:
688N/A <!--#if expr="$a = test1 && $b = test2" -->
688N/A <!--#if expr="($a = test1) && ($b = test2)" -->
688N/A<
P> Anything that's not recognized as a variable or an operator is
688N/A treated as a string. Strings can also be quoted: <
EM>'string'</
EM>.
688N/A Unquoted strings can't contain whitespace (blanks and tabs)
688N/A because it is used to separate tokens such as variables. If
688N/A multiple strings are found in a row, they are concatenated using
<
EM>string1 string2</
EM> results in <
EM>string1 string2</
EM>
<
EM>'string1 string2'</
EM> results in <
EM>string1 string2</
EM>
<
H2>Using Server Side Includes for ErrorDocuments</
H2>
describes how to use the features of mod_include to offer internationalized
customized server error documents.
<
H2><
A NAME="xbithack">XBitHack</
A> directive</
H2>
<!--%plaintext <?INDEX {\tt XBitHack} directive> --> ><
STRONG>Syntax:</
STRONG></
A> XBitHack on|off|full<
BR>
><
STRONG>Default:</
STRONG></
A> <
CODE>XBitHack off</
CODE><
BR>
><
STRONG>Context:</
STRONG></
A> server config, virtual host, directory, .htaccess<
BR>
><
STRONG>Override:</
STRONG></
A> Options<
BR>
><
STRONG>Status:</
STRONG></
A> Base<
BR>
><
STRONG>Module:</
STRONG></
A> 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>. XBitHack can take on the following values:
<
DD>No special treatment of executable files.
<
DD>Any file that has the user-execute bit set will be treated as a
server-parsed html document.
<
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
<
P><
STRONG>Note:</
STRONG> 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).