Server Side Includes

Webpages that are interactive or provide current information generally need to be "active" in some way. There are two main methods of achieving this:

a script modifies the webpage
the webpage is built automatically when requested

Scripted modification is a reasonable solution if the webpage to be built is always edited on the website itself and the script can be trusted not to mess up the page. If the webpage is to be edited on a remote system then this is not a sensible method as the script-updated copy will be erased on upload of a new version.

Automatic generation is generally a better approach, and can be achieved by either having a script run to create the whole page, or having a static page but asking the webserver to include active content as the page is requested. This latter option is SSI.

SSI provides a neat solution for simple active inclusions because it allows easy editing of the webpage in plain HTML. It is less suitable for pages consisting almost entirely of active content where a traditional script-generated page may be easier to maintain.

Enabling SSI

SSI is accessed using tags which are inserted into the webpage. These are in the form of HTML comments (and so will be ignored by the browser if accidentally passed on by the server). However since searching for these tags in HTML files is time-consuming the server must be told which documents use SSI. With Apache (currently running on zeus) there are three main ways to do this:

changing the file's extension to .shtml
adding a suitable .htaccess file to the directory
persuading someone to switch on the XBitHack on the webserver and then making the .html file executable

The .shtml file extension is the simplest solution. However given existing pages an .htaccess file can be placed in the directory containing the webpage to use SSI. The file should contain the line:

AddHandler server-parsed .html

SSI variables

SSI makes the following variables available to commands:

DATE_GMT
the current date in GMT
DATE_LOCAL
the current local date
DOCUMENT_NAME
the filename (excluding directories) of the document requested
DOCUMENT_URI
The URL of the document requested
LAST_MODIFIED
the last modification date of the document requested

SSI commands

There are several SSI commands, the most obviously useful of which are listed below. For information about others (which include viewing and setting server variables and conditional removal of parts of the webpage) please follow the link to the Apache documentation (for the module mod_include).

echo

echo prints a server variable. It takes one attribute, var, the name of the variable.

This produces: Wednesday, 16-May-2012 12:39:27 BST

flastmod

flastmod prints the date on which any specified file was last modified. It can take either a file or virtual attribute. If a file attribute is used then it is the path to the file in question relative to the current directory (in which the webpage is stored). If virtual is used then this is the virtual URL relative to the current document. For example:

This produces: Wednesday, 16-Mar-2005 22:14:50 GMT

include

include inserts the contents of another document. Its attributes are the same as those for flastmod, but "file" cannot contain "../" or be an absolute path. "virtual" may however include a query string. Use of "virtual" is preferred.

This produces: doco-content/html-only

exec

exec executes a given command. It can take either a cgi or cmd attribute. cgi takes the relative URL to a cgi script. cmd takes a command to be executed by /bin/sh.

It is generally better just to use the "include" command, for example:

Calling scripts with SSI

A final point to note is that if an exec or include command would cause a program to run then this will only succeed if allowable. Scripts are most easily made runnable by placing them in a directory called cgi-bin and making sure that the permissions on this directory do not allow anyone except the owner to write:

chmod 755 cgi-bin

On zeus, using zeus-cgi-handler

For full information, see:

Zeus notes for webmasters

On suEXEC systems

Restricitions on programs which can be called are listed in Apache's suexec manual. Essentially, since Apache currently switches to be you when executing your programs (using the suexec facility), it won't run anything that isn't yours, isn't in your own webspace, is writable by anyone else, or is backreferenced with "../" or "/". This seems to limit the use of exec to the cgi option (since cmd would need to run /bin/sh).