50N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
50N/A<
TITLE>Apache module mod_include</
TITLE>
50N/A<!-- Background white, links blue (unvisited), navy (visited), red (active) --> 50N/A<
H1 ALIGN="CENTER">Module mod_include</
H1>
50N/Ais compiled in by default. It provides for server-parsed html
50N/Adocuments. Several directives beyond the original NCSA definition were
50N/Aintroduced in Apache 1.2 - these are flagged below with the phrase
50N/A"Apache 1.2 and above". Of particular significance are the new flow
50N/Acontrol directives documented at the bottom.
50N/A<
H2>Enabling Server-Side Includes</
H2>
202N/AAny document with handler of "server-parsed" will be parsed by this
50N/Amodule, if the <
CODE>Includes</
CODE> option is set. If documents
50N/Acontaining server-side include directives are given the extension
72N/A.shtml, the following directives will make Apache parse them and
119N/Aassign the resulting document the mime type of <
CODE>
text/
html</
CODE>:
50N/AAddHandler server-parsed .shtml
66N/AThe following directive must be given for the directories containing
66N/Athe shtml files (typically in a <
CODE><Directory></
CODE> section,
50N/Abut this directive is also valid .htaccess files if <
CODE>AllowOverride
50N/AAlternatively the <
A HREF="#xbithack"><
CODE>XBitHack</
CODE></
A>
235N/Adirective can be used to parse normal (<
CODE>
text/
html</
CODE>) files,
50N/Abased on file permissions. <
P>
50N/AFor backwards compatibility, documents with mime type
235N/A(and the resulting output given the mime type <
CODE>
text/
html</
CODE>).
63N/AThe document is parsed as an HTML document, with special commands embedded
72N/Aas SGML comments. A command has the syntax:
72N/A<!--#</
CODE><
EM>element attribute=value attribute=value ...</
EM>
72N/A</
CODE></
BLOCKQUOTE>
50N/AThe value will often be enclosed in double quotes; many commands only allow
50N/Aa single attribute-value pair. Note that the comment terminator
242N/A(<
SAMP>--></
SAMP>) should be preceded by whitespace to ensure that it
50N/Aisn't considered part of an SSI token.
50N/AThe allowed elements are:<
P>
59N/A<
DT><
STRONG>config</
STRONG>
242N/AThis command controls various aspects of the parsing. The valid attributes
195N/A<
DD>The value is a message that is sent back to the client if an error occurs
66N/Awhilst parsing the document.
50N/A<
DD>The value sets the format to be used which displaying the size of a file.
235N/AValid values are <
CODE>bytes</
CODE> for a count in bytes, or
235N/A<
CODE>abbrev</
CODE> for a count in Kb or Mb as appropriate.
235N/A<
DD>The value is a string to be used by the <
CODE>strftime(3)</
CODE> library
235N/Aroutine when printing dates.
66N/A<
DT><
STRONG>echo</
STRONG>
50N/AThis command prints one of the include variables, defined below.
66N/AIf the variable is unset, it is printed as <
CODE>(none)</
CODE>.
66N/AAny dates printed are subject to the currently configured <
CODE>timefmt</
CODE>.
258N/A<
DD>The value is the name of the variable to print.
59N/A<
DT><
STRONG>exec</
STRONG>
50N/AThe exec command executes a given shell command or CGI script.
111N/AThe IncludesNOEXEC <
A HREF="core.html#options">Option</
A> disables this command
111N/Acompletely. The valid attributes are:
111N/AThe value specifies a (%-encoded) URL relative path to the CGI script.
111N/AIf the path does not begin with a (/), then it is taken to be relative to
111N/Athe current document. The document referenced by this path is invoked
111N/Aas a CGI script, even if the server would not normally recognize it as
111N/Asuch. However, the directory containing the script must be enabled for
111N/AThe CGI script is given the PATH_INFO and query string (QUERY_STRING) of the
111N/Aoriginal request from the client; these cannot be specified in the URL path.
111N/AThe include variables will be available to the script in addition to the
111N/AIf the script returns a Location: header instead of output, then this
111N/Awill be translated into an HTML anchor.<
P>
111N/AThe <
CODE>include virtual</
CODE> element should be used in preference to
111N/A<
DD>The server will execute the given string using <
CODE>/
bin/
sh</
CODE>.
111N/AThe include variables are available to the command.
111N/A<
DT><
STRONG>fsize</
STRONG>
111N/AThis command prints the size of the specified file, subject to the
111N/A<
CODE>sizefmt</
CODE> format specification. Attributes:
50N/A<
DD>The value is a path relative to the directory containing the current
237N/A<
DD>The value is a (%-encoded) URL-path relative to the current document being
237N/Aparsed. If it does not begin with a slash (/) then it is taken to be relative
237N/Ato the current document.
237N/A<
DT><
STRONG>flastmod</
STRONG>
237N/AThis command prints the last modification date of the specified file,
237N/Asubject to the <
CODE>timefmt</
CODE> format specification. The attributes are
237N/Athe same as for the <
CODE>fsize</
CODE> command.
235N/A<
DT><
STRONG>include</
STRONG>
235N/AThis command inserts the text of another document or file into the parsed
235N/Afile. Any included file is subject to the usual access control. If the
235N/Adirectory containing the parsed file has the
235N/AIncludesNOEXEC set, and the including the document would cause a program
235N/Ato be executed, then it will not be included; this prevents the execution of
235N/ACGI scripts. Otherwise CGI scripts are invoked as normal using the complete
235N/AURL given in the command, including any query string.
235N/A<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> --> 235N/AAn attribute defines the location of the document; the inclusion is done for
235N/Aeach attribute given to the include command. The valid attributes are:
235N/A<
DD>The value is a path relative to the directory containing the current
235N/Adocument being parsed. It cannot contain <
CODE>../</
CODE>, nor can it be an
235N/Aabsolute path. The <
CODE>virtual</
CODE> attribute should always be used
235N/Ain preference to this one.
235N/A<
DD>The value is a (%-encoded) URL relative to the current document being
235N/Aparsed. The URL cannot contain a scheme or hostname, only a path and
235N/Aan optional query string. If it does not begin with a slash (/) then it
235N/Ais taken to be relative to the current document.
50N/AA URL is constructed from the attribute, and the output the server
66N/Awould return if the URL were accessed by the client is included in the parsed
135N/Aoutput. Thus included files can be nested.
66N/A<
DT><
STRONG>printenv</
STRONG>
66N/A<
DD>This prints out a listing of all existing variables and their values.
119N/A<
DD>For example: <
CODE><!--#printenv --></
CODE>
119N/A<
DD>Apache 1.2 and above.
235N/A<
DT><
STRONG>set</
STRONG>
235N/A<
DD>This sets the value of a variable. Attributes:
66N/A<
DD>The name of the variable to set.
59N/A<
DD>The value to give a variable.
135N/A <
CODE><!--#set var="category" value="help" --></
CODE>
135N/A<
DD>Apache 1.2 and above.
111N/A<
H2>Include Variables</
H2>
72N/AIn addition to the variables in the standard CGI environment, these are
136N/Aavailable for the <
CODE>echo</
CODE> command, for <
CODE>if</
CODE> and
66N/A<
CODE>elif</
CODE>, and to any program invoked by the document.
119N/A<
DD>The current date in Greenwich Mean Time.
119N/A<
DD>The current date in the local time zone.
235N/A<
DD>The filename (excluding directories) of the document requested by the
119N/A<
DD>The (%-decoded) URL path of the document requested by the user. Note that
119N/Ain the case of nested include files, this is <
EM>not</
EM> then URL for the
119N/A<
DD>The last modification date of the document requested by the user.
119N/A<
H2>Variable Substitution</
H2>
119N/A<
P> Variable substitution is done within quoted strings in most cases
119N/A where they may reasonably occur as an argument to an SSI directive.
119N/A <
SAMP>include</
SAMP>, and
119N/A directives, as well as the arguments to conditional operators.
119N/A You can insert a literal dollar sign into the string using backslash
235N/A <!--#if expr="$a = \$test" -->
202N/A<
P> If a variable reference needs to be substituted in the middle of a
237N/A character sequence that might otherwise be considered a valid
237N/A identifier in its own right, it can be disambiguated by enclosing
237N/A the reference in braces, <
EM>à la</
EM> shell substitution:
237N/A <!--#set var="Zed" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->
237N/A<
P> This will result in the <
SAMP>Zed</
SAMP> variable being set to
237N/A "<
SAMP>X_Y</
SAMP>" if <
SAMP>REMOTE_HOST</
SAMP> is
237N/A "<
SAMP>X</
SAMP>" and <
SAMP>REQUEST_METHOD</
SAMP> is
237N/A "<
SAMP>Y</
SAMP>".
237N/A<
P> EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is
237N/A<
H2><
A NAME="flowctrl">Flow Control Elements</
A></
H2>
237N/AThese are available in Apache 1.2 and above. The basic flow control
237N/A <!--#if expr="<
EM>test_condition</
EM>" -->
237N/A <!--#elif expr="<
EM>test_condition</
EM>" -->
237N/A<
P> The <
STRONG><
CODE>if</
CODE></
STRONG> element works like an
237N/A if statement in a programming language. The test condition
237N/A is evaluated and if the result is true, then the text until
237N/A the next <
STRONG><
CODE>elif</
CODE></
STRONG>, <
STRONG><
CODE>else</
CODE></
STRONG>.
237N/A or <
STRONG><
CODE>endif</
CODE></
STRONG> element is included in the
135N/A<
P> The <
STRONG><
CODE>elif</
CODE></
STRONG> or <
STRONG><
CODE>else</
CODE></
STRONG>
66N/A statements are be used the put text into the output stream
66N/A if the original test_condition was false. These elements
66N/A<
P> The <
STRONG><
CODE>endif</
CODE></
STRONG> element ends the
202N/A <
STRONG><
CODE>if</
CODE></
STRONG> element and is required.
136N/A<
P> <
EM>test_condition</
EM> is one of the following:
111N/A<
DT><
EM>string</
EM><
DD>true if <
EM>string</
EM> is not empty
66N/A<
DT><
EM>string1</
EM> = <
EM>string2</
EM>
195N/A <
EM>string1</
EM> != <
EM>string2</
EM>
135N/A <
EM>string1</
EM> < <
EM>string2</
EM>
135N/A <
EM>string1</
EM> <= <
EM>string2</
EM>
135N/A <
EM>string1</
EM> > <
EM>string2</
EM>
135N/A <
EM>string1</
EM> >= <
EM>string2</
EM>
66N/A<
DD>Compare string1 with string 2. If string2 has the form <
EM>/string/</
EM>
195N/A then it is compared as a regular expression.
60N/A Regular expressions have the same syntax as those found in the
111N/A Unix <
SAMP>egrep</
SAMP> command.
111N/A<
DT>( <
EM>test_condition</
EM> )
111N/A <
DD>true if <
EM>test_condition</
EM> is true
111N/A<
DT>! <
EM>test_condition</
EM>
111N/A <
DD>true if <
EM>test_condition</
EM> is false
111N/A<
DT><
EM>test_condition1</
EM> && <
EM>test_condition2</
EM>
111N/A <
DD>true if both <
EM>test_condition1</
EM> and
242N/A <
EM>test_condition2</
EM> are true
242N/A<
DT><
EM>test_condition1</
EM> || <
EM>test_condition2</
EM>
111N/A <
DD>true if either <
EM>test_condition1</
EM> or
111N/A <
EM>test_condition2</
EM> is true
<
P> "<
EM>=</
EM>" and "<
EM>!=</
EM>" bind more tightly than "<
EM>&&</
EM>" and
"<
EM>!</
EM>" binds most tightly. Thus, the following are equivalent:
<!--#if expr="$a = test1 && $b = test2" -->
<!--#if expr="($a = test1) && ($b = test2)" -->
<
P> Anything that's not recognized as a variable or an operator is
treated as a string. Strings can also be quoted: <
EM>'string'</
EM>.
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
<
EM>string1 string2</
EM> results in <
EM>string1 string2</
EM>
<
EM>'string1 string2'</
EM> results in <
EM>string1 string2</
EM>
<
LI><
A HREF="#xbithack">XBitHack</
A>
<
H2><
A NAME="xbithack">XBitHack</
A></
H2>
<!--%plaintext <?INDEX {\tt XBitHack} directive> --> ><
STRONG>Syntax:</
STRONG></
A> XBitHack <
EM>status</
EM><
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
<
EM>Status</
EM> can have 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).
<
H2>Using Server Side Includes for ErrorDocuments</
H2>
describes how to use the features of mod_include to offer internationalized
customized server error documents.