NAME

     ssi — Server-Side-Includes CGI program

SYNOPSIS

     ssi

DESCRIPTION

     This is an external CGI program that provides the same functionality as the built-in server-
     side-includes feature in many HTTP daemons.  It is written for use with thttpd(8) and
     merecat(8), but should be easy to adapt to other systems.

     There are two ways to use this; the modern way of using a .shtml pattern in merecat.conf(5)
     to trigger the SSI script, which requires enabling the SSI module.  Then there is the
     traditional thttpd(8) approach.  We start with the relevant settings needed in merecat.conf:

           ssi {
               enabled = true
               pattern = "**.shtml"        # default
               cgi-path = "cgi-bin/ssi"    # default, web server root is used
           }

     The traditional thttpd way runs ssi as a simple CGI script, which requires placing the ssi
     binary in the web server CGI area, and enabling CGI.  Then set up URLs with the path to the
     document to parse as the "pathinfo".  That's the part of the URL that comes after the CGI
     program name.  For example, if the URL to this program is:

         http://www.acme.com/cgi-bin/ssi

     and the url for the document is:

         http://www.acme.com/users/wecoyote/doc.html

     then the compound URL would be:

         http://www.acme.com/cgi-bin/ssi/users/wecoyote/doc.html

INCLUDE FORMAT

     The format description below is adapted from
     ⟨http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html⟩.

     All directives are formatted as SGML comments within the document.  This is in case the
     document should ever find itself in the client's hands unparsed.  Each directive has the
     following format:

         <!--#command tag1="value1" tag2="value2" -->

     Note: the lack of space between the initial HTML comment start and the #command.  This is
     explicitly stated in the standard and strictly enforced by all web servers implementing SSI.

     Each command takes different arguments, most only accept one tag at a time.  Here is a
     breakdown of the commands and their associated tags:

     config  The config directive controls various aspects of the file parsing.  There are two
             valid tags:

             timefmt
                     gives the server a new format to use when providing dates.  This is a string
                     compatible with the strftime(3) library call.

             sizefmt
                     determines the formatting to be used when displaying the size of a file.
                     Valid choices are bytes, for a formatted byte count (formatted as
                     1,234,567), or abbrev for an abbreviated version displaying the number of
                     kilobytes or megabytes the file occupies.

             errmsg  overrides the default; "[an error occurred while processing this directive]"

     include
             Inserts the text of another document into the parsed document.  The inserted file is
             parsed recursively, so it can contain server-side-include directives too.  This
             command accepts two tags:

             virtual
                     Gives a virtual path to a document on the server.

             file    Gives a pathname relative to the current directory. ../ cannot be used in
                     this pathname, nor can absolute paths be used.

     echo    Prints the value of one of the include variables (defined below).  Any dates are
             printed subject to the currently configured timefmt.  The only valid tag to this
             command is var, whose value is the name of the variable you wish to echo.

     fsize   prints the size of the specified file, subject to the sizefmt parameter to the
             config command.  Valid tags are the same as with the include command.

     flastmod
             prints the last modification date of the specified file, subject to the formatting
             preference given by the timefmt parameter to config.  Valid tags are the same as
             with the include command.

VARIABLES

     A number of variables are made available to parsed documents.  In addition to the CGI
     variable set, the following variables are made available:

     DOCUMENT_NAME
             The current filename.

     DOCUMENT_URI
             The virtual path to this document (such as /~robm/foo.shtml).

     QUERY_STRING_UNESCAPED
             The unescaped version of any search query the client sent.

     DATE_LOCAL
             The current date, local time zone.  Subject to the timefmt parameter to the config
             command.

     DATE_GMT
             Same as DATE_LOCAL but in Greenwich mean time (GMT).

     LAST_MODIFIED
             The last modification date of the current document.  Subject to timefmt like the
             others.

SEE ALSO

     merecat(8), merecat.conf(5), strftime(3)

AUTHORS

     Jef Poskanzer <jef@mail.acme.com> wrote the original for use with thttpd.
     Joachim Wiberg <troglobit@gmail.com> added minor features and a trigger in merecat for
     .shtml pages.

BUGS

     Does not implement all "modern" SSI directives are supported. E.g., exec cgi and exec cmd or
     any control directives like if, elif, else, endif, etc.  Patches and pull-requests are
     welcome :)