I sat around and goofed off, since we didn't have an assignment last week! I spent lots of time in the garden too.

Ordinarily, when you ask the HTTP daemon for a static file (a normal HTML document, image, or the like) the daemon simply retrieves the file, sends the appropriate HTTP headers to your browser, and then dumps the content of the file to your browser. The daemon doesn't bother to look inside the file or parse its contents.

You can, however, set up the server (using the httpd.conf file, in the case of apache) so that the daemon will parse the files follow specific directives contained inside, and include the output of those directives in place of the directives themselves in the final output page. These directives are known as server side includes - because the server goes off and does something, and then includes the results. The end result is much like having only part of the page be a CGI program.

Note that you can't print these server side include directives in CGI output (or they won't work, anyway). The daemon won't parse your file TWICE!

In order for the server daemon to know which files to parse, you need to give them a special suffix. This suffix may be anything you like, but you must set it up in the server configuration files. On the clam server, the suffix has been set to .shtml (this is actually a popular choice - another popular one is .phtml). To set this up in apache, you'll need to edit the httpd.conf file to:

• add an AddType directive

  This tells the server what Content-type: header to use with the .shtml files.

• add an AddHandler directive

  This tells the server that how it should handle these special .shtml files - namely by parsing them.

	# To use server-parsed HTML files
	AddType text/html .shtml
	AddHandler server-parsed .shtml

	DirectoryIndex index.html index.shtml index.cgi

Of course, if you like, you could set the special suffix to .html. This would result in all files ending in .html being parsed. While there is nothing technically wrong with this, it will lead to a lot of unnecessary server load, as the vast majority of files ending in .html probably do not actually contain any server side includes.

The files containing server side includes, like any other content files that will be served over the web, must reside underneath the document root. In addition, the directory that they reside in must be explicitly set up to allow server side includes, in much the same manner as the directories containing CGI scripts must be set up to allow CGI script execution. This makes sense when you consider that both server side includes and CGI scripts result in code being run on the server in most cases.

The relevant lines from CLAM's configuration are:

	UserDir public_html

	#
	# Control access to UserDir directories.  The following is an example
	# for a site where these directories are restricted to read-only.
	#
	<Directory "/home/*/public_html">
    	    AllowOverride All
    	    Options MultiViews ExecCGI Indexes FollowSymLinks Includes
    	    CheckSpelling on
    	    Order allow,deny
    	    Allow from all
	</Directory>

In most cases? Yes. You can restrict what directives are allowed in your server side include statements, so that you will only allow directives that include static text, and disable any directives that result in code execution. If we were to do this, the relevant lines from CLAM above would become:

        UserDir public_html

        #
        # Control access to UserDir directories.  The following is an example
        # for a site where these directories are restricted to read-only.
        #
        <Directory "/home/*/public_html">
            AllowOverride All
            Options MultiViews ExecCGI Indexes FollowSymLinks IncludesNOEXEC
            CheckSpelling on
            Order allow,deny
            Allow from all
        </Directory>

One of the most popular uses of server side includes is to have them execute a CGI program and insert its output. If you do this, the actual CGI program must reside in a directory that is configured to allow CGI execution. In our case, we can put the file with the server side include and the CGI script the include directives call right in our public_html directories and it will all work fine.

Presuming that you are allowing the server side includes to execute code (using the Includes option above, rather than the IncludesNOEXEC option), then server side includes present the same risks as CGI files do. Server side include directives, like CGI programs (and remember, one of the most popular server side include directives is one which executes a perl script and prints its output) execute commands on your server as the HTTP daemon user. You should be careful about who you let use server side includes on your server!

Server side includes look like SGML comments (or HTML comments, which are a special case of SGML comments). This is so that if you move a page intended for server parsing (foo.shtml, for instance) to a server which doesn't support server side includes, the the server side include (which is now not being parsed and replaced) will not mess up the appearance of the page. Inside the "comment begin and end" (<!-- and -->) there is the type of server side include, or element, and one or more attribute=value pairs. The format of a server side include is thus

	<!--#element attribute=value attribute=value -->

For a complete list, you should go to the references listed below. However, here are some of the most common:

• echo

  Used to print one of the include variables available to server side includes. If the variable has no value, it will print as "(none)."

  Attributes are:

  • var
    The name of the variable you want to print. These variables may be printed directly with echo or they may be accessed by a CGI program called with exec. In the latter case, the CGI program will find the variables in the %ENV hash.
    Available variables are:
    • DOCUMENT_NAME: Name of the current file (with the SSI in it).
    • DOCUMENT_URI: The virtual path to this document (starting with a slash for the document root)
    • DATE_LOCAL: The current time, in the local time zone.
    • DATE_GMT: The current time, in GMT.
    • LAST_MODIFIED: When the current file was last modified.

    Example: This file was last modified on <!--#echo var="LAST_MODIFIED"-->

• include

  Used to include a static file (perhaps containing a boilerplate copyright notice or menu) inside the current document.
  Attributes are:

  • file
    The name of a file to include, relative to the current document. It cannot contain ../, nor can it be an absolute path. Generally you'll want to use the virtual attribute instead.
    Example: <!--#include file="legal_notice.html"-->

  • virtual
    The encoded URL path to a file to include, on your site, relative to the document root (represented by a slash "/"). If the path does not begin with a slash, it is assumed to be relative to the current document.
    Note: If the directory containing the parsed file (the .shtml file) has IncludesNOEXEC set on it (rather than simply Includes) then you can't link to a CGI script. Otherwise, you can link to a CGI script, and it will execute as usual, complete with any attached query string.
    Example: <!--#include file="legal_notice.html"-->

• exec

  Used to execute a given shell command (with /bin/sh) or CGI script, and insert the results into the current document. The IncludesNOEXEC command disables this completely.
  Attributes are:

  • cgi
    The encoded URL relative path to the CGI script. If the path does not begin with a slash (indicating the document root) it is assumed to be relative to the current file. The directory containing the script must be set up to allow CGI execution. You cannot append any query string or path info to the end of the URL for the CGI script - instead, the CGI script will be passed any query string or path info data appended to the URL for the current page containing the server side include. Note: If the page should return a Location: header rather than content, the server side include will be replaced with a link to the URL given in the returned Location: header.

  • cmd
    A string to be sent to /bin/sh and executed. This can of course be a call to execute a garden variety perl script complete with command line arguments. The various include variables (explained above) will be available to such scripts.

    This can of course include strings like "rm -f *" too, so you should be careful! If Options NoExec is set, or the directory is configured with IncludeNOEXEC (as opposed to plain Includes), this command is disabled.
    Example: <!--#exec cmd="finger"-->

• config

  This command controls some behaviors of the SSI, such as the formatting of times and dates and the error message to be printed when a file fails to parse.

  Attributes are:

  • errmsg
    The error message to print to the screen in place of the SSI when an error occurs during parsing.
    Example: <!--#config errmsg="Something barfed!" -->

  • sizefmt
    The format to use when displaying the size of a file. Setting it to bytes displays sizes in bytes, whereas setting it to abbrev will use the KB or MB abbreviations as appropriate.

  • timefmt
    A format string used by the strftime() library routine when printing dates (such as the last modified date).

Please try to do the following tasks:

• Make a mainly static HTML page that uses a server side include to maintain the "last five people visited" list at the bottom of the page.
  (Hint: You'll probably just want to have the server call the same perl script you wrote to do this as a CGI in week 9.)

• Adjust the script and the above page so that the same script can be used to maintain "last five lists" for multiple pages (i.e., it will know what unique lockfile and last five list to write to).

• Make the above page also include the last modified date.