home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / in_files.doc < prev    next >
Text File  |  2001-03-27  |  63KB  |  1,685 lines
  1. 1 Nov 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.    i) the "mime-like" structure of ATTRIBS.CFG is easier to understand
  80.       then the more idiosyncratic structure of the .IN files
  81.   ii) SRE-http's use of realms mirrors how most browsers store access
  82.       information 
  83.  iii) 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 of whether 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.       (host specific entries trump non-host specific entries).
  189.  
  190.    Non-superceding hosts,
  191.       Both "host-specific" and "non-host specific" entries are checked.
  192.       The best match from this combined set of entries is used. Thus,
  193.       a non-host specific entry can be used in preference to a host-specific
  194.       entry (host specific entries do NOT trump non-host specific entries).
  195.  
  196.  
  197. The type of host is defined by the form of the host_nickname:
  198.    a) Strict-superceding hosts have "host_nicknames" that start with a _!!
  199.       For example:  _!!TREES
  200.    b) Superceding hosts have "host_nicknames" that start with a _!
  201.       For example:  _!FOREST 
  202.    c) Otherwise, it is a non-superceding host
  203.       For example:  RURAL
  204.  
  205.  
  206. 1.2.i. An example:
  207.  
  208.  
  209.   1)  IF: _!FOREST is the  host-nickname for forest.mysite.org
  210.  
  211.   2)  AND: the following entries are defined in ACCESS.IN
  212.         _!FOREST// BBS/*   PRIV1
  213.                    BBS/AREA12/*  PRIV2
  214.                    B*  PRIV3
  215.  
  216.   3)  THEN: a request for  
  217.            http://forest.mysite.org/bbs/area12/foo.bar
  218.  
  219.   4)  WILL REQURE: PRIV1 privileges 
  220.  
  221.   5)  THIS IS BECAUSE: the 
  222.          _!FOREST// BBS/*   PRIV1
  223.       entry "supercedes" the "better matching" non-host specific entry of
  224.          BBS/AREA12/*  PRIV2
  225.  
  226.  
  227. Or:
  228.  
  229.   1)  IF: the host-nickname was RURAL (a non-superceding host),
  230.  
  231.   2)  THEN: a PRIV2 privilege would be required 
  232.        (since BBS/AREA12/* is  a better match to bbs/area12/foo.bar).
  233.  
  234.  
  235. Or:
  236.  
  237.   1)  IF: the host-nickname was _!!TREES (a strict-superceding host),
  238.  
  239.   2)  THEN: a request for  
  240.            http://forest.mysite.org/bell/hello.txt
  241.  
  242.   3)  WILL NOT match any entries (implicitly requiring a SUPERUSR privilege)
  243.   
  244.   4) HOWEVER: if the host_nickname was RURAL
  245.   5) THEN: a PRIV3 privilege would be required, since the
  246.                    B*  PRIV3
  247.            non-host specific entry is a match.
  248.  
  249.  
  250.  
  251.                         -------------------
  252.  
  253. 2. The .IN files.
  254.  
  255. In this section, the four ".IN" files are described in detail.
  256. Note that these files can be editied using your favorite
  257. text editor, or with  SRE-http's "intermediate configurator"
  258. (/CONFIGUR.HTM).
  259.  
  260. Notes:
  261.  
  262.   * in most cases, the following descriptions can also be used for
  263.     "host and port specific .IN" files -- with the exception that
  264.     the "HOST_NICK//" parameter should NOT be used in
  265.     entries that appear in "host and port specific" files.
  266.  
  267.  
  268.                         -------------------
  269. 2.1. ACCESS.IN
  270.  
  271. ACCESS.IN is used to control access, and to assign various attributes.
  272.  
  273. 2.1.i)Introduction
  274.  
  275. The ACCESS.IN file is used to control access to your server's 
  276. resource on a selector specific basis.  This access control
  277. is based on a comparison of a client's "privileges" and the
  278. privileges assigned to a selector.
  279.  
  280. ACCESS.IN is also used to set several selector-specific attributes,
  281. including:
  282.    *) A variety of "permissions"
  283.    *) An "access failure file"
  284.    *) The realm to which this resource belongs
  285.    *) The name of an advanced options file
  286.  
  287.                         -------------------
  288.  
  289. 2.1.ii) Structure of entries
  290.  
  291. Each entry should be a space delimited list containing:
  292.   HOST_NICK// ASEL  RES_PRIVS , PERM_LIST , REALM , FAIL_FILE , ADVOPT_FILE
  293.  
  294. SRE-http will attempt to (exact or wildcard) match the request selector 
  295. with one of the ASEL fields in these entries.
  296.  
  297.  HOST_NICK//)  Optional.
  298.     Used to identify "host specific" entries.  
  299.     If a HOST_NICK is present, then the entry is only used with 
  300.     requests to hosts having this HOST_NICK "host nickname".
  301.     If a request is to a specified host (for which a HOST_NICK has been
  302.     defined); then "host-specific" entries are checked first. 
  303.     NOTE:
  304.        If the host is a "superceding host", then non-host specific entries 
  305.        are checked ONLY if no host-specific match is found.
  306.  
  307.  ASEL) Required. The ASEL  should be a (possibly wildcarded) request selector
  308.    SRE-http will compare ASEL against the request selector, and
  309.    use the entry with the best-matching ASEL.
  310.  
  311.  RES_PRIVS) Optional.
  312.     The RES_PRIVS  should be a (space delimited) list.
  313.     It can contain 2 forms of "resource privileges":
  314.         ONE_OF -- the client has to have "one of" these ONE_OF privileges
  315.         MUST_HAVE -- the client "must have" all of the MUST_HAVE privileges
  316.     To specify a MUST_HAVE privilege, add a & character at the beginning.
  317.     Otherwise, it is assumed to be a ONE_OF privilege
  318.                  (in other words, ONE_OF is the default form)
  319.  
  320.     For example, the list:
  321.            SALMON &TROUT HALIBUT
  322.     means that the client must have a TROUT privilege, as well as
  323.     either a SALMON or HALIBUT privilege (note that the TROUT privilege
  324.     is necessary but NOT sufficient!)
  325.  
  326.     There are a few special "ONE_OF" privileges: *  YES and NO
  327.         YES and * mean "allow everyone in" (given MUST_HAVE privs are ok)
  328.         NO means "only superusers"
  329.  
  330.    Notes on RES_PRIVS:
  331.  
  332.      *   If there are no ONE_OF conditions, it is assumed that the
  333.          "ONE_OF conditions are automatically satisfied" (the same can be
  334.          said if there  are no MUST_HAVE conditions).
  335.      *   If a REALM is specified, and a realm-specific resource 
  336.          privilege list exists for this REALM, then it (the realm-specific
  337.          resource privilege list) will be appended to the 
  338.          "selector specific" RES_PRIVS list  (see the description
  339.          of !REALM below for details).
  340.      *   If the combination of a RES_PRIVS list, and a "realm-specific
  341.          resource privileges" list is empty (that is, neither is specified),
  342.          then access IS allowed. 
  343.          That is (assuming you never use !REALM entries):
  344.           RES_PRIVS=' ' is the same as RES_PRIVS='*'
  345.      *   If none of these entries matches the selector, and ALLOW_ACCESS
  346.          is not equal to "YES", then access is NOT allowed (SUPERUSERS
  347.          and INHOUSE users possibly excepted).
  348.      *   If the ADD_RESOURCE_NAME='YES', then the "action" portion 
  349.          of the request selector is added to the resource privilege list.
  350.      *   Caution: when including entries of the form:
  351.                SECRETS/*  ADMIN1
  352.          and NODIR_EXT='DIR', then a request generated by
  353.                 http://foo.bar.net/secrets
  354.          will NOT match the SECRETS/* .. entry.
  355.      *   See ADDPRIVS.DOC for a discussion of how client's are granted 
  356.          transient privileges.
  357.  
  358.  PERM_LIST) Optional.
  359.    The PERM_LIST is optional (there MUST be comma seperating the
  360.    RES_PRIVS and the PERM_LIST)
  361.  
  362.    Permissions are used to modify how SRE-http processes the request.
  363.    Permissions include:
  364.      NO_SSI  : Suppress server side includes.
  365.      YES_SSI  : Check HTML documents for server side includes
  366.                (this overrides NO_SSI)
  367.      NO_SSP  : Suppress server side processing.
  368.      NO_CODE : Suppress SELECT and INTERPRET CODE ssi-keyphrases.
  369.                NO_CODE is a subset of NO_SSP (that is, if NO_SSP is present,
  370.                then NO_CODE is irrelevant)
  371.      CACHE :  Always allow caching of this selector by proxies 
  372.               (and by SREPROXY)
  373.               This does NOT enable caching by the GoServe cache.
  374.     CACHE* : As above, but ALSO allow  GoServe's caching of this selector.
  375.  
  376.              If the GoServe cache is not enabled, CACHE* and CACHE 
  377.              do the same thing.
  378.  
  379.              Note: if logon controls or access controls are in place, 
  380.                    then by default caching is disabled.  Use of CACHE or 
  381.                    CACHE* allows one to override this default rule.
  382.  
  383.      NOCACHE:  Do NOT cache this selector. NOCACHE overrides CACHE and
  384.                CACHE*. It also overrides PROXY_CACHE settings, but does
  385.                not override the cachable status of PUBLIC_URLs.
  386.  
  387.       PUT : Allow PUT method requests to "copy information to" the directory
  388.             represented by this selector (also used by GET_URL and PUT_FILE
  389.             facilities)
  390.     DELETE : Allow DELETE method request to "delete" the file represented by
  391.              this selector.
  392.  
  393.     NO_HTACCESS: Suppress the HTACCESS method.
  394.     NO_ALIAS   : Suppress SRE-http "aliasing."
  395.     NO_VIRTUAL : Suppress virtual directory lookup.
  396.     NO_POSTFILTER: Suppress post-filter processing (such as common-log 
  397.                   auditing, and augmentation of the SRE-http RECORD_ALL file).
  398.  
  399.    The last three (NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER) are meant
  400.    to be used to avoid unnecessary processing.  Note that NO_VIRTUAL
  401.    is ignored by CGI-BIN scripts and SRE-http addons (you can use the 
  402.    virtual directory's limitation_lists instead).
  403.  
  404.  REALM) Optional.
  405.    (there must be a comma between the REALM and the PERM_LIST)
  406.    The REALM is optional -- it identifies which "realm" this
  407.    selector "belongs" to..  The REALM is displayed as a SEL-specific realm
  408.    whenever SRE-http needs to "re prompt" the client for a 
  409.    new username/password (as when the user's first username/password
  410.    did not contain sufficient privileges to access the selector).
  411.  
  412.    If you don't specify REALM:
  413.       * If you've set the REALM_1ST_PRIV parameter (in SREFILTR.80)
  414.         then the first resource privilege is used as the realm name
  415.       * otherwise, the THE_REALM variable (set in INITFILT.80) is used
  416.  
  417.    Semi-Obsolete:
  418.       Special !REALM entries in this file can be used to specify
  419.       "realm specific resource privileges list" (see below for details).
  420.  
  421.  FAIL_FILE) Optional.
  422.     (there must be a comma between the FAIL_FILE and the REALM).
  423.     The FAIL_FILE (sometimes refered to as the ACCESS_FAILURE_FILE)
  424.     is optional . If the client does not have sufficient privileges
  425.     (as defined by the RES_PRIVS), then the FAIL_FILE is used as 
  426.     a "response file".  
  427.     Basically, the FAIL_FILE "overrides" the ACCESS_FAIL_FILE parameter
  428.     that is set in INITFILT.80.
  429.     Note that the FAIL_FILE should be one of:
  430.               -1: If no access, do NOT ask for authorization. Useful when
  431.                   combined with "dynamic privileges"
  432.      0 or blank :  use generic access_fail_file (or send an authorization response)
  433.    filename.ext :  a fully qualified file name.
  434.  
  435.   Actually, the ACCESS_FAIL_FILE parameter can suppress use of this FAIL_FILE
  436.   -- see initfilt.doc for details.
  437.  
  438.  ADVOPT_FILE) Optional.
  439.    (you must precede it with a comma)
  440.    The ADVOPT_FILE is optional -- if you do specify it,
  441.    SRE-http allows you to specify several selector-specific
  442.    "advanced options", including:
  443.      * customization of the response header,
  444.      * execution of a rexx program before sending a file (sort of
  445.        "mid-filter" hook),
  446.      * suppression of SSI features (such as headers and footers) --
  447.      * sel specific mime type
  448.      * string replacement (used with HTML documents)
  449.    The ADVOPT_FILE should be a relative file name, though it may point to a
  450.    subdirectory (it will be interpreted relative to the the SRE-http ADDON
  451.    directory).  For more details, see ADV_OPTS.DOC
  452.  
  453.                         -------------------
  454.  
  455. 2.1.iii) Notes
  456.  
  457.  Semi-obsolete option: additional, REALM-specific, resource privileges
  458.  
  459.    We no longer recommend use of this option -- see section III
  460.    (the selector-attributes documentation) for a better way to
  461.    define "realms".
  462.  
  463.      Each realm can have associated with it a list of "realm specific 
  464.      resource privileges".  If available, this (space delimited)
  465.      list is added to the the RES_PRIVS list of all selectors that
  466.      "belong" to this realm.
  467.      The syntax of these special entries is:
  468.            !REALM  realm_name  realm_privilege_list
  469.      Note that realm_name should match a REALM specified in several 
  470.      (or one) of the sel-specific entries.
  471.      
  472.      See below for some examples of realm-specific resource privilege_lists.
  473.  
  474.      NOTE: Currently, these !realm entires are NOT host specific!
  475.            Hence, on multi host systems we HIGHLY recommend using
  476.            the  host nickname as part of the realm_name (and, hence,
  477.            in corresponding REALM fields).
  478.  
  479.   / and \ :  They are treated the same (all / are converted to \)
  480.                        A Leading \ (or /) is stripped.
  481.  
  482.                         -------------------
  483.  
  484. 2.1.iv) Examples
  485.  
  486. Only superusers have access to the SYSTEM subdirectory
  487.    SYSTEM\*   NO
  488.  
  489. Only inhouse and superusers have access to the PRIVATE directory
  490.    PRIVATE\*  INHOUSE
  491.  
  492. Everyone has access to the PUBLIC\ directory, but documents in the
  493. public directory can not contain SELECT or INTERPRET CODE keyphrases.
  494.     PUBLIC\*  * , NO_CODE
  495.  
  496. Requests, to the host with nickname SWEETSHOP, for selectors that match 
  497. RECORDS/*, requires INHOUSE privileges
  498.     SWEETSHOP//  RECORDS/*  INHOUSE , , ADMIN_REALM
  499.  
  500. The client has to have "one of" VENUS,MARS, or MERCURY privlieges,
  501. and "must have" an EARTH privilege, to access the PLANETS/INNER directory.
  502. If the client does not have these privilegs, D:\WWW\NOPLANET.HTM
  503. is returned (given that ACCESS_FAIL_FILE<>0).
  504.     PLANETS/INNER/*  MERCURY VENUS &EARTH MARS , , , d:\www\NOPLANET.HTM
  505.  
  506. Allow uploads and deletes in the Uploads directory 
  507.     UPLOADS/* * , DELETE PUT 
  508.  
  509. Wildcards all requests for getafile.  Add a privilege list if you 
  510. want to limit its use 
  511.     GETAFILE*
  512.  
  513. These wildcard the  message box facility. Add a privilege list if desired ..
  514.    MESSAGE*
  515.    !ASKMESS*
  516.  
  517. Control access to the SECRET2 message box.
  518. All other message boxes are open to everyone with VIEWMESS privileges.
  519.     !VIEWMESS?messbox=secret2*  INHOUSE
  520.     !VIEWMESS* VIEWMESSAGES
  521.  
  522. Gives selectors pointing to the GUEST subdirectory (or virtual directory)
  523. a limited purview 
  524.     GUEST/*  * , NO_SSI NO_SSP , GUEST_REALM
  525.  
  526. Use the NEW.CTL "advanced options file" with all selectors
  527. that point to NEWSTUFF (and below). Note that there are no permissions
  528. specified, and no FAIL_FILE.
  529.    NEWSTUFF/*  * , , EXPERIMENTAL , , NEW.CTL
  530.  
  531. Allow caching of GIF files in (or under) the IMG directory; and don't bother
  532. checking aliases or the virtual directories, and don't do postfilter stuff
  533.    IMGS/*.GIF * , CACHE NO_ALIAS NO_VIRTUAL NO_POSTFILTER
  534.  
  535. Let goserve cache GIF files in (or under) the IMG directory. This is
  536. especially useful if you have NOT checked the "call filter anyways" 
  537. option of goserve (since if the filter is not called, then post 
  538. filtering etc. will not be done).
  539.    IMGS/*.GIF * , CACHE*
  540.  
  541. Give access to a clients with a privilege of MARTIANS, IONIANS
  542. or one of the privileges in the "additional resource privilege" list
  543. associated with the SPACEMEN realm (see below), access to files
  544. in the STELLAR directory
  545.    STELLAR/* MARTIANS IONIANS ,  , SPACEMEN
  546.  
  547.  
  548.  This is a catchall: "for all other files, everyone has access" 
  549.  or, you can change the second * to whatever privilege list 
  550.  you want (i.e.; NO, to disallow all access)
  551.     /* *
  552.  
  553. 2.1.iv.a) Some !REALM examples
  554.  
  555.  Note that !REALM entries can appear in any order or location in this file,
  556.  but there should only be one entry per realm_name.
  557.  
  558.  All selectors that belong to the REALM1 realm will have 
  559.  BIGFOOT and SASQUATCH added to their (possibly empty) RES_PRIVS list.
  560.  That is, the client will be allowed access (to selectors with
  561.  SEL-specific realm of REALM1) if they have a privilege
  562.  of BIGFOOT or SASQUATCH (or one the entries in the sel-specific
  563.  RES_PRIVS list).
  564.      !REALM  REALM1  BIGFOOT  SASQUATCH
  565.  
  566.  The SPACEMEN realm has "additional resource privileges" 
  567.  of: VULCANS KLINGONS and FERENGI
  568.       !REALM  SPACEMEN  VULCANS KLINGONS FERENGI
  569.  
  570.  Selectors in the  SPACEMEN2 realm requires a FEDERATION privileges as well
  571.  as "one of" the VULCANS KLINGONS or FERENGI (in addition to selector-
  572.  specific privileges)
  573.       !REALM SPACEMEN2 VULCANCS KLINGONS FERENGI &FEDERATION
  574.  
  575.  
  576.  
  577.                         -------------------
  578.  
  579. 2.2. ALIASES.IN
  580.  
  581. ALIASES.IN is used to specify internal and external redirection.
  582.  
  583.  
  584. 2.2.i)Introduction
  585.  
  586. Aliases are used to modify and transform the request selector.
  587. This includes:
  588.   Local redirection: Substituting for common "misspellings 
  589.                     and abbreviations"
  590.   Implementing searchable indices.
  591.   Remote redirection: Redirecting requests for moved URLS
  592.   Specifying "negotiable" resources
  593.  (SEMI-OBSOLETE) Setting path for CGI-BIN scripts
  594.  (SEMI-OBSOLETE) Transferring non-data-directory files.
  595.  
  596. Note: the following descriptions can also be used for "host and
  597.        port specific ALIASES.IN" files -- with the exception that
  598.       the "HOST_NICK//" parameter should NOT be used in
  599.       entries that appear in "host and port specific" files.
  600.  
  601.                         -------------------
  602.  
  603. 2.2.ii) Structure of entries
  604.  
  605.  Each line is structured as:
  606.      host_nickname//  TARGET  REPLACEMENT
  607.  where host_nickname// is optional.
  608.  Spaces should seperate these items.  
  609.  The TARGET should  have NO embedded spaes.
  610.  Note that in the TARGET, we convert / to \, and drop any leading / (or \).
  611.  
  612.   * Special feature:
  613.        if a line ends with a ' ,' (a space, then a comma)
  614.        the next line is treated as a continuation (with intervening 
  615.        spaces removed).
  616.  
  617.   SRE-http attempts to (exact or wildcard) match the request selector
  618.   with each TARGET.   
  619.  
  620.                         -------------------
  621.  
  622. 2.2.iii. Notes
  623.  
  624.  
  625.   *  If a match is found, the request selector is replaced by the
  626.      REPLACEMENT, with possible "wildcard substitution".
  627.  
  628.   *  "Wildcard substitution" occurs only if a * appears in the REPLACEMENT
  629.      and in the TARGET.  When this occurs, and the request selector "wildcard"
  630.      matches the TARGET, a textual substitution will occur in the REPLACEMENT.
  631.      Specifically, the * in the REPLACEMENT will be removed, and
  632.      the portion of the request selector "covered" by the * (in the
  633.      TARGET) will be inserted in its place.
  634.      Examples, given:
  635.           Request selector: /CATS/A14.HTM
  636.               and an alias entry with
  637.           Target:  /CATS/*
  638.           Replacement: /SHOP1/PETS/FELINES/PUREBRED/*
  639.         will yield:
  640.                   /SHOP1/PETS/FELINES/PUREBRED/A14.HTM
  641.         Note that the A14.HTM in the Rquest Selector is "covered"
  642.         by the * in the Target, and is then used to "replace" the
  643.         * in the Replacement.
  644.  
  645.  * When specifying a "negotiable resource", the REPLACEMENT is optional
  646.    
  647.                         -------------------
  648.  
  649. 2.2.iv. Some Examples   
  650.  
  651.    i) Local redirection: Replace a "misspelling or abbreviation".
  652.       Example: 
  653.         INDEX INDEX.HTM
  654.  
  655.  ii) Implementing searchable indices (using SRE-http's DOSEARCH utility)
  656.     In this example, CONGRESS.DAT will be searched using the search
  657.     list returned by the client
  658.         TESTSRCH.HTM?* DOSEARCH?file=/congress.dat&searchfor=*&delim=$
  659.     If ROOTC/ is a virtual directory for  C:\USERS\, this will search
  660.     C:\USERS\JOES.LST
  661.         LOOKUSER.HTM?* dosearch?file=/ROOTC/JOES.LST&searchfor=*&delim=0
  662.  
  663.  iii) The next 4 examples perform  "remote" redirectons.
  664.    a) This (note use of a full URL, including the http://)
  665.       causes a "temporary move"  (http status code 302) redirection.
  666.          YAH* http://www.yahoo.com/
  667.    b)Specifies the same thing, but the URL that follows
  668.       need not be comletely specified (if the ip domain is left out, it is
  669.       assumed to be to be back to your server.) Of course, to be safe one
  670.       should always specify the full URL (complete with http://)
  671.            WAH* !TEMP=www.yahoo.com/
  672.    c) A "permanent" move (http code 301) otherwise it's the same as
  673.         example ii.
  674.            ZAH* !MOVED=http://www.yahoo.com/
  675.    d) A "notification of moved resource" -- client recieves a document
  676.          telling her the resource has been moved, with a link to its new
  677.          location
  678.            JOEDIR/CV.HTM  !NOTIFY  http://college.faraway.edu/FAC/JOE/CV.HTM
  679.  
  680.  iv) Specifying a "negotiable resource"
  681.  
  682.     To specify a "negotiable resource", just enter the selector that
  683.     points to the resource, followed by the word !NEGOTIATE.
  684.     If this match occurs, the TARGET (selector) is assumed to be
  685.     a variant list, which will then be processed.
  686.     Example:
  687.          VARTEST/VAR1.LST !NEGOTIATE
  688.     (note that REPLACEMENT is not specified; instead, the word
  689.     !NEGOTIATE shoud appear)
  690.  
  691.     Alternatively, you can use a wildcarded "selector" and place the
  692.     name of the variant-list file after the !NEGOTIATE. 
  693.     Example:
  694.         MANUAL/* !NEGOTIATE  MANUAL/MANUALS.LST
  695.     would cause the "variant list" in MANUAL/MANUALS.LST to be used
  696.     for all selectors that match  MANUAL/*
  697.     Caution: If use this "wildcarded construct", the variant list MUST
  698.              contain an appropriate PATTERN: entry.
  699.  
  700.  v)  Specifying location of CGI-BIN script.
  701.      (semi-obsolete: use of a "location" before the /cgi-bin/ is
  702.      now recommended).
  703.      Example:
  704.        SCRIPT10   d:\progs\new
  705.      would instruct SRE-http to look for SCRIPT10 in d:\PROGS\NEW
  706.      (rather then the default, "cgi_bin_dir", script directory)
  707.  
  708.  vi) A host specific entry (only applies to requests to
  709.      hosts with a nickname of ZOO)
  710.      Example:
  711.        ZOO//  TIGERS    ANIMALS/FELINES/TIGERS.HTM
  712.      would only apply to request to a "host" with a ZOO host nickname.
  713.  
  714.  vii) Transfering files from anywhere 
  715.       (Semi-obsolete -- virtual directories are now recommended)
  716.       Example:
  717.          GETMAP?* !TRANSFER=e:\MAPS\*
  718.      Note that this example assumes that 1 argument is appended to the selector 
  719.      (say by a FORM of type GET)
  720.  
  721.                         -------------------
  722.  
  723. 2.2.v. Some cautions
  724.  
  725.  * A CAUTION  regarding unwanted aliasing:
  726.           Unless you explicitly want to "alias" actual files, directories,
  727.           or "server side program" names...
  728.                  we HIGHLY RECOMMEND that all entries in this file
  729.                  have "targets" that do NOT MATCH pre-existing files,
  730.                  directories, or "actions".
  731.          {and be especially careful if you are using any wildcard matches)
  732.  
  733.  * A CAUTION on local redirection and partial urls:
  734.       When using aliases for "local redirection", URL resolution by the
  735.       client's browser may have unexpected consequences. See the discussion 
  736.       of "local  vs remote redirection" in INITFILT.DOC for details!
  737.  
  738.                         -------------------
  739.  
  740. 2.3. PUBURLS.IN
  741.  
  742. PUBURLS.IN is used to specify publically accessible" resources.
  743.  
  744.  
  745. 2.3.i) Introduction
  746.   
  747. PUBURLS.IN is used to identify  public-urls: which are defined as
  748. resources for which access (and logon) controls are not imposed.  
  749.  
  750.     * See PUBURLS.DOC for a complete description of public-urls. 
  751.  
  752. 2.3.ii) Syntax
  753.  
  754. The basic syntax of entries is:
  755.    host_nickname// candidate_sel  anoption filename
  756. where:
  757.     host_nickname is an (optional) host nickname
  758.     candidate_sel is compared against the request selector
  759.     anoption can be: LITERAL LITERAL_NORECORD or NORECORD
  760.     filename is a fully qualified file name (with possible * "wildcard 
  761.     characters")
  762. (anoption and filename are both optional)
  763.  
  764. 2.3.iii) Examples
  765.  
  766.      INDEX.HTM
  767.      MAPS/* 
  768.      STORE/AD1.HTM  LITERAL 
  769.      STORE/*.GIF  NORECORD 
  770.      PICTURE/HELLO.GIF  LITERAL_NORECORD  D:\PICTS\HELLO.GIF
  771.      ZOO// HOURS.HTM LITERAL
  772.  
  773.  Notes
  774.    * LITERAL_NORECORD implies "let goserve cache this" 
  775.        (assuming the goserve cache is enabled)
  776.    * Requests to host ONLY match host specific entries, That is,
  777.      non-host specific entries WILL NOT match requests to 
  778.      "hosts" (for which a host_nickname is defined).
  779.    * Public URLS with a LITERAL_NORECORD attribute may be cached
  780.      by the GoServe cache.
  781.  
  782.  
  783.                         -------------------
  784.  
  785. 2.4. VIRTUAL.IN
  786.  
  787. VIRTUAL.IN is used to specify virtual directories. 
  788.  
  789.  
  790. 2.4.i) Introduction            
  791.  
  792. Virtual directories are used to allow access to files not in a default 
  793. directory. The typical use is to allow requests for documents to be 
  794. in a subdirectory NOT under the "GoServe data directory".
  795.  
  796. VIRTUAL.IN can also be for several other reasons, including:
  797.      specifying the location of a  cgi-bin script
  798.      specifying the location of an sre-http add-on
  799.      specifying where an uploaded file should be placed
  800. Lastly, for some cases, virtual directories can be used to allow server
  801. mediated access to files on other (remote) servers.
  802.  
  803.                         -------------------
  804.  
  805. 2.4.ii) Basic structure of entries  
  806.  
  807. Each line in VIRTUAL.IN should have the following structure:
  808.      host_nickname//  SEL_fragment  TARGET  limitation_list , username:pwd
  809. where:
  810.    * host_nickname// is optional
  811.    * SEL_fragment is the "beginning portion" of a request selector
  812.    * TARGET can be a (local) fully qualified directory or a
  813.                     (remote) fully specified URL
  814.    * the [optional] limitation_list is used to limit the applicability of 
  815.      the entry.
  816.      If present, it should be a spaced  delimited list. Its use is 
  817.      described below.
  818.    * the [optional] username:password is ONLY used for remote 
  819.      (http://) directories
  820.  
  821.                         -------------------
  822.  
  823. 2.4.iii) How virtual directories work 
  824.  
  825. The SEL_fragment is compared to the beginning of the request selector 
  826. (the selector).  If an "abbreviation" match occurs, the
  827. "fragment" is removed from the "request selector"
  828. and replaced with either the (local) target "directory" OR the
  829. (remote) target "URL".  
  830.  
  831. The limitation_list (if present) is used to control which entries are used, 
  832. based on whether the request is asking for a document, a server side 
  833. program, or an upload (see section V below for details).
  834.  
  835.  [If this is confusing, the examples in 2.4.vii should help.]
  836.  
  837.   
  838.                         -------------------
  839.  
  840.                               
  841. 2.4.iv) General Notes                             
  842.  
  843.    * If  no match is found, a "default directory" is used.  
  844.      In the typical case of a document request on a single host server, 
  845.      the default directory is the GoServe data directory.
  846.  
  847.    * If the host is a "superceding host", then non-host specific entries 
  848.      are checked ONLY if no host-specific match is found.
  849.  
  850.    * The limitation list can be used to limit the "scope" of the entry.
  851.      If there is no limitation_list, the entry will be used for all requests.
  852.  
  853.    *  An asterisk (*) at the end of  directory name means "allow access to 
  854.       subdirectories". Note that you should NOT place an asterisk at
  855.       the end of the SEL_FRAGMENT
  856.  
  857.    *  Leading and trailing slashes in the SEL_fragment are ignored, and
  858.       / and \ are treated equivalently.  Similarly, trailing slashes in
  859.       the TARGET directory are ignored.
  860.       Thus, the following are all equivalent:
  861.           foobar1/   d:\foobar\*
  862.           foobar1    d:\foobar*
  863.           \foobar1\  d:\foobar*
  864.  
  865.    *  If a Drive is not specified in the TARGET (local) directory, the drive 
  866.       that SRE-http is installed on will be used.
  867.  
  868.    *   WARNING: The use of "REMOTE urls" is ONLY supported for document 
  869.                 requests. It is NOT supported for "server side include" 
  870.                 files, such as specified in the INCLUDE and INTERPRET 
  871.                 SSI keyphrases. Nor is it supported for server side programs,
  872.                 or upload, requests.
  873.  
  874.    * CAUTION:  The NO_VIRTUAL permission (in ACCESS.IN) suppresses
  875.                the use of VIRTUAL directories. That is, when a selector
  876.                matches an ACCESS.IN entry that contains a NO_VIRTUAL
  877.                permssion, virtual directory information will NOT be examined!
  878.  
  879.  
  880.                         -------------------
  881.  
  882. 2.4.v) Using the limitation_list   
  883.  
  884.    The limitation_list is used to limit the scope of a virtual 
  885.    directory entry. For example, you may wish to have some virtual 
  886.    directories apply only to document requests, and some only to upload 
  887.    requests. 
  888.    The limitation_list (if present) should contain any mixture of the 
  889.    following special keywords:  !UPLOAD, !CGI-BIN, !ADDONS, and !HTML. 
  890.         !HTML    --- use this entry for document requests
  891.         !CGI-BIN --- use this entry for cgi-bin requests
  892.         !ADDONS  --- use this entry for sre-http addons
  893.         !UPLOAD  --- use this entry for file uploads
  894.    Note that more than one of these keywords can appear in this
  895.    "space delimited" limitation list.  Including all four entries is
  896.    the same as not having a limitation list: the entry will be
  897.    used for all requests.
  898.  
  899.    For example:
  900.       scdemo d:\netdata\macros\scdemo !cgi-bin
  901.       scdemo d:\netdata\html\scdemo   !html
  902.    The first entry will be used when a request for a cgi-bin script arrives
  903.         (i.e.; scdemo/cgi-bin/scinit.cmd
  904.    The second will be used for document requests  
  905.         (i.e.; scdemo/foo1.htm)
  906.  
  907.                         -------------------
  908.  
  909.  
  910. 2.4.vi) Specifying remote "target urls" 
  911.  
  912.     i) the http:// MUST be present (otherwise SRE-http assumes you
  913.         are referring to a local directory name)
  914.     ii) conversion of  / does NOT occur for these entries
  915.    iii) the trailing * option is supported
  916.     iv) This is NOT a redirect! Rather, SRE-Http will use socket calls to
  917.         retrieve the resources represented by this URL (on a remote server), 
  918.         strip out the response headers, and treat it as if it came from a 
  919.         local directory.
  920.     vi) If you specify a username & password (after a comma), a
  921.         BASIC authorization request header will be added with this 
  922.         username & password. Otherwise, the client's username & password 
  923.         is used (if it is available)
  924.  
  925.                         -------------------
  926.  
  927. 2.4.vii)  Match precedence     
  928.  
  929.   Unlike most other SRE-http files, match precedence for virtual directories
  930.   is based on "abbreviation" matching, not "best matching".  That is,
  931.   * wildcards should not be in the SEL_FRAGMENT.  Instead, SRE-Http simply
  932.   uses the longest SEL_FRAGMENT that is an "abbreviation" for the request
  933.   selector.
  934.  
  935.  
  936.                         -------------------
  937.  
  938. 2.4.viii) Examples
  939.  
  940. Two examples of "subdirectory access is allowed":
  941.  
  942.   (if a selector of: /LOCAL/PROJECTS/BOB/PLANE.HTM is recieved, the file
  943.   returned will be D:\WORK\PROJECTS\BOB\PLANE.HTM)
  944.       LOCAL/PROJECTS     D:\WORK\PROJECTS*
  945.  
  946.   Note: If the * is removed, /LOCAL/PROJECTS/BOB/PLANE.HTM would generate
  947.           a "no access allowed" error (since access to subdirectory BOB, 
  948.           under WORK\PROJECTS, would not be allowed).
  949.  
  950.   (D:\work, with subdirectory access allowed)
  951.       D\work D:\WORK\*
  952.  
  953.  
  954. Two examples of "no subdirectory allowed access"
  955.  
  956.   (a selector of STATES/AG.HTM would be valid,and would
  957.   return D:\USA\MAINE\AG.HTM)
  958.     STATES   D:\USA\MAINE
  959.  
  960.   (temp on C:, but NO subdirectory access)
  961.     CTEMP C:\temp
  962.  
  963. Three examples of a remote target URL:
  964.  
  965.  (a selector of SERVER2/CANADA.HTM will cause SRE-Http to request
  966.  /support1/canada.htm from pc2.myorg.net)
  967.     SERVER2 http://pc2.myorg.net/support1/
  968.  
  969.  (get from the EXPORT directory (and directories underneath EXPORT)
  970.  on the server at www.ours.org)
  971.     SITE2 http://www.ours.org/export/*
  972.  
  973.  (remote request to a server, using your server's username:password)
  974.     special\  http://server2.hissite.org/grate/stuff/* , specialask:ernie
  975.  
  976. An example of a host-specific entry:
  977.  
  978.   (requests, to hosts with host_nickname of SWEETSHOP, that have
  979.   selectors beginning with CANDY refer to files in
  980.   E:\STORE1\PRODUCTS\CANDY and its subdirectories).
  981.      SWEETSHOP//  CANDY   E:\STORE1\PRODUCTS\CANDY\*
  982.  
  983. Two examples of limitation lists:
  984.  
  985.   (the !addons signals that the ACTION2 "virtual directory" will only
  986.   be used for requests for sre-http add-ons).
  987.       ACTION2 e:\programs\task1  !addons
  988.  
  989.    For example:
  990.       /action2/getafile?dir=foodir1
  991.          E:\programs\task1\GETAFILE.CMD is executed (as an SRE-Http add-on)
  992.       /action2/gogo.htm
  993.          D:\www\action2\gogo.htm would be returned (assuming that the 
  994.          GoServe data directory is D:\www)
  995.  
  996.   (the D:\project1 directory (and subdirectories) contain html documents, 
  997.   and sre-http add-on procedures)
  998.    project1   d:\project1*  !HTML !ADDONS
  999.  
  1000.  
  1001.                         -------------------
  1002.  
  1003. 3.          Specifying selector-specific attributes using realms
  1004.  
  1005.  ATTRIBS.CFG is used to set selector-specific attributes, using 
  1006.  a "realm-architecture". In addition, ATTRIBS.CFG can be 
  1007.  used to specify user/passwords, and to specify replacement strings.
  1008.  
  1009.                         -------------------
  1010.  
  1011. 3.1.i)Introduction
  1012.  
  1013. ATTRIBS.CFG supplements (or replaces) the several user-configurable
  1014. ".IN" files used by SRE-http. These are ACCESS.IN, ALIASES.IN, 
  1015. PUBURLS.IN, REPSTRGTS.IN, USERS.IN, and VIRTUAL.IN (note that prior
  1016. to ver 1.3f, ACCESS.IN was named ALL_FILE.CTL). 
  1017.  
  1018. Four of these ".IN" files (ACCESS.IN, ALIASES.IN, PUBURLS.IN,
  1019. and VIRTUAL.IN) are used to set "selector-specific" attributes 
  1020. (see section 2. for the details).  ATTRIBS.CFG integrates
  1021. these four files using a "realm-architecture"; an architecture 
  1022. that matches how the WWW is organized, and should be easier to
  1023. work with.
  1024.  
  1025.  
  1026. The basic idea of this "realm-architecture" is:
  1027.   1) a server's resources (documents, images, scripts, etc.)
  1028.      can be sorted into "realms"
  1029.   2) each of these "realms" may have numerous "sub-realms"
  1030.   3) access to your server's resources can be defined on a "realm" specific
  1031.      basis --  a given client can be granted access to resources in only
  1032.      a subset of your server's "realms".
  1033.   4) other attributes, such as redirection instructions, and 
  1034.      customization of how sre-http will process the request, can
  1035.      be defined on a realm, or subrealm, basis
  1036.   5) A realm, or a sub-realm, can contain:
  1037.       *) one resource  (a single selector), or
  1038.       *) set of similarly named resources (a single, wildcarded
  1039.          selector), or
  1040.       *) several similarly named resources
  1041.  
  1042.  
  1043.                         -------------------
  1044.  
  1045. 3.1.ii) Syntax 
  1046.  
  1047. Entries in ATTRIBS.CFG consist of a block of several "mime-like" lines, 
  1048. ending with a blank line. Each "mime-like" line has the following structure:
  1049.    action: options 
  1050.  
  1051. Briefly, the following lists (in alphabetical order) the available "actions."
  1052.  
  1053.   advopt_file -- specify an advanced options file
  1054.   failure    -- specify an access failure file
  1055.   host       -- specify which host this entry is to be used for
  1056.   include    -- include a host/port specific set of entries
  1057.   limitlist  -- specify a limitation list (used with redirect: dir=)
  1058.   option     -- specify an advanced option
  1059.   permissons -- specify sre-http "permissions"
  1060.   port       -- specify which server port this entry is to be used for
  1061.   privs      -- specify client privileges (used with USER)
  1062.   pwd        -- specify a password (used with USER)
  1063.   realm      -- the realm (subrealm) name of this entry (REQIURED)
  1064.   redirect   -- url redirection, or virtual directory assignment
  1065.   requires   -- resources privileges needed for access 
  1066.   rule       -- selectors (possibly *'ed) to assign to this realm (REQUIRED)
  1067.   replace    -- specify a replacement variable
  1068.   with       -- specify a replacement string (used with REPLACE)
  1069.   user       -- specify a user name
  1070.  
  1071. Note that a "block" must contain one of:
  1072.   INCLUDE -- an "include file" block
  1073.   REALM and RULE -- a "realm definition"
  1074.   REPLACE and WITH -- a "replacement rule
  1075.   USER and PWD -- a username/password 
  1076.  
  1077.  
  1078. The following describes these actions in greater detail:
  1079.  
  1080.  
  1081. advopt_file: 
  1082.  
  1083.  Specify an "advanced" options file.
  1084.  
  1085.  Syntax:
  1086.    advopt_file: file_name
  1087.  
  1088.  file_name should be a relative file name (it will relative to the
  1089.  SRE-http ADDON directory). For more details on advanced options files,
  1090.  please see section 2.1.ii, or see ADV_OPTS.DOC
  1091.  
  1092.  
  1093.  Notes:
  1094.    * advopt_file complements OPTION: 
  1095.    * you can use ADV as an abbreviation for ADVOPT_FILE
  1096.  
  1097.  
  1098.  
  1099. failure: 
  1100.  
  1101.   Specify an "access failure file"
  1102.  
  1103.   Syntax:
  1104.     failure: file_name
  1105.  
  1106.   file_name should be a fully qualified file name, or a special
  1107.   code -- see the discussion of FAIL_FILE in section 2.1.ii for
  1108.   further discussion of access failure files.
  1109.  
  1110. host:
  1111.   The "host nickname" of the host this entry applies to
  1112.  
  1113.   Syntax:
  1114.     host: host_nickname
  1115.  
  1116.   If not specified, the entry will be used for all requests -- such
  1117.   entries are assumed to refer to a "default" host. 
  1118.  
  1119.   For redirect and requires:
  1120.     If the host is a "superceding host", then non-host specific entries 
  1121.     are checked ONLY if no host-specific match is found.
  1122.  
  1123.  
  1124.   Note: If you are running a single host site, you do NOT need to use 
  1125.         host:
  1126.  
  1127. include:
  1128.  
  1129.  Include a file of entries, to be assigned to a single host and port.
  1130.  
  1131.  Syntax:
  1132.     include:  file_name
  1133.  
  1134.  file_name should be a fully qualified filename 
  1135.  
  1136.  The include: action is special -- when it appears in an entry,
  1137.  only host: or port: actions are used, all other actions are ignored.
  1138.  
  1139.  Files "included" should have the same structure as ATTRIBS.CFG,
  1140.  with one exception -- host: and port: actions should not be included
  1141.  (actually, they can be included, but they will be ignored).
  1142.  
  1143.  Basically, the main purpose for include: is to allow each "host"
  1144.  to have its own configuration file.  This provides an alternative
  1145.  to the use of host: (and port:) actions.
  1146.  
  1147.  Note: you can also use CFGLIST.CFG to specify "host & port
  1148.        specific ATTRIBS entries".
  1149.  
  1150.  
  1151. limitlist:
  1152.  
  1153.   Specify a "limitation list". This limitation list is used with
  1154.       redirect: dir=.
  1155.   There are four valid values that can appear in the limitation list:
  1156.   !HTML, !CGI-BIN, !ADDONS, and !UPLOAD.
  1157.   See section 2.4.v for the details on limitation lists.
  1158.  
  1159.   Example: limitlist: !HTML
  1160.  
  1161.   Note: not specifying a limitlist is the same as specifying all
  1162.         four of these values.
  1163.  
  1164. option:
  1165.   Specify an advanced option
  1166.  
  1167.   Syntax:
  1168.     option: an_advanced_option
  1169.  
  1170.   The advanced_option can be any of the SRE-http advanced options,
  1171.   as described in ADV_OPTS.DOC.
  1172.  
  1173.   You can specify multiple option: lines -- with one option per 
  1174.   line.
  1175.  
  1176.   Examples:
  1177.     option: set fix_expire 0.5
  1178.     option: ssi_no_footer
  1179.     option: REPLACE_RULES=</HEAD>==<BASE href="http://www.x.org"></HEAD>
  1180.  
  1181.   Note that option: complements advopt_file:
  1182.  
  1183. permissions:
  1184.  
  1185.  Specify the "permissions" to use for selectors that belong to this realm.
  1186.  
  1187.  Syntax:
  1188.     permisson:  permission_list  
  1189.  
  1190.   permission_list is a spaced delimited list of SRE-http "permissions".
  1191.   Currently available permissions include:
  1192.       NO_SSI     YES_SSI       NO_SSP      NO_CODE      CACHE   
  1193.       CACHE*     PUT           DELETE     NO_HTACCESS    NO_ALIAS   
  1194.       NO_VIRTUAL NO_POSTFILTER  
  1195.  
  1196.   For details on how to use permissions, see the discussion of
  1197.   PERM_LIST in section 2.1.ii                 
  1198.  
  1199.  
  1200.   Notes:
  1201.  
  1202.     * Sub-realms can inherit the PERMISSIONS values of their parent
  1203.       subrealm (or grandparent, etc.).
  1204.  
  1205.     * The NO_POSTFILTER permission, when used with a PUBLIC realm,
  1206.       is equivalent to specifying a NORECORD (or LITERAL_NORECORD)
  1207.       attribute in a PUBURLS.IN entry (see 2.3.iii for details)
  1208.  
  1209. port:
  1210.   
  1211.   Specify which port this entry applies to.
  1212.  
  1213.   Syntax:
  1214.      port: nnn
  1215.  
  1216.   where nnn is the port number your server is running on.
  1217.   If a port: entry does not appear, the default (80) is
  1218.   assumed.
  1219.  
  1220.   If you always run your web server on the standard http port (port 80),
  1221.   then you will never need to use port:
  1222.  
  1223.  
  1224. privs:
  1225.  
  1226.    Specify  user (client) privileges
  1227.  
  1228.    Syntax:
  1229.        privs: privlist
  1230.  
  1231.    Specify a set of "client privileges" to be assigned to a user.
  1232.    You MUST also specify  a username and a password 
  1233.   (using the user: and pwd: actions).
  1234.  
  1235.    Privlist is a space delimited list of privileges.  
  1236.      * "secret" privileges should start with a ?.
  1237.      * see USERS.DOC for details on replacement rules.
  1238.      * you can specify host and port usernames (using
  1239.        the HOST: and PORT: actions)
  1240.  
  1241.  
  1242. pwd:
  1243.  
  1244.    Specify a password
  1245.  
  1246.    Syntax:
  1247.        pwd: a_password
  1248.  
  1249.    Specify a password for a user of site.  You MUST also specify
  1250.    a username (using the user: action).
  1251.  
  1252.      * a_password may be case sensitive  (depending on the authorization
  1253.        mechanism used by the client)
  1254.      * the PRIVS: action is also used with user: and pwd:
  1255.      * see USERS.DOC for details on replacement rules.
  1256.      * you can specify host and port usernames (using
  1257.        the HOST: and PORT: actions)
  1258.  
  1259.  
  1260. replace: xxx
  1261.      
  1262.   Specify a replacement rule. 
  1263.  
  1264.   Syntax:
  1265.      replace: xxx
  1266.  
  1267.   Replacement rules are used with <!-- REPLACE xxx --> server side includes.  
  1268.  
  1269.   Notes:
  1270.      * replace MUST be used in conjunction with a WITH: action
  1271.      * see REPSTRGS.DOC for details on replacement rules.
  1272.      * you can specify host and port specific replacement rules (using
  1273.        the HOST: and PORT: actions)
  1274.      * spaces are stripped from xxx. In other words:
  1275.         replace: myvar1
  1276.       and
  1277.         replace:myvar1
  1278.       and
  1279.         replace:    myvar1
  1280.       are equivalent.
  1281.  
  1282.  
  1283. realm: 
  1284.  
  1285.  The realm_name, or realm_name plus subrealm_name, idenfies this "entry". 
  1286.  
  1287.  Syntax:
  1288.       realm: realm_name C
  1289.   or                   
  1290.       realm: realm_name.subrealm_name C
  1291.  
  1292.   Notes:
  1293.     * PUBLIC is a "special" realm_name --  it signifies "open access" 
  1294.       resources
  1295.     * In order to define a subrealm, you MUST define its  "main realm" 
  1296.     * Subrealms can be more then 1 deep. Thus, FOO.BAR.UP is legitimate.
  1297.  
  1298.     * When SRE-http returns an authorization request to a client,
  1299.       it will use the "main realm". For example, if a request
  1300.       matches R1.S3.T4, then R1 is the realm reported to the client.
  1301.  
  1302.     * the C is optional. If present, this realm (or realm.subrealm) is
  1303.       a "superceding" realm. Otherwise, it is a normal realm (see
  1304.       section 3.1.v for a discussion of superceding realms)
  1305.     
  1306.                            
  1307. requires:
  1308.  
  1309.   Identify the resource privileges a client needs to access this realm.
  1310.  
  1311.   Syntax:
  1312.       requires: priv_list
  1313.  
  1314.   priv_list is a space delimited list of "resource privileges".
  1315.  
  1316.   Note that subrealms MUST inherit the "resource privileges" of their
  1317.   main realm -- you can not specify different sets of resource
  1318.   privileges for different subrealms under the same "main realm"
  1319.  
  1320.   Thus:  requires can NOT be used in subrealm entries!
  1321.  
  1322.   For further discussion of "resource privileges", see the discussion of
  1323.   RES_PRIVS in section 2.1.ii.
  1324.  
  1325.  
  1326.   Notes:
  1327.    *  For the PUBLIC realm, REQUIRES is ignored (an implicit REQUIRES: *
  1328.       is used).
  1329.    *  Reiterating: Sub-realms inherit the REQUIRES values of their
  1330.       parent realm.  You can NOT set sub-realm specific REQURES
  1331.  
  1332.  
  1333. redirect:
  1334.  
  1335.  Redirect or redefine a request
  1336.  
  1337.  Syntax
  1338.    redirect: mode = xxx
  1339.  
  1340.   mode can be:
  1341.  
  1342.    dir      -- a "virtual directory". XXX is  a fully qualified
  1343.                directory. It can contain one wildcard at the end.
  1344.                For more details, please see the dicussion of virtual 
  1345.                directories in section 2.4.
  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.  Redirect 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 the
  1476.   parent of 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 or subrealm is 
  1505. used.  That is, non-superceding realms and subrealms, 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 (and superceding subrealms).
  1526.   b) if any match it found, use the "public url, etc." information specified 
  1527.      in the "best matching" superceding realm (or superceding subrealm). 
  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 orthogonal to 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 this 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 its 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. realm r5
  1661. rule: /inhouse/*
  1662. requires: inhouse
  1663.  
  1664. host: goons
  1665. include: d:\goserve\cfgs\goon2,cfg
  1666.  
  1667. user: dan1
  1668. pwd: wow
  1669. privs: a1 a2 a1a   
  1670.  
  1671. host: _!forest
  1672. user:  joe2
  1673. pwd: me1
  1674. privs: a1a a2a 
  1675.  
  1676. replace: contactme
  1677. with: this is the default contact
  1678.  
  1679. host: _!forest 
  1680. replace: contactme  
  1681. with: this is the contact for the forest site
  1682.  
  1683.  
  1684.  
  1685.