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