SSI-LM-Hack 1.0b for Apache 1.3b7 and 1.2.0/1.2.1/1.2.4/
--------------------------------------------------------

What is it all about?
---------------------
The SSI-LM-Hack is a patch/replacement for the Apache 
module mod_include (the one providing SSI (server-side includes) 
features) giving Last-Modified-Dates for non-dynamic SSI
documents. Please refer to the Apache documentation (e.g.
at http://www.apache.org) for further info on SSI.


Why use it?
-----------
Because the Apache httpd assumes all SSI parsed documents to
be dynamic it does not provide a Last-Modified: http header if such
a document is requested. This is a good thing for truly dynamic
pages (e.g. using #exec) as this stops most proxy and browser caches 
from caching the document.

But when using SSI for the sole purpose of being able to include
portions of html source common to several files, the resulting
documents are not really dynamic. Nonetheless the above rule applies
to them as well, stopping proxies from caching the document thus
increasing your server load and access times.

There are several ways to solve this problem:

- Use the Apache XBITHACK feature. This enables you to manually
  set the group xbit on those SSI-parsed files that you know to
  be non-dynamic. The Apache httpd will provide the files' last
  modification date as Last-Modified: header.
  Pros: nearly no server overhead, comes with apache distribution
  Cons: ugly, awkward to keep all those bits correct, modifiying
        the included files doesn't update the date

- Use some way to create an Expires: http header which will be
  used by proxy caches. You can do that by using mod_expire
  from the standard distribution.
  Pros: depending on the application you can set very accurate
        expiry dates
  Cons: lots of work for the administrator

- Use the SSILMHACK :-)
  Pros: the server handles everything automagically, modifying included 
        documents updates the Last-Modified: date
  Cons: slight hit on server performance for SSI-parsed documents


How does it work?
-----------------
The basic idea is to use the most recent modification date of
the SSI document file itself and all included document files as the
Last-Modification-Date used in the header of the HTTP response.
Because the header must be output before the body an additional parse
pass was necessary. During this pass all relevant SSI statements are
analyzed as follows (no output is generated):

- #include: SSILMHACK will stat the file to be included and get its
  modification date. In case it's more recent than the current date
  (initialized with the document's LM date) the new date is used.
  
- #exec: The document is considered to be a dynamic one. No LM date
  will be used.
  
- most of the other statements are ignored

After this first pass the Header including the LM date is sent.
Then the normal document parsing producing output will be performed.


How do I install it?
--------------------
Installing is quite easy. However, you'll have to remake the httpd
executable. I assume you are familiar with this process. The
following steps are necessary:

- Replace the file src/mod_include.c by the SSILM one. You may
  want to keep a backup copy of the original file:
  
    src/modules/standard> mv mod_include.c mod_include.c.ori
    src/modules/standard> cp ~/ssilm/mod_include_1.3b7.c mod_include.c  

- Next edit 'Configuration', find the EXTRA_CFLAGS and add something 
  like the following:

    EXTRA_CFLAGS=-DSERVER_SUBVERSION=\"SSILMHack/1.0b\" -DSSILMHACK

  The -DSSILMHACK will define the preprocessor symbol SSILMHACK
  which enables the changes in mod_include.c. If you do not define
  this the new mod_include.c will behave identically to the original
  one.
  The -DSERVER_SUBVERSION=\"SSILMHack/1.0b\" changes the 
  Server: http header Apache uses to:

    Server: Apache/1.3b7 SSILMHack/1.0b

- That's all. Now continue as usual with './Configure' followed by
  'make'. This should give you a new httpd executable with the
  SSILM features.


Are there any problems?
-----------------------
There are some points you should be aware of:

- SSILMHACK does not work correctly with nested includes, i.e.
  dates of files included by other included files are not considered
  when calculating the modification time. This is due to the simplified
  parsing in the additional pass. This is often not too much of a
  problem, however.

- SSILMHACK has not really been tested with all of the SSI statements
  out there. It should however give plausible results in most cases,
  but I cannot guarantee that. One potential problem is using the #if
  or #echo directives with environment variables such as REMOTE_HOST
  etc. which give different results for each request. SSILMHACK won't
  detect this and consider the document static.

SSILMHACK has been successfully used by the webserver of the Unix-AG 
at the University of Siegen (http://www.unix-ag.uni-siegen.de) for 
over 2 years with an NCSA httpd and for several months with an Apache
httpd providing homepages for students at the University
(http://www.stud.uni-siegen.de).


Revision History
----------------
1.0b - support for 1.3 (currently 1.3beta7)

1.0a - support for 1.2.4
     - 1.0 had a bug when trying to use '#include file=...' to include
       a file that is not in the same or lower directory where the document
       resides. Apache forbids this include yielding an error message.
       SSILMHACK crashed when doing this - fixed now.

1.0  - first public version

Things to do
------------
There is much space for improvement:

- Make it configurable on a per directory/file basis. This could
  be done via special SSI directives (e.g. <!--#dynamic -->) or
  the server config files (e.g. 'Options -SSILMHACK')

- Make SSILMHACK smarter and more robust, i.e. producing correct
  output with some of the more exotic SSI statements.
  
- Support correct dates when using nested includes.

- Improve this documentation.


Contacting the author and retrieving new versions
-------------------------------------------------
If you have any questions or suggestions for improvement feel free
to contact me via email: Frank Thilo <thilo@unix-ag.org>

You can also retrieve the current version from

  http://www.home.unix-ag.org/thilo/ssilmhack/

-- 
Frank Thilo - thilo@unix-ag.org
