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