Server-Side Includes

Server-side includes are best described as a preprocessing language for HTML. The “processing” takes place on the server side. As such, visitors to your site never need to know that you use server-side includes, and thus they require no special client software. The format of these includes looks something like the following:

<!--#directive attribute ="value" -->

Sometimes a given “directive” can have more than one attribute at the same time. The funky syntax is due to the desire to hide this functionality within an SGML comment—that way, your regular HTML validation tools will work without having to learn new tags or anything. The syntax is important; leaving off the final --, for example, will result in errors.

#include

The #include directive is probably the most commonly used. You use it to insert another HTML file into the HTML document. The allowed attributes for #include are virtual and file. The functionality of the file attribute is a subset of that provided by the virtual attribute, and it exists mostly for backward compatibility, so its use isn’t recommended.

The virtual attribute tells the server to treat the value of the attribute as a request for a relative link—meaning that you can use ../ to locate objects above the directory and that other transformations, such as Alias, will apply. Here’s an example of such:

<!--#include virtual="quote.txt" -->

<!--#include virtual="/toolbar/footer.html" -->

<!--#include virtual="../footer.html" -->

#exec

The #exec directive is used to run a script on the server side and insert its output into the SSI (server-side includes) document being processed. There are two choices: executing a CGI script by using the cgi attribute or executing a shell command by using the cmd attribute. For example,

<!--#exec cgi="counter.cgi" -->

takes the output of the CGI program counter.cgi and inserts it into the document.

---

NOTE:  The CGI output still has to include the "text/html" content-type header; otherwise, an error will occur.

---

Likewise,

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

takes the output of a call to ls -l in the document’s directory and inserts it into the output page as a replacement for the #exec command. Like the file attribute for the #include directive, this type of #exec command is mostly for backward compatibility, because it’s something of a security hole in an untrusted environment.

---

NOTE:  There are definitely security concerns with allowing users access to CGI functionality and even greater concerns with #exec cmd, such as

   cmd="cat /etc/passwd"

If a site administrator wants to let users use server-side includes but not use the #exec directive, he or she can set IncludesNOEXEC as an option for the directory in the access configurations.

---

#echo

The #echo directive has one attribute—var —whose value is any CGI environment variable as well as a small list of other variables, as shown in Table 36.3.

For example, the command

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

inserts something along the lines of Wednesday, 05-Mar-97 10:44:54 GMT into the document.

#fsize, #flastmod

The #fsize and #flastmod directives print out the size and the last-modified date, respectively, of any object given by the URI listed in the file or virtual attribute, as in the #include directive. For example, this command

<!--#fsize file="index.html" -->

returns the size of the index.html file in that directory.

#config

You can modify the rendering of certain SSI directives by using the #config directive. The sizefmt attribute controls the rendering of the #fsize directive with values of bytes or abbrev. The exact number of bytes is printed when bytes is given, whereas an abbreviated version of the size (in KB for kilobytes or MB for megabytes) is given when abbrev (the default) is set. For example, a snippet of SSI HTML like

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

The index.html file is <!--#fsize virtual="index.html" --> bytes

returns The index.html file is 4,522 bytes. Meanwhile,

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

returns The index.html file is 4K bytes.

The timefmt directive controls the rendering of the date in the DATE_LOCAL, DATE_GMT, and LAST_MODIFIED values for the #echo directive. It uses the same format as the strftime call. (In fact, the server does call strftime, a system call that formats the time in a string of specified length.) The string format consists of variables that begin with %. For example, %H is the hour of the day, in 24-hour format. For directions on how to construct a strftime -format date string, consult strftime ’s man page for a list of variables.

An example might be

<!--#config timefmt="%Y/%m/%d-%H:%M:%S" -->

with the resulting date string for Jan. 2, 1997, at 12:30 in the afternoon as

1997/01/02-12:30:00

Finally, the last attribute the #config directive can take is errmsg, which is simply the error to print out if there are any problems parsing the document. For example, the right default is

<!--#config errmsg="An error occurred while processing this directive" -->