[ Up (Contents) ] Last Updated: 30 August 2000


The XHTML 1.0 Web development Sourcebook

Syntax for Server-Side Includes


The server-side includes (SSI) mechanism is a simple, widely supported syntax for embedding commands inside HyperText Markup Language (HTML)/eXtensible Markup Language–based HTML (XHTML) documents for processing by the Web server before the documents are served out. SSI commands are placed inside documents as HTML comment strings, using the special syntax:

<!--#include_command -->

When parsed by a server supporting the SSI feature, the entire comment string is replaced by the output of include_command. Because the command is inside a comment string, this will not cause parsing problems if the document is processed by a server that does not support this feature, or if this feature disabled. Such servers will simply deliver the document, including the comment line—and the client will treat the string as a comment and will ignore it.

The general form for an include command is

<!--#command argl="value1" arg2="value2" -->

where command is the name of the command to be executed and argl and arg2 are arguments passed to the command. There must be no space between the hash sign (#) and the command name, or between the hash sign and the leading double dash (--#). The number and name of the argument(s) depend on the actual command—most commands take one or no arguments. Note that, despite its structure, this is not a comment statement. You cannot include comment descriptions inside an include command. Consequently, lines like

<!--#command argl="value1" This prints the time of day -->

are invalid, and will be ignored by the SSI processor.

There are eight SSI commands: config, echo, exec, fsize, flastmod, include, printenv, and set. Config configures the way the server parses the document. Include includes another document [not a Common Gateway Interface (CGI) program] at the indicated location, while echo includes the contents of one of the special environment variables that are set for parsed documents. Fsize and flastmod are similar to echo; fsize prints the size of a specified file, while flastmod prints the last modification date of a specified file. Printenv prints out a list of all the variables defined to the parsed HTML page, while set lets the document define special variables used by the parsed document. Finally, exec executes a single-line Bourne shell command or a CGI program. For security reasons, the exec facility can be disabled in the server configuration files while the other features remain operational.

The next sections describe each of these commands and how they work; entries in italics are variables to be set by the document author. Table E.1 summarizes the commands and the allowed forms.

The Apache SSI implementation also supports four SSI conditional commands, designated if, elif, else, and endif. The syntax for these statements is shown in Table E.1, while their use is described in Section E.2.


E.1 SSI Command Specifications

This section briefly describes the eight commands introduced in the previous section and listed in Table E.1. This specification describes the SSI features as implemented on the Apache 1.2 and later servers. Some of these features may be implemented differently (or not at all) on other servers. Please see your own server documentation for details.

Table E.1  
Server-Side Include Commands Supported by the Apache Server. Strings in Italics are Set by the Document Author.
<--#config errmsg="err_str" --> Set error message to be returned upon error.
<--#config timefmt="format_str" --> Set format for times and dates.
<--#config sizefmt="bytes" --> Set format for printing file sizes to bytes.
<--#config sizefmt="abbrev" --> Set format for printing file sizes—bytes, Kbytes, or Mbytes, depending on size.
<--#echo var="variable" --> Print contents of listed environment variable.
<--#exec cmd="cmd_string" --> Execute the given Bourne shell command string and include the output inline.
<--#exec cgi="path/cgi_prog" --> Execute the indicated CGI program and include the output inline.
<--#flastmod virtual="virt/file" --> Print last modification date of the file at the indicated virtual location.
<--#flastmod file="path/file" --> Print last modification date of the file at the indicated relative location.
<--#fsize virtual="virt/file" --> Print size of the file at the indicated virtual location.
<--#fsize file="path/file" --> Print size of the file at the indicated relative location.
<--#include virtual="virt/file" --> Include document from the indicated virtual location.
<--#include file="path/file" --> Include document from indicated relative location.
<!--#printenv --> Print out a list of all existing variables and their values. For Apache 1.3.12 and later, special characters in the URL text are encoded using HTML entity references.
<!--#set nal="val" na2="va2" --> Set the value for one or more variables.
<!--#if expr="test_condn" --> See Section E.2.
<!--#elif expr="test_condn" --> See Section E.2.
<!--#else --> See Section E.2.
<!--#endif --> See Section E.2.

Back to top

E.1.1 Include: Include Another Document

This directive includes another document (or another parsed document) at the given location in the current document. Include can take one of two possible arguments specifying the file to be included. These are:

virtual="virtual-path/file". Specifies the virtual Uniform Resource Locator (URL) path to the document, relative to the server’s document directory or to a user’s personal server directory. For example, user fosdick with his or her own public HTML area would access files in this area with the virtual path:

<!--#include virtual="~fosdick/path/file.html" -->

Note that the location string must be URL escaped, as per the URL syntax described in Chapter 8. In Apache 1.2 and later, the virtual path can reference a CGI program, where the output of the program is included inline.

file="relative-path/file". Specifies the path to the document relative to the current URL. For example, to include the file junk.html from the same directory, or the file blog.html from the subdirectory muck, you would use:

<!--#include file="junk.html" -->

<!--#include file="muck/blog.html" -->

You cannot use this form to move up in the hierarchy, only down (e.g., you can’t use ../stuff.html). Indeed, file is only present to support legacy SSI code written for the NCSA Web server. With new documents you should avoid using the file and use the virtual form instead.

Back to top

E.1.2 Echo: Include Value of a Variable

This directive includes the contents of a named environment variable. The variable is indicated by the argument var="var_name". In this expression, var_name is the name of any of the CGI environment variables listed in Tables 10.2 and 10.3, or one of the special environment variables listed in Table E.2, valid only in parsable files or in CGI programs called from a parsable file. It can also include the value of specially defined SSI variables set using the set directive (see Section E.1.8).

Table E.2  Environment Variables Defined Only in Parsed HTML Documents. These Variables Are Also Available to CGI Programs Executed from within a Parsed HTML Document.
DOCUMENT_NAME The name of the document being parsed. This is the raw name, stripped of any leading path information, extra path information, or query string data. For example, if the accessed URL were of the form /path/to/file.shtml/extra/path?foo, DOCUMENT_NAME would simply be file.shtml.
DOCUMENT_URI The virtual (relative to server document directory) path to the document, such as ~fosdick/path/file.shtml or /path/subpath/templates/template2.html. This will include any extra path information in the requesting URL, but not query string data.
DATE_LOCAL The current date, using the local time zone. The format of this date is controlled using the timefmt argument of the config command.
DATE_GMT Same as DATE_LOCAL, but in Greenwich Mean Time.
LAST_MODIFIED The last modification date of the current document. The format is specified by timefmt.
DOCUMENT_PATH_INFO Contains any extra path information in the requesting URL. For example, if the requesting URL were /path/to/file.shtml/extra/path?foo, the DOCUMENT_PATH_INFO value would be /extra/path. This is the same as the PATH_INFO environment variable.

As of the Apache 1.3.12 server, this directive also takes an encoding argument to specify how special characters in the string should be encoded before they are output. There are three possible values:

encoding="none". No encoding of the data is done.

encoding="url". The data will be encoded as if it were URL data (e.g., spaces will be encoded as the sequence %20).

encoding="entity". Any special HTML characters are encoded using entity references. This is the default encoding value.

Once an encoding value is set, any subsequent var is encoded as indicated. This means that if you want to set the encoding for a specific variable, then the encoding argument must be set before you name the variable. That is, the statement must be written as:

<!--#echo encoding="type" var="var_name" -->

Back to top

E.1.3 Fsize: Include Size of Listed File

This includes the size, in bytes, of a file—the file can be specified using either the file or virtual arguments, as described in the include command section. Fsize is useful for presenting information about a file to be downloaded, particularly when the size varies often. For example:

...Download</A> the mail

archive: (<!--#fsize file="main.html" --> bytes)

The output format is set by the sizefmt argument of the config command.

Back to top

E.1.4 Flastmod: Include Last Modification Time of Listed File

This includes the last modification time of a file specified using the file or virtual arguments, as described in the include command section. Like fsize, flastmod is useful for providing up-to-date information about files that are periodically changed. For example:

This file was last changed on:

<!--#flastmod virtual="/path/dir1/dir2/main.html" -->

The output format is determined by the timefmt argument of the config command.

Back to top

E.1.5 Exec: Execute Shell Script of CGI Program

This directive executes the indicated Bourne shell command or CGI program, and includes the program output inline in the document. The two possible arguments are:

cmd="cmd_string". Causes the string cmd_string to be executed using the Bourne shell (sh). Cmd_string can be a simple one-line shell program that does simple tasks, such as listing directory contents or running a program to filter data for inclusion. The SSI directive is replaced by the output of the shell program. This form is allowed only to support legacy SSI programs—newer SSI pages should avoid cmd and should use cgi instead.

cgi="cgi_program". Executes the given CGI program, where the location of the program is given by the virtual path to the program. Recall that the SSI directive is replaced by the output of the program. Also note that the script must return a valid Multipurpose Internet Mail Extensions (MIME) content type. You cannot pass query strings or path information to the script using the standard URL mechanisms. Thus, expressions like

<!--#exec cgi="/cgi-bin/script.cgi/path1/path2?query" -->

are invalid. The only way you can access the script is with the command:

<!--#exec cgi="/cgi-bin/script.cgi" -->

However, suppose the parsable script stuff.shtml contains the command

<!--#exec cgi="/cgi-bin/script.cgi" -->

and you access the file stuff.shtml via a URL of the form:


In this case, the query_string and /extra/path information are available to the script script.cgi called from stuff.shtml. This is illustrated in an example at the end of this section.

The exec cgi mechanism is supported for legacy reasons only: New documents should use the include virtual directive instead.

Back to top

Environment Variables Within Exec’ed CGIs

The variables defined in Table E.2 are also available within gateway or shell programs that are executed using the exec command. In addition, any extra path or query information appended to the parsed HTML document name is passed to the CGI program within the PATH_INFO and QUERY_STRING variables, as per standard practice. At the same time, several servers define additional environment variables to provide information about the executing script. The most common of these additional variables are given in Table E.3. These variables are defined by Apache (Version 1 and greater) and Netscape/iPlanet servers (and probably by others), but not by NCSA servers prior to version 1.5.

Table E.3   Environment Variables Defined Only within CGI Programs Invoked by a Parsed HTML Document. These Variables Are not Universally Available on All Servers.
SCRIPT_NAME The name of the script being executed, including the virtual path information needed to locate the script.
SCRIPT_FILENAME The complete absolute name of the file, including the path to the file from the root of the file system.


NOTE POSSIBLE PROBLEMS WITH ENVIRONMENT VARIABLES  Some servers do not set the environment variables listed in Table E.3 or at the bottom of Table E.2, while others improperly set their content. To be safe, you should verify the accuracy of all environment variables prior to installing any CGI programs invoked via server-side includes.

Back to top

E.1.6 Config—Set SSI Configuration Settings

This directive controls aspects of the output of the other parsed commands, such as the formats of the date and size output strings, or the error message string to include if parsing fails. Config can take three different arguments, one argument per command. These are

errmsg="error_string". Sets the error message to use if there is an error in parsing the parsable commands.

timefmt="format". Sets the format for printing dates. This format is specified as per the C strftime library (strftime is commonly found on Unix computers).

sizefmt="bytes","abbrev". Sets the format for the specification of file sizes. The value bytes prints file sizes in bytes, while abbrev uses kilobytes or megabytes as abbreviated forms, where applicable.

Some examples of config format specifications are:

<!--#config sizefmt="abbrev" -->

<!--#config timefmt="%m%d%y" -->

<!--#config errmsg="Unable to parse scripts" -->

Back to top

E.1.7 Printenv: Print All Environment Variables

This directive, added with the Apache 1.2 server, prints out all the environment variable names and their values, one per line, using the format

VARIABLE_NAME=value. This is useful when diagnosing problems with SSI documents.

Back to top

E.1.8 Set: Set Value for a Variable

This directive, added with the Apache 1.2 server, lets you create a variable and assign it a string value. The syntax is:

<!--#set var="var_name" value="var_value" -->

where the meanings are obvious. These variables can be referenced by name from within echo statements. For example:

<!--#set var="stuff" value="yabba dabba do" -->

Value for "stuff" is: <!--#echo var="stuff" -->

These values (and any defined environment variables) can also be referenced within config, exec, flastmod, fsize, include, and set directives, but only by prepending a dollar sign in front of the variable name. For example, the directive

<!--#set var="test" value="This is $stuff$DATE_GMT" -->

sets the variable test to be equal to the string "This is" followed by the value of the variable stuff, followed by the value of the DATE_GMT environment variable. If the variable name appears inside a string, then the start and end of the variable name can be delimited by curly brackets, as in:

<!--#set var="test" value="This is ${DATE_GMT}easy " -->

Back to top

E.2 Conditional SSI Blocks

Apache 1.2 and later versions support conditional SSI directives, where only the markup inside "true" blocks is included when the document is served out. The blocks work like regular if and else if statements, as in the following simple example:

<!--#if expr="test-expression-1" -->

First block of markup

<!--#if expr="test-expression-2" -->

Second block of markup

<!--#else -->

Third block of markup

<!--#endif -->

If test-expression-1 is true, then the first block of markup is included in the document, while the second and third blocks are discarded. On the other hand, if test-expression-1 is false and test-expression-2 is true, then the second block of markup is included in the document, while the first and third blocks are discarded. Finally, if both test-expression-1 and test-expression-2 are false, then the third block of markup is included, and the first and second are discarded.

The test expressions test the value of strings (there are no numeric operations or comparisons). For details, please see the Apache server document listed in the references.

Back to top

E.3 References

Back to top

The XHTML Web Development Sourcebook © 1995-2000 by Ian S. Graham