Server Side Includes

1. Client-Server Basics
2. Server-Side-Include Definition
3. Server-Side-Include (SSI) Format
4. Commands
5. Command Tags
6. Environment Variables
7. References

Client-Server Basics

The program requesting the document (Netscape, Mosaic, Lynx, etc) is called the client.

The program that takes the request and returns the page is called the server.

Most servers are not just limited to grabbing a home page from the disk and sending it back. They can search through the page requested by the client for special commands they recognize. This is called "parsing" the document.

In order for the server to do this, it must be told to do so. By default, most servers do not parse a document before sending it.

FortNet Instructions:

Use the extension "shtml" rather than "html" for files you wish parsed.
(Although all html files are currently parsed, this may not always be the case.)


Top

Server-Side-Include Definition

A Server-Side-Include is simply some
• specially-formatted line of code ( a directive ) in your html document which causes
• the server to take some action before returning the document to the client.



Server-Side-Include (SSI) Format

<!--#command tag1="value1" tag2="value2" -->

Although this looks a lot like a comment, the results are quite different.

All directives to the server are formatted as SGML comments within the document.

Each command takes different arguments, most only accept one tag at a time.
(Make sure there is no space before the # sign)

The results of the directive are inserted into the html document at the point of your include statement.


Top

Commands

include

echo

exec

config

flastmod

fsize

Command Tags

include

include will insert the text of a document into the parsed document. Any included file is subject to the usual access control. This is the directive used on many of the current FortNet pages for the trailer.

This command accepts two tags:

• virtual gives a virtual path to a document on the server. You must access a normal file this way, you cannot access a CGI script in this fashion. You can, however, access another parsed document.

• file gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. As above, you can send other parsed documents, but you cannot send CGI scripts.

Example: <!--#include virtual="/FortNet/includes/fortnet_owned.html"-->
Includes the code to produce the trailer on FortNet pages

Example: <!--#include file="sample.txt"-->
Produces:
This is some text from the file sample.txt. Included text may be html code as well.

echo

prints the value of one of the include environment 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 variable link above displays a page with each environment variable and the results of entering the variable in an echo directive.

Example: <!--#echo var="LAST_MODIFIED"-->
Produces: Monday, 07-Oct-2002 10:53:22 MDT

exec

executes a given shell command or CGI script in your local directory. Valid tags are:
• cmd will execute the given string using /bin/sh. All of the SSI Environment Variables are defined, and can be used in the command.

• cgi 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.

  FortNet Instructions: the referenced cgi file must have the extension "cgi"
  
  Example: <!--#exec cgi="hello.cgi"-->
  Would execute the script "hello.cgi"

  #!/usr/bin/perl
  print "Content-type: text/html\n\n";
  print "Hello";
  

  Fortnet Response: Hello

config

The config directive controls various aspects of the file parsing. There are three valid tags:
• errmsg controls what message is sent back to the client if an error includes while parsing the document. When an error occurs, it is logged in the server's error log.

• timefmt gives the server a new format to use when providing dates. This is a string compatible with the strftime library call under most versions of UNIX.

• sizefmt determines the formatting to be used when displaying the size of a file. Valid choices are bytes, for a formatted byte count (formatted as 1,234,567), or abbrev for an abbreviated version displaying the number of kilobytes or megabytes the file occupies.

fsize

prints the size of the specified file. Valid tags are the same as with the include command. The resulting format of this command is subject to the sizefmt parameter to the config command.


Example: <!--#fsize file="echovar.shtml"-->

Fortnet Response: 5.6K

flastmod

prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to config. Valid tags are the same as with the include command.


Example: <!--#flastmod file="echovar.shtml"-->

Fortnet Response: Monday, 07-Oct-2002 10:58:33 MDT

Environment Variables

References

• NCSA Tutorial: Server Side Includes
  
• NCSA - CGI Environment Variables
  
• NCSA - CGI Script Output

Top