mod_include

MODULE

mod_include

MODULE SUMMARY

Server-parsed documents.

DESCRIPTION

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.

Having the server parse HTML pages is a double edged sword! It can be costly for a heavily loaded server to perform parsing of HTML pages while sending them. Furthermore, it can be considered a security risk to have average users executing commands in the name of the Erlang node user. Carefully consider these items before activating server-side includes.

SERVER-SIDE INCLUDES (SSI) SETUP

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 isn't a problem, all HTML pages can be marked as parsed:

text/x-server-parsed-html html htm
    

SERVER-SIDE INCLUDES (SSI) FORMAT

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.

SERVER-SIDE INCLUDES (SSI) ENVIRONMENT VARIABLES

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.

EWSAPI MODULE INTERACTION

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

SEE ALSO

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

AUTHORS

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