SSI Documentation                                          ZeroToaster::HTTPD
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Preface
=======
Server Side Includes (in short SSI) allow some dynamic content in static
HTML pages like inserting the local time, size of a certain file and 
including content of the output of CGI programs.

SSI Issues
==========
HTML files which have to be interpreted as SSI files are somewhat slower 
than usual HTML pages and they consume more memory while processing and 
buffering. A usual HTML page is simply streamed from disk to the requesting
client. An SSI page is loaded into memory, parsed, interpreted, executed,
filled with content, then stuffed back into memory where the final content 
length is calculated and sent to the client.

Another problem is the possibility of including and executing files outside 
of the document root context (and in the context of the HTTPD process).

SSI format
==========
Each directive has the following format:

<!-- #command [tag [="parameter"]] -->

Some commands require tags and some do not.  Most, but not all, tags need parameters.  Each directive can only have one command, but multiple tags for each command are allowed. 

Valid:   <!-- #config sizefmt="bytes" errmsg="Shit happens" -->
Invalid: <!-- #config sizefmt="bytes" #include virtual="file" -->

Supported SSI commands
======================

#config
-------
As the name says, this command configures various parameters. The presets
for this are defined in vhost.cfg in section [MOD_CGI]

Valid tags and parameters:

 * errmsg="message"
   Sets the new default errormessage which is sent back to the client if
   an error occured while interpreting or executing a command.

   Example: <!-- #config errmsg="Shit happens" -->
   
 * sizefmt="bytes/abbrev"
   Sets the formatting to be used when displaying file sizes. Valid 
   parameters are "bytes" (size is displayed as raw number) and "abbrev"
   (size is displayed as GB/MB/KB/Bytes)

   Example: <!-- #config sizefmt="abbrev" -->
   
 * timefmt="display-string"
   Sets the formatting to be used when displaying a file date/time. See
   appendix A for valid parameters.

   Example: <!-- #config timefmt="%d.%m.%Y, %H:%M" -->

 * locale="language_COUNTRY"
   Sets the locale used for date/time formatting.

   Example: <!-- #config locale="en_AU" -->
 
#echo 
-----
Echos the content of a CGI environment variable. The environment also contains
the parameters declared by #config and #set.

Valid tags and parameters:

 * var="environment variable" 
   Outputs a specific environment variable.
   
   Example: <!-- #echo var="SERVER_NAME" var="SERVER_PORT" -->
   
 * dump="all"
 
   This special tag=parameter combination dumps the whole content of
   the CGI environment for this page and is provided for debugging.
  
   Example: <!-- #echo dump="all" -->

#error
------
Simply displays the current default errormessage. A simple test command for
#config errormessage="new message"

Valid tag and parameters: none.

   Example: <!-- #error -->

#exec
-----
Executes a script or program. The CGI environment is copied into the operating 
system environment. The script output to STDOUT is copied into the website.
Zerotoaster::HTTPD makes no difference between CGI or shell or something. 
Everything is executed through the cgi_handler parameters defined in 
vhost.cfg, section MOD_CGI.

 * cmd="/script.cmd"
 * cgi="/webmail"
   
   Example: <!-- #exec cmd="ssi.cmd" -->
   
#flastmod
---------
Displays the last modified date for this file.

Valid tags and parameters:

 * virtual="/filename"
   The path is assumed to be below the document root.
   
   Example: <!-- #flastmod virtual="/index.html" -->

 * file="filename"
   The path is assumed to be an absolute path.

   Example: <!-- #flastmod file="c:\startup.cmd" -->
   
#fsize
------
Echoes the size of the specified file.

Valid tags and parameters: See #flastmod

   Example: <!-- #fsize file="zerotoaster.ini" -->

#include
--------
Includes this file into the SSI document and displays it

Valid tags and parameters: See #flastmod

   Example: <!-- #include virtual="/footer.inc" -->

#set 
----
This command sets a certain environment variable to a new value. This is 
the same as "#config name="newvalue" because we're storing the configuration
in the environment too.

Valid tags and parameters:

 * var="name" value="newvalue"
   Sets the environment variable "name" to the new value "newvalue".

   Example: <!-- #set var="cow" value="moo" -->

#statistics
-----------
Provides some statistics about the simple life of our webserver and the  
pages requested.

Valid tags and parameters:

 * server="uptime"
   Returns the uptime of the server in d/h/m/s
   
   Example: <!-- #statistics server="uptime" -->
   
 * server="served"
   Returns the number of requests served
   
   Example: <!-- #statistics server="served" -->

 * page="requested"
   Returns how often this page was requested. The request data is stored
   in a file "pagecounter.dat" in the /htdocs/ directory. This filename
   and its location is not changeable.
   
   Example: <!-- #statistics page="requested" -->

Appendix A
----------
Valid parameters for "timefmt"

 %a Weekday short, like Sat, Sun
 %A Weekday long, like Saturday, Sunday
 %b Month short, like "Oct"
 %B Month long, like "October"
 %d Day in month, 2 digits right aligned
 %e Day in month, 1-2 digits
 %H Hour (24h)
 %I Hour (12h)
 %m Month as number, 2 digits right aligned
 %M Minute in hour, 2 digits right aligned
 %p AM/PM
 %S Second in minute, 2 digits right aligned
 %w Day of week, 1-2 digits
 %y Year, 2 digits right aligned
 %Y Year, 4 digits
 %Z Time zone like GMT, UCT

Appendix B
----------
References:
http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
http://httpd.apache.org/docs/howto/ssi.html
