home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / initfilt.doc < prev    next >
Text File  |  2001-03-27  |  158KB  |  4,081 lines
  1. 15 November 1999.
  2.  
  3.        Optimization hints, configuration information, and other commentaries 
  4.        on SRE-http. 
  5.  
  6. This file contains several sections discussing various aspects of 
  7. SRE-http (ver 1.3h)
  8.  
  9.  1)  Optimization hints: a discussion of ways of speeding up SRE-http
  10.  2)  Configuration information: a complete description of all the SRE-http
  11.      intialization parameters: including the more important dynamic parameters
  12.      set in INITFILT.80, more obscure "static" parameters set in INIT_STA.80,
  13.      and even more obscure parameters in SREFMON.CMD.
  14.  3)  Remote vs. local redirection: A discussion of the various methods
  15.      SRE-http uses to redirect files.
  16.  
  17.  
  18.                   ===========================================
  19.  
  20.    SECTION 1.                    Performance hints
  21.  
  22.  
  23. (a) The use of the server side include cache (SSI-Cache) is highly
  24.     recommended. However, for very dynamic documents (such as documents
  25.     that contain several INTERPRET and #EXEC keyphrases), it may
  26.     be more efficient to suppress caching of these files (you
  27.     can use the <!-- CACHE NO --> keyphrase for just such a purpose).
  28.  
  29.  
  30. (b) Suppressing incorporation of  server side includes (SSIs)
  31.  
  32.    i) If you 
  33.         1) set SSI_SHTML_ONLY='YES'
  34.         2) name html documents, that contain SSIs, with a .SHT or .SHTML
  35.           extension
  36.       Then
  37.          SRE-http will not attempt to process SSI's in .HTM or .HTML files
  38.          but WILL attemp to process SSI's in .SHT or .SHTML files.
  39.       This can save some processing time.
  40.  
  41.   ii) If you are willing to NOT have SSIs, then set
  42.           NO_INCLUDE='YES'
  43.      (this saves more processing time, and it also makes
  44.       hints (a) and (b.i) totally irrelevant)
  45.  
  46. (c) Use the SREPROXY "alternative" filter. SREPROXY is a "simple proxy"
  47.     that can handle many requests recieved by your server. In particular,
  48.     SRE-http will identify "public, cachable, non-temporary" URLs can
  49.     be handled by SRE-Proxy. And since SRE-Proxy is much simpler then
  50.     the full filter, throughput is enhanced.  Note that this involves 
  51.     no loss in functionality -- when SREPROXY can not deal with a request,
  52.     it simply passes processing to the standard filter (SREFILTR).
  53.  
  54.     Upgraders note: The GoServe cache should be used carefully -- it is
  55.                     not http/1.1 compliant. In fact, when GoServe answers
  56.                     a request from a cache, it claims to be a http/1.0
  57.                     server! 
  58.                     These are not fatal problems, but they are not exactly
  59.                     spec.  Therefore, we recommend limited use of the
  60.                     GoServe cache, with the "do not call filter" GoServe
  61.                     option selected.
  62.                     For more details on how to use the GoServe cache, see
  63.                     the description of the CACHE* privilege in SREHTTP.HTM,
  64.                     or in the shipped version of ACCESS.IN
  65.  
  66.    Need speed, don't need features? Try the sreLite variant of sre-http!
  67.  
  68. (d) If you never check "access" info, or virtual directories,
  69.     set the access_file and virtual_file to " " (or see note e).
  70.     Note that in addition to access information, the access file contains 
  71.     permissions and advanced options -- please read the default ACCESS.IN 
  72.     file for further details.
  73.  
  74. (e)  Use the NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER "permissions"
  75.      in the ACCESS_FILE to suppress unnecessary processing.
  76.  
  77. (f)  If you have a choice, the ACCESS_FILE method is preferable to the
  78.      the HTACCESS access control method: HTACCESS it is not
  79.      implemented with quite the same attention to efficiency.  Or,
  80.      use the NO_HTACCESS permission (in your ACCESS_FILE) whenever possible.
  81.  
  82. (g)  On an otherwise access controlled site, you can use PUBLIC_URLS
  83.      to grant fast & easy access to "publically available" resources.
  84.  
  85. (h)  Turn on the RECORD_ALL_FILE cache.  This is useful ONLY if you
  86.      are recording all requests (i.e.; RECORD_OPTION='YES').
  87.      Turning on the cache will cause the RECORD_ALL_FILE to be cached
  88.      in memory, with disk-writes every 5 minutes.  See the description
  89.      of RECORD_CACHE_LINES for details.
  90.  
  91. (i)  If you don't need extensive auditing, set WRITE_LOGS=0
  92.  
  93. (j)  It you don't need "dynamic privileges", set CHECK_ADD_PRIVS='NO'.
  94.  
  95. (k)   Setting the TEMPDATA_DIR to be a RAM Disk can help.
  96.  
  97. (l)  If you intend to use SRE-http macrospace procedures with daemons, or
  98.      in completely seperate processes (processes that are not under GoServe),
  99.      you should add the following line to your CONFIG.SYS file
  100.           SET SRE_LIBDIR=e:\goserve\lib
  101.      where "e:\goserve\lib" is the "lib" subdirectory of GoServe/SRE-http.
  102.  
  103.  
  104.                         =============================
  105.  
  106.    Section 2.                Parameter descriptions
  107.  
  108. 2a.  Basic Description
  109.  
  110. The following  parameters are in alphabetical order (by name  of parameter).
  111. Many of them can be editied with SRE-http's configurator, especially the 
  112. "intermediate mode" configurator. However, to changes several of
  113. these parameters, you must "hand-edit" the INITFILT.80 file.  In general, the
  114. "hand-edit only" parameters are more obscure, and may never need to be changed.
  115.  
  116. "Power users" may wish to see section 2a (below) for a discussion of
  117. variables contained in INIT_STA.80 and in the "even more obscure"
  118. parameters contained in SREFMON.CMD.
  119.  
  120. 2b. Miscellaneous Notes:
  121.  *   The terms "variable" and "parameter" are used interchangeably.
  122.  
  123.  *  As of version 1.3d, INITFILT.80 and INIT_STA.80 will be
  124.     installed in the CFG\ subdirectory (of your goserve working
  125.     directory).
  126.  
  127.  *   In almost all cases the variables (aka parameters) are set to equal
  128.      strings, so if you are "hand editing" INITFILT.80, remember to put
  129.      single quotes (') around the stuff on the rhs of the = sign.
  130.  
  131.  *   When this document mentions "SEL-specific", it really means
  132.      "selector specific", where the selector is the slightly modified
  133.      middle portion of the request string sent by the client to the server.
  134.      For example, if the client requests a URL of:
  135.          http://your.server/animals/bear.jpg
  136.      her browser will issue a request string of:
  137.          GET   /animals/bear.jpg  http/1.0
  138.      and the selector would be
  139.                animals/bear.jpg
  140.  
  141.  *   The CFGSLIST.CFG file can be used to specify host and port specific
  142.      parameter files (to complemenet the public_url, alias, and other
  143.      paramter files.  See USE_CFGS.DOC for the details.
  144.  
  145. 2c. Notes on Host-specific parameters:
  146.  *   Almost all of the parameters (that are set in INITFILT.80) may be "host
  147.      specific".  The several that aren't are:
  148.           INTERPRET_TYPES, DISPLAY_ENV, KEEP_ADDONS., and HOSTS.
  149.  
  150.  *   Host specific stem variables should have the host nickname following 
  151.      the number. For example: INHOUSEIPS.2.HOST1='151.222.55.1'
  152.  
  153.  *   Parameters set in INIT_STA.80 and in SREFMON.CMD (described in section 2a)
  154.      can NOT be host specific (they apply to all hosts).
  155.  
  156.  *   To specify a host-specific parameter, you append the "host nickname"
  157.      to the parameter name (see the HOSTS. variable for a discussion of
  158.      host nicknames).
  159.         For example, to set the CHECKLOG variable for the ZOO host,
  160.            CHECKLOG.ZOO='NO'
  161.         and for all other hosts:
  162.            CHECKLOG='ALWAYS'
  163.         where this non host-specific value (CHECKLOG='ALWAYS') is the
  164.         "generic" value, and will be used for hosts other then the "ZOO" host.
  165.       
  166.      NOTE: as of ver 1.3d, we now encourage administrators to use a
  167.            "host and port specific" INITFILT.80 file (as specified
  168.            in the CFGLIST.CFG file), rather then using  
  169.            varname.host_nickname entries in the "default" INITFILT.80
  170.            Please see USE_CFGS.DOC for more details.
  171.  
  172.  *   When a request to a  host is recieved, SRE-http will attempt
  173.      to find the appropriate host-specific parameters. If a given
  174.      parameter does not have a host-specific value, the "generic"
  175.      (the value of the non host-specific parameter) is almost always
  176.      used instead.
  177.  
  178.          The exceptions are: UNALLOWEDIPS., INHOUSEIPS., and PUBLIC_URLS
  179.  
  180.  *   For security reasons, for these three (sets of) parameters
  181.      the generic (non host-specific) values are  NOT used as  a default.
  182.          The astute reader may notice that the OWNERS variable is not
  183.          on this list of "exceptions". In other words, the
  184.          "generic" OWNER has SUPERUSER privileges for ALL hosts.
  185.  
  186. 2d. Note on "hand edited" parameters:
  187.  *  Currently, the "hand-edited" parameters (that can NOT be set with the
  188.     intermediate mode configurator) are:
  189.        ACCEPT_RANGE      ADD_USER_NAME      ADD_RESOURCE_NAME  ADD_PRIVS_PREFIX
  190.        CHECK_ALIAS       CONTENT_MD5
  191.        DELIM_1.n         DELIM_2.n          DISPLAY_ENV        
  192.        HTACCESS_FILE     INTERPRET_TYPES    KEEP_ADDONS.n
  193.        MAX_POINTDIST     NO_INCLUDE
  194.        NO_PROCESSING     NO_INTERPRET_CODE  PREFILTER_NAME     POSTFILTER_NAME
  195.        REPLACE_RULES.n   USE_STDOUT         USER_LOGON_ENABLE  VERBOSE
  196.  
  197.    The EDITINIT.CMD utility can be used to modify the values of all
  198.     the parameters in INITFILT.80, including these "hand-edit" parameters.
  199.  
  200. 2e. For Advanced users: Notes on "machine specific" entries.
  201.  
  202.    If you are DNS-binding several IP addresses (that are served from several
  203.    seperate machines) to a single IP name; you might want to use a common set
  204.    of SRE-http program and configuration files (i.e.; on a LAN drive). This can
  205.    work well, but there are few directories and files that should NOT be shared.
  206.    In particular, the TEMPDATA_DIR should be "machine specific". Other parameters
  207.    that probably should be machine specific are the RECORD_ALL_FILE and the 
  208.    COUNTER_FILE.
  209.  
  210.    To specify such machine-specific values, you can insert a $MACHINE_ID prefix
  211.    to each line in INITFILT.80. For example:
  212.       tempdata_dir='S:\GOSERVE\TEMP'
  213.       $COW1  tempdata_dir='S:\COW1\TEMP'
  214.       $HORSE9 tempdata_dir='S:\HORSE8\TEMP'
  215.    the "COW1" machine will use S:\COW1\TEMP, "HORSE9" will use S:\HORSE8\TEMP,
  216.    and other machines will use S:\GOSERVE\TEMP.
  217.    
  218.    The value of the $machine_id (i.e.; COW1 and HORSE9) is read from the
  219.    MACHINE_ID_SRE OS/2 environment variable.  That is, when an instance of 
  220.    SRE-http starts up, it will check its "own" OS/2 environment 
  221.    for a MACHINE_ID_SRE variable.
  222.   
  223.    Notes:
  224.  
  225.       ** The MACHINE_ID_SRE variable must be set BEFORE starting GoServe --
  226.          ideally, you should set it in your CONFIG.SYS file.
  227.  
  228.       ** For all variables, SRE-http uses the "last" relevant entry in 
  229.          INITFILT.80.  That's why the above example  has the  "generic" entry 
  230.          (tempdata_dir='S:\GOSERVE\TEMP') first -- this  causes generic entries 
  231.          to be used for all "machine_ids" (unless pecifically overwritten in a
  232.          latter entry).
  233.  
  234.  
  235.       ** Although SRE-http will well in a DNS-binding environment, please be
  236.          aware that certain features will be undependable, especially features
  237.          that depend on daemons that keep track of dynamic events. In particular,
  238.          various "hit count suppression" tricks (for not-augmenting a hit
  239.          counter when a client repeats a request) may not work (since
  240.          some of them use a machine specific daemon to store results).
  241.  
  242.  
  243. 2f. Summary of parameters
  244.  
  245. --- Parameters in INITFILT.80
  246.  
  247. ACCEPT_RANGE: Return only specified range of the request file
  248. ACCESS_FAIL_FILE: File to return when sel-specific access is denied
  249. ADD_USER_NAME: Add clients "logon name" to the list of client privileges 
  250. ADD_RESOURCE_NAME: Add request "action" to the list of resource privileges
  251. ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic" privileges
  252. ALLOW_ACCESS : Enable sel-specific access controls
  253. AUTO_HEADER:  Automatic generation of response headers from <HEAD> elements.
  254. AUTO_NAME : Resolving requests for directories (that end with /)
  255. CHECK_ADD_PRIVS: Enable checking for "dynamic privileges"
  256. CHECK_ALIAS: Enable alias checking
  257. CHECKLOG:  When and how to check for "logon rights".
  258. CONTENT_MD5 : Enable creation of Content-MD5 header
  259. DEFAULT: The "default" (home) page.
  260. DIR_EXCLUSION: Files and subdirectories that !DIR should exclude
  261. DIR_ACCESS and DIR_ACCESS_PRIVS: Supress !DIR display of selected files & dirs
  262. DIR_OPTIONS: Set the !DIR display options 
  263. DISPLAY_ENV: write "SRE-http" environment variables to PMPRINTF window
  264. DELIM. : delimiters for SSI keyphrases
  265. DNS_CHECK: Force DNS check before allowing access
  266. DO_HTACCESS: Controls whether the HTACCESS method is used
  267. FIX_EXPIRE: Add an offset to the Expires automatic response header
  268. HEADERS and FOOTERS: Automatically added to all "SSI-enabled" HTML documents
  269. HOME_DIR: The "home directory" --  replaces ~
  270. HOSTS.:  Stem variable containing information on multiple hosts.
  271. HIT_CACHE_LEN and HIT_CACHE_DURATION:  Used to limit false hits.
  272. HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS"
  273. HOME_NAME: The colloquial name of your organization
  274. HTACCESS_FILE : The name of the HTACCESS file.
  275. INHOUSEIPS.: Stem variable containing IP address of "in-house" clients.
  276. INHOUSE. and SUPERUSERS.: Special SSI "replacable" keywords
  277. INHOUSE_PRIVS: Privileges for IN-HOUSE clients.
  278. INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor
  279. KEEP_ADDONS.n: List of addons to preload into macrospace
  280. LOGON_FAIL_FILE: Response file to use if logon fails
  281. MAX_POINTDIST : Used with the POINT type in mappable images.
  282. NO_PROCESSING:  Suppress server side processing
  283. NO_INTERPRET_CODE:  Suppress execution of "in-document" executables.
  284. NO_INCLUDE:  Suppress server side includes.
  285. NOEXT_TYPE: Determine how to handle "no extension" request selectors.
  286. NOT_FOUND_URL : A message, or response file, used if resource is not found
  287. OPTION_HIT_LINE : Used to write OPTION  info instead of counts
  288. OWNERS: IP addresses to be assigned SUPERUSER privileges
  289. PRE_FILTER: Enable use of user written pre-filters
  290. PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s)
  291. POST_FILTER: Enable use of user written post-filters
  292. POSTFILTER_NAME: A series of procedures to call as  post filters(s)
  293. PUBLIC_PRIVS.  Additional privileges for all clients
  294. RECORD_OPTION: Select whether to record all allowed requests
  295. REPLACE_RULES.: Stem variable containing text replacement rules for html files
  296. SMTP_GATEWAY: Domain name of an SMTP server
  297. SSI_CACHE_ON: enable the server side include cache 
  298. SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only
  299. THE_REALM: "Realm" name to use in requests for username/password
  300. UNALLOWEDIPS : Stem variable of "disallowed" IP addresses
  301. UPLOAD_MAXSIZE:  The maximum size (in Kbytes) allowed in a uploaded file
  302. UPLOAD_MINFREE: Space that must remain after an upload
  303. USE_STDOUT: Permit use of standard output in "INTERPRET" keyphrases
  304. USER_LOGON_ENABLE: Enable use of a custom  "user logon procedure"
  305. USER_PRIVS: Additional privileges for registered users
  306. VERBOSE: Controls verbosity of PMPRINTF comments
  307. WEBMASTER: A variable use in SSIs
  308. WRITE_LOGS: Enable the common-log, browser, and referer logs
  309.  
  310. In addition, a number of file and directory names can be modified by
  311. changing entries in the INITFILT.80 file.
  312.  
  313.  
  314. --- Parameters in INIT_STA.80
  315.  
  316. ALWAYS_CHECK_PRIVS: Flag to "check client privileges even if it is a public url"
  317. BackupServerList: ip addresses of servers to distribute to under load
  318. Ce_GZIP: Perform on-the-fly GZIP content-encoding 
  319. Cgi_Bin_Pieces: Send pieces of CGI-BIN output as they become available
  320. Cgi_Post_Long_Get: Convert long GET requests to POST requests
  321. Custom_Inits: Comma delimited list of "custom initialization procedures"
  322. Default_encryption: The default encryption algorithim. 
  323. Delay_seconds: how frequently SRE-http checks for input file updates
  324. Delta_encoding_enable: enable support for delta encoding
  325. Delta_encoding_maxsize: maximum size of delta encoding cache
  326. Digest_auth: Enable use of digest authentication
  327. Dir_Cache_Size: size of the directory-listing cache
  328. Dir_Cache_Duration: lifespan of entries in the directory-listing cache
  329. Delay_Seconds: time delay for SRE-http to check parameter files for changes
  330. Empty_Path_Ok: CGI-BIN control; what to do if no path_info recieved
  331. Enable_Encryption: enable sre-http encryption
  332. Event_Check: check events
  333. Get_Decode_Cptions: Enable URL-decoding of options of GET requests 
  334. Hit_Superuser_Suppress: modify HIT_OWNER_SUPPRESS to check for SUPERUSERS
  335. Ncsa_Ismap: substring(s) that signals "this is an NCSA mappable image request"
  336. Cern_Ismap: substring(s) that signals "this is a CERN mappable image request"
  337. Head_To_Get: tell addons that HEAD requests are GET
  338. Key_Preface: optional preface for server side include keywords
  339. Logon_Limit:  maximum # of attempts, per minute per client
  340. LoadThreshold: Used with BACKUPSERVERLIST (load at which transfer occurs)
  341. Main_Server: An IP address for a "main server" 
  342. Message_Scramble: used by messages boxes to encode passwords and nonces
  343. Never_Imagemaps: suppess check if this is an imagemap
  344. Never_Publicurls: suppress checking for publicurls
  345. No_Remote_Config: Suppress remote configuration
  346. No_No_Record: Suppress the !NORECORD directive
  347. Pre_Reply_Procedure: an external rexx program to call before sending response
  348. PROXY_CACHE: Allow proxy caching (or SREPROXY caching)
  349. Pmprintf_Opt: Output type for SRE-http's audit file
  350. Put_No_Overwrite: Allow PUT method requests to overwrite existing files
  351. Quick_Interp: Shorthand for INTERPRET FILE
  352. Quick_Interp_Code: Shorthand for INTERPRET CODE
  353. Quick_Replace: Shorthand for REPLACE
  354. Range_at_end: Enable use of ;range_info (at end of selector)
  355. Realm_1st_Priv: If need be, use first resource privilege as the realm
  356. Record_Cache_lines: Size of RECORD_ALL_FILE cache
  357. Sem_Maxwait: waiting time till threads check their queue
  358. Ssi_Extensions: extensions for which the ssi_shtml_only parameter applies
  359. Ssi_Cache_Size: size of the ssi-cache
  360. Ssi_Cache_Duration: lifespan of entries in the ssi-cache
  361. Ssi_Cache_Stamp: Type of "trigger" check (used with ssi-cache)
  362. suppress_gzip_te: Suppress on-the-fly gzip
  363. User_Logon_Proc: Name of an alternate "user logon procedure"
  364. Wild_Sels_Ok: Use * in selectors to find best matching file
  365.  
  366.  
  367. --- Parameters in SREFMON.CMD
  368.  
  369. Check_compliance: Check GoServe settings for http/1.1 "compliance"
  370. Clear_Macrospace: Clear macrospace when GoServe is launched
  371. Cfgs_Dir: Location of SRE-http configuration files
  372. Doanyway_Loops: Re-read parameters after this many loops
  373. Do_Cleanup: Cleanup orphaned cgi-bin temp files
  374. logfile_maxsize: Maximum size of log files
  375. MD5_Cache: Size of cache in the MD5 daemon
  376. Mediatype_File_Always: Examine MEDIATYP.RXX only when no default match
  377. No_DNS: Suppress DNS lookup of clientname's 
  378. No_superceding_realm: Suppress use of superceding realms
  379. Storage_Daemons: Number of variable storage daemons to launch
  380. Use_Dynamic_Lib: Select dynamic or static macrospace library
  381. Use_Lib_Dir: Alternative location of macrospace library files
  382. Pmprintf_Line_Length: Maximum line length to PMPRINTF
  383. Pmprintf_Log_File: Name of SRE-http (PMPRINTF) log file
  384.  
  385.  
  386.  
  387. 2g. Full description of parameters
  388.  
  389.  
  390. ************
  391. ACCEPT_RANGE: Return only specified range of the request file
  392.  
  393. You can instruct SRE-http to respond to a "range:" request header. If such a
  394. request header is present, SRE-http will extract the "byte
  395. range" information, and return only this portion of the request file.
  396.  
  397.  
  398. If accept_range=NO, this processing will not occur -- the entire file will
  399. always be returned.
  400. If accept_range=YES, this processing will occur.  Of course, if there is
  401. no range: header, then the entire file is returned.
  402.  
  403.   Example: accept_range='YES'
  404.  
  405. (ACCEPT_RANGE can be host specific)
  406.  
  407. ***********
  408. ACCESS_FAIL_FILE
  409.  
  410. If SEL-specific access control is enabled (ALLOW_ACCESS=1),
  411. and a client does not have sufficient privileges (i.e; none of 
  412. her client privileges appear in the resource privileges list 
  413. associated with the chosen selector) you can use the ACCESS_FAIL_FILE 
  414. as a response.
  415.  
  416. ACCESS_FAIL_FILE should be one of the following values:
  417.   -1 : Terse denial: Do NOT send a message, and do NOT ask for authorization.
  418.        Hint: this is useful when combined with "dynamic privileges"
  419.    0 : Do NOT use an access_fail_file -- just ask for authorization
  420.    1 : If a "SEL-specific" access file is specified (in ACCESS.IN or
  421.        ATTRIBS.CFG), use it. Otherwise, ask for authorization
  422. filename.ext : The "default" file (fully qualified) to return when 
  423.                the client does not have access privileges for this selector.
  424.                If a relative file name is used, the file is assumed
  425.                to be relative to the GoServe working directory.
  426.                Note that if a "SEL-specific" access-fail
  427.                file is specified (in ACCESS.IN), then this is NOT used
  428.                (the "SEL-specific" access-fail file is used instead)
  429.  
  430. As with the LOGON_FAIL_FILE, when the ACCESS_FAIL_FILE is an HTML document,
  431. server side includes are NOT attempted. However, a few special 
  432. substitutions will occur (when the ACCESS_FAIL_FILE is an HTML document):
  433.     <!--#URL--> phrases are substituted with the request selector.
  434.     <!--#SERVER--> phrases are substituted with the servername.
  435.     <!-- #WEBMASTER --> phrases are substituted with the WEBMASTER variable.
  436.     <!-- #MESSAGE --> phrases are substituted with a short description
  437.                      of the reason for failure
  438.     <!-- #LINK --> phrases are substituted with a "forced" URL: which points
  439.                    back to this resource, and forces an "ask authorization"
  440.                    if access is denied.
  441.  
  442. It is HIGHLY recommended that a #LINK be included.  Without such an
  443. entry, the client will be unable to enter a new username/password, should
  444. his first entry be misspelled (or if he had previously used a
  445. different username/password for a different resource on the same realm
  446. or your site).
  447.  
  448. PROVISO:
  449.    In some cases (such as when dynamic privileges are used to control
  450.    access to .GIF files), you may want to use an ACCESS_FAIL_FILE that does
  451.    not contain a #LINK.  
  452.  
  453. Examples:
  454.    ACCESS_FAIL_FILE=0
  455.    ACCESS_FAIL_FILE='D:\goserve\accfail.htm'
  456.  
  457. Notes:
  458.   * When  ACCESS_FAIL_FILE=0,
  459.       ** the client will be re-sent an authorization request.
  460.       ** SEL-specific access fail files are NOT used, even if one 
  461.          is available.
  462.  
  463.   * The #LINK entry uses a special form of SRE-http request selector.
  464.     The effect is to force SRE-http to request authorization should
  465.     the current username/password be incorrect; thereby avoiding an
  466.     annoying recursive trap.
  467.  
  468.   *  Reminder: the LOGON_FAIL_FILE is used when the client
  469.      fails a "generic" logon (that is, she does not have a valid
  470.      username and password).  In contrast, the ACCESS_FAIL_FILE
  471.      (or the Sel-specific access fail file) is used when the client 
  472.      does not have sufficient "client privileges".
  473.  
  474. (ACCESS_FAIL_FILE can be host-specific)
  475.  
  476.  
  477. ***********
  478. ADD_USER_NAME: Controls whether a clients "logon name" should be
  479.                added to the list of client privileges.
  480.  
  481.         YES: Add logon name to client privilege list
  482.         NO: Do not add logon name to client privilege list.
  483.  
  484.         This can be a useful means of personallizing a client's
  485.         privilege list (of course, you could always enter his
  486.         name in the privilege list when setting up his
  487.         username/password entry).
  488.  
  489.   Example:
  490.         ADD_USER_NAME='YES'
  491.  
  492.    Usage Example:
  493.             if a username of ACIDER exists, with a client privileges of
  494.             HARD SOFT, then if ADD_USER_NAME='YES', an ACIDER client
  495.             privilege is added (yielding a client privilege list of
  496.             ACIDER HARD SOFT).
  497.  
  498. Notes:
  499.  *   For INHOUSEIPS. entries, the "clientname" (the full, dotted, IP name) is
  500.      used as the "logon name".
  501.  
  502.  *   If you set ADD_USER_NAME=1, you should be careful that the usernames
  503.      you assign (in the USERS.IN file) do not conflict with the words used for
  504.      privileges. In particular, don't casually give someone a
  505.      username of SUPERUSER or INHOUSE.
  506.  
  507. ***********
  508. ADD_RESOURCE_NAME: Controls whether the "action" portion of the request
  509.                    selector be included as a resource privilege.
  510.  
  511.         YES: Add the action to the resource privilege list
  512.         NO:  Do not add.
  513.  
  514.         Similar to the ADD_USER_NAME, this can be a useful shortcut
  515.         in environments where highly specific access controls are
  516.         required.
  517.  
  518.         CAUTION: When ADD_RESOURCE_NAME='YES', unmatched requests
  519.                  will require clients to have a privilege matching
  520.                  the "requested resource".
  521.  
  522.    Example: ADD_RESOURCE_NAME='YES'
  523.  
  524. Notes:
  525.  *   The "action" portion of a request selector is everything before the
  526.      first ? character (if no ? is found, the entire request selector is used).
  527.  
  528.  *   If ALLOW_ACCESS='YES', ADD_RESOURCE_NAME has no effect.
  529.  
  530. ************
  531. ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic"
  532.                   client privileges.
  533.  
  534. As a security measure, when SRE-http adds "dynamic" privileges, it will
  535. append the ADD_PRIVS_PREFIX.  For example, if ADD_PRIVS_PREVIX='!', and
  536. a <!-- INTERPRET FILE ADDPRIVS.RXX  SATURN ,30 --> keyphrase appears
  537. in a requested document, the client will be granted a !SATURN
  538. client-privilege (in this example, for 30 minutes).
  539.  
  540. The rationale is to prevent unscrupulous individuals, who may have been
  541. granted a limited ability to post documents to "user" sub-directories,
  542. from subverting access control with keyphrases of the form:
  543.         <!-- INTERPRET FILE ADDPRIVS.RXX  SUPERUSER, 100 -->
  544.  
  545. If such problems are not likely to occur, you may want to
  546. set ADD_PRIVS_PREFIX=' '
  547.  
  548.   Example:
  549.         ADD_PRIVS_PREFIX='!'
  550.  
  551. (ADD_PRIVS_PREVIX may be host specific)
  552.  
  553. ************
  554. ALLOW_ACCESS : Control access to server resources.
  555.  
  556.    You can check "access privileges" for server resources (files, programs, etc.)
  557.    by setting the ALLOW_ACCESS variable.
  558.           YES : no access control (ACCESS.IN is not use to limit access)
  559.       INHOUSE : don't check in-house and superusers.
  560.           NO  : don't check superusers.
  561.   Note that checking involves examination of privilege information
  562.   on a  per-request-selector basis (using ACCESS.IN).
  563.  
  564.   Note that ACCESS.IN (also known as the ACCESS_FILE) is  used for:
  565.     1) Controlling server side include privileges and server side processing,
  566.         on a SEL-specific basis
  567.     2) Allowing caching of files that would normally not be cached
  568.         (If CHECKLOG<>"YES" or ALLOW_ACCES<>"YES", then caching is
  569.         suppressed).
  570.     3) Setting the default "realm" of the resource (see the THE_REALM variable)
  571.     4) Permitting PUT and DELETE methods to operate
  572.     5) Suppressing aliasing, virtual directory lookup, and "post-filtering"
  573.     6) Specifying an "advanced options" file
  574.  
  575.    If you do not ever want SRE-http to check the access file,
  576.    just set access_file=" ". BUT if you do, the  above features will not be
  577.    available!
  578.  
  579. Notes:
  580.     * The default name of the ACCESS_FILE is ACCESS.IN (in the DATA/
  581.       directory of GoServe's "working" directory).
  582.  
  583.     * WARNING: If you set allow_access="NO", and access_file=" ", then
  584.             only SUPERUSERS will have access to your site!
  585.  
  586. (ALLOW_ACCESS can be host specific)
  587.  
  588. ********
  589. AUTO_HEADER.  Automatic generation of response headers.
  590.  
  591. AUTO_HEADER is used to automatically generate response
  592. headers, based on LINK and META HTTP-EQUIV elements in the <HEAD>
  593. section of HTML documents.
  594.  
  595. 3 values are supported:
  596.        NO : Do not generate these headers
  597.      HEAD : Generate headers for HEAD requests only
  598.    ALWAYS : Generate headers for HEAD and GET requests.
  599.  
  600. Note that this is only relevant for HTML files.
  601. Also, when AUTO_HEADER occurs, the html file is parsed for header information
  602. before server side includes are attempted -- that is, any server side
  603. include in the <HEAD> of a document will NOT appear in the response
  604. headers (but they will appear in the body of the response).
  605.  
  606. IN OTHER WORDS -- If you set AUTO_HEADER='ALWAYS', you should NOT use 
  607. SSI's <HEAD> portion of HTML documents
  608.  
  609.   Example: AUTO_HEADER="HEAD"
  610.  
  611. Technical note: HTTP purists disapprove of the use of the "HEAD" value;
  612. since HEAD method requests are supposed to return exactly the same
  613. response headers as GET method requests.
  614.  
  615. (AUTO_HEADER can be host specific)
  616.  
  617.  
  618. *********
  619. AUTO_NAME : Resolving requests for directories.
  620.  
  621.  AUTO_NAME is used to deal with non-specific requests that are NOT to the
  622.  root (the /) directory.
  623.  
  624.  AUTO_NAME should contain a space delimited list of potential "directory
  625.  specific default names".
  626.  
  627.  Several special names are supported:
  628.       *.HTM
  629.   or  *.HTML :  means "use the "directory" name, with .HTM or .HTML appended
  630.      !CREATE :  Create a list of links, one for each file in the directory.
  631.     !CREATE* : Same as !CREATE, but include links to subdirectories
  632.  
  633.   Example: AUTO_NAME=" *.HTM INDEX.HTM PAGE.HTM DESCRIBE.HTM  !CREATE "
  634.  
  635.      If a request for xxx/yyy/ (with optional ?abc after the final /) is
  636.      recieved, then
  637.           first, yyy.htm is looked for (in datadir/xxx/yyy)
  638.         second, INDEX.HTM (in datadir/xxx/yyy).
  639.         Then PAGE.HTM, and then, DESCRIBE.HTM are tried.
  640.         If all these fail, !CREATE signals "just display a list of the files
  641.         in this directory".
  642.  
  643.  
  644.      Note that if !CREATE were not included in this list, and
  645.      none of the requested files exist, a  not_found message is returned.
  646.      Similarly, if !CREATE fails (if there is no such directory),
  647.      the not_found message is returned (see the description of NOT_FOUND_URL
  648.      for details).
  649.  
  650.  
  651.   Notes:
  652.     * AUTO_NAME is NOT used when request is to the root (to /) -- DEFAULT is
  653.       used!
  654.     * See NOEXT_TYPE for a discussion of how to deal with requests that
  655.       have neither an extension or a trailing / (i.e.; xxx/yyy).
  656.     * You can put a "pathed" name (using /, relative to the data directory)
  657.       This is one means of handling bad requests (but only if the request
  658.       ends in a /) -- just put the home page document in the auto_name list,
  659.       i.e.; auto_name=" * INDEX.HTM /HOMEPAGE.HTM "
  660.     * It is recommended that a !CREATE be placed at the end of the
  661.       AUTO_NAME list (since !CREATE is "always a match", assuming the
  662.       request points to a valid directory)
  663.  
  664.   Example: AUTO_NAME=" * INDEX.HTM  "
  665.  
  666. (AUTO_NAME can be host specific)
  667.  
  668.  
  669. CAUTION: When using AUTO_NAME (and other types of local redirection)
  670. URL resolution by the client's browser may have unexpected consequences.
  671. See the discussion of "local  vs remote redirection" at the bottom of
  672. this document for details!
  673.  
  674.  
  675. ****************
  676. CE_GZIP: Default enabling of on-the-fly GZIP content-encoding
  677.  
  678. If CE_GZIP is enabled, and the client includes a GZIP 
  679. in an Accept-encoding header, then SRE-http will perform
  680. a GZIP "content-encoding" on the resource. Using a 
  681. GZIP content-encoding can help save bandwidth.
  682.  
  683.    CE_GZIP=1  to enable
  684.    CE_GZIP=0  to suppress
  685.    CE_GZIP=-1  Always disable (CE_GZIP advanced option can NOT override)
  686.  
  687. Notes:
  688.    *  a CE_GZIP "advanced option" will override this default
  689.  
  690.    * if a GZIP content-encoding has already been applied (and noted in a
  691.      content-encoding response header), then GZIP content-encoding will NOT
  692.      be performed.  In particular, if content-negotiation yields a
  693.      GZIP content-encoded variant, then on-the-fly GZIP is NOT re-done
  694.  
  695.    * If a GZIP content-encoding is done, then GZIP transfer encoding (as
  696.      enabled by the SUPPRESS_GZIP_ENCODING parameter) will NOT be
  697.      attempted.
  698.  
  699.    * GZIP content-encoding is NOT attempted on !RANGE requests, or for
  700.      delta-encoded responses (when a "difference file" is returned)
  701.  
  702.  
  703. **************
  704. CHECK_ADD_PRIVS: Check for "dynamic privileges"
  705.  
  706. CHECK_ADD_PRIVS is used to instruct SRE-http to check for "additional,
  707. dynamic privileges", and if they exist, add them to the client's "privilege"
  708. list.
  709. CHECK_ADD_PRIVS can take two values;
  710.     YES :  Check for additional, dynamic privileges
  711.      NO:   Do NOT check for additional, dynamic privileges
  712.  
  713.  Example:
  714.         CHECK_ADD_PRIVS='NO'
  715.  
  716. Note:
  717.   *  When CHECK_ADD_PRIVS='YES', an _ADDPRIV.DOC file is created in the
  718.      TEMPDATA_DIR directory (typically, \GOSERVE\TEMP).
  719.  
  720.   *  See ADDPRIVS.DOC for a detailed discussion of "additional, dynamic"
  721.      privileges.
  722.  
  723. (CHECK_ADD_PRIVS can be host specific)
  724.  
  725. ***************
  726. CHECK_ALIAS: Controls whether alias checking occurs.
  727.  
  728.    SREFILTR can check all requests to see if they are aliases for some
  729.    other action.
  730.  
  731.      Uses of aliases include:
  732.         *  implementation of searchable indices
  733.         * "local" redirection -- useful as a means of assigning
  734.            proper document names  to abbreviations
  735.           (say, to convert an request of OVERVU into OVERVIEW.HTM)
  736.         * "remote" document redirection -- often to a different
  737.           ip addreess
  738.         * transferring non-data directory files
  739.  
  740.  Setting CHECK_ALIAS to --
  741.        NO suppresses this alias lookup
  742.        YES causes this lookup to be done for all requests
  743.  
  744.  
  745.   Example:  CHECK_alias="YES"
  746.  
  747. (CHECK_ALIAS can be host specific)
  748.  
  749. ************
  750. CHECKLOG:  When and how to check for "logon rights".
  751.  
  752.  "Logon rights" refer to basic site access rights.  These may
  753.  be (or may not) be used with SEL-specific access privileges (see ALLOW_ACCESS)
  754.  
  755.   CHECKLOG can take four values:
  756.          1) NO  -- never check (basic access granted to all clients)
  757.          3) YES or ALWAYS -- check on every request.
  758.          4) INHOUSE -- Access allowed only for INHOUSE and SUPERUSERS.
  759.                        INHOUSE users are determined by occurence of a
  760.                        INHOUSE in the client's 'privilege list', or
  761.                        if the client has an IP address listed in the
  762.                        INHOUSEIPS.n variables.
  763.    Note: if ALWAYS, YES or INHOUSE is selected, then GOSERVE will NOT cache GET
  764.          requests (the discussion of the ALLOW_ACCESS variable
  765.          describes an exception to this through the use of the CACHE
  766.          permission)
  767.  
  768.    Example:   checklog='NO'
  769.  
  770. (CHECKLOG can be host specific)
  771.  
  772.  
  773. ************
  774. CONTENT_MD5  -- Enable creation of an Content-MD5 response header.
  775.  
  776. Content-MD5 response headers contain an "MD5 digest" of the body of the 
  777. response. Savvy clients can use this information to check the integrity 
  778. of transmission (however, it is not proof against tampering).
  779.  
  780. The MD5 digest is relatively compute intensive, hence general use of it may not
  781. be recommended.  In fact, you can use the "advanced options" file to enable the
  782. creation of a content-md5 response header on a selector specific basis.
  783.  
  784.  
  785. To disable, set CONTENT_MD5=0
  786.  
  787. If CONTENT_MD5 = 1, then a dynamic procedure is used to compute the MD5.
  788.  
  789.  
  790. If CONTENT_MD5 = 2, then the MD5.EXE program (that comes with SRE-http
  791. ver 1.3f and above) is used to compute the MD5 of files -- MD5.EXE seems
  792. to be better behaved in circumstances that crash the MD5 procedure.
  793.  
  794.      **  NOTE: to use MD5.EXE you must have EMX installed!  **
  795.  
  796.   Examples:
  797.         CONTENT_MD5=1           ; enable creation of Content-MD5 response headers
  798.         CONTENT_MD5=2           ; enable creation of Content-MD5 response headers
  799.                                 ; using the MD5.EXE program
  800.         CONTENT_MD5=0           ; do not create.
  801.  
  802. Note: as of 1.3h.0400.a, the occassional instability of CONTENT_MD5
  803. generation seems to be solved. Hence, there is less reason
  804. for using MD5.EXE.
  805.  
  806. **********
  807. DEFAULT -- The "default" (home) page.
  808.   Use this when a default request (say, http://www.joe.com/ ) occurs.
  809.  
  810.    Note: it is traditional, but by no means required, to use INDEX.HTML 
  811.          as your default (as your "home page")
  812.  
  813.   You can enter one, or several, different names.  Each will be tried
  814.   in turn, if the file exists (relative to the possibly host specific 
  815.   data directory), it will be used.
  816.  
  817.   You can also use DEFAULT to redirect a request (using a 301 redirection),
  818.   say, for an IP Alias that has moved.  To do this, just enter the full
  819.   URL -- be SURE to include the leading http://
  820.  
  821.    Examples: default='index.htm index.html '
  822.              default.zoo='ourzoo.htm'
  823.              default.circus='http://silly.places.net/bigtop.htm'
  824.  
  825.   Notes on examples:
  826.     * the "generic" DEFAULT dictates that Index.htm be used first; 
  827.      if not found, index.html is then tried.
  828.    * you can NOT include * or ? in DEFAULT filenames.
  829.    * default.zoo defines the DEFAULT file for requests to the
  830.      ZOO host only. 
  831.    * default.circus causes request to the default document of the circus 
  832.      host to be redirected to silly.places.net
  833.  
  834. (DEFAULT can be host specific)
  835.  
  836. CAUTION: When using DEFAULT (and other types of local redirection)
  837. URL resolution by the client's browser may have unexpected consequences.
  838. See the discussion of "local  vs remote redirection" at the bottom of
  839. this document for details!
  840.  
  841. **********
  842. DIR_EXCLUSION: A list of files and subdirectories that the !DIR
  843.                (and other) directory listers should exclude.
  844.  
  845. SRE-http's !DIR special command (and GETAFILE addon) can be instructed
  846. o suppress displaying certain files and subdirectories.
  847. To do this, one uses the DIR_EXCLUSION parameter.  DIR_EXCLUSION should 
  848. contain a space delimited list of files and subdirectories".
  849.  
  850.    Example:  dir_exclusion='Htaccess. /private describe.txt  *.CNT '
  851.  
  852. Note that a / must preceed subdirectories (otherwise, the entry is
  853. interpreted as a file name).
  854.  
  855. Notes:
  856.   *  The !dir "special command" is used by the !CREATE option of AUTO_NAME.
  857.   *  Subdirectories are assumed to be relative to the "requested directory",
  858.      and should only be one name deep.  
  859.      That is, DIR_EXCLUSION='/personal/family ' is invalid.
  860.   *  The wildcard character (*) can be used in file and directory names.
  861.   *  For a further discussion of the !dir function, see DIR.DOC.
  862.  
  863. (DIR_EXCLUSION can be host specific)
  864.  
  865. **********
  866. DIR_ACCESS and DIR_ACCESS_PRIVS
  867.  
  868.  For extra security, you can use DIR_ACCESS to suppress display of 
  869.  selected directories. DIR_ACCESS is checked by both the !DIR SRE-http
  870.  facility, and the GETAFILE addon.
  871.  
  872.  DIR_ACCESS should contain a space delimited list of "selectors" that
  873.  !DIR (and GETAFILE) will limit access to.
  874.   
  875.    More precisely, each item in DIR_ACCESS is compared against the 
  876.    requested directory; and if any of them match (with wild cards allowed) 
  877.    then the client must have one of the privileges listed in DIR_ACCESS_PRIVS
  878.    (or must be a SUPERUSER).
  879.  
  880.         Example: DIR_ACCESS=' SYSTEM  INFO/SECRETS   */PRIVATE '
  881.                  DIR_ACCESS_PRIVS='SPECIAL1 DIRPRIVS '
  882.  
  883.  
  884. (DIR_ACCESS and DIR_ACCESS_PRIVS can be host specific)
  885.  
  886.  
  887. **********
  888. DIR_OPTIONS: Set the display options of the !dir function.
  889.  
  890. To control the display option of SRE-http's !dir special command, you should
  891. modify the DIR_OPTIONS parameter.  DIR_OPTIONS should contain a
  892. space delimited list of parameters.
  893.  
  894. The allowed options are:
  895.   AUTO_DESCRIBE DESCRIBE DESC_LEN DATEFMT MULTI_SEND
  896.   NOSIZE  NOTIME NODATE NOICON NOSORT NODIR NO_RECURSE_DIR
  897.   SIZEFMT SHOWPARENT TABLE TABLE_BORDER TIMEFMT
  898.  
  899. For a description of what these options do, see DIR.DOC.
  900.  
  901.   Example: DIR_OPTIONS='notime auto_describe describe  datefmt=u '
  902.  
  903. Notes:
  904.   *  The !dir special command is used by the !CREATE option of AUTO_NAME.
  905.  
  906. (DIR_OPTIONS can be host specific)
  907.  
  908. **********
  909. DISPLAY_ENV -- write "SRE-http" environment variables to PMPRINTF window
  910.  
  911. Use this as a debugging tool to display the values of the SRE-http
  912. enviroment variables in the PMPRINTF window (and possibly the SREHTTP.LOG
  913. file, if you set PMPRINTF_OPTIONS accordingly).
  914.  
  915.   DISPLAY_ENV = 1 : The SRE-http environment variables (basically,
  916.                     transforms of everything in INITFILT.80 and REPSTRGS.IN)
  917.                     are written to the "PMPRINTF" window.  This will occur
  918.                     whenever the environment variables are refreshed
  919.                     (say, when you change INITFILT.80).
  920.  
  921.       otherwise  : Do not write environment variables.
  922.  
  923. Example
  924.   DISPLAY_ENV=0
  925.  
  926. (DISPLAY_ENV is NOT host specific)
  927.  
  928. *************
  929. DELIMITERS for KEYPHRASES
  930.  SREFILTR does "server side" includes by looking for keyphrases in your
  931.  HTML documents. A keyphrase is defined as: delim1  keyword keyvalue delim2.
  932.  
  933.  Delim1 and Delim2 are strings (possibly 1 character) that signal the
  934.  location   of the keyphrase.  These delimiters should be odd,
  935.  yet easy to remember (and not likely to occur in your text).
  936.  ALTHOUGH WE DO NOT RECOMMEND IT, you can enter several sets of delimiters.
  937.  
  938.  The default set is the HTML comment delimiters:  '<!--'  and '-->' .
  939.  If you use these, the raw document will not look too wierd should it be
  940.  accidentally sent to the client "as is").
  941.  
  942.  For each set of delimiters, You MUST specify both the beginning (DELIM_1)
  943.  and end (DELIM_2) delimiter.
  944.  
  945.  
  946.  Examples:
  947.  
  948.      delim_1.1="<!--"
  949.      delim_2.1="-->"
  950.  
  951.      delim_1.2="{"
  952.      delim_2.2="}"
  953.  
  954.      delim_1.3=0
  955.      delim_2.3=0
  956.  
  957.  
  958. or, if just the ZOO host should recognize a second set of delimiters
  959.      delim_1.1="<!--"
  960.      delim_2.1="-->"
  961.  
  962.      delim_1.2=0
  963.      delim_2.2=0
  964.  
  965.      delim_1.1.zoo="<!--"
  966.      delim_2.1.zoo="-->"
  967.  
  968.      delim_1.2.zoo='{'
  969.      delim_2.2.zoo='}'
  970.  
  971.      delim_1.3.zoo=0
  972.      delim_2.3.zoo=0
  973.  
  974. Note: The most important reasons for NOT using several sets of delimiters:
  975.  
  976.      * SSI-Caching will be turned OFF (regardless of value of SSI_CACHE_ON)
  977.      * SSI processing will be slower
  978.  
  979.         But if you are willing to accept these performance disadvantages,
  980.         then the use of several delimiters should cause NO problems.
  981.  
  982. (DELIMS can  be host specific)
  983.  
  984. *************************
  985. DNS_CHECK: Force DNS check before access
  986.  
  987.  As a security measure, you might want to look up the IP name of the
  988.  client (using the client's IP address and his DNS).  If no name can
  989.  be found, logon is not allowed.
  990.  
  991.       NO: do not check DNS for an IP name
  992.       YES: Force lookup of IP name before allowing access
  993.  
  994.  Although this will provide some security agains "fake" IP addresses, it
  995.  will also slow down response time and disable caching by proxy servers.  
  996.  Furthermore, many legitimate clients may not have "names" (say, if
  997.  they are using pooled IP addresses).
  998.  
  999.  Example:
  1000.      DNS_CHECK='NO'
  1001.  
  1002. (DNS_CHECK can be host specific)
  1003.  
  1004.  
  1005. ********
  1006. DO_HTACCESS: Controls whether the HTACCESS method is used.
  1007.  
  1008. To provide compatability with HTTPD style servers (such as Don Meyer's
  1009. GOHTTP), SRE-http supports the HTACCESS method of access control
  1010. (see the description of HTACCESS_FILE in INITIFLT.DOC for details).
  1011.  
  1012. DO_HTACCESS can take two values
  1013.    YES:   Enable support of the HTACCESS access control method
  1014.    NO:    Do NOT support HTACCESS.
  1015.  
  1016.   Example:  DO_HTACCESS='YES'
  1017.  
  1018.  
  1019. When DO_HTACCESS='YES', SRE-http will check for an HTACCESS file
  1020. in the directory (and parent directories) of the requested file.
  1021. Note that this control is by "file name", rather then by request selector.
  1022.  
  1023. Details on HTACCESS files are in the description of the
  1024. HTACCESS_FILE variable.
  1025.  
  1026. Details concerning the use of the HTACCESS method can be found at:
  1027.   http://w3.ag.uiuc.edu/DLM/GoHTTP/htaccess.html
  1028.  
  1029.  
  1030. (DO_HTACCESS can be host specific).
  1031.  
  1032.  
  1033. *********
  1034. FIX_EXPIRE:  For fixing the GoServe automatic response header.
  1035.  
  1036. For certain responses that return temporary file, setting FIX_EXPIRE > 0
  1037. will cause a modifyed "Expires: " response header to be returned.
  1038. In particular, it will add FIX_EXPIRE "fractions of a day" to the
  1039. current date/time, and use it as the File-Expires date.
  1040.  
  1041. In particular, FIX_EXPIRE is used whenever a server-side include containing 
  1042. HTML document is being returned.  It is also used when temporary files are
  1043. returned by SRE-http addons (such as by GETAFILE and DOSEARCH), and by 
  1044. CGI-BIN scripts.
  1045.  
  1046. FIX_EXPIRE=0, 
  1047.   do no add an offset to an Expires: response header.
  1048.  
  1049. FIX_EXPIRE>0
  1050.   add fix_expire "days" to an Expires: response header (fix_expire is added to
  1051.   the current time).
  1052.  
  1053. Setting FIX_EXPIRE > 0 can be useful when relatively static (that do not
  1054. depend on the current "hour") server side includes are performed.
  1055. In such cases, GoServe automatically sets the expiration time to be
  1056. the current moment.  This can be a hassle for some clients (Netscape
  1057. will, incorrectly, reload such "expired" documents if "backed up" to).
  1058.  
  1059. Note that a value of FIX_EXPIRE=0.1 = .1 * 24 hours = 2.4 hours.
  1060.  
  1061. Example: FIX_EXPIRE=0
  1062.  
  1063. (FIX_EXPIRE can  be host specific)
  1064.  
  1065. Note: Along with this modified expiratoin date, SRE-http ver 1.3A and 
  1066. above will add a
  1067.      Cache-Contol: max-age=0 
  1068. header -- which http/1.1 compliant applications will use instead of the  
  1069. the Expires: response header.
  1070.  
  1071. **********
  1072. HEADERS and FOOTERS: Automatically added to all "SSI-enabled" HTML documents.
  1073.     You can specify a block of HTML code to include at the beginning and the
  1074.     end of the body of the document.  This is done by specifying HEADERS.n
  1075.     (n=1...) and FOOTERS.n
  1076.     To suppress this, set HEADERS.1=0 and/or FOOTERS.1=0
  1077.  
  1078.     Notes:
  1079.         * HEADERS.n lines are written (consecutively) just after the first
  1080.           <BODY> phrase in your document (see example 3 below for an exception
  1081.           to thisrule)
  1082.         * FOOTERS.n lines are written just before the last </BODY> phrase
  1083.           in your document.
  1084.         * Headers and footers are NOT added to documents for which server side
  1085.           includes are suppressed. For example, if you've set SSI_SHTML_ONLY='YES',
  1086.           then HTML documents that end with a .HTML will NOT have footers and
  1087.           headers added.
  1088.  
  1089.  
  1090. Examples:
  1091.  
  1092.   1) Simple case:
  1093.      HEADERS.1=' <em> Our docuuments are supplied as-is </em> <p>'
  1094.      FOOTERS.1=' <p> <strong> goodbye  </strong> '
  1095.  
  1096.   2)To suppress headers and footers
  1097.      HEADERS.1=0
  1098.      FOOTERS.1=0
  1099.  
  1100.   3) The "exception":
  1101.     Headers.1='<BODY bgcolor="#5500aa"> <h1> This is our site! </h1> '
  1102.  
  1103.         Whenever the HEADERS.1 lines begins with <BODY, then
  1104.         rather then writing the header AFTER the first <BODY ...> element,
  1105.         the header will replace the first <BODY ..> element.
  1106.  
  1107.  
  1108. HEADERS and FOOTERS can be host specific.
  1109.   For example:
  1110.       HEADERS.1.ZOO = ' <B> The ZOO server </b> '
  1111.       HEADERS1.1.CIRCUS = '  <em> The Circus Site </em>
  1112.       HEADERS.2.ZOO=0
  1113.       HEADERS.2.CIRCUS=0
  1114.  
  1115.   will set up a one-line header for the ZOO and for the  CIRCUS "hosts".
  1116.  
  1117. *************
  1118. HOME_DIR: The "home directory" -- used as a text replacement whenever a ~
  1119.           is encountered in a request selector.
  1120.  
  1121. A typical value of this would be "Users/".
  1122.  
  1123.   Example: HOME_DIR='USERS/'
  1124.  
  1125. (HOME_DIR can be host specific)
  1126.  
  1127. ADVANCED OPTION: Specifying User Subdirectories
  1128.   In many cases, you may wish clients to have access to particular
  1129.    subdirectories of your "Users" directories.  For example, all
  1130.    "students" may have space on the server machine, some of which
  1131.    is used for web, and some for "personal" purposes. The goal is to
  1132.    give clients direct access to the "web" related directories
  1133.    but not to the "personal" directories.
  1134.  
  1135.    This can be achieved by including a $ in the HOME_DIR parameter.
  1136.    Specifically, the $ is replaced by the substring between the  ~ and the
  1137.    first / following the ~.
  1138.  
  1139.    For example:,
  1140.      If the  HOME_DIR=USERS/$/WWW
  1141.         and the request selector is /~GERALD/RESUME.HTM
  1142.      Then SRE-http will use:
  1143.         /USERS/GERALD/WWW/RESUME.HTM
  1144.    Summarizing, given a $ in the HOME_DIR.
  1145.      1) SRE-http reads the substring (of the request selector) between ~ and
  1146.         the first / following the ~ (i.e.; GERALD)
  1147.      2) The substring is deleted from the request selector
  1148.      3) The $ in the HOME_DIR is replaced with this substring (from step 1)
  1149.      4) The ~ in the modified request selector (from step 2) is replaced with
  1150.         the modified HOME_DIR (from step 3)
  1151.      
  1152.  
  1153. NOTES:
  1154.  
  1155.  * If there is no $ in the HOME_DIR, a simple HOME_DIR for ~
  1156.    replacement is done. For example, if HOME_DIR=USERS/and the
  1157.    request selector is /~GERALD/RESUME.HTM, the result would be
  1158.    /USERS/GERALD/RESUME.HTM
  1159.  
  1160.  * If a / immediately follows the ~ (in the request selector), the $ is
  1161.    removed from HOME_DIR (without replacement).
  1162.  
  1163.  * HOME_DIR substitution occurs BEFORE virtual file lookup and AUTO_NAME
  1164.    construction, but after ALIAS conversion.  Thus, the ~ can point to a
  1165.    virtual directory (or a subdirectory of a virtual directory).
  1166.  
  1167.  * HOME_DIR for ~ substitution is also used when resolving filenames
  1168.    requested in server side includes.
  1169.  
  1170.  * CAUTION: Since HOME_DIR is used in a direct textual substitution, only
  1171.             a mild degree of syntax checking  is attempted. In particular,
  1172.             // are  converted to /.  To be safe, be sure your use of ~ is
  1173.             internally consistent.
  1174.  
  1175.  
  1176. **************
  1177. HOSTS. :  Stem variable containing information on multiple hosts.
  1178.  
  1179.  NOTE:
  1180.      As of ver 1.3d, use of the HOSTS. stem variable is discouraged.
  1181.      Instead, use the CFGLIST.CFG file (in the CFGS\ subdirectory).
  1182.  
  1183. The HOSTS. stem variable(s) is used to define the multiple hosts
  1184. (IP addresses) your server will recognize.
  1185.  
  1186. Each HOSTS. entry should contain the following comma-delimited information:
  1187.     IP_address, host_nickname, default_dir
  1188.  
  1189. Where:
  1190.     IP_address is the IP address (numeric or character) of the host.
  1191.                 You should use the full name -- do not use a "local
  1192.                 abbreviation" (that is, don't use bill as a shorthand
  1193.                 for bill.my.org; even though your local dns may recognize it)
  1194.     host_nickname is the "nickname" that you will use to refer to this host.
  1195.                 It MUST NOT be a number -- that is, it must contain
  1196.                 a non-numeric character. Thus, 234 is invalid, but
  1197.                 N234 is okay.
  1198.                 
  1199.                 Note: To indicate that this is a "superceding host" (defined 
  1200.                       below), the host_nickname MUST start with a _!
  1201.                       (see the HOSTS.3 example below).
  1202.  
  1203.                       To indicate that this is a "strict-superceding host" 
  1204.                      (defined  below), the host_nickname MUST start with a _!!
  1205.                      (see the HOSTS.4 example below).
  1206.  
  1207.     default_directory is the default data directory for this host
  1208.  
  1209. Examples:
  1210.     hosts.1="dh.ag.gov , MY1 , e:\WWW1  "
  1211.     hosts.2=" 151.122.33.6 ,  H20 ,e:\www2  "
  1212.     hosts.3=" forest.ag.gov,  _!Woods ,e:\wwwforest  "
  1213.     hosts.4=" trees.ag.gov,  _!!Tree ,e:\wwwtrees  "
  1214.  
  1215.     hosts.5=0
  1216.  
  1217.   If you do NOT have multiple hosts, set hosts.1=0
  1218.   Note that we recommend that the last hosts.value = 0.
  1219.  
  1220. Definition: superceding hosts.
  1221.  
  1222.    Entries in several of SRE-http's parameter files are either "host
  1223.    specific" or "non-host specific". Host specific entries are only
  1224.    checked for requests that are to a particular host, non-host specific
  1225.    entries are used for all requests.
  1226.  
  1227.    SRE-http will use a "best match" algorithim (described in IN_FILES.DOC)
  1228.    to determine which entry to use.  This algorithim is a function of
  1229.    whether the "host" (to which a request was directed) is a "strict-
  1230.    superceding",  "superceding", or a "non-superceding" host.  Basically:
  1231.  
  1232.    Strict Superceding host: 
  1233.       "Host-specific" entries are checked.  Non-host specific entries 
  1234.        are NOT checked.
  1235.  
  1236.    Superceding host: 
  1237.       "Host-specific" entries are checked.  If there are ANY matching
  1238.       host-specific entries, then the best matching host-specific entries
  1239.       is used. Ifthere are no matching host-specific entries, then the
  1240.       non-host specific entries are checked.
  1241.       In other words, if there are ANY matching host-specific
  1242.       entries, the non-host specific entries will NOT be checked.
  1243.  
  1244.    Non-superceding hosts,
  1245.       Both "host-specific" and "non-host specific" entries are checked.
  1246.       The best match from this combined set of entries is used. Thus,
  1247.       a non-host specific entry can be used in preference to a host-specific
  1248.       entry.
  1249.  
  1250.        
  1251. Note:
  1252.   
  1253.   * A Caution on Using IP Aliases:
  1254.     IP aliases offer a convenient means of
  1255.     setting up multiple hosts (IP names) while only using one numeric ip address.
  1256.     Unfortunately, use of IP name aliases requires browsers that understand
  1257.     HTTP/1.1; specifically, that send the HOST: request header with each request.
  1258.     When an older browsers (that does not include a HOST: request header) makes
  1259.     a request, SRE-http will use the numeric IP address (that is, it will
  1260.     use the "canonical name" for the IP address, rather then the desired alias).
  1261.  
  1262.  *  When using multiple hosts, you can specify many of SRE-http's
  1263.     parameters in INITFILT.80 and in the various .IN and .CTL files,
  1264.     to be "host specific".
  1265.  
  1266.  *  You can define HOST entries using both HOSTS. variables (in INITFILT.80)
  1267.     and the CFGLIST.CFG file. 
  1268.  
  1269.  *  See USE_CFGS.DOC for details on the CFGLIST.CFG fle.
  1270.  
  1271.  
  1272. For obvious reasons, HOSTS can NEVER be host specific!
  1273.  
  1274.  
  1275. ****************
  1276. HIT_CACHE_LEN and HIT_CACHE_DURATION:  Used to limit false hits.
  1277.  
  1278. To reduce the number of "false hits" (from clients returning to
  1279. your document after a short absence, which may be caused by the
  1280. use of a browser's "back" button), a current hits list can be
  1281. maintained.  If a request matches a request in this list (where
  1282. the request selector and the client's IP address are both used),
  1283. the "count of hits" will not be augmented.  Specifically,
  1284. the COUNTER_FILE and the RECORD_ALL_FILE will not be augmented.
  1285.  
  1286. There are two methods of storing these current hits: in the
  1287. SRE-http's "storage" thread, or in a "file":
  1288.  
  1289. 1) The SRE-http's "storage thread". 
  1290.    To specify this, set HIT_CACHE_LEN to the number of entries you wish to set
  1291.    aside.  For example:
  1292.          HIT_CACHE_LEN=1000
  1293.  
  1294. 2) File.  Not as fast, but probably safer if you are storing a lot of hits.
  1295.    To specify this, set:
  1296.          HIT_CACHE_LEN='FILE'
  1297.    A special file in the TEMP/ subdirectory of the GoServe "working"
  1298.    directory, with the name _HITCACH.80 (or .nnn if nnn is your serverport)
  1299.    is created and used to store recent hits.
  1300.  
  1301.     Each selector/client pair will be retained for HIT_CACHE_DURATION minutes.
  1302.     Note that "overflow" will NOT occur, but the _HITCACH.80 file may
  1303.     become large.  Since "expired" entries are removed, only in rare
  1304.     circumstances (extremely heavy load, or when HIT_CACHE_DURATION is
  1305.     very large), will the file size become problemmatic.
  1306.  
  1307.  
  1308. To turn of this feature, set HIT_CACHE_LEN=0
  1309.  
  1310.  
  1311. Example:
  1312.    HIT_CACHE_LEN=500
  1313.    HIT_CACHE_DURATION=5
  1314.  
  1315.    HIT_CACHE_LEN='FILE'
  1316.    HIT_CACHE_DURATION=20
  1317.  
  1318. Notes:
  1319.  
  1320.  * In general, we no longer recommend use of the 'FILE' mode of HIT_CACHE_LEN
  1321.    (the "storage thread" mode is quite stable and can handle a fairly large
  1322.     number of entries)
  1323.  
  1324.  * If you are using the FILE mode, a limit of 10,000 entries is imposed.
  1325.  
  1326.  * HIT_CACHE_LEN and HIT_CACHE_DURATION can NOT be host specific. Note that
  1327.    hits are stored both by selector and by host nickname.
  1328.  
  1329.  
  1330.  
  1331.  
  1332. *****************
  1333. HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS"
  1334.  
  1335.     Switch to turn off and on the "suppresion of OWNER request"
  1336.        HIT_OWNER_SUPPRESS='YES'
  1337.            Do not record (in the COUNTER_FILE or RECORD_ALL_FILE)
  1338.            any request from an OWNERS.
  1339.        HIT_OWNER_SUPPRESS='NO'
  1340.             Requests from OWNERS are recorded.
  1341.  
  1342. This is provided to limit the number of false hits attributable to
  1343. site-maintenance operations (say, from the Webmaster monitoring
  1344. her own site).
  1345.  
  1346. Example:
  1347.         HIT_OWNER_SUPPRESS='YES'
  1348.  
  1349. Note: the HIT_SUPERUSER_SUPPRESS variable (set in INIT_STA.80)
  1350.       can be used to extend the "range" of HIT_OWNER_SUPPRESS to
  1351.       include SUPERUSERS.
  1352.  
  1353. ***************
  1354. HOME_NAME  : The name of your organization
  1355.   The colloquial (not necessarily IP name) of your organization.
  1356.   This can be included in a document by using the REPLACE HOME_NAME
  1357.   keyphrase.  Note its use in NOT_FOUND_URL.
  1358.  
  1359.     home_name="DIVISION/AGENCY/DEPARTMENT/GOV"
  1360.  
  1361. (HOME_NAME can be host specific)
  1362.  
  1363. *******
  1364. HTACCESS_FILE : The name of the HTACCESS file.
  1365.  
  1366. When DO_HTACCESS='YES', SRE-http will look in the "requested file's"
  1367. directory (and its parent's directory) for file(s) with the name
  1368. given by HTACCESS_FILE.  Typically, this is HTACCESS. or .HTACCESS,
  1369. but you can use any name you want (but do NOT include path information).
  1370.  
  1371.  
  1372.   Example:  HTACCESS_FILE='HTACCESS.'
  1373.  
  1374.  
  1375. (HTACCESS_FILE can be host specific)
  1376.  
  1377.  
  1378. Hint: The HTACCESS_FILE contains access control information, as well as
  1379. URL redirection and "default index" information.  To use the URL
  1380. redirection, you should set up a file containing entries of the form:
  1381.     old_url  :  new_url
  1382. i.e.
  1383.     PLANET/JUPITER.HTM   :  http://www.starts.edu/ss/n5.htm
  1384. (note the old_url should not contain http://, and should not contain
  1385. the dot address)
  1386.  
  1387. (HTACCESS_FILE can be host specific)
  1388.  
  1389. *******
  1390. INHOUSEIPS. : Stem variable containing IP address of "in-house" clients.
  1391.   You can specify any number of "in-house IP domains".
  1392.   You can specify (several) * wildcards; for example: 111.222.33.*
  1393.  
  1394.     If Logon controls are desired, then clients with these
  1395.     IP addresses are automatically given access (they don't need to
  1396.     provide a username and password).
  1397.  
  1398.     In addition, you can specify extra privileges for each inhouseips. entry.
  1399.  
  1400.  
  1401. Examples:
  1402.        inhouseips.1="151.121.* VIEWMESS CONTROL "
  1403.        inhouseips.2="JOE.USDA.GOV   "
  1404.        inhouseips.3=0
  1405.        (All clients from 151.121.* are given VIEWMESS and CONTROL
  1406.         privileges, in addition to the privileges contained in the
  1407.         INHOUSE_PRIVS variable)
  1408.  
  1409. Notes:
  1410.  *  If you do NOT want to identify "in-house" clients, set inhouseips.1=0
  1411.  
  1412.  *  Note that we recommend that the last inhouseips. value = 0.
  1413.  
  1414.  *  INHOUSEIPS. can be host specific.
  1415.  
  1416.                       ************** CAUTION  **************
  1417.     In fact, non-host specific values of INHOUSEIPS will NOT be used
  1418.     as "default" values!
  1419.                       ************** CAUTION  **************
  1420.  
  1421.     For example:
  1422.         inhouseips.1='BUYER.STORE.COM'
  1423.         inhouseips.1.candy='MANAGER.STORE.COM  CONTROL '
  1424.     indicates that requests from MANAGER.STORE.COM to the "host"
  1425.     with a nickname of CANDY should be treated as an "in-House"
  1426.     request (note that if no HOSTS. are specified, this entry
  1427.     will never be used). However, requests from BUYER.STORE.COM to
  1428.     this CANDY host will NOT be treated as an INHOUSEIPS.
  1429.  
  1430.  
  1431.  
  1432. *******
  1433. INHOUSE. and SUPERUSERS.
  1434.      The following are special variables used with the INHOUSE.n
  1435.       and SUPERUSER.n replacement selector (see decripition of the REPLACE
  1436.       keyphrase).  They will be displayed only for  "inhouse" and "superusers", 
  1437.       respectively.
  1438.       Note that INHOUSE.n variables correspond to INHOUSE.n replacement
  1439.       strings, and SUPERUSER.n variables correspond to SUPERUSER.n
  1440.       replacement  strings.
  1441.  
  1442. Examples:
  1443.    inhouse.1=" (Staff Version) "
  1444.    inhouse.2=' .. more staff stuff '
  1445.    superuser.1="(Super User)"
  1446.    inhouse.3=0
  1447.    superuser.2=0
  1448.  
  1449. We recommend that the last inhouse. and superuser. should equal 0.
  1450.  
  1451. Inhouse. and superuser. can be host-specific; i.e.:
  1452. INHOUSE.1.CANDY='Special this week: Chocolate'
  1453.  
  1454.  
  1455. **************
  1456. INHOUSE_PRIVS: Privileges for IN-HOUSE clients.
  1457.  
  1458.   A space delimited list of  privileges to be granted to OWNERS and
  1459.   IN-HOUSE clients. It is HIGHLY recommended that INHOUSE_PRIVS always contain
  1460.   INHOUSE as one of the privileges!
  1461.  
  1462.   Example: inhouse_privs=" INHOUSE SECRET1 "
  1463.  
  1464.   Note that INHOUSE_PRIVS can be host specific.
  1465.     For example: INHOUSE_PRIVS.ZOO=' INHOUSE  SCHEDULES '
  1466.  
  1467.  
  1468. ********
  1469. INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor
  1470.  
  1471. SRE-http can use "non-REXX" processors to interpert CGI-BIN scripts.
  1472. To do this, you must tell SRE-http which processor to associate
  1473. with a file extension; where the file extension appears on the
  1474. "scriptname" (that follows the CGI-BIN/ portion of the request
  1475. selector).
  1476.  
  1477. This "association" is accomplished with the INTERPRET_TYPES parameter.
  1478. INTERPRET_TYPES should be a space delimited string of "type_options".
  1479. Each type_option should have the form:
  1480.     EXT=Interpreter_invocation
  1481. For example:
  1482.   interpret_types=' PL=PERL5 FOO=D:\FAKEIT\FOOEXEC '
  1483.  
  1484.    The first type_option (PL=PERL5) instructs SRE-http to use the PERL5
  1485.    program to interpret all CGI-BIN scripts with a .PL extension
  1486.    (this example assumes that PERL5 can be found in the OS/2 PATH).
  1487.  
  1488.    The second type_option (FOO=D:\FAKEIT\FOOEXEC) instructs SRE-http to use
  1489.    D:\FAKEIT\FOOEXEC to interpret CGI-BIN scripts with .FOO extensions.
  1490.    Note that a fully  qualified name is used for this "FOO interpreter".
  1491.  
  1492. Of particular interest is the use of one of the OS/2 PERL interpreters;
  1493. since there is a slew of PERL scripts out there.  It's not that
  1494. hard to obtain a PERL interpreter -- see PERL.DOC for details
  1495. on one we've had some success with.
  1496.  
  1497. Hint: you can include command line "switches"  when invoking a "non-REXX" 
  1498. processor. To do this, use %20 as a space.
  1499. For example:
  1500.  interpret_types='PL=PERL  NRX=netrexx%20-run '  
  1501. means "use PERL5 with .PL scripts, and use netrexx -run with .NRX scripts.
  1502. Thus, a selector of /CGI-BIN/foo.nrx would cause the following to be executed:
  1503.     netrexx -run  foo.nrx
  1504.  
  1505.  
  1506. REXX processor), use #20
  1507.  
  1508. Note: by default, INTERPRET_TYPES=' PL=PERL5 '
  1509.  
  1510.  
  1511. (INTERPRET_TYPES can NOT be host specific!)
  1512.  
  1513. ********
  1514. KEEP_ADDONS.n
  1515.  
  1516. To speed up processing of commonly used SRE-http addons (i.e.; STATUS.CMD),
  1517. you can tell SRE-http to "load an addon into macrospace" (procedures
  1518. load more quickly when they are placed into macrospace).  To do this,
  1519. you need to specify KEEP_ADDONS. entries.  
  1520.  
  1521. KEEP_ADDONS.0 should equal the number of entries, and KEEP_ADDONS.n
  1522. (n=1 .. KEEP_ADDONS.0) should contain the entries (note that this
  1523. is a different syntax from other SRE-http stem variables).
  1524.  
  1525. Each KEEP_ADDONS.n (n>0) entry should have the form:
  1526.    KEEP_ADDONS.n=' SEL  FULLY_QUALIFIED_FILE'
  1527.  
  1528. For example:
  1529.    keep_addons.0=2
  1530.    keep_addons.1='STATUS  G:\GOSERVE\ADDON\STATUS.CMD '
  1531.    keep_addons.2='NUSTATUS G:\GOSERVE\ADDON\NUSTATUS.CMD '
  1532.  
  1533. Notes:
  1534.    * the SEL is compared to the requested selector AFTER possible
  1535.      "alias" modifications. 
  1536.  
  1537.    * you don't need to include a leading /
  1538.  
  1539.    * keep_addons. entries are updated along with the SRE-http variables.
  1540.      Thus, if you change an internal parameter in an addon, it might
  1541.      take a while for the change to take effect (or, you can issue a
  1542.      !RESET requeset to your server to signal SRE-http to "update
  1543.      parameters immediately").
  1544.  
  1545.      IF YOU MUST HAVE AN ADDON BE QUICKLY RESPONSIVE TO CHANGES IN
  1546.      HARD-CODED PARAMETERS, DO NOT SPECIFY IT IN A KEEP_ADDONS. ENTRY!
  1547.  
  1548.    * Errors in KEEP_ADDONS. entries are not fatal -- bad entries are ignored.
  1549.  
  1550.    * If you do NOT specify a FULLY_QUALIFIED_FILE, then SRE-http will
  1551.      attempt to drop the macrospace procedure associated with the SEL (if no
  1552.      such procedure exists, it is ignored).  This allows you to selectively
  1553.      purge macrospace of "addon" procedures.  For example, inclusion of:
  1554.          Keep_addons.3='DO_ONCE   '
  1555.      tell SRE-http to "remove the DO_ONCE program from macrospace"
  1556.      (with no ill consequence if it's not there).
  1557.  
  1558.    * Addons that are referenced by a keep_addons. entry can be invoked using
  1559.      the !RUN special directive.  When  !RUN is used SRE-http will
  1560.      immediately call the macrospace version of the addon, and not bother
  1561.      with some unnecessary housekeeping.
  1562.          Example:  <a href="/!RUN/gif_text?font=hobo&mess="Hello">
  1563.      
  1564.  
  1565. ADVANCED USERS NOTE:
  1566.  
  1567.     There may be cases where you have a set of addons that you'ld like
  1568.     to distribute.  Rather then distributing the various .CMD files,
  1569.     you can (using REXXLIB) create & distribute a "macrospace library" 
  1570.     that contains these procedures.  That is, users of these procedures
  1571.     would NOT have the .CMD files, they'ld only have the image of the
  1572.     macrospace library (let's call it YOURPROCS.RXL).
  1573.  
  1574.     Since SRE-http always check macrospace for a procedure BEFORE
  1575.     looking on the disk, if you "preload" YOURPROCS.RXL into macrospace,
  1576.     SRE-http will find it and NOT look for a matching .CMD file (or .80
  1577.     file).  
  1578.  
  1579.     There is one requirement: the procedures must have a special name.
  1580.     To wit, if the procedure is to be requested with a selector of:
  1581.         /MYPROC1?xxxx
  1582.     then the macrospace procedure name should be
  1583.         SREF_nn_ADDON_MYPROC1
  1584.     where nn is the port you are running the http server on (typically,
  1585.     nn is equal to 80).
  1586.  
  1587.     If you want to use selectors of the form
  1588.         /SET1/MYPROC1?xxxx
  1589.     then the macrospace procedure should have a name of
  1590.         SREF_nn_ADDON_SET1_MYPROC1
  1591.     That is, all periods, / and \ should be converted to _ characters.
  1592.  
  1593.     HINT: to facilitate loading of YOURPROCS.RXL, you could distribute a
  1594.           loader.cmd (or some such name) that loads YOURPROCS.RXL,
  1595.           and is called as one of the CUSTOM_INITS.
  1596.           For example:
  1597.             /*load the YOURPROC.RXL "addon procedures into macrospace */
  1598.             foo=macroload('YOURPROC.RXL')
  1599.             if foo=0 then
  1600.                 call pmprintf(' Warning: problem loading YOURPROC.RXL')
  1601.             return 0
  1602.  
  1603.  
  1604. KEEP_ADDONS. is NOT Host specific.
  1605.  
  1606.  
  1607. ********
  1608. LOGON_FAIL_FILE
  1609.  
  1610. If a logon failure occurs (either due to an incorrect username/password,
  1611. or due to logon_limit being violated), SRE-http can
  1612. either send a "401 Unauthorized" response; or the contents of
  1613. the LOGON_FAIL_FILE.
  1614.  
  1615. If LOGON_FAIL_FILE=0, then a "401 Unauthorized" response is sent.
  1616.  
  1617. Otherwise, the LOGON_FAIL_FILE is sent as is; with a few substitutions:
  1618.     <!--#URL--> phrases are substituted with the request selector.
  1619.     <!--#SERVER--> phrases are substituted with the servername.
  1620.     <!-- #WEBMASTER --> phrases are substituted with the WEBMASTER variable.
  1621.     <!-- #MESSAGE --> phrases are substituted with a short description
  1622.                      of the reason for failure
  1623.     <!-- #LINK --> phrases are substituted with a link back to this URL.
  1624.  
  1625. Examples:
  1626.    LOGON_FAIL_FILE=0
  1627.    LOGON_FAIL_FILE='D:\GOSERVE\LOGFAIL.HTM'
  1628.  
  1629.  
  1630. Notes:
  1631.    *  LOGON_FAIL_FILE should be a fully qualified file name.
  1632.    *  If the LOGON_FAIL_FILE is unavailable, a "401 Unauthorized" response is
  1633.       sent.
  1634.    *  When using #LINK, you probably should advice the client to "wait a
  1635.       minute before trying again" (given that the problem might be
  1636.       due to logon_limit being exceeded).
  1637.  
  1638.    *  Reminder: the LOGON_FAIL_FILE is used when the client
  1639.       fails a "generic" logon (that is, she does not have a valid
  1640.       username and password).  In contrast, the ACCESS_FAIL_FILE
  1641.       is used when the client does not have sufficient "client privileges".
  1642.  
  1643. (LOGON_FAIL_FILE can be host specific)
  1644.  
  1645. *****************
  1646. MAX_POINTDIST : Used with the POINT type in mappable images.
  1647.  
  1648. Max_pointdist is used with server side image maps.
  1649.  
  1650.     The "point" area is one of the 4 types of areas (circle, rectangles,
  1651.     polygons, points) used in selecting a URL from a mappable image.
  1652.     If a selected pixel does not lie in one of the first 3, or does not
  1653.     lie directly on top of a point; SRE-http determines to which (of
  1654.     the many possible different points that may appear in the map file)
  1655.     the selected pixel is closest to.  However, if the distance to this
  1656.     closest point is greater then max_pointdist, then the Default URL is used.
  1657.  
  1658. Thus, this  limits the region of space "potentially assigned" to each point.
  1659.  
  1660.    Of course, setting max_pointdist to be very high (say, 100000),
  1661.    will effectively cancel this limit.
  1662.  
  1663.   Example: max_pointdist=50
  1664.  
  1665. (MAX_POINTDIST can be host specific)
  1666.  
  1667. *************
  1668. NO_PROCESSING:  Suppress server side processing
  1669.  
  1670. Switch to dictate whether or not to allow server side processing.
  1671.  
  1672.         YES - Do NOT do  allow server side processing
  1673.               If YES, then requests for server side processing will cause
  1674.               a 401 Unauthorized message to be returned to the client.
  1675.  
  1676.         NO -  Allow server side processing.
  1677.  
  1678. Note: A NO_SSP permission (in the access_file), overrides a NO_PROCESSING='NO'.
  1679.  
  1680.   Example: no_processing="NO"
  1681.  
  1682. (NO_PROCESSING   can be host specific)
  1683.  
  1684. ************
  1685. NO_INTERPRET_CODE:  Suppress execution of "in-document" executables.
  1686.  
  1687. This is similar to NO_PROCESSING, but not as stringent -- it only applies
  1688. to the SELECT and INTERPRET CODE "server side include" keyphrases.
  1689.        YES-  Ignore SELECT and INTERPRET CODE server side include keyphrases.
  1690.        NO -  Process SELECT and INTERPRET CODE server side include keyphrases.
  1691. Note that NO_PROCESSING (and NO_SSP) have precedence -- if NO_PROCESSING is
  1692. on, the value of NO_INTERPRET_CODE is irrelevant.
  1693.  
  1694. Notes:
  1695.    *  A NO_CODE permission (in the access_file) overrides a
  1696.       NO_INTERPRET_CODE='NO'
  1697.  
  1698.    *  CGI-BIN scripts, INTERPRET FILE, and other "executed files" WILL
  1699.       be processed if NO_INTERPRET_CODE='YES' (assuming NO_PROCESSING, etc.
  1700.       is not binding).
  1701.       Hence:If NO_INTERPRET_CODE='YES', you can still use an equivalent
  1702.             INTERPRET FILE keyphrase.
  1703.  
  1704.    *  The idea is that users of your site will not be able to cause trouble
  1705.       by including ill-mannered code into their HTML documents.
  1706.       In other words:
  1707.           i) If  site administrators will not review HTML documents
  1708.              posted on their site (say, by students)
  1709.          ii) Site adminstrators will review  CGI-BIN scripts, etc. that these
  1710.              "students" wish to place on the server.
  1711.         iii) Site administrators DO want to grant server side processing
  1712.              and server side include privileges to clients.
  1713.       Then, a reasonable level of security, without too harshly limiting
  1714.       flexibility,  can be achieved by setting NO_INTERPRET_CODE
  1715.       (or by judicious use of the NO_CODE permission).
  1716.  
  1717.  
  1718.    Example:  no_interpret_code='NO'
  1719.  
  1720. (NO_INTERPRET_CODE can be host specific)
  1721.  
  1722. ************
  1723. NO_INCLUDE:  Suppress server side includes.
  1724.  
  1725. Switch to dictate whether or not to process server side includes (SSIs).
  1726.     YES : Do NOT do dynamic page processing.
  1727.           Files sent as is (if SSI keyphrases occur, they will be sent "as is"
  1728.      NO :  Process server side includes.
  1729.  
  1730. If you  NEVER include SSI keyphrases, and you want to speed
  1731. up processing a bit, set NO_INCLUDE="YES"
  1732.  
  1733. Notes:
  1734.  * A NO_SSI permission (in the access_control_filefile), overrides 
  1735.    NO_INCLUDE=NO.
  1736.  * A YES_SSI permission (in the access_control_file) overrides
  1737.    NO_INCLUDE=YES
  1738.  
  1739.   Example: no_include="NO"
  1740.  
  1741. (NO_INCLUDE  can be host specific)
  1742.  
  1743. **********
  1744. NOEXT_TYPE: Determine how to handle "no extension" request selectors.
  1745.  
  1746. NOEXT_TYPE is used to instruct SRE-http what to do with requests that
  1747. have no extension, do not end in a /, and do not have ? in them.  There are
  1748. several allowed values of NOEXT_TYPE, any set of which may appear in a 
  1749. space delimited list:
  1750.  
  1751.   REDIR : A / is appended to the end, and then the client is 
  1752.    or     is "redirected" back to this new (/ appended) URL --
  1753.   DIR     at which time the AUTO_NAME feature kicks in.  This solves
  1754.           potential "resolution of local URL" problems, at the cost of slower
  1755.           overall response times. Note that REDIR is the default value.
  1756.   HTM or HTML : Interpret as an HTML file (a .HTM or .HTML is appended to
  1757.                 the end, respectively)
  1758.    NONE :  Use as is
  1759.   other_string: Append other_string.  For example, if NOEXT_TYPE='.GIF',
  1760.                 then .GIF will be appended to the end).
  1761.  
  1762.  Examples: NOEXT_TYPE="DIR"
  1763.            NOEXT_TYPE='HTM HTML .SHT .SHTML DIR'
  1764.               (try several extensions, and then redirect back to xx/)
  1765.  
  1766. (NOEXT_TYPE   can be host specific)
  1767.  
  1768.  
  1769. CAUTION: 
  1770.   When using NOEXT_TYPE (and other types of local redirection)
  1771.   URL resolution by the client's browser may have unexpected consequences.
  1772.   See the discussion of "local  vs remote redirection" at the bottom of
  1773.   this document for details!
  1774.  
  1775. ***************
  1776. NOT_FOUND_URL : A message, or response file, to use if the requested resource 
  1777.                 is not found.
  1778.  
  1779. There are basically three formats of the NOT_FOUND_URL:
  1780.  
  1781. 1) not_found_url='Message string'
  1782.   The 'message string' is sent along with a generic "not found url" response.
  1783.   Note that  this message string should be a valid HTML string.
  1784.   Set it to  " " if you want no such message sent.
  1785.  
  1786.       Example: not_found_url='<a href="/"> Visit the HOME_NAME page? </a> '
  1787.  
  1788.   Note that the HOME_NAME substring will be replaced with the current
  1789.   value of the HOME_NAME variable.
  1790.  
  1791. 2) not_found_url='file=fully_qualified_filename'
  1792.    If you want to return a "generic" custom document, perhaps one that lists
  1793.    several choices, you should use a special form of NOT_FOUND_URL.
  1794.    Specifically:
  1795.         NOT_FOUND_URL= 'FILE=fully_qualified_file_name'
  1796.    For example:
  1797.         NOT_FOUND_URL= 'FILE=d:\www\notfound.htm'
  1798.  
  1799.    If you are very ambitious, you can also append a custom "reponse code".
  1800.    For example:
  1801.         NOT_FOUND_URL= 'FILE=d:\www\notfound.htm, 200 Ok with error '
  1802.         (note the comma follwing the file name)
  1803.  
  1804.   The returned document will NOT have server side includes -- it is sent
  1805.   "as is".  There are a few special exception to this rule (for HTML
  1806.    documents):
  1807.        i) all occurences of <!-- #URL --> will be replaced with the
  1808.           request selector.
  1809.       ii) all occurences of <!-- #SERVER --> will be replaced with the
  1810.           server's IP address.
  1811.  
  1812.   Notes:
  1813.      * You can specify any type of document (i.e.; an HTML file, a GIF file,
  1814.        or a plain/text file).
  1815.      * A fully qualified file is expected: no attempt is made to map a
  1816.        relative file name to the data directory.
  1817.      * The file can be anywhere (it need not be in the data directory,
  1818.        or in virtual directories).
  1819.      * Historical note: this was the first type of "customized 404 response file"
  1820.        supported by SRE-http.  Although not deprecated, in general we recommend
  1821.        use of the "virtual" form described below. 
  1822.        That said, there is 1 advantage to this "fully qualified not_found_url" --
  1823.        you don't have to maintain seperate "path specific" not_found_url files.
  1824.         
  1825. 3) not_found_url='file=filename.ext'
  1826.         or
  1827.    not_found_url='virtual=filename.ext'
  1828.         
  1829.  
  1830.    When filename.ext contains no path information, SRE-http will look
  1831.    for a "directory specific" response file (with the name filename.ext).
  1832.    First, the directory of the request will be checked. If filename.ext
  1833.    does not exist in this "selector's own directory", SRE-http will
  1834.    check the next directory, continuing until a matching file is found, or
  1835.    until the root directory has been checked. 
  1836.  
  1837.    It may be more appropriate to refer to this as a "cascading, directory 
  1838.    (or directory-tree) specific response-file".
  1839.  
  1840.    Notes:
  1841.      * At each step, virtual directory matching will be attempted. Thus,
  1842.        depending on how complicated your virtual directories are, it
  1843.        is possible for "lower directories" to refer to completely seperate
  1844.        absolute directories.
  1845.      * Abstracting from virtual directories, the "directory tree" searched
  1846.        depends on the type of "not found URL":
  1847.           > Document (text file, graphics, etc.).  Look under the GoServe
  1848.             data directory (i.e.; D:\WWW).
  1849.           > CGI-BIN script. Look under the CGI-BIN directory 
  1850.            (i.e.; D:\GOSERVE\CGI-BIN)
  1851.           > SRE-http addon. Look under the ADDON_DIR directory
  1852.             (i.e.; D:\GOSERVE\ADDON).
  1853.        Therefore, is is wise to place copies of (possibly different)
  1854.        "filename.ext" files in all three "root" directories.
  1855.     *  If filename.ext points to a "server side includable" text/html file,
  1856.        tbe full gamut of SRE-http's server side includes will be available.
  1857.     *  Both forms are identical -- the "VIRTUAL=" was added (as of ver
  1858.        1.3B.1298e) as a pneumonic device (to remind you that this 
  1859.        "no path" form of NOT_FOUND_URL refers to a "virtual" filename).
  1860.     *  You can use the "find best match" addon (MTCHFILE.RXX, as illustrated 
  1861.        by MTCHFILE.SHT) to return a list of "candidate matches" (in
  1862.        the current directory).  See MTCHFILE.DOC for details.
  1863.  
  1864. NOT_FOUND_URL can be host specific (and HOME_NAME can also
  1865. be host specific).
  1866.  
  1867.  
  1868. *********
  1869. OPTION_HIT_LINE : Used to write OPTION  info instead of counts
  1870.  
  1871. OPTION_HIT_LINE is used  to write out "# hits drawn from an OPTION
  1872. passed to me" -- that is, it used with the REPLACE OPTION_HITS keyphrase
  1873.  
  1874.   Example: OPTION_Hit_line=":: still access # "
  1875.  
  1876. Note: OPTION_HIT_LINE is somewhat obsolete -- its major purpose is
  1877.       now better accomplished by using the HIT_CACHE_LEN parameter
  1878.  
  1879. (OPTION_HIT_LINE can be host specific)
  1880.  
  1881.  
  1882. *************************
  1883. OWNERS: Assigned SUPERUSER privileges
  1884.  
  1885. Owners are always given SUPERUSER privileges.
  1886. You can specify any number of owners, just seperate each of them
  1887. with a space. Note that wildcards are NOT allowed.  Furthermore,
  1888. you must specify a numeric IP address (not an IP name).
  1889.  
  1890.     If there are no owners, set owners=0.
  1891.  
  1892.  Example: owners   = " 151.121.65.163 "
  1893.  
  1894. (OWNERS  can be host specific).
  1895.  
  1896.  
  1897. ************
  1898. PRE_FILTER: Call  user written pre-filters.
  1899.  
  1900. PRE_FILTER is used to control whether a set of user written "pre-filters" 
  1901. are called before SREFILTR is given control.  It can take 3 values:
  1902.  NO:  Do not call a pre-filter.
  1903.  YES: Call a pre-filter after checking logon privileges (if the client
  1904.       does not have logon rights, the pre-filter will not be called)
  1905.  FIRST:  Call a pre-filter as the first action (before checking logon rights)
  1906.  
  1907. Note: if the selector matches a PUBLIC_URL, then:
  1908.         > If PRE_FILTER=FIRST, then the pre filter will be called
  1909.         > Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is
  1910.           treated as a NO.)
  1911.  
  1912.  
  1913. Example: PRE_FILTER="FIRST"
  1914.  
  1915. (PRE_FILTER  can be host specific)
  1916.  
  1917. ************
  1918. PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s).
  1919. This should point to a list of external procedures (or just to a
  1920. single external procedure).  Each of them will be called in turn
  1921. (or until one of them responds to the client).  Note that these
  1922. "PREFILTER" files should be in the GoServe working directory.
  1923.  
  1924.  Examples:  PREFILTER_NAME='PREFILTR'
  1925.             PREFILTER_NAME='PREFILT1.CMD  PREFILT9.CMD '
  1926.  
  1927.  
  1928. In the first example, note that a .80 (or .nnn if using port nnn) is added to
  1929. PREFILTR.
  1930.  
  1931. (PREFILTER_NAME  can be host specific)
  1932.  
  1933.  
  1934. ************
  1935. POST_FILTER: Call  user written post-filters.
  1936.  
  1937. POST_FILTER is used to control whether one or more  user written
  1938. "post-filters " are called before SRE-http is given control.
  1939. It can take 2 values:
  1940.  NO:  Do not call a post-filter.
  1941.  YES: Call a pre-filter after sending response to client.
  1942.  
  1943. (POST_FILTER  can be host specific)
  1944.  
  1945.  
  1946. ************
  1947. POSTFILTER_NAME: A series of procedures to call as  post filters.
  1948.  
  1949. POSTFILTER_NAME should contain a  list (or just one) procedures that
  1950. will be called as "post filters".
  1951. As with other external procedures, the procedures should correspond
  1952. to files with  names like POSTF1.80 (they should be in the GoServe
  1953. working directory).
  1954.  
  1955. If the  POSTFILTER_NAME variable is missing, a value of  POSTFILT will be used.
  1956.  
  1957.  Examples:  POSTFILTER_NAME='POSTRCRD.80'
  1958.             POSTFILTER_NAME='POST1.CMD POSTMAIL '
  1959.  
  1960. In the second example, first POST1.CMD will be called, and then POSTMAIL --
  1961. note that a .80 (or .nnn if using port nnn) is added to a name when there is
  1962. no extension (and no final period).
  1963.  
  1964. Notes:
  1965.  *  Post-filters are called AFTER the client has recieved a response.
  1966.     Therefore, post-filters can NOT be used to modify the response.
  1967.  
  1968.  *  Certain request-specific GoServe functions are NOT available to 
  1969.     post-filter procedures (i.e.; EXTRACT('CLIENTPORT') will not
  1970.     work).  
  1971.  
  1972.  *  POSTFILTER_NAME can be host specific
  1973.  
  1974.  
  1975. ****************
  1976. PUBLIC_URLS.  
  1977.  
  1978. As of version 1.3A, SRE-http no longer stores PUBLIC_URLS in the INITFILT.80
  1979. file. Instead, a seperate file (PUBURLS.IN, in the DATA directory) is used.
  1980. Please see PUBURLS.DOC for further details.
  1981.  
  1982.  
  1983. **************
  1984. PUBLIC_PRIVS.  Additional privileges for all clients.
  1985.  
  1986. A space delimited list of additional privileges to be granted to all
  1987. clients).
  1988. Set PUBLIC_PRIVS=" " if no additional privileges  are needed.
  1989.  
  1990.  Examples: public_privs=" PUBLIC  MESSBOX=*"
  1991.             public_privs=' PUBLIC  MESSBOX=FORUM1  MESSBOX=PUBGRP* '
  1992.  
  1993.   Notes:
  1994.  
  1995.      * PUBLIC_PRIVS are used with requests that match a PUBLIC_URL.
  1996.  
  1997.      * The MESSBOX=* privilege (the SRE-http default) grants read/write
  1998.       access to all "message boxes" (assuming Selector and FILE specific
  1999.       access controls are NOT in place).  In contrast,  MESSBOX=FORUM1
  2000.       permits access to the FORUM1 message box. and MESSBOX=PUBGRP*
  2001.       allows access to PUBGRP01, PUBGRP02, etc.
  2002.  
  2003.      * The CONTROL privilege allows some of the special (the !xxx) commands.
  2004.  
  2005.      * The BROADCAST privilege allows the user to "broadcast" e-mail messages
  2006.        using the SRE-http message facility.
  2007.  
  2008.      * The VIEWMESS privilege allows a client to download a
  2009.        SRE-http message box file.
  2010.  
  2011. (PUBLIC_PRIVS  can be host specific)
  2012.  
  2013. ******
  2014. RANGE_AT_END
  2015.  
  2016.  
  2017. Enable checking for range information at the end of a request
  2018. string (after a ;). This is an alternative to the 
  2019. !RANGE special directive.
  2020.  
  2021.       0 = Do NOT look for this info
  2022.       1 = Do look
  2023.  
  2024. Example:
  2025.    RANGE_AT_END=0
  2026.  
  2027.  
  2028. In general, it's safer to NOT use ;range_info -- use the
  2029. !RANGE special directive instead.
  2030.  
  2031.  
  2032. *******
  2033. RECORD_OPTION : Select whether to record all allowed requests.
  2034.  
  2035.  Used if you want to keep a running total of requests.
  2036.  
  2037.   RECORD_OPTION can take several values
  2038.         NO = Do NOT Keep track of requests
  2039.         YES = Remove argument list, and keep track of all requests.
  2040.         YES_ALL = Do not remove argument list, and keep track of all requests.
  2041.         FILE = Record using the name of the requested file (or script)
  2042.  
  2043.     If RECORD_OPTION is <> NO, results will be written to the RECORD_ALL_FILE.
  2044.  
  2045.   Example:  record_option="YES"
  2046.  
  2047.  Notes:
  2048.     * The "argument list" is the ? (and anything that follows it) in a
  2049.       request selector.
  2050.     * If you use YES_ALL or FILE, be prepared for your RECORD_ALL_FILE to
  2051.       grow quite large.
  2052.     * Note that RECORD_ALL_FILE can be hand-edited.  You may want to add
  2053.       appropriate "wildcarded" entries (such as /TEMP/*) to keep track of
  2054.       all temporary files, thereby avoiding the creation of
  2055.       lots of useless entries.
  2056.     * The RECORD_CACHE_FILE (see section 2a) is used to control caching
  2057.       of the RECORD_ALL_FILE.
  2058.     * See the WRITE_LOGS parameters for an alternative auditing mechanism
  2059.       (the common-log file).
  2060.  
  2061. (RECORD_OPTION   can be host specific)
  2062.  
  2063.  
  2064. ************
  2065. REPLACE_RULES.n
  2066.  
  2067. The REPLACE_RULES. are used to perform textual substituion on HTML
  2068. documents subject to server side includes.  Although only attempted
  2069. on "SSI" documents, the REPLACE_RULES. are not "server side
  2070. includes". Rather, they are textual replacements that occur
  2071. throughout the document, regardless of the placement of
  2072. HTML elements.
  2073.  
  2074. REPLACE_RULES. can be useful as a way of changing values across
  2075. a wide range of documents (they emulate style sheets), or 
  2076. as a shorthand for longer actions.
  2077.  
  2078. When specifying REPLACE_RULES.; you must specify REPLACE_RULES.0
  2079. to be the number of rules you'll specify.  Each REPLACE_RULES.n
  2080. should have the form:
  2081.   REPLACE_RULES.n='old_string==newstring'
  2082. All occurences of old_string will be replace by newstring.
  2083.  
  2084. Notes:
  2085.    * == is used to divide the old and new strings. 
  2086.    * spaces are NOT stripped. Thus:
  2087.         replace_rules.1=$x==THIS is X
  2088.      will have different effects then:
  2089.         replace_rules.1= $x== THIS is X
  2090.      (the latter requires a space before the x, and will add a space
  2091.        before the THIS)
  2092.    * the match of old_string is case insensitive; but the newstring
  2093.      case will be maintained.
  2094.    * Not only will the original document be subject to REPLACE_RULES, so
  2095.      will all subsequent server side includes.
  2096.    * To specify an == in a new or old string, use URL-encoding
  2097.      (== is %2b%2b).  
  2098.            Note that you can specify = by using a single = sign.
  2099.    * To not use any REPLACE_RULES; set REPLACE_RULES.0=0
  2100.    * If any REPLACE_RULES are specified in a selector-specific advanced
  2101.      options file, they will be used INSTEAD of these "generic" REPLACE_RULES. 
  2102.         That is, these generic REPLACE_RULES will be dropped whenever
  2103.         SEL-specific REPLACE_RULES are specified).  
  2104.         Please see ADV_OPTS.DOC for more information on selector-specific
  2105.         REPLACE_RULES.
  2106.  
  2107. Example:
  2108.    REPLACE_RULES.0=2
  2109.    REPLACE_RULES.1='${==<!-- $ customiz '
  2110.    REPLACE_RULES.2='}==  -->'
  2111.  
  2112. This will transform
  2113.    Customization is ${set1.var1}
  2114. into
  2115.    Customization is <!-- $ customiz set1.var1 -->
  2116.         
  2117.  
  2118. REPLACE_RULES. can be host specific. For example:
  2119.    REPLACE_RULES.0.HOST2='1'
  2120.    REPLACE_RULES.1.HOST2=' C.== $ Customiz 
  2121. where HOST2 is the host-nickname of one of your hosts.
  2122.  
  2123.  
  2124. ************
  2125. SMTP_GATEWAY: Domain name of an SMTP server
  2126.  
  2127. The SMTP_GATEWAY is used when e-mail messages are to be sent; as may
  2128. be attempted by MESSAGE, FORUM, and several other SRE-http facilties.
  2129. This should be the domain name of a SMTP mail server.
  2130.  
  2131.  
  2132. Example:  SMTP_GATEWAY=MAILBOX.BIG.EDU
  2133.  
  2134. Note: You can use your own server as the SMTP gateway by running SENDMAIL.
  2135.  
  2136.  
  2137. (SMTP_GATEWAY  can be host specific)
  2138.  
  2139. ***********
  2140. SSI_CACHE_ON
  2141.  
  2142. SSI_CACHE_ON is used to enable the server side include cache (SSI-cache).
  2143.  
  2144.     NO : Turn the SSI-Cache off -- HTML documents will not be cached.
  2145.    YES : Turn the SSI-Cache on.
  2146.  
  2147. The SSI-cache is used to store "compiled" versions of HTML documents that
  2148. contain server side includes.  When a request for such document arrives,
  2149. SRE-http will return it (perhaps with further modifications).
  2150.  
  2151.    Turning off caching is sometimes useful in highly dynamic
  2152.    environments; say, where INCLUDE files are constantly changing.
  2153.  
  2154. Example: SSI_CACHE_ON = 'YES'
  2155.  
  2156.  
  2157. Notes:
  2158.  * For further discussion of SSI-caching, please see the SSICACHE.HTM
  2159.    file.
  2160.  
  2161.  * The SSI_CACHE_SIZE variable (set in INIT_STA.80) can also be used
  2162.    to disable the SSI-Cache.
  2163.  
  2164.  
  2165. (SSI_CACHE_ON can be host specific)
  2166.  
  2167. *******
  2168. SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only
  2169.  
  2170. SRE-http can be instructed to attempt server side includes (SSIs) only on
  2171. files with a .SHT or .SHTML extension -- files with .HTM (or .HTML)
  2172. extension will NOT be checked for server side includes.  This can speed
  2173. up file transfer, but does require more care when naming html files.
  2174.  
  2175.  SSI_SHTML_ONLY : NO.  All HTML documents will be checked for SSIs.
  2176.                        Note that files with .HTM .SHT .HTML and .SHTML are
  2177.                        assumed to be html documents (more specifically,
  2178.                        mime type text/html documents).
  2179.  
  2180.  SSI_SHTML_ONLY : YES  Only .SHTM and .SHTML files are checked for SSIs.
  2181.  
  2182. Notes:
  2183.   * SSIs are NOT processed when NO_INCLUDE='NO' (or if there is no
  2184.     NO_SSI permission).
  2185.  
  2186.   * The list of "SSI capable" files can be modified to include files with
  2187.     extensions other then .SHT and .SHTML.  See the description of the
  2188.     SSI_EXTENSIONS variable (in the next section of this document) for details.
  2189.  
  2190.   * A YES_SSI "SEL-specific" permission overrides 
  2191.     SSI_SHTML_ONLY='YES'.
  2192.  
  2193. (SSI_SHTML_ONLY  can be host specific)
  2194.  
  2195. ****************
  2196. SUPPRESS_GZIP_TE: Suppress on-the-fly gzip encoding
  2197.  
  2198. By default, when a client asks for it, SRE-http will GZIP encode a response
  2199. "on the fly".  While this can save bandwidth, it does add extra processing
  2200. burden.  
  2201.  
  2202. You can suppress this "on the fly" compression by setting
  2203.    SUPPRESS_GZIP_TE=1
  2204. To permit this compression, you should set
  2205.    SUPPRESS_GZIP_TE=0
  2206.  
  2207. Technical Notes:
  2208.  
  2209. *   Assuming SUPPRESS_GZIP_TE=0, then SRE-http uses the following algorithim:
  2210.       a) The SREF_GOS procedure (which handles almost all of SRE-http's 
  2211.          transfers) checks for TE: request header. If not found, exit
  2212.       b) If the resource has  GZIP "content-encoding", exit
  2213.       c) If a TE: request header is found, a GZIP argument is looked for.
  2214.          If not found, exit.
  2215.       d) If a GZIP argument is found, and its "quality" parameter is
  2216.          compared to the IDENTITY quality parameter (where, by default,
  2217.          IDENTITY has a quality parameter of 0.001). If not greater, then exit.
  2218.       e) rxGZlib.dll is used to compress the response. Note that the response 
  2219.          may be a file, or a string (as produced by an sre-http addon).
  2220.       f) If the client is http/1.1, then the response is also "chunked"
  2221.       g) A Transfer-encoding: Gzip (or Transfer-encoding: gzip,chunked)
  2222.          response header is added
  2223.       h) The GZIPped (and possibly chunked) response is sent to the client
  2224.  
  2225. *    An alternative means of transferring GZIPped (or otherwise compressed)
  2226.      files is to use content negotiation to return a GZIPped "variant" 
  2227.      (as described in NEGOTIAT.DOC).  This requires that you create GZIPped 
  2228.      file(s) and store them in the same directory as the original file --
  2229.      they will not be GZIPped on the fly.
  2230.  
  2231. *   As of 1.3h.0010 -- if content-negotiation, or CE_GZIP (as
  2232.     set in INIT_STA.80 or as an advanced option) is enabled,
  2233.     then on-the-fly GZIP content encoding is attempted. 
  2234.     Furthremore, on-the-fly GZIP transfer-encoding is NOT attempted.
  2235.  
  2236.   
  2237.  
  2238. ****************
  2239. THE_REALM: "Realm" name to use in requests for username/password.
  2240.  
  2241. This is the "realm" which client are "challenged" by --
  2242. most browsers will display this "realm" information when asking for
  2243. username/password (as when CHECKLOG='ALWAYS' and a non-inhouse
  2244. client comes a calling)
  2245.  
  2246.   Example:  the_realm="OUR WEB SITE"
  2247.  
  2248. Notes:
  2249.  * The "SEL-specific realm"  (specified in the access file) is used
  2250.    if it is available.
  2251.    If no "SEL-specific realm" is available, the value of THE_REALM is used.
  2252.  
  2253.  * If you set REALM_1ST_PRIV=1  (in INIT_STA.80), then the "first
  2254.    resource privilege" will be used as the realm name (if no "sel specific"
  2255.    realm is explicitly specified)
  2256.  
  2257.  * THE_REALM can be host specific.
  2258.    For example: THE_REALM.ZOO='ZOO_SITE'
  2259.  
  2260.  
  2261. *******
  2262. UNALLOWEDIPS : Stem variable of "disallowed" IP addresses.
  2263.  
  2264. You can specify a set of ips that are NOT allowed in (a keep out pests
  2265. option). The syntax is the same (* allowed, consecutive numbering), as
  2266. the INHOUSEIPS. variables.
  2267.  
  2268.      Note: UNALLOWEDIPS. is ALWAYS checked (even if checklog=NO) -- and if a
  2269.            match is found, no logon is requested (they can't get in)
  2270.  
  2271.      Example:   unallowedips.1 = "149.126.12.*"
  2272.                 unallowedips.2="136.12.5.212"
  2273.                 unallowedips.3=0
  2274.      Example2: unallowedips.1="*"
  2275.                unallowedips.2=0
  2276.                 Only OWNERS and INHOUSEIPS.n clients can get in !
  2277.      Example3 : unallowedips.1 = 0
  2278.                  means that no one is automatically excluded.
  2279.  
  2280. Notes:
  2281.     * If any UNALLOWEDIPS. are specified, then caching is suppressed.
  2282.       Thus, in general, we do NOT recommend use of UNALLOWEDIPS.
  2283.     * UNALLOWEDIPS. is checked after INHOUSEIPS. and OWNERS
  2284.     * We recommend that the last unallowedips. value = 0.
  2285.  
  2286.  
  2287. HINT: In some cases (such as when you want an accurate count of the
  2288.       number of requests for all your documents), you may wish to
  2289.       "cache bust". That is, you may wish to prevent proxy servers
  2290.       from resolving a request to your server. You can do this by
  2291.       specifying a nonsense unallowedips. For example, set
  2292.         unallowedips.1='0.0.0.0'
  2293.         unallowedips.2=0
  2294.  
  2295.       WE DO NOT RECOMMEND THIS TRICK -- HTTP/1.1'S EFFORTS TO MAKE THE WEB
  2296.       PROXY SERVER FRIENDLY WILL BENEFIT EVERYONE!
  2297.  
  2298. UNALLOWEDIPS. may be specified on a host-specific basis.
  2299.  
  2300.                      ************** CAUTION  **************
  2301.     Non-host specific values of UNALLOWEDIPS will NOT be used
  2302.     as "default" values (see INHOUSEIPS. for details)!
  2303.                      ************** CAUTION  **************
  2304.  
  2305.  
  2306. ********
  2307. UPLOAD_MAXSIZE:  The maximum size (in Kbytes) allowed in a uploaded file.
  2308.  
  2309. Uploaded files are placed on the server when a GET_URL or a PUT_FILE
  2310. request selector is recieved.
  2311.  
  2312. Set this small (say, 20) if you don't want large files dumped onto
  2313. your machine.  Set it to 0 to disable all file uploads!
  2314.  
  2315.   Example: upload_MAXSIZE=50
  2316.  
  2317. Note:
  2318.    Uploads using the PUT http method are not limited by the UPLOAD_MAXSIZE
  2319.    variable.
  2320.  
  2321. (UPLOAD_MAXSIZE can be host specific)
  2322.  
  2323.  
  2324. ********
  2325. UPLOAD_MINFREE: Space that must remain after an upload.
  2326.  
  2327. The minimum amount of free space (in Kbytes) that must exist in the
  2328. upload_DIRECTORY's hard drive after uploading a file with GET_URL or PUT_FILE.
  2329.  
  2330. Set this large (say 100000) if you want to be certain that your
  2331. hard drive doesn't get filled up).
  2332.  
  2333.  
  2334.    Example: upload_MINFREE=25000
  2335.  
  2336. Note: if either upload_MINFREE or upload_MAXSIZE are violated, file
  2337. upload will not occur.
  2338.  
  2339. (UPLOAD_MINFREE can be host specific)
  2340.  
  2341. *******
  2342. USE_STDOUT: In "INTERPRET" keyphrases, use standard output as a means
  2343.             of writing results to a document.
  2344.  
  2345. If USE_STDOUT='YES', then INTERPRET keyphrases will have three
  2346. means of inserting data into your document:
  2347.   1) A string RETURNed (by a RETURN statement in the code block)
  2348.         or
  2349.   2a) interpret.results='some string'
  2350.   2b) All QUEUE (and PUSH) statements will be inserted (after the string stored
  2351.       in interpret.results
  2352.  
  2353. If USE_STDOUT='NO', then ONLY methods 1 or 2a are used (2b, output from
  2354. QUEUE and PUSH statements, will be ignored).
  2355.  
  2356. With USE_STDOUT='YES', INTERPRET will work similarly to the #EXEC
  2357. server side include -- except SAY generated output is NOT retained
  2358. (GoServe traps SAY statements, and sends their output to the 
  2359. PMPRINTF window).
  2360.  
  2361. Hence the need to use QUEUE (or PUSH) ...
  2362.  
  2363.     Example:  USE_STDOUT='YES'
  2364.  
  2365.  
  2366. Note: INTERPRET "interprets" REXX code blocks (rather then
  2367.        call them as external procedures).  Hence, you do NOT have to
  2368.        have a RETURN in the code block (if you do, SRE-http will
  2369.        trap it, and use the RETURNed results; viz method 1 above).
  2370.  
  2371.  
  2372. (USE_STDOUT can be host specific)
  2373.  
  2374.  
  2375. *******
  2376. USER_LOGON_ENABLE: Enable the use of a custom "user logon procedure"
  2377.  
  2378. You can instruct SRE-http to use a custom built "user logon procedure"
  2379. instead of the built in logon procedure. 
  2380.  
  2381. To do this, you must set the USER_LOGON_PROC parameter in INIT_STA.80, 
  2382. and you must set USER_LOGON_ENABLE. Note that if USER_LOGON_PROC
  2383. is not specified, then USER_LOGON_ENABLE is ignored.
  2384.  
  2385. USER_LOGON_ENABLE extends USER_LOGON_PROC in several ways:
  2386.     a) You can enable (or suppress) use of the default user_logon_proc 
  2387.        procedure on a host-specific basis
  2388.     b) You can specify a host specific "user logon" procedure
  2389.     
  2390. Permissible values of USER_LOGON_ENABLE are:
  2391.  
  2392.    NO or 0 = do NOT use a custom user logon procedure
  2393.   YES or 1 = use the USER_LOGON_PROC procedure
  2394.   procname =  use "procname" as the user logon procedure. That is, override
  2395.              the value specified in  USER_LOGON_PROC.
  2396.  
  2397. Advanced users note:
  2398.   SRE-http uses the REXX "INTERPRET" facility to support user logon procedures.
  2399.   Since INTERPRET is somewhat slow, you can speed things up by specifying
  2400.   a special name of a procedure that you've loaded into macrospace.
  2401.   To do this:
  2402.      a) set USER_LOGON_ENABLE='SREF_USER_LOGON'. 
  2403.         Or, set USER_LOGON_PROC='SREF_USER_LOGON'
  2404.      b) Before (or soon after) starting GoServe, load your user logon procedure 
  2405.         into macrospace, using the name "SREF_USER_LOGON".
  2406.   Note that you can only do this once -- you can not have host-specific 
  2407.   "user logon procedures in macrospace".
  2408.   
  2409.  
  2410. Examples:
  2411.    USER_LOGON_ENABLE='YES'
  2412.    USER_LOGON_ENABLE.HOST1='NO'
  2413.    USER_LOGON_ENABLE.HOST2='HOST2LOG.CMD'
  2414.  
  2415.    USER_LOGON_ENABLE='NO'
  2416.    USER_LOGON_ENABLE.HERSITE='YES'
  2417.    USER_LOGON_ENABLE.FLIMFLAM='SREF_USER_LOGON'
  2418.  
  2419. Notes:
  2420.  
  2421.     *  see the discussion of USER_LOGON_PROC for details on how SRE-http works
  2422.        with user logon procedures. 
  2423.  
  2424.     *  to reiterate: If USER_LOGON_PROC is not specified (or equals 0), then
  2425.        USER_LOGON_ENABLE is ignored.
  2426.    
  2427.     *  the default value of USER_LOGON_ENABLE is used when a host-specific
  2428.        value is not specified.
  2429.  
  2430.  
  2431. (USER_LOGON_ENABLE can be host specific)
  2432.  
  2433. *******
  2434. USER_PRIVS: Additional privileges assigned to registered users.
  2435.  
  2436. USER_PRIVS should be a space delimited list of "privileges" 
  2437. that will be granted to "registered users" -- to clients
  2438. who have a username and password for your server (i.e.; for
  2439. whom an entry exists in the USERS.IN file).
  2440.  
  2441. By default, USER_PRIVS='USER'
  2442.  
  2443. Example:
  2444.     USER_PRIVS='USER  REG_1999 '
  2445.  
  2446. (USER_PRIVS  can be host specific)
  2447.  
  2448.  
  2449. *******
  2450. VERBOSE: Controls the extent of comments written to the Pmprintf window/
  2451.          SREHTTP.LOG file..
  2452.  
  2453. Set verbose=1  if you want a fair number of status messages written to
  2454. the pmprintf window and/or the SREHTTP.LOG file
  2455.  
  2456. Set to verbose= 0, and  only error messages and certain initialization 
  2457. messages will be displayed.
  2458.  
  2459.     Example:   verbose=0
  2460.  
  2461. (VERBOSE  can be host specific)
  2462.  
  2463. Notes: 
  2464.   *  for even more comments, set VERBOSE=2, 3 or 4.
  2465.   *  see the description of PMPRINTF_OPT for more details on how SRE-http
  2466.      "audits" transient messages
  2467.  
  2468.  
  2469. *********
  2470. WEBMASTER: A static variable.
  2471.  
  2472. The WEBMASTER variable is used in certain error and status messages.
  2473.  
  2474. Note: you might also want to put specify a CONTACT "REPLACEment variable"
  2475.       in the repstrgs_file file.
  2476.  
  2477.   Example: webmaster='<a href="mailto:bb1@farm.ag.gov"> Webmaster </a> '
  2478.  
  2479.  
  2480. WEBMASTER may be host specific
  2481.    (i.e.; WEBMASTER.SWEETSHOP='CANDY@SWEET.ISP.COM')
  2482.  
  2483. ********
  2484. WRITE_LOGS: Enable the common-log, browser, and referer logs.
  2485.  
  2486. The WRITE_LOGS variable is used to enable recording of all requests
  2487. toe the common-log audit file.  In addition, browser and referer information
  2488. will be written to seperate log files.
  2489.  
  2490.    YES = Enable these log files
  2491.    NO  = Do NOT record requestsion in these log files.
  2492.  
  2493.  Example: WRITE_LOGS='YES'
  2494.  
  2495. Note: For further details on the common-log, etc. log files, see
  2496.       SREFLOGS.DOC.
  2497.  
  2498. WRITE_LOGS may be host specific.
  2499.  
  2500.  
  2501. ********
  2502. List of files and directory identifier variables.
  2503.  
  2504.    With one exception, these directories are NOT host specific.
  2505.    The exception is the ADDON_DIR directory, which can be host specific.
  2506.  
  2507. NOTE: If you change these, you MUST re-start GOSERVE!
  2508.  
  2509.    ADDON_DIR) Directory for SRE-http addons (and INTERPRETable files).
  2510.               Notes: ADDON_DIR can be host specific.
  2511.                      Alternatively, you can use virtual directories when
  2512.                      invoking an SRE-http addon.
  2513.    MESSBOX_DIR) Directory containing message boxes,
  2514.    MAILBOX_DIR) The in-box directory of an SMTP server.
  2515.    CGI_BIN_DIR) Location of CGI-BIN programs.
  2516.    TEMPFILE_DIR) Web accessible directory to use for creation of 
  2517.         "temporary" files   (by external procedures).  
  2518.        In comparison to the TEMPDATA_DIR, TEMPFILE_DIR
  2519.        s meant for short-life files (typically created by
  2520.        a server side program) that are meant to be downloaded
  2521.        in response to a subsequent request.
  2522.        Note: The !DELSEND "special action" looks for files in
  2523.              TEMPFILE_DIR.
  2524.    UPLOAD_DIR) Default location for uploaded files.
  2525.    TEMPDATA_DIR) Used for various SRE-http temporary files, such as
  2526.         _HITCACH.80, _ADDPRIV.80, and the $xxx.80 temporary
  2527.         "response" files.  In comparison to the TEMPFILE_DIR, these
  2528.         are files that are used by SRE-http, and should NOT be
  2529.         to be directly accessible to WWW clients.
  2530.    USERINFO_DIR) Directory used to store client-specific information
  2531.                  (i.e.; client customization data files).
  2532.    WORKDATA_DIR) Directory containing various SRE-http parameter files.
  2533.  
  2534.    COUNTER_FILE) "REPLACE HITS" counter file
  2535.    ERROR_LOG) The error log file (written to by the SREF_ERROR procedure)
  2536.    RECORD_ALL_FILE) "Record all requests" counter file
  2537.    SENDFILE_FILE) File used by SENDFILE procedure to keep track of requests.
  2538.    ACCESS_FILE) File used to control access when ALLOW_ACCESS is binding
  2539.    UPLOAD_LOG) Record of "uploaded files"
  2540.    ALIAS_FILE)  File containing the aliases.
  2541.    PUBURL_FILE) Contains public urls.
  2542.    VIRTUAL_FILE) File containing "virtual directory" selector aliases.
  2543.    REPSTGS_FILE)  REPLACEment string file
  2544.    USERS_FILE) Username/password file
  2545.    INTERPRET_FILE) File containing blocks of REXX code for use by the
  2546.         INTERPRET keyphrase (obsolete, retained for backwards compatability).
  2547.  
  2548. Examples:
  2549.    messbox_dir='e:\goserve\MESSAGE'
  2550.    mailbox_dir='c:\mptn\etc\mail'
  2551.  
  2552.    tempfile_dir='e:\WWW\temp'
  2553.  
  2554.    upload_dir='E:\goserve\upload'
  2555.    cgi_bin_dir='E:\goserve\CGI_BIN'
  2556.  
  2557.    counter_file='e:\goserve\DATA\COUNTER.CNT'
  2558.    record_all_file='e:\goserve\data\recrdall.cnt'
  2559.    sendfile_file='e:\goserve\DATA\SENDFILE.CNT'
  2560.    error_log='e:\goserve\data\error.log'
  2561.    access_file='e:\goserve\cfgs\ACCESS.IN'
  2562.  
  2563.    tempdata_dir='e:\goserve\temp'
  2564.    userinfo_dir='e:\goserve\userinfo'
  2565.  
  2566.    virtual_file='E:\goserve\cfgs\VIRTUAL.IN'
  2567.    alias_file='e:\goserve\cfgs\ALIASES.IN'
  2568.    repstrgs_file='e:\goserve\cfgs\REPSTRGS.IN'
  2569.    user_file='e:\goserve\cfgs\USERS.IN'
  2570.    interpret_file='e:\goserve\INTERPET.IN'
  2571.  
  2572.  
  2573. Note: The various .CNT and .IN files that are shipped with
  2574.       SRE-http (such as ACCESS.IN) contain additional documentation.
  2575.  
  2576.       Note that these various filenames are NOT host specific, but
  2577.       they MAY contain host specific entries!
  2578.  
  2579.  
  2580.                        =============================
  2581.  
  2582. 2h.                  Parameters in INIT_STA.80
  2583.  
  2584.  
  2585. In addition to the dynamic-parameters contained in INITFILT.80, there are a 
  2586. number of static-parameters in INIT_STA.80 which the ambitious user may wish 
  2587. to change. Note that:
  2588.   * None of these static-parameters are host-specfic.
  2589.   * In order for changes to these static parameters to take effect, you MUST
  2590.     restart GoServe
  2591.  
  2592. Very ambitious webmasters may wish to tinker with a few parameters
  2593. in SREFMON.CMD. Descriptions of these more obscure parameters follows
  2594. the descriptions of the parameters in INIT_STA.80.
  2595.  
  2596.  
  2597. NOTE: As of ver 1.3d, parameters are no longer set in the SREFILTR.80 file--
  2598.       all the parameters that were in SREFILTR.80 are now in INIT_STA.80.
  2599.  
  2600.                         ---- PARAMETERS in INIT_STA.80 ---
  2601.  
  2602. ********
  2603. ALWAYS_CHECK_PRIVS
  2604.  
  2605.    When a request selector matches a PUBLIC_URL, SRE-http does not
  2606.    require the client to have "access privileges".  However, the
  2607.    request may be for a SRE-http addon which may require specific
  2608.    privileges.
  2609.  
  2610.    Setting ALWAYS_CHECK_PRIVS=1 tells SRE-http to "get the client
  2611.    privileges, even if she asked for a PUBLIC_URL.  A value of 0
  2612.    tells SRE-http to NOT lookup client privileges when PUBLIC_URLs
  2613.    are requested.
  2614.  
  2615.    Basically, If you know that PUBLIC_URLs NEVER require privilege
  2616.    information, setting ALWAYS_CHECK_PRIVS=0 will improve performance.
  2617.    If you aren't sure, the safe choice is to set ALWAYS_CHECK_PRIVS=1.
  2618.  
  2619.    Example:  always_check_privs=1
  2620.  
  2621.  
  2622.  
  2623. ********
  2624. BACKUPSERVERLIST and LOADTHRESHOLD
  2625.  
  2626.    These variables are used to control "load balancing".  SRE-http comes
  2627.    with a simple load-balancer, but you can easily specify far more
  2628.    complicated load balancing schemes (i.e.; the BALANCER SRE-http addon).
  2629.  
  2630.    LOADTHRESHOLD:
  2631.        If LOADTHRESHOLD=0, then this "load balancing" is not attempted.
  2632.        Otherwise, load balancing will occur if the number of active clients
  2633.        is greater then the value given.
  2634.  
  2635.    BACKUPSERVERLIST:
  2636.       If BACKUPSERVERLIST=' ', then load balancing is not attempted.
  2637.       Otherwise, it should contain a list of IP addresses of  alternate
  2638.       (backup) servers (that presumably mirror the main site).
  2639.       If  BACKUPSERVERLIST contains more then one entry (entries should be
  2640.       seperated by spaces), then a partially random method is used to select
  2641.       which server to redirect the client to.  For example:
  2642.                2 entries =  2/3 of the redirections go to the first entry.
  2643.                3 entries =  1/2 go to the first entry (1/4 to 2nd and 3rd)
  2644.  
  2645.      Examples:
  2646.                 loadthreshold=0
  2647.                 backupserverlist=' '
  2648.  
  2649.                 loadthreshold=6
  2650.                 backupserverlist='www2.oursite.net'
  2651.  
  2652.                 loadthreshold=3
  2653.                 backupserverlist='www2.oursite.net  overflow.hersite.net '
  2654.     
  2655.                 backupserverproc='d:\goserve\addon\backsrv2.80'                
  2656.  
  2657. Citation: The basic idea for the generic balancer is borrowed from 
  2658.           Don Meyer's GoHTTP filter.
  2659.  
  2660.  
  2661. **********
  2662. CERN_ISMAP
  2663.  
  2664. The value(s) in the spaced delimited CERN_ISMAP variable is used
  2665. to indicate that this "is an image-map request".  You can specify several
  2666. different values (though you should only use one of them in a given
  2667.  "image map" URL).
  2668.  
  2669. When one of these identifier-strings appear in a request selector,
  2670. SRE-http assumes that the request "is a response from a mappable image"
  2671.  
  2672. For example, if CERN_ISMAP='/MAPCERN', then selectors (that are generated
  2673. by clicking on a mappable image) of the form:
  2674.      /MAPCERN/GIFSDIR/USMAP.MAP?123,312
  2675. will be interpreted as ...
  2676.      pixel 123,312, in combination with the instructions contained
  2677.      in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
  2678.      the client to (where USMAP.MAP is a CERN style MAP file)
  2679.  
  2680. IMPORTANT NOTE:  the MAPCERN/ is NOT considered to be part of the directory
  2681.                  name -- it is treated as a flag!
  2682.  
  2683. Example:
  2684.      CERN_ISMAP="MAPCERN/ HTIMAGE/"
  2685.  
  2686. Notes
  2687.   *  The trailing /  in the above example(s) is optional.
  2688.   *  The "map file location" is interpreted using the regular SRE-http rules
  2689.      (relative to the GoServe data directory, or to a virtual directory)
  2690.   *  For NCSA style image maps, see the  NCSA_ISMAP variable.
  2691.  
  2692. *******
  2693. CGI_BIN_PIECES
  2694.  
  2695. CGI_BIN_PIECES enables the CGI-BIN  "send pieces as they become available" 
  2696. mode.
  2697.  
  2698. One problem with cgi-bin scripts is that if you have lengthy output, or a 
  2699. compute intensive script that  writes stuff in spurts, the client has 
  2700. to wait for everything to be done before recieving any output.
  2701. If this takes more then several seconds, the client may get discouraged,
  2702. and disconnect. Even worse, if one has the "end client after inactive"
  2703. set low (say, 15 seconds), there may be times when the server kills the
  2704. request even though a lengthy script has yet to finish.
  2705.  
  2706. To deal with these situations, SRE-http can send CGI-BIN output
  2707. to the client "as it becomes available". To enable this mode, just set
  2708. the CGI_BIN_PIECES parameter:
  2709.  
  2710.    0  : Do NOT send output in pieces; wait until the script is done,
  2711.         and then send the whole thing
  2712.    1  : Send output in pieces, using FILEREXX procedures
  2713.  
  2714.    Example: CGI_BIN_PIECES=1
  2715.  
  2716. Caution:
  2717.     For reasons we can't figure out, sometimes partial loads of
  2718.     FILEREXX functions don't seem to "stick" when done from within
  2719.     a GoServe thread.  However, the same calls when done from a
  2720.     different session (that is, from some program running under
  2721.     a different invocation of CMD.EXE) work.
  2722.     Therefore, if you are getting "can't find procedure" errors
  2723.     (RC=43); you can try running the following program before starting
  2724.     GoServe:
  2725.  
  2726.     /* Program to preload filerexx procedures */
  2727.       say " This will preload several  FILEREXX procedures"
  2728.       if rxfuncquery('fileread_rxf')=1 then do
  2729.         goti1=RxFuncAdd('Fileread_rxf', 'FILEREXX', 'FILEREAD')
  2730.         if goti1=1 then 
  2731.             say " Error: unable to load FILEREAD FILEREXX functions "
  2732.       end
  2733.       if rxfuncquery('fileopen_rxf')=1 then do
  2734.          goti2=RxFuncAdd('Fileopen_rxf', 'FILEREXX', 'FILEOPEN')
  2735.       end
  2736.       if rxfuncquery('fileclose_rxf')=1 then do
  2737.         goti3=RxFuncAdd('Fileclose_rxf', 'FILEREXX', 'FILECLOSE')
  2738.       end
  2739.       if rxfuncquery('fileclose_rxf')=1 then do
  2740.          goti3=RxFuncAdd('Fileclose_rxf', 'FILEREXX', 'FILECLOSE')
  2741.       end
  2742.       if rxfuncquery('fileseek_rxf')=1 then do
  2743.         goti3=RxFuncAdd('FileSeek_rxf', 'FILEREXX', 'fileseek')
  2744.       end
  2745.       if rxfuncquery('filegetinfo_rxf')=1 then do
  2746.         goti3=RxFuncAdd('Filegetinfo_rxf', 'FILEREXX', 'filegetinfo')
  2747.       end
  2748.       exit
  2749.  
  2750.   
  2751. Notes
  2752.   * on the !CGI-BIN_n server directives:
  2753.     If you need to use the "send pieces" mode occasionally, and the
  2754.     "standard" mode on other occasions, you can use the !CGI-BIN_n
  2755.     (where n=2,3) "server directives" (see SREHTTP.HTM for further
  2756.     discussion of the !CGI-BIN_n "server directives").
  2757.  
  2758.  
  2759. *******
  2760. CGI_POST_LONG_GET
  2761.  
  2762. Due to limitations on the number of characters that can be included on an OS/2
  2763. command line, GET method CGI-BIN requests can not have argument lists 
  2764. (information after the ?) longer then 245 characters.  Furthermore, environment
  2765. strings should not be greater then about 1000 characters.
  2766.  
  2767.  
  2768. To  work around these limits, SRE-http can convert long GET requests into POST
  2769. requests.  
  2770.  
  2771. To do this, set CGI_POST_LONG_GET=nnnn, where nnnn is the size at which
  2772. this conversion takes place.
  2773.  
  2774.     Example:  cgi_post_long_get=1000
  2775.  
  2776.  
  2777. For this to be useful, your CGI-BIN scripts will need to understand how to 
  2778. detect and read POSTed information.
  2779.  
  2780. Notes:
  2781.   For backwards compatability:
  2782.         0 = infinity
  2783.         1 = 245 
  2784.   Note that if nnnn>245, the "command line argument" will be truncated to
  2785.   245 characters. Thus, as a general principle you should use QUERY_STRING
  2786.   to obtain the request line options.
  2787.  
  2788.  
  2789. ********
  2790. CUSTOM_INITS
  2791.  
  2792. CUSTOM_INITS can contain a list of REXX procedures to run when first starting
  2793. GoServe/SRE-http.  Typically, these will be custom-written procedures
  2794. that will perform special, one-time actions; such as starting up a database
  2795. server, or "preloading" URL's into the GoServe cache.
  2796.  
  2797. CUSTOM_INITS should be a comma delimited list, with each entry containing
  2798. the name of an external procedure, followed by an optional argument.
  2799.  
  2800. If you do NOT want to run any initialization procedures, set CUSTOM_INITS=0.
  2801.  
  2802.  
  2803. Examples:
  2804.    custom_inits=0
  2805.    custom_inits='preload '
  2806.    custom_inits='preload , userproc Web Server 1 '
  2807.  
  2808.   where the "Web Server 1" is an argument that will be sent to the userproc
  2809.   external procedure.
  2810.  
  2811.  
  2812. Notes:
  2813.  *  These procedures are executed very early in the 
  2814.     SRE-http initialization processs (i.e.; before reading INITFILT.80).  
  2815.  *  SRE-http waits until these procedures finish.  Thus, if these 
  2816.     procedures stay resident, or otherwise take a long time to complete,
  2817.     YOU SHOULD INVOKE A NEW PROCESS (OR THREAD). That is, the external
  2818.     procedure should immediately invoke a new process (or thread), and
  2819.     then exit.
  2820.  *  An (optional) argument list should NOT contain commas!       
  2821.  *  External procedures should be stored in files in the GoServe directory.
  2822.     These files should have the same name  as the procedure, and 
  2823.     should have a .CMD (or .80) extension.   
  2824.        For example, if Custom_inits='preload', 
  2825.        then a PRELOAD.CMD file should be in the GoServe directory.
  2826.  
  2827. Suggestion:
  2828.  
  2829.    The PRELOAD addon to SRE-http is a useful example: the PRELOAD.CMD
  2830.    file (invoked by setting custom_inits='PRELOAD') will call a "preload
  2831.    URL's" daemon (PRELOAD.RXX).   
  2832.  
  2833.  
  2834. ***********
  2835. DEFAULT_ENCRYPTION
  2836.  
  2837. The default encryption algorithim.  This default is used when an
  2838. !ENCRYPT/selector is requested, or when an advanced-options file
  2839. contains SET ENCRYPT.
  2840.  
  2841. Currently, two algorithims are supported: SRE_A and SRE_B.
  2842.  
  2843.   Example:  DEFAULT_ENCRYPTION='SRE_A'
  2844.  
  2845.  
  2846. ********
  2847. DELAY_SECONDS
  2848.  
  2849. Delay_seconds controls how frequently SRE-http
  2850. checks input files for updates.  Larger values mean more time between
  2851. checks.  If you never change initialization parameters, etc. you can
  2852. set this to a high value (say, 1000) to reduce the load on the server.
  2853.  
  2854. Example:
  2855.    delay_seconds=9
  2856.  
  2857. Note: you can always force SRE-http to re-read files by issuing a
  2858.       !RESET request to your server.
  2859.  
  2860.  
  2861. *********
  2862. DELTA_ENCODING_ENABLE
  2863.  
  2864. Enable support for delta-encoding 
  2865.     0 = disable
  2866.     1 = allow sel-specific support for delta encoding
  2867.     2 = allow delta encoding for all requests 
  2868.  
  2869. Example:
  2870.     delta_encoding_enable=0 
  2871.  
  2872. See DELTA.DOC for the details.
  2873.  
  2874.  
  2875. *********
  2876. DELTA_ENCODING_MAXSIZE
  2877.  
  2878. Size of the delta_encoding_cache, in kbytes.
  2879.  
  2880. Example:
  2881.    delta_encoding_maxsize=5000
  2882.  
  2883. See DELTA.DOC for the details.
  2884.  
  2885. *********
  2886. DIGEST_AUTH
  2887.  
  2888. Enable the use of "digest" authentication. If you never talk to http/1.1 clients,
  2889. you can save some time by suppressing this.
  2890.  
  2891.    DIGEST_AUTH=1     ; try to use digest authentication
  2892.    DIGEST_AUTH=0     ; do not use digest authenticaion
  2893.  
  2894. Technically speakin, when DIGEST_AUTH=1, then a WWW-Authorize: Digest xxxx
  2895. response header is added to the response before a WWW-Authorize: Basic xxx
  2896. response header.
  2897.  
  2898.  
  2899. **********
  2900. DIR_CACHE_DURATION
  2901.  
  2902. DIR_CACHE_DURATION is used by SRE-http's !DIR facility. It is the lifespan
  2903. (in days, or fractional days) of entries in the "directory listing cache".
  2904.  
  2905. Example: DIR_CACHE_DURATION=3
  2906.  
  2907. **********
  2908. DIR_CACHE_SIZE
  2909.  
  2910. DIR_CACHE_DURATION is used by SRE-http's !DIR facility. It is the
  2911. maximum size (in Kbytes), of the "directory listing cache".
  2912.  
  2913. Example: DIR_CACHE_SIZE=1000
  2914.  
  2915. Notes:
  2916.   * setting DIR_CACHE_SIZE=0 will suppress use of the directory listing
  2917.     cache.
  2918.   * directory listing "cache files" are stored in the TEMPDATA_DIR, with
  2919.     names of _nnnnn.DSH (i.e.; _0000012.DSH).  There is also a
  2920.     _DIRLIST.IDX file used as an index to these listings).
  2921.  
  2922.  
  2923.  
  2924. ***********
  2925. DYNSSI_MAXAGE
  2926.  
  2927. The number of seconds a cache can maintain a document that has
  2928. "dynamic" SSIs.  To force all caches to always revalidate
  2929. any document that has a dynamic SSI in it,  set
  2930.    DYNSSI_MAXAGE=0
  2931.  
  2932. To allow caches to use a response, that contains "dynamic SSIs"
  2933. for two minutes (after which it must revalidate), set
  2934.    DYNSSI_MAXAGE=120
  2935.  
  2936. Notes:
  2937.   * an s-maxage limit (as specified in PROXY_CACHE) can not exceed this 
  2938.     value (if it does, it will be adjusted down).
  2939.  
  2940.   * the <!-- CACHE DURATION=nnn --> SSI-phrase is used for resources
  2941.     that have static SSIs.
  2942.  
  2943.  
  2944.  
  2945. ***********
  2946. EMPTY_PATH_OK
  2947.  
  2948. Empty_path_ok is a CGI-BIN option: it controls the  value of 
  2949. the PATH_INFO and PATH_TRANSLATED "environment variables". 
  2950. In particular, when there is no PATH_INFO sent (i.e.; a 
  2951. request of /CGI-BIN/TEST-CGI?ARG1 has no PATH_INFO specified),
  2952. there are two possibilties:
  2953.  
  2954.   EMPTY_PATH_OK=1. PATH_INFO (and PATH_TRANSLATED) are set to
  2955.                    an empty string (no spaces).  In addition,
  2956.                    the SCRIPTNAME is preceded by /CGI-BIN/.
  2957.                    This seems to be more of a  standard (ICS and
  2958.                    the NCSA.1.5.2 servers  use it).
  2959.   EMPTY_PATH_OK=0  PATH_INFO='/' and PATH_TRANSLATE='the GoServe
  2960.                    data directory'.
  2961.                    This is what Don Meyer's GOHTTP uses.
  2962.  
  2963. Notes:
  2964.   * we know of several scripts that expect an empty PATH_INFO environment
  2965.     variable when none is specified, and will fail if EMPTY_PATH_OK=0.
  2966.   * to control which is used on a "selector specific basis", you can use
  2967.     the !CGI-BIN_1 and !CGI-BIN_0 (or !CGI_BIN_2 and !CGI-BIN_3) 
  2968.     "special directives".
  2969.  
  2970.  
  2971. ***********
  2972. ENABLE_ENCRYPTION
  2973.  
  2974. Enable SRE-http's encryption. Allowed values include:
  2975.   0 : disable
  2976.   1 : enable for  non-addon responses
  2977.   2 : enable for all responses
  2978.   3 : force encryption of ALL response
  2979.  
  2980. 1 and 2 are quite similar, but 1 may fail to encrypt responses that are 
  2981. generated by some older SRE-http addons. However, it's a bit quicker.
  2982.  
  2983. See ENCRYPT.DOC for more details.
  2984.  
  2985. *********
  2986. EVENT_CHECK
  2987.  
  2988.    Check for events.
  2989.    SRE-http's monitor daemon can check a set of administrator specified
  2990.    events.  These events, which are specified in EVENTS.CFG, 
  2991.    will be checked every EVENT_CHECK minutes.
  2992.    To never check events, set EVENT_CHECK=0
  2993.  
  2994.    Examples:
  2995.        EVENT_CHECK=0
  2996.        EVENT_CHECK=15
  2997.  
  2998.    For details on event checking, see EVENTS.DOC.
  2999.  
  3000. **********
  3001. GET_DECODE_OPTIONS
  3002.  
  3003. By default, when SRE-http sends "GET request options" (the stuff
  3004. after a ?) to an addon, it will first "URL decode" them. That is, SRE-http
  3005. will convert %2b to +, etc.  
  3006. While this can save you a step, it can cause trouble when the request may
  3007. contain these special characters (i.e.; +, &, and =).  Although you
  3008. can use the URI argument, you may find it convenient to suppress this
  3009. decoding instead.
  3010.  
  3011.   GET_DECODE_OPTIONS=1  : URL decode 
  3012.   GET_DECODE_OPTIONS=0  : do NOT URL decode.
  3013.  
  3014. Example:
  3015.   GET_DECODE_OPTIONS=1
  3016.  
  3017.  
  3018. **********
  3019. HEAD_TO_GET
  3020.  
  3021. Tell addons that HEAD methods are GET methods -- this is done by
  3022. sending GET as the "VERB" argument (see MK_ADDON.HTM for details on
  3023. how addons are called).  In this case, addons can get the true
  3024. verb by using EXTRACT('CLIENTMETHOD')
  3025.  
  3026. Enabling this can be help some older addons, that don't recognize
  3027. HEAD requests. (note that on HEAD requests goserve never sends 
  3028. the body of a response, even if one is produced).
  3029.  
  3030. To enable this, set head_to_get=1
  3031.  
  3032. Example: head_to_Get=0
  3033.  
  3034.  
  3035. **********
  3036. HIT_SUPERUSER_SUPPRESS
  3037.  
  3038. If HIT_OWNER_SUPPRESS is enabled (see description above), then
  3039. "OWNERS" will not have their hits recorded (in the RECORD_ALL_FILE
  3040. and in the hit counter file).
  3041. You can extend the "range" of HIT_SUPERUSER_SUPPRESS to include SUPERUSERs by
  3042. setting HIT_SUPERUSER_SUPPRESS=1. That is, if HIT_OWNER_SUPPRESS=1 and
  3043. HIT_SUPERUSER_SUPPRESS=1, then requests from OWNERS and from SUPERUSERs
  3044. will NOT be recorded.
  3045.  
  3046. Otherwise (if HIT_SUPERUSER_SUPPRESS=0), SUPERUSER requests will
  3047. be recorded.
  3048.  
  3049.   Example:
  3050.         HIT_SUPERUSER_SUPPRESS=1                (the default is 0)
  3051.  
  3052. Note:  if HIT_OWNER_SUPPRESS=0, then HIT_SUPERUSER_SUPPRESS is ignored
  3053.        (that is, SUPERUSER requests will be recorded).
  3054.  
  3055. **********
  3056. NCSA_ISMAP
  3057.  
  3058. The value(s) in the spaced delimited NCSA_ISMAP variables are used 
  3059. to indicate that this "is an image-map request".  You can specify several
  3060. different values (though you should only use one of them in your "image map"
  3061. URL).
  3062.  
  3063. When one of these identifier-strings appear in a request selector,
  3064. SRE-http assumes that the request "is a response from a mappable image"
  3065.  
  3066. For example, if NCSA_ISMAP='/MAPIMAGE', then selectors (that are generated 
  3067. by clicking on a mappable image) of the form:
  3068.      /MAPIMAGE/GIFSDIR/USMAP.MAP?123,312
  3069. will be interpreted as ...
  3070.      pixel 123,312, in combination with the instructions contained
  3071.      in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
  3072.      the client to (where USMAP.MAP is an NCSA style MAP file)
  3073.  
  3074. IMPORTANT NOTE:  the MAPIMAGE/ is NOT considered to be part of the directory name --
  3075.                        it is treated as a flag!
  3076.  
  3077. Example:
  3078.      NCSA_ISMAP="MAPIMAGE/ NCSAIMG/"   
  3079.  
  3080. Notes
  3081.   *  The trailing /  in the above example(s) is optional.
  3082.   *  The "map file location" is interpreted using the regular SRE-http rules
  3083.      (relative to the GoServe data directory, or to a virtual directory)
  3084.   *  For CERN style image maps, see the  CERN_ISMAP variable.
  3085.  
  3086.  
  3087. *********
  3088. KEY_PREFACE
  3089.  
  3090. If the REPLACE, INCLUDE, OPTIONS, INTERPRET and SELECT "keywords"
  3091. appear at the beginning of real comments (and you are using the
  3092. default "server side keyphrase" delimiters of <!-- and -->), you
  3093. might want to add a "preface" to these keywords.  For example,
  3094. you can add the ! character, so that SRE-http will look for
  3095. !REPLACE, !INCLUDE, etc.
  3096.  
  3097. Note that KEY_PREFACE=0 or KEY_PREFACE='' means "do not add a preface".
  3098. Also note that the # can not be used as a preface (since it is
  3099. used by the HTTPD-style #INCLUDE keyphrase).
  3100.  
  3101.   Examples:
  3102.         KEY_PREFACE='!'
  3103.         KEY_PREFACE=0
  3104.  
  3105.  
  3106. ********
  3107. LOGON_LIMIT
  3108.  
  3109. As a security measure, SRE-http's "authorization facility" can limit
  3110. the number of unsuccessful attempts, per IP address per minute.  When this
  3111. limit is exceeded, for the next minute further attempts (from this IP address
  3112. will be immediately denied.
  3113.  
  3114. To enable this, set LOGON_LIMIT to the number of logon attempts per minute.
  3115. A value of 0 means "no limits".
  3116.  
  3117.   Examples:
  3118.         LOGON_LIMIT=0
  3119.         LOGON_LIMIT=3
  3120.  
  3121. Warning: do NOT use LOGON_LIMIT=1 (it causes odd problems)
  3122.  
  3123. Note: the authorization facility handles all client answers to
  3124.      "401 Unauthorized" server responses. These include "logon" requests
  3125.       and "SEL-specific" access requests.
  3126.  
  3127.  
  3128. ********
  3129. MAIN_SERVER
  3130.  
  3131. The numeric IP address of a "main server".  The MAIN_SERVER variable
  3132. is used to expedite responses to certain requests -- in particular,
  3133. HEAD !PING requests from this "main server" are answered quickly, with
  3134. no recording (except in the GoServe audit file).  One use of this
  3135. is to help implement dynamic load balancing.
  3136.  
  3137.  Example:
  3138.    Main_server='151.125.21.61'
  3139.  
  3140. Special cases:
  3141.   main_server=0         --- suppress
  3142.   main_Server=''        --- use "own ip" address.
  3143.  
  3144.  
  3145. ********
  3146. MESSAGE_SCRAMBLE
  3147.  
  3148. MESSAGE_SCRAMBLE is used to "encrypt" message-box passwords.
  3149. You can change it for a wee bit extra security (though security is never going
  3150. to be great).
  3151.  
  3152. MESSAGE_SCRAMBLE is also used to create "nonces" (nonces are used by digest
  3153. authentication).
  3154.  
  3155.  
  3156. Example:
  3157.    message_scramble=12415
  3158.  
  3159.  
  3160. ( message_scramble should be an integer less than 1 million and greater
  3161.   then 0).
  3162.  
  3163.  WARNING: If you change this, existing "message" passwords will not be
  3164.           decodable!  That is, they won't work anymore.
  3165.           Similarly, outstanding nonces (from clients that retain such
  3166.           information) will not work.
  3167.  
  3168. Note: only the password, which is just used to control deletion rights,
  3169. is encrypted.
  3170.  
  3171. ***********
  3172. NO_NO_RECORD
  3173.  
  3174. The NO_NO_RECORD option can be used to suppress the !NORECORD directive.
  3175. One reason to suppress !NORECORD is to prevent tricky clients
  3176. from sneaking by your audit mechanisms.
  3177.  
  3178. To disable the !NORECORD directive, set NO_NO_RECORD=1
  3179. To enable it, set NO_NO_RECORD=0
  3180.  
  3181. ***********
  3182. PRE_REPLY_PROCEDURE
  3183.  
  3184. The PRE_REPLY_PROCEDURE is used to specify an external REXX procedure;
  3185. this procecure will be given a chance to modify a response just before 
  3186. sending it to the client -- it's a "last second" hook into SRE-http.  
  3187.  
  3188. To clarify:  PRE_REPLY_PROCEDURE specifies a  rexx procedure that will do
  3189.             "final" modifications to content that is to be sent to the client.
  3190.              For example, a PRE_REPLY_PROCEDURE could be used translate text 
  3191.              responses (such as file's determined using the usual SRE-http
  3192.              aliasing, etc. rules) into a different code-page.
  3193.  
  3194.  
  3195. PRE_REPLY_PROCEDURE should be equal to 0, or to a fully qualified filename.
  3196. *  A value of 0 means "do not call a pre-reply procedure.
  3197. *  A fully qualified filename should point to a file containing a REXX procedure.
  3198.    The input and output structure of this procedure are fully described in 
  3199.    PREREPLY.DOC
  3200. *  Special format: to only use a pre-reply procedure on a selector specific
  3201.    basis, pre-pend an exclamation point to the filename.
  3202.  
  3203. Examples:
  3204.    PRE_REPLY_PROCEDURE=0
  3205.    PRE_REPLY_PROCEDURE='E:\GOSERVE\PREREPLY.CMD'
  3206.    PRE_REPLY_PROCEDURE='!E:\GOSERVE\SRERsync.CMD'
  3207.  
  3208. Notes:
  3209.   * You can use the SET PRE_REPLY 0 "advanced option" to suppress the 
  3210.     use of a pre-reply procedure on a selector specfic basis.
  3211.  
  3212.     Conversely, you MUST use the  SET PRE_REPLY 1 "advanced option" to 
  3213.     enable the use of a "selector specific" pre-reply procedure.
  3214.     Note that by "selector specific" pre-reply procedure, we do NOT
  3215.     mean that different selectors can have different pre-reply
  3216.     procedures; we do mean that "the global pre-reply procedure will
  3217.     only be called when a selector specific flag allows it".
  3218.  
  3219.     See ADV_OPTS.DOC for details on the PRE_REPLY advanced option.
  3220.  
  3221.   * Since this entails an extra step, use of the PRE_REPLY_PROCEDURE will
  3222.     slow down throughput.
  3223.   * We recommend using PRE_REPLY_PROCEDURE only when there are no other
  3224.     alternatives.
  3225.   * SRE-http will load this procedure into macrospace, under the 
  3226.     name SREF_PREREPLY_PROC.
  3227.  
  3228. ***********
  3229. PROXY_CACHE
  3230.  
  3231. PROXY_CACHE is used to control the  extent to which GoServe, SRE-http,
  3232. and proxy caches will cache responses.
  3233.  
  3234. Set PROXY_CACHE=0 to disable, or limit, proxy caching --
  3235.  
  3236. PROXY_CACHE can take the following values:
  3237.  
  3238.    0= disallow all caching
  3239.       All caching is disallowed: including user-agent caches,
  3240.       caches on proxy servers, and the SREPROXY "proxy-like" front 
  3241.       end to SRE-http.
  3242.    1= allow caching
  3243.       Caching is allowed by user-agents, proxy servers, and SREPROXY.
  3244.    2= allow storage of response, but force all caches (proxy and user-agent)
  3245.       to revalidate (using an If-modified or If-no-match) before using.
  3246.    3= similar to 2, but applies only to shared (proxy) caches. User-agent
  3247.       caches do not need to re-validate.
  3248.  
  3249. Example:
  3250.         PROXY_CACHE=1     
  3251.  
  3252. In addition, you can specify a "max-age" -- which is how long
  3253. an item can be retained in a cache before it is validated.
  3254. By default;
  3255.   1: infinite max-age
  3256.   2 and 3: 0 seconds maxage (always re-authenticate)
  3257.  
  3258. To do this, simply use 
  3259.   PROXY_CACHE=n_maxage
  3260. where
  3261.   n=0,1,2, or 3
  3262.   maxage= maximum age of cache entries in seconds.  
  3263.  
  3264. For example:
  3265.   PROXY_CACHE=1_86400
  3266.   PROXY_CACHE=3_1800
  3267.  
  3268. In most cases PROXY_CACHE=1 is recommended. However, if you need to accurately
  3269. audit the use of all resources, the use of 2 or 3 is a reasonable compromise
  3270. (it allows caches to respond to a request, but your server is informed of 
  3271. each request). 
  3272.  
  3273. You might also wish to use 1_86400 if your "static" resources occassionally
  3274. change (this tells caches to re-validate their cache entry every day).
  3275.  
  3276. If you do use PROXY_CACHE=1, and wish to have improved (though 
  3277. not necessarily 100% accurate) counts, you can use the METER: selector-
  3278. specific advanced option (see ADV_OPTS.DOC and HITMETER.DOC for the details).
  3279.  
  3280. Note: for resources that contain "dynamic SSI's", the _nnn value 
  3281. may be reduced to the value of DYNSSI_MAXAGE.
  3282.  
  3283. ***********
  3284. NEVER_IMAGEMAPS
  3285.  
  3286. If you never use server side imagemaps, you can save a fraction of a second
  3287. (on some requests) by suppressing SRE-http's "check if this is an 
  3288. imagemap request".
  3289.  
  3290. NEVER_IMAGEMAPS=1       : Suppress imagemap checking
  3291. NEVER_IMAGEMAPS=0       : Check for imagemaps
  3292.  
  3293. Example:
  3294.    NEVER_IMAGEMAPS=0
  3295.  
  3296. ***********
  3297. NEVER_PUBLICURLS
  3298.  
  3299. If you never use PUBLIC_URLs, you can save a fraction of a second
  3300. (on some requests) by suppressing SRE-http's "check if this selector
  3301. matches a PUBLIC_URL"
  3302.  
  3303. NEVER_PUBLICURLS=1  : Do NOT check if this selector matches a public_url
  3304. NEVER_PUBLICURLS=0  : Do check.
  3305.  
  3306. Example:
  3307.   NEVER_PUBLICURLS=1
  3308.  
  3309. ***********
  3310. NO_REMOTE_CONFIG
  3311.  
  3312. SRE-http is designed to be remotely configurable; with most  of 
  3313. the SRE-http parameters, virtual directories, usernames, etc. settable
  3314. by a SUPERUSER running a web browser from anywhere in the world.  This is a 
  3315. great convenience, but can be somewhat of a security risk.
  3316.  
  3317. If you desire, you can use the NO_REMOTE_CONFIG parameter to
  3318. disable this "remote configuration" feature. 
  3319.  
  3320. NO_REMOTE_CONFIG can take values of:
  3321.    0 :  Allow remote configuration (by clients with a SUPERUSER privilege)
  3322.    1 :  Disallow remote configuration, but allow configuration (using
  3323.         the SRE-http configuration forms) from clients sitting at the
  3324.         server (this entails a check of the client's IP address against
  3325.         the server's IP address).
  3326.    2 :  Disable all remote configuration -- to modify any SRE-http parameter
  3327.         you will have to edit the various ascii parameter files.
  3328.  
  3329. Example:
  3330.   NO_REMOTE_CONFIG=0
  3331.  
  3332. Note: The CHECKIT parameter in SREFCONF.CMD, CONFIG2.CMD, and the 
  3333.       *CFG.CMD files can also be used to suppress remote configuration.
  3334.       
  3335. ***********
  3336. PMPRINTF_OPT:
  3337.  
  3338. To lend extra flexibility to SRE-http's run-time auditing, and to catch a few
  3339. bugs in the REXXLIB PMPRINTF; SRE-http now uses its own version
  3340. of PMPRINTF (PMPRINTF_SREF),  Furthermore, SRE-http uses a seperate
  3341. thread to do the actual screen & file output, this thread will
  3342. "lazy write" output, with consequent reduction in disk & screen overhead.
  3343.  
  3344. You can control the output of PMPRINTF_SREF by setting the PMPRINTF_OPT parameter.
  3345.  
  3346. PMPRINTF_OPT  can take values of:
  3347.        1 : Use PMPRINTF window
  3348.        2 : Use PMPRINTF window and SREHTTP.LOG file
  3349.        3 : Use SREHTTP.LOG only
  3350. SREHTTP.LOG will be written to the GoServe working directory.
  3351.  
  3352. Notes:
  3353.    * Ambitious webmasters can change the name of this log file,
  3354.      and the "maximum line length",  by adjusting a few parameters 
  3355.      in SREFMON.CMD.
  3356.    * Very ambitious webmasters can change the "lazy write" rate, and
  3357.      can add a special preface to PMPRINTF output, by adjusting a
  3358.      few parameters in PMPRINTF.RXX.
  3359.    * Common-log output that is sent to the PMPRINTF window (when VERBOSE>0)
  3360.      will NOT be written to the SREHTTP.LOG (that would be redundant, since
  3361.      it's already being written to the COMMON.LOG file)
  3362.  
  3363. ***********
  3364. PUT_NO_OVERWRITE
  3365.  
  3366. When accepting PUT method requests, SRE-http can either overwrite
  3367. a pre-existing file, or it can refuse to overwrite.  
  3368.  
  3369. PUT_NO_OVERWRITE = 1   : do NOT overwrite (send back an error response)
  3370. PUT_NO_OVERWRITE = 0   : overwrite
  3371.  
  3372. Note that the file is determined by the selector supplied by the
  3373. client; after adding the GoServe default data directory (or a virtual
  3374. directory).
  3375.  
  3376. Example:
  3377.   PUT_NO_OVERWRITE=1            (the default)
  3378.  
  3379.  
  3380. ***********
  3381. QUICK_INTERP
  3382.  
  3383. To facilitate the use of in-line REXX code for server side includes;
  3384. you can use a shorthand for the <!-- INTERPRET FILE filename.ext --> 
  3385. keyphrase. In particular, you can use a $ instead of INTERPRET FILE:
  3386. as in <!-- $ filename.ext -->
  3387.  
  3388. If you'ld rather use some character other then $, just change the
  3389. QUICK_INTERP parameter.
  3390.  
  3391. Example:
  3392.         QUICK_INTERP='$'
  3393.  
  3394. Note: Be sure that the values for QUICK_INTERP and QUICK_INTERP_CODE
  3395.       are different!
  3396.  
  3397. ***********
  3398. QUICK_REPLACE
  3399.  
  3400. You can use a shorthand for the <!-- INTERPRET REPLACE varname arg1 .. argn -->
  3401. keyphrase. In particular, you can use a % instead of REPLACE:
  3402. as in <!-- % TIME --> or <!-- % ODOM personal -->
  3403.  
  3404. If you'ld rather use some character other then %, just change the
  3405. QUICK_REPLACE parameter.
  3406.  
  3407. Example:
  3408.         QUICK_REPLACE='%'
  3409.  
  3410.  
  3411. ***********
  3412. QUICK_INTERP_CODE
  3413.  
  3414. To facilitate the use of in-line REXX code for server side includes;
  3415. you can use a shorthand for the <!-- INTERPRET CODE abc ; def -->
  3416. keyphrase. In particular, you can use a $ instead of INTERPRET CODE:
  3417. as in <!-- # abc ; def  -->
  3418.  
  3419. If you'ld rather use some character other then #, just change the
  3420. QUICK_INTERP_CODE parameter.
  3421.  
  3422. Example:
  3423.         QUICK_INTERP_CODE='#'
  3424.  
  3425. Note: Be sure that the values for QUICK_INTERP and QUICK_INTERP_CODE
  3426.       are different!
  3427.  
  3428. ***********
  3429. REALM_1ST_PRIV
  3430.  
  3431. If no "sel specific realm" is specified (in the access control file),
  3432. the value of the first resource privilege can be used as the realm name.
  3433. To enable this, set REALM_1ST_PRIV=1.  Otherwise, the DEFAULT_REALM
  3434. parameter will be used.
  3435.  
  3436. Example:
  3437.    REALM_1ST_PRIV=0
  3438.  
  3439. Note: If you:
  3440.          use just one resource privilege per selector,
  3441.          specify REALM_1ST_PRIV=1, and 
  3442.          never set an explicit "sel-specific realms"
  3443.       then
  3444.          the "realm" is equivalent to the "resource privilege list".
  3445.  
  3446.  
  3447. ***********
  3448. RECORD_CACHE_LINES:
  3449.  
  3450. This controls the size of the "request recorder" cache.
  3451. Shrinking the size of this cache (say, if you don't have
  3452. many documents) will free up memory.  Increasing it (say, you
  3453. have a large site, and a lot of RAM) will speed up request
  3454. recording.  In addition, since the RECORD_ALL_FILE is backed up and
  3455. then reset when the cache grows beyond RECORD_CACHE_LINES, a larger
  3456. cache may reduce fragmentation of these RECORD_ALL_FILE audit files.
  3457.  
  3458. To suppress caching, set RECORD_CACHE_LINES=0
  3459.  
  3460.  
  3461. Example:
  3462.   RECORD_CACHE_LINES=750
  3463.  
  3464.  
  3465. ************
  3466. SEM_MAXWAIT
  3467.  
  3468. The "independent threads" that help SRE-http work by waiting on
  3469. queues.  The waiting is partially contolled by a semaphores, which are
  3470. set whenever anything is written to a queue.  Since OS/2 can be a mite
  3471. slow about writing semaphores, it is sometimes convenient to check
  3472. the queue, and then go back to waiting if nothing is there.
  3473.  
  3474. To increase the frequency that this "check queue even though the semaphore
  3475. hasn't been set" occurs, select a low value of SEM_MAXWAIT.  Note that
  3476. SEM_MAXWAIT is in milliseconds, so values under 100 are considered low.
  3477.  
  3478. A possible drawback is that the smaller SEM_MAXWAIT is, the more
  3479. SRE-http will engage in useless queue examinations.  The best value to
  3480. use should be determined by experimentation.
  3481.  
  3482. Example: SEM_MAXWAIT=15000
  3483.  
  3484.  
  3485. *********
  3486. SSI_EXTENSIONS:  File extensions that are equivalent to SHTML.
  3487.  
  3488.  
  3489. The SSI_EXTENSIONS variable contains a space delimited list of file extensions
  3490. that will be treated as "SHTML" files.  That is, when SSI_SHTML_ONLY='YES',
  3491. only files with one of with these extensions will have server side
  3492. includes added.
  3493.  
  3494. If you add to this list, you may also need to specify that the file is a
  3495. text/html MIME type.  To do this, you should add entries to the MEDIATYP.RXX
  3496. file located in the GoServe directory.
  3497.  
  3498. Note: SRE-http's default value of ssi_extensions is:
  3499.     ssi_extensions=' SHT SHTML HTML-SSI HTM-SSI '
  3500.  
  3501. ****************
  3502. SSI_CACHE_SIZE
  3503.  
  3504. SSI_CACHE_SIZE is used to set the size of the "server side include cache".
  3505. You should enter the size in Kilobytes. For example:
  3506.  
  3507.    SSI_CACHE_SIZE=5000  (the default)
  3508.  
  3509. corresponds to a cache size of 5M.
  3510.  
  3511.  
  3512. Notes:
  3513.  
  3514.  * For further discussion of SSI-caching, please see the SSICACHE.HTM
  3515.    file.
  3516.  
  3517.  * Cached files are stored in your TEMPDATA_DIR directory (typically,
  3518.    GOSERVE\TEMP). They have names of _CS?????.80 (or .nnn, if you are
  3519.    using port .nnn).
  3520.  
  3521.  * Once the size of the cached files exceeds this amount, the oldest
  3522.    entries will be deleted (where oldest is measured in terms of
  3523.    "last requested").
  3524.  
  3525.  * Setting SSI_CACHE_SIZE=0 will turn the SSI-Cache off (regardless of
  3526.    the value of SSI_CACHE_ON).
  3527.  
  3528. ****************
  3529. SSI_CACHE_DURATION
  3530.  
  3531. SSI_CACHE_DURATION is used to set (in days) the "lifespan"
  3532. of entries in the server side include cache.
  3533.  
  3534. After this lifespan has been exceeded, the entry will die.
  3535. This helps ensure that documents do not get "too far" out of
  3536. date (thus, egregious out-of-sync errors won't last forever).
  3537.  
  3538. Examples:
  3539.    SSI_CACHE_DURATION=0.5  --  a 12 hr. lifespan.
  3540.    SSI_CACHE_DURATION=30   -- a 30 day lifespan
  3541.    SSI_CACHE_DURATION=0    -- infinite lifespan
  3542.  
  3543.  
  3544. Note:
  3545.     You can use the <!-- CACHE DURATION m.n --> SSI keyphrase
  3546.     to override this "default" value on a file-by-file basis.
  3547.  
  3548.  
  3549. ****************
  3550. SSI_CACHE_STAMP
  3551.  
  3552. The SSI_CACHE_STAMP dictates which fields to use when determining
  3553. whether a SSI-cache "trigger" file has changed.  SSI_CACHE_STAMP
  3554. can have one of the following values:
  3555.  
  3556. ALL -- Use time,date, and size (if any change, the trigger is considered
  3557.        to be out-of-sync)
  3558. DATE -- Just use the date
  3559. TIME -- Just use the time (hr/minute)
  3560. DATETIME -- Use the time and date
  3561. SIZE -- Just use the size
  3562.  
  3563.  
  3564. Note:
  3565.     You can use the <!-- CACHE TRIGGER_TYPE stamp --> SSI keyphrase,
  3566.     where stamp is one of the above values,  to override this "default"
  3567.     value on a file-by-file basis.
  3568.  
  3569. ****************
  3570. USER_LOGON_PROC
  3571.  
  3572. In some circumstances, you might want to use an external program to 
  3573. check & store usename/password/privilege information (and thereby
  3574. not use SRE-http's USER.IN and ATTRIBS.IN databases, and related procedures).
  3575.  
  3576. To do this, set USER_LOGON_PROC=procedure_name, where procedure_name 
  3577. is an external procedure (either on disk, or preloaded into macrospace).
  3578.  
  3579.   Examples:
  3580.         USER_LOGON_PROC=' '         (use SRE-http's procedure)
  3581.         USER_LOGON_PROC="MY_LOGON"  (use the MY_LOGON procedure)
  3582.         USER_LOGON_PROC="SREF_USER_LOGON"  (use the SREF_USER_LOGON 
  3583.                                             macrospace procedure)
  3584.  
  3585. SRE-http will pass 3 arguments to this USER_LOGON_PROC preocedure. 
  3586.  
  3587.   1) The 1st argument is a space delimited list consisting of:
  3588.          if BASIC authentication is used:   USER  PASSWORD CLIENT_IP_ADDRESS
  3589.         if DIGEST authentication is used:   USER CLIENT_IP_ADDRESS
  3590.      (where USER and PASSWORD are extracted from the AUTHENTICATION request header).
  3591.  
  3592.   2) The 2nd argument is the "servername"
  3593.   3) The 3rd argument is the host_nickname
  3594.  
  3595.  
  3596. This procedure MUST return the following
  3597.    STATUS PRIVILEGE_LIST
  3598. (The privilege list is optional)
  3599.  
  3600. The status must be an X, or an integer.  These values mean:
  3601.  
  3602. X  :  Excluded -- let the regular SRE-http logon procedures do the job instead.
  3603. 0  : Logon unsuccessful
  3604. >=1 : Logon successful (the value identifies which "record" matched, and is
  3605.                        not currently used -- a value of 1 for all success
  3606.                        will suffice)
  3607. <0 : Logon unsuccessful, this (absolute value) is the "nth" try. This 
  3608.                         "nth try" value is used by the 
  3609.                         LOGON_LIMIT facility of SRE-http. You can
  3610.                         always use 0 for "failure", in which case
  3611.                         the LOGON_LIMIT stuff will not work.
  3612.  
  3613. Notes:
  3614.  
  3615.    *  you can use the USER_LOGON_ENABLE procedure to enable or disable the
  3616.       use of the USER_LOGON_PROC on a host specific basis, or to specify
  3617.       host specific values of USER_LOGON_PROC.
  3618.  
  3619.    * see the discussion of USER_LOGON_ENABLE for details on using user logon
  3620.      procedures on a multi-host server.
  3621.  
  3622. ****************
  3623. WILD_SELS_OK
  3624.  
  3625. As a convenience, you can permit asterisk (*) containing selectors, where 
  3626. the * is treated as a wildcard character.
  3627.  
  3628. If such a selector is requested, then SRE will search the appropriate
  3629. directory for the a wildcard match, and use that file or display
  3630. a directory-style listing of all matches.
  3631.  
  3632. For example (assuming the GoServe data directory is D:\WWW):
  3633.    If the selector is /DINOS/BRON*.JPG (and WILD_SELS_OK=1), 
  3634.    then SRE will find all files that match  D:\WWW\DINOS\BRON*.JPG, 
  3635.    and use the shortest one (i.e.; the best match is D:\WWW\DINOS\BRON.JPG)
  3636.  
  3637. In fact, you can even instruct SRE to look at all "subdirectories" of
  3638. the selector. Thus, the above example one might yield
  3639. D:\WWW\DINOS\veggies\brontos.JPG.
  3640.  
  3641. WILD_SELS_OK can take the following values:
  3642.   0 :  Do NOT search
  3643.   1 :  Search the own directory
  3644.  11 :  Search the own directory. If multiple matches, display a directory
  3645.        style listing of the matches (with links to each match)
  3646.   2 :  Search own directory and subdirectories
  3647.  22 :  Search the own directory and subdirectories. If multiple matches, 
  3648.        display a directory style listing of the matches (with links to each 
  3649.        match). 
  3650.  
  3651. Example:  WILD_SELS_OK=1
  3652.  
  3653. Notes:
  3654.    * WILD_SELS_OK is ONLY used with GET requests for files; it is not used
  3655.      for imagemaps, cgi-bin scripts, POST requests, or "addon"
  3656.      requests.
  3657.  
  3658.    * If WILD_SELS_OK=0, then a *-containing selector  will always cause 
  3659.      a NOT_FOUND response.
  3660.  
  3661.    * CAUTION: Use of WILD_SELS_OK can subvert access controls (especially when
  3662.               you use WILD_SELS_OK=2). The problem is that SRE does NOT
  3663.               check a "wildcard matched" file (or directory) against the
  3664.               access control file. 
  3665.  
  3666.               SRE will check the original *-containing selector against the
  3667.               access control file. Please note that in both the
  3668.               access control and alias files, the * character has special
  3669.               meaning -- hence you can not explicitily match a *-containing
  3670.               selector (but you can "wildcard match" a *-containing selector).
  3671.  
  3672.     * SRE will use the wildcard derived filename when it checks the HTACCESS
  3673.       file.
  3674.  
  3675.     * *-containing selectors will NOT wildcard match directories. That is,
  3676.         you can only use * in the filename portion of a "directory/filename"
  3677.         (it's like using a DIR AB*C.DEF /S command)
  3678.  
  3679.     * You can include multiple *s in the selector. You can NOT include ?s    
  3680.               
  3681.  
  3682. 2i.                 ---- PARAMETERS in SREFMON.CMD ---
  3683.  
  3684. ****************
  3685. CLEAR_MACROSPACE
  3686.  
  3687. SRE-http uses the macrospace procedures it loads from SREFPRC.RXL. If 
  3688. ANY of the procedures stored in SREFPRC.RXL are already in macrospace,
  3689. it will NOT load SREFPRC.RXL.  If you frequently update SREFPRC.RXL
  3690. (or the .SRF files) this may be a problem -- since the updates will 
  3691. not get loaded.
  3692.  
  3693. There are two ways around this problem:
  3694.   a) Shutdown GoServe, clear macrospace, and restart GoServe
  3695.      whenever you update SREFPRC.RXL
  3696.      (this is what the SRE-http install procedure does).
  3697.   b) Set CLEAR_MACROSPACE=1, and shutdown/restart GoServe.
  3698.      When CLEAR_MACROSPACE=1, SRE-http will "clear" macrospace,
  3699.      and then load SREFPRC2.RXL.
  3700.       
  3701. Thus, use of CLEAR_MACROSPACE=1 saves you the trouble of explicitily 
  3702. clearing macrospace. However, since macrospace is global to OS/2,
  3703. such an act may adversely impact other REXX programs. 
  3704.  
  3705. Thus, use CLEAR_MACROSPACE=1 only if you KNOW that no other REXX
  3706. programs are using macrospace!
  3707.  
  3708. Example:
  3709.   clear_macrospace=0   /* do NOT clear macrospace */
  3710.  
  3711.  
  3712.  
  3713. ***************
  3714. CFGS_DIR
  3715.  
  3716. Fully qualified name of the directory containing the SRE-http configuration
  3717. files. If blank, a default (CFGS under the GoServe working directory) is used.
  3718.  
  3719.  
  3720. Examples:
  3721.   CFGS_DIR=''            (use the default; perhaps D:\GOSERVE\CFGS)
  3722.   CFGS_DIR='D:\SERVER\CFGS1\CFGS'   
  3723.  
  3724. In general, we STRONGLY recommend setting CFGS_DIR=''.
  3725.  
  3726.  
  3727. ****************
  3728. DOANYWAY_LOOPS
  3729.  
  3730. SRE-http will reread its various parameter files whenever it detects a change.
  3731. Occassionally, a change may occur that is undetected (typically, when you
  3732. are making & saving changes rapidly). To catch such changes, SRE-http will
  3733. occasionally automatically re-read configuation files, even if no change is
  3734. detected.  The DOANYWAY_LOOPS parameter controls this.
  3735.  
  3736. DOANYWAY_LOOPS is measured (approximately) in DELAY_SECONDS units (by default,
  3737. 15 seconds). The default value of DOANYWAY_LOOPS of 300 means "redo every
  3738. 300 loops", about 1.25 hours.
  3739.  
  3740. Example:   
  3741.    doanyway_loops=300      
  3742.  
  3743. ****************
  3744. DO_CLEANUP
  3745.  
  3746. When CGI-BIN scripts are run, they create several temporary files. 
  3747. Should a CGI-BIN script abort prematurely, or otherwise fail, these 
  3748. files will be left behind. In order to keep disk clutter to a minimum,
  3749. SRE-http can occasionally remove "orphaned" CGI-BIN temporary files.  
  3750.  
  3751. DO_CLEANUP=1    : Enable this "orphaned files" removal
  3752. DO_CLEANUP=0    : Suppress this "orphaned files" removal
  3753.  
  3754. Note that the file time/date is used for this removal. If you have scripts that
  3755. stay active for days, you might have problems using DO_CLEANUP=1!
  3756.  
  3757. ***************
  3758. USE_LIB_DIR
  3759.  
  3760. Fully qualified name of the directory containing the SRE-http dynamic 
  3761. macrospace library procedures.  If blank, a default (LIB under the
  3762. GoServe working directory) is used.
  3763.  
  3764. If you installed SRE-http with a non-default "sre-http" library directory, 
  3765. you must set this.
  3766.  
  3767. Examples:
  3768.   USE_LIB_DIR=''            (use the default; perhaps D:\GOSERVE\LIB)
  3769.   USE_LIB_DIR='D:\PROCS\SRELIB'   
  3770.  
  3771. In general, we STRONGLY recommend setting USE_LIB_DIR=''.
  3772.  
  3773. ***************
  3774. LOGFILE_MAXSIZE 
  3775.  
  3776. The maximum size of common, referer, browser and combined log files
  3777. (in Kbytes).  
  3778.  
  3779. When one of these files exceeds this size, it will be renamed using
  3780. a sequentially numbered extension. Thus, the first time common.log 
  3781. gets large,it will be renamed to COMMON.001; and the second time
  3782. it will be renamed to COMMON.002 (etc. etc. etc.)
  3783.  
  3784. To suppress this auto-renaming, set LOGFILE_MAXSIZE=0
  3785.  
  3786. Examples:
  3787.         LOGFILE_MAXSIZE=0
  3788.         LOGFILE_MAXSIZE=1000
  3789.  
  3790. where 1000 means 1M (1000 kilo bytes).
  3791.  
  3792. Notes:
  3793.   * File sizes are checked occasionally. Thus, on rare occassions the size of
  3794.     a log file file will exceed this maxsize by a few kbytes.
  3795.   * Reminder: LOGFILE_MAXSIZE=1000 means "maximum size of 1Mbyte"
  3796.   * The LOG_TOOBIG parameter (in POSTFCHK.RXX) is no longer used. Thus,
  3797.     warnings about your log file becoming too large will NO LONGER be written
  3798.     to the PMPRINTF window.
  3799.   * For finer control of the renaming of log files, you should set
  3800.     LOGFILE_MAXSIZE=0, and use the RENLOGS.CMD utility (see SCHEDULDE.DOC
  3801.     for details on running scheduled events)
  3802.  
  3803.  
  3804.  
  3805. ****************
  3806. MD5_CACHE
  3807.  
  3808. The MD5_CACHE is an optional daemon that will take care of computing
  3809. MD5 digests (for inclusion in a Content-MD5 response header).  
  3810. If you set MD5_CACHE to be a non-zero value, then SRE-http
  3811. will launch an MD5 daemon (as a seperate process), and this
  3812. daemon will create a cache for up to MD5_CACHE entries. 
  3813.  
  3814. When an MD5 digest is needed, the daemon will first check this cache,
  3815. and if a match is found (and the file has not changed), then the
  3816. MD5 digest stored in the cache will be used. Otherwise, an MD5 digest
  3817. will be computed.
  3818.  
  3819. If MD5_CACHE=0, then the MD5 daemon will NOT be launched, and an
  3820. MD5 digest will always be re-computed.
  3821.  
  3822. Examples:
  3823.    MD5_CACHE=0          /* no md5 daemon */
  3824.    MD5_CACHE=800        /* store up to 800 md5 digests */
  3825.  
  3826.  
  3827. Notes: 
  3828.   * The MD5_CACHE is only used if CONTENT_MD5=1. 
  3829.         Thus, if  CONTENT_MD5=0, 
  3830.         then you might as well set MD5_CACHE=0.
  3831.  
  3832.   * There are two reasons for using the MD5 daemon
  3833.       i) For large files, computing the md5 digest may be time consuming;
  3834.          hence maintaining a cache of values can improve throughput.
  3835.      ii) As noted above, on rare occasions the MD5 digest procedure will 
  3836.          throw a sys3175 error (and crash goserve).  Placing
  3837.          the daemon in a seperate process isolates this crash from GoServe.
  3838.  
  3839. ****************
  3840. MEDIATYPE_FILE_ALWAYS
  3841.  
  3842. To determine the content-type (the mimetype) of a response, SRE-http
  3843. uses an "extension to mimetype" mapping strategy. 
  3844.  
  3845.    Basically, the selector's extension (i.e.; HTML in FOO.HTML) is compared 
  3846.    to a list of mappings, the mapping that contains the selector's extension
  3847.    also contains its mimetype.
  3848.  
  3849. By default, SRE-http will use a hard-coded set of mappings.  You can
  3850. add to, or override, these defaults, by changing the MEDIATYP.RXX file.
  3851.  
  3852. MEDIATYPE_FILE_ALWAYS is used to control whether SRE-http will
  3853. always read this MEDIATYP.RXX file, or it whether it reads
  3854. MEDIATYP.RXX only when none of the default mappings work. 
  3855.  
  3856.   MEDIATYPE_FILE_ALWAYS=0
  3857.       Only check MEDIATYP.RXX when no default "extension to
  3858.       mimetype" entry can be found.
  3859.  
  3860.   MEDIATYPE_FILE_ALWAYS=1
  3861.       Always check MEDIATYP.RXX, and allow MEDIATYP.RXX 
  3862.       entries to override default entries.
  3863.  
  3864. Notes:
  3865.    * Default entries are hard coded in MEDIATYP.SRF (in the \LIB sudirectory).
  3866.    * MEDIATYP.RXX is located7 in your GoServe working directory.
  3867.    * For details on custom assignation of a selectors mimetype, see
  3868.      SREHTTP.FAQ or see ADV_OPTS.DOC.
  3869.    * If you NEVER use MEDIATYP.RXX to override defaults, you can speed things
  3870.      up a bit by setting MEDIATYPE_FILE_ALWAYS=0.
  3871.  
  3872.  Example:
  3873.    MEDIATYPE_FILE_ALWAYS=1 
  3874.  
  3875.  
  3876. ****************
  3877. NO_DNS
  3878.  
  3879. If your access to a DNS is slow, or non-existent, SRE-http can take a
  3880. long time to process requests. This is caused by SRE-http waiting
  3881. for a timeout on a DNS request (as is needed when resolving a
  3882. client's ip name).
  3883.  
  3884. You can work around this problem by setting NO_DNS=1.
  3885.  
  3886. If NO_DNS=0, then DNS lookups will occur.
  3887. If NO_DNS=1, then DNS lookups will NOT occur -- the IP number 
  3888. will be used instead of the IP name.
  3889.  
  3890. Example:
  3891.   NO_DNS=0
  3892.  
  3893.  
  3894. ****************
  3895. NO_SUPERCEDING_REALM
  3896.  
  3897. SRE-http uses "superceding realms" (specified in ATTRIBS.CFG) to
  3898. group several types of selector-specific information. This includes
  3899. information on whether the selector is a PUB_URL, its redirection
  3900. ALIASES, ACCESS controls, and VIRTUAL directory information.
  3901.  
  3902. If a selector matches a rule for a superceding realm, then no
  3903. other selector-specific information is looked for. That is, entries
  3904. in the various .IN files will not be used, and entries in
  3905. non-superceding realms will not be examined.
  3906.  
  3907. To suppress this special treatment of superceding realms, set
  3908. NO_SUPERCEDING_REALM=1 (superceding realm entries will still
  3909. be checked, but they will not "supercede" all other kinds
  3910. of entries).
  3911.  
  3912. For a further  description of superceding realms, see IN_FILES.DOC.
  3913.  
  3914. Example:
  3915.  
  3916.   NO_SUPERCEDING_REALM=0
  3917.  
  3918. ****************
  3919. STORAGE_DAEMONS
  3920.  
  3921. By default (when STORAGE_DAEMONS=1), SRE-http will launch one instance
  3922. of the "variable storage daemon". There may be times where having
  3923. multiple instances of this daemon is beneficial. In particular,
  3924. if you are heavily using an SRE-http queue (via the SREF_QUEUE procedure),
  3925. assigning the queue to the "non-default variable storage daemon" can
  3926. improve throughput.
  3927.  
  3928. Examples:
  3929.    STORAGE_DAEMONS=1  : Start one (the default) variable storage daemon
  3930.    STORAGE_DAEMONS=3  : Start three instances (the default, plus two additional)
  3931.  
  3932. For more details on how to use these daemons with SREF_QUEUE, see SREFQUE.DOC
  3933.  
  3934.  
  3935. ****************
  3936. USE_DYNAMIC_LIB:
  3937.  
  3938. If you wish to not use a "dynamic macrospace library",  set 
  3939. USE_DYNAMIC_LIB=0
  3940.  
  3941. HOWEVER -- you'll have to or create, using MAKELIB.CMD,
  3942. a "SREFPRC1.RXL" static macrospace library file, and store it
  3943. in your GoServe working directory.
  3944.  
  3945. Note that there is one good reason for using a "static" macrospace
  3946. library -- when using sre-http macrospace procedures in other (non-goserve)
  3947. programs, the dynamic procedures library may not be found -- which means 
  3948. they won't be available. 
  3949.  
  3950. In contrast, the static procedures,once loaded,are "all there". 
  3951.  
  3952.  
  3953.                   ========================================
  3954.  
  3955.  
  3956.    Section 3.       A Comparison of Local vs. Remote Redirection of URL's
  3957.  
  3958.  
  3959. One of the strengths of SRE-http is the variety of redirection
  3960. mechanisms it offers, where redirection implies "sending the client
  3961. a file that is not a direct mapping of the request selector".  Redirection
  3962. has two general classes: remote and local.
  3963.  
  3964. "Remote" redirection, which  is what most of the literature simply
  3965. calls redirection, involves telling the client's browser that
  3966. "the url you have requested has been moved to xxxx", where xxxx may
  3967. be any URL  -- it need not be on the same server, and it need not have
  3968. the same name.
  3969.  
  3970. For example, an alias (in the alias-file) of
  3971.    whatgot  http://www.mine.org/dir1/index1.htm
  3972. would cause the server to send back a "302" response to the client's
  3973. browser whenever a request for "whatgot" arrives.  This 302 response,
  3974. would instruct the client's browser to automatically request
  3975. http://www.mine.org/dir1/index1.htm.
  3976.  
  3977. "Local" redirection is handled solely by the server, and involves
  3978. substituting the "request selector" with another "request selector".
  3979. SRE-http has a number of methods of specifying "local redirection",
  3980. such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the
  3981. use of aliases of the form:
  3982.    whatgot   dir1/index.htm.
  3983.  
  3984. In all these cases, the browser assumes that the document it recieves
  3985. is a direct result of the  original request selector issued.
  3986.  
  3987. While offering a real convenience, with less demands on the client,
  3988. local redirection can have undesired effects.  In particular, "partial URLS"
  3989. in documents that were sent as the result of a local alias
  3990. may not work properly.
  3991.  
  3992. A short discussion of how browsers handle partial URLs is germane:
  3993.  
  3994.    When a link (in an HTML document) is specified as a "partial URL"
  3995.       (such as <img src="wow.gif"> or <a href="wow.htm">)
  3996.    the  URL actually requested by the browser is determined by using 
  3997.    the "full" URL that invoked this html document.
  3998.  
  3999.    For example, if the client asks for, and recieves:
  4000.       http://www.mine.net/dir1/index.htm,
  4001.    and index.htm contains  a "partial URL" of:
  4002.       <img src="wow.gif">,
  4003.    the client's browser would then try to get:
  4004.        http://www.mine.net/dir1/wow.gif.
  4005.  
  4006. In other words, when the browser is asked to get a partial url (that does NOT
  4007. begin with a /), it will take everything before the last / in the "parent" URL
  4008. (of the document that contains this partial URL) and then append the requested
  4009. partial URL.
  4010.  
  4011. (Actually, if a URL does not begin with http://, it will
  4012. append the "begins with / partial URL" to the http://.../ component of
  4013. the "full URL".)
  4014.  
  4015. The use of the "local redirection" features of SRE-http is
  4016. complicated by this "automatic resolution of partial URLS".
  4017. If you want to use local redirection you should:
  4018.    1) fully specify the links in your documents ..
  4019.       i.e.; use /dir1/foo.gif instead of foo.gif
  4020.    2) Use a <base> element in the <HEAD> of each document...
  4021.       i.e.; <base href="/dir1/">
  4022.    3) Don't use local redirection (just use remote redirection).  This
  4023.       entails the use of "remote" aliases instead of AUTO_NAME, DEFAULT,
  4024.       and NOEXT_TYPE.
  4025.  
  4026.  
  4027.                      ========================================
  4028.  
  4029.   Section 3a.   An example of local redirection.
  4030.  
  4031. Local redirection, despite its potential pitfalls, does provide some fairly
  4032. powerful configuration possibilitles.  As an example, consider recording
  4033. "successful" transfers of one of several files: STUFF.ZIP and OTHRSTUF.ZIP.
  4034.  
  4035.  i) The simple method.
  4036.        Assume an HTML document with the following links
  4037.            <A href="stuff.zip">Get our stuff </a> <br>
  4038.            or, <A href="othrstuf.zip">get our other stuff </a>
  4039.        Also assume that RECORD_OPTION='YES'
  4040.  
  4041.        When a client invokes one of these links, SRE-http will augment the
  4042.        appropriate entry in the RECORD_ALL_FILE.
  4043.  
  4044. If you wish to record "each individual" request, you could wade through
  4045. SRE-http's "common-log" audit file. A better idea is to use SENDFILE with
  4046. the COUNTER option:
  4047.  
  4048.    ii) Using SENDFILE, the above would be:
  4049.            <A href="sendfile?stuff.zip&counter=file=stuff">Get our stuff </a>
  4050.            <br> or, <A href="sendfile?othrstuf.zip&counter=file=othrstuf">
  4051.                 get our other stuff </a>
  4052.  
  4053.        The SENDFILE facility is used to transfer the document; and upon
  4054.        successful transfer, the appropriate .CNT file is updated.
  4055.  
  4056. One nice feature of SENDFILE is that unsuccessful (or aborted) transfers
  4057. are explicitily noted.  There is a minor problem: many browsers
  4058. (i.e.; Netscape) will give the client a default filename of "SENDFILE".
  4059. This will probably confuse a number of folks.
  4060.  
  4061. Fortunately, it's not  hard to avoid this problem by using local redirection.
  4062.  
  4063.    iii) Using local redirection, we use what looks like a standard URL, with
  4064.         the following in the HTML document:
  4065.            <A href="/stuff.zip">Get our stuff </a> <br>
  4066.            <A href="/othrstuf.zip"> or, get our other stuff </a>
  4067.         In addition, we include  the following entries in the ALIAS_FILE:
  4068.            stuff.zip     sendfile?stuff.zip&counter=file=stuff
  4069.            othrstuf.zip  sendfile?othrstuf.zip&counter=file=othrstuf
  4070.  
  4071.         When a request for "stuff.zip" arrives, SRE-http uses the
  4072.         sendfile?stuff.zip&counter=file=stuff alias. The client's browser
  4073.         doesn't know this, and will assume the file's name is stuff.zip
  4074.         (which is the desired assumption).
  4075.  
  4076. This use of aliases could not be replicated with virtual directories, or with
  4077. remote redirection!
  4078.  
  4079.  
  4080. --- End of Document.
  4081.