---
name: "mod_include"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:10.b.1a-1"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/mod_include"
---

# mod\_include(3erl)

Server-parsed documents.

## NAME

mod\_include - 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.

### Note:

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 is not 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.ericsson.se
Mattias Nilsson  - support@erlang.ericsson.se
```