home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Spezial / SPEZIAL2_97.zip / SPEZIAL2_97.iso / ANWEND / ONLINE / SREFV12J / VIRTUAL.IN < prev    next >
Text File  |  1997-07-23  |  8KB  |  176 lines
  1. ; SRE-FILTER support file -- specifying virtual directories. 3/97
  2. ;
  3. ; I) Introduction               ---------------------
  4. ;
  5. ;    Virtual directories are used to allow access to files not in a default directory.
  6. ;    The typical use is to allow requests for documents to be in a subdirectory
  7. ;    NOT under the "GoServe data directory".
  8. ;    Virtual files can also be for several other cases, including:
  9. ;           specifying the location of a  cgi-bin script
  10. ;           specifying the location of an sre-filter add-on
  11. ;           specifying where an uploaded file should be placed
  12. ;    Lastly, for some cases, virtual directories can be used to allow server
  13. ;    mediated access to files on other (remote) servers.
  14. ;
  15. ; II) Basic structure of entries   ----------------
  16. ;
  17. ; Each line in this file  should have the following structure:
  18. ;     host_nickname//  SEL_fragment  TARGET  limitation_list , username:password
  19. ; where:
  20. ;   * host_nickname// is optional
  21. ;   * SEL_fragment is the "beginning portion" of a request selector
  22. ;   * TARGET can be a (local) fully qualified directory or a
  23. ;                    (remote) fully specified URL
  24. ;   * the [optional] limitation_list is used to limit the applicability of the entry.
  25. ;     If present, it should be a spaced  delimited list. It's use is described below.
  26. ;   * the [optional] username:password is ONLY used for remote (http://) directories
  27. ;
  28. ; III) How virtual directories work   ---------------
  29. ;
  30. ;   The SEL_fragment is compared to the beginning of the request selector (the
  31. ;   selector).  If an "abbreviation" match occurs, the
  32. ;   "fragment" is removed from the "request selector"
  33. ;   and replaced with either the (local) target "directory" OR the
  34. ;   (remote) target "URL".  The limitation_list (if present) is used to control
  35. ;   which entries are used, based on whether the request is asking for a document,
  36. ;   a server side program, or an upload (see section V below for details).
  37. ;   If this is confusing, the examples at the bottom of this document should help.
  38. ;
  39. ;                              
  40. ; IV) General Notes                             ------------------
  41. ;
  42. ;   * If  no match is found, a "default directory" is used.  In the typical case
  43. ;     of a document request on a single host server, the default directory is the
  44. ;     goserve data directory.
  45. ;
  46. ;   * The limitation list can be used to limit the "scope" of the entry.
  47. ;     In particular, the "default directory"  must match  one of the entries
  48. ;     in the limitation list.  If there is no limitation_list, the entry will
  49. ;     be used for all requests.
  50. ;
  51. ;   *  An asterisk (*) at the end of  directory name means "allow access to subdirectories".
  52. ;
  53. ;   *  Leading and trailing slashes in the SEL_fragment are ignored, and
  54. ;      / and \ are treated equivalently.  Similarly, trailing slashes in
  55. ;      the TARGET directory are ignored.
  56. ;      Thus, the following are all equivalent:
  57. ;          foobar1/   d:\foobar\*
  58. ;          foobar1    d:\foobar*
  59. ;          \foobar1\  d:\foobar*
  60. ;
  61. ;   *  If a Drive is not specified in the TARGET (local) directory, the drive that
  62. ;      SRE-filter is installed on will be used.
  63. ;
  64. ;   *   WARNING: The use of "REMOTE urls" is ONLY supported for document requests.
  65. ;             It is NOT supported for "server side include" files, such
  66. ;             as specified in the INCLUDE and INTERPRET keyphrases. Nor is it
  67. ;             supported for server side programs, or upload, requests.
  68. ;
  69. ;   * CAUTION:  The NO_VIRTUAL permission (in ALL_FILE.CTL) suppresses
  70. ;               the use of VIRTUAL directories. That is, when a selector
  71. ;               matches an ALL_FILE.CTL entry that contains a NO_VIRTUAL
  72. ;               permssion, the information in this file will NOT be examined!
  73. ;
  74. ;
  75. ; V) Using the limitation_list   ----------
  76. ;
  77. ;   The limitation_list is used to limit the applicability of a virtual directory
  78. ;   entry. For example, you may wish to have some virtual directories apply only
  79. ;   to document requests, and some only to upload requests. 
  80. ;   The limitation_list (if present) should contain any mixture of the following
  81. ;   special keywords:  !UPLOAD, !CGI-BIN, !ADDONS, and !HTML. 
  82. ;        !HTML    --- use this entry for document requests
  83. ;        !CGI-BIN --- use this entry for cgi-bin requests
  84. ;        !ADDONS  --- use this entry for sre-filter addons
  85. ;        !UPLOAD  --- use this entry for file uploads
  86. ;   Note that you can contain more then one entry in the "space delimited"
  87. ;   limitation list.  Including all four entries is the same as not having
  88. ;   a limitation list: the entry will be used for all requests.
  89. ;
  90. ;   For example:
  91. ;      scdemo d:\netdata\macros\scdemo !cgi-bin
  92. ;      scdemo d:\netdata\html\scdemo   !html
  93. ;   The first entry will be used when a request for a cgi-bin script arrives
  94. ;        (i.e.; scdemo/cgi-bin/scinit.cmd
  95. ;   The second will be used for document requests  
  96. ;        (i.e.; scdemo/foo1.htm)
  97. ;
  98. ;
  99. ; VI) Specifying remote "target urls"   -------------
  100. ;
  101. ;    i) the http:// MUST be present (otherwise SRE-Filter assumes you
  102. ;        are referring to a local directory name)
  103. ;    ii) conversion of  / does NOT occur for these entries
  104. ;   iii) the trailing * option is supported
  105. ;    iv) This is NOT a redirect! Rather, SRE-Filter will retrieve the file
  106. ;        represented by this URL (on a remote server), strip out the
  107. ;        response headers, and treat it as if it came from a local directory.
  108. ;    vi) If you specify a username & password (after a comma), a BASIC authorization
  109. ;        request header will be added with this username & password. 
  110. ;        Otherwise, the client's username & password is used (if it is available)
  111. ;
  112. ; VII)  Match precedence      ---------------
  113. ;  Unlike most other SRE-Filter files, match precedence for virtual directories
  114. ;  is based on "abbreviation" matching, not "best matching".  That is,
  115. ;  * wildcards should not be in the SEL_FRAGMENT.  Instead, SRE-Filter simply
  116. ;  uses the longest SEL_FRAGMENT that is an "abbreviation" for the request
  117. ;  selector.
  118. ;
  119. ;
  120. ; VIII) EXAMPLES --------------------------
  121. ;
  122. ; LOCAL/PROJECTS     D:\WORK\PROJECTS*
  123. ;    If a selector of: /LOCAL/PROJECTS/BOB/PLANE.HTM is recieved, the file
  124. ;    returned will be D:\WORK\PROJECTS\BOB\PLANE.HTM.
  125. ;
  126. ;    Note: If the * is removed, /LOCAL/PROJECTS/BOB/PLANE.HTM would generate
  127. ;       a "no access allowed" error (since access to subdirectory BOB, 
  128. ;        under WORK\PROJECTS, would not be allowed).
  129. ;
  130. ; Example of "no subdirectory allowed access"
  131. ;    STATES   D:\USA\MAINE
  132. ;    .. a selector of STATES/AG.HTM would be valid (and would
  133. ;       return D:\USA\MAINE\AG.HTM)
  134. ;
  135. ; Example of a remote target URL:
  136. ;    SERVER2 http://pc2.myorg.net/support1/
  137. ;    .. a selector of SERVER2/CANADA.HTM will cause SRE-Filter to request
  138. ;    /support1/canada.htm from pc2.myorg.net
  139. ;
  140. ;  Example of host-specific entry:
  141. ;     SWEETSHOP//  CANDY   E:\STORE1\PRODUCTS\CANDY\*
  142. ;      ... requests, to hosts with host_nickname of SWEETSHOP, that have
  143. ;      selectors beginning with CANDY refer to files in
  144. ;      E:\STORE1\PRODUCTS\CANDY (and it's subdirectories).
  145. ;
  146. ;  Example of a limitation list:
  147. ;           ACTION2 e:\programs\task1  !addons
  148. ;    The !addons signals that the ACTION2 "virtual directory" will only
  149. ;    be used for requests for sre-filter add-ons.
  150. ;      For example:
  151. ;      /action2/getafile?dir=foodir1
  152. ;         E:\programs\task1\GETAFILE.CMD would be executed (as an SRE-Filter add-on)
  153. ;      /action2/gogo.htm
  154. ;         D:\www\action2\gogo.htm would be returned (assuming that the GoServe data
  155. ;        directory is D:\www)
  156. ;  
  157. ; Some additional examples:
  158. ;
  159. ; Temp on C, but NO subdirectory access
  160. ; CTEMP C:\temp
  161. ;
  162. ; D:\work, with subdirectory access allowed.
  163. ;D\work D:\WORK\*
  164. ;
  165. ; Get from the EXPORT directory (and directories underneath EXPORT)
  166. ; on the server at www.ours.org
  167. ;SITE2 http://www.ours.org/export/*
  168. ;
  169. ; the D:\project1 directory (and subdirectories) contain html documents, and
  170. ; sre-filter add-on procedures.
  171. ; project1   d:\project1*  !HTML !ADDONS
  172. ;
  173. ; Remote request to a server, using your server's username:password
  174. ; special\  http://server2.hissite.org/grate/stuff/* , specialask:ernie
  175. ; ---- End of comments
  176.