5 January 2002 danielh@crosslink.net The SIMPLE filter for the SRE2002 Http Server This directory contains the SIMPLE filter for the SRE2002 ver 1.10 http server for OS/2. ---------------------------------------- Introduction SIMPLE, as it's name suggests, does not have a lot of bells and whisltes. But it does have a few, all of which are set by modifying user-configurable parameters in SIMPLE.RXX. For example: * alternative directories on a selector specific basis. * redirection * simple access controls * automatically add an Content-MD5 header Again, to set these features, you must modify SIMPLE.RXX -- there's plenty of documentation there to remind you of the hows and whats. Also included in this directory is FASTFILT.RXX -- a VERY simple (though slightly configurable) example of a SRE2002 "fast filter". See FASTFILT.RXX for the details. ---------------------------------------- Basic Parameters: Add_md5: add_md5=1 -- add a Content-MD5 header to all responses add_md5=0 -- do not add a Content-MD5 header to all responses AUDIT: 0 : do not write "log" information 1 : write info to the audit.log file 2 : write to audit file and pmprintf window, Example: AUDIT=2 DEFAULT: The default document == used if the request ends in a / This also includes the "empty" request. Examples of when DEFAULT is used: http://www.hello.org/ http://www.hello.org/files/june10/ Default should be a file name only (no path info). Note that the location of the home page, etc. is relative to the datadir (datadir is set in SRE2002.CFG). Thus, if the DataDir is d:\www, and default is index.htm, the a request to http://www.hello.org/ would yield d:\www\index.htm */ Example: default='index.html' FEATURES. : Used to specify selector specific features, such as alternate "base" directories, redirection, and access controls See below for the details. MIMETYPE. : Mime type mappings -- these modify the default mimetypes. These should be of the form: mimetype.!xxx='type/subtype' where xxx is an extension. For example: mimetype.!DOC='text/plain' mimetype.!ARJ='application/octet-stream' SCRIPT_ACCESS_LOCALONLY Limit access to scripts. If set equal to 1, then only clients running a browser on the same machine as the server (that is, only when the client's ip address is the same as the servers) will be allowed to run scripts Example: script_access_localonly=0 SCRIPT_DIR Scripts directory. This directory (relative to the "filter" directory) contains scripts. Scripts are invoked by placing a ! point as the first character of the URI (actually, the first character after the leading /). For example... if SCRIPT_DIR=SCRIPTS, then the SIMPLE\SCRIPTS\STATUS.CMD script can be invoked by using a URI of /!STATUS (the .CMD is optional). Example: script_dir='SCRIPTS' USE_IPNAME: Use IP name in AUDIT.LOG output (i.e.; use me.foobar.net instead of 121.225.12.5) 0 : use IP address (dotted numeric) 1 : use IP name Example: US_IPNAME=1 ---------------------------------------- The FEATURES. parameters FEATURES. is used to set a few simple access control and redirection options. FEATURES.0 should contain the number of "FEATURES." entries. The first "matching" entry is used -- where matching is based on a) abbreviation match of the selector and the FEATURE.nn entry b) optionally, a suffix match of the selector and the FEATURE.nn entry. Alternatively, you can require that FEATURE.nn be an exact match to the selector Notes: * By default, this SIMPLE filter assumes that all uri's refer to files that are relative to the "datadir" directory. You can change this with the !BASEDIR option. * Since the first match found is the one that is used -- THE ORDER OF ENTRY MATTERS!! * If FEATURES.0=0, or the request "selector" does not match any of the FEATURES. entries, the request is accepted (and assumed to refer to a file relative to the data directory) Features options are (for n=1 to FEATURES.0): * Required: FEATURES.n -- the "abbreviation match" * Optional: FEATURES.n.!SUFFIX -- A secondary check -- a suffix match FEATURES.n.!EXACT -- Exact match flag FEATURES.n.!BASEDIR -- specify the base directory FEATURES.n.!USERS -- access control, by username and password FEATURES.n.!PWDS -- access control, by username and password FEATURES.n.!REDIRECT -- redirect to this selector In greater detail: FEATURES.n If FEATURES.n is a case-insensitive abbreviation for the selector then this entry may be used (depending on the values of the .!EXACT .!SUFFIX options). FEATURES.n.!SUFFIX: In addition to the "prefix" specified in FEATURES.n, you can also specify a "suffix". For example, you may want to specify all .TXT files in a directory, but not .HTML files. For example: FEATURES.0=2 FEATURES.1='/mydir/' FEATURES.1.!SUFFIX='.DOC' FEATURES.2='/mydir/' FEATURES.2.!SUFFIX='.TXT' This means "only accept requests to the /MYDIR/ directory that are for files ending in .DOC or .TXT" FEATURES.n.!EXACT If equal to 1, forces an exact (case insensitive) match -- not an abbreviation match. Example: FEATURES.4='/' FEATURES.4.!EXACT=1 Means "accept the '/' selector, but not necessarily '/other_stuff'" FEATURES.n.!BASEDIR: Specify a base directory to use when determining the file corresponding to this selector. If FEATURES.n.!BASEDIR is not specified, the default (SRE2002) "datadir" directory is used. Example: FEATURES.10='/cartoons/' FEATURES.10.!BASEDIR='F:\FUNNIES\GRAPHIC\' Notes: * Be careful how you specify FEATURES.nn and FEATURES.nn.!BASEDIR -- / and \ characters are not added or removed. FEATURES.n.!REDIRECT: FEATURES.n.!REDIRECT is used to redirect a request to a different URI. The value of the "prefix" is replaced by FEATURES.n.!REDIRECT, and a 301 response is returned to the client. Example: FEATURES.7='/joe/' FEATURES.7.!REDIRECT='http://foo.bar/net/joesplace/' If the request is for /joe/index.htm, a 301 "redirect" to http://foo.bar.net/joesplace/index.htm will be returned to the client. Note that you should specify the full url, including the http://. FEATURES.n.!USERS and FEATURES.n.!PWDS You can use the .!USERS and .!PWDS option to control access to a resource. The value of FEATURES.n.!USERS should be a space delimited list of case insensitive username. The value of FEATURES.n.!PWDS should be a space delimited list of case insensitive passwords. The nth password is associated with the nth usename. Thus: There MUST be the same number of words in each !USERS and !PWDS entry. Example: FEATURES.3.!USERS='joe jill Cat' FEATURES.3.!PWDS='buz1 onthehill DogAWAY ' Hence, the "jill" username has a "onthehill" password (note that neither is case sensitive). Notes: * usernames and passwords must NOT contain spaces * if the request does not contain an Authorization header, a 401 (request for authorization) response is returned. * FEATURES.3.!USERS=' ' means "no access control" Examples: FEATURES.0=3 FEATURES.1='/manual/' FEATURES.1.!suffix='.DOC' FEATURES.1.!USERS='joe jill Cat ' FEATURES.1.!PWDS='buz1 onthehill DogAWAY ' FEATURES.2='/temp/' FEATURES.2.!basedir='f:\temp\' FEATURES.3='/site2/' FEATURES.3.!Redirect='http://www.site2.net/' ---------------------------------------- Sample Scripts The SIMPLE filter has the capability of running some "simple" scripts. These scripts are invoked by using a URI that starts with a !. For example: View Server status? Note the leading / -- that's to ensure that the browser doesn't add "directory" information to the request! Scripts should be placed in the SCRIPTS subdirectory of the SIMPLE directory (see the description of the SCRIPTS_DIR parameter). Thus, if the SCRIPTS_DIR is D:\SRE2002\SIMPLE\SCRIPTS, in the above example SIMPLE will use a file with the name D:\SRE2002\SIMPLE\SCRIPTS\STATUS.CMD. Note that if you do NOT have a .extension in the URI, a .CMD is assumed. Scripts are called as procedures, with two variables; params: everything following a ? in the URI idinfo: the "id_info". You can use this in calls to SRE_COMMAND, etc. Rather then go into great detail, we advise examination of the several samples scripts packaged with SRE2002.