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, program or servlet. 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. For more information about using Servlets
in a SSI website, refer to the servlet.txt document. The #exec command has
one restriction: only one tag is allowed so #exec cmd="ssi.cmd" cmd="this.cmd"
doesn't work.

Valid tags and parameters:

 * cmd="executeable/script"
 * cgi="executeable/script"
 * srv="classname" [attribute="value"] [attribute="value"] [...]
 
   Example: <!-- #exec cmd="ssi.cmd" -->
   Example: <!-- #exec cmd="/cgi-bin/webmail" -->
   Example: <!-- #exec cgi="/shop" -->
   Example: <!-- #exec srv="net.zerotoaster.httpd.servlet.CGIServlet" action="display" -->
   
#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" -->

#fhash
------
Calculates and echoes the MD5/SHA hash of the specified file. The calculated
value is cached in the tempfiles directory of your vhost. Only the "virtual"
tag is allowed, files outside the /htdocs/ directory can't be processed. 
This is an intentional limitation of the caching system.

Valid tags and parameters:

 * virtual="/filename" algorithm="MD5"
   Echoes the MD5 hash of file "/filename"

   Example: <!-- #fhash virtual="/importantsoftware.exe" algorithm="MD5" -->

 * virtual="/filename" algorithm="SHA"
   Echoes the SHA hash of file "/filename"

   Example: <!-- #fhash virtual="/docs/myresume.pdf" algorithm="SHA" -->

#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
