home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Spezial / SPEZIAL2_97.zip / SPEZIAL2_97.iso / ANWEND / ONLINE / SREFV12J / SREFAST.DOC < prev    next >
Text File  |  1997-07-06  |  19KB  |  392 lines
  1. 06 Jul 1997
  2.  
  3. The SREFAST variant of SRE-Filter.
  4.  
  5. 1) Introduction
  6.  
  7.    SREFAST provides faster throughput for a user-specified subset of
  8.    selectors.  The operative assumption is that many requests are "simple",
  9.    and do NOT require the full power of SRE-Filter.  If you can specify which
  10.    selectors fall into this "simple request" category, then it makes sense
  11.    to use a low powered (but faster) filter to deal with them.
  12.  
  13.    Use of SREFAST requires that the site administrator specify which selectors
  14.    SREFAST should attempt to process.  However, for requests that are
  15.    NOT "specified", and for requests that are too complicated, SREFAST will 
  16.    simply pass the request to SREFILTR for normal processing.
  17.    Thus, you will never loose functionality by using SREFAST.
  18.  
  19.    To use SREFAST, you'll need to set GoServe's Filter to be SREFAST.80.
  20.    More importantly, you'll need to specify the selectors to treat
  21.    as "simple requests".  The easiest way to do this is to run the
  22.    SREFST configurator (SREFAST.HTM).  Section 3 contains a detailed
  23.    description of configuration options.
  24.  
  25.    SREFAST can be seen as a more flexible alternative to SREFQUIK.
  26.    It's disadvantage is that it demands more careful configuration.
  27.  
  28.  
  29.  ** We recommend careful reading of the hints and cautions section at the   **
  30.  **                         end of this document.                                  **
  31.  
  32.  
  33. 2) Features of SREFAST
  34.  
  35.    The major feature of SREFAST is that it's much smaller then the main
  36.    SRE-Filter program (SREFILTR.80).   Loading, and executing, SREFAST will
  37.    therefore take less time.
  38.  
  39.    This smallness means that it doesn't do nearly as much as SREFILTR.  However,
  40.    it does have several features, including:
  41.  
  42.    * Most of the  common server side includes will be processed, using a
  43.      simple caching algorithim.
  44.  
  45.    * Requests can be redirected
  46.  
  47.    * Virtual directories can be specified
  48.  
  49.    * A simple form of access control is available
  50.  
  51.    * Non standard mime types can be specified.
  52.  
  53.    * Post-filtering (recording in log files) can be suppressed
  54.  
  55.   MOST IMPORTANTLY, for requests that SREFAST can't/won't deal with, the
  56.   regular SRE-Filter is called.  Thus, you need not loose functionality.
  57.  
  58.   Notes:
  59.         *  When starting SREFAST, you must shut down GoServe.  That is,
  60.            do not start SREFAST by changing the FILTER tab while
  61.            running another filter.
  62.  
  63.         *  SREFAST does not check SRE-Filter's load balancing.  However,
  64.            if SREFILTR is called, load balancing will be checked.
  65.  
  66.         *  SREFAST does not call SRE-Filter's PRE-Filter.  However, if
  67.             SREFILTR is called, PRE-Filter(s) will be run.
  68.  
  69.  
  70. 3) Configuring SREFAST
  71.  
  72.    Configuration of SREFAST requires modification of the INITFAST.80
  73.    configration file. This modificaiton file can be readily accomplished
  74.    by using the SREFAST configurator (SREFAST.HTM, located
  75.    in your GoServe data directory).
  76.  
  77.    Using INITFAST.80, a special "binary" configuration file is created.
  78.    This binary file contains a REXX stem variable, hereinafter referred to
  79.    as the DOIT. variable.  Each request recieved by SREFAST is
  80.    compared to entries stored in the DOIT. stem variables (as read from the
  81.    binary configuration file).  If a match is found,  the instructions 
  82.    contained in the matching entry will dictate how the request is to be 
  83.    handled.  If there is no match, then SREFILTR.80 is  immediately called.
  84.  
  85.    The following describes the possible "options" that DOIT. may contain.
  86.  
  87.          SEL:   Required. The target "selector".
  88.                 The selector requested by the client will be compared against
  89.                 SEL.
  90.                 * You can include * (wildcard) characters in SEL.
  91.  
  92.  
  93.        SERVER:  Optional. The numeric IP address, or Host alias, this
  94.                   entry is valid for.
  95.                        If you are NOT running multiple hosts,
  96.                        you should NOT specify a SERVER variable.
  97.                 * If SERVER is not specified, the entry is valid for all 
  98.                   +requests.
  99.                 * Otherwise, it's value will be compared against the numeric
  100.                   IP address of the target server (as provided by GoServe), and
  101.                   the HOST: request header (if one exists).
  102.                 * If SERVER is specified, and neither the numeric IP address
  103.                   or the HOST: request header match the value of SERVER,
  104.                   this entry will be ignored.
  105.          HOST:  Optional.  The "host nickname" of the SERVER.
  106.                       If you are NOT running multiple hosts,
  107.                       you should NOT specify a SERVER variable.
  108.                  * HOST is only used to resolve REPLACE variables in
  109.                    server side includes. If you specify a SERVER but
  110.                    not a HOST, the "generic host" variables will be used.
  111.                  * We highly recommend coordinating the values assigned to
  112.                    SERVER, HOST, and DIR with the HOSTS. entries (in 
  113.                    INITFILT.80)
  114.  
  115.           DIR:  Optional. The directory containing the requested file.
  116.                 * If not specified, the GoServe default data directory is used.
  117.                 * If  DIR starts with a url (that MUST begin with http://),
  118.                   then requests that match this entry will be redirected to
  119.                   this URL.
  120.                * When redirecting, you can include an * at the end of DIR to
  121.                  "append the selector" (or the file portion of the selector) to
  122.                  the target URL.
  123.  
  124.  DIR_NAMEONLY:  Optional.  Modifies the DIR option.
  125.                 When mapping requests to files, SREFAST can use the value of
  126.                 the DIR option in two ways:
  127.                     i) It can append the selector
  128.                    ii) It can append <u>just the file name</u> portion of the
  129.                        selector
  130.                DIR_NAMEONLY controls which method to use; if DIRNAME_ONLY is
  131.                selected, then method ii is used.
  132.                Example:  Assuming DOIT.1.!DIR='D:\PERSONAL' and the selector
  133.                          is /STUF/FOO.BAR, then the following are returned:
  134.                             If DIR_NAMEONLY=0,  D:\PERSONAL\STUF\FOO.BAR
  135.                             If DIR_NAMEONLY=1,  D:\PERSONAL\FOO.BAR
  136.            *  The default value, used if DIR_NAMEONLY is not specified, is 0.
  137.            *  If DIR is not specified, DIR_NAMEONLY is ignored.
  138.  
  139.  
  140.        SSI:   Optional.  If set to 1, then this entry contains server side 
  141.               includes.
  142.               * SREFAST uses "pre-compiled" cache files to handle most
  143.                 server side includes.
  144.               * If SSI=1, and if SEL contains wildcards, then multiple cache
  145.                 files will be created.
  146.  
  147.        MIME:  Optional. Mime type.  The Mime type of this request.  If not 
  148.               specified, the standard SRE-Filter mime type is used.
  149.  
  150.       USERS : Optional.  A space delimited list of allowed users.
  151.               * If the client did not provide a username, the main
  152.                  filter (SREFILTR) is called.  SREFILTR may then
  153.                  return an authorization request.
  154.               * If this username is in USERS., then PWDS is also checked.
  155.  
  156.       PWDS:  Optional. A list of allowed passwords, with each word in the list
  157.              paired with the corresponding word in USERS.
  158.              * Given that USERS is satfisfied,the appropriate word in PWDS is
  159.                compared against the password provided by the client.
  160.              * If this word does not match the password, then the  main
  161.                  filter (SREFILTR) is called. 
  162.              * A value of * means "any password will do".
  163.  
  164.       NOCACHE:  Optional.  If set to 1, then this entry will NOT be cached
  165.                 by GoServe.
  166.  
  167.       NORECORD:  Optional.  If set to 1, then this entry will not be recorded.
  168.                That is, no POST-Filter action will occur: no recording in
  169.                the RECORD_ALL file, no recording in the .LOG files, etc.
  170.                Otherwise, the entry WILL be recorded (using the standard
  171.                SRE-Filter mechanisms).
  172.  
  173.      TRIGGER:  Optional.  If filled in, this should contain
  174.              the fully qualified name of a trigger file.  When SREFAST
  175.              checks it's SSI cache, it always checks the file-stamp of the "own
  176.              file";  and will not use the cache entry if the file stamp has 
  177.              changed.  However, if an INCLUDEd file has changed, SREFAST 
  178.              will not detect the change;  and will instead use the out-of-date 
  179.              cache entry.  By using a trigger file, you can specify one 
  180.              additional file-stamp to check (i.e.; an INCLUDEd file).
  181.          
  182.   Notes:
  183.      * DOIT. stem variables have the form:
  184.               DOIT.nn.!tail
  185.          where nn is an integer, and tail is one of the options listed above
  186.      * DOIT.0 entry should be set to the  number of DOIT. entries.
  187.      * SREFAST uses a "first match" criteria -- the first match to the
  188.        requested selector is used. That is, "best matching" is NOT attempted.
  189.      * Entries with NOCACHE=1, or with USERS (and PWDS) entries will NOT
  190.        be cached.
  191.      * We HIGHLY RECOMMEND enabling (and using) GoServe's cache whenever
  192.        possible (that is, when security requirements are not binding).
  193.        Note that documents with "dynamic server side includes" are never
  194.        cached, but documents with "static" server side includes may
  195.        be cached.
  196.  
  197.   Examples  (note that case does not matter):
  198.         DOIT.0=6
  199.         DOIT.1.!SEL="/"
  200.         DOIT.1.!DIR="http://my.site.net/index.htm"
  201.  
  202.         DOIT.2.!SEL="index.htm"
  203.         DOIT.2.!SSI=1
  204.         DOIT.2.!MIME="text/html"
  205.  
  206.         DOIT.3.!SEL="IMGS/*.GIF"    
  207.         DOIT.3.!DIR_NAMEONLY=1
  208.         DOIT.3.!DIR="d:\IMGS\"
  209.         DOIT.3.!MIME="image/gif"
  210.         DOIT.3.!NORECORD=1
  211.  
  212.         DOIT.4.!SEL="BBS/BBS.HTM"
  213.         DOIT.4.!SSI=1
  214.         DOIT.4.!USERS="JOE FRANK BOB "
  215.         DOIT.4.!PWDS=" EOJ CRAB * "
  216.  
  217.         DOIT.5.!SEL="HELLO.HTM"
  218.         DOIT.5.!SERVER="OUR.SITE.NET"
  219.         DOIT.5.!DIR="D:\WWW2\"
  220.         DOIT.5.!MIME="text/html"
  221.  
  222.         DOIT.6.!SEL="/HELLO.HTM"
  223.         DOIT.6.!NOCACHE=1
  224.  
  225.         Notes on examples:
  226.          * The "number of words" in DOIT.4.!USERS must match the number of
  227.            words in DOIT.4.!PWDS
  228.          * Use of a leading / in DOIT.n.!SEL is optional (leading /'s are 
  229.            ignored).
  230.          * DOIT.5 applies only to requests to the OUR.SITE.NET host.
  231.          * If DOIT.6 and DOIT.5 had their number reversed, then the OUR.SITE.NET
  232.            entry would NEVER be found (since the "generic" HELLO.HTM would
  233.            be the first match).
  234.          * A DOIT.7 entry would NOT be examined (since DOIT.0=6).
  235.          * You could create a text file similar to the above, and use the 
  236.            SREFAST configurator to transform it into a "SREFAST configuration 
  237.            file".
  238.  
  239. 4) SREFAST and Server Side Includes
  240.  
  241.   To expedite processing of server side includes, SREFAST will start a special
  242.   "html compiler" daemon.  This daemon (running in a seperate thread) will
  243.   examine the INITFAST.80 configuration file and determine which files are to 
  244.   be processed for server side includes.  It will attempt to do this 
  245.   processing, and will save results to special cache files.
  246.  
  247.   When a request for such an SSI file arrives, SREFAST will read the 
  248.   appropriate special cache file.  It will then check for a few simple 
  249.   "dynamic" string replacements, and send the document to the client.
  250.  
  251.   If an html file contains a SELECT, OPTION, #EXEC, or INTERPRET keyphrase;
  252.   then this file will NOT be processed by SREFAST.  That is, the main filter
  253.   (SREFILTR.80) will be used to process documents that contain any of these
  254.   four keyphrases.  Therefore, it is pointless and wasteful to specify
  255.   DOIT. entries that refer to HTML documents that contain any of these 4
  256.   keyphrases.
  257.  
  258.  Notes:
  259.    * SREFAST does NOT check "trigger files".  It does check the "own"
  260.       filestamp  (mismatches cause the main filter to be called).
  261.       Otherwise, SREFAST assumes that the special cache file (created by
  262.       the "SREFAST SSI daemon") is correct.
  263.  
  264.    * In order to prevent this cache from becoming seriously out of date, the
  265.      daemon will refresh the cache periodically (by default, every 15 minutes).
  266.      You can change this refresh rate by changing the REFRESH variable
  267.      in SREFAST.80.
  268.  
  269.    * Almost all of the REPLACE keyphrases will be processed.  The exception is
  270.      the HITS and COUNT keyphrases -- if such as keyphrase is found,
  271.      then SREFAST will not process the document.
  272.  
  273.    * If there are NO dynamic replacements (and none of the verboten 
  274.      keyphrases), SREFAST will instruct GoServe to cache the "compiled" 
  275.      document.  Note that versions of GoServe older then 2.50 might fail 
  276.      to recognize when a change occurs in a "cached, pre-compiled HTML 
  277.      document".
  278.  
  279.    * To force SREFAST to "recompile", you can delete all files with a
  280.      .FST extension in SRE-Filter's TEMPDATA_DIR directory (typically,
  281.      x:\goserve\temp).
  282.  
  283.  
  284. 5) Hints and Cautions
  285.  
  286.   * SREFAST should be used with SRE-Filter version 1.2j (and above).
  287.  
  288.   * It may take a minute or so (depending on how many SSI entries you have)
  289.      for SREFAST to initialize.  We recommend immediately hitting your server
  290.      with a request (any request) after starting GoServe with SREFAST. This
  291.      can be easily done with DOGET.CMD (DOGET.CMD is an SRE-Filter
  292.      utility installed into your GoServe working directory).
  293.  
  294.   * When SREFAST processes a request, most of SRE-Filter's parameters
  295.      are NOT checked.  In particular:
  296.         **  ALIASES are NOT checked
  297.         **  VIRTUAL directories are NOT checked (see below for an
  298.              exception)
  299.         **  ACCESS controls are NOT checked
  300.         **  The USER database (and associated privileges) are NOT used
  301.         **  Pre-filter processing is NOT attempted
  302.         **  The SAVE_STATE and  HIT_SUPERUSER_SUPPRESS features are NOT used
  303.         **  PUBLIC_URLS are not checked.
  304.  
  305.      There are a few exceptions:
  306.         **  OWNERS are recognized  (OWNERS are not checked for USERS).
  307.         **  Virtual directories WILL be used when  resolving the INCLUDE and
  308.              #INCLUDE SSI keyphrases.
  309.          ** Post-filtering options (WRITE_LOGS, RECORD_OPTION, POST_FILTER,
  310.              POSTFILTER_NAME,RECORD_ALL_FILE, and HIT_OWNER_SUPPRESS) will
  311.              be used (and if you specify a .!HOST field, it's value will 
  312.              be used as a host-nickname when  looking up these 
  313.              post-filtering options).
  314.  
  315.   * By default, SREFAST assumes that .HTM and .HTML documents do NOT have
  316.     server side includes.  To force SREFAST to process SSI's, be sure to 
  317.     set the !SSI option.
  318.  
  319.   * If you have specified a lot of !SSI files (say, you used wildcarded a
  320.      large directory), you may need a fair amount of disk space to store
  321.      the cached files.  As a precaution, SREFAST will always leave about
  322.      10M free (see the DISK_FREE variable in SREFAST.80) on the
  323.      temporary data directory disk (it's where the cached files are written).
  324.      If this limit is exceeded, cached files will not be written.
  325.  
  326.   * SREFAST does somee checking of "trigger" files: SREFAST will check the
  327.     "own" file, and (optionally) one "trigger file". If the file stamp of 
  328.      either of these files differs from what is stored in the cache, then 
  329.      SREFILTR is called.
  330.      Note that (unlike the SREFILTR SSI cache), INCLUDEd files are NOT 
  331.      automatically   checked.  In other words, if your site has ever 
  332.      changing "included" files, it is quite possible that slightly out of 
  333.      date information may be sent to the client.
  334.      
  335.    * SREFAST will frequently check (about once a minute) to see if any of 
  336.      several configuration files have changed.  If a change is detected, 
  337.      SREFAST will regenerate the binary configuration file  (which means 
  338.      that it will recreate the SREFAST cache).
  339.      Furthermore, about once an hour SREFAST will regenerate the binary 
  340.      configuration file, even if no change has been detected (this limits
  341.      how "out of date" your SREFAST cache can become).
  342.      Ambitious administrators can change these limits by modifying the 
  343.      REFRESH and FORCE_REFRESH variables in SREFAST.80.
  344.  
  345.         A Recommendation:
  346.                 IF A DOCUMENT HAS INCLUDED FILES THAT CHANGE RAPIDLY, SREFAST
  347.                 SHOULD NOT PROCESS IT.
  348.  
  349.   * SREFAST will NOT attempt to process the following requests:
  350.         ** !SPECIAL requests
  351.         ** POST, PUT and DELETE method requests
  352.         ** CGI-BIN requests
  353.         ** Selectors that contain a ?
  354.  
  355.   * On occasion; such as on transaction #1, or while the cache is being
  356.     refreshed, the main filter will be called even when a matching SREFAST
  357.     entry exists.  Therefore, we strongly advise that you "synchronize" the
  358.     various features of SREFAST with the corresponding features in the
  359.     "main" SRE-Filter's various configuration files.
  360.     For example:
  361.      i) Double check that the security features of SREFAST are
  362.         synchronized with those in SRE-Filter.  That is, the !USERS and !PWDS
  363.         should be the same as entries in the USERS.IN file.
  364.      ii) !NOCACHE and !SSI options should be synchronized with the 
  365.          SSI_SHTML_ONLY option, and with the various "access control 
  366.          permissions".
  367.     iii) !HOST and !SERVER options be the same as listed in the HOST.  options.
  368.     iv) !DIR should yield the same results as SRE-Filter's virtual directories
  369.         and aliases.
  370.      v) The value of VERBOSE in SREFAST should correspond to it's value in
  371.         INITFILT.80.
  372.  
  373.      Basically: when configuring SREFAST to accept "complicated" requests,
  374.      you might want to test your server's responses under both SREFAST and
  375.      SREFILTR.
  376.  
  377.    * Use of * in Selectors with SSI's will lead to seperate cache entries for
  378.      each matching file.
  379.  
  380.    * When transferring "dynamically cached SSI" documents, SREFAST will
  381.      send the document in pieces if the SREFILTR variable DO_SEND_PIECE=1.
  382.  
  383.    * You can create a short list of UNALLOWEDIPS -- see SREFAST.80
  384.      for details.
  385.  
  386.    * You can use SREFAST.HTM to check the proportion of requests handled 
  387.      by SREFAST. 
  388.          Remember: if the proportion of requests handled by SREFAST is low,
  389.                    it may be more efficient to use the standard filter!
  390.  
  391. --- End of file.
  392.