home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13g.zip / ADV_OPTS.DOC < prev    next >
Text File  |  1999-06-28  |  13KB  |  356 lines
  1. 14 June 1999
  2.  
  3. Description of SRE-http's SEL-specific "advanced options"
  4.  
  5. 1) Introduction
  6.  
  7. SRE-http's selector specific advanced-options provides a set of 
  8. less-frequently needed, "advanced-options" to the ambitious webmaster.
  9. These advanced-options include:
  10.  * execution of "mid-filter" procedures,
  11.  * customization of response headers
  12.  * suppression of specific server side includes.
  13.  * selector specific mime type
  14.  * selector specific replacement-rules
  15.  * set the FIX_EXPIRE, CONTENT_MD5, and PRE_REPLY parameters
  16.  * enabling simple hit-metering
  17.  * enable or disable encryption
  18.  * in the future, additional features may be added.
  19.  
  20.  
  21. 2) Specifying advanced-options 
  22.  
  23. There are two ways of specifying selector-specific advanced optionsfile.
  24.  
  25. a) Using an advanced options file.
  26.    You can specify a selector-specific advanced option file either in 
  27.    ACCESS.IN or in ATTRIBS.CFG -- you can use the intermediate
  28.    configurator to do this (or see IN_FILES.DOC for the details). 
  29.    By default, these files should be located in, or under, the DATA\
  30.    subdirectory of your GoServe working directory (technical note:
  31.    it will be in or under the SRE-http WORKDATA_DIR directory).
  32.  
  33.    Note:there is NO global (default) advanced-options file.
  34.  
  35. b)Specifying options in ATTRIBS.CFG
  36.    In the usual case where one needs to set a few advanced options,
  37.    the use of the Option: lines in ATTRIBS.CFG is easier then
  38.    specification of a seperate advanced options file.  
  39.    Note that for any REALM specified in ATTRIBS.CFG you can 
  40.    use both an advanced options file line (ADVOPT_FILE)
  41.    and one (or several) Options: lines.
  42.  
  43. Some examples::
  44.   * Assuming that your SRE-http "WORKDATA_DIR" directory is
  45.     D:\GOSERVE\DATA, the following entry in ACCESS.IN:
  46.         /SAMPLES/* *   ,     ,  MYREALM  ,   , ADV_OPT.CTL
  47.    tells SRE-http to use D:\GOSERVE\DATA\ADV_OPT.CTL for selectors
  48.    that match /SAMPLES/*
  49.  
  50.   * The following entry in ATTRIBS.CGG could also be used to set some 
  51.     advanced options:
  52.        REALM: Myrealm
  53.        RULE: /SAMPLES/*
  54.        Option: header add X-Grader: this is  mediocre resource
  55.        Option: set fix_expire 0.1
  56.  
  57.  
  58.  
  59. 3) The advanced options
  60.  
  61. There are several sets of selector advanced options:
  62.  
  63.   1) EXEC commands  -- execute an external REXX procedure.
  64.   2) HEADER and RESPONSE directives -- specify a custom response header
  65.   3) SSI_suppression directives -- suppress specific SSI actions.
  66.   4) Set MIME type
  67.   5) Replacement rules
  68.   6) Set a few variables
  69.   7) Enabling hit-metering 
  70.  
  71. Note that each of these entries should appear on a single line (lines
  72. beginning with a ; are comments).  The following documents how to
  73. use these options.  We also recommend perusing the ADV_OPTS.CTL and
  74. ADV_OPTS.CMD sample files.
  75.  
  76.  
  77. 3a) EXEC Commands
  78.  
  79. EXEC entries are used to execute external REXX procedures.  This execution
  80. occurs just before the "verb is processed", and after all "selector
  81. modifications/redirections" and "access control checks."
  82.  
  83.     In a sense, the EXEC commands can be thought of as "mid-filter" hook,
  84.     occuring after the (optional) pre-filter, and before the (optional)
  85.     "pre-reply" procedure.
  86.  
  87. Example:
  88.   EXEC ADV_OPTS.CMD  Hello from job 1.
  89.  
  90. In this example, ADV_OPTS.CMD should be in the GoServe working directory.
  91.  
  92. Note that ADV_OPTS will be sent a set of variables:
  93.  ARGUMENT:
  94.      The "argument" following the procedure-file name.  This may contain
  95.      commas (a comma containing ARGUMENT does NOT result in multiple
  96.      arguments being sent to the called procedure).
  97.      In the above example, ARGUMENT would be "Hello from job 1." (without
  98.      the quotes).
  99.  SOURCE:
  100.     The GoServe "source" line
  101.  REQUEST:
  102.     The GoServe request line
  103.  SEL:
  104.    The (SRE-http) modified selector
  105. VERBOSE:
  106.    The SRE-http VERBOSE parameter
  107. SERVERNAME:
  108.    The name of the server processing this request (might be an alias)
  109. HOST_NICKNAME:
  110.    SRE-http "host nickname" for the server processing this request
  111. DATA_DIRECTORY:
  112.    The default data directory (might be servername dependent)
  113. HOME_DIRECTORY:
  114.    The ~ replacement directory (the "home" directory).
  115. TEMP_DIRECTORY:
  116.    The SRE-http TEMPDATA_DIR "temporary files" directory
  117.  
  118. These external procedures MAY issue GoServe completion codes. If they do,
  119. they should return
  120.   status_code bytes_sent
  121. (i.e.; 200 15122)
  122. If they do not, they should return a 0.
  123. All other returns are ignored.
  124.  
  125. Note that ADV_OPTS.CMD contains a simple example of such an external
  126. procedure.
  127.  
  128. Hint: one use of EXEC is to support HTTP M-extensions, as described in
  129.       the "HTTP Extensions" Internet-Draft. Otherwise, these 
  130.       M-extensions will result in a 510 error return.
  131.  
  132.  
  133. 3b) HEADER and RESPONSE directives.
  134.  
  135. You can include HEADER and RESPONSE entries -- they will be sent almost
  136. verbatim to GoServe.
  137.  
  138. This response header customization is only available for GET and HEAD
  139. requests that invoke a file transferal (including HTML documents
  140. with server side includes).
  141.     That is, for "server side processing" requests (such as CGI-BIN
  142.     scripts, SRE-http addons, PUT and DELETE requests, and imagemaps)
  143.     HEADER and RESPONSE entries will NOT be used.
  144.  
  145. As a convenience, SRE-http will perform a few substitutions on HEADER
  146. and RESPONSE entries:
  147.   $GMT : The current  GMT day, date and time.
  148.   $SERVERNAME: The "server name" of the server processing this request
  149.   $SIZE: The number of bytes to be sent
  150.   $CODE: The status code (almost always 200)
  151.  
  152. Examples:
  153.   response HTTP/1.1 406 Variant not available
  154.   header add X-Webmaster-Name: Daniel Platypus
  155.   header add X-comment:  X- headers are created by SRE-http
  156.   header add X-Our-server: $servername
  157.   header add X-Size-1: this is $size size
  158.   header add X-Code-1: this is $code code
  159.  
  160. Notes:
  161.  *  This customization is akin to ICS's "meta information".
  162.  *  Headers specified using advanced options override automatically
  163.     generated headers. For example, if  a cache-control header 
  164.     is specified as an advanced option, then the automatically
  165.     generated cache-control header will not be used.
  166.  *  See GOSERVE.DOC for a description of the HEADER and RESPONSE GoServe
  167.     directives.
  168.  *  When adding a header, be sure to include an ADD after the HEADER
  169.     
  170. 3c) Server Side Include Suppression
  171.  
  172. Although you can suppress all server side includes (either for all documents,
  173. or on a SEL-specific basis), you may wish to only suppress a select set of
  174. these includes. In particular, you may wish to supress HEADERS and FOOTERS
  175. for a portion of  your HTML documents.  This can be easily done with
  176. the various server side include suppression options.
  177.  
  178. The available options are:
  179.   ssi_no_cache     : suppress caching (similar to a <!-- CACHE NO -->
  180.                      keyphrase)
  181.   ssi_no_header    : Do NOT include HEADERS lines
  182.   ssi_no_footer    : Do NOT include FOOTERS lines
  183.   ssi_no_replace   : Do NOT process <!-- REPLACE varname --> keyphrases
  184.   ssi_no_include   : Do NOT process <!-- INCLUDE filename --> keyphrases
  185.   ssi_no_option    : Do NOT process <!-- OPTION n --> keyphrases
  186.   ssi_no_interpret : Do NOT process <!-- INTERPRET FILE filename --> or
  187.                      <!-- INTERPRET CODE  xxx ;yyy --> keyphrases.
  188.   ssi_no_select    : Do NOT process <!-- SELECT xxx --> ... <!-- SELECT END -->
  189.                      keyphrases
  190.   ssi_no_#filestat : Do NOT process <!-- #FLASTMOD ... --> or <!-- #FSIZE ... -->
  191.                      keyphrases
  192.   ssi_no_#config   : Do NOT process <!-- #CONFIG ... --> keyphrases
  193.   ssi_no_#echo     : Do NOT process <!-- #ECHO ... --> keyphrases
  194.   ssi_no_#include  : Do NOT process <!-- #INCLUDE ... --> keyphrases
  195.   ssi_no_#exec     : Do NOT process <!-- #EXEC ... --> keyphrases
  196.  
  197. Note that these options should appear one-per-line.
  198.  
  199. Examples:
  200.   ssi_no_cache
  201.   ssi_no_header
  202.   ssi_no_footer
  203.   ssi_no_select
  204.   ssi_no_#echo
  205.   ssi_no_#exec
  206.  
  207. 3d) Mime types
  208.  
  209. You can specify the mime type for this (these) selector(s). Just enter
  210.    MIME type/subtype
  211.  
  212. For example:
  213. MIME  text/plain
  214. MIME  image/jpg
  215.  
  216. You should have, at most, one MIME entry (latter entries are ignored)
  217.  
  218.  
  219. 3e) Replacement rules
  220.  
  221. You can specify selector specific "replacement rules".  These will be
  222. used instead of the generic REPLACE_RULES. replacement rules (set in
  223. INITFILT.80).  
  224.  
  225. The syntax is
  226. REPLACE_RULES=old_string==new_string
  227.  
  228. Notes:
  229.     * Spaces will NOT be stripped from either old_string or new_string
  230.       -- thus "invisible spaces" at the end of new_string will be retained.
  231.     * Note the use of == as a seperator between old_string and new_string.
  232.     * Unlike REPLACE_RULES.n (in INITFILT.80), do NOT include a "stem";
  233.       the order of appearance is the order of processing
  234.     * If you do NOT specify any replacement rules here, the generic ones 
  235.       (in INITFILT.80) will be used.
  236.  
  237. Example:
  238.  REPLACE_RULES=$(==<!-- $ customiz 
  239.  REPLACE_RULES=)$== -->
  240.  
  241.  
  242. Hint: Using Replace_rules and Load Balancing.
  243.  
  244.  Replace rules can come in handy when you are load balancing to subsidiary-
  245.  sites. In order to guarantee that all requests pass through a "main-site", 
  246.  you may have to include a <BASE href="main.site.url"> element in the 
  247.  <HEAD> section of HTML documents on subsidiary-sites.  Since adding these 
  248.  elements may be tedious, the following REPLACE_RULES can be used instead:
  249.  
  250.     REPLACE_RULES=</HEAD>==<BASE href="http://main.site.url"> </HEAD>
  251.  
  252.  where main.site.url should be the IP address of the main-site.
  253.  
  254.  
  255. 3f) Setting variables
  256.  
  257. You can set several SRE-http variables on a request specific basis. 
  258. These are:
  259.    CONTENT_MD5 (add an Content-MD5 response header) 
  260.    FIX_EXPIRE (add an offset to an otherwise immediate expiration).
  261.    PRE_REPLY (suppress use of a "pre-reply" procedure).
  262.    ENCRYPT (enable or disable encryption)
  263.  
  264. The syntax to use is: 
  265.    SET varname value
  266. where varname is either CONTENT_MD5, FIX_EXPIRE, PRE_REPLY, or ENCRYPT
  267.  
  268. For example:
  269.    SET CONTENT_MD5 0         (suppress generation of Content-MD5 header)
  270.    SET CONTENT_MD5 1
  271.    SET CONTENT_MD5 2        (use MD5.EXE, assuming EMX is avaiable)
  272.  
  273.    SET FIX_EXPIRE  0
  274.    SET FIX_EXPIRE 0.66
  275.    SET PRE_REPLY 0  
  276.    SET ENCRYPT SRE_A   
  277.  
  278. Notes: 
  279.   * You can suppress use of a pre-reply procedure by setting PRE_REPLY 0.
  280.     However, you can not "invoke" it -- setting PRE_REPLY=1, when 
  281.     PRE_REPLY_PROCEDURE was NOT set in INIT_STA.80, will have no effect.
  282.  
  283.   * If encryption is not enabled (ENABLE_ENCRYPTION=0) then SET ENCRYPT
  284.     has no effect.
  285.  
  286.   * SET ENCRYPT 0 means "never encrypt" -- this will override a !ENCRYPT
  287.     "special directive" (that is prepended to the selector)
  288.  
  289.   * SET ENCRYPT (without any other argument) is a shorthand 
  290.     for SET ENCRYPT SRE_A
  291.  
  292.  
  293. 3g) Enabling hit-metering.
  294.  
  295. In order to get some measure of the number of times proxy servers
  296. are resolving requests for resources from your site, SRE-http
  297. supports a form of simple-hit-metering.  This algorithim (based
  298. on RFC 2227) depends on proxies reporting their activity
  299. to your server.  
  300.  
  301. To enable this, you must specify a METER advanced option.
  302. When METER is specified, and when a proxy says that it is willing to
  303. support this hit metering, SRE-http will include a METER: 
  304. response header, and will watch for special METER: request
  305. headers. The information in these METER: request headers 
  306. is written to HITMETER.CNT. 
  307.  
  308. The syntax of this option is:
  309.  METER=[options]
  310. where:
  311.   options are a set of optional modifiers, that are described in RFC2227. 
  312.  
  313. These options  include directives on cache lifetime, and on when and how
  314. to report hits.  Alternatively, you can not specify options, which
  315. will enable hit-meterin but not effect cache behavior.
  316.  
  317. Examples:
  318.    METER=
  319.    METER= max-uses=3, dont-report
  320.  
  321. Note that if you do not specify a METER= option, then hit-metering
  322. will not be attempted (even if a proxy reports that it is willing
  323. to provide hit-metering).
  324.  
  325. For further details, please HITMETER.DOC, and see the description of
  326. the PROXY_CACHE variable in INITFILT.DOC.
  327.  
  328.  
  329.       
  330. 4) A sample "advanced options file"
  331.  
  332. The following is a sample of an advanced options file. You might also want
  333. to examine ADV_OPTS.CTL.
  334.  
  335. ;------------- Begin Example ------------
  336. ; call the sample external procedure
  337. exec adv_opts.cmd This is an argument , with commas embedded.
  338. ;
  339. ; add a custom response header
  340. header add X-Webmaster-Name: Timothy Platypus
  341. ;
  342. ; Suppress headers, footers, and server side "excludes"
  343. ssi_no_header
  344. ssi_no_footer
  345. ssi_no_select
  346. replace_rules= C.== $ Customiz 
  347.  
  348. ; suppress content-md5 header
  349. set fcontent_md5 0
  350.  
  351. ;------------- End Example ------------
  352.  
  353.  
  354.  
  355. ---- End of document
  356.