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.
By default, both the NCSA and Apache servers disable server-side includes. To enable them, you need to take the following two steps:
You can enable server-side includes and disable the ability to run programseither executables or CGIby using the option IncludesNOEXEC instead of Includes.
The basic format for the server-side include is as follows:
<!--#command tag1="value1" tag2="value2" -->
Possible commands include the following:
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
Using echo, you can display 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" -->
Environment Variable Purpose
The name of the document the server returns.
The URI of the document.
The unescaped QUERY_STRING, if one is included.
The local date.
The date in GMT.
The date the document was last modified.
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" -->
<!--#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.
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:
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.
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).
Use flastmod to display the last date a filespecified using either file or virtualwas 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).