5 January 2002   danielh@crosslink.net

                   The SIMPLE filter for the SRE2003 Http Server

This directory contains the SIMPLE filter for the SRE2003 ver 1.12
http server for OS/2.

                ----------------------------------------

                        Introduction

SIMPLE, as it's name suggests, does not have a lot of bells and
whisltes. But it does have a few, all of which are set by
modifying user-configurable parameters in SIMPLE.RXX.

For example:

 * alternative directories on a selector specific basis.
 * redirection
 * simple access controls
 * automatically add an Content-MD5 header

Again, to set these features, you must modify SIMPLE.RXX -- there's
plenty of documentation there to remind you of the hows and whats.

Also included in this directory is FASTFILT.RXX -- a VERY simple
(though slightly configurable) example of a SRE2003 "fast filter". 
See FASTFILT.RXX for the details.

                ----------------------------------------

                        Basic Parameters:


Add_md5:
   add_md5=1   -- add a Content-MD5 header to all responses
   add_md5=0   -- do not add a Content-MD5 header to all responses

AUDIT:
  0  : do not write "log" information 
  1 :  write info to the audit.log file
  2 :  write to audit file and pmprintf window,

   Example: AUDIT=2     

DEFAULT:

   The default document == used if the request ends in a /
   This also includes the "empty" request.
   Examples of when DEFAULT is used:
       http://www.hello.org/
       http://www.hello.org/files/june10/

   Default should be a file name only (no path info).

   Note that the location of the home page, etc. is relative to the datadir (datadir
   is set in SRE2003.CFG). Thus, if the DataDir is d:\www, and default is index.htm,
   the a request to http://www.hello.org/ would yield d:\www\index.htm  */

  Example: default='index.html'

FEATURES. :
   Used to specify selector specific features, such as alternate "base" directories,
   redirection, and access controls  See below for the details.


MIMETYPE. :

  Mime type mappings -- these modify the default mimetypes.

  These should be of the form:   
      mimetype.!xxx='type/subtype'
  where xxx is an extension.

  For example:
      mimetype.!DOC='text/plain'
      mimetype.!ARJ='application/octet-stream'


SCRIPT_ACCESS_LOCALONLY

  Limit access to scripts. If set equal to 1, then only clients running a 
  browser on the  same machine as the server (that is, only when the
  client's ip address is the same as the servers) will be allowed to run 
  scripts

  Example:
    script_access_localonly=0


SCRIPT_DIR
   Scripts directory. This directory (relative to the "filter" directory)
   contains scripts. Scripts are invoked by placing a ! point as the first
   character of the URI (actually, the first character after the leading /).
   For example...
   if 
       SCRIPT_DIR=SCRIPTS, 
   then the SIMPLE\SCRIPTS\STATUS.CMD script can be invoked by using a URI of 
       /!STATUS   
   (the .CMD is optional).   
 
  Example: script_dir='SCRIPTS'

USE_IPNAME:
   Use IP name in AUDIT.LOG output (i.e.; use me.foobar.net instead of 121.225.12.5)
   0 : use IP address (dotted numeric)
   1 : use IP name 

   Example: US_IPNAME=1



                ----------------------------------------

                    The FEATURES. parameters


   FEATURES. is used to set a few simple access control and
   redirection options.

   FEATURES.0 should contain the number of "FEATURES." entries.
   The first "matching" entry is used -- where matching
   is based on
     a) abbreviation match of the selector and the FEATURE.nn
        entry
     b) optionally, a suffix match of the selector and the 
        FEATURE.nn entry.
   Alternatively, you can require that FEATURE.nn be an exact
   match to the selector 


Notes:

   * By default, this SIMPLE filter assumes that all uri's refer to files that are
     relative to the "datadir" directory. You can change this with the !BASEDIR 
     option.
 
   * Since the first match found is the one that is used --  
     THE ORDER OF ENTRY MATTERS!!

   * If FEATURES.0=0, or the request "selector" does not match any
     of the FEATURES. entries, the request is accepted (and assumed to refer
     to a file relative to the data directory)

Features options are (for n=1 to FEATURES.0):

 * Required: 
    FEATURES.n           -- the "abbreviation match"
 * Optional:
    FEATURES.n.!SUFFIX   -- A secondary check -- a suffix match
    FEATURES.n.!EXACT    -- Exact match flag 

    FEATURES.n.!BASEDIR  -- specify the base directory
    FEATURES.n.!USERS    -- access control, by username and password
    FEATURES.n.!PWDS    -- access control, by username and password

    FEATURES.n.!REDIRECT -- redirect to this selector 

In greater detail:

  FEATURES.n
     If FEATURES.n is a case-insensitive abbreviation for the selector
     then this entry may be used (depending on the values of the .!EXACT
     .!SUFFIX options).


  FEATURES.n.!SUFFIX:
        In addition to the "prefix" specified in FEATURES.n, you
        can also specify a "suffix". For example, you may
        want to specify all .TXT files in a directory, but not
        .HTML files.

        For example:
            FEATURES.0=2
            FEATURES.1='/mydir/'
            FEATURES.1.!SUFFIX='.DOC'
            FEATURES.2='/mydir/'
            FEATURES.2.!SUFFIX='.TXT'

     This means "only accept requests to the /MYDIR/ directory that are for files ending in
    .DOC or .TXT"

  FEATURES.n.!EXACT
     If equal to 1, forces an exact (case insensitive) match -- 
     not an abbreviation match.
     Example:
         FEATURES.4='/'
         FEATURES.4.!EXACT=1     
     Means "accept the '/' selector, but not necessarily '/other_stuff'"


  FEATURES.n.!BASEDIR:
        Specify a base directory to use when determining the
        file corresponding to this selector. If FEATURES.n.!BASEDIR
        is not specified, the default (SRE2003) "datadir"
        directory is used.

        Example:
            FEATURES.10='/cartoons/'
            FEATURES.10.!BASEDIR='F:\FUNNIES\GRAPHIC\'

        Notes:
          * Be careful how you specify FEATURES.nn and FEATURES.nn.!BASEDIR --
            / and \ characters are not added or removed.



   FEATURES.n.!REDIRECT:
        
        FEATURES.n.!REDIRECT is used to redirect a request 
        to a different URI.  The value of the "prefix" is
        replaced by FEATURES.n.!REDIRECT, and a 301 response
        is returned to the client.

         Example:
             FEATURES.7='/joe/'
             FEATURES.7.!REDIRECT='http://foo.bar/net/joesplace/'
        
        If the request is for /joe/index.htm, a 301 "redirect"
        to http://foo.bar.net/joesplace/index.htm will be
        returned to the client.

        Note that you should specify the full url, including the
        http://.


  FEATURES.n.!USERS and FEATURES.n.!PWDS
     You can use the .!USERS and .!PWDS option to control access to a 
     resource.
     The value of FEATURES.n.!USERS should be a space delimited list of
     case insensitive username. 
     The value of FEATURES.n.!PWDS should be a space delimited list of
     case insensitive passwords. 

     The nth password is associated with the nth usename.
     Thus:
       There MUST be the same number of words in each !USERS and !PWDS entry.
  
     Example:
        FEATURES.3.!USERS='joe  jill Cat'
        FEATURES.3.!PWDS='buz1  onthehill DogAWAY '
     Hence, the "jill" username has a "onthehill" password (note that neither is
     case sensitive).
  
    Notes:
        * usernames and passwords must NOT contain spaces
        * if the request does not contain an Authorization header,
          a 401 (request for authorization) response is returned.
        * FEATURES.3.!USERS=' ' means "no access control"

Examples:

FEATURES.0=3

FEATURES.1='/manual/'
FEATURES.1.!suffix='.DOC'
FEATURES.1.!USERS='joe  jill Cat '
FEATURES.1.!PWDS='buz1  onthehill DogAWAY '


FEATURES.2='/temp/'
FEATURES.2.!basedir='f:\temp\'

FEATURES.3='/site2/'
FEATURES.3.!Redirect='http://www.site2.net/'


                ----------------------------------------

                    Sample Scripts

The SIMPLE filter has the capability of running some "simple" scripts. These scripts
are invoked by using a URI that starts with a !. For example:
  <a href="/!STATUS.CMD">View Server status? </a>
Note the leading / -- that's to ensure that the browser doesn't add "directory"
information to the request!

Scripts should be placed in the SCRIPTS subdirectory of the SIMPLE directory (see the
description of the SCRIPTS_DIR parameter).  Thus, if the SCRIPTS_DIR is
D:\SRE2003\SIMPLE\SCRIPTS, in the above example SIMPLE will use a file with the
name D:\SRE2003\SIMPLE\SCRIPTS\STATUS.CMD.

Note that if you do NOT have a .extension in the URI, a .CMD is assumed.

Scripts are called as procedures, with two variables;
   params: everything following a ? in the URI
   idinfo: the "id_info". You can use this in calls to SRE_COMMAND, etc.

Rather then go into great detail, we advise examination of the several samples scripts
packaged with SRE2003. 


