Apache: The Definitive Guide

Chapter 10: Server Side Includes

Server-Side Includes

The object of this set of facilities is to allow statements that trigger further actions to be put into served documents. The same results could be achieved by CGI scripts, either shell scripts or specially written C programs, but server-side includes often do what is wanted with a lot less effort.

The manual page for the module mod_include is somewhat opaque, but on the other hand the range of possible actions is immense, so we will just give basic illustrations of each command in a number of text files in .../htdocs.

The Config file for this site (.../site.ssi) is:

User webuser
Group webgroup
ServerName www.butterthlies.com
DocumentRoot /usr/www/site.ssi/htdocs
AccessConfig /dev/null
ResourceConfig /dev/null
AddHandler server-parsed shtml

The key line is:

AddHandler server-parsed shtml

shtml is our own invention and is found as the extension to the relevant files in .../htdocs. We could as well use brian or #dog_run as long as it appeared the same there, in the file with the relevant command, and in the configuration file. As usual, look in the error_log if things don't work. The error messages passed to the client are necessarily uninformative since they are probably being read three continents away where nothing useful can be done about them.

The trick is to insert special strings into our documents which then get picked up by Apache on their way through, recognized, and then replaced by dynamically written messages. As we will see, the strings have a deliberately unusual form so they won't get confused with more routine stuff. The syntax of a command is:

<!--#element attribute=value attribute=value ... -->

The Apache manual tells us what the elements are.

config

This command controls various aspects of the parsing. The valid attributes are:

errmsg: The value is a message that is sent back to the client if an error occurs during document parsing.

sizefmt

: The value sets the format to be used when displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in kilobytes or megabytes as appropriate.

timefmt

: The value is a string to be used by the strftime() library routine when printing dates.

echo

This command prints one of the include variables, defined below. If the variable is unset, it is printed as (none). Any dates printed are subject to the currently configured timefmt. The only attribute is:

var

: The value is the name of the variable to print.

exec

The exec command executes a given shell command or CGI script. The IncludesNOEXEC option disables this command completely. The valid attribute is:

cgi

: The value specifies a %-encoded URL relative path to the CGI script. If the path does not begin with a slash, it is taken to be relative to the current document. The document referenced by this path is invoked as a CGI script, even if the server would not normally recognize it as such. However, the directory containing the script must be enabled for CGI scripts (with ScriptAlias or the ExecCGI option). The CGI script is given the PATH_INFO and query string (QUERY_STRING) of the original request from the client; these cannot be specified in the URL path. The include variables will be available to the script in addition to the standard CGI environment. If the script returns a Location header instead of output, this is translated into an HTML anchor. If Options NoExec is set in the Config file, this is turned off. The include virtual element should be used in preference to exec cgi.

cmd

: The server executes the given string using /bin/sh. The include variables are available to the command. If Options NoExec is set in the Config file, this is turned off.

fsize

This command prints the size of the specified file, subject to the sizefmt format specification. The attributes are:

file

: The value is a path relative to the directory containing the current document being parsed.

virtual

: The value is a %-encoded URL path relative to the current document being parsed. If it does not begin with a slash, it is taken to be relative to the current document.

flastmod

: This command prints the last modification date of the specified file, subject to the timefmt format specification. The attributes are the same as for the fsize command.

include

This command inserts the text of another document or file into the parsed file. Any included file is subject to the usual access control. If the directory containing the parsed file has the Option IncludesNOEXEC set and including the document causes a program to be executed, it isn't included; this prevents the execution of CGI scripts. Otherwise, CGI scripts are invoked as normal using the complete URL given in the command, including any query string.

An attribute defines the location of the document; the inclusion is done for each attribute given to the include command. The valid attributes are:

file

: The value is a path relative to the directory containing the current document being parsed. It can't contain ../, nor can it be an absolute path. The virtual attribute should always be used in preference to this one.

virtual

: The value is a %-encoded URL relative to the current document being parsed. The URL cannot contain a scheme or hostname, only a path and an optional query string. If it does not begin with a slash, then it is taken to be relative to the current document. A URL is constructed from the attribute's value, and the server returns the same output it would have if the client had requested that URL. Thus included files can be nested. A CGI can still be run by this method even if Options NoExec is set in the Config file. The reasoning is that clients can run the CGI anyway by using its URL as a hot link, or simply typing it into their browser, so no harm is done by using this method (unlike cmd or exec).

File Size

The fsize command allows you to report the size of a file inside a document. The file size.shtml is:

<!--#config errmsg="Bungled again!"-->
<!--#config sizefmt="bytes"-->
The size of this file is <!--#fsize file="size.shtml"--> bytes.
The size of another_file is <!--#fsize file="another_file"--> bytes.

The first line provides an error message. The second line means that the size of any files is reported in bytes printed as a number, for instance: 89. Changing bytes to abbrev gets the size in kilobytes, printed as 1k. The third line prints the size of size.shtml itself; the fourth line prints the size of another_file. You can't comment out lines with the # character since it just prints, and the following command is parsed straight away. config commands must come above commands that might want to use them.

You can replace the word file= in this script and those below, with virtual=, which gives %-encoded URL-path relative to the current document being parsed. If it does not begin with a slash, it is taken to be relative to the current document.

If you play with this stuff, you find that Apache is picky about the syntax. For instance, trailing spaces cause an error:

The size of this file is <!--#fsize file="size.shtml   "--> bytes.
The size of this file is Bungled again! bytes

If we had not used the errmsg command, we would see:

...[an error occurred while processing this directive]...

File Modification Time

The last modification time of a file can be reported with flastmod. This gives the client an idea of the freshness of the data you are offering. The format of the output is controlled by the timefmt attribute of the config element. The rules for timefmt are the same as for the UNIX C function strftime().

% man strftime

shows them (we have not included it here because it may well vary from system to system). The file time.shtml gives an example:

<!--#config errmsg="Bungled again!"-->
<!--#config timefmt="%A %B %C, the %jth day of the year, %S seconds since the Epoch"-->
The mod time of this file is <!--#flastmod virtual="size.shtml"-->
The mod time of another_file is <!--#flastmod virtual="another_file"-->

This produces a response like:

The mod time of this file is Tuesday August 19, the 240th day of the year, 841162166 seconds since the Epoch The mod time of another_file is Friday August 19, the 229th day of the year, 840194838 seconds since the Epoch

(The alert reader will notice a certain inconsistency about the dates. This is being investigated as a bug.)

Includes

We can include one file in another with the include command:

<!--#config errmsg="Bungled again!"-->
This is some text in which we want to include text from another file:
<< <!--#include virtual="another_file"--> >>
That was it.

This produces the response:

This is some text in which we want to include text from another file:
<< This the stuff in 'another_file'. >>
That was it.

Execute CGI

We can have a CGI script executed without having to bother with AddHandler, SetHandler, or ExecCGI. The command is exec {cmd cgi}:

<!--#config errmsg="Bungled again!"-->
We're now going to execute the file 'do_this'.
<< <!--#exec cmd="rubbish/do_this"--> >>
and now /usr/www/cgi-bin/mycgi.ok:
<< <!--#exec cmd="/usr/www/cgi-bin/mycgi.ok"--> >>
That was it.

The script do_this is simply ls -l.

We are already familiar with mycgi.ok (see Chapter 4, Common Gateway Interface (CGI)). There are two attributes available to exec: cgi and cmd. cgi executes CGI scripts, and cmd uses the shell /bin/sh. For fine detail, see the manual, to which we cannot usefully add. This produces the response:

We're now going to execute the file 'do_this'. << >> and
              now /usr/www/cgi-bin/mycgi.ok: <<
Content-type: text/html GATEWAY_INTERFACE=CGI/1.1 REMOTE_HOST=192.168.123.1
DOCUMENT_URI=/exec.shtml REMOTE_ADDR=192.168.123.1 QUERY_STRING=
HTTP_USER_AGENT=Mozilla/3.0Gold (Win95; I)
DOCUMENT_ROOT=/usr/www/site.ssi/htdocs HTTP_ACCEPT=image/gif,
               image/x-xbitmap,
image/jpeg, image/pjpeg, */* SCRIPT_FILENAME=/usr/www/site.ssi/htdocs/
               exec.shtml
LAST_MODIFIED=Thursday, 12-Sep-96 16:34:49 DOCUMENT_NAME=exec.shtml
HTTP_HOST=192.168.123.2 SERVER_SOFTWARE=Apache/1.2-dev
HTTP_CONNECTION=Keep-Alive HTTP_COOKIE=Apache=192380845288358461
PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin HTTP_REFERER=
               http://192.168.123.2/
SERVER_PROTOCOL=HTTP/1.0 DATE_GMT=Monday, 14-Oct-96 10:21:00
DOCUMENT_PATH_INFO= REQUEST_METHOD=GET SERVER_ADMIN=[no address
given] SERVER_PORT=80 USER_NAME=root SCRIPT_NAME=/exec.shtml
SERVER_NAME=www.butterthlies.com DATE_LOCAL=Monday, 14-Oct-96 10:21:00 >>
That was it.

Echo

Finally, we can echo a limited number of environment variables: DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, DOCUMENT_URI, and LAST_MODIFIED. The file echo.shtml is:

Echoing the Document_URI <!--#echo var="DOCUMENT_URI"-->
Echoing the DATE_GMT <!--#echo var="DATE_GMT"-->

and produces the response:

Echoing the Document_URI /echo.shtml
Echoing the DATE_GMT Saturday, 17-Aug-96 07:50:31

XBitHack

This is an obsolete facility to do server-side includes automatically if the execute permission is set on a file. It is provided for backward compatibility. If the group execute bit is set, a long expiration time is given to the browser.

XSSI

This is an extension of the standard SSI commands available in the XSSI module, which became a standard part of the Apache distribution from Version 1.2. Unfortunately it was released as this book was going to press, and we can't vouch for it.

XSSI adds the following abilities to the standard SSI:

XSSI allows variables in any SSI commands. For example, the last modification time of the current document could be obtained with:

<tt>&lt;!--#flastmod file="$DOCUMENT_NAME" --&gt.

The set command sets variables within the SSI.
SSI commands if, else, elif, and endif are used to include parts of the file based on conditional tests. For example, the $HTTP_USER_AGENT variable could be tested to see the type of browser and different HTML codes output depending on the browser capabilities.

Return to Apache: The Definitive Guide