27 Oct 1997     SRE-Filter Frequently Asked Questions

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

This document answers the following questions:

* What is SRE-Filter and GoServe?
* What can SRE-Filter do?
* What does SRE-Filter cost?
* Where can I get SRE-Filter?
* I downloaded SREFV12J.ZIP, how do I install it?
* Can SRE-Filter run under Object REXX.
* How do I configure SRE-Filter?
* Can I edit SRE-Filter's configuration files?

* How can I control access to my site?
* How can I use selector specific access controls to control access to a directory?
* What are "client privileges" and "resource privileges" ?
* What's the difference between REALMS and privileges?
* I'm still confused about these privilege things?
* How can I limit the capabilities of different users of our server?
* How can I prevent other web sites from using images stored on our server?

* What are the server side include capabilities of SRE-Filter?
* Can I use cookies with GoServe and SRE-Filter?
* I am having trouble with uploads, what should I do?
* What about default documents?
* What are SRE-Filter's virtual directories?
* How do I redirect a request?
* Can I customize SRE-Filter responses?
* How does SRE-Filter deal with multiple "wildcard" matches?
* How can I record the number of hits I get?
* How can I speed up throughput?
* How do I define new MIME media types?
* How can I prevent NetScape from reloading files too frequently?
* What are the SRE-Filter add-ons?

To users of Don Meyer's GoHTTP -- where appropriate, this document notes
the similarities between the two filters.  You might want to pay special
attention to:
    What are "client privileges" and "resource privileges"?
    How do I redirect a request?
    What are SRE-Filter's virtual directories?
    How can I control access to my site?


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


*** The basics:

* What is SRE-Filter and GoServe?

   SRE-Filter is a "filter" for the GoServe OS/2 Internet Server.
   GoServe, an IBM EWS "freeware" product, is an HTTP (web) and Gopher server.
   GoServe requires a "filter", written in REXX, to interpret and process
   requests for resources.  SRE-Filter is one of several such filters.

* What  can SRE-Filter do?

  In a nutshell:
    SRE-Filter is designed to provide a web server for non-cutting
    edge, small-to-medium load sites being maintained by non-professionals
    who want a fair degree of functionality in an easily maintained system.

* What does SRE-Filter cost.

  $0.00.  You may freely distribute SRE-Filter, and you may dissect, subsect,
  and otherwise utilize it's source code.  Please be aware of the standard
  "use at own risk" disclaimer, and the fact that SRE-Filter is in NO way
  an official or unofficial product of the U.S government.

* Where can I get SRE-Filter

  The latest version of SRE-Filter (it's constantly being updated) can be
  found at http://rpbcam.econ.ag.gov/srefilter.  If you have
  problems with downloading large files over the web, you can
  find FTP instructions at the above URL.

**** Installing SRE-Filter:

* I downloaded SREFV12J.ZIP, how do I install it?

   i) Create a temporary directory somewhere on your hard drive,
   ii) Copy SREFV12J.ZIP (or the several "pieces") to this temporary directory
  iii) Using UNZIP, unzip SREFV12J.ZIP 
  iv) Read the READ.ME file
   v) Run the INSTALL program (type INSTALL from an OS/2 prompt)

* Can SRE-Filter run under Object REXX?

  SRE-Filter was designed to run under "classic" REXX (technically, REXXSAA).
  Unfortunately, for several reasons, the current version of SRE-Filter
  (ver 1.2k) will NOT run object REXX.

  If you really want to use SRE-Filter and Object Rexx, you might
  be interested in obtaining ver 1.2g of SRE-Filter, and some
  special modifications of ver 1.2g.  However, besides lacking
  many features of the current version, experience has shown that
  this combination (modified 1.2g and Object Rexx) is not very stable.

  For details, see the "are you using OBJECT REXX" link on the
  SRE-Filter home page.

  Author's note:  If there is real interest in using SRE-Filter in an
  Object REXX environment, I might be persuadable ...

* How do I configure SRE-Filter?

   Most people will probably want to use the built in configurator.
   This configurator is designed to be run via your web brower.
   Assuming you did not make major modifications to SRE-Filter's
   installation defaults, you can just point your web browser at:
           http://your.browser.wherever/configur.htm
   You will then be given the choice between a "simple-mode",
   "intermediate mode", and "expert mode" configurator.  New users
   will probably like the "simple mode" best.

   Both the simple and intermediate modes make heavy use of HTML
   FORMS.  The simple mode has a "one, well-documented, form
   per parameter" philosophy.  The intermediate mode has a
   "one, not-so-well-documented, form for a large set of parameters"
   The advantage of the simple mode is ease of use.  The disadvantage
   is that it does not give you access to some of the more obscure
   SRE-Filter parameters.

    Hint: If SRE-Filter denies you access to the configurator, you should
          check the OWNERS variable (in INITFILT.80) to make sure it's
          that same as your browser's IP address.  Or, use the
          username/password that the INSTALL procedure asked you to
          supply (or did you skip that part)?

* Can I edit SRE-Filter's configuration files?

  For those who like to make their changes quickly, you may want
  to directly edit the SRE-Filter configuration files, and not
  bother with the configurator. The configuration files are
  all text (ascii) files, which you can modify with your favorite
  text edtior (such as OS/2's EPM editor).
  The most important configuration files are:
       INITFILT.80, ALIASES.IN, ALL_FILE.CTL, VIRTUAL.IN, and USERS.IN.
  INITFILT.80 is in the GoServe "working" directory (the directory you
  installed SREFILTR.80 to). By default, other configuration files are
  in the DATA/ subdirectory of the GoServe working directory.

  If you plan on editing INITFILT.80, you should read INITFILT.DOC first.
  For the other files, pay attention to comments (lines that start
  with a semi-colon) embedded in the default versions of these file -- they
  provide detailed syntax information.

*** Some more specific questions:

*  How can I control access to my site?

   SRE-Filter contains three levels of access controls:

   *) LOGON controls: a "can you get into our site" control.
   *) Directory specific: directory specific controls using  HTACCESS files.
   *) Resource specifc: "SEL-specific" access controls contained in the
      ACCESS_FILE (i.e.; data/all_file.ctl).

   Logon controls pertain to all requests.  You can tell SRE-Filter
   to check none, some, or all requests for username/password authorization
   (using the BASIC authorization scheme).

   For details on "logon controls", see the description of the CHECKLOG,
   OWNERS, INHOUSEIPS, and UNALLOWEDIPS variables in INITFILT.DOC.
   Or, check out the appropriate sections in the "simple mode" configurator.

   Of greater interest are the "directory specific" and "SEL-specific"
   access control methods.  The HTACCESS method (using code graciously
   provided by Don Meyer) uses special "HTACCESS" files located in the
   directory (and in the parent directories) of the requested file.
   This (or these) HTACCESS files contain information on who has access
   rights to files in the directory (and in child directories).

   In contrast, "SEL-specific" access controls compare the request selector
   against a list of "selectors".  This list (which may contain wildcarded
   entries) dictates who can access these selectors.  Note that, in contrast
   to HTACCESS files, there is one globally maintained list, rather then
   seperate "HTACCESS file" per directory.

        Note that we use the term "SEL-specific" to mean "Selector-specific",
        where the "selector" is the slightly-modified middle portion of
        the client's request string.
        For example, a URL of
              http://foo.bar.net/dir1/redsox.htm
        would generate a request string of
              GET  /dir1/redsox.htm  http/1.0
        which yields a selector of
                   dir1/redsox.htm
        In other words, SEL-specific access controls are
        sensitive to how you code links in your HTML documents.

   The choice of method is a matter of taste and convenience -- controlling
   directories is a sure way to prevent access to files, but controlling
   selectors is more flexible.  In fact, these two methods (SEL-specific and
   directory-specific) can be used jointly, which implies multiple checks. But
   be careful when using both methods, it is possible to get stuck in
   authorization loops!

   Since "SEL-specific" controls are native to SRE-Filter, they will tend
   to be faster.  Therefore, our recommendation is to use the SEL-specific
   method. If you do go with the "directory-specific" (HTACCESS) method, and
   you want to suppress lookup in the access control file (by setting
   ACCESS_FILE=' '), be aware that you will suppress other SRE-Filter
   options (see the description of the ALLOW_ACCESS paramter in INITFILT.DOC,
   or see the ALL_FILE.CTL file, for a description of these options).

   Lastly, to allow unhindered access to selected clients, or to a subset of
   your site, you can use INHOUSEIPS. and PUBLIC_URLS. parameters.

    *  You can circumvent access controls for selected server resources by
       by using the PUBLIC_URLS parameters.  When the client's 
       "request selector" matches a PUBLIC_URLS, access controls are not 
       attempted.

    *  INHOUSEIPS. parameters are similar to the IDENT method of
       authorization (but INHOUSEIPS. does not obtain or use
       username@ information).  Basically, if a client's IP address
       matches one of a set of "INHOUSEIPS", she is given access
       to the site (though she may still need resource/directory specific
       privileges).  Note that these INHOUSEIPS entries may contain wildcard
       characters.

    *  By the way, the simple mode configurator can be used to create,
       and remove  both INHOUSEIPS. and PUBLIC_URLS. (note that the
       PUBLIC_URLS are also called "public areas")

* How can I use selector specific access controls to control access to a
  directory?

   Since "SEL-specific" can refer to "a set of resources on your server"
   (via the use of the * wildcard), and since selectors typically point
   to directories, "SEL-specific" controls are easily used to control
   access to files in a subdirectory.

   A simple example follows:

   1) Place an entry in the access_file (e.g.; ALL_FILE.CTL) of the form
            Relative_DIR_NAME/*    A_Privilege
      For example:
             ROCKETS/*    ROCKETEERS
       (...to access selectors beginning with ROCKETS/, the client 
           must have a  ROCKETEERS  priviliege).

   2) Place an entry in the USERS_FILE (e.g.; USERS.IN) of the form:
           username  password  privilege_list
      For example:
           OBRIEN  JORDIX2  ROCKETEERS
       (.. User OBRIEN, with password JORDIX2, has a ROCKETEERS privilege).

   3) Set ALLOW_ACCESS="NO" (in INITFILT.80)
      (... SRE-Filter will check privileges for all requests).

   4) you might want to add a
         *  *
     entry to the ACCESS_FILE file to signal "all other files/directories
     are open access".

   Summarizing this example:
     When the client asks for anything in (or under) the ROCKETS subdirectory
     (of your GoServe data directory), SRE-Filter will challenge the user
     for a username and password.  If the client enters a username
     with the correct privileges (such as OBRIEN), he will be allowed entry.

   Notes:
      *  If CHECKLOG='ALWAYS', SRE-Filter will only "re-challenge"
         the client if his initial logon privileges did NOT contain a
         matching privilege.
      *  The simple mode SRE-Filter configurator can be used to add
         (and remove) both SEL-specific access controls and
         username/password entries.

* What are "client privileges" and "resource privileges" ?

    SRE-Filter uses "privileges" to provide flexibility and brevity
    when assigning (and determining)  access rights.

    "Client privileges" are assigned to clients in a variety of
    fashions (typically as part of their username/password
    authentication).  In a sense, "client privileges" can be thought of
    as shorthands for "groups of users".  In fact, one could simply
    define the client's username as a (or as the only) privilege
    (the ADD_USER_NAME variable is used for just that purpose!).

    The point is that by allowing multiple privileges per username,
    a given client can be placed in many different groups of users.

    "Resource privileges", contained in SEL-specific access
    control entries (in the ACCESS_FILE), refers to these "client privileges".
    Resource privlieges can be thought of as a list of
    "groups of users".  In the extreme case of each username
    having a single privilege (equal to her username), the "resource
    privileges" list the acceptable users!

    Advanced users note:
       The use of "SEL-specific" REALMs can further augment the
       resource privilege list.

    In comparison to the HTACCESS method:
       * The PASSWD.LST file is akin  to SRE-Filter's USERS.IN file
         (albeit one that's directory specific); but with each entry
         (in PASSWD.LST) assigned just an "own name" client privilege.
       * The GROUPS.LST file is akin to a privilege, with each entry
         in GROUPS.LST dictating which users have the "groupname" privilege.
       * There does not seem to be a corollary to the "realm specific
         resource privileges list".

* What's the difference between REALMS and privileges?

  For reasons both inertial and sensible, SRE-Filter's SEL-specific access
  control method is based on the notion of  "privileges".  Basically,
  a "client's privileges" are compared to a "resource privileges", and if
  they match (as discussed above), access is granted.

  In contrast, other servers use the notion of the REALM -- where resources
  are assigned to different REALMS on the server.  The client is then granted
  access to these realms on as-needed basis.

  So, one could think of "resource privileges" as a list of REALMS that a
  resource belongs to, and the "client privileges" as the REALMS that a client
  has access rights to.

  But the astute reader might ask: then what are SRE-Filter's SEL-specific
  REALMS?  Basically,  SRE-Filter's SEL-specific realms have two purposes:
      1) They are sent to the client's browser when authorization is requested.
         The browser will display this realm, and will cache responses by
         server/realm.
           NOTE: If no sel-specific REALM is specfied, SRE-Filter can
                 use the "1st resource privilege" as the realm name.
       2) As a shorthand for a "set of resource privileges".
         By using this shorthand, you might be able to save some tedious entry
         of long lists of "resource privileges". Note that !REALM entries in
         the access control file are used to create these  "sets of resource
         privileges".

  Perhaps we should have called the SRE-Filter SEL-specific realms  "displayed
  REALMS", or "super-Realms"?

 

* I'm still confused about these privilege things?

It's actually simpler then it reads, especially if you don't need the
fancier features. Let's sketch out a path to usefulness:
    1) Use the simple-mode configurator to add a set of users.
       For each user, you provide a username, password, and a
       list of client privileges.
    2) Use the simple-mode configurator to create "SEL-specific"
       access-control entries. For each entry you'll specify the request
       string (perhaps ending with a *), a list of resource
       privileges, and an (optional) realm.  In most cases, you'll only
       need to define one "resource privilege" per selector; and you
       can even use this one resource privilege as the realm name (see
       the description, in INITFILT.DOC, of REALM_1ST_PRIV for details).

That's all you have to do -- user's with a "client privilege" that
matches ANY ONE of a "selector's" resource privileges will be granted
access rights to it.  If they haven't entered a username/password
before hitting a protected server resource, the (optional) realm (or,
the 1st resource privilege),  will be displayed on their browser's 
authorization screen.

* How can I limit the capabilities of different users of my server?

   The use of "SEL-specific" permissions allows one to control what
   capabilities of the server are avaiable to different users.
   Of particular interest are the following permissions:
        NO_SSI : All server-side includes will be suppressed
        NO_SSP : All server side processing will be suppressed
        NO_CODE: INTERPRET CODE and SELECT keyphrases will be
                  suppressed (these are "in-document" executable
                  statements).
   Note that these permissions are applied on a "SEL-specific" basis.
   Thus, a given client may have "server side include" privileges
   on some parts of your web-site, but not on other parts.


* How can I prevent other web sites from using images stored on our server?

  If other sites are using your server to "store" files, such as interesting
  .GIFs for use as in-line images, you may find this annoying.  For example,
   you may maintain a publicly accessbile clip-art collection, which you
   are happy to give away.  However, you don't want lazy websters to
   use inline images that point to the files on your server.

   To preclude such sneaky tricks, you should use the "additional privileges"
   facility of SRE-Filter.  Basically, you  issue a short-term
   client privilege to all clients who "visit" your site (say, who
   loads up the welcome screen for your clip-art collection).
   This short-term client privilege is then required for all
   requests for the actual clip-art files.  Thus, a request coming out of
   the blue (with no prior request for  the "welcome" screen) will NOT
   be assigned the short-term privileges, and access will be denied.

   The following outlines what you need to  implement the above:
     *) Assume you have a /CLIPART directory, with lots of .GIF files in it.
    **) Assume that your "welcome to clipart" page is called
        /CLIPART/HELLO.HTM
     1) Set SRE-Filter's variables:
                 CHECK_ADD_PRIVS='YES'
                 ALLOW_ACCESS='NO'
                 ACCESS_FAIL_FILE=1
        (you will have to hand-edit INITFILT.80 to change CHECK_ADD_PRIVS
         and ACCESS_FAIL_FILE. Note that any non-0 value of ACCESS_FAIL_FILE
         will do)
     2 Add the following entries to your ALL_FILE.CTL file
          /CLIPART/HELLO.HTM *
          /CLIPART/*.GIF  !GETCLIP , , , -1
       (the -1 signals "do NOT ask for authorization in event of failure")
     3) Add the following line to /CLIPART/HELLO.HTM
           <!-- INTERPRET FILE ADDPRIVS.RXX  GETCLIP , 30 -->

   That's it!  You might want to add a * * line to ALL_FILE.CTL (assuming
   your site is otherwise open access).

   For further discussion of "dynamic privileges", see ADDPRIVS.DOC

* What are the server side include capabilities of SRE-Filter?

   A major advantage of SRE-FILTER is the ease with which a variety
   of Server Side Includes  (SSIs) can be invoked-- just by adding special
   keyphrases to your HTML document. Even better, these server side
   includes are processed recursively -- so a server side include
   can invoke further server side includes.

   SRE-Filter supports two classes of server side includes, instances of
   which can be freely intermingled in your documents:

       i) The SRE-FILTER syntax.
          The SRE-Filter syntax supports a variety of server side includes,
          such as:
            a) Inclusion of a file
            b) Inclusion of a set of "dynamic variables" (such as time/date)
            c) Inclusion of user defined "static variables"
            d) Execution of a REXX program, with inclusion of "QUEUED"
               output
            e) SPECIAL Feature: Exclusion of a portion of a document,
               based on the results of user written REXX code
            f) Headers and Footers can be added to all documents.

       ii) The NCSA HTTPD syntax.
           The NCSA HTTPD syntax is supported by SRE-Filter.  It overlaps
           largely with the SRE_Filter syntax, with a few extra file-information
           and time/date display features, and a CGI execution capacity.
           More importantly, it's something of a standard.
           For more information on the NCSA HTTPD server side includes,
           check out http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html

* What's is the SSI-Cache?

   To improve performance, SRE-Filter can "intelligently" cache
   documents that contain server-side includes.  In simple cases,
   these cached entries can be sent to the client "as is" -- relieving
   the server of the need to reprocess the "server side includes".  Needless
   to say, this can yield major performance advantages.

   The "intelligently" refers to those not-so-simple cases where the server
   side includes are "dynamic".  "Dynamic" server side includes are items that
   change over time, client, and circumstance.   A few obvious examples
   include the current time, the "number of hits", and the client's IP address.
   Obviously, one can't cache-return dynamic server side includes "as is".

   SRE-Filter solves this dilemna by "partially caching".  Basically, "static"
   includes are performed (such as file INCLUDES), and placemarkers are
   created for the "dynamic" includes.  This can substantially diminish the
   workload, especially in cases where large file include (such as a standard
   menu bar) are combined with minor dynamic includes (such as the current
   "hit"). If you are still curious, SSICACHE.HTM contains a more detailed
    discussion.


* Can I use cookies with GoServe and SRE-Filter?

   The short answer is YES -- the 'HEADER ' GoServe "return code",
   and the REQFIELD() function can be used to read and write cookies.

   SRE-Filter offers a few conveniences when processing cookies:
        *) The INTERPRET "keyphrase" of SRE-Filter provides a convenient
           means of reading and creating cookies; and of changing
           the contents of document based the values of the cookies.
        *) SREF_GET_COOKIE, a "macrospace" procedure provided with SRE-Filter,
           facilitates "cookie extraction".

   Notes:
     *  A good description of cookies can be found at:
          http://home.netscape.com/newsref/std/cookie_spec.html
     *  A short example of how SRE-Filter works with cookies can be found
        in SAMPCOOK.HTM and SAMPCOOK.RXX


* I am having trouble with uploads, what should I do?


  SRE-Filter's implementation of "file uploads" requires
  the use of an HTML document that contains a special type
  of  <FORM>. This should be constructed as:

      <FORM enctype="multipart/form-data" ACTION="/put_file" METHOD="post">
           Some stuff here:
      <INPUT TYPE="file"  name="userfile" value="filename.ext">
           More stuff
      </FORM>

  For an example of such a  document, you can look at the
 "PUT_FILE" portion of the UPLOAD.HTM file that comes with SRE-Filter.

  In addition, an HTML 3.x  aware browser (netscape 2.01 and above),
  that knows how to properly deal with such <FORM>s, has to upload this
  document.

  But before you start, you should check the following variables in
  your INITFILT.80 file (or you can use SRE-Filter intermediate mode
  configurator).

       UPLOAD_DIR :Change this to your desired "upload directory:
            Example: UPLOAD_DIR = 'g:\GOSERV\upload '

  These next are automatically set upon installation, and are probably
  okay; but you might want to check them just for fun.
        UPLOAD_MINFREE  : Minimum space (in Kbytes) that must exist on
                          your disk after upload
                 Example: UPLOAD_MINFREE= 20000

        UPLOAD_MAXSIZE  : Maximum size of file upload (in Kbytes)
                 Example: UPLOAD_MAXSIZE=1000

             UPLOAD_LOG :  Location of a "log" file, a short note on
                           recieved uploads are written here.
                 Example:UPLOAD_LOG = 'g:\GOSERV\UPLOAD\UPLOAD.LOG '

  With these setting in place, with your HTML document ready to rock
  (again, see UPLOAD.HTM for an example), and with your client running
  NetScape 2.01; everything should be ready to go!?
      That is, when the client requests this form, Netscape gives
      her a file-browse box. When the form is submitted, Netscape
      appends the file, and SRE-Filter writes it to a file name

  <Alas> GoServe seems to have intermittent problems with these uploads!
   The following settings seem to help, sometimes (as does use of
   GoServe ver 2.50):
     1) double click on the GoServe icon
     2) Select the OPTIONS  menu
     3) Select the LIMITS tab
     3) Change the Connection Maintain to some  positive value (say, 15).
        The proper value should be determined by experimentation, and
        may depend on the size of files being transfered.
     4) You may also want to go to page 2 of this tab, and change the
        "body data size" variable (to the largest size you expect to recieve).
        NOTE THAT GOSERVE SEEMS TO HAVE A 1M LIMIT ON UPLOADS.

                      >>>>>  Reviewing:   <<<<<<<

  1) Check your INITFILT.80 settings (especially the UPLOAD_DIR parameter)
  2) Create an HTML document with a special <FORM> element
     (see UPLOAD.HTM for an example)
  3) You might need to change some Goserve settings
  4) Request your html document with netscape 2.01 (other browsers
     might work.  .. but WebEx  1.1d does NOT understand this type of FORM
     element)

  By the way, UPLOAD.HTM contains a discussion on how to specify the
  filename that SRE-Filter should use when saving the file.
  You may also want to look at SREFILTR.HTM for further discussion  of
  the PUT_FILE facility of SRE-Filter.


* What about default documents?

  SRE-Filter recognizes two types of "default documents" -- those for
  "empty requests", and those for "requests to a directory".

      When an empty request arrives, the DEFAULT variable is used to indicate
      what document to return.  For example, if DEFAULT='INDEX.HTML', then
      a request for http://foo.bar.net/ would result in D:\WWW\INDEX.HTML
      being returned (assuming that D:\WWW is your GoServe default data
      directory).

      "Requests to a directory" refers to requests that mention a directory
      name, but no file. For examplem, a request for http://foo.bar.net/mule/
      refers to the "default document in the MULE subdirectory".  In order
      to find this "default document", the AUTO_NAME variable is used.
      For example, if AUTO_NAME='INDEX.HTML *.HTM ', then SRE-Filter
      would first look for MULE/INDEX.HTML, and then look for MULE/MULE.HTM.

        Note: depending on the value of the NOEXT_TYPE variable,
              a request for http://foo.bar.net/mule could also
              be interpreted as a "request for the default document
              in the MULE subdirectory"


  Consider the following examples:

      http://foo.bar.net  -- empty request; uses the DEFAULT
      http://foo.bar.net/  -- empty requests, use the DEFAULT
      http://foo.bar.net/index -- depends on the value of NOEXT_TYPE. 
          By default, SRE-Filter assumes this is a request to the "INDEX" 
          subdirectory, and will try to use look for the AUTO_NAME files
          in this INDEX subdirectory.  In the likely event that there 
          is no INDEX subdirectory, a "could not find resource" error
          message will be returned to the client.
      http://foo.bar.net/index.  --- Looks for INDEX.; which probably does not 
         exist. If it does exist, given the empty extension, SRE-Filter will 
         transfer it as  a "text/plain" file (you can change this by
         modifying MEDIATYP.RXX).

      http://foo.bar.net/index.htm   -- Looks for INDEX.HTM
      http://foo.bar.net/index.html -- Looks for INDEX.HTML

  Now let's consider the behavior of the REPLACE HITS server side include.

     Because REPLACE HITS records on a "selector specific basis", and because
     it's sort of difficult to indicate an "empty selector", SRE-Filter records
     "empty requests" using a listing of --DEFAULT--.   Let's suppose that
     DEFAULT='INDEX.HTM'. Now consider an request to INDEX.HTM -- it would be
     recorded under a listing of INDEX.HTM.  Thus, you would need to add up
     the INDEX.HTM and -DEFAULT- entries to find the true total number of
     requests that yielded INDEX.HTM.

     If this is a disagreeable notion, you might want to use REPLACE HITS_FILE
     -- it stores entries by fully-qualified file name; in the above example,
     empty requests would be stored under  D:\WWW\INDEX.HTM (assuming that D:\WWW
   is your GoServe default data directory).


* What are SRE-Filter's virtual directories?

    By default, SRE-Filter will match a request selector to a file in the 
    "GoServe data directory".  While a good security feature (files not in or
     under the GoServe data directory are inaccessible), this can be an 
     inconvenience.

    To remedy this inconvenience, one can define "virtual directories"

    Basically, SRE-FILTER will compare the starting portion of the client's
    request to see if it matches one of your virtual directory entries. If it
    does, the target directory listed in the matching entry is used
    (instead of the data directory).

    Thus, you can make available a wide, but controllable, set of
    directories (on or LAN accessible from) your server.

    Furthermore, virtual directories can point to "remote" directories on
    other http servers --  SRE-Filter will attempt to retrieve the file
    from the remote server, without using a redirection!

    For details on the use of the virtual directories, see the sample
    VIRTUAL_FILE (VIRTUAL.IN). Or, you can use the configurator!


    Note: Compared to Don Meyer's GOHTTP filter:
         * GOHTTP's use of "aliases" corresponds to SRE-Filter's use of
           "virtual directories",
         * GOHTTP's use of "redirection" (via the REDIRECT.LST files)
           corresponds to  SRE-Filter's use of "aliases".

    An example of the use of virtual directories:
         i) Assume that the Goserve data directory is D:\WWW
        ii) Assume you want to provide access to the following files;
                D:\WWW\TELLME.HTM, D:\WWW\BIRDS\PARROT.HTM,
                E:\SOUND\NATURE\CHIRP.WAV, E:\SOUND\NATURE\MORE\TWEET.WAV,
                E:\PHOTOS\SKY\FLYING.JPG
        iii) Two entries should be included in VIRTUAL.IN
                  NATURE/   E:\SOUND\NATURE*
                  PHOTOS2/   E:\PHOTOS\SKY*

         Given i,ii, and iii; the following links can be used
                 HTML anchor      ---> points to --->   file
              href="/TELLME.HTM"              D:\WWW\TELLME.HTM
              href="/BIRDS/PARROT.HTM"        D:\WWW\BIRDS\PARROT.HTM
              href="/NATURE/CHIRP.WAV"         E:\SOUND\NATURE\CHIRP.WAV
              href="/NATURE/MORE/TWEET.WAV"    E:\SOUND\NATURE\MORE\TWEET.WAV
              href="/PHOTOS2/FLYING.JPG"       E:\PHOTOS\SKY\FLYING.JPG


* How do I redirect a request?

   One of the strengths of SRE-Filter is the variety of redirection
   mechanisms it offers, where redirection implies "sending the client
   a file that is not a direct mapping of the request selector.  Redirection
   has two general classes: remote and local.

    "Remote" redirection, which  is what most of the literature simply
    calls redirection, involves telling the client's browser that
    "the url you have been requested has been moved to xxxx", where xxxx may
    be any URL  -- it need not be on the same server, and it need not have
    the same name.

    To do remote redirection, you need to add an entry to the list of aliases
    contained in the ALIAS_FILE (ALIASES.IN), either by editing with your
    favorite text editor, or by using the configurator.

    For example, an entry (in the alias-file) of
         whatgot  http://www.mine.org/dir1/index1.htm
    would cause the server to send back a "302" response to the client's
    browser whenever a request for "whatgot" arrives.  This 302 response,
    would instruct the client's browser to automatically request
          http://www.mine.org/dir1/index1.htm.


   "Local" redirection is handled solely by SRE-Filter, and involves
   directly modifying the "request selector."
   SRE-Filter has a number of methods of specifying "local redirection",
   such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the
   use of entries (in the ALIAS_FILE) of the form:
         whatgot   dir1/index.htm.
   Local redirections actually involve textual substitution (after SRE-Filter
   has recieved the request). Among other advantages, this gives you quite a
   bit of control over how "SRE-Filter facilities, and external procedures"
   percieve the request.

  Notes:

   * A CAUTION on local redirection and partial urls:
       When using aliases for "local redirection", partial URL resolution by
       the client's browser may have unexpected consequences. See the
       discussion of "local  vs remote redirection" in INITFILT.DOC for details!

   * On Using HTACCESS files for redirection:
       In addition to the use of the ALIAS_FILE, the REDIRECTFILE parameter
       of HTACCESS files can be used for "directory specific" redirections
       (see the description of the HTACCESS_FILE variable, in INITFILT.DOC,
       for more details).

    * Compared to Don Meyer's GOHTTP filter:
         * GOHTTP's use of "aliases" corresponds to SRE-Filter's use of
           "virtual directories",
         * GOHTTP's use of "redirection" (via the REDIRECT.LST files)
           corresponds to  SRE-Filter's use of "aliases".

* Can I customize SRE-Filter responses.

  In a number of circumstances, SRE-Filter will generate an error or status
  response. For example, if a request file does not exist, or if a client
  does not have access rights to a file, SRE-Filter will send a somewhat terse
  response (but at least it's not a totally terse "401 Unauthorized"
  displayed all by it's self)!

  Currently, you can customize a few of these responses (for details,
  see the descriptions in INITFILT.DOC):

     No file found:
       The NOT_FOUND_URL parameter can be assigned a
       short string, which will be displayed in the middle of a
       generic message.  Alternatively, you specify a special
       "not found" response file (typically, an HTML document
       that you create)

     Logon denied:
        SRE-Filter can either reprompt the client for a different username
        and password, or it can send her a custom written response
        file.  This file's name is set with the LOGON_FAIL_FILE.

     Access to a server resource denied:
          If a request is denied due to insufficient "SEL-specific" privileges,
          SRE-Filter can either reprompt the client for a different username,
          or it can send her a custome written response file.  This default
          name of this file is set with the ACCESS_FAIL_FILE parameter.
          In addition, you can specify "SEL-specific accesss failure response
          files" -- see the descriptions of the ACCESS_FILE (in SREFILTR.HTM,
          or in the sample ALL_FILE.CTL file) for details on this advanced
          option.

* How does SRE-Filter deal with multiple "wildcard" matches.

   When SRE-Filter attempts to match a selector to an "alias", "virtual 
   directory",  or "access control entry", it is possible that several entries
   will be "wildcard" matches.  Depending on the action, several different
   rules are used (in all cases, if an exact match exists, it's always used):

   *VIRTUAL Directories: The longest "abbreviation match" is used:
          Example: If the selector is FOOD/FRUIT/ORANGES.HTM
          and VIRTUAL.IN contains:
                /FOOD    D:\SNACKS\*
                /FOOD/FRUIT   E:\HEALTHY*
          then  the /FOOD/FRUIT entry will be used (since both match, but
          /FOOD/FRUIT is longer then /FOOD

   *ACCESS control and ALIASES: A multiple wildcard match algorithim is used.
      Example: If the selector is FOOD/FRUIT/ORANGES.HTM
     Then the following all match; with earlier entries used first.
     That is, if more then one of these entries appears in ALL_FILE.CTL,
     then the one earlier in the list is used.
                FOOD/FRUIT/*HTM
                FOOD/FRUIT/*
                FOOD/*IT/*HTM
                FOOD/*.HTM
                FOOD*
      (these entries can appear in any order in this file, with no
       effect on precedence).
 
     Furthermore, ACCESS and ALIAS matching suport "multiple replacements".
     For example, an entry (in ALIASES.IN) of:
        school/*/personal/*/pictures*  arg1=*:arg2=*
     And a request of:
        school/grade8/personal/killebrew/pictures/family.jpg
     would yield:
         arg1=grade8;arg2=killebrew
     

   * RECORDALL, and others
    A "single wildcard" algorithim is used (you can NOT include more
    then one * character).  Using the above example, the following
    entries are used (with earlier ones have precedence).
                FOOD/FRUIT/*
                FOOD/*.HTM          (more characters after the *)
                FOOD/*
      (these 4 entries can appear in any order in this file, with no
       effect on precedence).

  For further details, see the various "sample" configuration files shipped
  with SRE-Filter.

* How can I record the number of hits I get?

  SRE-Filter provides a wide variety of tools for recording the number
  of hits you recieve. These include:

     1) The RECORD_ALL_FILE. The RECORD_ALL_FILE is used to record
        the number of times ALL of your files are requested (on a
        file-by-file basis).  It does NOT record individual requests, nor
        does it place a "number of hits" line into a requested document.
        The RECORD_OPTION parameter of SRE-Filter is used to
        turn this option on or off.
     2) The COUNTER_FILE is used to record, and display, total hits
        for explicit files. The COUNTER_FILE is accessed by the
        <!-- REPLACE HITS --> SRE-Filter "server side include"
        keyphrase (there are several variants of this keyphrase).
     3) The SENDFILE_FILE is used to record files that are
        transfered with SRE-Filter's SENDFILE facility.
     4) COUNTER.RXX is used to track hits requests on a file-specific
        basis, and can record individual requests (as well as
        total requests). COUNTER.RXX  can be invoked as a server
        side include (using a <!-- INTERPRET COUNTER.RXX  xxx -->
        keyphrase), or it can be invoked by  SENDFILE.
        Lastly, the output of COUNTER.RXX is highly configurable.
     5) XCOUNT.CMD is a CGI-BIN script that generates
        a simple odometer for specific files (it's meant to be
        included as an in-line image).
        JCOUNT.CMD is similar, but is called using an
        <!-- #EXEC xxx --> style  server side include (both of
        these are courtesy of Don Meyer).
     6) The GOAUDIT.80 file contains tons of stuff, you can use it
        (but you'll have to wade through a lot of verbiage).
     7) SRE-Filter supports the common-log audit files, and there are
        lots of tools out there for analyzing common-log files.

     For details on the above choices, see SREFILTR.HTM, INITFILT.DOC, and
     COUNTER.DOC.  Power users will probably like COUNTER.RXX the best,
     (and when used with SENDFILE, COUNTER.RXX can be used with any type
     of file, not just HTML documents).

     One last point: A nice feature of the COUNTER_FILE and
     RECORD_ALL_FILE is the ability to NOT augment the counter when
     repetitive requests  (from the same client) are recieved --
     check out the descriptions of the HIT_CACHE_LEN, HIT_CACHE_DURATION,
     and HIT_OWNER_SUPPRESS variables in INITFILT.DOC
     (note that COUNTER.RXX  has similar features).



* How can I speed up throughput?

  The best way to speed up throughput is to use either the SREFQUIK
  (SREFQUIK.80) or SREFAST (SREFAST.80) variants of SRE-Filter.  
  Both SREFQUIK and SREFAST are small filters designed to process "simpler" 
  requests.  The benefits of either of these variants are especially 
  noticable under moderate to heavy loads, where their small memory 
  requirements are most important. 

  Both SREFAST and SREFQUIK require extra configuration: with the more 
  flexible SREFAST requiring  more configuration.  In general, the more
  effort you put into configuring either of these "simple filters", 
  the greater the performance gains.  
   
  The use of either SREFAST or SREFQUIK will never diminish the functionality 
  of SRE-Filter -- if SREFQUIK (or SREFAST) can't handle a request, it just 
  calls SREFILTR.80.  However,  this does add some extra overhead.  Therefore, 
  SREFQUIK (and SREFAST) are best used when you are willing to spend some
  time to configure them optimally.  In other words, haphazard use of
  either of these variants will degrade performance!

  For other speed up hints, see the introduction to INITFILT.DOC


* How do I define new MIME media types?

  If you want define a new MIME media type (or link a non-standard extension
  to a standard MIME media type), just edit the MEDIATYP.RXX file located in
  the GoServe directory (the default version of MEDIATYP.RXX contains detailed
  instructions).

  You may also wish to define a subset of the text/html files to be "server
  side include capable".  To do this, you need to set the SSI_SHTML_ONLY
  variable to 'YES', and edit the SSI_EXTENSIONS variable (at the top
  of SREFILTR.80).


* How can I prevent NetScape from reloading files too frequently?

  Certain browsers (NetScape seems to be the most stringent about this)
  are quite serious about reloading "expired" documents WHENEVER you
  refresh them.   That is, not only will such documents be loaded afresh
  upon the first request of a session, but even if you "back button" to
  it, Netscape will reload it!

  There are many cases where SRE-Filter (actually, GoServe by default) will
  return a document with an "immediate expire" (i.e.; documents
  with server side includes, and results of CGI-bin scripts).  Hence,
  this "feature" of NetScape can be quite annoying.

  To alleviate this annoyance, you can set the FIX_EXPIRE variable to
  a "time delay".  When this time delay is greater then 0, the
  expiration date will be augmented (correctly accounting for
  new-dates and GMT).  This eliminates the over zealous refresh
  activity of NetScape, but retains the "don't keep this
  temporary file around forever" notion.

  Further details are contained in the description of the FIX_EXPIRE
  variable in INITFILT.DOC.


* What are the SRE-Filter add-ons?

   As an alternative to the CGI-BIN script interface, one can
   write REXX routines that are called directly by SRE-Filter,
   without the somewhat convoluted use of environment strings
   that CGI-BIN scripts depend on.

   Currently, there are several add-ons available for SRE-Filter.
   These include:
      FORUM: A  "news-group and list-server" discussion-group package
        BBS: A full featured "web based bulletin board system"
   GETAFILE: A  directory displayer, with user-settable display features
       CALC: A character-mode scientific calculator with a web interface
   SREFPRC1: The source code for the SRE-Filter macrospace routines
   SRCHINX: A front-end (+ more) to the freeware SWISH search engine.

   Some new "SUPERUSER" additions:
     VURECORD: View the Record_all_file, with several display options
     _COMMAND: Issue OS/2 Commands to the server computer


   These add-ons can be obtained from the SRE-Filter home page at
   http://rpbcam.econ.ag.gov/srefilter.

--- End of document.
