Back in January, I got email from Delia, Luis & Ruben at University of Baja California in Ensenada, Mexico. They wanted to include some boilerplate HTML in every page of their document tree without requiring any action on the part of the user browsing the page. They thought that a little C program might do the trick and wanted my input on whether that strategy made sense (and, if so, on how to implement it).
Assuming that their Web server supports the Common Gateway Interface (CGI), a little program in C might well do the trick for them. However, if their Web server supports Server Side Includes (SSI) and their Web administrator has enabled SSI, there's an easier way to flay the same feline.
Neither condition is necessarily a foregone conclusion. Most commercial Web servers support SSI, but not all freeware servers do. And, as Randy Hoefer (firstname.lastname@example.org) points out in his "What are Server Side Includes and Can I use them?" page at http://vbn.com/~randy/ssis.shtml, most Web administrators hate them. From an administrator standpoint, the problems with SSI are that it can enable strangers to execute programs on a Web server outside of the administrator-controlled CGI-BIN directory and that HTML pages with a lot of includes can eat up a significant amount of processor time (since each include spawns a separate process).
So, just what is an SSI and how does it work? And, with these potential drawbacks, what advantages are there to enabling SSI?
SSI is an HTML capability which, if implemented, permits individual users to include CGI-like executables in their own pages without needing to have the administrator put a copy of each executable in the master CGI-BIN directory. (Note that the administrator can turn off this capability by setting the NOEXEC option.) It also allows one HTML document to transparently include the contents of a second document and to display information about the current document or other files, or to display the values of certain environment variables, all without requiring the use of CGI.
In order to enable SSI, the Web server must have have either an
Options IncludesNoExecline in the master access configuration file and/or the access configuration files for specific directories or directory trees. The same file must also have an
AddType text/x-server-parsed-html (filetype(s))where the default value for (filetype) is "shtml" (without the quotes). The (filetype) can be set to "html", but, by convention, HTML documents which feature SSI take the filename extension .shtml in order to reduce the burden on the server (the server attempts to parse only documents with the filename extension defined by the AddType text/x-server-parsed-html entry). Naturally, this means that any document which makes use of SSI must have the filename extension .shtml in order for the includes to actually function.
SSI enables a Web server to parse HTML documents for included directives. SSI directives are issued in the form of HTML comments, with a # character indicating that the comment is an SSI directive, as follows:
The NCSA Web server was the first Web server to support SSI. It supports six SSI directives: config, echo, exec, flastmod, fsize and include. Other servers may support additional directives, but any server which supports SSI will support these six.
The config directive can define the default error message and control the format in which other directives will display file sizes or date and time via its "errmsg", "sizefmt" and "timefmt" parameters, respectively. "Errmsg" sets the default error message equal to a double-quote-delimited string. "Sizefmt" may equal "bytes" (which displays exact file sizes in bytes) or "abbrev" (which rounds the display to the nearest kilobyte or megabyte). "Timefmt" defines the date and time display according to the conventions of the strftime() Unix call, using 11 possible variables in any combination, separated by any desired delimiters.
The echo directive takes the parameter "var", which is used to display the contents of any of the SSI or CGI environmental variables, including DATE_GMT, DATE_LOCAL, DOCUMENT_NAME, DOCUMENT_URI, LAST_MODIFIED and QUERY_STRING_UNESCAPED.
The exec directive takes one of two parameters: "cmd" or "cgi". "Cmd" can be set equal to a command string which will be executed by the default local shell. It can be used to run any program or script to which the Web server has execute rights (although any program specified should use standard output) and to pass any legal arguments to the program. "Cgi", on the other hand, defines a virtual path to an actual CGI script and invokes it.
The flastmod and fsize directives both take a single parameter, "file". Flastmod returns the last modification date and fsize the length of the file specified by the value of "file".
The include directive takes either a "virtual" or "file" parameter. The "virtual" parameter specifies a path to a file from the Web server's document root, while the "file" parameter specifies a file path from the directory in which the current document resides. In either case, the contents of the file that the chosen parameter defines will be included as part of the current document, with the insertion point at the position occupied by the include directive. (This is what I recommended Delia, Luis & Ruben consider using). The included file can, itself, have include directives embedded in it, as can any files it includes, although the burden that these recursive inclusions place on the Web server can be non-trivial.
You can get somewhat more information about SSI at the "NCSA HTTPd Tutorial: Server Side Includes (SSI)" page (http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html) and at Matt Kruse's (email@example.com) "Server-Side-Includes Tutorial" (http://web.sau.edu/~mkruse/www/info/ssi.html), and at Randy Hoefer's pages. Lincoln Stein's invaluable book "How to Set Up and Maintain a World Wide Web Site (Addison-Wesley, 1995, ISBN 0-201-63389-2) also includes information on how to configure the NCSA server for SSI as well as on using SSI. You may also find useful advice in the Usenet newsgroups comp.infosystems.www.authoring.cgi, comp.infosystems.www.authoring.html and comp.infosystems.www.authoring.misc. And if your Web administrator won't enable SSI, you can always try bribery.
(Copyright© 1996 by Thom Stark--all rights reserved)