HTTPD_SSI(7) BSD Miscellaneous Information Manual HTTPD_SSI(7)NAMEhttpd_ssi — Server Side Includes (SSI) for xs-httpd
DESCRIPTION
One of the advanced features of this WWW server is its server side
includes. Server side includes (SSIs) are “commands” to the server to do
something. These may be embedded in HTML documents.
The general format of such a directive is as follows:
<!--#name opt=arg [opt=arg ...]-->
name is the name of the directive. Options may sometimes be omitted.
Option and argument pairs should be separated each other nd from the com‐
mand name by a single space. If the argument contains spaces or other
special characters (such as the equals sign), it must be contained in
double quotes ("). Note also that a directive must start and end on the
same line. You may have other things on that line, including other
directives.
When the server sends a HTML document to the remote client, it will parse
all of the directives that are embedded in that document. The following
directives are recognized:
Content directives
<!--#count-total-->
This directive inserts the number of times that this page has
ever been retrieved. You may use counters as many times as you
wish per page, they will only increment once.
<!--#count-month-->
This directive inserts the number of times that this page has
been retrieved this month.
<!--#count-today-->
This directive inserts the number of times that this page has
been retrieved today.
<!--#count-total-gfx [location]-->
This directive inserts a HTML tag to include a graphical repre‐
sentation of the number of times that this page has ever been
retrieved. If location is specified, it will be used as a base
location for the font. A font has 10 digits in it, each in a
separate file, all PPMs. Say location is /~user/font1/, and
digit 1 is needed, then /~user/font1/1.ppm will be used as that
digit. Three standard fonts are supplied with this WWW server.
They may be accessed using the locations: /fonts/digital (which
is the default), /fonts/large and /fonts/largecol.
<!--#count-month-gfx [location]-->
This directive inserts a HTML tag to include a graphical repre‐
sentation of the number of times that this page has been
retrieved this month. See above for location.
<!--#count-today-gfx [location]-->
This directive inserts a HTML tag to include a graphical repre‐
sentation of the number of times that this page has been
retrieved today. See above for location.
<!--#count-reset-->
This directive resets all counters for this page to 0.
<!--#date [format=conv-spec]-->
This directive inserts the current date and time, optionally in
your own format. The conversion specification conv-spec must be
in strftime(3) format.
<!--#date-format format=conv-spec-->
This directive sets format as the new date and time format. You
must specify the format in strftime(3) format.
<!--#echo varname [encoding={none|html|url}]-->
<!--#echo var=varname [encoding={none|html|url}]-->
<!--#echo envvar=varname [encoding={none|html|url}]-->
Print the value of a variable. This can be a local variable that
was set using the set directive, or an CGI environment variable
that was set by the webserver. If the envvar option is used, only
CGI environment variables are searched.
The optional encoding= argument defaults to html encoding.
Selecting none will do no rewriting at all and is therefore use‐
ful in text/plain files. Selecting html replaces special html
symbols (such as ‘<’ and ‘&’) to the appropriate sgml entities
for proper display. Selecting url encodes any non alphanumeric
characters with their ‘%xx’ equivalent.
<!--#include file=file-->
<!--#include-file file-->
This directive allows you to include file in this document. This
is very useful for standard headers and footers. Note that
included files may be nested and that directives are parsed in
them. Note also that counters and such always count the original
file, so you can use the count directives in your standard head‐
ers and footers. The argument can be an absolute path
(/home/username/.html/file.html), a virtual path relative to the
user's html directory (/~username/file.html) or a relative path
(file.html).
<!--#include binary=file-->
<!--#include virtual=file-->
By default included files are handled as if they are standard
HTML documents. This means these are interpreted as text and SSI
directives inside these files will be parsed as well. Special
handling can be selected using the binary or virtual argument.
Binary files are copied directly: without SSI handling or other
special (text) parsing taking place. Virtual files are handled
as if these were separate webserver (GET) requests: full parsing
is done and it is even possible to call CGI binaries which will
be interpreted as well this way.
<!--#last-mod [file]-->
<!--#last-modified [file]-->
This directive inserts the last modification date of either the
originally request file (the current document) or the optionally
specified file. The date will be in the format specified by the
date-format directive.
<!--#run-cgi cgi-->
Runs the CGI binary cgi and inserts its output at this point.
Standard PATH_INFO and PATH_TRANSLATED parsing is done, so you
can give arguments to the CGI binary. All standard CGI environ‐
ment variables will be set up appropriately. See httpd_cgi(7)
for more details on CGIs.
The CGI pathname must be given in URL syntax, the same way as the
local part of a full URL. The path may not be omitted:
<!--#run-cgi /~username/cgi-bin/file-->
The arguments will be made available through the QUERY_STRING
environment variable. For example
<!--#run-cgi "/~username/cgi-bin/file?foo=bar&foo=baz"-->
Quotes are important here to guarantee proper parsing. Without
these the path might be interpreted as a command, value pair.
<!--#set varname=value [varname=value ...]-->
Set one or more internal variables with given names and values.
These variables can later be printed using the echo directive.
The variables can also be accessed from other files that are pro‐
cessed during the same request.
Variable names or values may contain spaces if this value is
enclosed in double quotes, e.g.
<!--#set title="Hello World"-->
set in combination with include can be used for example to create
a common header file for inclusion, in which only the title
changes. This title can then be printed with echo. Another use‐
ful method is to have set in combination with if-statements in an
included file, for instance to generate a common menu file in
which the selected entry is displayed distinctively. Alterna‐
tively, variables may also be set in the included file and then
used in the main document.
Control directives
<!--#if keyword pattern [pattern ...]-->
<!--#if-not keyword pattern [pattern ...]-->
The if and if-not directives try to match the value associated
with the given keyword against the set of patterns. If any pat‐
tern matches or in the case of if-not if no pattern matches the
section until the next matching else or endif is parsed. Other‐
wise when a matching else directive is encountered the section up
to the matching endif directive is parsed. Patterns are simple
case-insensitive wildcard patterns.
The following keywords are recognized:
var=varname
envvar=varname
Use the requested variable or CGI environment variable to
check against the given pattern(s).
For backwards compatibility reasons the following keyword aliases
are also recognized:
browser
Alias for envvar=USER_AGENT
remote-host
Alias for envvar=REMOTE_HOST
remote-name
Alias for envvar=REMOTE_HOST
remote-addr
Alias for envvar=REMOTE_ADDR
<!--#else-->
This directive optionally separates the code for the true and the
false evaluation of the corresponding checking (i.e. if or
if-not) directive. If there is no else directive between the
checking directive and the corresponding endif directive nothing
will be evaluated when the check fails.
<!--#endif-->
This directive closes a conditional section started by an if or
if-not directive.
<!--#switch keyword-->
The switch directive tries to find a corresponding case directive
with a matching pattern before the corresponding endswitch direc‐
tive. If a matching case directive is found the code following
this case up to the next corresponding case directive or the next
corresponding endswitch directive.
<!--#case pattern [pattern ...]-->
The case directive starts the section to parse if any of its
patterns matches the keyword from the corresponding switch.
<!--#endswitch-->
This directive closes a conditional section started by the corre‐
sponding switch directive.
SEE ALSOhttpd(1), httpd_cgi(7)
The project homepage: http://www.xs-httpd.org/
xs-httpd/3.5 May 9, 2007 xs-httpd/3.5
