home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / in_files.doc < prev    next >
Text File  |  1999-06-28  |  63KB  |  1,687 lines
  1. 27 June 1999. A Description of SRE-http selector-specific attribute files.
  2.  
  3.   This document details the function, structure, and syntax of 
  4.   several of SRE-http's user-configurable files; with special attention
  5.   to files that are used to set selector-specific attributes.
  6.  
  7. Table of Contents:
  8.  
  9. 1.          Introduction
  10. 1.1         A note on wildcard matching
  11. 1.2         A note on superceding hosts
  12.  
  13. 2.         The .IN files
  14.  
  15. 2.1        ACCESS.IN
  16. 2.1.i      Introduction
  17. 2.1.ii     Structure of entries
  18. 2.1.iii    Notes
  19. 2.1.iv     Examples
  20.  
  21. 2.2        ALIASES.IN
  22. 2.2.i      Introduction
  23. 2.2.ii     Structure of entries
  24. 2.2.iii    Notes
  25. 2.2.iv     Some Examples   
  26. 2.2.v      Some Cautions
  27.  
  28. 2.3        PUBURLS.IN
  29. 2.3.i      Introduction
  30. 2.3.ii     Syntax
  31. 2.3.iii    Examples
  32.  
  33. 2.4        VIRTUAL.IN
  34. 2.4.i      Introduction            
  35. 2.4.ii     Basic structure of entries  
  36. 2.4.iii    How virtual directories work 
  37. 2.4.iv     General Notes                             
  38. 2.4.v      Using the limitation_list   
  39. 2.4.vi     Specifying remote "target urls" 
  40. 2.4.vii    Match precedence     
  41. 2.4.viii   Examples
  42.  
  43. 3.         Specifying selector-specific attributes using realms
  44. 3.1        ATTRIBS.CFG
  45. 3.1.i      Introduction
  46. 3.1.ii     Syntax 
  47. 3.1.iii    Limitations
  48. 3.1.iv     Some notes on using realms and subrealms
  49. 3.1.v      Some notes on superceding realms
  50. 3.1.vi     Some examples
  51.  
  52.  
  53.                         -------------------
  54.  
  55. 1) Introduction
  56.  
  57. User-configurable, selector-specific attributes are attributes 
  58. that you (the web site administrator) may wish to set on a request-selector
  59. basis.  These include access requirements, controls on how SRE-http will 
  60. process a request, URL redirections, and other remappings.
  61.  
  62.   * Definition of "request selector:"
  63.      The "request selector" is the slightly modified middle portion of
  64.      the request string sent by a client to a server.
  65.      For example, a URL of
  66.           http://your.server/big/dance/price.htm
  67.      would generate a request string of
  68.           GET  /big/dance/price.htm  HTTP/1.0
  69.      and the selector would be
  70.           big/dance/price.htm
  71.  
  72. SRE-http supports two broad methods of specifying these selector-specific
  73. attributes: 
  74.   a) by using one of the several .IN files (ACCESS.IN, ALIASES.IN
  75.      PUBURLS.IN, and VIRTUAL.IN), or
  76.   b) by defining "realms" using the ATTRIBS.CFG file.
  77.  
  78. For several reasons we recommend use of the latter method (defining "realms"):
  79.   a) the "mime-like" structure of ATTRIBS.CFG is easier to understand
  80.      then the more idiosyncratic structure of the .IN files
  81.   b) SRE-http's use of realms mirrors how most browsers store access
  82.      information 
  83.   c) When used with CFGLIST.CFG, you can use the intermediate-configurator
  84.      to modify "port and host" specific versions of ATTRIBS.CFG
  85.  
  86. However, since the latter method (the "realms method") was introduced as 
  87. of ver 1.3f, users upgrading SRE-http may not wish to bother 
  88. translating their .IN files to the equivalent ATTRIBS.CFG entries 
  89. (even though this translation is not that complicated).
  90.  
  91. Note that both methods can be used simultaneously (technical note:
  92. they both feed into a unified database). However, to avoid 
  93. accidentally specifing contradictory attributes it is probably best to 
  94. stick to just one method.
  95.  
  96. On multi-hosts servers, both methods provide 2 means of specifying
  97. "host specific" parameters:
  98.    a) you can specify which "host" an entry is to be applied to, or
  99.    b) you can specify, in CFGLIST.CFG, auxillary files that contain entries
  100.       that will be used only with a specified host and port.
  101. Please see USE_CFGS.DOC for a description of how to specify these host
  102. and port specific files.
  103.  
  104.  
  105.  
  106.                         -------------------
  107.  
  108. 1.1) A note on wildcard matching
  109.  
  110. In many cases, SRE-http uses a "wildcard" matching algorithim
  111. to determine the best match between a request selector and 
  112. a set of entries (say, a set of possible aliases). This section
  113. describes this wildcard matching algorithim.
  114.  
  115. Match precedence and wildcarding:
  116.    Entries are checked using a "multiple wildcard" algorithim, with
  117.    multiple substitutions.
  118.  
  119.    If several entries can match the selector...
  120.      1) Exact matches always take precedence
  121.      2) The wildcard match that has the most "early character" matches wins
  122.      Thus, if your selector is FOOD/FRUIT/ORANGES.HTM
  123.      then the order (with first being chosen before last) is:
  124.                FOOD/FRUIT/ORANGES.HTM  (the exact match)
  125.                FOOD/FRUIT/*HTM
  126.                FOOD/FRUIT/*
  127.                FOOD/*IT/*HTM
  128.                FOOD/*.HTM          
  129.                FOOD*
  130.     (these entries can appear in any order in this file, with no
  131.      effect on precedence). 
  132.  
  133. Special feature:
  134.         ending the TARGET with a | means "no / or \ can be
  135.         covered by the final *".  Thus, if the selector is:
  136.             "anim/cats/food.1",
  137.         then
  138.              anim/*food.1   >> will yield a match, but
  139.              anim/*food.1|  >> will NOT yield a match 
  140.                               (since "cats/" contains a /)
  141.         The purpose of this feature is to "limit" wildcard matches to a single
  142.         subdirectory (that is, to prevent matches to items in deeper portions
  143.         of the directory tree)
  144.  
  145. Some wildcard examples:
  146.         /BILL/DOG.HTM will match /BILL/DOG.HTM
  147.         /JOE/*  will match /JOE/FOO.HTM
  148.         /JOAN/SRCH.HTM?*  will match /JOAN/SRCH.HTM?search+me
  149.         /JOAN/SRCH.HTM?*  will NOT match /JOAN/SRCH.HTM
  150.              (/JOAN/SRCH.HTM* will match BOTH these examples)
  151.         /PETS/*FOOD/*INDEX.HTM will match
  152.              /PETS/FOOD/INDEX.HTM, /PETS/CAT/FOOD/INDEX.HTM and
  153.              /PETS/PUPPY/FOOD/LAB/INDEX.HTM
  154.           but will NOT match
  155.              /PETS/CAT/PUREBRED.HTM and /PETS/FOOD/HELLO.HTM
  156.         /STORE/*.JPG|  will match
  157.                 /STORE/RADIO.JPG
  158.           but will not match
  159.                 /STORE/DEPT1/TV.JPG
  160.  
  161.                         -------------------
  162.  
  163. 1.2         A note on superceding hosts
  164.  
  165.    Entries in these user-configurable parameter files are either "host
  166.    specific" or "non-host specific". Host specific entries are only
  167.    checked for requests that are to a particular host, non-host specific
  168.    entries are used for "almost" all requests.
  169.  
  170.    SRE-http will use a "best match" algorithim (described above)
  171.    to determine which entry to use. For several of these files,
  172.    (ATTRIBS.CFG, ALIASES.IN, ACCESS.IN, and VIRTUAL.IN)  this 
  173.    algorithim is a function ofwhether the "host" (to which a request was 
  174.    directed) is a "strict-superceding", a "superceding", or a "non-superceding" 
  175.    host.  Basically,
  176.  
  177.    Strict Superceding host: 
  178.       "Host-specific" entries are checked.  Non-host specific entries 
  179.        are NOT checked.
  180.  
  181.    Superceding host: 
  182.       "Host-specific" entries are checked.  If there are ANY matching
  183.       host-specific entries, then the best matching host-specific entries
  184.       is used. If there are no matching host-specific entries, then the
  185.       non-host specific entries are checked.
  186.       In other words, if there are ANY matching host-specific
  187.       entries, the non-host specific entries will NOT be checked.
  188.  
  189.    Non-superceding hosts,
  190.       Both "host-specific" and "non-host specific" entries are checked.
  191.       The best match from this combined set of entries is used. Thus,
  192.       a non-host specific entry can be used in preference to a host-specific
  193.       entry.
  194.  
  195.  
  196. The type of host is defined by the form of the host_nickname:
  197.    a) Strict-superceding hosts have "host_nicknames" that start with a _!!
  198.       For example:  _!!TREES
  199.    b) Superceding hosts have "host_nicknames" that start with a _!
  200.       For example:  _!FOREST 
  201.    c) Otherwise, it is a non-superceding host
  202.       For example:  RURAL
  203.  
  204.  
  205. 1.2.i. An example:
  206.  
  207.  
  208.   1)  IF: _!FOREST is the  host-nickname for forest.mysite.org
  209.  
  210.   2)  AND: the following entries are defined in ACCESS.IN
  211.         _!FOREST// BBS/*   PRIV1
  212.                    BBS/AREA12/*  PRIV2
  213.                    B*  PRIV3
  214.  
  215.   3)  THEN: a request for  
  216.            http://forest.mysite.org/bbs/area12/foo.bar
  217.  
  218.   4)  WILL REQURE: PRIV1 privileges 
  219.  
  220.   5)  THIS IS BECAUSE: the 
  221.          _!FOREST// BBS/*   PRIV1
  222.       entry "supercedes" the "better matching" non-host specific entry of
  223.                    BBS/AREA12/*  PRIV2
  224.  
  225.  
  226. Or:
  227.  
  228.   1)  IF: the host-nickname was RURAL (a non-superceding host),
  229.  
  230.   2)  THEN: a PRIV2 privilege would be required 
  231.        (since BBS/AREA12/* is  a better match to bbs/area12/foo.bar).
  232.  
  233.  
  234. Or:
  235.  
  236.   1)  IF: the host-nickname was _!!TREES (a strict-superceding host),
  237.  
  238.   2)  THEN: a request for  
  239.            http://forest.mysite.org/bell/hello.txt
  240.  
  241.   3)  WILL NOT match any entries (implicitly requiring a SUPERUSR privilege)
  242.   
  243.   4) HOWEVER: if the host_nickname was RURAL
  244.   5) THEN: a PRIV3 privilege would be required, since the
  245.                    B*  PRIV3
  246.            non-host specific entry is a match.
  247.  
  248.  
  249.  
  250.                         -------------------
  251.  
  252. 2. The .IN files.
  253.  
  254. In this section, the four ".IN" files are described in detail.
  255. Note that these files can be editied using your favorite
  256. text editor, or with  SRE-http's "intermediate configurator"
  257. (/CONFIGUR.HTM).
  258.  
  259. Notes:
  260.  
  261.   * in most cases, the following descriptions can also be used for
  262.     "host and port specific .IN" files -- with the exception that
  263.     the "HOST_NICK//" parameter should NOT be used in
  264.     entries that appear in "host and port specific" files.
  265.  
  266.   * On a multi-host site:
  267.      a) host specific requests are checked first -- as may be
  268.         specified in the "default" .IN file, or in a host and 
  269.         port specific .IN file.
  270.      b) if there is no host-specific entry that matches, then the generic 
  271.         (default) entries are checked
  272.  
  273.  
  274.  
  275.                         -------------------
  276. 2.1. ACCESS.IN
  277.  
  278. ACCESS.IN is used to control access, and to assign various attributes.
  279.  
  280. 2.1.i)Introduction
  281.  
  282. The ACCESS.IN file is used to control access to your server's 
  283. resource on a selector specific basis.  This access control
  284. is based on a comparison of a client's "privileges" and the
  285. privileges assigned to a selector.
  286.  
  287. ACCESS.IN is also used to set several selector-specific attributes,
  288. including:
  289.    *) A variety of "permissions"
  290.    *) An "access failure file"
  291.    *) The realm to which this resource belongs
  292.    *) The name of an advanced options file
  293.  
  294.                         -------------------
  295.  
  296. 2.1.ii) Structure of entries
  297.  
  298. Each entry should be a space delimited list containing:
  299.   HOST_NICK// ASEL  RES_PRIVS , PERM_LIST , REALM , FAIL_FILE , ADVOPT_FILE
  300.  
  301. SRE-http will attempt to (exact or wildcard) match the request selector 
  302. with one of the ASEL fields in these entries.
  303.  
  304.  HOST_NICK//)  Optional.
  305.     Used to identify "host specific" entries.  
  306.     If a HOST_NICK is present, then the entry is only used with 
  307.     requests to hosts having this HOST_NICK "host nickname".
  308.     If a request is to a specified host (for which a HOST_NICK has been
  309.     defined); then "host-specific" entries are checked first. 
  310.     NOTE:
  311.        If the host is a "superceding host", then non-host specific entries 
  312.        are checked ONLY if no host-specific match is found.
  313.  ASEL) Required. The ASEL  should be a (possibly wildcarded) request selector
  314.    SRE-http will compare ASEL against the request selector, and
  315.    use the entry with the best-matching ASEL.
  316.  
  317.  RES_PRIVS) Optional.
  318.     The RES_PRIVS  should be a (space delimited) list.
  319.     It can contain 2 forms of "resource privileges":
  320.         ONE_OF -- the client has to have "one of" these ONE_OF privileges
  321.         MUST_HAVE -- the client "must have" all of the MUST_HAVE privileges
  322.     To specify a MUST_HAVE privilege, add a & character at the beginning.
  323.     Otherwise, it is assumed to be a ONE_OF privilege
  324.                  (in other words, ONE_OF is the default form)
  325.  
  326.     For example, the list:
  327.            SALMON &TROUT HALIBUT
  328.     means that the client must have a TROUT privilege, as well as
  329.     either a SALMON or HALIBUT privilege (note that the TROUT privilege
  330.     is necessary but NOT sufficient!)
  331.  
  332.     There are a few special "ONE_OF" privileges: *  YES and NO
  333.         YES and * mean "allow everyone in" (given MUST_HAVE privs are ok)
  334.         NO means "only superusers"
  335.  
  336.    Notes on RES_PRIVS:
  337.  
  338.      *   If there are no ONE_OF conditions, it is assumed that the
  339.          "ONE_OF conditions are automatically satisfied" (the same can be
  340.          said if there  are no MUST_HAVE conditions).
  341.      *   If a REALM is specified, and a realm-specific resource 
  342.          privilege list exists for this REALM, then it (the realm-specific
  343.          resource privilege list) will be appended to the 
  344.          "selector specific" RES_PRIVS list  (see the description
  345.          of !REALM below for details).
  346.      *   If the combination of a RES_PRIVS list, and a "realm-specific
  347.          resource privileges" list is empty (that is, neither is specified),
  348.          then access IS allowed. 
  349.          That is (assuming you never use !REALM entries):
  350.           RES_PRIVS=' ' is the same as RES_PRIVS='*'
  351.      *   If none of these entries matches the selector, and ALLOW_ACCESS
  352.          is not equal to "YES", then access is NOT allowed (SUPERUSERS
  353.          and INHOUSE users possibly excepted).
  354.      *   If the ADD_RESOURCE_NAME='YES', then the "action" portion 
  355.          of the request selector is added to the resource privilege list.
  356.      *   Caution: when including entries of the form:
  357.                SECRETS/*  ADMIN1
  358.          and NODIR_EXT='DIR', then a request generated by
  359.                 http://foo.bar.net/secrets
  360.          will NOT match the SECRETS/* .. entry.
  361.      *   See ADDPRIVS.DOC for a discussion of how client's are granted 
  362.          transient privileges.
  363.  
  364.  PERM_LIST) Optional.
  365.    The PERM_LIST is optional (there MUST be comma seperating the
  366.    RES_PRIVS and the PERM_LIST)
  367.  
  368.    Permissions are used to modify how SRE-http processes the request.
  369.    Permissions include:
  370.      NO_SSI  : Suppress server side includes.
  371.      YES_SSI  : Check HTML documents for server side includes
  372.                (this overrides NO_SSI)
  373.      NO_SSP  : Suppress server side processing.
  374.      NO_CODE : Suppress SELECT and INTERPRET CODE ssi-keyphrases.
  375.                NO_CODE is a subset of NO_SSP (that is, if NO_SSP is present,
  376.                then NO_CODE is irrelevant)
  377.      CACHE :  Always allow caching of this selector by proxies 
  378.               (and by SREPROXY)
  379.               This does NOT enable caching by the GoServe cache.
  380.     CACHE* : As above, but ALSO allow  GoServe's caching of this selector.
  381.  
  382.              If the GoServe cache is not enabled, CACHE* and CACHE 
  383.              do the same thing.
  384.  
  385.              Note: if logon controls or access controls are in place, 
  386.                    then all caching is disabled.  Use of CACHE or CACHE*    
  387.                    allows one to override this general rule.
  388.  
  389.      NOCACHE:  Do NOT cache this selector. NOCACHE overrides CACHE and
  390.                CACHE*. It also overrides PROXY_CACHE settings, but does
  391.                not override the cachable status of PUBLIC_URLs.
  392.  
  393.       PUT : Allow PUT method requests to "copy information to" the directory
  394.             represented by this selector (also used by GET_URL and PUT_FILE
  395.             facilities)
  396.     DELETE : Allow DELETE method request to "delete" the file represented by
  397.              this selector.
  398.  
  399.     NO_HTACCESS: Suppress the HTACCESS method.
  400.     NO_ALIAS   : Suppress SRE-http "aliasing."
  401.     NO_VIRTUAL : Suppress virtual directory lookup.
  402.     NO_POSTFILTER: Suppress post-filter processing (such as common-log 
  403.                   auditing, and augmentation of the SRE-http RECORD_ALL file).
  404.  
  405.    The last three (NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER) are meant
  406.    to be used to avoid unnecessary processing.  Note that NO_VIRTUAL
  407.    is ignored by CGI-BIN scripts and SRE-http addons (use the virtual
  408.    directory's limitation_lists instead).
  409.  
  410.  REALM) Optional.
  411.    (there must be a comma between the REALM and the PERM_LIST)
  412.    The REALM is optional -- it identifies which "realm" this
  413.    selector "belongs" to..  The REALM is displayed as a SEL-specific realm
  414.    whenever SRE-http needs to "re prompt" the client for a 
  415.    new username/password (as when the user's first username/password
  416.    did not contain sufficient privileges to access the selector).
  417.  
  418.    If you don't specify REALM:
  419.       * If you've set the REALM_1ST_PRIV parameter (in SREFILTR.80)
  420.         then the first resource privilege is used as the realm name
  421.       * otherwise, the THE_REALM variable (set in INITFILT.80) is used
  422.  
  423.    Semi-Obsolete:
  424.       Special !REALM entries in this file can be used to specify
  425.       "realm specific resource privileges list" (see below for details).
  426.  
  427.  FAIL_FILE) Optional.
  428.     (there must be a comma between the FAIL_FILE and the REALM).
  429.     The FAIL_FILE (sometimes refered to as the ACCESS_FAILURE_FILE)
  430.     is optional . If the client does not have sufficient privileges
  431.     (as defined by the RES_PRIVS), then the FAIL_FILE is used as 
  432.     a "response file".  
  433.     Basically, the FAIL_FILE "overrides" the ACCESS_FAIL_FILE parameter
  434.     that is set in INITFILT.80.
  435.     Note that the FAIL_FILE should be one of:
  436.               -1: If no access, do NOT ask for authorization. Useful when
  437.                   combined with "dynamic privileges"
  438.      0 or blank :  use generic access_fail_file (or send an authorization response)
  439.    filename.ext :  a fully qualified file name.
  440.  
  441.   Actually, the ACCESS_FAIL_FILE parameter can suppress use of this FAIL_FILE
  442.   -- see initfilt.doc for details.
  443.  
  444.  ADVOPT_FILE) Optional.
  445.    (you must precede it with a comma)
  446.    The ADVOPT_FILE is optional -- if you do specify it,
  447.    SRE-http allows you to specify several selector-specific
  448.    "advanced options", including:
  449.      * customization of the response header,
  450.      * execution of a rexx program before sending a file (sort of
  451.        "mid-filter" hook),
  452.      * suppression of SSI features (such as headers and footers) --
  453.      * sel specific mime type
  454.      * string replacement (used with HTML documents)
  455.    The ADVOPT_FILE should be a relative file name, though it may point to a
  456.    subdirectory (it will be interpreted relative to the the SRE-http ADDON
  457.    directory).  For more details, see ADV_OPTS.DOC
  458.  
  459.                         -------------------
  460.  
  461. 2.1.iii) Notes
  462.  
  463.  Semi-obsolete option: additional, REALM-specific, resource privileges
  464.  
  465.    We no longer recommend use of this option -- see section III
  466.    (the selector-attributes documentation) for a better way to
  467.    define "realms".
  468.  
  469.      Each realm can have associated with it a list of "realm specific 
  470.      resource privileges".  If available, this (space delimited)
  471.      list is added to the the RES_PRIVS list of all selectors that
  472.      "belong" to this realm.
  473.      The syntax of these special entries is:
  474.            !REALM  realm_name  realm_privilege_list
  475.      Note that realm_name should match a REALM specified in several 
  476.      (or one) of the sel-specific entries.
  477.      
  478.      See below for some examples of realm-specific resource privilege_lists.
  479.  
  480.      NOTE: Currently, these !realm entires are NOT host specific!
  481.            Hence, on multi host systems we HIGHLY recommend using
  482.            the  host nickname as part of the realm_name (and, hence,
  483.            in corresponding REALM fields).
  484.  
  485.   / and \ :  They are treated the same (all / are converted to \)
  486.                        A Leading \ (or /) is stripped.
  487.  
  488.                         -------------------
  489.  
  490. 2.1.iv) Examples
  491.  
  492. Only superusers have access to the SYSTEM subdirectory
  493.    SYSTEM\*   NO
  494.  
  495. Only inhouse and superusers have access to the PRIVATE directory
  496.    PRIVATE\*  INHOUSE
  497.  
  498. Everyone has access to the PUBLIC\ directory, but documents in the
  499. public directory can not contain SELECT or INTERPRET CODE keyphrases.
  500.     PUBLIC\*  * , NO_CODE
  501.  
  502. Requests, to the host with nickname SWEETSHOP, for selectors that match 
  503. RECORDS/*, requires INHOUSE privileges
  504.     SWEETSHOP//  RECORDS/*  INHOUSE , , ADMIN_REALM
  505.  
  506. The client has to have "one of" VENUS,MARS, or MERCURY privlieges,
  507. and "must have" an EARTH privilege, to access the PLANETS/INNER directory.
  508. If the client does not have these privilegs, D:\WWW\NOPLANET.HTM
  509. is returned (given that ACCESS_FAIL_FILE<>0).
  510.     PLANETS/INNER/*  MERCURY VENUS &EARTH MARS , , , d:\www\NOPLANET.HTM
  511.  
  512. Allow uploads and deletes in the Uploads directory 
  513.     UPLOADS/* * , DELETE PUT 
  514.  
  515. Wildcards all requests for getafile.  Add a privilege list if you 
  516. want to limit it's use 
  517.     GETAFILE*
  518.  
  519. These wildcard the  message box facility. Add a privilege list if desired ..
  520.    MESSAGE*
  521.    !ASKMESS*
  522.  
  523. Control access to the SECRET2 message box.
  524. All other message boxes are open to everyone with VIEWMESS privileges.
  525.     !VIEWMESS?messbox=secret2*  INHOUSE
  526.     !VIEWMESS* VIEWMESSAGES
  527.  
  528. Gives selectors pointing to the GUEST subdirectory (or virtual directory)
  529. a limited purview 
  530.     GUEST/*  * , NO_SSI NO_SSP , GUEST_REALM
  531.  
  532. Use the NEW.CTL "advanced options file" with all selectors
  533. that point to NEWSTUFF (and below). Note that there are no permissions
  534. specified, and no FAIL_FILE.
  535.    NEWSTUFF/*  * , , EXPERIMENTAL , , NEW.CTL
  536.  
  537. Allow caching of GIF files in (or under) the IMG directory; and don't bother
  538. checking aliases or the virtual directories, and don't do postfilter stuff
  539.    IMGS/*.GIF * , CACHE NO_ALIAS NO_VIRTUAL NO_POSTFILTER
  540.  
  541. Let goserve cache GIF files in (or under) the IMG directory. This is
  542. especially useful if you have NOT checked the "call filter anyways" 
  543. option of goserve (since if the filter is not called, then post 
  544. filtering etc. will not be done).
  545.    IMGS/*.GIF * , CACHE*
  546.  
  547. Give access to a clients with a privilege of MARTIANS, IONIANS
  548. or one of the privileges in the "additional resource privilege" list
  549. associated with the SPACEMEN realm (see below), access to files
  550. in the STELLAR directory
  551.    STELLAR/* MARTIANS IONIANS ,  , SPACEMEN
  552.  
  553.  
  554.  This is a catchall: "for all other files, everyone has access" 
  555.  or, you can change the second * to whatever privilege list 
  556.  you want (i.e.; NO, to disallow all access)
  557.     /* *
  558.  
  559. 2.1.iv.a) Some !REALM examples
  560.  
  561.  Note that !REALM entries can appear in any order or location in this file,
  562.  but there should only be one entry per realm_name.
  563.  
  564.  All selectors that belong to the REALM1 realm will have 
  565.  BIGFOOT and SASQUATCH added to their (possibly empty) RES_PRIVS list.
  566.  That is, the client will be allowed access (to selectors with
  567.  SEL-specific realm of REALM1) if they have a privilege
  568.  of BIGFOOT or SASQUATCH (or one the entries in the sel-specific
  569.  RES_PRIVS list).
  570.      !REALM  REALM1  BIGFOOT  SASQUATCH
  571.  
  572.  The SPACEMEN realm has "additional resource privileges" 
  573.  of: VULCANS KLINGONS and FERENGI
  574.       !REALM  SPACEMEN  VULCANS KLINGONS FERENGI
  575.  
  576.  Selectors in the  SPACEMEN2 realm requires a FEDERATION privileges as well
  577.  as "one of" the VULCANS KLINGONS or FERENGI (in addition to selector-
  578.  specific privileges)
  579.       !REALM SPACEMEN2 VULCANCS KLINGONS FERENGI &FEDERATION
  580.  
  581.  
  582.  
  583.                         -------------------
  584.  
  585. 2.2. ALIASES.IN
  586.  
  587. ALIASES.IN is used to specify internal and external redirection.
  588.  
  589.  
  590. 2.2.i)Introduction
  591.  
  592. Aliases are used to modify and transform the request selector.
  593. This includes:
  594.   Local redirection: Substituting for common "misspellings 
  595.                     and abbreviations"
  596.   Implementing searchable indices.
  597.   Remote redirection: Redirecting requests for moved URLS
  598.   Specifying "negotiable" resources
  599.  (SEMI-OBSOLETE) Setting path for CGI-BIN scripts
  600.  (SEMI-OBSOLETE) Transferring non-data-directory files.
  601.  
  602. Note: the following descriptions can also be used for "host and
  603.        port specific ALIASES.IN" files -- with the exception that
  604.       the "HOST_NICK//" parameter should NOT be used in
  605.       entries that appear in "host and port specific" files.
  606.  
  607.                         -------------------
  608.  
  609. 2.2.ii) Structure of entries
  610.  
  611.  Each line is structured as:
  612.      host_nickname//  TARGET  REPLACEMENT
  613.  where host_nickname// is optional.
  614.  Spaces should seperate these items.  
  615.  The TARGET should  have NO embedded spaes.
  616.  Note that in the TARGET, we convert / to \, and drop any leading / (or \).
  617.  
  618.   * Special feature:
  619.        if a line ends with a ' ,' (a space, then a comma)
  620.        the next line is treated as a continuation (with intervening 
  621.        spaces removed).
  622.  
  623.   SRE-http attempts to (exact or wildcard) match the request selector
  624.   with each TARGET.   
  625.  
  626.                         -------------------
  627.  
  628. 2.2.iii. Notes
  629.  
  630.   *  If a host_nickname appears, that the entry is only
  631.      used for "Hosts" that have been assigned this host_nickname.
  632.  
  633.      If the host is a "superceding host", then non-host specific entries 
  634.      are checked ONLY if no host-specific match is found.
  635.  
  636.  
  637.   *  If a match is found, the request selector is replaced by the
  638.      REPLACEMENT, with possible "wildcard substitution".
  639.  
  640.   *  "Wildcard substitution" occurs only if a * appears in the REPLACEMENT
  641.      and in the TARGET.  When this occurs, and the request selector "wildcard"
  642.      matches the TARGET, a textual substitution will occur in the REPLACEMENT.
  643.      Specifically, the * in the REPLACEMENT will be removed, and
  644.      the portion of the request selector "covered" by the * (in the
  645.      TARGET) will be inserted in it's place.
  646.      Examples, given:
  647.           Request selector: /CATS/A14.HTM
  648.               and an alias entry with
  649.           Target:  /CATS/*
  650.           Replacement: /SHOP1/PETS/FELINES/PUREBRED/*
  651.         will yield:
  652.                   /SHOP1/PETS/FELINES/PUREBRED/A14.HTM
  653.         Note that the A14.HTM in the Rquest Selector is "covered"
  654.         by the * in the Target, and is then used to "replace" the
  655.         * in the Replacement.
  656.  
  657.  * When specifying a "negotiable resource", the REPLACEMENT is optional
  658.    
  659.                         -------------------
  660.  
  661. 2.2.iv. Some Examples   
  662.  
  663.    i) Local redirection: Replace a "misspelling or abbreviation".
  664.       Example: 
  665.         INDEX INDEX.HTM
  666.  
  667.  ii) Implementing searchable indices (using SRE-http's DOSEARCH utility)
  668.     In this example, CONGRESS.DAT will be searched using the search
  669.     list returned by the client
  670.         TESTSRCH.HTM?* DOSEARCH?file=/congress.dat&searchfor=*&delim=$
  671.     If ROOTC/ is a virtual directory for  C:\USERS\, this will search
  672.     C:\USERS\JOES.LST
  673.         LOOKUSER.HTM?* dosearch?file=/ROOTC/JOES.LST&searchfor=*&delim=0
  674.  
  675.  iii) The next 4 examples perform  "remote" redirectons.
  676.    a) This (note use of a full URL, including the http://)
  677.       causes a "temporary move"  (http status code 302) redirection.
  678.          YAH* http://www.yahoo.com/
  679.    b)Specifies the same thing, but the URL that follows
  680.       need not be comletely specified (if the ip domain is left out, it is
  681.       assumed to be to be back to your server.) Of course, to be safe one
  682.       should always specify the full URL (complete with http://)
  683.            WAH* !TEMP=www.yahoo.com/
  684.    c) A "permanent" move (http code 301) otherwise it's the same as
  685.         example ii.
  686.            ZAH* !MOVED=http://www.yahoo.com/
  687.    d) A "notification of moved resource" -- client recieves a document
  688.          telling her the resource has been moved, with a link to it's new
  689.          location
  690.            JOEDIR/CV.HTM  !NOTIFY  http://college.faraway.edu/FAC/JOE/CV.HTM
  691.  
  692.  iv) Specifying a "negotiable resource"
  693.  
  694.     To specify a "negotiable resource", just enter the selector that
  695.     points to the resource, followed by the word !NEGOTIATE.
  696.     If this match occurs, the TARGET (selector) is assumed to be
  697.     a variant list, which will then be processed.
  698.     Example:
  699.          VARTEST/VAR1.LST !NEGOTIATE
  700.     (note that REPLACEMENT is not specified; instead, the word
  701.     !NEGOTIATE shoud appear)
  702.  
  703.     Alternatively, you can use a wildcarded "selector" and place the
  704.     name of the variant-list file after the !NEGOTIATE. 
  705.     Example:
  706.         MANUAL/* !NEGOTIATE  MANUAL/MANUALS.LST
  707.     would cause the "variant list" in MANUAL/MANUALS.LST to be used
  708.     for all selectors that match  MANUAL/*
  709.     Caution: If use this "wildcarded construct", the variant list MUST
  710.              contain an appropriate PATTERN: entry!
  711.  
  712.  v)  Specifying location of CGI-BIN script.
  713.      (semi-obsolote: use of a "location" before the /cgi-bin/ is
  714.      now recommended).
  715.      Example:
  716.        SCRIPT10   d:\progs\new
  717.      would instruct SRE-http to look for SCRIPT10 in d:\PROGS\NEW
  718.      (rather then the default, "cgi_bin_dir", script directory)
  719.  
  720.  vi) A host specific entry (only applies to requests to
  721.      hosts with a nickname of ZOO)
  722.      Example:
  723.        ZOO//  TIGERS    ANIMALS/FELINES/TIGERS.HTM
  724.      would only apply to request to a "host" with a ZOO host nickname.
  725.  
  726.  vii) Semi-obsolote Transfering files from anywhere 
  727.       (Semi-obsolete -- virtual directories are now recommended)
  728.       Examp;e:
  729.         GETMAP?* !TRANSFER=e:\MAPS\*
  730.     Note that this assumes that 1 argument is appended to the selector 
  731.     (say by a FORM of type GET)
  732.  
  733.                         -------------------
  734.  
  735. 2.2.v. Some cautions
  736.  
  737.  * A CAUTION  regarding unwanted aliasing:
  738.           Unless you explicitly want to "alias" actual files, directories,
  739.           or "server side program" names...
  740.                  we HIGHLY RECOMMEND that all entries in this file
  741.                  have "targets" that do NOT MATCH pre-existing files,
  742.                  directories, or "actions".
  743.          {and be especially careful if you are using any wildcard matches)
  744.  
  745.  * A CAUTION on local redirection and partial urls:
  746.       When using aliases for "local redirection", URL resolution by the
  747.       client's browser may have unexpected consequences. See the discussion 
  748.       of "local  vs remote redirection" in INITFILT.DOC for details!
  749.  
  750.                         -------------------
  751.  
  752. 2.3. PUBURLS.IN
  753.  
  754. PUBURLS.IN is used to specify publically accessible" resources.
  755.  
  756.  
  757. 2.3.i) Introduction
  758.   
  759. PUBURLS.IN is used to identify  public-urls: which are defined as
  760. resources for which access (and logon) controls are not imposed.  
  761.  
  762.     * See PUBURLS.DOC for a complete description of public-urls. 
  763.  
  764. 2.3.ii) Syntax
  765.  
  766. The basic syntax of entries is:
  767.    host_nickname// candidate_sel  anoption filename
  768. where:
  769.     host_nickname is an (optional) host nickname
  770.     candidate_sel is compared against the request selector
  771.     anoption can be: LITERAL LITERAL_NORECORD or NORECORD
  772.     filename is a fully qualified file name (with possible * "wildcard 
  773.     characters")
  774. (anoption and filename are both optional)
  775.  
  776. 2.3.iii) Examples
  777.  
  778.      INDEX.HTM
  779.      MAPS/* 
  780.      STORE/AD1.HTM  LITERAL 
  781.      STORE/*.GIF  NORECORD 
  782.      PICTURE/HELLO.GIF  LITERAL_NORECORD  D:\PICTS\HELLO.GIF
  783.      ZOO// HOURS.HTM LITERAL
  784.  
  785.  Notes
  786.    * LITERAL_NORECORD implies "let goserve cache this" 
  787.        (assuming the goserve cache is enabled)
  788.    * Requests to host ONLY match host specific entries, That is,
  789.      non-host specific entries WILL NOT match requests to 
  790.      "hosts" (for which a host_nickname is defined).
  791.    * Public URLS with a LITERAL_NORECORD attribute may be cached
  792.      by the GoServe cache.
  793.  
  794.  
  795.                         -------------------
  796.  
  797. 2.4. VIRTUAL.IN
  798.  
  799. VIRTUAL.IN is used to specify virtual directories. 
  800.  
  801.  
  802. 2.4.i) Introduction            
  803.  
  804. Virtual directories are used to allow access to files not in a default 
  805. directory. The typical use is to allow requests for documents to be 
  806. in a subdirectory  NOT under the "GoServe data directory".
  807.  
  808. VIRTUAL.IN can also be for several other reasons, including:
  809.      specifying the location of a  cgi-bin script
  810.      specifying the location of an sre-http add-on
  811.      specifying where an uploaded file should be placed
  812. Lastly, for some cases, virtual directories can be used to allow server
  813. mediated access to files on other (remote) servers.
  814.  
  815.                         -------------------
  816.  
  817. 2.4.ii) Basic structure of entries  
  818.  
  819. Each line in VIRTUAL.IN should have the following structure:
  820.      host_nickname//  SEL_fragment  TARGET  limitation_list , username:pwd
  821. where:
  822.    * host_nickname// is optional
  823.    * SEL_fragment is the "beginning portion" of a request selector
  824.    * TARGET can be a (local) fully qualified directory or a
  825.                     (remote) fully specified URL
  826.    * the [optional] limitation_list is used to limit the applicability of 
  827.      the entry.
  828.      If present, it should be a spaced  delimited list. It's use is 
  829.      described below.
  830.    * the [optional] username:password is ONLY used for remote 
  831.      (http://) directories
  832.  
  833.                         -------------------
  834.  
  835. 2.4.iii) How virtual directories work 
  836.  
  837. The SEL_fragment is compared to the beginning of the request selector 
  838. (the selector).  If an "abbreviation" match occurs, the
  839. "fragment" is removed from the "request selector"
  840. and replaced with either the (local) target "directory" OR the
  841. (remote) target "URL".  The limitation_list (if present) is used to
  842. control which entries are used, based on whether the request is asking 
  843. for a document, a server side program, or an upload (see section V below 
  844. for details).
  845.  
  846.  [If this is confusing, the examples in 2.4.vii should help.]
  847.  
  848.   
  849.                         -------------------
  850.  
  851.                               
  852. 2.4.iv) General Notes                             
  853.  
  854.    * If  no match is found, a "default directory" is used.  
  855.      In the typical case of a document request on a single host server, 
  856.      the default directory is the GoServe data directory.
  857.  
  858.    * If the host is a "superceding host", then non-host specific entries 
  859.      are checked ONLY if no host-specific match is found.
  860.  
  861.  
  862.    * The limitation list can be used to limit the "scope" of the entry.
  863.      In particular, the "default directory"  must match  one of the entries
  864.      in the limitation list.  If there is no limitation_list, the entry will
  865.      be used for all requests.
  866.  
  867.    *  An asterisk (*) at the end of  directory name means "allow access to 
  868.       subdirectories". Note that you should NOT place an asterisk at
  869.       the end of the SEL_FRAGMENT
  870.  
  871.    *  Leading and trailing slashes in the SEL_fragment are ignored, and
  872.       / and \ are treated equivalently.  Similarly, trailing slashes in
  873.       the TARGET directory are ignored.
  874.       Thus, the following are all equivalent:
  875.           foobar1/   d:\foobar\*
  876.           foobar1    d:\foobar*
  877.           \foobar1\  d:\foobar*
  878.  
  879.    *  If a Drive is not specified in the TARGET (local) directory, the drive 
  880.       that SRE-http is installed on will be used.
  881.  
  882.    *   WARNING: The use of "REMOTE urls" is ONLY supported for document 
  883.                 requests. It is NOT supported for "server side include" 
  884.                 files, such as specified in the INCLUDE and INTERPRET 
  885.                 SSI keyphrases. Nor is it supported for server side programs,
  886.                 or upload, requests.
  887.  
  888.    * CAUTION:  The NO_VIRTUAL permission (in ACCESS.IN) suppresses
  889.                the use of VIRTUAL directories. That is, when a selector
  890.                matches an ACCESS.IN entry that contains a NO_VIRTUAL
  891.                permssion, the information in this file will NOT be examined!
  892.  
  893.  
  894.                         -------------------
  895.  
  896. 2.4.v) Using the limitation_list   
  897.  
  898.    The limitation_list is used to limit the applicability of a virtual 
  899.    directory entry. For example, you may wish to have some virtual 
  900.    directories apply only to document requests, and some only to upload 
  901.    requests. 
  902.    The limitation_list (if present) should contain any mixture of the 
  903.    following special keywords:  !UPLOAD, !CGI-BIN, !ADDONS, and !HTML. 
  904.         !HTML    --- use this entry for document requests
  905.         !CGI-BIN --- use this entry for cgi-bin requests
  906.         !ADDONS  --- use this entry for sre-http addons
  907.         !UPLOAD  --- use this entry for file uploads
  908.    Note that more than one of these keywords can appear in this
  909.    "space delimited" limitation list.  Including all four entries is
  910.    the same as not having a limitation list: the entry will be
  911.    used for all requests.
  912.  
  913.    For example:
  914.       scdemo d:\netdata\macros\scdemo !cgi-bin
  915.       scdemo d:\netdata\html\scdemo   !html
  916.    The first entry will be used when a request for a cgi-bin script arrives
  917.         (i.e.; scdemo/cgi-bin/scinit.cmd
  918.    The second will be used for document requests  
  919.         (i.e.; scdemo/foo1.htm)
  920.  
  921.                         -------------------
  922.  
  923.  
  924. 2.4.vi) Specifying remote "target urls" 
  925.  
  926.     i) the http:// MUST be present (otherwise SRE-Http assumes you
  927.         are referring to a local directory name)
  928.     ii) conversion of  / does NOT occur for these entries
  929.    iii) the trailing * option is supported
  930.     iv) This is NOT a redirect! Rather, SRE-Http will retrieve the file
  931.         represented by this URL (on a remote server), strip out the
  932.         response headers, and treat it as if it came from a local directory.
  933.     vi) If you specify a username & password (after a comma), a
  934.         BASIC authorization request header will be added with this 
  935.         username & password. Otherwise, the client's username & password 
  936.         is used (if it is available)
  937.  
  938.                         -------------------
  939.  
  940. 2.4.vii)  Match precedence     
  941.  
  942.   Unlike most other SRE-http files, match precedence for virtual directories
  943.   is based on "abbreviation" matching, not "best matching".  That is,
  944.   * wildcards should not be in the SEL_FRAGMENT.  Instead, SRE-Http simply
  945.   uses the longest SEL_FRAGMENT that is an "abbreviation" for the request
  946.   selector.
  947.  
  948.  
  949.                         -------------------
  950.  
  951. 2.4.viii) Examples
  952.  
  953. Two examples of "subdirectory access is allowed):
  954.   (if a selector of: /LOCAL/PROJECTS/BOB/PLANE.HTM is recieved, the file
  955.   returned will be D:\WORK\PROJECTS\BOB\PLANE.HTM)
  956.       LOCAL/PROJECTS     D:\WORK\PROJECTS*
  957.  
  958.   Note: If the * is removed, /LOCAL/PROJECTS/BOB/PLANE.HTM would generate
  959.           a "no access allowed" error (since access to subdirectory BOB, 
  960.           under WORK\PROJECTS, would not be allowed).
  961.  
  962.   (D:\work, with subdirectory access allowed)
  963.       D\work D:\WORK\*
  964.  
  965.  
  966. Two examples of "no subdirectory allowed access"
  967.   (a selector of STATES/AG.HTM would be valid,(and would
  968.   return D:\USA\MAINE\AG.HTM)
  969.     STATES   D:\USA\MAINE
  970.  
  971.   (temp on C:, but NO subdirectory access)
  972.     CTEMP C:\temp
  973.  
  974. Three examples of a remote target URL:
  975.  (a selector of SERVER2/CANADA.HTM will cause SRE-Http to request
  976.  /support1/canada.htm from pc2.myorg.net)
  977.     SERVER2 http://pc2.myorg.net/support1/
  978.  
  979.  (get from the EXPORT directory (and directories underneath EXPORT)
  980.  on the server at www.ours.org)
  981.     SITE2 http://www.ours.org/export/*
  982.  
  983.  (remote request to a server, using your server's username:password)
  984.     special\  http://server2.hissite.org/grate/stuff/* , specialask:ernie
  985.  
  986. An example of a host-specific entry:
  987.   (requests, to hosts with host_nickname of SWEETSHOP, that have
  988.   selectors beginning with CANDY refer to files in
  989.   E:\STORE1\PRODUCTS\CANDY and it's subdirectories).
  990.      SWEETSHOP//  CANDY   E:\STORE1\PRODUCTS\CANDY\*
  991.  
  992. Two examples of limitation lists:
  993.   (the !addons signals that the ACTION2 "virtual directory" will only
  994.   be used for requests for sre-http add-ons).
  995.       ACTION2 e:\programs\task1  !addons
  996.  
  997.    For example:
  998.       /action2/getafile?dir=foodir1
  999.          E:\programs\task1\GETAFILE.CMD is executed (as an SRE-Http add-on)
  1000.       /action2/gogo.htm
  1001.          D:\www\action2\gogo.htm would be returned (assuming that the 
  1002.          GoServe data directory is D:\www)
  1003.   
  1004.  
  1005.   (the D:\project1 directory (and subdirectories) contain html documents, 
  1006.   and sre-http add-on procedures)
  1007.    project1   d:\project1*  !HTML !ADDONS
  1008.  
  1009.  
  1010.                         -------------------
  1011.  
  1012. 3.          Specifying selector-specific attributes using realms
  1013.  
  1014.  ATTRIBS.CFG is used to set selector-specific attributes, using 
  1015.  a "realm-architecture". In addition, ATTRIBS.CFG can be 
  1016.  used to specify user/passwords, and to specify replacement strings.
  1017.  
  1018.                         -------------------
  1019.  
  1020. 3.1.i)Introduction
  1021.  
  1022. ATTRIBS.CFG supplements (or replaces) several user-configurable
  1023. ".IN" files used by SRE-http. These are ACCESS.IN, ALIASES.IN, 
  1024. PUBURLS.IN, REPSTRGTS.IN, USERS.IN, and VIRTUAL.IN (note that prior
  1025. to ver 1.3f, ACCESS.IN was named ALL_FILE.CTL). 
  1026.  
  1027. Four of these ".IN" files (ACCESS.IN, ALIASES.IN, PUBURLS.IN,
  1028. and VIRTUAL.IN) are used to set "selector-specific" attributes 
  1029. (see section 2. for the details).  ATTRIBS.CFG integrates
  1030. these four files using a "realm-architecture"; an architecture 
  1031. that matches how the WWW is organized, and should be easier to
  1032. work with.
  1033.  
  1034.  
  1035. The basic idea of this "realm-architecture" is:
  1036.   1) a server's resources (documents, images, scripts, etc.)
  1037.      can be sorted into "realms"
  1038.   2) each of these "realms" may have numerous "sub-realms"
  1039.   3) access to your server's resources can be defined on a "realm" specific
  1040.      basis --  a given client can be granted access to resources in only
  1041.      a subset of your server's "realms".
  1042.   4) other attributes, such as redirection instructions, and 
  1043.      customization of how sre-http will process the request, can
  1044.      be defined on a subrealm basis
  1045.   5) A realm, or a sub-realm, can contain:
  1046.       *) one resource  (a single selector), or
  1047.       *) set of similarly named resources (a single, wildcarded
  1048.          selector), or
  1049.       *) several similarly named resources
  1050.  
  1051.  
  1052.                         -------------------
  1053.  
  1054. 3.1.ii) Syntax 
  1055.  
  1056. Entries in ATTRIBS.CFG consist of a block several "mime-like" lines, 
  1057. ending with a blank line. Each "mime-like" line has the following structure:
  1058.    action: options 
  1059.  
  1060. Briefly, the following lists (in alphabetical order) the available "actions."
  1061.  
  1062.   advopt_file -- specify an advanced options file
  1063.   failure    -- specify an access failure file
  1064.   host       -- specify which host this entry is to be used for
  1065.   include    -- include a host/port specific set of entries
  1066.   permissons -- specify sre-http "permissions"
  1067.   port       -- specify which server port this entry is to be used for
  1068.   realm      -- the realm (subrealm) name of this entry (REQIURED)
  1069.   redirect   -- url redirection, or virtual directory assignment
  1070.   requires   -- resources privileges needed for access 
  1071.   rule       -- selectors (possibly *'ed) to assign to this realm (REQUIRED)
  1072.   replace    -- specify a replacement variable
  1073.   with       -- specify a replacement string (used with REPLACE)
  1074.   user       -- specify a user name
  1075.   pwd        -- specify a password (used with USER)
  1076.   privs      -- specify client privileges (used with USER)
  1077.  
  1078. Note that a "block" must contain one of:
  1079.   INCLUDE -- an "include file" block
  1080.   REALM and RULE -- a "realm definition"
  1081.   REPLACE and WITH -- a "replacement rule
  1082.   USER and PWD -- a username/password 
  1083.  
  1084.  
  1085. The following describes these actions in greater detail:
  1086.  
  1087.  
  1088. advopt_file: 
  1089.  
  1090.  Specify an "advanced" options file.
  1091.  
  1092.  Syntax:
  1093.    advopt_file: file_name
  1094.  
  1095.  file_name should be a relative file name (it will relative to the
  1096.  SRE-http ADDON directory). For more details on advanced options files,
  1097.  please see section 2.1.ii, or see ADV_OPTS.DOC
  1098.  
  1099.  
  1100.  Notes:
  1101.    * advopt_file complements the option action
  1102.    * you can use ADV as an abbreviation for ADVOPT_FILE
  1103.  
  1104.  
  1105.  
  1106. failure: 
  1107.  
  1108.   Specify an "access failure file"
  1109.  
  1110.   Syntax:
  1111.     failure: file_name
  1112.  
  1113.   file_name should be a fully qualified file name, or a special
  1114.   code -- see the discussion of FAIL_FILE in section 2.1.ii for
  1115.   further discussion of access failure files.
  1116.  
  1117. host:
  1118.   The "host nickname" of the host this entry applies to
  1119.  
  1120.   Syntax:
  1121.     host: host_nickname
  1122.  
  1123.   If not specified, the entry will be used for all requests -- such
  1124.   entries are assumed to refer to a "default" host. 
  1125.  
  1126.   For redirect and requires:
  1127.     If the host is a "superceding host", then non-host specific entries 
  1128.     are checked ONLY if no host-specific match is found.
  1129.  
  1130.  
  1131.   Note: If you are running a single host site, you do NOT need to use 
  1132.         host:
  1133.  
  1134. include:
  1135.  
  1136.  Include a file of entries, to be assigned to a single host and port.
  1137.  
  1138.  Syntax:
  1139.     include:  file_name
  1140.  
  1141.  file_name should be a fully qualified filename 
  1142.  
  1143.  The include: action is special -- when it appears in an entry,
  1144.  only host: or port: actions are used, all other actions are ignored.
  1145.  
  1146.  Files "included" should look have the same structure as ATTRIBS.CFG,
  1147.  with one exception -- host: and port: actions should not be included
  1148.  (actually, they can be included, but they will be ignored).
  1149.  
  1150.  Basically, the main purpose for include: is to allow each "host"
  1151.  to have it's own configuration file.  This provides an alternative
  1152.  to the use of host: (and port:) actions.
  1153.  
  1154.  Note that you can also use CFGLIST.CFG to specify "host & port
  1155.  specific ATTRIBS entries".
  1156.  
  1157.  
  1158. limitlist:
  1159.  
  1160.   Specify a "limitation list". This limitation list is used with
  1161.   redirect: dir=.
  1162.   There are four valid values that can appear in the limitation list:
  1163.   !HTML, !CGI-BIN, !ADDONS, and !UPLOAD.
  1164.   See section 2.4.v for the details on limitation lists.
  1165.   Example: limitlist: !HTML
  1166.  
  1167.   Note: not specifying a limitlist is the same as specifying all
  1168.         four of these values.
  1169.  
  1170.  
  1171. option:
  1172.   Specify an advanced option
  1173.  
  1174.   Syntax:
  1175.     option: an_advanced_option
  1176.  
  1177.   The advanced_option can be any of the SRE-http advanced options,
  1178.   as described in ADV_OPTS.DOC.
  1179.  
  1180.   You can specify multiple option: lines -- with one option per 
  1181.   line.
  1182.  
  1183.   Examples:
  1184.     option: set fix_expire 0.5
  1185.     option: ssi_no_footer
  1186.     option: REPLACE_RULES=</HEAD>==<BASE href="http://www.x.org"></HEAD>
  1187.  
  1188.   Note that option: complements advopt_file
  1189.  
  1190. permissions:
  1191.  
  1192.  Specify the "permissions" to use for selectors that belong to this realm.
  1193.  
  1194.  Syntax:
  1195.     permisson:  permission_list  
  1196.  
  1197.   permission_list is a spaced delimited list of SRE-http "permissions".
  1198.   Currently available permissions include:
  1199.       NO_SSI     YES_SSI       NO_SSP      NO_CODE      CACHE   
  1200.       CACHE*     PUT           DELETE     NO_HTACCESS    NO_ALIAS   
  1201.       NO_VIRTUAL NO_POSTFILTER  
  1202.  
  1203.   For details on how to use permissions, see the discussion of
  1204.   PERM_LIST in section 2.1.ii                 
  1205.  
  1206.  
  1207.   Notes:
  1208.  
  1209.     * Sub-realms can inherit the PERMISSIONS values of their parent
  1210.       subrealm (or grandparent, etc.).
  1211.  
  1212.     * The NO_POSTFILTER permission, when used with a PUBLIC realm,
  1213.       is equivalent to specifying a NORECORD (or LITERAL_NORECORD)
  1214.       attribute in a PUBURLS.IN entry (see 2.3.iii for details)
  1215.  
  1216. port:
  1217.   
  1218.   Specify which port this entry applies to.
  1219.  
  1220.   Syntax:
  1221.      port: nnn
  1222.  
  1223.   where nnn is the port number your server is running on.
  1224.   If a port: entry does not appear, the default (80) is
  1225.   assumed.
  1226.  
  1227.   If you always run your web server on the standard http port (port 80),
  1228.   then you will never need to use port:
  1229.  
  1230.  
  1231. privs:
  1232.  
  1233.    Specify  user (client) privileges
  1234.  
  1235.    Syntax:
  1236.        privs: privlist
  1237.  
  1238.    Specify a set of "client privileges" to be assigned to a user.
  1239.    You MUST also specify  a username and a password 
  1240.   (using the user: and pwd: actions).
  1241.  
  1242.    Privlist is a space delimited list of privileges.  
  1243.      * "secret" privileges should start with a ?.
  1244.      * see USERS.DOC for details on replacement rules.
  1245.      * you can specify host and port usernames (using
  1246.        the HOST: and PORT: actions)
  1247.  
  1248.  
  1249. pwd:
  1250.  
  1251.    Specify a password
  1252.  
  1253.    Syntax:
  1254.        user: a_password
  1255.  
  1256.    Specify a password for a user of site.  You MUST also specify
  1257.    a username (using the user: action).
  1258.  
  1259.      * a_password may be case sensitive  (depending on the authorization
  1260.        mechanism used by the client)
  1261.      * the PRIVS: action is also used with user: and pwd:
  1262.      * see USERS.DOC for details on replacement rules.
  1263.      * you can specify host and port usernames (using
  1264.        the HOST: and PORT: actions)
  1265.  
  1266.  
  1267. replace: xxx
  1268.      
  1269.   Specify a replacement rule. 
  1270.  
  1271.   Syntax:
  1272.      replace: xxx
  1273.  
  1274.   Replacement rules are used with <!-- REPLACE xxx --> server side includes.  
  1275.  
  1276.   Notes:
  1277.      * replace MUST be used in conjunction with a WITH: action
  1278.      * see REPSTRGS.DOC for details on replacement rules.
  1279.      * you can specify host and port specific replacement rules (using
  1280.        the HOST: and PORT: actions)
  1281.  
  1282. realm: 
  1283.  
  1284.  The realm_name, or realm_name plus subrealm_name, idenfies this "entry". 
  1285.  
  1286.  Syntax:
  1287.       realm: realm_name C
  1288.   or                   
  1289.       realm: realm_name.subrealm_name C
  1290.  
  1291.   Notes:
  1292.     * PUBLIC is a "special" realm_name --  it signifies "open access" 
  1293.       resources
  1294.     * In order to define a subrealm, you MUST define it's  "main realm" 
  1295.     * Subrealms can be more then 1 deep. Thus, FOO.BAR.UP is legitimate.
  1296.  
  1297.     * When SRE-http returns an authorization request to a client,
  1298.       it will use the "main realm". For example, if a request
  1299.       matches R1.S3.T4, then R1 is the realm reported to the client.
  1300.  
  1301.     * the C is optional. If present, this realm (or realm.subrealm) is
  1302.       a "superceding" realm. Otherwise, it is a normal realm (see
  1303.       section 3.1.v for a discussion of superceding realms)
  1304.     
  1305.                            
  1306. requires:
  1307.  
  1308.   Identify the resource privileges a client needs to access this realm.
  1309.  
  1310.   Syntax:
  1311.       requires: priv_list
  1312.  
  1313.   priv_list is a space delimited list of "resource privileges".
  1314.  
  1315.   Note that subrealms MUST inherit the "resource privileges" of their
  1316.   main realm -- you can not specify different sets of resource
  1317.   privileges for different subrealms under the same "main realm"
  1318.  
  1319.   Thus:  requires can NOT be used in subrealm entries!
  1320.  
  1321.   For further discussion of "resource privileges", see the discussion of
  1322.   RES_PRIVS in section 2.1.ii.
  1323.  
  1324.  
  1325.   Notes:
  1326.    *  For the PUBLIC realm, REQUIRES is ignored (an implicit REQUIRES: *
  1327.       is used).
  1328.    *  Reiterating: Sub-realms inherit the REQUIRES values of their
  1329.       parent realm.  You can NOT set sub-realm specific REQURES
  1330.  
  1331.  
  1332. redirect:
  1333.  
  1334.  Redirect or redefine a request
  1335.  
  1336.  Syntax
  1337.    redirect: mode = xxx
  1338.  
  1339.   mode can be:
  1340.  
  1341.    dir      -- a "virtual directory". XXX is  a fully qualified
  1342.                directory. It can contain one wildcard at the end.
  1343.                For more details, please see the dicussion of virtual 
  1344.                directories in section 2.4.
  1345.  
  1346.    internal -- "an alias". XXX is a selector, which can 
  1347.                 contain multiple wildcard (*) characters.
  1348.                 For more details, please see the discussion of "local
  1349.                 redirection" in section 2.2.
  1350.    literal  -- a "literal" transfer.  XXX is a fully qualified
  1351.                file name, which can contain multiple wildcard (*) characters.
  1352.                When used with a PUBLIC realm, literal is equivalent to
  1353.                using a LITERAL (or LITERAL_NORECORD) modifier in
  1354.                a PUBURLS.IN entry (see section 2.3.iii)
  1355.                Otherwise, LITERAL is equivalent to using a !TRANSFER=xxx
  1356.                in an ALIASES.IN entry  (see section 2.2.iv for the details)
  1357.   negotiate -- identifies a "negotiable resource". This resource contains
  1358.                content-negotiation information.  XXX is usually empty,
  1359.                but in certain cases it can point to a special listing
  1360.                file. See 2.2.iv for details on content-negotiation.
  1361.    perm     -- "a permanent redirection" (301). XXX is a local or
  1362.                fully qualified URI. It may contain mulitple wildcards. 
  1363.                For more details, please see the discussion of external 
  1364.                redirection in section 2.2.
  1365.    temp     -- "a temporary redirection" (302). XXX is a local or
  1366.                fully qualified URI. It may contain mulitple wildcards
  1367.                For more details, please see the discussion of external 
  1368.                redirection in section 2.2.
  1369.  
  1370.  Reirect notes:
  1371.     * There can be at most ONE (or none) redirect: actions per entry.
  1372.     * The url in a redirect: perm (or redirect: temp) can be local,
  1373.       or it can be fully specified (starting with http://).
  1374.    * The following synonyms can be also be used:
  1375.         ALIAS: xxx     instead of  REDIRECT: INTERNAL = xxx
  1376.         LITERAL: xxx   instead of  REDIRECT: LITERAL= xxx
  1377.         VIRTUAL: xxx   instead of  REDIRECT: DIR=xxx
  1378.         MOVE: xxx      instead of  REDIRECT: PERM=xxx
  1379.         TEMPMOVE: xxx  instead of  REDIRECT: TEMP = xxx
  1380.  
  1381. rule:
  1382.  
  1383.   Specify matching rules for idenfitying selectors that belong to this realm.
  1384.  
  1385.   Syntax:
  1386.      rule: a_selector
  1387.   
  1388.   a_selector may contain multiple wildcard (*) characters. Some
  1389.   simple examples include:
  1390.     rule: /xxx/yyy/foo.htm
  1391.     rule: /zzz/*         
  1392.  
  1393.   Note that one can define rule: several times within a single entry --
  1394.   multiple rule actions are cumulative. Thus, several different
  1395.   "selector matching rules" can be used to identify resources
  1396.   belonging to a given realm (or to a given subrealm)
  1397.  
  1398.   Please see section 1.1 for a discussion of how SRE-http uses
  1399.   wildcards when "matching selectors to a rule".
  1400.  
  1401.  
  1402. user:
  1403.  
  1404.    Specify a user.
  1405.  
  1406.    Syntax:
  1407.        user: username
  1408.  
  1409.    Specify a username for this site.  You MUST also specify
  1410.    a password (using the pwd: action).
  1411.  
  1412.      * the PRIVS: action is also used with user: and pwd:
  1413.      * see USERS.DOC for details on replacement rules.
  1414.      * you can specify host and port usernames (using
  1415.        the HOST: and PORT: actions)
  1416.  
  1417. with:      
  1418.  
  1419.   Specify the string used in a replacement rule. 
  1420.  
  1421.   Syntax:
  1422.      with: a string 
  1423.  
  1424.   Replacement rules are used with <!-- REPLACE xxx --> server side includes.  
  1425.   "A string" can be a string of any length; it can contain html entities
  1426.    and spaces.
  1427.  
  1428.   Notes:
  1429.      * replace MUST be used in conjunction with a REPLACE: action
  1430.      * see REPSTRGS.DOC for details on replacement rules.
  1431.      * you can specify host and port specific replacement rules (using
  1432.        the HOST: and PORT: actions)
  1433.  
  1434.  
  1435.    
  1436.                         -------------------
  1437.  
  1438. 3.1.iii) Limitations
  1439.  
  1440.  The following "selector-specific" attributes can NOT be set
  1441.  using ATTRIBS.CFG, but can be set using one of the ".IN" files
  1442.  (filenames in parenthesis indicate where these can be set):
  1443.  
  1444.     i) location of a cgi-bin script (ALIASES.IN)
  1445.    ii) specifying a "remote" virtual directory (VIRTUAL.IN)
  1446.   iii) multi-line replacements (REPSTRGS.IN)
  1447.  
  1448.                         -------------------
  1449.  
  1450. 3.1.iv) Some notes on using realms and subrealms
  1451.  
  1452.   Underlying the logic of the "realm" and "subrealm" architecture
  1453.   is that browsers store authorization information by
  1454.   "realm within a host" (host being a named IP address).
  1455.  
  1456.    * When SRE-http returns an authorization request to a client,
  1457.       it will use the "main realm". For example, if a request
  1458.       matches R1.S3.T4, then R1 is the realm reported to the client.
  1459.  
  1460.   SRE-http mirrors this fact by forcing all "subrealms" of a "realm"
  1461.   to have the same set of "resource privileges".  
  1462.   Thus, sub-realms are used primarily to specify other attributes, such
  1463.   as redirections and permissions.
  1464.  
  1465.   In particular, permissions are defined recursively; if no permissions
  1466.   were granted a subrealm, it will search "down the realm/sub-realm tree"
  1467.   for a set of permissions.
  1468.   
  1469.   For example, suppose the  FOO, FOO.BAR, and FOO.BAR.UP have been
  1470.   defined. FOO is the "main realm", and FOO.BAR and FOO.BAR.UP are
  1471.   subrealms of FOO.  Suppose that FOO was defined with no permissions,
  1472.   FOO.BAR with the NO_SSI and NO_VIRTUAL permissions, and FOO.BAR.UP
  1473.   with no permissions. Then, FOO.BAR.UP will "inherit" the
  1474.   permissions of FOO.BAR (in this case, NO_SSI and NO_VIRTUAL)
  1475.   However, FOO will NOT "inherit" these permissions, since FOO is "lower"
  1476.   in the tree then FOO.BAR.
  1477.  
  1478.   Note that "redirections", "failure files", and "advanced options" are
  1479.   NOT inherited -- you have to explicitly define them when needed.
  1480.  
  1481.   One useful trick is to have a "dummy" realm entry, within which
  1482.   you define the resource privileges, and a set of sub-realms
  1483.   where you actually specify the selectors (this is akin to using
  1484.   a !REALM entry in ACCESS.IN). For example:
  1485.      Realm: MYREALM
  1486.      Rule: 0
  1487.      Requires: priva privd privq
  1488.  
  1489.      Realm: Myrealm.set1
  1490.      Rule: foo/*
  1491.         etc.
  1492.  
  1493.   Note the effect of "Rule: 0 " -- no selector will match this rule;
  1494.   but the resource privileges (specified in the REQUIRES: line)
  1495.   will be inherited by MYREALM.SET1, etc.
  1496.  
  1497.  
  1498. 3.1.v) Some notes on superceding realms
  1499.  
  1500. The set of "superceding realms" (and "superceding subrealms") 
  1501. supercede all other "selector specific" information. 
  1502. SRE-http will first try and match a selector to the rules
  1503. for superceding realms. If a match is found (using the usual
  1504. "best matching" rules), the information for this realm
  1505. is used.  That is, non-superceding realms, and entries from
  1506. the .IN files, are NOT checked!
  1507.  
  1508. The successful use of superceding realms means that rather then calling 
  1509. four separate daemons (for "public url info, access control info, alias info, 
  1510. and virtual directory info"), only one daemon is called.  Since this
  1511. reduces queue and semaphore related overhead, and reduces the number of 
  1512. "best match searchs" from four to one, throughput should be improved.
  1513.  
  1514. However, the fact that "public url info, access control info, alias info, 
  1515. and virtual directory info" are independently specified allows a 
  1516. certain dynamism. For example, an alias can change a selector, and this 
  1517. changed selector can then match a virtual directory entry. Since such 
  1518. dynamics would either greatly complicate, (or render useless) this 
  1519. one lookup, the use of this "one daemon" is limited to information
  1520. specified in "superceding realms".  
  1521.  
  1522. Given that there  are more then zero superceding realms defined, 
  1523. SRE-http will:
  1524.   a) compare the selector to the rules belonding to the set of superceding 
  1525.      realms
  1526.   b) if any match it found, use the "public url, etc." information specified 
  1527.      in the "best matching" superceding realm. 
  1528.   c) if no match is found, check the rest of the selector specific entries 
  1529.      (that is, check all non-superceding realms specified in ATTRIBS.CFG, 
  1530.      and all the entries in the PUBURLS.IN, etc. files).
  1531.  
  1532. In other words (in a fashion similar to superceding hosts), a match to a 
  1533. superceding realm "trumps" all other (possibly better) matches in non-
  1534. superceding realms (and in the .IN files).
  1535.  
  1536. This does reduce the dynamism of sre-http -- since realm definitions are more
  1537. constrained then definitions made in the .IN files. For example, the
  1538. preceding example of "virtual directory from a modified selector" can not be 
  1539. implemented within a single realm. In addition, if there is no match 
  1540. to a "superceding realm", the time required to search the superceding realms 
  1541. confers no benefit (that is, it worsens throughput).
  1542. .
  1543. Therefore, it is recommended that...
  1544.     **  if you use superceding realms, use them as much as possible **
  1545. (which  implies careful migration of information from the .IN files 
  1546. to ATTRIBS.CFG).  
  1547.  
  1548. Notes: 
  1549.  
  1550.   * if no superceding realms are defined, then this daemon is not called --
  1551.     hence non-use of this feature should have minimal impact.
  1552.     However, you can fully disable the use of superceding realms by
  1553.     setting NO_SUPERCEDING_REALMS=1 (in SREFMON.CMD) -- this reduces
  1554.     extra processing even more then defining no superceding realms.
  1555.  
  1556.   * the use of superceding realms is independent of the use of superceding 
  1557.     hosts;  you need not worry about perverse interactions.
  1558.  
  1559.   * when the above description mentions the .IN files and the ATTRIBS.CFG file, 
  1560.     it also implies "host specific" versions of these files.
  1561.  
  1562.   * NOT all realms defined in ATTRIBS.CFG are superceding. 
  1563.  
  1564.   * Caution: In most cases the rules for a superceding realm will always
  1565.          be used in preference to other rules. However, certain
  1566.          lookups (such as some virtual directory lookups by
  1567.          addons, and PUB_URL lookups after a GoServe cache hit) do not 
  1568.          give thise special treatment to superceding realms.
  1569.  
  1570.          Therefore, it is safest to structure your realm rules so that
  1571.          selectors would match superceding realms even if they (the
  1572.          realms) weren't superceding.
  1573.  
  1574.   * A sub realm may be a superceding "subrealm" even if it's parent
  1575.     realm is non-superceding (and vice versa).
  1576.  
  1577.     
  1578.  
  1579.                         -------------------
  1580.  
  1581. 3.1.vi) Some examples:
  1582.  
  1583. realm: r1
  1584. rule: blendgif.htm mkgiftxt.htm
  1585. redirect: moved=http://www.srehttp.org/apps/
  1586.  
  1587. realm: r2
  1588. rule: temp/*
  1589. redirect: dir=h:\temp\*
  1590. options: set fix_expire .5 
  1591.  
  1592. realm: public
  1593. rule: pubfiles/*
  1594.  
  1595. realm: public.1
  1596. rule: morepubfiles/*
  1597. permissions: no_postfilter
  1598. redirect: literal=f:\pubs\*
  1599.  
  1600. realm: r2 C
  1601. host: danny
  1602. requires: *
  1603. rule: temp/*
  1604. redirect: dir=f:\temp\*  
  1605. limitlist: !HTML !ADDON
  1606.  
  1607. ; note:redirect: sel= is synonymous with redirect: internal=
  1608. realm: magic
  1609. port: 8080
  1610. rule: foo/*
  1611. redirect: sel=foobar/*
  1612.  
  1613.  
  1614. realm: send1
  1615. rule: scores/yankees
  1616. literal: e:\baseball\yanks.txt
  1617.  
  1618. realm: r2.3  
  1619. host: danny
  1620. rule: yahoo
  1621. redirect: move = http://www.yahoo.com
  1622.  
  1623. realm: r3
  1624. rule: *srehttp.faq
  1625.  
  1626. realm: r3.a C
  1627. rule: srehttp_faq
  1628. redirect: internal=/samples/srehttp.faq
  1629. permissions: yes_ssi
  1630.  
  1631. realm: r4
  1632. rule: config2.*
  1633. requires: superuser
  1634. permissions: no_aliase no_dogs
  1635. redirect: temp=http:/www.srehttp.org/config2.*
  1636.  
  1637. realm: r5.a.1
  1638. rule: /inhouse/foobar.htm
  1639. permissions: no_ssi
  1640.  
  1641. realm:r4.b
  1642. rule: config3.*
  1643. advanced: foo.ctl
  1644. permissions: no_virtual
  1645. option: ssi_no_header
  1646. option: ssi_no_footer
  1647.  
  1648. realm:r4.a.2
  1649. rule: config4.*
  1650.  
  1651. realm: manual
  1652. rule: /manual/*
  1653. negotiate: mans/manual1.lst
  1654.  
  1655. realm: intr
  1656. rule: intro.txt
  1657. negotiate: 
  1658. option: set content_md5 1
  1659.  
  1660.  
  1661.  
  1662. realm r5
  1663. rule: /inhouse/*
  1664. requires: inhouse
  1665.  
  1666. host: goons
  1667. include: d:\goserve\cfgs\goon2,cfg
  1668.  
  1669. user: dan1
  1670. pwd: wow
  1671. privs: a1 a2 a1a   
  1672.  
  1673. host: _!forest
  1674. user:  joe2
  1675. pwd: me1
  1676. privs: a1a a2a 
  1677.  
  1678. replace: contactme
  1679. with: this is the default contact
  1680.  
  1681. host: _!forest 
  1682. replace: contactme  
  1683. with: this is the contact for the forest site
  1684.  
  1685.  
  1686.  
  1687.