mirror of
https://github.com/apache/httpd.git
synced 2025-05-19 02:21:09 +03:00
8a147876e2
This is the end of this pass for the online manual. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@78228 13f79535-47bb-0310-9956-ffa450edef68
386 lines
13 KiB
HTML
386 lines
13 KiB
HTML
<!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>
|