mod_include - Server-parsed documents.

This module makes it possible to expand "macros" embedded in HTML pages before they are delivered to the client, that is Server-Side Includes (SSI). To make this possible the server parses HTML pages on-the-fly and optionally includes the current date, the requested file's last modification date or the size (or last modification date) of other files. In its more advanced form, it can include output from embedded CGI and /bin/sh scripts.

Note:

The server must be told which filename extensions to be used for the parsed files. These files, while very similar to HTML, are not HTML and are thus not treated the same. Internally, the server uses the magic MIME type text/x-server-parsed-html to identify parsed documents. It will then perform a format conversion to change these files into HTML for the client. Update the mime.types file, as described in the Mime Type Settings section of httpd(3), to tell the server which extension to use for parsed files, for example:

text/x-server-parsed-html shtml shtm

This makes files ending with .shtml and .shtm into parsed files. Alternatively, if the performance hit is not a problem, all HTML pages can be marked as parsed:

text/x-server-parsed-html html htm

All server-side include directives to the server are formatted as SGML comments within the HTML page. This is in case the document should ever find itself in the client's hands unparsed. Each directive has the following format:

<!--#command tag1="value1" tag2="value2" -->

Each command takes different arguments, most only accept one tag at a time. Here is a breakdown of the commands and their associated tags:

config: The config directive controls various aspects of the file parsing. There are two valid tags:

errmsg: controls the message sent back to the client if an error occurred while parsing the document. All errors are logged in the server's error log.

sizefmt: determines the format used to display the size of a file. Valid choices are bytes or abbrev. bytes for a formatted byte count or abbrev for an abbreviated version displaying the number of kilobytes.

include: will insert the text of a document into the parsed document. This command accepts two tags:

virtual: gives a virtual path to a document on the server. Only normal files and other parsed documents can be accessed in this way.

file: gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths. As above, you can send other parsed documents, but you cannot send CGI scripts.

echo: prints the value of one of the include variables (defined below). The only valid tag to this command is var, whose value is the name of the variable you wish to echo.

fsize: prints the size of the specified file. Valid tags are the same as with the include command. The resulting format of this command is subject to the sizefmt parameter to the config command.

flastmod: prints the last modification date of the specified file. Valid tags are the same as with the include command.

exec: executes a given shell command or CGI script. Valid tags are:

cmd: executes the given string using /bin/sh. All of the variables defined below are defined, and can be used in the command.

cgi: executes the given virtual path to a CGI script and includes its output. The server does not perform error checking on the script output.

A number of variables are made available to parsed documents. In addition to the CGI variable set, the following variables are made available:

DOCUMENT_NAME: The current filename.

DOCUMENT_URI: The virtual path to this document (such as /docs/tutorials/foo.shtml).

QUERY_STRING_UNESCAPED: The unescaped version of any search query the client sent, with all shell-special characters escaped with \.

DATE_LOCAL: The current date, local time zone.

DATE_GMT: Same as DATE_LOCAL but in Greenwich mean time.

LAST_MODIFIED: The last modification date of the current document.

Uses the following EWSAPI interaction data, if available:

{real_name, {Path, AfterPath}}: as defined in mod_alias(3).

{remote_user, RemoteUser}: as defined in mod_auth(3)

Exports the following EWSAPI interaction data, if possible:

{mime_type, MimeType}: The file suffix of the incoming URL mapped into a MimeType as defined in the Mime Type Settings section of httpd_core(3).

Uses the following EWSAPI functions:

*

mod_cgi:env/3

*

mod_alias:path/3

*

mod_alias:real_name/3

*

mod_alias:real_script_name/3

httpd(3), mod_alias(3), mod_auth(3), mod_security(3), mod_cgi(3)

Joakim Grebenö  - support@erlang.ericsson.se
Mattias Nilsson  - support@erlang.ericsson.se