Chapter 14. Server-Side Includes
Server-side includes trigger further actions whose output, if any,
may then be placed inline into served documents or affect subsequent
includes. The same results could be achieved by CGI
scripts — either shell scripts or specially written C
programs — but server-side includes often achieve these results
with a lot less effort. There are, however, some security problems.
The range of possible actions is immense, so we will just give basic
illustrations of each command in a number of text files in
...site.ssi/htdocs.
The Config file, .../conf/httpd1.conf, is as
follows:
User webuser
Group webgroup
ServerName www.butterthlies.com
DocumentRoot /usr/www/APACHE3/site.ssi/htdocs
ScriptAlias /cgi-bin /usr/www/APACHE3/cgi-bin
AddHandler server-parsed shtml
Options +Includes
Run it by executing ./go 1.
shtml is the
normal extension for HTML documents with server-side includes in them
and is found as the extension to the relevant files in ...
/htdocs. We could just as well use
brian or dog_run, as long
as it appears the same in the file with the relevant command and in
the configuration file. Using html can be
useful — for instance, you can easily implement site-wide headers
and footers — but it does mean that every HTML page gets parsed
by the SSI engine. On busy systems, this could reduce performance.
Bear in mind that HTML generated by a CGI script does not get put
through the SSI processor, so it's no good including
the markup listed in this chapter in a CGI script.
Options
Includes
turns on processing of SSIs. As usual, look in the
error_log if things don't work.
The error messages passed to the client are necessarily uninformative
since they are probably being read three continents away, where
nothing useful can be done about them.
The trick of SSI is to insert special strings into our documents,
which then get picked up by Apache on their way through, tested
against reference strings using =, !=, <, <=, >, and >=,
and then replaced by dynamically written messages. As we will see,
the strings have a deliberately unusual form so they
won't get confused with more routine stuff. This is
the syntax of a command:
<!--#element attribute="value" attribute="value" ... -->
The Apache manual tells us what the
elements are:
- config
-
This command
controls various aspects of the parsing. The valid attributes are as
follows:
- errmsg
-
The value is a message that is sent back to the client if an error
occurs during document parsing.
- sizefmt
-
The value sets the format to be used when displaying the size of a
file. Valid values are bytes for a count in bytes
or abbrev for a count in kilobytes or megabytes,
as appropriate.
- timefmt
-
The value is a string to be used by the strftime(
) library routine when printing dates.
- echo
-
This
command
prints one of the include variables, defined later
in this chapter. If the variable is unset, it is printed as
(none). Any dates printed are subject to the
currently configured timefmt. This is the only
attribute:
- var
-
The value is the name of the variable to print.
- exec
-
The exec command
executes a given shell command or CGI script.
Options IncludesNOEXEC disables
this command completely — a boon to the prudent webmaster. The
valid attribute is as follows:
- cgi
-
The value specifies a %-encoded URL relative path to the CGI script.
If the path does not begin with a slash, it is taken to be relative
to the current document. The document referenced by this path is
invoked as a CGI script, even if the server would not normally
recognize it as such. However, the directory containing the script
must be enabled for CGI scripts (with ScriptAlias
or the ExecCGI option). The protective wrapper
suEXEC will be applied if it is turned on. The
CGI script is given the PATH_INFO and query string
(QUERY_STRING) of the original request from the
client; these cannot be specified in the URL path. The
include variables will be available to the script
in addition to the standard CGI environment. If the script returns a
Location header instead of output, this is
translated into an HTML anchor. If Options
IncludesNOEXEC is set in the Config file, this
command is turned off. The include
virtual element should be used in preference to
exec cgi.
- cmd
-
The server executes the given string
using /bin/sh. The include
variables are available to the command. If Options
IncludesNOEXEC is set in the Config file, this is
disabled and will cause an error, which will be written to the error
log.
- fsize
-
This
command
prints the size of the specified file, subject to the
sizefmt format specification. The attributes are
as follows:
- file
-
The value is a path relative to the directory containing the current
document being parsed.
- virtual
-
The value is a %-encoded URL path relative to the document root. If
it does not begin with a slash, it is taken to be relative to the
current document.
- flastmod
-
This
command prints the last modification date
of the specified file, subject to the timefmt
format specification. The attributes are the same as for the
fsize command.
- include
-
This command
includes other files immediately at that point in parsing — right
there and then, not later on. Any included file is subject to the
usual access control. If the directory containing the parsed file has
Options IncludesNOEXEC set and
including the document causes a program to be executed, it
isn't included: this prevents the execution of CGI
scripts. Otherwise, CGI scripts are invoked as normal using the
complete URL given in the command, including any query string.
An attribute defines the location of the document; the inclusion is
done for each attribute given to the include
command. The valid attributes are as follows:
- file
-
The value is a path relative to the directory containing the current
document being parsed. It can't contain
../, nor can it be an absolute path. The
virtual attribute should always be used in
preference to this one.
- virtual
-
The value is a %-encoded URL relative to the document root. The URL
cannot contain a scheme or hostname, only a path and an optional
query string. If it does not begin with a slash, then it is taken to
be relative to the current document. A URL is constructed from the
attribute's value, and the server returns the same
output it would have if the client had requested that URL. Thus,
included files can be nested. A CGI script can still be run by this
method even if Options
IncludesNOEXEC is set in the Config file. The
reasoning is that clients can run the CGI anyway by using its URL as
a hot link or simply by typing it into their browser; so no harm is
done by using this method (unlike cmd or
exec).
14.1. File Size
The fsize command allows you to report the size of
a file inside a document. The file size.shtml is
as follows:
<!--#config errmsg="Bungled again!"-->
<!--#config sizefmt="bytes"-->
The size of this file is <!--#fsize file="size.shtml"--> bytes.
The size of another_file is <!--#fsize file="another_file"--> bytes.
The first line provides an error message. The second line means that
the size of any files is reported in bytes printed as a number, for
instance, 89. Changing bytes to
abbrev gets the size in kilobytes, printed as
1k. The third line prints the size of
size.shtml itself; the fourth line prints the
size of another_file. config
commands must appear above commands that might want to use them.
You can replace the word file= in this script, and
in those which follow, with virtual=, which gives
a %-encoded URL path relative to the document root. If it does not
begin with a slash, it is taken to be relative to the current
document.
If you play with this stuff, you find that Apache is strict about the
syntax. For instance, trailing spaces cause an error because valid
filenames don't have them:
The size of this file is <!--#fsize file="size.shtml "--> bytes.
The size of this file is Bungled again! bytes.
If we had not used the errmsg command, we would
see the following:
...[an error occurred while processing this directive]...
| | |
13.3. XML, XSLT, and Web Applications | | 14.2. File Modification Time |
Copyright © 2003 O'Reilly & Associates. All rights reserved.