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