home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / BYCLIENT.DOC < prev    next >
Text File  |  1999-04-09  |  14KB  |  330 lines
  1. 15 Apr 1998: ByClient.RXX :  Using Client Specific Documents.
  2.  
  3. Abstract:
  4.   ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  5.   deliver of "client specific" documents to your WWW clients.
  6.  
  7. Contents:
  8.  
  9. 1.0 Introduction
  10. 2.0 Using ByCLIENT.RXX
  11. 2.1 A Simple Example
  12. 2.2 Syntax of a .USR file
  13. 2.3 Specifying IDs
  14. 3.0 Miscellaneous Notes
  15. 4.0 A sample
  16.                         --------    ----   ---------
  17.  
  18. 1.0) Introduction
  19.  
  20. ByCLIENT.RXX is an "INTERPRETable" SRE-http addon that simplifies the
  21. delivery of "client specific" documents to your WWW clients.  Using
  22. ByCLIENT.RXX requires creation of special instructions files (.USR files)
  23. that identify which files should be delivered to which clients. After
  24. identifying the client, ByCLIENT will use this .USR file to ascertain
  25. a file to be INCLUDEd in the document.
  26.  
  27. Identification of clients is based on a number of possible pieces of
  28. information, including: special ByCLIENT cookies, the SRE-http "client
  29. privileges", or the IP namd and address.  The .USR file can freely mix
  30. these different "client identification" mechanisms.
  31.  
  32.  
  33.                         --------    ----   ---------
  34.  
  35. 2.0) Using ByCLIENT.RXX
  36.  
  37. To use ByCLIENT.RXX, you just need to include
  38.  
  39.     <!-- INTERPRET FILE ByCLIENT.RXX -->
  40.  
  41. "SSI keyphrases" in a "requesting document". When this "requesting document" 
  42. is requested by a client,  SRE-http will call (actually, SRE-http will 
  43. read and "interpret") ByCLIENT.RXX. ByCLIENT.RXX will find a .USR
  44. file (with the same name as the "requesting document"), match the
  45. "client" with an "rule" in this .USR file, and INCLUDE the "client
  46. specific document" this rule points to.
  47.  
  48. Inclusion of these client specific documents is accomplished via a
  49. <!-- #INCLUDE file=docname >  or <!-- #INCLUDE virtual=docname > 
  50. server-side includes (where docname is the "client specific document"
  51. specified in the .USR file).  Typically, these files will contain information
  52. relevant to a subset of clients (say, "intranet" versus "extranet" clients).
  53.  
  54. In addition to the (unavoidable) task of writing these client specific 
  55. documents, use of ByCLIENT requires creation of .USR files. These .USR
  56. files consist of a series of matching "rules". Each rule contains two sets
  57. of information: the file to use, and the clients for whom this file should
  58. be used.  
  59.    * File to use: The file to use should be specified relative to the
  60.      web space of your server, or relative to the location of the
  61.      "requesting document". 
  62.     
  63.    * Client identification: Clients may be identified via cookies,
  64.      client privileges, or IP address.   
  65.        Cookies: If a BYCLIENT cookie was passed to the server, it's value
  66.        will be used as a client-id. 
  67.        Client privileges: Each of the various "client privileges" will
  68.        be used to identify 
  69.        IP address: The IP address (numeric or name) can be used to 
  70.        identify a client -- with wildcards used to specify entire domains.
  71.  
  72.     Note that a client may be identified several times; say, through
  73.     a BYCLIENT cookie, through several client privileges, and through
  74.     several wild-card'ed domains.  In such cases, the cookie "identification"
  75.     is tried first, followed by the client privileges, followed by
  76.     the IP address.  
  77.  
  78. As this point, a simple example should help....
  79.  
  80.                         --------    ----   ---------
  81.  
  82. 2.1) A Simple Example
  83.  
  84. Let's assume the following URL on your home page:
  85.     <A href="/NEWS.HTM">Today's news? </a>
  86. Let's also assume that /NEWS.HTM points to D:\WWW\NEWS.HTM,
  87. and that D:\WWW\NEWS.HTM contains the following:
  88.  
  89.    <h2>Local news</h2>
  90.       <!-- INTERPRET FILE ByCLIENT.RXX -->
  91.    <h2> National news </h2>
  92.  
  93. Thus, the "local news" will be "client specific".
  94.  
  95. SRE-http will invoke ByCLIENT.RXX, and ByCLIENT.RXX will look for
  96. a file named D:\WWW\NEWS.USR. NEWS.USR should contain "rules" used
  97. to determine what file this client should get. For example:
  98.  
  99. ; ByCLIENT .USR file for /NEWS.HTM
  100. COOKIE: /stories/news1.inc     class1 class2
  101. PRIVILEGE: /stories/news1.inc  priv1 priv2 priv3
  102. PRIVILEGE: /stories/newsA.ink  privas privb
  103. IP: /stories/news1.inc   *.mysite.net *.newsdog.com *.131.51
  104. IP: /stories/newsa.ink   *.hersite.net *.newsdog.com *.31.61
  105. COOKIE: /stories/newsA.ink     classA classB
  106.  
  107. These rules select between two files: D:\WWW\STORIES\NEWS1.INC and
  108. D:\WWW\STORIES\NEWSA.INK.  Each rule consists of three components:
  109. the "type" of rule, the file, and a space delimited list of client
  110. ids.  Note that lines beginning with a ; are comments.
  111.  
  112. The actual file "INCLUDED" will depend on the values of the ByCLIENT
  113. cookie, the client privileges, and the client's IP address.  For example:
  114.  
  115.   *  If BYCLIENT=CLASS2 and the client's IP name is JOHN.MYSITE.NET
  116.         then D:\WWW\STORIES\NEWS1.INC will be used.
  117.  
  118.   *  If BYCLIENT=CLASS6 and the client has a PRIVB privilege; 
  119.         then D:\WWW\STORIES\NEWSA.INK will be used.
  120.  
  121.    * If there is no BYCLIENT cookie, and the client's IP name 
  122.      is JOHN.NEWSDOG.COM;
  123.         then D:\WWW\STORIES\NEWS1.INC will be used.
  124.  
  125. The key to using ByCLIENT is to understand how the .USR file identifies
  126. clients. The next section discusses the syntax of these .USR files.
  127.  
  128.                         --------    ----   ---------
  129.  
  130. 2.2) Syntax of a .USR file
  131.  
  132.  
  133. The .USR file is used to match a client to a filename. This filename
  134. (which is specified using a "selector" style of name) will then be
  135. #INCLUDEd in the requesting document.
  136.  
  137. When an <!-- INTERPRET ByCLIENT.RXX --> keyphrase is encountered,
  138. ByCLIENT will look in the "requesting documents" directory 
  139. for a file with a .USR extension. If no such file can be found, nothing
  140. is done (i.e; the <!--INTERPRET  ByCLIENT.RXX --> keyphrase is ignored).
  141.  
  142. NOTE:  You can specify an explicit .USR file to use. For example:
  143.              <!-- INTERPRET ByCLIENT.RXX  buttons/helplink.usr --> 
  144.       (see this section's notes for further details).
  145.  
  146. Note:
  147.   
  148.   *  To specify an explicit .USR file, place it's name after the 
  149.      ByCLIENT.RXX.  For example:
  150.              <!-- INTERPRET ByCLIENT.RXX /order/form1.usr --> 
  151.      This can be  quite useful if you have a commonly used file
  152.      (say, a button bar), or if you want to include several files 
  153.      (say, several different tables in an otherwise generic document).
  154.  
  155.      Note that the location of this "explicit" .USR file is
  156.      either relative to the "requested document's directory" (if the
  157.      filename does NOT begin with a /). When this filename starts with a
  158.      /, it is interpreted using the standard SRE-http selector rules 
  159.      (i.e.; using the data directory and virtual directories).
  160.       
  161. The .USR file is an ascii (text) file.  Each line of the .USR file 
  162. is a "rule" that is used to match clients to INCLUDEable files.
  163.  
  164. The syntax of these rules is:
  165.    type  filename   id1 ... idn
  166. where
  167.   type:  The type of "client ID". Three types are recognized:
  168.          * COOKIE: The value of the "ByCLIENT" cookie (if one exists).
  169.          * PRIVILEGE: The values of the SRE-http client privileges
  170.          * IP: IP addresses (either numeric or name)
  171.  
  172.   filename: The "selector" style filename of the file to be #INCLUDEd.
  173.             This file is assumed to be either
  174.                a) relative to the requesting document's directory, or 
  175.                b) relative to the root of the web tree, or in a virtual
  176.                   directory
  177.            In particular, if the filename does NOT start with a /, then
  178.            a is used. If the filename DOES start with a /, then b is used.
  179.            In other words:
  180.              foo/bar.1 is equivalent to <!-- #include file="foo/bar.1" -->
  181.            and
  182.              /foo/bar.1 is equivalent to <!-- #include virtual="foo/bar.1" -->
  183.  
  184.   id1 ..idn : A space delimited list of "client identifiers". The values
  185.               will depend on the type.  Thus, if type=IP, then these "ids"
  186.               should be IP addresses (either name or number). Or, if
  187.               type=COOKIE, then these "ids" should be possible values
  188.               of a ByCLIENT cookie.
  189.  
  190. In addition to these three rules, lines starting with semi-colons
  191. are treated as comments, and empty lines are ignored.
  192.  
  193. 2.3) Specifying IDs
  194.  
  195. When looking for a rule with a matching ID, ByCLIENT does the following:
  196.  
  197. 1) Checks for a ByCLIENT cookie (note that the case of ByCLIENT is ignored).
  198.    All COOKIE "rules" are then checked.  The first rule that contains
  199.    an id that matches ByCLIENT will be used, provided that the 
  200.    filename (contained in the rule) exists. 
  201.    If it does not exist, the next COOKIE rule is used.
  202.  
  203. 2) If no matching COOKIE rule can be found, the PRIVILEGE rules are used.
  204.    Since there may be many client privileges, each id is compared against
  205.    all the client privileges -- if a match is found, then the rule
  206.    is used. As with COOKIE rules, if the filename does not exist, the
  207.    next PRIVILEGE rule is used.
  208.  
  209. 3) If no matching PRIVILEGE rule can be found, the IP rules will be checked.
  210.    IP ids can either by numeric (i.e.; 121.55.12.5) or name (i.e.; 
  211.    JOE.COWS.ORG).  The IP ids can also contain * wildcards.
  212.  
  213. 4) If no matching PRIVILEGE rule can be found, 
  214.    the <!-- INTERPRET ByCLIENT.RXX -->  SSI keyphrase is ignored.
  215.  
  216.  
  217. 3.0) Misellaneous Notes
  218.  
  219.   *  Please be aware that within a "type" of rules, rules nearer the
  220.      top of the file are used in precedence to rules that are lower
  221.      in the file. Conversely, COOKIE rules are always used before
  222.      PRIVILEGE (and IP) rules, regardless of where they appear.
  223.  
  224.   *  There are a number of ways of specifying "cookies".  The easiest
  225.      way is to use a META element in the <HEAD> section of an HTML document
  226.      that is examined before the "requesting document" is loaded.
  227.      For example, you might include:
  228.            <meta http-equiv="Set-Cookie:" content="ByCLIENT=USER_REG">
  229.      on a "registration" page that contains a link to the "requesting
  230.      document" (that is, a link to the document containing the
  231.      <!-- INTERPRET FILE ByCLIENT.RXX -->)
  232.  
  233.   *  Wildcard characters (the *, several of which may appear) used in IP "ids"
  234.      are used in a standard string-matching fashion. 
  235.      Thus, an id of *.121.55 would match 5.21.121.55 and would match 62.121.55.
  236.  
  237.   *  Wildcard characters can NOT be used with PRIVILEGE rules, but can
  238.      be used with COOKIE rules.
  239.  
  240.   *  For a more dynamic form of "client customization", that makes extensive 
  241.      use of cookies, consider the CUSTOMIZ addon. CUSTOMIZ can be on obtained 
  242.      from http://www.srehttp.org/apps/customiz/.
  243.   
  244.   *  Reminder: you can modify client privileges by changing "user"
  245.      entries in the USERS.IN file.  This, however, requires the
  246.      client to login.  Alternatively, the PUBLIC_PRIVS, INHOUSE_PRIVS,
  247.      and INHOUSEIPS. entries allow you to set privileges on a 
  248.      global and on a per-IP-address basis.
  249.  
  250.   *  It's a good idea to specify a "default" rule as the last entry in a 
  251.      .USR file. For example:
  252.          IP  /stories/news0.htm  *
  253.      will cause /stories/news0.htm to be used for ALL IP addresses.
  254.  
  255.                         --------    ----   ---------
  256. 4) Demo
  257.  
  258. The following simple sample can be used to demo ByClient.RXX. 
  259. To use this demo:
  260.  
  261.  a)With your favorite text editor, cut out the code and create 
  262.    the indicated files, 
  263.  b)Request /ByClient.sht
  264.    or, to first set a cookie, 
  265.  c) request /ByClien2.Sht?cookie_value
  266.       (where cookie_value could be COOK1 or COOK2)
  267.     and then request /ByClient.sht
  268.  
  269.  
  270. 1) BYCLIENT.SHT (in your GoServe data directory):
  271.                   ------- cut here ---------------
  272. <!DOCTYPE HTML PUBLIC "-//W3 Organization//DTD W3 HTML 2.0//EN">
  273. <html>
  274. <head>
  275. <title>Test ByCLIENT</title>
  276. </head>
  277. <body>
  278. <h1>Test of ByClient</h1>
  279.  
  280. <!-- This will cause the "client specific" file (BYC.0...BYC.5)
  281.      to be INCLUDEd -->
  282.  
  283. Welcome.<p>
  284. <!-- interpret file $ byclient.rxx  -->
  285.  
  286. </body>
  287. </html>
  288.                  ------- cut here ---------------
  289.  
  290. 2) ByCLIEN2.SHT (in your goserve data directory)
  291.                   ------- cut here ---------------
  292. <html><head>
  293. <title>SEt ByClient Cookie </title>
  294. <meta http-equiv="Set-cookie:" content="ByClient=<!-- option 1-->" >
  295. </head><body>
  296. <h1>Set ByClient Cookie</h1>
  297. <p> Your ByClient cookie has been set to <!-- option 1-->
  298. <hr>
  299. <b>Note:</b> To set client, use a selector of:
  300.             <tt>/byclien2.htm?cookie_value</tt>
  301. </body></html>
  302.                   ------- cut here ---------------
  303.  
  304. 3)ByCLIENT.USR -- same directory as byclient.sht
  305.                   ------- cut here ---------------
  306. ;sample .USR file for ByClient
  307. ip byc.1 127.*.*
  308. cookie byc.2 cook2 owner
  309. cookie byc.3 cook23
  310. priv byc.4   byclientp
  311. priv byc.5   superuser
  312. ip byc.0 *
  313.                   ------- cut here ---------------
  314.  
  315. 4) Create Byc.0, byc.1, to byc.5 in the same directory as 
  316.    byclient.sht.
  317.    For exampe, simple one line files can be used:
  318. BYC.0  :  This is the default message
  319. BYC.1  :  This is the message for loopback clients (on 127.*.*)
  320. BYC.2  :  Message for clients with ByClient cookie of <b>cook2</b> or <b>owner</b>
  321. BYC.3  :  Message for clients with ByClient cookie of <b>cook23</b> 
  322. BYC.4  :  Message for clients with a <b>byclientp</b> privilege
  323. BYC.5  :  Message for <b>SUPERUSER</b>s
  324.  
  325. Reminder: the above entries represent 6 seperate files!
  326.  
  327.                         --------    ----   ---------
  328.  
  329. .End of document.
  330.