mod_include.html revision 2eaf662cbc81e823e8d9aeb8d54e69e63032493e
5f5870385cff47efd2f58e7892f251cf13761528Timo Sirainen<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <meta name="generator" content="HTML Tidy, see www.w3.org" />
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <!--#include virtual="header.html" -->
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <p>This module provides for server-parsed html documents.</p>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen rel="Help"><strong>Status:</strong></a> Base<br />
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen rel="Help"><strong>Module Identifier:</strong></a>
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen includes_module</p>
eef4ba0cc3e78f8c26804c1c9251a76580a41f0cTimo Sirainen <p>This module provides a filter which will process files
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen before they are sent to the client. The processing is
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen controlled by specially formated SGML comments, referred to as
eef4ba0cc3e78f8c26804c1c9251a76580a41f0cTimo Sirainen <em>elements</em>. These elements allow conditional text, the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen inclusion other files or programs, as well as the setting and
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen printing of environment variables.</p>
12224fcf2de6724c89f63c0f9ee857f28a270df5Timo Sirainen <p>See also: <a href="core.html#options">Options</a> and <a
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen href="core.html.html#SetOutputFilter">SetOutputFilter</a>.</p>
12224fcf2de6724c89f63c0f9ee857f28a270df5Timo Sirainen <p>Server Side Includes are implemented by the
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <code>INCLUDES</code> <a href="/filter.html">filter</a>. If
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen documents containing server-side include directives are given
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen the extension .shtml, the following directives will make Apache
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen parse them and assign the resulting document the mime type of
12224fcf2de6724c89f63c0f9ee857f28a270df5Timo Sirainen <FilesMatch "\.shtml(\..+)?$"><br />
12224fcf2de6724c89f63c0f9ee857f28a270df5Timo Sirainen SetOutputFilter INCLUDES<br />
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen </FilesMatch></code>
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen </blockquote>
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <p>Be careful to properly scope the INCLUDES filter to process
12224fcf2de6724c89f63c0f9ee857f28a270df5Timo Sirainen only the correct files. The filter is <strong>not</strong>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen restricted to processing only HTML files. So, for example, if
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the INCLUDES filter is activated using a
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code><Directory></code> section and that directory
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen includes GIF files, mod_include will process the GIF files.
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen This can have two adverse consequences: 1. there will be extra
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen overhead in serving these files, and 2. these files could
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen become corrupted if they happen to contain something that looks
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen like an SSI element.</p>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <p>The following directive must be given for the directories
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen containing the shtml files (typically in a
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code><Directory></code> section, but this directive is
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen also valid .htaccess files if <code>AllowOverride
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen </blockquote>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <p>For backwards compatibility, the <code>server-parsed</code>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <a href="/handler.html">handler</a> also activates the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen INCLUDES filter. As well, Apache will activate the INCLUDES
f77da594de6318312a7f31589c9e4c38e2b74c73Timo Sirainen filter for any document with mime type
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code>text/x-server-parsed-html3</code> (and the resulting
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen output will have the mime type <code>text/html</code>).</p>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen href="/howto/ssi.html">Tutorial on Server Side
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen The document is parsed as an HTML document, with special
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen commands embedded as SGML comments. A command has the syntax:
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code><!--#</code><em>element attribute=value
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen </blockquote>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen The value will often be enclosed in double quotes; many
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen commands only allow a single attribute-value pair. Note that
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the comment terminator (<samp>--></samp>) should be preceded
f77da594de6318312a7f31589c9e4c38e2b74c73Timo Sirainen by whitespace to ensure that it isn't considered part of an SSI
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen This command controls various aspects of the parsing. The
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen valid attributes are:
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dd>The value is a message that is sent back to the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen client if an error occurs whilst parsing the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen document.</dd>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dd>The value sets the format to be used which displaying
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the size of a file. Valid values are <code>bytes</code>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen for a count in bytes, or <code>abbrev</code> for a count
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen in Kb or Mb as appropriate.</dd>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dd>The value is a string to be used by the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code>strftime(3)</code> library routine when printing
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dt><strong><a id="echo" name="echo">echo</a></strong></dt>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen This command prints one of the include variables, defined
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen below. If the variable is unset, it is printed as
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code>(none)</code>. Any dates printed are subject to the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen currently configured <code>timefmt</code>. Attributes:
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dd>The value is the name of the variable to print.</dd>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <dd>Specifies how Apache should encode special characters
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen contained in the variable before outputting them. If set
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen to "none", no encoding will be done. If set to "url",
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen then URL encoding (also known as %-encoding; this is
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen appropriate for use within URLs in links, etc.) will be
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen performed. At the start of an <code>echo</code> element,
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the default is set to "entity", resulting in entity
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen encoding (which is appropriate in the context of a
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen block-level HTML element, eg. a paragraph of text). This
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen can be changed by adding an <code>encoding</code>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen attribute, which will remain in effect until the next
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code>encoding</code> attribute is encountered or the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen element ends, whichever comes first. Note that the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <code>encoding</code> attribute must <em>precede</em> the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen corresponding <code>var</code> attribute to be effective,
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen and that only special characters as defined in the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen ISO-8859-1 character encoding will be encoded. This
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen encoding process may not have the desired result if a
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen different character encoding is in use. Apache 1.3.12 and
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen above; previous versions do no encoding.</dd>
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen The exec command executes a given shell command or CGI
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen script. The IncludesNOEXEC <a
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen href="core.html#options">Option</a> disables this command
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen completely. The valid attributes are:
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen The value specifies a (%-encoded) URL relative path to
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the CGI script. If the path does not begin with a (/),
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen then it is taken to be relative to the current
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen document. The document referenced by this path is
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen invoked as a CGI script, even if the server would not
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen normally recognize it as such. However, the directory
1db62753d9e3b5d71018889c8ef0a3722a307455Timo Sirainen containing the script must be enabled for CGI scripts
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen href="mod_alias.html#scriptalias">ScriptAlias</a> or
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen the ExecCGI <a href="core.html#options">Option</a>).
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen <p>The CGI script is given the PATH_INFO and query
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen string (QUERY_STRING) of the original request from the
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen client; these cannot be specified in the URL path. The
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen include variables will be available to the script in
4eecd3e2aadb20768a60f701e329b4345d04430cTimo Sirainen addition to the standard <a href="mod_cgi.html">CGI</a>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen environment.</p>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <p>If the script returns a Location: header instead of
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen output, then this will be translated into an HTML
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen <p>The <code>include virtual</code> element should be
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen used in preference to <code>exec cgi</code>.</p>
b932ee7fbbec6e79b777dcc7ba613b9e99f8337bTimo Sirainen <dd>The server will execute the given string using
b932ee7fbbec6e79b777dcc7ba613b9e99f8337bTimo Sirainen <code>/bin/sh</code>. The include variables are available
b932ee7fbbec6e79b777dcc7ba613b9e99f8337bTimo Sirainen to the command.</dd>
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen This command prints the size of the specified file, subject
5fbccc935e3f7b916aa7c6e302a212821072e83aTimo Sirainen to the <code>sizefmt</code> format specification.
cf63dc8723b971cc80638fccbf494d961cbafc7fTimo Sirainen <dd>The value is a path relative to the directory
cf63dc8723b971cc80638fccbf494d961cbafc7fTimo Sirainen containing the current document being parsed.</dd>
b932ee7fbbec6e79b777dcc7ba613b9e99f8337bTimo Sirainen <dd>The value is a (%-encoded) URL-path relative to the
23878bd03d1de531e3261a25598beec621351910Timo Sirainen current document being parsed. If it does not begin with
23878bd03d1de531e3261a25598beec621351910Timo Sirainen a slash (/) then it is taken to be relative to the
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen current document.</dd>
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <dd>This command prints the last modification date of the
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen specified file, subject to the <code>timefmt</code> format
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen specification. The attributes are the same as for the
23878bd03d1de531e3261a25598beec621351910Timo Sirainen This command inserts the text of another document or file
23878bd03d1de531e3261a25598beec621351910Timo Sirainen into the parsed file. Any included file is subject to the
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen usual access control. If the directory containing the
23878bd03d1de531e3261a25598beec621351910Timo Sirainen parsed file has the <a href="core.html#options">Option</a>
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen IncludesNOEXEC set, and the including the document would
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen cause a program to be executed, then it will not be
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen included; this prevents the execution of CGI scripts.
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen Otherwise CGI scripts are invoked as normal using the
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen complete URL given in the command, including any query
cf63dc8723b971cc80638fccbf494d961cbafc7fTimo Sirainen <!--%plaintext <?INDEX CGI scripts, {\tt include} element and> -->
1a3f9d72e15fb931edf58f104fb7ff12d238f051Timo Sirainen <p>An attribute defines the location of the document; the
23878bd03d1de531e3261a25598beec621351910Timo Sirainen inclusion is done for each attribute given to the include