What is SSI?

An SSI — server side include — is a piece of code that is embedded in an HTML page and interpreted by the the server before the page is sent to the client's browser. SSIs allow the inclusion of information in HTML files like a file's date of last modification, another HTML file, a counter, or the output of any CGI script.

Server Side Includes are server intensive. Because all files need to be parsed by the server, having all Web pages as SSI would cut performance.

Any file that has the extension .shtml will automatically be parsed by the server. Use index.shtml instead of index.html as the default directory file.

SSI COMMANDS

A server side include command is contained within a comment tag:
<!--#command argument="value" -->

Syntax must be correct, or the include will not work.

The INCLUDE Command

To include the contents of another file in a shtml file, use the include command.

The include command has two possible arguments: virtual and file.

"Virtual" is used when the path to the document is given relative to the document root (usually the www directory.)

"File" is used when the path to the document is given relative to the shtml file itself. However, use "file" to go up a directory ( "../page.html" won't work.)

For example, to include the file named "file.html" which resides in the same subdirectory as this shtml file.

Employing "virtual," use:

<!--#include virtual="/mirror/ssi/file.html" -->

This would return: This is from file.html

Employing "file," use:

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

This would return: This is from file.html

The ECHO Command

The echo command includes, or "echoes," the contents of an environment variable. Here are some examples showing the SSI tag and the results :

<!--#echo var="DOCUMENT_NAME" -->

This document is named: products.htm

<!--#echo var="DATE_LOCAL" -->

This document was last accessed: Tuesday, 30-Jun-07 12:025:17 MDT

<!--#echo var="DATE_GMT" -->

This is the same as the above, but in Greenwich Mean Time: Tuesday, 30-Jun-07 18:025:17 MST

<!--#echo var="DOCUMENT_URI" -->

The URI (the path form document root) of this document is: /catalog/products.htm

<!--#echo var="LAST_MODIFIED" -->

This document was last modified: Friday, 15-Mar-07 12:22:21 MST

<!--#echo var="HTTP_REFERER" -->

The user came by way of a link from: http://www.surfinsafari.com

<!--#echo var="HTTP_USER_AGENT" -->

The browser used to access this document was: Mozilla/4.0b3 [en] (WinNT; I)

Echo Command Values

SERVER_SOFTWARE server application
SERVER_NAME hostname of the server
SERVER_PROTOCOL server protocol
SERVER_PORT listening TCP port
REQUEST_METHOD HTTP method used by the client
REMOTE_HOST domain name of the client, note DNS option must be set
REMOTE_ADDR IP address of the client
AUTH_TYPE method that the client used for authorization
REMOTE_USER username entered by the remote client
CONTENT_TYPE MIME type of the content posted by the client
CONTENT_LENGTH size of the data posted by the client
DOCUMENT_NAME name of the document requested
DOCUMENT_URI URL of the document requested
DATE_LOCAL current date, format specified by the config command
DATE_GMT The current GMT, format specified by the config command
LAST_MODIFIED document modified date, format specified by the config command
PAGE_COUNT number of hits on the current document since server came on-line
TOTAL_HITS number of documents server has served since coming on-line
REFERRER The URL of the document the viewer came from

The EXEC Command

The exec command executes a Unix command or CGI script. It always takes the argument "cmd".

<!--#exec cmd="/usr/bin/date" --> This executes the Unix date command.

<!--#exec cgi="./greetingsplanetearth.cgi" --> This executes the CGI script, greetingsplanetearth.cgi.

The second line uses the statement exec cgi opposed to the previous line which used exec cmd. The second line is calling a CGI script that was written, the first a UNIX command. Here is the perl code contained in greetingsplanetearth.cgi:

 #!/bin/perl
print "Greetings Planet Earth";
exit;

All the environment variables passed to the CGI script are the same as those for the shtml file itself.

A query string using a question mark will not pass (?), as in:

 <!--#exec cmd="greetingsplanetearth.cgi?mars" -->

The query string passed to the CGI script will be the same as the query string passed to the shtml file itself. If this file were referenced as "ssi.shtml?mars", than the word "mars" would also be passed to the "greetingsplanetearth.cgi" script above.

The FSIZE Command

The fsize command returns the size of the specified file in bytes. It uses the argument "virtual," which is the path to the file is given relative to the document root.

To find the size of image.gif, use:

 <!--#fsize virtual="graphics/image.gif" -->

This would then return the file size.

 This is used to give visitors to a Web site an idea of the size of the files they are downloading.

 The FLASTMOD Command

The flastmod command returns the date the specified file was last modified.

The flastmod command uses the argument "virtual," in which the path to the file is given relative to the document.

To find the last modified date of a file, use:

 <!--#flastmod virtual="filename.txt" -->

This would return: Friday, 06-Apr-07 12:37:07 MDT

The CONFIG Command

The config command controls how the results of other SSI are displayed. There are three possible arguments: timefmt, sizefmt and errmesg.

To set the format for the date to dd/mm/yy, use:

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

The date will be displayed as: 04/06/07

The field descriptors used by this SSI tag are the same as those used by the Unix date command.

Dates displayed above this config command use the normal date format. Dates displayed below it use the new format.

To set the format for how file sizes are displayed, use:

 <!--#config sizefmt="abbrev" -->
Displays the size abbreviated as "1k". (Without size format.)

or:

 <!--#config sizefmt="bytes" -->
Displays the size in total bytes.

To set error message returned when an SSI tag fails, use:

 <!--#config errmsg="Error" -->

A failed SSI tag will return: Error

Reasons for Using SSI

SSI is often used to include something in an HTML page. Contents of one HTML page may be inserted into another page. A practical usage for this is to include an e-mail address at the bottom of each HTML page. If done as an include, then when the e-mail address changes, only one file will have to be updated it on one page and not the entire Web site.

SSI may also be used to to call CGI scripts. Many counters, clocks, and other scripts may be called in this manner. The to command used will be provided in the script's documentation.

SSI Resources

SSI Tutorials

SSI Tutorials & Resources

Advanced SSI Techniques

Beginners' SSI Tutorial

Add to Favourites

Print this Article