mod_include.html revision c9aaa4cb1a852cad08fb47cf348f8c38332dc797
bcb4e51a409d94ae670de96afb8483a4f7855294Stephan Bosch<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen BGCOLOR="#FFFFFF"
156027ee3a689893bf22271d1cea8c97f9813cb9Timo Sirainen TEXT="#000000"
156027ee3a689893bf22271d1cea8c97f9813cb9Timo Sirainen LINK="#0000FF"
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen VLINK="#000080"
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen ALINK="#FF0000"
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<!--#include virtual="header.html" -->
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenThis module is contained in the <CODE>mod_include.c</CODE> file, and
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenis compiled in by default. It provides for server-parsed html
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainendocuments. Several directives beyond the original NCSA definition were
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenintroduced in Apache 1.2 - these are flagged below with the phrase
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen"Apache 1.2 and above". Of particular significance are the new flow
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainencontrol directives documented at the bottom.
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenAny document with handler of "server-parsed" will be parsed by this
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenmodule, if the <CODE>Includes</CODE> option is set. If documents
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainencontaining server-side include directives are given the extension
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen.shtml, the following directives will make Apache parse them and
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenassign the resulting document the mime type of <CODE>text/html</CODE>:
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenAddHandler server-parsed .shtml
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe following directive must be given for the directories containing
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenthe shtml files (typically in a <CODE><Directory></CODE> section,
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenbut this directive is also valid .htaccess files if <CODE>AllowOverride
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenOptions</CODE> is set):
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenOptions +Includes
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenAlternatively the <A HREF="#xbithack"><CODE>XBitHack</CODE></A>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainendirective can be used to parse normal (<CODE>text/html</CODE>) files,
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenbased on file permissions. <P>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenFor backwards compatibility, documents with mime type
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<CODE>text/x-server-parsed-html3</CODE> will also be parsed
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen(and the resulting output given the mime type <CODE>text/html</CODE>).
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe document is parsed as an HTML document, with special commands embedded
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenas SGML comments. A command has the syntax:
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<!--#</CODE><EM>element attribute=value attribute=value ...</EM>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe value will often be enclosed in double quotes; many commands only allow
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainena single attribute-value pair. Note that the comment terminator
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen(<SAMP>--></SAMP>) should be preceded by whitespace to ensure that it
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenisn't considered part of an SSI token.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe allowed elements are:<P>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThis command controls various aspects of the parsing. The valid attributes
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<DD>The value is a message that is sent back to the client if an error occurs
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenwhilst parsing the document.
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainen<DD>The value sets the format to be used which displaying the size of a file.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenValid values are <CODE>bytes</CODE> for a count in bytes, or
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<CODE>abbrev</CODE> for a count in Kb or Mb as appropriate.
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainen<DD>The value is a string to be used by the <CODE>strftime(3)</CODE> library
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenroutine when printing dates.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThis command prints one of the include variables, defined below.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenIf the variable is unset, it is printed as <CODE>(none)</CODE>.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenAny dates printed are subject to the currently configured <CODE>timefmt</CODE>.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<DD>The value is the name of the variable to print.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<DD>Specifies how Apache should encode special characters contained
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenin the variable before outputting them. If set to "none", no encoding
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenwill be done. If set to "url", then URL encoding (also known as
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainen%-encoding; this is appropriate for use within URLs in links, etc.)
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenwill be performed. At the start of an <CODE>echo</CODE> element,
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenthe default is set to "entity", resulting in entity encoding (which
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenis appropriate in the context of a block-level HTML element, eg.
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainena paragraph of text). This can be changed by adding an
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<CODE>encoding</CODE> attribute, which will remain in effect until
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenthe next <CODE>encoding</CODE> attribute is encountered or the
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenelement ends, whichever comes first. Note that the
5ae97456417a137a85c236a3db32f51fb592e474Timo Sirainen<CODE>encoding</CODE> attribute must <EM>precede</EM> the corresponding
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<CODE>var</CODE> attribute to be effective, and that only special
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainencharacters as defined in the ISO-8859-1 character encoding will be
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenencoded. This encoding process may not have the desired result if
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainena different character encoding is in use.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenApache 1.3.12 and above; previous versions do no encoding.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe exec command executes a given shell command or CGI script.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe IncludesNOEXEC <A HREF="core.html#options">Option</A> disables this command
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainencompletely. The valid attributes are:
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenThe value specifies a (%-encoded) URL relative path to the CGI script.
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenIf the path does not begin with a (/), then it is taken to be relative to
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenthe current document. The document referenced by this path is invoked
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenas a CGI script, even if the server would not normally recognize it as
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainensuch. However, the directory containing the script must be enabled for
dcb783533ad1d6944db7c227cde46414a575d81cTimo SirainenCGI scripts (with <A HREF="mod_alias.html#scriptalias">ScriptAlias</A>
dcb783533ad1d6944db7c227cde46414a575d81cTimo Sirainenor the ExecCGI <A HREF="core.html#options">Option</A>).<P>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe CGI script is given the PATH_INFO and query string (QUERY_STRING) of the
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenoriginal request from the client; these cannot be specified in the URL path.
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe include variables will be available to the script in addition to the
5ae97456417a137a85c236a3db32f51fb592e474Timo Sirainenstandard <A HREF="mod_cgi.html">CGI</A> environment.<P>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenIf the script returns a Location: header instead of output, then this
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenwill be translated into an HTML anchor.<P>
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenThe <CODE>include virtual</CODE> element should be used in preference to
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainen<DD>The server will execute the given string using <CODE>/bin/sh</CODE>.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo SirainenThe include variables are available to the command.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo SirainenThis command prints the size of the specified file, subject to the
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainen<CODE>sizefmt</CODE> format specification. Attributes:
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainen<DD>The value is a path relative to the directory containing the current
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainendocument being parsed.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainen<DD>The value is a (%-encoded) URL-path relative to the current document being
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainenparsed. If it does not begin with a slash (/) then it is taken to be relative
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainento the current document.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo SirainenThis command prints the last modification date of the specified file,
8b48c53a81bdc67f267ffbcc45ba9860cb49e977Timo Sirainensubject to the <CODE>timefmt</CODE> format specification. The attributes are
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainenthe same as for the <CODE>fsize</CODE> command.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo SirainenThis command inserts the text of another document or file into the parsed
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo Sirainenfile. Any included file is subject to the usual access control. If the
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo Sirainendirectory containing the parsed file has the
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo SirainenIncludesNOEXEC set, and the including the document would cause a program
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo Sirainento be executed, then it will not be included; this prevents the execution of
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo SirainenCGI scripts. Otherwise CGI scripts are invoked as normal using the complete
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo SirainenURL given in the command, including any query string.
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo Sirainen<!--%plaintext <?INDEX CGI scripts, {\tt include} element and> -->
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo SirainenAn attribute defines the location of the document; the inclusion is done for
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Siraineneach attribute given to the include command. The valid attributes are:
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainen<DD>The value is a path relative to the directory containing the current
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainendocument being parsed. It cannot contain <CODE>../</CODE>, nor can it be an
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenabsolute path. The <CODE>virtual</CODE> attribute should always be used
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenin preference to this one.
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainen<DD>The value is a (%-encoded) URL relative to the current document being
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainenparsed. The URL cannot contain a scheme or hostname, only a path and
c25abb52b05f4a7e380134ac21e7525d0b46187aTimo Sirainenan optional query string. If it does not begin with a slash (/) then it
bf698b98d3a3a1eced66cc682c449f23bf2b67d0Timo Sirainenis taken to be relative to the current document.
156027ee3a689893bf22271d1cea8c97f9813cb9Timo SirainenA URL is constructed from the attribute, and the output the server
37dfa8907f8216aa73e3880f3f98aba634458e42Timo Sirainenwould return if the URL were accessed by the client is included in the parsed
156027ee3a689893bf22271d1cea8c97f9813cb9Timo Sirainenoutput. Thus included files can be nested.
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Default"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Override"
HREF="directive-dict.html#Status"
HREF="directive-dict.html#Module"
<!--#include virtual="footer.html" -->