18 October 1999 SRE-http's configuration files. SRE-http version 1.3d introduced a change in the structure of SRE-http's configuration files. This document discusses these changes, and how to "migrate" from earlier versions of SRE-http to this new structure. The basic changes are: a) A new subdirectory is used: the CFGS\ subdirectory under the GoServe working directory. b) Static initialization parameters, that used to be specified in SREFILTR.80, are now stored in INIT_STA.80. c) Several configuration files are now installed to the CFGS\ subdirectory; instead of the DATA\ subdirectory. d) Two new configuration files are supported: CFGLIST.CFG -- specify host & port specific configuration files SCHEDULE.CFG -- for specifying scheduled event e) Version 1.3f introduced ATTRIBS.CFG, a new file for setting "selector attributes on a realm specific basis." We now recommend use of ATTRIBS.CFG instead of the various .IN files. ----------------------------------------------- A) The CFGS\ subdirectory. SRE-http now stores configuration information in the CFGS\ subdirectory (of your GoServe working directory). If necessary, this directory will be created when you run SRE-http's INSTALL program). ----------------------------------------------- B) Static initialization parameters are now stored in INIT_STA.80, and not in SREFILTR.80. In order to avoid the hassle of modifying SREFILTR.80 whenever an upgrade occurs, parameters in SREFILTR.80 are now defined in INIT_STA.80, which is stored in the CFGS\ subdirectory. Upon your first install of ver 1.3d (or above), you can either i) Edit the default version of INIT_STA.80 * The EDITSREF.CMD utility can be used to edit parameters in INIT_STA.80. ii) Extract information from your current version of srefiltr.80 a) use your favorite editor to extract the "User Configurable Parameters" section from your current version of SREFILTR.80 (you did enable the backup option when you installed version SRE-http) b) paste this to a new file c) save this file as INIT_STA.80 Caution: INIT_STA.80 is "interpreted" -- hence, it must be valid rexx code. That means that /* */ is used to bracket comments (the ; comment delimiter used in other SRE-http files should NOT be used in INIT_STA.80). ----------------------------------------------- C) Several configuration files are now installed to the CFGS\ subdirectory; instead of the DATA\ subdirectory. If you do a new install of SRE-http, several files will be written to the CFGS\ subdirectory; several of which used to be written to the DATA\ subdirectory, These files are: ALIASES.IN -- aliases and redirections ACCESS.IN -- access control information ATTRIBS.CFG -- the "realm definition", users, & replacement strings file CFGLLIST.CFG -- list of "host/port specific" configuration files INITFILT.80 -- dynamic initialization parameters INIT_STA.80 -- static initialization parameters PUBURLS.IN -- public_urls REPSTRGS.IN -- strings file SCHEDULE.CFG -- event scheduluing information SREFLOGS.INI -- common log configuartion USERS.IN -- username/passwords VIRTUAL.IN -- virtual directories If you do an upgrade, these files will NOT be copied. Although you can continue to use your current setup, we recommend the following: a) Move INITFILT.80 from to the CFGS\ directory (relative to the GoServe working directory) Note that INIT_STA.80 should already be in the CFGS\ directory (INSTALL will always create a CFGS\INIT_STA.80 if one does not exist). Note: i) SRE-http will first look for CFGS\INITFILT.80 (or INITFILT.nnnn if you are using port nnnn) ii) If that does not exist, SRE-http will then look for INITFILT.80 (in the GoServe working directory) iii) If neither exist, SRE-http will report an error, and stop. b) Move the following files from your DATA\ directory to this CFGS\ directory: ACCESS.IN, ALIASES.IN, PUBURLS.IN, REPSTRGS.IN, SREFLOGS.INI, USERS.IN, and VIRTUAL.IN c) Using your favorite text editor, edit INITFILT.80; and change several filename parameters to point to CFGS\, instead of DATA\. In particular, change the following variables: ACCESS_FILE, ALIAS_FILE, PUBURL_FILE, USER_FILE, VIRTUAL_FILE, For example, you should change ACCESS_FILE='E:\GOSERVE\DATA\ACCESS.IN' to ACCESS_FILE='E:\GOSERVE\CFGS\ACCESS.IN' Note that ATTRIBS.CFG, which is new to 1.3f, is also copied to CFGS\ on a new install. ----------------------------------------------- D) Host and port specific configuration files using CFGLIST.CFG CFGLIST.CFG is used to specify host-specific information, including HOST definitions (assignations of IP addresses/aliases to SRE-http HOST_NICKNAMES), and to define host (and port) specific configuration files. In particular, you can define: i) The host_nickname and default data directory to use for an IP address/alias. This is now the recommended method of defining hosts (note that one can still use HOSTS. entries in INITFILT.80). ii) In addition, for each host you can define several configuration files (the defaults are in parenthesis): * ALIAS files (ALIASES.IN) * ACCESS control files (ACCESS.IN) * Realm-definiton, etc. files (ATTRIBS.CFG) * COUNTER.RXX COUNTER_DIR directory (set in COUNTER.RXX) * HIT_COUNTER hit-counter files (COUNTER.CNT) * INITFILT configuration parameters files (INITFILT.80) * PUBLIC_URLS files (PUBURLS.IN) * RECORD_ALL_FILE audit files (RECRDALL.CNT) * REPLACEMENT strings files (REPSTRGS.IN) * SEND_FILE counter files (SENDFILE.CNT) * USERNAME/PASSWORD files (USER.IN) * VIRTUAL directories files (VIRTUAL.IN) The primary advantage of this capability (in addition to reducing clutter) is to allow a user to have complete control over a host, without giving him access to parameters that effect other hosts. For example, one could place a set of "host specific" configuration files in a directory (say, E:\GOSERVE\CFGS\HISHOST1) and give an administrator FTP privileges to this directory). Then, she could freely modify these files; but not the default SRE-http parameter files (assuming you did not give her superuser privileges). ----------------------------------------------- Appendix 1: SCHEDULE.CFG There should be one entry per line; with each entry having the form: frequency prog_name here: frequency: frequency of execution; prog_name: a fully qualified (typically REXX) program to execute argument: an argument to be sent to prog_name The following frequencies are permitted: HOURLY -- run in at nn:01 (nn=0..23) DAILY -- run it at midnight (12:01 AM) WEEKLY -- run it Sunday at 12:01 AM MONTHLY -- run it at 12:01 on the first day of a month Examples: DAILY D:\GOSERVE\RENLOGS.CMD MONTHLY E:\GOSERVE\MYPROG.CMD Monthly Execution Hint: SRE-http comes with "RENLOGS.CMD", the log-renamer (which can be used as an alternative to setting the LOGFILE_MAXSIZE variable in SREFMON.CMD) ----------------------------------------------- Appendix 2: CFGLIST.CFG CFGLIST.CFG lists host and port specific configuration files. It is organized into sections, with a section containing files pertaining to a host and port combination. Syntax: a) Sections are seperated by blank lines b) Each section contains case-insensitive "mime-style" entries, with a form: identifier: value Notes: * the identifier must end with a colon (a :) c) Each section should contain the following entries: PORT: this section applies to servers running on this port number. If PORT is not specified, port 80 is assumed HOST: a SRE-http "host_nickname". This host_nickname is used in SRE-http configuration files to associate values with "requests to this host". If host is not defined, or if no value is specified, the section specifies "default" entries. Note: to define a "superceding" host, the host nickname MUST start with a _!. to define a "strict-superceding" host, the host nickname MUST start with a _!!. For example: IP: wood.oursite.org HOST: _!forest means "the _!forest host is a superceding host" Definition of superceding host: For access control, redirection, and virtual directory parameters: a) strict-superceding host: non-host specific parameters are never used b) superceding host: a matching host-specific parameter "trumps" a (possibly better quality) matching non-host specific parameter c) non-superceding hosts: the best match, across host and non-host specific parameters, is used Please see the description of HOSTS. in INITFILT.DOC, or section 1.3 of IN_FILES.DOC, for a fuller description of superceding hosts. IP: the ip address (or alias) of this host -- the host_nickname is "associated" with this IP address (or IP alias). The IP: should be: > what would be specified in a HOST: request header. > an ip address if your machine is serving multiple ip addresses If no IP: is defined, only the following entries are used: PUBULRLS:, USERS:, ACCESS:, ALIAS:, VIRTUAL:, REPSTRGS:, and INITFILT: DATADIR: The default data directory for this HOST. If not specified (and an IP: and HOST: are specified), the GoServe default data directory is used. d) The other valid identifiers are: ALIAS: a redirection aliases file ACCESS: an access control file COUNTER_RXX: a COUNTER.RXX default "COUNTER_DIR" directory HIT_COUNTER: a hit-counter file (used in SSI's) ATTRIBS: the "define realms" file INITFILT: a "dynamic" configuration parameters file PUBURLS: a PUBLIC_URLS file RECORD_ALL_FILE: a SRE-http RECORD_ALL audit file REPSTRGS: a REPLACEMENT strings file (used in SEND_FILE: a SENDFILE counter files (used by the SENDFILE utility) USERS: username/password file VIRTUAL: a virtual directories file and a special entry: *: a subdirectory containing host/port specific configuration files Notes: i) In general, the value for these entries should be either: i) a fully qualifed file name (it MUST include a drive letter) ii) a relative filename (relative to the CFGS\ directory) ii) *: is a special shorthand,it expects a subdirectory. It means "look for the default files names in this subdirectory" where the default names are: PUBURLS.IN, USERS.IN, ACCESS.IN, ALIASES.IN, VIRTUAL.IN, REPSTRGS.IN, and INITFILT.80 Notes: * these defaults names are used, and NOT values you may have set in CFGS\INITFILT.80. * if you use * in section:, you should NOT use: PUBULRLS:, USERS:, ACCESS:, ALIAS:, VIRTUAL:, REPSTRGS:, or INITFILT: iii) These entries will be added to the respective "default" files -- that is, they do NOT replace the default files. * i.e.; to the INITFILT.80, PUBURLS.IN, USERS.IN, ACCESS.IN, ALIASES.IN, REPSTRGS.IN, and VIRTUAL.IN files defined in the "default" INITFILT.80. * a "host specific" INITFILT.80 should ONLY contain parameters that can take host specific values (see INITFILT.DOC for the details) * Only entries pertaining to the appropriate port will be added. * Implicitily, a HOST// is appended before each of these entries. iv) Reminders: If you do NOT specify a HOST:, or if the "value" is empty, the section applies to the "default" host. If you do NOT specify a PORT:, the "section" applies to port 80 servers. If you specify an IP:, you MUST specify a HOST v) In NO CASE should an entry (in one of these auxillary files) contain a "HOST//" prefix, a .HOST "stem"!, or a host: action. vi) It is possible to have several sections apply to the same host & port. In fact, it is not a bad idea to have seperate entries when multiple representations may be used for the same address (such as internal clients using www2, and outsiders using www2.bigcorp.com) -- a) the first such section would define the various "host-specific" files, b) the remaining sections would only contain a HOST:, an IP:, and a DATADIR: entry (in other words, the same information contained in an INITFILT.80 HOSTS. parameter). vii) Since blank lines delimit sections; do NOT include blank lines between entries (within a section). However, you can include comment lines (that begin with ;) viii) ACCESS refers to ACCESS.IN equivalents. ix) The COUNTER_DIR is used by COUNTER.RXX. This DOES require that you update to ver 1.3d (or above) of COUNTER.RXX. x) The RECORD_ALL_FILE is used to record counts of all hits (on a selector specific basis). Caution: if you specify any host-specific count files, then you must set RECORD_CACHE_LINES=0 (in INIT_STA.80). Example: (the indentations are for readabilty, as is the purposely sloppy use of lower case): host: ZOO ip: www.zoo.org datadir: d:\zoo\htmls RECORDALL: D:\ZOO\COUNTERS\RECALL.CNT host: ZOO ALIAS: ZOO\ALIASES.IN ACCESS: ZOO\ACCESS1.CTL host:store IP: 121.22.5.3 port:8080 datadir: d:\storewww users: D:\STORESITE\PRIVATE\USERS.1 initfilt: d:\storesite\moreinit.80 hit_counter: d:\storesite\hitcounts.cnt HOST: USERS: MOREUSER.IN ; do NOT specify a DATADIR or a HOST for the "default host" virtual: VIRTUAL2.IN HOST:WWW2 IP: WWW2 DATADIR: *: WWW2INIS\ ; since datadir: is empty, use the goserve datadir directory HOST: $WWW3 ATTRIBS: F:\GUEST\WWW3\ATTRIBS.W3 .end of document