home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / use_cfgs.doc < prev    next >
Text File  |  2001-03-27  |  15KB  |  372 lines
  1. 18 October  1999
  2.                    SRE-http's configuration files.
  3.  
  4. SRE-http version 1.3d introduced a change in the structure of
  5. SRE-http's configuration files. This document discusses these changes,
  6. and how to "migrate" from earlier versions of SRE-http to this new structure.
  7.  
  8. The basic changes are:
  9.  
  10.  a) A new subdirectory is used: the CFGS\ subdirectory under the
  11.     GoServe working directory.
  12.  
  13.  b) Static initialization parameters, that used to be specified in SREFILTR.80,
  14.     are now stored in INIT_STA.80.
  15.  
  16.  c) Several configuration files are now installed to the CFGS\ subdirectory;
  17.     instead of the DATA\ subdirectory.
  18.  
  19.  d) Two new configuration files are supported:
  20.       CFGLIST.CFG  --  specify host & port specific configuration files
  21.       SCHEDULE.CFG -- for specifying scheduled event
  22.   
  23.  e) Version 1.3f introduced ATTRIBS.CFG, a new file for setting "selector
  24.     attributes on a realm specific basis."  We now recommend use of
  25.     ATTRIBS.CFG instead of the various .IN files.
  26.  
  27.                 -----------------------------------------------
  28.  
  29.  
  30.  
  31. A) The CFGS\ subdirectory.
  32.  
  33. SRE-http now stores configuration information in the CFGS\ subdirectory 
  34. (of your GoServe working directory).  If necessary, this directory will be 
  35. created when you run SRE-http's INSTALL program).
  36.  
  37.                 -----------------------------------------------
  38.  
  39. B) Static initialization parameters  are now stored in INIT_STA.80,      
  40.    and not in SREFILTR.80.                                               
  41.  
  42. In order to avoid the hassle of modifying SREFILTR.80 whenever an upgrade 
  43. occurs, parameters in SREFILTR.80 are now defined in INIT_STA.80, which 
  44. is stored in the CFGS\ subdirectory.   
  45.  
  46. Upon your first install of ver 1.3d (or above), you can either
  47.  i)  Edit the default version of INIT_STA.80
  48.       *  The EDITSREF.CMD utility can be used to edit parameters
  49.          in INIT_STA.80.
  50.  ii) Extract information from your current version of srefiltr.80
  51.      a) use your favorite editor to extract the 
  52.         "User Configurable Parameters" section from your current 
  53.         version of SREFILTR.80 (you did enable the backup option
  54.         when you installed version SRE-http)
  55.      b) paste this to a new file
  56.      c) save this file as INIT_STA.80
  57.  
  58. Caution:
  59.   INIT_STA.80 is "interpreted" -- hence, it must be valid rexx code.
  60.   That means that /*   */ is used to bracket comments (the ; comment 
  61.   delimiter used in other SRE-http files should NOT be used in INIT_STA.80).
  62.  
  63.                 -----------------------------------------------
  64.  
  65.  
  66. C) Several configuration files are now installed to the CFGS\ subdirectory;
  67.    instead of the DATA\ subdirectory.
  68.  
  69. If you do a new install of SRE-http, several files will be written to
  70. the CFGS\ subdirectory; several of which used to be written to the DATA\
  71. subdirectory,  These files are:
  72.   ALIASES.IN   -- aliases and redirections
  73.   ACCESS.IN    -- access control information
  74.   ATTRIBS.CFG  -- the "realm definition", users, & replacement strings file
  75.   CFGLLIST.CFG -- list of "host/port specific" configuration files
  76.   INITFILT.80  -- dynamic initialization parameters
  77.   INIT_STA.80  -- static initialization parameters
  78.   PUBURLS.IN   -- public_urls
  79.   REPSTRGS.IN  -- <!-- REPLACE --> strings file
  80.   SCHEDULE.CFG -- event scheduluing information
  81.   SREFLOGS.INI -- common log configuartion
  82.   USERS.IN     -- username/passwords
  83.   VIRTUAL.IN   -- virtual directories
  84.  
  85. If you do an upgrade, these files will NOT be copied. Although you can 
  86. continue to use your current setup, we recommend the following:
  87.  
  88. a) Move INITFILT.80 from to the CFGS\ directory (relative to the
  89.    GoServe working  directory)  Note that INIT_STA.80 should
  90.    already be in the CFGS\ directory (INSTALL will always create 
  91.    a CFGS\INIT_STA.80 if one does  not exist). 
  92.        Note:
  93.         i) SRE-http will first look for CFGS\INITFILT.80 (or INITFILT.nnnn
  94.            if you are using port nnnn)
  95.        ii) If that does not exist, SRE-http will then look for INITFILT.80
  96.            (in the GoServe working directory)
  97.       iii) If neither exist, SRE-http will report an error, and stop.
  98.  
  99. b) Move the following files from your DATA\ directory to this 
  100.    CFGS\ directory:
  101.       ACCESS.IN, ALIASES.IN, PUBURLS.IN, REPSTRGS.IN, SREFLOGS.INI,
  102.       USERS.IN, and VIRTUAL.IN
  103.  
  104. c) Using your favorite text editor, edit INITFILT.80; and change several 
  105.    filename parameters to point to CFGS\, instead of DATA\.  
  106.       In particular, change the following variables:
  107.          ACCESS_FILE, ALIAS_FILE, PUBURL_FILE, USER_FILE, VIRTUAL_FILE,
  108.  
  109.    For example, you should change
  110.       ACCESS_FILE='E:\GOSERVE\DATA\ACCESS.IN'
  111.    to
  112.       ACCESS_FILE='E:\GOSERVE\CFGS\ACCESS.IN'
  113.  
  114.  
  115. Note that ATTRIBS.CFG, which is new to 1.3f, is also copied
  116. to CFGS\ on a new install.
  117.  
  118.                 -----------------------------------------------
  119.  
  120.  
  121. D) Host and port specific configuration files using CFGLIST.CFG
  122.  
  123. CFGLIST.CFG is used to specify host-specific information,
  124. including  HOST definitions (assignations of IP addresses/aliases
  125. to SRE-http HOST_NICKNAMES), and to define host (and port) specific 
  126. configuration files.
  127.  
  128. In particular, you can define:
  129.  
  130.    i) The host_nickname and default data directory to use for
  131.       an IP address/alias. This is now the recommended method 
  132.       of defining hosts (note that one can still use HOSTS. entries
  133.       in INITFILT.80).
  134.  
  135.  ii) In addition, for each host you can define several configuration files
  136.      (the defaults are in parenthesis):
  137.        * ALIAS files  (ALIASES.IN)
  138.        * ACCESS control files (ACCESS.IN)
  139.        * Realm-definiton, etc. files (ATTRIBS.CFG)
  140.        * COUNTER.RXX COUNTER_DIR directory (set in COUNTER.RXX)
  141.        * HIT_COUNTER hit-counter files (COUNTER.CNT)
  142.        * INITFILT configuration parameters files (INITFILT.80)
  143.        * PUBLIC_URLS files (PUBURLS.IN)
  144.        * RECORD_ALL_FILE audit files (RECRDALL.CNT)
  145.        * REPLACEMENT strings files (REPSTRGS.IN)
  146.        * SEND_FILE counter files (SENDFILE.CNT)
  147.        * USERNAME/PASSWORD files (USER.IN)
  148.        * VIRTUAL directories files (VIRTUAL.IN)
  149.  
  150. The primary advantage of this capability (in addition to reducing clutter)
  151. is to allow a user to have complete control over a host, without giving him
  152. access to parameters that effect other hosts. For example, one could
  153. place a set of "host specific" configuration files in a directory (say,
  154. E:\GOSERVE\CFGS\HISHOST1) and give an administrator FTP privileges to 
  155. this directory). Then, she could freely modify these files; but not the
  156. default SRE-http parameter files (assuming you did not give her 
  157. superuser privileges).
  158.  
  159.  
  160.  
  161.                 -----------------------------------------------
  162.  
  163. Appendix 1: SCHEDULE.CFG
  164.  
  165. There should be one entry per line; with each entry having the form:
  166.  
  167.     frequency prog_name
  168.  
  169. here:
  170.     frequency: frequency of execution; 
  171.     prog_name: a fully qualified (typically REXX) program to execute
  172.     argument: an argument to be sent to prog_name
  173.  
  174. The following frequencies are permitted:
  175.   HOURLY -- run in at nn:01 (nn=0..23)
  176.    DAILY -- run it at midnight (12:01 AM)
  177.   WEEKLY -- run it Sunday at 12:01 AM
  178.  MONTHLY -- run it at 12:01 on the first day of a month
  179.  
  180.  Examples:
  181.  
  182. DAILY D:\GOSERVE\RENLOGS.CMD 
  183. MONTHLY E:\GOSERVE\MYPROG.CMD Monthly Execution
  184.  
  185.  
  186. Hint: SRE-http comes with "RENLOGS.CMD", the log-renamer (which can be
  187.       used as an alternative to setting the LOGFILE_MAXSIZE variable in 
  188.       SREFMON.CMD)
  189.  
  190.                 -----------------------------------------------
  191.  
  192. Appendix 2: CFGLIST.CFG
  193.  
  194. CFGLIST.CFG lists host and port specific configuration files.
  195. It is organized into sections, with a section containing files
  196. pertaining to a host and port combination.
  197.  
  198.  
  199. Syntax:
  200. a) Sections are seperated by blank lines
  201. b) Each section contains case-insensitive "mime-style" entries, with a form:
  202.       identifier:  value 
  203.   Notes:
  204.    * the identifier must end with a colon (a :)
  205.  
  206.  
  207. c) Each section should contain the following entries:
  208.  
  209.    PORT: this section applies to servers running on this port number.
  210.          If PORT is not specified, port 80 is assumed
  211.  
  212.    HOST: a SRE-http "host_nickname".
  213.        This host_nickname is used in SRE-http configuration files to 
  214.        associate values with "requests to this host".
  215.        If host is not defined, or if no value is specified,
  216.        the section specifies "default" entries.
  217.  
  218.        Note: to define a "superceding" host, the host nickname MUST
  219.                start with a _!.
  220.             to define a "strict-superceding" host, the host nickname MUST
  221.                start with a _!!.
  222.         For example:
  223.                 IP: wood.oursite.org
  224.                 HOST: _!forest 
  225.              means "the _!forest host is a superceding host"
  226.  
  227.              Definition of superceding host: 
  228.                 For access control, redirection, and virtual 
  229.                 directory parameters:
  230.                 a) strict-superceding host: non-host specific parameters are
  231.                    never used
  232.                 b) superceding host: a matching host-specific parameter 
  233.                    "trumps" a (possibly better quality) matching non-host 
  234.                     specific parameter
  235.                 c) non-superceding hosts: the best match, across host and
  236.                    non-host specific parameters, is used
  237.  
  238.                  Please see the description of HOSTS. in INITFILT.DOC,
  239.                  or section 1.3 of IN_FILES.DOC, for a fuller description
  240.                  of superceding hosts.
  241.  
  242.    IP: the ip address (or alias) of this host -- the host_nickname is 
  243.        "associated" with this IP address (or IP alias).
  244.        The IP: should be:
  245.          > what would be specified in a  HOST: request header.
  246.          > an ip address if your machine is serving multiple ip addresses
  247.        If no IP: is defined, only the following entries are used:
  248.              PUBULRLS:, USERS:, ACCESS:, ALIAS:, VIRTUAL:, REPSTRGS:, 
  249.              and INITFILT:
  250.        
  251.   DATADIR: The default data directory for this HOST.
  252.        If not specified (and an IP: and HOST: are specified), the 
  253.        GoServe default data directory is used.
  254.  
  255.  
  256. d) The other valid identifiers are:
  257.      ALIAS:   a redirection aliases file
  258.      ACCESS:  an access control file
  259.      COUNTER_RXX:  a COUNTER.RXX default "COUNTER_DIR" directory
  260.      HIT_COUNTER: a  hit-counter file (used in <!-- Replace hits --> SSI's)
  261.      ATTRIBS: the "define realms" file
  262.      INITFILT:  a "dynamic" configuration parameters file
  263.      PUBURLS: a PUBLIC_URLS file
  264.      RECORD_ALL_FILE: a SRE-http RECORD_ALL audit file
  265.      REPSTRGS:  a REPLACEMENT strings file (used in <!-- REPLACE varname -->
  266.      SEND_FILE: a SENDFILE  counter files (used by the SENDFILE utility)
  267.      USERS:  username/password file
  268.      VIRTUAL: a virtual directories file
  269.    and a special entry:
  270.      *: a subdirectory containing host/port specific configuration files
  271.  
  272. Notes:
  273.    i)  In general, the value for these entries should be either:
  274.          i) a fully qualifed file  name (it MUST include a drive letter) 
  275.         ii) a relative filename (relative to the CFGS\ directory)
  276.   
  277.    ii) *: is a special shorthand,it expects a subdirectory.
  278.        It means "look for the default files names in this subdirectory"
  279.         where the default names are: 
  280.           PUBURLS.IN, USERS.IN, ACCESS.IN, ALIASES.IN, VIRTUAL.IN,
  281.           REPSTRGS.IN, and INITFILT.80 
  282.        Notes:
  283.            * these  defaults  names are used, and NOT
  284.              values you may have set in CFGS\INITFILT.80. 
  285.            * if you use * in section:, you should NOT use:
  286.              PUBULRLS:, USERS:, ACCESS:, ALIAS:, VIRTUAL:, REPSTRGS:, 
  287.              or INITFILT:
  288.           
  289.   iii) These entries will be added to the respective "default" files --
  290.        that is, they do NOT replace the default files.
  291.       * i.e.; to the INITFILT.80, PUBURLS.IN, USERS.IN, ACCESS.IN, 
  292.         ALIASES.IN, REPSTRGS.IN, and VIRTUAL.IN files defined in 
  293.         the "default" INITFILT.80.
  294.       * a "host specific" INITFILT.80 should ONLY contain parameters that
  295.         can take host specific values (see INITFILT.DOC for the details)
  296.       * Only entries pertaining to the appropriate port will be added.
  297.       * Implicitily, a HOST// is appended before each of these entries.
  298.  
  299.   iv) Reminders:
  300.      If you do NOT specify a HOST:, or if the "value" is empty,
  301.      the section applies to the "default" host.
  302.      If you do NOT specify a PORT:, the "section" applies to port 80 servers.
  303.      If you specify an IP:, you MUST specify a HOST
  304.  
  305.   v) In NO CASE should an entry (in one of these auxillary files)
  306.       contain a "HOST//" prefix,  a .HOST "stem"!, or a host:
  307.       action.
  308.  
  309.   vi) It is possible to have several sections apply to the same host & port. 
  310.       In fact, it is not a bad idea to have seperate entries when 
  311.       multiple representations may be used for the same  address 
  312.       (such as internal clients using www2, and outsiders using 
  313.       www2.bigcorp.com) --
  314.          a)  the first such section would define   the various    
  315.              "host-specific" files, 
  316.          b)  the remaining sections would only contain a HOST:,  an IP:,
  317.              and a DATADIR: entry (in other words, the same information
  318.              contained in an INITFILT.80 HOSTS. parameter).
  319.  
  320.   vii) Since blank lines delimit sections; do NOT include blank lines between
  321.        entries (within a section). However, you can include comment 
  322.        lines (that begin with ;)
  323.  
  324.  viii) ACCESS refers to ACCESS.IN equivalents.
  325.  
  326.    ix) The  COUNTER_DIR is used by COUNTER.RXX.  This DOES require
  327.        that you update to ver 1.3d (or above) of COUNTER.RXX.
  328.  
  329.  
  330.     x) The RECORD_ALL_FILE is used to record counts of all hits (on
  331.        a selector specific basis).
  332.        Caution: if you specify any host-specific count files, then you
  333.                must set RECORD_CACHE_LINES=0 (in INIT_STA.80).
  334.  
  335. Example: (the indentations are for readabilty, as is the purposely
  336.           sloppy use of lower case):
  337.  
  338. host: ZOO
  339.   ip: www.zoo.org
  340.   datadir: d:\zoo\htmls
  341.   RECORDALL: D:\ZOO\COUNTERS\RECALL.CNT
  342.  
  343. host: ZOO
  344.   ALIAS: ZOO\ALIASES.IN     
  345.   ACCESS: ZOO\ACCESS1.CTL
  346.  
  347. host:store
  348.   IP: 121.22.5.3
  349.   port:8080
  350.   datadir: d:\storewww
  351.   users: D:\STORESITE\PRIVATE\USERS.1
  352.   initfilt: d:\storesite\moreinit.80
  353.   hit_counter: d:\storesite\hitcounts.cnt
  354.  
  355. HOST:
  356.  USERS: MOREUSER.IN
  357. ; do NOT specify a DATADIR or a HOST for the "default host"
  358.  virtual: VIRTUAL2.IN
  359.  
  360. HOST:WWW2
  361.  IP: WWW2
  362.  DATADIR:
  363.  *: WWW2INIS\
  364. ; since datadir: is empty, use the goserve datadir directory
  365.   
  366. HOST: $WWW3
  367. ATTRIBS: F:\GUEST\WWW3\ATTRIBS.W3
  368.  
  369.  
  370. .end of document
  371.  
  372.