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