1 Jan 2000. Daniel Hellerstein (danielh@crosslink.net) sreLite -- a "lite" variant of the SRE-http www server Abstract: sreLite ver 1.06 is an http www server for OS/2. It is freeware, and requires the free GoServe IBM Internet Server. sreLite is a subset of the SRE-http web server. Contents: I. Introduction II. Installation II.a. List of files. III. Configuration III.a. Description of Configuration Parameters IV. Assigning client privileges V. Definitions VI. Disclaimer ================================================= I. Introduction sreLite is the "lite" version of the SRE-http web server. It supports many of the most common web server features, and on fairly simple sites will be quicker then the full-featured SRE-http www server. Compared to the full version of SRE-http, the primary disadvantages of sreLite are: a) sreLite supports a minimal set of the http/1.1 standard -- several of the fancier features (such as gzip encoding) are not supported. A philosophical aside: Perhaps the greatest advantage conferred by http/1.1 is the enhancement of proxy-caching that an "all http/1.1" web would provide. Thus, although use of small & quick http/1.0 servers might speed up response time as observed at your server, in the long run such a strategy might cut true response time (the wait a client actually endures), since your server will be handling requests that a proxy could have taken care of. However, if you are serving lots of cgi-bin scripts, or are serving lots of "limited access" resources, then caching will often be suppressed. In such cases, the proxy-caching capabilities of an http/1.1 server are less important. b) sreLite becomes cumbersome to configure, and looses efficiency, when you have a complicated set of redirections, aliases, and access controls. c) Many of the fancier SRE-http features are NOT supported; such as: GZIP encoding, ssi caching, the "SRE-http" ssi options, server-side imagemaps, seperate browser and referer log files, elaborate multiple-hosts, MD5 hash tags, the various pre-filter and pre-reply hooks, built-in support for file uploads, et al. If you find that you would benefit from such features, please consider SRE-http (check it out at http://www.srehttp.org) However, many of the most common features you'ld want in a web server are supported, including: * On-line configuration * Support for both "basic" and "digest" authentication * Access controls on a resource specific basis. In other words, some portions of your web site can be open to the public, some portion can be open to all registered users, and other portions can be open to specified subsets of these registered users. * A limited form of multi-hosting * A directory specific "default" document can be returned when the request does not specify a filename. * Support for the ~shorthand for a "users-home" directory. * Directory-specific customized "404" responses can be sent. * Optional automatic directory listing when no "default" document can be found. * A "list of best matches" can be sent instead of a "404" response * GET, POST, and HEAD are supported * Full support for cgi-bin/1.1, with support for PERL scripts. * Support for most sre-http addons. * Range requests are understood * Server side imagemaps are supported (using an included addon) * Support for most of the NCSA server side include options, including #EXEC * Requests can be recorded in a common log file, or by your own custom procedure. ================================================= II. Installation The simplest and fastest way to install sreLite is to use the sreLite INSTALL.CMD program. If you don't trust such things, the following lists the steps you should follow. In either case: 1) we assume you have not installed SRE-http, but HAVE installed GoServe (note that sreLite requires GoServe 2.52). 2) you should unzip srelite.zip to an empty temporary directory. Note to users of SRE-http: If you HAVE installed SRE-http, you can skip many of the following steps. In particular, you can skip steps b through g. a) Unzip SRELITE.ZIP to an empty directory b) Create the following subdirectories under the GoServe working directory DATA/ -- for USERS.IN and other SRE-http data files CGI-BIN/ -- for your CGI-BIN scripts TEMP/ -- temporary files are put here ADDON/ -- for your SRE-http addons. c) Create a the following subdirectories under your GoServe data directory: TEMP/ -- word space for scripts and addons SAMPLES/ -- for sample documents IMGS/ -- for sample images d) Copy the following to your GoServe working directory: SRELITE.80, SRELITE0.CMD, SRELITE1.RXX, SRELITE2.RXX, POSTFILT.CMD, SRELITEP.RXL, SRELITE.INI, MTCHFILE.CMD, and NOTFOUND.SHT. You might also want to copy SRELITE.DOC to the GoServe working directory, but that's not required. Basically, you can copy SRELITE*.* to your GoServe working directory, though you don't need to copy SRELITE.ZIP. e) Copy REXXLIB.DLL to your GoServe working directory, or to a directory in your LIBPATH (say, C:\OS2\DLL). f) Optional -- copy some demo scripts and documents: Copy INDEX.SHT and CONFIGU.HTM to your GoServe data directory. Copy TEST-CGI.CMD, XCOUNT.CMD, and JCOUNT.CMD to the CGI-BIN/ subdirectory (of the GoServe working directory). Copy OPTSCFGL.CMD, USERCFGL.CMD STATUSL.CMD and MAPIMAGE.CMD to the ADDON/ subdirectory Copy TSTHTTPD.SHT, SAMPMAP.HTM, SAMPMAP.GIF, and SAMPMAP.MAP to the SAMPLES/ subdirectory (of the GoServe data directory). Copy SREHTTP.GIF and SREFWEB.GIF to the IMGS/ subdirectory (of the GoServe data directory) g) Copy USERS.IN to the DATA/ subdirectory. ** Caution: SKIP this step if you already have a working version of ** ** USERS.IN (say, if you are currently using SRE-http). ** h) Optional: Using your favorite text editor, edit the parameters in SRELITE.INI. This is not strictly required -- using the defaults, sreLite will run as an open access web server. Advanced users can also edit parameters in SRELITE0.CMD, but most users needn't bother (the defaults are recommended). The parameters in SRELITE0.CMD are: addon_dir: location of addon directory cgi_bin_dir: location of cgi-bin directory common_log_file: name of common log file digest_auth: enable digest authentication empty_path_ok: how to deal with the cgi-bin path_translated variable enable_http11: enable sreLite's http/1.1 mode interpret_types: enable PERL (and other non-REXX,non-EXE) CGI-BIN scripts proxy_cache: enable proxies to cache this site's resources suppress_varstore: suppress the SRE-http daemon facility tempdata_dir: temporary data directory tempfile_dir: temporary html files directory user_file: user input file If you want to use PERL scripts, you should look at the INTERPRET_TYPES parameter in SRELITE0.CMD. If you are running a controlled access web site, you'll also want to edit USERS.IN, the "username/password" file. Alternatively, you can use the CONFIGU.HTM "configuration" tool (which is available from INDEX.SHT, the sample home page). i) Optional: If you are running a multiple host server, you should set the HOSTS. parameters in SRELITE.80 j) Run GoServe using SRELITE.80 as your filter. That's it; you can now test it out, by pointing it at your home page. Or, you can check out some sreLite features by pointing your browser at: /TSTHTTPD.SHT (assuming you put it in your root directory) Examples of the NCSA server-side includes (and a few "SRE-http REPLACE" SSIs). /STATUSL? A simple "server status" sreLite addon (also can be used to reset & view parameters) /CGI-BIN/TEST-CGI A simple cgi-bin script (that returns the state of CGI-BIN variables) /SAMPLES/SAMPMAP.HTM Demo of server side image maps. Notes: * If you are using Object Rexx (under OS/2 4.0), you will NOT be able to use sreLite * sreLite requires GoServe, ver 2.52, IBM EWS Internet Server. GoServe is free. You can get it from: http://www2.hursley.ibm.com/goserve. * if you are using OS/2 Warp Server; you may need to install the latest fix packs * If you are using Warp 4.0, you should be using the latest fix packs for TCP/IP (INETVER should report 4.02t or above). You can get the latest TCP/IP fix-packs from: ftp://ftp.software.ibm.com/ps/products/mpts/fixes/english-us/ or you can try http://duanec.indelible-blue.com/fixes/latestwarp4.html * sreLite comes with the standard freeware dislaimer; in a nutshell, use it at your own risk (see the bottom of this document for a more complete disclaimer). That said, we want to know when you run into problems, and are always willing to help. * sreLite uses the REXXLIB library, which is included. REXXLIB is commercial software for which we obtained an unlimited distribution licence. Thus, you can legally use REXXLIB with sreLite (please see the disclaimer for further details). * Questions, comments, bug reports? Please contact: Daniel Hellerstein at danielh@econ.ag.gov Or visit the SRE-http website at: http://www.srehttp.org II.a File List The following files are packaged with sreLite: INDEX.SHT -- A very simple home page, with links to sreLite examples JCOUNT.CMD -- Sample of an #EXECutable "server side include" (for displaying a textual hit count) MAPIMAGE.CMD -- SRE-http addon for processing server-side image maps NOTFOUND.SHT -- Sample of a "not found" response file. MTCHFILE.CMD -- A "return closest matches" procedure, used for 404 responses POSTFILT.CMD -- A sample of a post-filter procedure. REXXLIB.DLL -- the REXXLIB procedure library. SAMPMAP.HTM -- sample of how to use a server side image map SAMPMAP.MAP -- a sample of a "NCSA-style" server side image map SAMPMAP.GIF, and SREFWEB.GIF -- Some sre-http gifs. SRELITE.DOC -- this document SRELITE.80 -- the "main filter program". This contains parameters that you can modify, using your favorite text editor (see section III for descriptions of these parameters). SRELITE0.CMD -- the sreLite initialization procedure. This contains a few advanced parameters SRELITE.INI -- initialization parameters. SRELITE1.RXX -- the "username" daemon SRELITE2.RXX -- the "variable storage" daemon SRELITEP.RXL -- the sreLite macrospace library. This is a subset of the SRE-http (ver 1.3c) macrospace library. SREFILTR.GIF -- the unofficial SRE-http (and sreLite) logo. STATUSL.CMD -- Sample SRE-http addon CONFIGU.HTM -- Front-end to on-line configurator OPTSCFGL.CMD -- On-line configurator (SRELITE.INI) USERCFGL.CMD -- On-line configurator (USERS.IN) TEST-CGI.CMD -- A sample cgi-bin script. TSTHTTPD.SHT -- HTML document that contains NCSA-style server side includes. TSTHTTPD.SHT also demonstrates the SRE-http "REPLACE" server side includes (that are supported by SRE-lite). USERS,IN -- sample USERS.IN file. ================================================= III. Configuration Configuration of sreLite requires modifying the SRELITE.INI configuration file, and the USERS.IN "username" database. Both of these are text files which can be modified using your favorite text editor. If you are running a multiple-host server, you also have to edit the HOSTS. parameters in SRELITE.80. Alternatively, you can modiffy them "on-line" by using the USERCFGL.CMD and OPTSCFGL.CMD addons -- both of which can be accesses via CONFIGU.HTM. To do this, you must have SUPERUSER privileges (i.e.; use the username and password you provided when the INSTALL program asked you to specify a SUPERUSER). Notes: * Several advanced parameters (that rarely need to be changed) are set in SRELITE0.CMD. See SRELITE0.CMD for further discussion of these advanced parameters. * The HOSTS. parameters (in SRELITE.80) are described in SRELITE.80 * If you are very security conscious, you can disable "remote" configuration by setting switches at the top of USERCFGL.CMD and OPTSCFGL.CMD (both of which are in your ADDON directory). These switches allow you to use CONFIGU.HTM only if your are running your browser on the server machine. * For a description of the USER.IN file, see section IV. The parameters in SRELITE.INI are (with default values shown): accept_range=1 always_get_privs=1 aliases.0=0 check_slashs=1 default_requires='0' defaults='index.htm index.sht !DIR ' dir_exclusion='PASSWORD.* PASSWD.* USERS.* USER.* HTACCESS* \PRIVATE \SYSTEM ' inhouseips.0=0 logit=1 not_found_file='notfound.sht' post_filter=0 realm='Our site' sel_requires.0=0 ssi_extensions='SHTML SHT ' superusers='0' verbose=1 Note that inhouseips.0, sel_requires.0, and aliases.0 are used to indicate the number of inhouseips.n, sel_requires.n, and aliases.n entries. Thus, a working SRELITE.INI file may have several (or several dozen) of these "stem" variables specified. For most sites, the most important parameters to think about changing are: sel_requires., aliases., superusers, and default_requires. III.a. Description of Configuration Parameters The following descriptions of these parameters (in rough alphabetical order) assume you have some familiarity with SRE-http terminology. Newcomers to the SRE-http world should first read the "definititions and descriptions" in section V below! Note that configuration parameters, and the USERS.IN file, are read when GoServe/sreLite first starts. You can modify these parameters on the fly by: a) editing SRELITE.INI, and/or USERS.IN b) issuing, as a client with SUPERUSER privileges, a /!RESET command. or issue a /STATUSL? command, and hit the "reset privileges" link at the bottom of the screen. c) Parameter reset occurs immediately, username/password reset may take a few seconds. Parameters in SRELITE0.CMD can NOT be reset on the fly; to change them, you must edit SRELITE0.CMD, and then restart GoServe. Parameters set in SRELITE.80 (the HOSTS. parameters) will be reread for every request. ACCEPT_RANGE:Enable range requests. When enabled, sreLite will look for range headers, and return the appropriate range of document. sreLite will also send Accept: range headers on most responses. 0=disable 1= Enable Example: accept_range=1 ALIASES. : Aliasing rules. Aliasing is used for specifying virtual directories, and for "internal" and "external" redirection. Selectors (after all access controls have been completed) are compared to the "oldselector' field, and the "best" match is used (* can be used as a wildcard). The syntax of each entry is: aliases.n ='oldselector newselector ' Both the oldselector and newselector can contain * wildcards. Notes: * To redirect, newselector should start with http:// * * wildcards in the newselector are used as "* replacement" -- portions of the oldselector, that wildcard match the requested selector, are copied to the respective * location in the newselector. * As with sel_requires, aliases.0 is the number of aliases. * Instead of a "selector", you can specify a fully qualified file name, or a fully qualified directory, as the newselector. * To specify a "virtual directory", use a fully qualified directory, (that ends with an "/*") as the newselector. * if n>aliases.0, aliases.n is ignored * sreLite is shipped with two aliases that allow server-side image maps to be processed by the MAPIMAGE addon. * On a multi-host sytem, you MUST preface the "oldselector" with the host_Nickname (defined in srelite.80), followed by a //. Only entries that contain a matching host_nickname// preface will be used for requests to a host defined with a HOSTS. parameter (in srelite.80). Examples: aliases.0=7 aliases.1='/wow /wow/index.htm' aliases.2='/gone/* /dog/gone/*' aliases.3='/gone* /dog/gone*' aliases.4='/hersite/ * http://www.hersite.org/*' aliases.5='/jokes/* e:\funnies\*' aliases.6='/imgs http://danielh/imgs/' aliases.7='www2//new/* /files/current/* ' ALWAYS_GET_PRIVS: Always get username from client ALWAYS_GET_PRIVS controls how aggressive sreLite is about asking for (or looking up) a username/password. 0 = Ask only if necessary (if access would be denied otherwise) 1 = Check for usename (and associated privileges) whenever possible 2 = Similar to 1, but if no username was provided (in an Authorizaton: request header), ask the client to provide one. This would be done EVEN when the client would otherwise be granted access. Example: always_get_privs=1 CHECK_SLASHES: Suppress / conversions. If you are careful about your alias and sel_requires entries, you can suppress the "automatic conversion of / and \". This will save a fraction of a second. 0 : suppress automatic conversion. 1 :enable "automatic conversion. Note that "automatic conversion" includes "checking for a leading /" Example: check_slashs=1 DEFAULTS: list of default names to use when request ends with a / DEFAULTS list documents to return when a directory-type of entry (one that ends with a /) is requested. This includes the "home page", as would be sent on a request to http://foo.bar.net. DEFAULTS should be spaced delimited set of filenames. The first filename in the list is tried first, and if no such file exists (in the appropriate directory), latter names are tried. Notes: * DEFAULTS are used AFTER aliasing. * a !DIR item means "display a linked directory listing". If used, !DIR should always be the last item in the list Example: defaults='index.htm index.sht !DIR ' DEFAULT_REQUIRES: Default required priviliges DEFAULT_REQUIRES sets the required privilge when the does not match any of the sel_required. entries, (such as when sel_required.0=0). Suggested values are: '*' = Any valid user (with a username/password) can obtain this selector '0' = NO access control, anyone can obtain this selector 'SUPERUSER' = superusers only. Example: DEFAULT_REQUIRES='*' DIR_EXCLUSIONS: Directory exclusion list. DIR_EXCLUSIONS is used when a !DIR item (in the DEFAULTS) is activated. DIR_EXCLUSIONS should be a space delimited list of file and subdirectory patterns (which may contain wildcards). Filenames that match a "filename" entry in this list will not be displayed. Subdirectory names that match "subdirectory" entry in this list will not be displayed. Notes: * do NOT specify path information (these refer to files in the "requested" directory). * to define a subdirectory entry, start the item with a / Example: dir_exclusion='PASSWD.* USER*.* .HTACCESS* /PRIVATE /SYSTEM ' HOME_DIR: The users-home directory replacement for ~ The value of HOME_DIR is used whenever a ~ is seen in a request. Example: HOME_DIR='USERS/' ADVANCED OPTION: Specifying User Subdirectories In many cases, you may wish clients to have access to particular subdirectories of your "Users" directories. For example, all "students" may have space on the server machine, some of which is used for web, and some for "personal" purposes. The goal is to give clients direct access to the "web" related directories but not to the "personal" directories. This can be achieved by including a $ in the HOME_DIR parameter. Specifically, the $ is replaced by the substring between the ~ and the first / following the ~. For example:, If the HOME_DIR=USERS/$/WWW and the request selector is /~GERALD/RESUME.HTM Then SRE-http will use: /USERS/GERALD/WWW/RESUME.HTM Summarizing, given a $ in the HOME_DIR. 1) SRE-http reads the substring (of the request selector) between ~ and the first / following the ~ (i.e.; GERALD) 2) The substring is deleted from the request selector 3) The $ in the HOME_DIR is replaced with this substring (from step 1) 4) The ~ in the modified request selector (from step 2) is replaced with the modified HOME_DIR (from step 3) Note: This ~ replacement occurs AFTER checking SEL_REQUIRES, but before alias checking. Thus, it is possible to map a subset of the "home" directories (under the HOME_DIR) to virtual directories. HOSTS. Define hosts on a multiple-host server Use the HOSTS. variables in SRELITE.80 to define multiple hosts. Note: HOSTS are ALWAYS defined by the HOST: request header sent by a browser HOSTS.0 should be the number of host definitions. Each definition should have the form: hosts.n = 'IP_address, host_nickname, default_dir' where IP_Address : an ip address, or alias, as defined by a HOST: request header host_nickname: an 8 or fewer character internal name for this host default_dir: the default data directory to use for request to this host Example: hosts.0=2 hosts.1='www2.oursite.org, www2, e:\www2' hosts.2='insiders, internal, f:\work1\new' Note that hosts.2 is meant for urls that originate "in house" INHOUSEIPS: Automatically grant client priviliges by IP address. You can automatically grant client privileges to a sets of IP addresses. Notes: * As with sel_requires, inhousesips.0 is the number of aliases. * The IP address MUST be numeric, and can contain * wildcards * You can append a list of additional client privileges after the ip address. Note that matches always get an INHOUSE privilege. * if n>inhouseips.0, inhouesips.n is ignored Examples: inhouseips.0=0 inhouseips.1='* ME' LOGIT: Record entries in a common log file. LOGIT controls how much information to write to the common log file 0 = do NOT record requess 1 = record using a short format (no ?string, no http/1.x) 2 = record using a long format (the entire request string) 3 = same as 2, and also record User-Agent and Refer: information. Notes: * LOGIT can be overridden by a "do_log" item in SEL_REQUIRES. entry. * The add_hostnickname, in SRELITE.80, also effects the format of the commonlog file Example: logit=1 NOT_FOUND_FILE: A 404 response file NOT_FOUND_FILE, if not equal to 0 or '', is the name of a file. This file will be used instead of the generic 404 "not found" response. Do NOT include a path--sreLite will use a file of this name in the requested-files "own directory", or in the GoServe directory (if not available in the own directory). If this file ends with one of the ssi_extensions, server side includes will be attempted. To suppress this (and use a generic message), set =0 Example: not_found_file='notfound.sht' Note: notfound.sht, that is shipped with sreLite, is an example of a simple "not found" response file. SPECIAL FEATURE: If you specify not_found_file='!procname', then sreLite will call procname as an external procedure. This procedure should construct a properly specified html document, and return it (as a string variable) -- sreLite will then transfer this response to the client (as a text/html mime type). An example of this is MTCHFILE.CMD -- MTCHFILE.CMD will look for "similar" file names in the requested directory, and return a linked list to the best matches. For details on what arguments are passed, please see MTCHFILE.CMD. Examples: not_found_file=0 not_found_file='notfound.sht' not_found_file='!mtchfile.cmd' POST_FILTER: A procedure to call after responding to a request After the request has been responded to, you can call a special "post-filter" procedure. This post-filter procedure can be used for logging (say, as a substitute for the commmon log file), or for other purposes. 0 = no post filter procname = name of an external procedure that sreLite will call -- this should be the name of a .CMD file located in the GoServe working directory. The post-filter procedure will be called with the following variables: request,source,sel,clientname,user,afile,rcode Where Request: the GoServe "request" variable Source: the GoServe "source" variable Sel: the GoServe "selector" ClientName: client's name User : client's sreLite username AFile : File returned to the client. This may be missing (as when a CGI-BIN script is requested) RCode: result code; the http response code followed by the # of bytes sent (i.e; "200 15125") Examples: post_filter=0 post_filter=POSTMAIL.CMD See the POSTFILT.CMD file for a simple example of a post-filter procedure. Note: the sreLite ignores whatever the post-filter procedure returns. REALM: Define a realm name Realm name, displayed on client's authorization screen Note: REALM can be overridden by a "arealm" item in SEL_REQUIRES. entry. Example: realm='Our site' SSI_EXTENSIONS: List of server side include extensions. SSI_EXTENSIONS is a space delimted list of extensions (without the leading period). A file (that a selector matches) that ends with any of these extensions will be processed for server side includes (SSIs) Example: ssi_extensions='SHTML SHT ' SUPERUSERS: Define a list of superuers. Space delimited list of "superuser" ip addresses. Must be numerical addresses; wildcards are NOT allowed Example: superusers=' ' SEL_REQUIRES. : Selector specific access requirements Selectors are compared to a set of SEL_REQUIRES. entries. The best match is used, where * can be used as a wildcard. Each entry should have the following syntax: sel_requires.n='a_selector priv_list , use_this_file , no_log, realm ' where: n = 1 ... sel_requires.0 a_selector = a candidate selector, which may contain * wildcards. The selector (requested by the client) is compared against each of these candidate selectors priv_list = a space delimited list of privileges. The client must have at least one of these privileges. There are two special privileges, that should always be used by themselves (with no other privileges) * = any privilege will do (i.e.;all client needs is a valid usernamd and password) 0 = no privileges required -- access to this is NOT controlled. quick_file= Optional (it MUST follow a comma). A fully qualified filename (that contain * wildcards). If specified, this file is immediately returned to the client (with possible wildcard substitutions). no_log = Optional (it must follow a comma). If 1, then do NOT log this request. realm = Optional realm name (it must follow a comma). This will be displayed on the client's authorization screen. Notes: * sel_requires.0 defines the # of entries (i.e.; sel_requires.0=4 * You CAN include (multiple) * wildcards * Use of a priv_list of "0" is akin to specifying a public_url in sre-http. * Use of a quick_file implies a priv_list of 0. In fact, it's even stronger -- NO further checks are done. Note that when quick_file is ONLY used for simple file transfer -- in particular, ssi is NOT attempted, and scripts are NOT processed. * sel_requires. are compared against original request string (before aliasing) * if n>sel_requires.0, public_url.n is ignored * an empty priv_list implies a priv_list of 0. * If no match occurs, then the value of default_requires is used. * On a multi-host sytem, you MUST preface the "a_selector" with the host_Nickname (defined in srelite.80), followed by a //. Only entries that contain a matching host_nickname// preface will be used for requests to a host defined with a HOSTS. parameter (in srelite.80). Examples: sel_requires.0=8 sel_requires.1='/* 0 ' sel_requires.2='/samples* * , , ,Sample Realm' sel_requires.3='/status.txt priv1 ' sel_requires.4='/imgs/* 0 , G:\www\imgs\* , 1 ' sel_requires.5='/imgs/ 0 ' sel_requires.6='/imgs 0 ' sel_requires.7='host2//samples* * ' sel_requires.8='host2//private INHOUSE ' VERBOSE: Status message. tatus message verbosity. 0 = few messages 1 = some messages 2 = more messages HINT: to view these status messages, you should get PMPRINTF.EXE from: http://www2.hursely.ibm.com/goserve/pmprtf.exe Example: VERBOSE=1 ================================================= IV. Controlling access on a selector specific basis sreLite's access controls are similar, but not exactly the same, as SRE-http. The basic notion is: a) every selector is associated with a set of "required-privileges". b) every client is granted a set of "client-privileges" c) For a client to have access to the resource pointed to by a selector, ONE of her-client privileges must appear in the list of required- privileges. Note that just one match is required, the client does NOT have to match all of the "required privileges" (perhaps the "required" in "required privileges" is a bit too stringent?) d) on a multi host system, a selector is also associated with a host Please note that the .HTACCESS method of access control (that uses .HTACCESS files located in directories) is NOT supported by sreLite. Required-privileges are assigned with the SEL_REQUIRES. (and the DEFAULT_REQUIRES) parameters. Client privileges are assigned using the SUPERUSERS and INHOUSEIPS. parameters, and using the USERS.IN file. The USERS.IN file (which should be in the DATA/ subdirectory of your GoServe working directory) contains a list of usernames, passwords, and client privileges. It is read by the "username" daemon of sreLite at startup. When sreLite needs to check the privileges of a client (given that the client provided a username and password), a special "username" daemon is called, which will a) check the Authorization: request for a username and password b) determine (by examining USERS.IN) if a valid username and password were provided c) if so, extract (from USERS.IN) the client privileges assigned to this username and password. (Actually, the daemon saves time by examining a locally cached version of USERS.IN) The syntax of an entry in USERS.IN is : username password priv_list where priv_list is an arbitrarily long space delimited list of client privileges. Notes: * a "required resource privilege" of * means : any privilege will match. Thus, a client who matches SUPERUSERS, one of the INHOUSEIPS., or has a valid username and password, will be allowed to access this resource. * a "required resource privilege" of 0 means : no privileges are required, this is a "public" resource. This is akin to defining a "public_url" in SRE-http. * a username of * means any user; and a password of * means "any password" * wildcarded usernames are checked after the non-wildcarded usernames * lines in USERS.IN that begin with a semi-colon are comments * comparision of resource and client privileges is case insensitive * clients who match the SUPERUSER are automatically given a SUPERUSER privilege, and are ALWAYS granted access to all resources * clients who match an INHOUSEIPS. are automatically granted an INHOUSE privilege. This is in addition to INHOUSEIPS. specific privileges. * clients with a valid username and password are always granted a USERS privilege (in addition to username specific privileges) * client privileges are cumulative -- username privileges will be added to INHOUSEIPS. privileges. (which might be added to a SUPERUSER privilege). * You can control the extent of "client privilege accumulation" by setting the ALWAYS_GET_PRIVS parameter * On multiple hosts system, be sure to specify the "host-nickname" when defining SEL_REQUIRES. and ALIASES. parameters. Example of a USERS.IN file: ; This is a sample USERS.IN file ; do NOT use commas in the privilege list! ; and, of course, lines that begin with a ; are comments, ; (and blank lines are ignored) OUTATOWN SHEP2 PRIV0 MASTER1 12ISIE6 SUPERUSER USER1 1USER priv1 priv2 ANONYMOUS * PUBLIC ================================================= V. Definitions The following sundry definitions and descriptions of sreLite (and http) concepts are listed in rough alphabetical order. CGI-BIN CGI (Common Gateway Interfact) - BIN is a standard by which server side ("gateway") programs can be invoked. It uses environment variables to pass data, as well as standard input and output. SRE-http supports CGI-BIN, using procedures adapted from the GoHTTP package. Although this support should permit use of many CGI-BIN scripts, the use of the "native" SRE-http interface (using REXX procesures that are passed information in the argument list) offers advantages to ambitous programmers Default Data Directory The Default Data Directory is the root directory of your web site -- it (and it's subdirectories) are the usual locations for your HTML documents, images, etc. By default, the GoServe Data Directory is used as the Default Data Directory. A simple example might help: ~ a request selector of MYFILES/PROJECT1/BIGTASK.HTM is recieved ~ your default data directory is E:\WWW then, SRE-http will look in E:\WWW\MYFILES\PROJECT1 for the BIGTASK.HTM file. Note: The GoServe data directory is set by GoServe's Options-Datadir tab.. Request selector When a client sends a request to a server, it contains three components: the http method, the selector, and the http protocol. For example: GET /FOO1/BAR.HTM HTTP/1.0 In this documentation, the term "request selector" (or just "selector") refers to this middle component, with leading / stripped, and character decoding performed. In the above example, the REQUEST SELECTOR would be FOO1/BAR.HTM. Note that if a GET HTTP method was used, the request selector may contain information following a ? (for example, SHOWINFO?DATABASE=PRICES&ITEM=APPLES . Selector-specific Selector-specific means "a piece of information specific to a request selector. In other words, this means that sreLitewill use the value of the request selector to find information (such as the required privileges). STEM. variables STEM variables are REXX's way of implementing arrays, and are used by sreLite to specify several sets of variables. A REXX STEM variable has the following syntax: name.tail=some_value where: name = the "stem" variable name tail = an "array" indictor. Typically, this will be an integer from 0 to infinity. (Technically speaking, the tail can be any string; but for sreLite purposes, assume that the tail is always an integer) some_value = a string, or numeric, value URL: Uniform Resource Locator. URL's are a scheme for specifying Internet resources using a single line of printable ASCII characters. A URL should contain a protocol, domain name, port number (optional), the location of the resource, and an (optional) option list (following a ?). In this documentation, the URL term connotes "a link coded into an HTML document". Upon selecting such a link, the client sends back a request string that contains the verb (the HTTP method), the request ôselectorõ , and the http protocol (typically, HTTP/1.0) Example:given a URL of HTTP://WWW.ECON.AG.GOV/CALC/CALC.HTM the resulting request selector would be CALC/CALC.HTM Wildcard matching Wildcard matching use the * as a wildcard character in a natural fashion. Examples: /JOE/* will match /JOE/FOO.HTM /JOAN/SRCH.HTM?* will match /JOAN/SRCH.HTM?search+me /JOAN/SRCH.HTM?* will NOT match /JOAN/SRCH.HTM (/JOAN/SRCH.HTM* will match BOTH these examples) /PETS/*INDEX.HTM will match /PETS/INDEX.HTM, /PETS/CAT/INDEX.HTM and /PETS/PUPPY/LAB/INDEX.HTM but will NOT match /PETS/CAT/PUREBRED.HTM Wildcard matching is used when examining SEL_REQUIRES., ALIASES., and INHOUSEIPS. Wildcard matching with substitution Wildcard matching with substitution is similar to wildcard matching. However, rather then being a "many to one" match, it is a "many to many" match. The basic rule is that both a "target" and a "replacement" should contain * characters. When a wildcard match between the target and a candidate occurs, the "covered portion of the candidate" is inserted into the "replacement". In other words, the * character in the replacement is deleted, and the "covered portion" is inserted. Example: ~ If the request selector is: PROJECT/JILLWORK.HTM ~ and there is an alias of: PROJECT/* /RESEARCH/ONGOING/* ~ the resulting match is: /RESEARCH/ONGOING/JILLWORK.HTM GoServe Working Directory The GoServe Working Directory in the directory containing GOSERVE.EXE (typically, \GOSERVE). It's set in the "working directory" item of the GoServe desktop object. Client The Client (sometimes referred to as the requester) is the individual requesting a URL -- where the URL may point to a file, or may invoke A CGI-BIN script or an SRE-http addon. Typically, the request was generated by someone running a Web Browser, and clicking on a link or submitting a FORM. ================================================= VI. Basic copyright and it's never our fault disclaimer: Copyright 1999 by Daniel Hellerstein. Permission to use this program for any purpose is hereby granted without fee, provided that the author's name not be used in advertising or publicity pertaining to distribution of the software without specific written prior permision. With some provisos, this includes the right to subset and reuse the code, with proper attribution. The provisos are several fold: 1) Portions of the code are adapted from other authors' work (these are noted where appropriate); you'll need to contact these other authors for appropriate permissions. 2) sreLiteuses serveral Quercus System's REXXLIB procedure library. The license for REXXLIB gives the author the right to distribute REXXLIB without charge. This right may NOT extend to redistributors. Please contact Quercus Systems for details. 3) We, the authors of SRE-http and any potenially affiliated institutions, disclaim any and all liability for damages due to the use, misuse, or failure of the product or subsets of the product. Furthermore you may also charge a reasonable re-distribution fee for sreLite; with the understanding that this does not remove the work from the public domain and that the above provisos remain in effect. THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE. sreLite was developed on the personal time of Daniel Hellerstein, and is not supported, approved, or in any way an official product of my employer (USDA/ERS).