home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / ADV_OPTS.DOC < prev    next >
Text File  |  2001-03-27  |  20KB  |  511 lines
  1. 1 November 1999
  2.  
  3. Abstract:
  4.    SRE-http's SEL-specific "advanced options" are used for a variety
  5.    of purposes, including setting parameters, enabling less-frequently
  6.    used options, and executing mid-filter procedures.
  7.  
  8. 1. Introdution
  9. 2. Specifying advanced options
  10. 3. The advanced options
  11. 3a) EXEC Commands
  12. 3b) HEADER and RESPONSE directives.
  13.  
  14.                 --------------------------------
  15.  
  16. 1) Introduction
  17.  
  18. SRE-http's selector specific advanced-options provides a set of 
  19. less-frequently needed, "advanced-options" to the ambitious webmaster.
  20. These advanced-options include:
  21.  * execution of "mid-filter" procedures,
  22.  * customization of response headers
  23.  * suppression of specific server side includes.
  24.  * selector specific mime type
  25.  * selector specific replacement-rules
  26.  * set the FIX_EXPIRE, CONTENT_MD5, PRE_REPLY, and other parameters
  27.  * enabling simple hit-metering
  28.  * enable or disable encryption
  29.  * specify the maximum number of simultaneous users of a resource
  30.  * in the future, additional features may be added.
  31.  
  32.                 --------------------------------
  33.  
  34. 2) Specifying advanced-options 
  35.  
  36. There are two ways of specifying selector-specific advanced options.
  37.  
  38. a) Using an advanced options file.
  39.    You can specify a selector-specific advanced option file either in 
  40.    ACCESS.IN or in ATTRIBS.CFG -- you can use the intermediate
  41.    configurator to do this (or see IN_FILES.DOC for the details). 
  42.    By default, these advanced options files should be located in, or under, 
  43.    the DATA\ subdirectory of your GoServe working directory 
  44.    (technical note: it will be in or under SRE-http's WORKDATA_DIR directory).
  45.  
  46.    Note:there is NO global (default) advanced-options file.
  47.  
  48. b) Specifying options in ATTRIBS.CFG
  49.    In the usual case where one needs to set a few advanced options,
  50.    the use of the Option: lines in ATTRIBS.CFG is easier then
  51.    specification of a seperate advanced options file.  
  52.    Note that for any REALM specified in ATTRIBS.CFG you can 
  53.    use both an advanced options file line (ADVOPT_FILE)
  54.    and one (or several) Options: lines.
  55.  
  56. Some examples::
  57.   * Assuming that your SRE-http "WORKDATA_DIR" directory is
  58.     D:\GOSERVE\DATA, the following entry in ACCESS.IN:
  59.         /SAMPLES/* *   ,     ,  MYREALM  ,   , ADV_OPT.CTL
  60.    tells SRE-http to use the D:\GOSERVE\DATA\ADV_OPT.CTL advanced
  61.    options file for all selectors that match /SAMPLES/*
  62.  
  63.   * The following entry in ATTRIBS.CGG could also be used to set some 
  64.     advanced options (for all selectors that match /SAMPLES/*):
  65.        REALM: Myrealm
  66.        RULE: /SAMPLES/*
  67.        Option: header add X-Grader: this is  mediocre resource
  68.        Option: set fix_expire 0.1
  69.  
  70.                 --------------------------------
  71.  
  72. 3) The advanced options
  73.  
  74. There are several types of selector-specific advanced options:
  75.  
  76.   1) EXEC commands  -- execute an external REXX procedure.
  77.   2) HEADER and RESPONSE directives -- specify a custom response header
  78.   3) SSI_suppression directives -- suppress specific SSI actions.
  79.   4) Set MIME type
  80.   5) Replacement rules
  81.   6) Set a few variables
  82.   7) Enabling hit-metering 
  83.   8) Controlling the maximum number of simultaneous users of a resource
  84.  
  85. The following documents how to use these options.  We also recommend perusing 
  86. the ADV_OPTS.CTL and ADV_OPTS.CMD sample files.
  87.  
  88. Notes:
  89.  * each of these options should appear:
  90.     i) on a single line in  your advanced option file, or 
  91.     ii) in ATTRIBS.CFG 
  92.  
  93.  * lines in an advanced option file that begin with ; are comments
  94.  
  95.  
  96. 3a) EXEC Commands
  97.  
  98. EXEC entries are used to execute external REXX procedures.  This execution
  99. occurs just before the "verb is processed", and after all "selector
  100. modifications/redirections" and "access control checks."
  101.  
  102.     In a sense, the EXEC commands can be thought of as "mid-filter" hook,
  103.     occuring after the (optional) pre-filter, and before the (optional)
  104.     "pre-reply" procedure.
  105.  
  106. Example:
  107.   EXEC ADV_OPTS.CMD  Hello from job 1.
  108.  
  109. In this example, ADV_OPTS.CMD should be in the GoServe working directory.
  110.  
  111. Note that ADV_OPTS will be sent a set of variables:
  112.  ARGUMENT:
  113.      The "argument" following the procedure-file name.  This may contain
  114.      commas (a comma containing ARGUMENT does NOT result in multiple
  115.      arguments being sent to the called procedure).
  116.      In the above example, ARGUMENT would be "Hello from job 1." (without
  117.      the quotes).
  118.  SOURCE:
  119.     The GoServe "source" line
  120.  REQUEST:
  121.     The GoServe request line
  122.  SEL:
  123.    The (SRE-http) modified selector
  124.  VERBOSE:
  125.    The SRE-http VERBOSE parameter
  126.  SERVERNAME:
  127.    The name of the server processing this request (might be an alias)
  128.  HOST_NICKNAME:
  129.    SRE-http "host nickname" for the server processing this request
  130.  DATA_DIRECTORY:
  131.    The default data directory (might be servername dependent)
  132.  HOME_DIRECTORY:
  133.    The ~ replacement directory (the "home" directory).
  134.  TEMP_DIRECTORY:
  135.    The SRE-http TEMPDATA_DIR "temporary files" directory
  136.  
  137. These external procedures MAY issue GoServe completion codes. If they do,
  138. they should return
  139.   status_code bytes_sent
  140. (i.e.; 200 15122)
  141. If they do not, they should return a 0.
  142. All other returns are ignored.
  143.  
  144. Note that ADV_OPTS.CMD contains a simple example of such an external procedure.
  145.  
  146. Hint: one use of EXEC is to support HTTP M-extensions, as described in
  147.       the "HTTP Extensions" Internet-Draft. Otherwise, these 
  148.       M-extensions will result in a 510 error return.
  149.  
  150.  
  151. 3b) HEADER and RESPONSE directives.
  152.  
  153. You can include HEADER and RESPONSE entries -- they will be sent almost
  154. verbatim to GoServe.
  155.  
  156. This response header customization is only available for GET and HEAD
  157. requests that invoke a file transferal (including HTML documents
  158. with server side includes).
  159.     That is, for "server side processing" requests (such as CGI-BIN
  160.     scripts, SRE-http addons, PUT and DELETE requests, and imagemaps)
  161.     HEADER and RESPONSE entries will NOT be used.
  162.  
  163. As a convenience, SRE-http will perform a few substitutions on HEADER
  164. and RESPONSE entries:
  165.   $GMT : The current  GMT day, date and time.
  166.   $SERVERNAME: The "server name" of the server processing this request
  167.   $SIZE: The number of bytes to be sent
  168.   $CODE: The status code (almost always 200)
  169.  
  170. Examples:
  171.   response HTTP/1.1 406 Variant not available
  172.   header add X-Webmaster-Name: Daniel Platypus
  173.   header drop expires
  174.   header add X-comment:  X- headers are created by SRE-http
  175.   header add X-Our-server: $servername
  176.   header add X-Size-1: this is $size size
  177.   header add X-Code-1: this is $code code
  178.  
  179. Notes:
  180.  *  This customization is akin to ICS's "meta information".
  181.  *  Headers specified using advanced options override automatically
  182.     generated headers. For example, if  a cache-control header 
  183.     is specified as an advanced option, then the automatically
  184.     generated cache-control header will not be used.
  185.  *  The HEADER DROP will drop a header (if one exists).  This is
  186.     cumulative, so that...
  187.         HEADER DROP EXPIRES
  188.         HEADER ADD Expires: not-now
  189.     yields an
  190.          Expires: not-now
  191.     response header.
  192.  *  HEADER ADD is cumulative -- if the named header exists, the new value
  193.     is appended. Thus, to replace a header, you should use HEADER DROP followed
  194.     by HEADER ADD.
  195.  *  See GOSERVE.DOC for a description of the HEADER and RESPONSE GoServe
  196.     directives.
  197.  *  When adding a header, be sure to include an ADD after the HEADER
  198.  *  CACHE-CONTROL is special -- it is not cumulative.
  199.     To drop it, specify
  200.         HEADER ADD Cache-Control: 0
  201.     To change it, specify
  202.         HEADER ADD Cache-Control: my_cache_control
  203.         
  204.  
  205. 3c) Server Side Include Suppression
  206.  
  207. Although you can suppress all server side includes (either for all documents,
  208. or on a SEL-specific basis), you may wish to only suppress a select set of
  209. these includes. In particular, you may wish to supress HEADERS and FOOTERS
  210. for a portion of  your HTML documents.  This can be easily done with
  211. the various server side include suppression options.
  212.  
  213. The available options are:
  214.   ssi_no_cache     : suppress caching (similar to a <!-- CACHE NO -->
  215.                      keyphrase)
  216.   ssi_no_header    : Do NOT include HEADERS lines
  217.   ssi_no_footer    : Do NOT include FOOTERS lines
  218.   ssi_no_replace   : Do NOT process <!-- REPLACE varname --> keyphrases
  219.   ssi_no_include   : Do NOT process <!-- INCLUDE filename --> keyphrases
  220.   ssi_no_option    : Do NOT process <!-- OPTION n --> keyphrases
  221.   ssi_no_interpret : Do NOT process <!-- INTERPRET FILE filename --> or
  222.                      <!-- INTERPRET CODE  xxx ;yyy --> keyphrases.
  223.   ssi_no_select    : Do NOT process <!-- SELECT xxx --> ... <!-- SELECT END -->
  224.                      keyphrases
  225.   ssi_no_#filestat : Do NOT process <!-- #FLASTMOD ... --> or <!-- #FSIZE ... -->
  226.                      keyphrases
  227.   ssi_no_#config   : Do NOT process <!-- #CONFIG ... --> keyphrases
  228.   ssi_no_#echo     : Do NOT process <!-- #ECHO ... --> keyphrases
  229.   ssi_no_#include  : Do NOT process <!-- #INCLUDE ... --> keyphrases
  230.   ssi_no_#exec     : Do NOT process <!-- #EXEC ... --> keyphrases
  231.  
  232. Note that these options should appear one-per-line.
  233.  
  234. Examples:
  235.   ssi_no_cache
  236.   ssi_no_header
  237.   ssi_no_footer
  238.   ssi_no_select
  239.   ssi_no_#echo
  240.   ssi_no_#exec
  241.  
  242. 3d) Mime types
  243.  
  244. You can specify the mime type for this (these) selector(s). Just enter
  245.    MIME type/subtype
  246.  
  247. For example:
  248. MIME  text/plain
  249. MIME  image/jpg
  250.  
  251. You should have, at most, one MIME line per selector (latter entries are 
  252. ignored).
  253.  
  254.  
  255. 3e) Replacement rules
  256.  
  257. You can specify selector specific "replacement rules".  These will be
  258. used instead of the generic REPLACE_RULES. replacement rules (set in
  259. INITFILT.80).  
  260.  
  261. The syntax is
  262. REPLACE_RULES=old_string==new_string
  263.  
  264. Notes:
  265.     * Spaces will NOT be stripped from either old_string or new_string
  266.       -- thus "invisible spaces" at the end of new_string will be retained.
  267.     * Note the use of == as a seperator between old_string and new_string.
  268.     * Unlike REPLACE_RULES.n (in INITFILT.80), do NOT include a "stem";
  269.       the order of appearance is the order of processing
  270.     * If you do NOT specify any replacement rules here, generic ones 
  271.       (specified in INITFILT.80) will be used.
  272.  
  273. Example:
  274.  REPLACE_RULES=$(==<!-- $ customiz 
  275.  REPLACE_RULES=)$== -->
  276.  
  277.  
  278. Hint: Using Replace_rules and Load Balancing.
  279.  
  280.  Replace rules can come in handy when you are load balancing to subsidiary-
  281.  sites. In order to guarantee that all requests pass through a "main-site", 
  282.  you may have to include a <BASE href="main.site.url"> element in the 
  283.  <HEAD> section of HTML documents on subsidiary-sites.  Since adding these 
  284.  elements may be tedious, the following REPLACE_RULES can be used instead:
  285.  
  286.     REPLACE_RULES=</HEAD>==<BASE href="http://main.site.url"> </HEAD>
  287.  
  288.  where main.site.url should be the IP address of the main-site.
  289.  
  290.  
  291. 3f) Setting variables
  292.  
  293. You can set several SRE-http variables on a request specific basis. 
  294. These are:
  295.    CG_GZIP (enable/disable on-the-fly GZIP content encoding)
  296.    CONTENT_MD5 (add an Content-MD5 response header) 
  297.    FIX_EXPIRE (add an offset to an otherwise immediate expiration).
  298.    PRE_REPLY (suppress or enable the use of a "pre-reply" procedure).
  299.    ENCRYPT (enable or disable encryption)
  300.    DELTA_ENCODING (enable delta encoding)
  301.    DTemplate (specify a delta encoding "DTemplate")
  302.    DCluster (specify a delta encoding "DCluster")
  303.  
  304. The syntax to use is: 
  305.    SET varname value
  306. where varname is either CONTENT_MD5, FIX_EXPIRE, PRE_REPLY, or ENCRYPT
  307.  
  308. For example:
  309.    SET CONTENT_MD5 0         (suppress generation of Content-MD5 header)
  310.    SET CONTENT_MD5 1
  311.    SET CONTENT_MD5 2        (use MD5.EXE, assuming EMX is avaiable)
  312.  
  313.    SET FIX_EXPIRE  0
  314.    SET FIX_EXPIRE 0.66
  315.    SET PRE_REPLY 0  
  316.    SET ENCRYPT SRE_A   
  317.    
  318.    SET DELTA_ENCODING 1    (1 means enable, 0 means disable)
  319.    SET DTEMPLATE  /quotes/?      
  320.    SET DCLUSTER  /quotes/basequote.1
  321.  
  322.    SET CE_GZIP 1    (enable on-the-fly GZIP content encoding)
  323.    SET CE_GZIP 0    (disable on-the-fly GZIP content encoding)
  324.  
  325. Notes: 
  326.   * PRE_REPLY can take the following values:
  327.  
  328.         0 - suppress the pre-reply procedure 
  329.             This is not necessary if the PRE_REPLY_PROCEDURE='!filename'
  330.             format is used.            
  331.         1 - use a "selector specific" pre-reply procedure.
  332.             This only has an effect when the "!filename" (selector specific)
  333.             format of PRE_REPLY_PROCEDURE is used; it is not necessary when the
  334.             PRE_REPLY_PROCEDURE='filename' format is used.            
  335.  
  336.   * If PRE_REPLY_PROCEDURE=0, then PRE_REPLY has no effect.
  337.  
  338.   * PRE_REPLY_PROCECURE is set in INIT_STA.80 (see INITFILT.DOC, or 
  339.     PREREPLY.DOC, for more details).
  340.     
  341.   * If encryption is not enabled (ENABLE_ENCRYPTION=0) then SET ENCRYPT
  342.     has no effect.
  343.  
  344.   * SET ENCRYPT 0 means "never encrypt" -- this will override a !ENCRYPT
  345.     "special directive" (that is prepended to the selector)
  346.  
  347.   * SET ENCRYPT (without any other argument) is a shorthand 
  348.     for SET ENCRYPT SRE_A
  349.  
  350.   * DELTA_ENCODING is used when the default DELTA_ENCODING (set in INIT_STA.80)
  351.     is equal to 1 or 2 (if the default DELTA_ENCODING=0, then DELTA_ENCODING
  352.     is never attempted)
  353.  
  354.   * DCLUSTER and DTEMPLATE are used to specify a Dcluster or Dtemplate
  355.     request header (they will be included verbatim).  These response
  356.     headers are used to improve delta-encoding (as described in DELTA.DOC).
  357.  
  358.   * CE_GZIP overrides the CE_GZIP parameter set in INIT_STA.80
  359.    
  360. 3g) Enabling hit-metering.
  361.  
  362. In order to get some measure of the number of times proxy servers
  363. are resolving requests for resources from your site, SRE-http
  364. supports a form of simple-hit-metering.  This algorithim (based
  365. on RFC 2227) depends on proxies reporting their activity
  366. to your server.  
  367.  
  368. To enable this, you must specify a METER advanced option.
  369. When METER is specified (and when a proxy says that it is willing to
  370. support hit metering), SRE-http will:
  371.   * include a METER: response header, and
  372.   * will watch for special METER: request headers. 
  373. The information in these METER: request headers is written to HITMETER.CNT. 
  374.  
  375. The syntax of this option is:
  376.   METER=[options]
  377. where:
  378.   options are a set of optional modifiers, that are described in RFC2227. 
  379.  
  380. These options  include directives on cache lifetime, and on when and how
  381. to report hits.  Alternatively, you can not specify options, which
  382. will enable hit-metering, but not effect cache behavior.
  383.  
  384. Examples:
  385.    METER=
  386.    METER= max-uses=3, dont-report
  387.  
  388. Note that if you do not specify a METER= option, then hit-metering
  389. will not be attempted (even if a proxy reports that it is willing
  390. to provide hit-metering).
  391.  
  392. For further details, please HITMETER.DOC, and see the description of
  393. the PROXY_CACHE variable in INITFILT.DOC.
  394.  
  395.  
  396. 3h) Controlling the maximum number of simultaneous users of a resource
  397.  
  398.  
  399. In order to selectively control the intensity of use of your server's
  400. resources (such as CPU intenstive scripts and addons), you can
  401. specify an 'intensity of use' option".  Basically, if more then this number 
  402. of requests for this resources are currently active, the server will respond 
  403. with a "Server busy, try again in a few minutes".
  404.  
  405. The syntax is:
  406.     MAXUSER  class = n ; failure=maxuser_fail_file retryafter
  407. where:
  408.   class : identifies a "class" of resources. This class can be
  409.           unique to the selector, or can be shared by several selectors
  410.           (say, due to several MAXUSER options in several advanced options 
  411.           files). These "classes" are similar to "realms", but are only used
  412.           by this MAXUSER option
  413.           If not specified, a "default" class is used.
  414.   n :  n is the maximum number of simultaneous users allowed.
  415.   maxuser_fail_file: Optional. If specified, maxuser_fail_file is used when
  416.             maxuser is not satisfied. Maxuser_fail_file should be a fully 
  417.             qualified file name, or a file name relative to your GoServe
  418.             working directory.
  419.   retryafter: Optional. Number of seconds to use in a Retry-After header.
  420.               If specified, a Retry-After reponse header is added to the
  421.               maxuser_fail_file response (http/1.1 clients can use Retry-After
  422.               response headers to automatically re-request the resource).                  
  423.  
  424. Example (as may appear in attribs.cfg):
  425.  
  426.   realm: foo1
  427.   rule: /addon/gif_text*
  428.   option: MAXUSER gifProgs =  3 ; failure=nogif.htm 60
  429.  
  430.   realm: foo2
  431.   rule: /addon/blendgif*
  432.   option: MAXUSER gifProgs =  1
  433.  
  434. Notes:
  435.  
  436.   * "class" is case insensitive.
  437.  
  438.   * a semi-colon (:) MUST appear before a failure=maxuser_fail_file
  439.  
  440.   * if a MAXUSER_FAIL_FILE is not specified ,a generic "server is busy" 
  441.     response will be returned (when the MAXUSER is not satisfied).
  442.  
  443.   *   As with the LOGON_FAIL_FILE, when the MAXUSER_FAIL_FILE is an HTML 
  444.       document, server side includes are NOT attempted. However, a 
  445.       few special substitutions will occur (when the MAXUSER_FAIL_FILE 
  446.       is an HTML document):
  447.     <!--#URL--> phrases are substituted with the request selector.
  448.     <!--#SERVER--> phrases are substituted with the servername.
  449.     <!-- #WEBMASTER --> phrases are substituted with the WEBMASTER variable.
  450.     <!-- #MESSAGE --> phrases are substituted with a short description
  451.                      of the reason for failure
  452.     <!-- #LINK --> phrases are substituted with a URL which points
  453.                    back to this resource
  454.    
  455.   * MAXUSER is defined on a selector specific basis, but the maximum users
  456.     are defined across a  "class" of selectors. Thus, one could limit 
  457.     users of a set of resources (say, only  2 simultaneous users of  
  458.     any one of several helper apps).
  459.  
  460.  *  The fact that n can vary for each of several selectors assigned to a "class"
  461.     lends some flexibilty.
  462.  
  463.  *  In the above example,
  464.      i) blendgif will not be started if any instance of blendgif or gif_text 
  465.         is currently active
  466.     ii) up to 3 instances of gif_text are  alllowed 
  467.    iii) or 1 instance of blendgif and 2 instances of gif_text (assuming that
  468.         blendgif was started first)
  469.  
  470.  * CAUTION: SRE-http uses mutex semaphores to implement this MAXUSER feature.
  471.             Unfortunately, REXXLIB's implementation of mutex semaphores is
  472.             somewhat buggy; and there may be cases where "ghost semaphores"
  473.             will interfere with program flow. 
  474.             SRE-http attempts to deal with this (by using alternative 
  475.             semaphores when required). However, on very dynamic
  476.             and unstable sites (where threads are being opened and closed
  477.             rapidly), this workaround may not be effective. If problems arise
  478.             that can be traced to the use of MAXUSERS, you can
  479.                 * enable more thorough bug reporting by setting VERBOSE=3
  480.                   (in INITFILT.80)
  481.                 * view these bug reports by running PMPRINTF
  482.                 * contact the author (Daniel Hellerstein) for advice
  483.                  (danielh@crosslink.net)
  484.      
  485. 4) A sample "advanced options file"
  486.  
  487. The following is a sample of an advanced options file. You might also want
  488. to examine ADV_OPTS.CTL.
  489.  
  490. ;------------- Begin Example ------------
  491. ; call the sample external procedure
  492. exec adv_opts.cmd This is an argument , with commas embedded.
  493. ;
  494. ; add a custom response header
  495. header add X-Webmaster-Name: Timothy Platypus
  496. ;
  497. ; Suppress headers, footers, and server side "excludes"
  498. ssi_no_header
  499. ssi_no_footer
  500. ssi_no_select
  501. replace_rules= C.== $ Customiz 
  502.  
  503. ; suppress content-md5 header
  504. set content_md5 0
  505.  
  506. ;------------- End Example ------------
  507.  
  508.  
  509.  
  510. ---- End of document
  511.