Server Side Includes (SSI's)

• SSI Introduction
• SSI Format
• Example SSI In-Line Commands
• Example SSI Web Page Access Counter

SSI's (Server Side Includes) allows users to create documents which provide basic and complex information to clients on the fly. Such information can include the current date, the file's last modification date, and the size or last modification of other files. In its more advanced usage, it can provide a powerful interface to CGI and /bin/sh programs. These commands are placed directly in the HTML document, and don't necessairly require any additional files or programs.

A useful source of information about SSI's is from NCSA:

NCSA HTTPD Server Side Includes (SSI)

WARNING: Care needs to be taken when editting these files. Using built in browser editors, such as Netscape or Internet Explorer, will distroy the SSI document. These browser/editors download the displayed/served document. The contents of this document may have been dynamically generated based on the SSI commands. The SSI commands themselves though are NOT included if the final document sent to the client. If the version of the page the client receives, is published back to the server, the SSI commands will be lost, and the document will become a static document.

All directives to the server are formatted as SGML comments within the document. 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" -->

Using the following commands the following tasks can be performed:

1. config: this directive controls various aspects of the file parsing. The two valid tags are timefmt and sizefmt. Examples will be shown in the echo and fsize sections below.

2. include: prints the value of one of the include variables. Any dates are printed subject to the currently configured timefmt. The only valid tag to this command is var, whose value is the name of the variable you wish to echo.
   • The following include statment has used to include the five button, purple banner at the top of this page:

     <!--#include file="csm_locs.inc" -->

   Note: the include file must reside in the same directory as the file being served. If the same file is to be used for multiple pages in multiple directories, make a master file, and place it in each directory using symbolic links.

3. echo: prints the value of one of the include variables. Any dates are printed subject to the currently configured timefmt. The only valid tag to this command is var, whose value is the name of the variable you wish to echo.
   • Current document filename:

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

     ssi.shtml

   • Current document virtual path and filename:

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

     /examples/ssi.shtml

   • Local date and time:

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

     Friday, 10-Oct-2008 15:05:14 MDT

   • GMT date and time:

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

     Friday, 10-Oct-2008 21:05:14 GMT

   • Date and time this file was last modified:

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

     Friday, 13-Mar-1998 14:32:09 MST

     02:32:09 PM 03/13/98

   • Using the config command and the timefmt parameter, the user can control the date and time output format (see man pages on strftime for details):

     <!--#config timefmt="Time = %r; Date = %D" -->

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

     Time = 02:32:09 PM; Date = 03/13/98

4. fsize: prints the size of the specified file. The resulting format of this command is subject to the sizefmt parameter to the config command.
   • Show ssi.shtml file size with default format:

     <!--#fsize file="ssi.shtml" -->

     9k

   • Show ssi.shtml file size with byte format:

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

     <!--#fsize file="ssi.shtml" --> bytes

     8,794 bytes

5. flastmod: prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to the config command.
   • Show the last modified time of the server homepage /index.shtml. Note that we are still using the time format, timefmt, specified above.

     <!--#flastmod file="/index.shtml" -->

     [an error occurred while processing this directive]

6. exec: executes a given shell command or CGI script. It must be activated to be used.
   • The cmd tag will execute the given string using /bin/sh. For example, to list the current directory:

     <pre><!--#exec cmd="ls -l" --></pre>

     total 368
     -rw-r--r--   1 1410     goldmine      11791 Feb 25 1998  TOC.pdf
     -rwxr-xr-x   1 1410     goldmine       5307 Feb 12 1998  cgi.gif
     -rw-r--r--   1 1410     199            3709 Mar 13 1998  cgi.shtml
     drwxr-sr-x   3 1410     goldmine        512 Apr 19 2004  count
     drwxr-sr-x   3 1410     199             512 Apr 19 2004  count.bak
     -rw-r--r--   1 1410     goldmine     112640 Apr 19 2004  count.tar
     lrwxrwxrwx   1 1410     goldmine         19 Sep 14 2001  csm_info.inc -> ../inc/csm_info.inc
     lrwxrwxrwx   1 1410     goldmine         19 Sep 14 2001  csm_locs.inc -> ../inc/csm_locs.inc
     lrwxrwxrwx   1 1410     goldmine         19 Sep 14 2001  csm_tail.inc -> ../inc/csm_tail.inc
     -rwxr-xr-x   1 1410     goldmine       4784 Feb 12 1998  examples.gif
     drwxr-sr-x   2 1410     199             512 Mar 17 1998  form
     -rw-r--r--   1 1410     199            1514 Feb 25 1998  fup.html
     -rw-r--r--   1 1410     goldmine       2231 Mar 13 1998  index.shtml
     -rwxr-xr-x   1 1410     goldmine       5085 Feb 12 1998  ssi.gif
     -rw-r--r--   1 1410     goldmine       8794 Mar 13 1998  ssi.shtml
     

   Note: <pre> and </pre> tags were placed around the SSI command, otherwise the results of the ls -asl command would have been printed on a single line.

   • The cgi tag will execute the given virtual path to a CGI script and include its output. The server does not perform error checking to make sure your script didn't output horrible things like a GIF, so be careful. It will, however, interpret any URL Location: header and translate it into an HTML anchor.