Appendix C

Server-Side Includes

CONTENTS

Server-side includes are special tags embedded in an HTML document that are parsed by the server before being sent to the Web browser. The several different implementations of server-side includes range from the simple to the vastly complex. This appendix focuses on NCSA's and Apache's implementations of server-side includes. Although neither of these servers has the most advanced or feature-rich implementation, combined they are the most popular servers used on the World Wide Web.

Enabling Server-Side Includes

By default, both the NCSA and Apache servers disable server-side includes. To enable them, you need to take the following two steps:

  1. Add the following line to the conf/srm.conf file:
    Add-Type text/x-server-parsed-html .shtml
    The server then preparses any file with the extension .shtml for server-side includes. If you want the server to preparse all HTML files, add this line instead:
    Add-Type text/x-server-parsed-html .html
  2. Add the Includes option to the Options line in the conf/access.conf file. It should look something like this:
    Options Indexes Includes FollowSymLinks
    Note that Includes enables you to include output of both CGI programs and system programs. The latter is undesirable; unfortunately, in the NCSA server, it is impossible to have one without the other.

You can enable server-side includes and disable the ability to run programs-either executables or CGI-by using the option IncludesNOEXEC instead of Includes.

Format and Commands

The basic format for the server-side include is as follows:

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

Possible commands include the following:

config

You use config to configure the behavior of certain server-side includes. You can configure three variables:

The error message errmsg should appear if you have a server-side includes error. Consider this example:

<!--#config errmsg="Server-side include error. Please contact the webmaster">

Here, the error message Server-side include error. Please contact the web administrator appears within your HTML document if you have a server-side include error.

If you are using the server-side include fsize to echo the size of a file, you can configure it to display the value in bytes, as follows:

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

Or you can configure it in abbreviated form (such as Mb for megabytes or Kb for kilobytes), as follows:

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

Finally, you can configure the format of a server-side include time string displayed when you display the last modified date of a file (flastmod). Also, timefmt accepts the same string format as the C function strftime() does. For example, if you set the following:

<!--#config timefmt="%A, %B %d, %Y" -->

dates are printed in the following format:

Sunday, March 3, 1996

echo

Using echo, you can display the special server-side include environment variables listed in Table C.1. For example, to embed the current date in an HTML document, use the following:

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

Table C.1. Server-side include environment variables.

Environment Variable
Purpose
DOCUMENT_NAME The name of the document the server returns.
DOCUMENT_URI The URI of the document.
QUERY_STRING_UNESCAPED The unescaped QUERY_STRING, if one is included.
DATE_LOCAL The local date.
DATE_GMT The date in GMT.
LAST_MODIFIED The date the document was last modified.

include

Using include, you can include either another file or, in the case of the Apache server, the output of a CGI program. include takes one of two attributes: file or virtual. file accepts a filename relative to the current path, where ../ is not a valid path, and virtual accepts a virtual path and filename relative to the document root.

Suppose, for example, that you have three HTML files: hello.shtml, there.html, and you.html. You want to include there.html and you.html in hello.shtml. The files are located in the following virtual directory tree (relative to document root):

/you.html
/greetings/hello.shtml
/greetings/there.html

The file hello.html might look like the following:

<!--#include file="there.html" -->
<!--#include virtual="/you.html" -->

To access you.html, you have to use virtual rather than file because you have no way of expressing the location of you.html relative to the current directory, greetings. You also can use the following:

<!--#include virtual="/greetings/there.html" -->
<!--#include virtual="/you.html" -->

or

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

Remember that although the Apache server does let you specify a CGI program, the NCSA server does not. This is the main difference between the Apache and NCSA implementation of server-side includes.

exec

You can use exec to include the output of either a CGI or a system program. exec takes one of two parameters: cgi or cmd. If you are including the output of a CGI program, you use cgi. The server-side include passes the values of QUERY_STRING and PATH_INFO, but you cannot include these values within the include yourself. Suppose, for example, you have the document at <URL:http://myserver.org/inde x.shtml>. The following include fails:

<!--#exec cgi="/cgi-bin/search?hello+there" -->

To get the desired effect, use the include

<!--#exec cgi="/cgi-bin/search" -->

and access the URL as follows:

http://myserver.org/index.shtml?hello+there

If you are executing a system command, use cmd. Make sure that you include the full pathname of the command. To include the output of the program /bin/date, for example, use the following:

<!--#exec cmd="/bin/date" -->

Note that the ability to include system commands is not normally desirable, especially if you have a CGI program that enables random Web users to insert HTML into your documents. Suppose, for example, you have a guestbook CGI that does not properly filter HTML tags. Suppose as well that your servers have server-side includes enabled and that all *.html files are parsed. A malicious user could include the following in his or her guestbook comments:

<!--#exec cmd="/bin/rm -rf /" -->

This use is clearly undesirable. Make sure that you either disable exec if you don't need it (using IncludesNOEXEC), or if you absolutely do need it, make sure that you do not allow random users to insert random HTML onto documents on your server.

fsize

Use fsize to display the file size of a file specified using either file or virtual. Here, file and virtual mean the same thing they do with include or flastmod. To display the file size of the file hello.html located in the present directory, for example, you use the following:

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

You can configure the include to either display the value in bytes or in abbreviated form using config (see the description of config earlier in this appendix).

flastmod

Use flastmod to display the last date a file-specified using either file or virtual-was modified. To display the last modification date of the file index.html located in the document root, for example, you can use the following:

<!--#flastmod virtual="/index.html" -->

You can configure the format of the date using the config include (see the description of config earlier in this appendix).