home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / puburls.doc < prev    next >
Text File  |  1999-06-27  |  9KB  |  207 lines
  1. 27 June 1999. Identifying publically accessible resources.
  2.  
  3. The basic idea of SRE-http's "public urls" is that before logon
  4. or access_controls are checked, SRE-http sees if the request selector 
  5. matches one of the PUBLIC_URLS. If so, no logon, etc. checking is attempted. 
  6.  
  7.     In a sense, the PUBLIC_URLS are purposely placed outside of the 
  8.     'protection'  of SRE-http's various access controls -- these are
  9.     resources which are always "open to the public".
  10.  
  11. PUBLIC_URLS are specified either:
  12.   a) via an entry in the "PUBURLS_FILE" file (PUBURLS.IN), or
  13.   b) via a PUBLIC "realm" entry in the "selector-attributes" file
  14.      (ATTRIBS.CFG)
  15.    
  16. Although this document focuses on the syntax of PUBURLS.IN,
  17. the general notions also apply to entries in ATTRIBS.CFG.
  18.  
  19.  *  In general, we now recommend that Public URLS be specified
  20.     by using the  ATTRIBS.CFG "realm definition file".
  21.  
  22.     For details on how to specify these "PUBLIC realms", see IN_FILES.DOC. 
  23.  
  24.  
  25. The basic structure of an entry in the PUBURLS.IN is:
  26.     candidate_sel  anoption filename
  27. where:
  28.     candidate_sel : is compared against the request selector
  29.          anoption : can be LITERAL LITERAL_NORECORD or NORECORD
  30.          filename : is a fully qualified file name (with possible * "wildcard 
  31.                     characters")
  32. (anoption and filename are both optional)
  33.  
  34. Entries in ATTRIBS.CFG are just like other "realm" definitions, with
  35. two exceptions:
  36.   a) The realm must be PUBLIC. Since subrealms are allowed, the following
  37.      realms define PUBLIC_URLS
  38.         Realm: public
  39.         Realm: public.set1
  40.   b) Requires: are ignored (since PUBLIC_URLS are never access controlled!)
  41. Furthermore:
  42.   c) instead of "NORECORD", specify a NO_POSTFILTER permission
  43.   d) instead of LITERAL, use a Redirect: literal= entry.
  44.  
  45. When the candidate_sel (or the Rule: in a realm definition) matches the 
  46. request selector (and the * wildcard character may be included in 
  47. the candidate_sel), SRE-http will treat the request as "a request 
  48. for a Public Resource".  Specifically, when anoption and filename are 
  49. not specified (or when a Literal: line does not appear in the realm
  50. definition), this means:
  51.     * logon checking does NOT occur
  52.     * selector-specific access control information, 
  53.       selector specific permissions, and selector-specific
  54.       advanced-options are NOT examined
  55.     * local redirections (such as home_name substitution, alias lookup
  56.       and virtual directory lookup WILL occur).
  57.     * server side includes may be attempted on HTML documents
  58.  
  59. The anoption and filename option are included to provide further
  60. flexibility.
  61.  
  62.    * If anoption=NORECORD or LITERAL_NORECORD (or if a NO_POSTFILTER
  63.      pemission is specified in a realm definition), then SRE-http will not
  64.      record the request, or perform any other "post filter" action
  65.      (for example, it will not record this request in the common-log
  66.      audit file). 
  67.  
  68.    * If anoption=LITERAL or LITERAL_NORECORD (or if a 
  69.      Redirect: literal=filename is used in a realm definition) then the 
  70.      resource is used "as is" -- no further processing of the "name" or
  71.      contents of the resource, is attempted (for example, SSI processing
  72.      will not be attempted)
  73.         > If no "filename" is specified, then the request selector
  74.           is assumed to point to a file under the GoServe data directory 
  75.           (virtual directories are not checked).
  76.         > If "filename" is specified, then it is used "as is" 
  77.            Actually, if filename contains a * wildcard, the usual "wildcard
  78.            substitution" is attempted (see the SREhttp.FAQ for a discsussion
  79.            of wildcard matching and substitution). 
  80.       The use of the filename argument allows a limited form of "aliasing" 
  81.       and "non-data directory file  transfer" 
  82.  
  83.    *  Setting anoption=LITERAL_NORECORD (or using a NO_POSTFILTER
  84.       permission and a Redirect: literal=filename in a realm definition)
  85.       implies "let goserve cache this"  (assuming the GoServe cache is 
  86.       enabled). That is, GoServe caching is  permitted for PUBLIC_URLS 
  87.       only when the matching public_url is "literal", and when it will
  88.       not be recorded (the idea is that the GoServe cache should
  89.       be used in "do not call filter" mode).
  90.     
  91.  
  92. Examples of entries in PUBURLS.IN:
  93.  
  94.    INDEX.HTM
  95.    MAPS/* 
  96.    STORE/AD1.HTM  LITERAL 
  97.    STORE/*.GIF  NORECORD 
  98.    PICTURE/HELLO.GIF  LITERAL_NORECORD  D:\PICTS\HELLO.GIF
  99.    FAMILY/*  LITERAL_NORECORD  D:\PERSONAL\*
  100.    CANDYSTORE// PRICES/CHOCO.HTM 
  101.  
  102. Examples of ATTRIBS.CFG entries
  103.  
  104.    ;this is equivalent to INDEX.HTM
  105.    Realm: public
  106.    rule: index.htm
  107.  
  108.    ; this is equivalent to STORE/AD1.HTM LITERAL
  109.    Realm: public.a
  110.    rule: store/ad1.htm
  111.    redirect: literal=
  112.  
  113.    ; this is equivalent to STORE/*.GIF NORECORD
  114.    Realm: public.b
  115.    rule: store/*.gif
  116.    permissions: no_postfilter
  117.  
  118.    ;this is equivalent to CANDYSTORE// PRICES/CHOCO.HTM
  119.    Realm: public.c
  120.    Host: candystore
  121.    rule: prices/choco.htm
  122.  
  123. Notes:
  124.    
  125.   i) INDEX.HTM is publically accessible
  126.  ii) Everything in the MAPS/ directory is publically accessible
  127.  
  128. III)STORE/AD1.HTM is to be transfered "as is",
  129.     where STORE/ is a subdirectory of the data directory. For example,
  130.     if the GoServe data directory is D:\WWW, then D:\WWW\STORE\AD1.HTM
  131.     would be transfered (without any SSI processing).
  132.  
  133.  iv) All .GIF files in STORE/ be transfered, with no recording of these 
  134.      transfers.
  135.  
  136.   v) PICTURE/HELLO.GIF causes transfer of d:\picts\hello.gif "as is"; 
  137.      with no recording done. Furthermore, PICTURE/HELLO.GIF may be
  138.      cached by the GoServe cache.
  139.  
  140.  vi) All requests beginning with FAMILY/ are to be directly mapped to 
  141.      D:\PERSONAL\, and transfered "as is", without recording the request. 
  142.      Furthermore, the GoServe cache (if enabled) is allowed to hangle future
  143.      requests for these resources.
  144.      For example, a request for FAMILY/JUNE.JPG
  145.            would result in D:\PERSONAL\JUNE.JPG being transferred.
  146.  
  147. vii) Requests to PRICE/CHOCO.HTM of the "CANDYSTORE" host are allowed
  148.  
  149. Notes on the examples:
  150.  
  151.    * As of SRE-http version 1.3d, you can specify host and port specific
  152.      PUBLIC_URLS files (in addition to using the host_nickname// modifier
  153.      on entries in this default PUBULRS.IN file).
  154.  
  155.    * To reiterate, the request selector (sent by the client to your server) is
  156.      examined for matches to one of the PUBLIC_URLS.  If multiple wildcard
  157.      matches (and no exact match) occur, the "best" match is used
  158.         The "best match " is defined as the match with the most characters
  159.         before the * character; and in the event of ties, the most after.
  160.  
  161.    * HTACCESS file lookup is suppressed whenever the request matches a
  162.      PUBLIC_URLS (HTACCESS access controls, redirection, etc. will not
  163.      be attempted).
  164.  
  165.    * In general, all files are assumed to be relative to the data directory
  166.      or a virtual directory.  Note that for "literal" public_url's,
  167.      virtual directories are NOT checked -- so all files are assumed to
  168.      be relative to the data directory
  169.      Reminder:  You can skip the "data directory" lookup by
  170.                 explicitly naming the file that this PUBLIC_URL maps to.
  171.                 You can do this simply by adding the (fully qualified) file
  172.                 name after the LITERAL option.
  173.                 For example:
  174.                    STORE/AD1.HTM  LITERAL D:\SHOP\ADS\AD_1.HTM
  175.  
  176.    * If you have no PUBLIC_URLS, you can speed up throughput a bit by 
  177.      setting  NEVER_PUBLICURLS=1 (in INIT_STA.80).
  178.  
  179.    *  To illustrate use of PUBLIC_URLS, SRE-http is shipped with
  180.       a version of PUBURLS.IN (and an ALIASES.IN) setup to respond to a
  181.       PUBLIC request by listing all files in the PUBFILES/ subdirectory
  182.       of the data directory (assuming you've created such a subdirectory).
  183.  
  184.    * If a request matches a PUBLIC_URLS, then:
  185.             If PRE_FILTER=FIRST, then the pre filter will be called.
  186.             Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is
  187.             treated as a NO).
  188.  
  189.    * You can specify PUBLIC_URLS on a host-specific basis.
  190.  
  191.                      ************** CAUTION  **************
  192.          In fact, non-host specific values of PUBLIC_URLS will
  193.          NOT be used as "default" values!
  194.                      ************** CAUTION  **************
  195.  
  196.      To do this, append a HOST_NICKNAME// to PUBLIC_URLS.  For example:
  197.          ZOO// HOURS.HTM LITERAL
  198.      indicates that this entry  applies to requests to the "host"
  199.      with a host nickname of ZOO.
  200.  
  201.  
  202. CAUTION: 
  203.    When using  "literal PUBLIC_URLS with fully qualified file names"
  204.    (and other types of local redirection) URL resolution by the client's
  205.    browser may have unexpected consequences. 
  206.  
  207.