All Categories :
CGI & PERL
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.
By default, both the NCSA and Apache servers disable server-side
includes. To enable them, you need to take the following two steps:
- 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
- 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.
The basic format for the server-side include is as follows:
<!--#command tag1="value1"
tag2="value2" -->
Possible commands include the following:
- config
- echo
- include
- exec
- fsize
- flastmod
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
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. |
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.
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.
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 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).

Contact
reference@developer.com with questions or comments.
Copyright 1998
EarthWeb Inc., All rights reserved.
PLEASE READ THE ACCEPTABLE USAGE STATEMENT.
Copyright 1998 Macmillan Computer Publishing. All rights reserved.