15 November 1999.
Optimization hints, configuration information, and other commentaries
on SRE-http.
This file contains several sections discussing various aspects of
SRE-http (ver 1.3h)
1) Optimization hints: a discussion of ways of speeding up SRE-http
2) Configuration information: a complete description of all the SRE-http
intialization parameters: including the more important dynamic parameters
set in INITFILT.80, more obscure "static" parameters set in INIT_STA.80,
and even more obscure parameters in SREFMON.CMD.
3) Remote vs. local redirection: A discussion of the various methods
SRE-http uses to redirect files.
===========================================
SECTION 1. Performance hints
(a) The use of the server side include cache (SSI-Cache) is highly
recommended. However, for very dynamic documents (such as documents
that contain several INTERPRET and #EXEC keyphrases), it may
be more efficient to suppress caching of these files (you
can use the keyphrase for just such a purpose).
(b) Suppressing incorporation of server side includes (SSIs)
i) If you
1) set SSI_SHTML_ONLY='YES'
2) name html documents, that contain SSIs, with a .SHT or .SHTML
extension
Then
SRE-http will not attempt to process SSI's in .HTM or .HTML files
but WILL attemp to process SSI's in .SHT or .SHTML files.
This can save some processing time.
ii) If you are willing to NOT have SSIs, then set
NO_INCLUDE='YES'
(this saves more processing time, and it also makes
hints (a) and (b.i) totally irrelevant)
(c) Use the SREPROXY "alternative" filter. SREPROXY is a "simple proxy"
that can handle many requests recieved by your server. In particular,
SRE-http will identify "public, cachable, non-temporary" URLs can
be handled by SRE-Proxy. And since SRE-Proxy is much simpler then
the full filter, throughput is enhanced. Note that this involves
no loss in functionality -- when SREPROXY can not deal with a request,
it simply passes processing to the standard filter (SREFILTR).
Upgraders note: The GoServe cache should be used carefully -- it is
not http/1.1 compliant. In fact, when GoServe answers
a request from a cache, it claims to be a http/1.0
server!
These are not fatal problems, but they are not exactly
spec. Therefore, we recommend limited use of the
GoServe cache, with the "do not call filter" GoServe
option selected.
For more details on how to use the GoServe cache, see
the description of the CACHE* privilege in SREHTTP.HTM,
or in the shipped version of ACCESS.IN
Need speed, don't need features? Try the sreLite variant of sre-http!
(d) If you never check "access" info, or virtual directories,
set the access_file and virtual_file to " " (or see note e).
Note that in addition to access information, the access file contains
permissions and advanced options -- please read the default ACCESS.IN
file for further details.
(e) Use the NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER "permissions"
in the ACCESS_FILE to suppress unnecessary processing.
(f) If you have a choice, the ACCESS_FILE method is preferable to the
the HTACCESS access control method: HTACCESS it is not
implemented with quite the same attention to efficiency. Or,
use the NO_HTACCESS permission (in your ACCESS_FILE) whenever possible.
(g) On an otherwise access controlled site, you can use PUBLIC_URLS
to grant fast & easy access to "publically available" resources.
(h) Turn on the RECORD_ALL_FILE cache. This is useful ONLY if you
are recording all requests (i.e.; RECORD_OPTION='YES').
Turning on the cache will cause the RECORD_ALL_FILE to be cached
in memory, with disk-writes every 5 minutes. See the description
of RECORD_CACHE_LINES for details.
(i) If you don't need extensive auditing, set WRITE_LOGS=0
(j) It you don't need "dynamic privileges", set CHECK_ADD_PRIVS='NO'.
(k) Setting the TEMPDATA_DIR to be a RAM Disk can help.
(l) If you intend to use SRE-http macrospace procedures with daemons, or
in completely seperate processes (processes that are not under GoServe),
you should add the following line to your CONFIG.SYS file
SET SRE_LIBDIR=e:\goserve\lib
where "e:\goserve\lib" is the "lib" subdirectory of GoServe/SRE-http.
=============================
Section 2. Parameter descriptions
2a. Basic Description
The following parameters are in alphabetical order (by name of parameter).
Many of them can be editied with SRE-http's configurator, especially the
"intermediate mode" configurator. However, to changes several of
these parameters, you must "hand-edit" the INITFILT.80 file. In general, the
"hand-edit only" parameters are more obscure, and may never need to be changed.
"Power users" may wish to see section 2a (below) for a discussion of
variables contained in INIT_STA.80 and in the "even more obscure"
parameters contained in SREFMON.CMD.
2b. Miscellaneous Notes:
* The terms "variable" and "parameter" are used interchangeably.
* As of version 1.3d, INITFILT.80 and INIT_STA.80 will be
installed in the CFG\ subdirectory (of your goserve working
directory).
* In almost all cases the variables (aka parameters) are set to equal
strings, so if you are "hand editing" INITFILT.80, remember to put
single quotes (') around the stuff on the rhs of the = sign.
* When this document mentions "SEL-specific", it really means
"selector specific", where the selector is the slightly modified
middle portion of the request string sent by the client to the server.
For example, if the client requests a URL of:
http://your.server/animals/bear.jpg
her browser will issue a request string of:
GET /animals/bear.jpg http/1.0
and the selector would be
animals/bear.jpg
* The CFGSLIST.CFG file can be used to specify host and port specific
parameter files (to complemenet the public_url, alias, and other
paramter files. See USE_CFGS.DOC for the details.
2c. Notes on Host-specific parameters:
* Almost all of the parameters (that are set in INITFILT.80) may be "host
specific". The several that aren't are:
INTERPRET_TYPES, DISPLAY_ENV, KEEP_ADDONS., and HOSTS.
* Host specific stem variables should have the host nickname following
the number. For example: INHOUSEIPS.2.HOST1='151.222.55.1'
* Parameters set in INIT_STA.80 and in SREFMON.CMD (described in section 2a)
can NOT be host specific (they apply to all hosts).
* To specify a host-specific parameter, you append the "host nickname"
to the parameter name (see the HOSTS. variable for a discussion of
host nicknames).
For example, to set the CHECKLOG variable for the ZOO host,
CHECKLOG.ZOO='NO'
and for all other hosts:
CHECKLOG='ALWAYS'
where this non host-specific value (CHECKLOG='ALWAYS') is the
"generic" value, and will be used for hosts other then the "ZOO" host.
NOTE: as of ver 1.3d, we now encourage administrators to use a
"host and port specific" INITFILT.80 file (as specified
in the CFGLIST.CFG file), rather then using
varname.host_nickname entries in the "default" INITFILT.80
Please see USE_CFGS.DOC for more details.
* When a request to a host is recieved, SRE-http will attempt
to find the appropriate host-specific parameters. If a given
parameter does not have a host-specific value, the "generic"
(the value of the non host-specific parameter) is almost always
used instead.
The exceptions are: UNALLOWEDIPS., INHOUSEIPS., and PUBLIC_URLS
* For security reasons, for these three (sets of) parameters
the generic (non host-specific) values are NOT used as a default.
The astute reader may notice that the OWNERS variable is not
on this list of "exceptions". In other words, the
"generic" OWNER has SUPERUSER privileges for ALL hosts.
2d. Note on "hand edited" parameters:
* Currently, the "hand-edited" parameters (that can NOT be set with the
intermediate mode configurator) are:
ACCEPT_RANGE ADD_USER_NAME ADD_RESOURCE_NAME ADD_PRIVS_PREFIX
CHECK_ALIAS CONTENT_MD5
DELIM_1.n DELIM_2.n DISPLAY_ENV
HTACCESS_FILE INTERPRET_TYPES KEEP_ADDONS.n
MAX_POINTDIST NO_INCLUDE
NO_PROCESSING NO_INTERPRET_CODE PREFILTER_NAME POSTFILTER_NAME
REPLACE_RULES.n USE_STDOUT USER_LOGON_ENABLE VERBOSE
The EDITINIT.CMD utility can be used to modify the values of all
the parameters in INITFILT.80, including these "hand-edit" parameters.
2e. For Advanced users: Notes on "machine specific" entries.
If you are DNS-binding several IP addresses (that are served from several
seperate machines) to a single IP name; you might want to use a common set
of SRE-http program and configuration files (i.e.; on a LAN drive). This can
work well, but there are few directories and files that should NOT be shared.
In particular, the TEMPDATA_DIR should be "machine specific". Other parameters
that probably should be machine specific are the RECORD_ALL_FILE and the
COUNTER_FILE.
To specify such machine-specific values, you can insert a $MACHINE_ID prefix
to each line in INITFILT.80. For example:
tempdata_dir='S:\GOSERVE\TEMP'
$COW1 tempdata_dir='S:\COW1\TEMP'
$HORSE9 tempdata_dir='S:\HORSE8\TEMP'
the "COW1" machine will use S:\COW1\TEMP, "HORSE9" will use S:\HORSE8\TEMP,
and other machines will use S:\GOSERVE\TEMP.
The value of the $machine_id (i.e.; COW1 and HORSE9) is read from the
MACHINE_ID_SRE OS/2 environment variable. That is, when an instance of
SRE-http starts up, it will check its "own" OS/2 environment
for a MACHINE_ID_SRE variable.
Notes:
** The MACHINE_ID_SRE variable must be set BEFORE starting GoServe --
ideally, you should set it in your CONFIG.SYS file.
** For all variables, SRE-http uses the "last" relevant entry in
INITFILT.80. That's why the above example has the "generic" entry
(tempdata_dir='S:\GOSERVE\TEMP') first -- this causes generic entries
to be used for all "machine_ids" (unless pecifically overwritten in a
latter entry).
** Although SRE-http will well in a DNS-binding environment, please be
aware that certain features will be undependable, especially features
that depend on daemons that keep track of dynamic events. In particular,
various "hit count suppression" tricks (for not-augmenting a hit
counter when a client repeats a request) may not work (since
some of them use a machine specific daemon to store results).
2f. Summary of parameters
--- Parameters in INITFILT.80
ACCEPT_RANGE: Return only specified range of the request file
ACCESS_FAIL_FILE: File to return when sel-specific access is denied
ADD_USER_NAME: Add clients "logon name" to the list of client privileges
ADD_RESOURCE_NAME: Add request "action" to the list of resource privileges
ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic" privileges
ALLOW_ACCESS : Enable sel-specific access controls
AUTO_HEADER: Automatic generation of response headers from elements.
AUTO_NAME : Resolving requests for directories (that end with /)
CHECK_ADD_PRIVS: Enable checking for "dynamic privileges"
CHECK_ALIAS: Enable alias checking
CHECKLOG: When and how to check for "logon rights".
CONTENT_MD5 : Enable creation of Content-MD5 header
DEFAULT: The "default" (home) page.
DIR_EXCLUSION: Files and subdirectories that !DIR should exclude
DIR_ACCESS and DIR_ACCESS_PRIVS: Supress !DIR display of selected files & dirs
DIR_OPTIONS: Set the !DIR display options
DISPLAY_ENV: write "SRE-http" environment variables to PMPRINTF window
DELIM. : delimiters for SSI keyphrases
DNS_CHECK: Force DNS check before allowing access
DO_HTACCESS: Controls whether the HTACCESS method is used
FIX_EXPIRE: Add an offset to the Expires automatic response header
HEADERS and FOOTERS: Automatically added to all "SSI-enabled" HTML documents
HOME_DIR: The "home directory" -- replaces ~
HOSTS.: Stem variable containing information on multiple hosts.
HIT_CACHE_LEN and HIT_CACHE_DURATION: Used to limit false hits.
HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS"
HOME_NAME: The colloquial name of your organization
HTACCESS_FILE : The name of the HTACCESS file.
INHOUSEIPS.: Stem variable containing IP address of "in-house" clients.
INHOUSE. and SUPERUSERS.: Special SSI "replacable" keywords
INHOUSE_PRIVS: Privileges for IN-HOUSE clients.
INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor
KEEP_ADDONS.n: List of addons to preload into macrospace
LOGON_FAIL_FILE: Response file to use if logon fails
MAX_POINTDIST : Used with the POINT type in mappable images.
NO_PROCESSING: Suppress server side processing
NO_INTERPRET_CODE: Suppress execution of "in-document" executables.
NO_INCLUDE: Suppress server side includes.
NOEXT_TYPE: Determine how to handle "no extension" request selectors.
NOT_FOUND_URL : A message, or response file, used if resource is not found
OPTION_HIT_LINE : Used to write OPTION info instead of counts
OWNERS: IP addresses to be assigned SUPERUSER privileges
PRE_FILTER: Enable use of user written pre-filters
PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s)
POST_FILTER: Enable use of user written post-filters
POSTFILTER_NAME: A series of procedures to call as post filters(s)
PUBLIC_PRIVS. Additional privileges for all clients
RECORD_OPTION: Select whether to record all allowed requests
REPLACE_RULES.: Stem variable containing text replacement rules for html files
SMTP_GATEWAY: Domain name of an SMTP server
SSI_CACHE_ON: enable the server side include cache
SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only
THE_REALM: "Realm" name to use in requests for username/password
UNALLOWEDIPS : Stem variable of "disallowed" IP addresses
UPLOAD_MAXSIZE: The maximum size (in Kbytes) allowed in a uploaded file
UPLOAD_MINFREE: Space that must remain after an upload
USE_STDOUT: Permit use of standard output in "INTERPRET" keyphrases
USER_LOGON_ENABLE: Enable use of a custom "user logon procedure"
USER_PRIVS: Additional privileges for registered users
VERBOSE: Controls verbosity of PMPRINTF comments
WEBMASTER: A variable use in SSIs
WRITE_LOGS: Enable the common-log, browser, and referer logs
In addition, a number of file and directory names can be modified by
changing entries in the INITFILT.80 file.
--- Parameters in INIT_STA.80
ALWAYS_CHECK_PRIVS: Flag to "check client privileges even if it is a public url"
BackupServerList: ip addresses of servers to distribute to under load
Ce_GZIP: Perform on-the-fly GZIP content-encoding
Cgi_Bin_Pieces: Send pieces of CGI-BIN output as they become available
Cgi_Post_Long_Get: Convert long GET requests to POST requests
Custom_Inits: Comma delimited list of "custom initialization procedures"
Default_encryption: The default encryption algorithim.
Delay_seconds: how frequently SRE-http checks for input file updates
Delta_encoding_enable: enable support for delta encoding
Delta_encoding_maxsize: maximum size of delta encoding cache
Digest_auth: Enable use of digest authentication
Dir_Cache_Size: size of the directory-listing cache
Dir_Cache_Duration: lifespan of entries in the directory-listing cache
Delay_Seconds: time delay for SRE-http to check parameter files for changes
Empty_Path_Ok: CGI-BIN control; what to do if no path_info recieved
Enable_Encryption: enable sre-http encryption
Event_Check: check events
Get_Decode_Cptions: Enable URL-decoding of options of GET requests
Hit_Superuser_Suppress: modify HIT_OWNER_SUPPRESS to check for SUPERUSERS
Ncsa_Ismap: substring(s) that signals "this is an NCSA mappable image request"
Cern_Ismap: substring(s) that signals "this is a CERN mappable image request"
Head_To_Get: tell addons that HEAD requests are GET
Key_Preface: optional preface for server side include keywords
Logon_Limit: maximum # of attempts, per minute per client
LoadThreshold: Used with BACKUPSERVERLIST (load at which transfer occurs)
Main_Server: An IP address for a "main server"
Message_Scramble: used by messages boxes to encode passwords and nonces
Never_Imagemaps: suppess check if this is an imagemap
Never_Publicurls: suppress checking for publicurls
No_Remote_Config: Suppress remote configuration
No_No_Record: Suppress the !NORECORD directive
Pre_Reply_Procedure: an external rexx program to call before sending response
PROXY_CACHE: Allow proxy caching (or SREPROXY caching)
Pmprintf_Opt: Output type for SRE-http's audit file
Put_No_Overwrite: Allow PUT method requests to overwrite existing files
Quick_Interp: Shorthand for INTERPRET FILE
Quick_Interp_Code: Shorthand for INTERPRET CODE
Quick_Replace: Shorthand for REPLACE
Range_at_end: Enable use of ;range_info (at end of selector)
Realm_1st_Priv: If need be, use first resource privilege as the realm
Record_Cache_lines: Size of RECORD_ALL_FILE cache
Sem_Maxwait: waiting time till threads check their queue
Ssi_Extensions: extensions for which the ssi_shtml_only parameter applies
Ssi_Cache_Size: size of the ssi-cache
Ssi_Cache_Duration: lifespan of entries in the ssi-cache
Ssi_Cache_Stamp: Type of "trigger" check (used with ssi-cache)
suppress_gzip_te: Suppress on-the-fly gzip
User_Logon_Proc: Name of an alternate "user logon procedure"
Wild_Sels_Ok: Use * in selectors to find best matching file
--- Parameters in SREFMON.CMD
Check_compliance: Check GoServe settings for http/1.1 "compliance"
Clear_Macrospace: Clear macrospace when GoServe is launched
Cfgs_Dir: Location of SRE-http configuration files
Doanyway_Loops: Re-read parameters after this many loops
Do_Cleanup: Cleanup orphaned cgi-bin temp files
logfile_maxsize: Maximum size of log files
MD5_Cache: Size of cache in the MD5 daemon
Mediatype_File_Always: Examine MEDIATYP.RXX only when no default match
No_DNS: Suppress DNS lookup of clientname's
No_superceding_realm: Suppress use of superceding realms
Storage_Daemons: Number of variable storage daemons to launch
Use_Dynamic_Lib: Select dynamic or static macrospace library
Use_Lib_Dir: Alternative location of macrospace library files
Pmprintf_Line_Length: Maximum line length to PMPRINTF
Pmprintf_Log_File: Name of SRE-http (PMPRINTF) log file
2g. Full description of parameters
************
ACCEPT_RANGE: Return only specified range of the request file
You can instruct SRE-http to respond to a "range:" request header. If such a
request header is present, SRE-http will extract the "byte
range" information, and return only this portion of the request file.
If accept_range=NO, this processing will not occur -- the entire file will
always be returned.
If accept_range=YES, this processing will occur. Of course, if there is
no range: header, then the entire file is returned.
Example: accept_range='YES'
(ACCEPT_RANGE can be host specific)
***********
ACCESS_FAIL_FILE
If SEL-specific access control is enabled (ALLOW_ACCESS=1),
and a client does not have sufficient privileges (i.e; none of
her client privileges appear in the resource privileges list
associated with the chosen selector) you can use the ACCESS_FAIL_FILE
as a response.
ACCESS_FAIL_FILE should be one of the following values:
-1 : Terse denial: Do NOT send a message, and do NOT ask for authorization.
Hint: this is useful when combined with "dynamic privileges"
0 : Do NOT use an access_fail_file -- just ask for authorization
1 : If a "SEL-specific" access file is specified (in ACCESS.IN or
ATTRIBS.CFG), use it. Otherwise, ask for authorization
filename.ext : The "default" file (fully qualified) to return when
the client does not have access privileges for this selector.
If a relative file name is used, the file is assumed
to be relative to the GoServe working directory.
Note that if a "SEL-specific" access-fail
file is specified (in ACCESS.IN), then this is NOT used
(the "SEL-specific" access-fail file is used instead)
As with the LOGON_FAIL_FILE, when the ACCESS_FAIL_FILE is an HTML document,
server side includes are NOT attempted. However, a few special
substitutions will occur (when the ACCESS_FAIL_FILE is an HTML document):
phrases are substituted with the request selector.
phrases are substituted with the servername.
phrases are substituted with the WEBMASTER variable.
phrases are substituted with a short description
of the reason for failure
phrases are substituted with a "forced" URL: which points
back to this resource, and forces an "ask authorization"
if access is denied.
It is HIGHLY recommended that a #LINK be included. Without such an
entry, the client will be unable to enter a new username/password, should
his first entry be misspelled (or if he had previously used a
different username/password for a different resource on the same realm
or your site).
PROVISO:
In some cases (such as when dynamic privileges are used to control
access to .GIF files), you may want to use an ACCESS_FAIL_FILE that does
not contain a #LINK.
Examples:
ACCESS_FAIL_FILE=0
ACCESS_FAIL_FILE='D:\goserve\accfail.htm'
Notes:
* When ACCESS_FAIL_FILE=0,
** the client will be re-sent an authorization request.
** SEL-specific access fail files are NOT used, even if one
is available.
* The #LINK entry uses a special form of SRE-http request selector.
The effect is to force SRE-http to request authorization should
the current username/password be incorrect; thereby avoiding an
annoying recursive trap.
* Reminder: the LOGON_FAIL_FILE is used when the client
fails a "generic" logon (that is, she does not have a valid
username and password). In contrast, the ACCESS_FAIL_FILE
(or the Sel-specific access fail file) is used when the client
does not have sufficient "client privileges".
(ACCESS_FAIL_FILE can be host-specific)
***********
ADD_USER_NAME: Controls whether a clients "logon name" should be
added to the list of client privileges.
YES: Add logon name to client privilege list
NO: Do not add logon name to client privilege list.
This can be a useful means of personallizing a client's
privilege list (of course, you could always enter his
name in the privilege list when setting up his
username/password entry).
Example:
ADD_USER_NAME='YES'
Usage Example:
if a username of ACIDER exists, with a client privileges of
HARD SOFT, then if ADD_USER_NAME='YES', an ACIDER client
privilege is added (yielding a client privilege list of
ACIDER HARD SOFT).
Notes:
* For INHOUSEIPS. entries, the "clientname" (the full, dotted, IP name) is
used as the "logon name".
* If you set ADD_USER_NAME=1, you should be careful that the usernames
you assign (in the USERS.IN file) do not conflict with the words used for
privileges. In particular, don't casually give someone a
username of SUPERUSER or INHOUSE.
***********
ADD_RESOURCE_NAME: Controls whether the "action" portion of the request
selector be included as a resource privilege.
YES: Add the action to the resource privilege list
NO: Do not add.
Similar to the ADD_USER_NAME, this can be a useful shortcut
in environments where highly specific access controls are
required.
CAUTION: When ADD_RESOURCE_NAME='YES', unmatched requests
will require clients to have a privilege matching
the "requested resource".
Example: ADD_RESOURCE_NAME='YES'
Notes:
* The "action" portion of a request selector is everything before the
first ? character (if no ? is found, the entire request selector is used).
* If ALLOW_ACCESS='YES', ADD_RESOURCE_NAME has no effect.
************
ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic"
client privileges.
As a security measure, when SRE-http adds "dynamic" privileges, it will
append the ADD_PRIVS_PREFIX. For example, if ADD_PRIVS_PREVIX='!', and
a keyphrase appears
in a requested document, the client will be granted a !SATURN
client-privilege (in this example, for 30 minutes).
The rationale is to prevent unscrupulous individuals, who may have been
granted a limited ability to post documents to "user" sub-directories,
from subverting access control with keyphrases of the form:
If such problems are not likely to occur, you may want to
set ADD_PRIVS_PREFIX=' '
Example:
ADD_PRIVS_PREFIX='!'
(ADD_PRIVS_PREVIX may be host specific)
************
ALLOW_ACCESS : Control access to server resources.
You can check "access privileges" for server resources (files, programs, etc.)
by setting the ALLOW_ACCESS variable.
YES : no access control (ACCESS.IN is not use to limit access)
INHOUSE : don't check in-house and superusers.
NO : don't check superusers.
Note that checking involves examination of privilege information
on a per-request-selector basis (using ACCESS.IN).
Note that ACCESS.IN (also known as the ACCESS_FILE) is used for:
1) Controlling server side include privileges and server side processing,
on a SEL-specific basis
2) Allowing caching of files that would normally not be cached
(If CHECKLOG<>"YES" or ALLOW_ACCES<>"YES", then caching is
suppressed).
3) Setting the default "realm" of the resource (see the THE_REALM variable)
4) Permitting PUT and DELETE methods to operate
5) Suppressing aliasing, virtual directory lookup, and "post-filtering"
6) Specifying an "advanced options" file
If you do not ever want SRE-http to check the access file,
just set access_file=" ". BUT if you do, the above features will not be
available!
Notes:
* The default name of the ACCESS_FILE is ACCESS.IN (in the DATA/
directory of GoServe's "working" directory).
* WARNING: If you set allow_access="NO", and access_file=" ", then
only SUPERUSERS will have access to your site!
(ALLOW_ACCESS can be host specific)
********
AUTO_HEADER. Automatic generation of response headers.
AUTO_HEADER is used to automatically generate response
headers, based on LINK and META HTTP-EQUIV elements in the
section of HTML documents.
3 values are supported:
NO : Do not generate these headers
HEAD : Generate headers for HEAD requests only
ALWAYS : Generate headers for HEAD and GET requests.
Note that this is only relevant for HTML files.
Also, when AUTO_HEADER occurs, the html file is parsed for header information
before server side includes are attempted -- that is, any server side
include in the of a document will NOT appear in the response
headers (but they will appear in the body of the response).
IN OTHER WORDS -- If you set AUTO_HEADER='ALWAYS', you should NOT use
SSI's portion of HTML documents
Example: AUTO_HEADER="HEAD"
Technical note: HTTP purists disapprove of the use of the "HEAD" value;
since HEAD method requests are supposed to return exactly the same
response headers as GET method requests.
(AUTO_HEADER can be host specific)
*********
AUTO_NAME : Resolving requests for directories.
AUTO_NAME is used to deal with non-specific requests that are NOT to the
root (the /) directory.
AUTO_NAME should contain a space delimited list of potential "directory
specific default names".
Several special names are supported:
*.HTM
or *.HTML : means "use the "directory" name, with .HTM or .HTML appended
!CREATE : Create a list of links, one for each file in the directory.
!CREATE* : Same as !CREATE, but include links to subdirectories
Example: AUTO_NAME=" *.HTM INDEX.HTM PAGE.HTM DESCRIBE.HTM !CREATE "
If a request for xxx/yyy/ (with optional ?abc after the final /) is
recieved, then
first, yyy.htm is looked for (in datadir/xxx/yyy)
second, INDEX.HTM (in datadir/xxx/yyy).
Then PAGE.HTM, and then, DESCRIBE.HTM are tried.
If all these fail, !CREATE signals "just display a list of the files
in this directory".
Note that if !CREATE were not included in this list, and
none of the requested files exist, a not_found message is returned.
Similarly, if !CREATE fails (if there is no such directory),
the not_found message is returned (see the description of NOT_FOUND_URL
for details).
Notes:
* AUTO_NAME is NOT used when request is to the root (to /) -- DEFAULT is
used!
* See NOEXT_TYPE for a discussion of how to deal with requests that
have neither an extension or a trailing / (i.e.; xxx/yyy).
* You can put a "pathed" name (using /, relative to the data directory)
This is one means of handling bad requests (but only if the request
ends in a /) -- just put the home page document in the auto_name list,
i.e.; auto_name=" * INDEX.HTM /HOMEPAGE.HTM "
* It is recommended that a !CREATE be placed at the end of the
AUTO_NAME list (since !CREATE is "always a match", assuming the
request points to a valid directory)
Example: AUTO_NAME=" * INDEX.HTM "
(AUTO_NAME can be host specific)
CAUTION: When using AUTO_NAME (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
****************
CE_GZIP: Default enabling of on-the-fly GZIP content-encoding
If CE_GZIP is enabled, and the client includes a GZIP
in an Accept-encoding header, then SRE-http will perform
a GZIP "content-encoding" on the resource. Using a
GZIP content-encoding can help save bandwidth.
CE_GZIP=1 to enable
CE_GZIP=0 to suppress
CE_GZIP=-1 Always disable (CE_GZIP advanced option can NOT override)
Notes:
* a CE_GZIP "advanced option" will override this default
* if a GZIP content-encoding has already been applied (and noted in a
content-encoding response header), then GZIP content-encoding will NOT
be performed. In particular, if content-negotiation yields a
GZIP content-encoded variant, then on-the-fly GZIP is NOT re-done
* If a GZIP content-encoding is done, then GZIP transfer encoding (as
enabled by the SUPPRESS_GZIP_ENCODING parameter) will NOT be
attempted.
* GZIP content-encoding is NOT attempted on !RANGE requests, or for
delta-encoded responses (when a "difference file" is returned)
**************
CHECK_ADD_PRIVS: Check for "dynamic privileges"
CHECK_ADD_PRIVS is used to instruct SRE-http to check for "additional,
dynamic privileges", and if they exist, add them to the client's "privilege"
list.
CHECK_ADD_PRIVS can take two values;
YES : Check for additional, dynamic privileges
NO: Do NOT check for additional, dynamic privileges
Example:
CHECK_ADD_PRIVS='NO'
Note:
* When CHECK_ADD_PRIVS='YES', an _ADDPRIV.DOC file is created in the
TEMPDATA_DIR directory (typically, \GOSERVE\TEMP).
* See ADDPRIVS.DOC for a detailed discussion of "additional, dynamic"
privileges.
(CHECK_ADD_PRIVS can be host specific)
***************
CHECK_ALIAS: Controls whether alias checking occurs.
SREFILTR can check all requests to see if they are aliases for some
other action.
Uses of aliases include:
* implementation of searchable indices
* "local" redirection -- useful as a means of assigning
proper document names to abbreviations
(say, to convert an request of OVERVU into OVERVIEW.HTM)
* "remote" document redirection -- often to a different
ip addreess
* transferring non-data directory files
Setting CHECK_ALIAS to --
NO suppresses this alias lookup
YES causes this lookup to be done for all requests
Example: CHECK_alias="YES"
(CHECK_ALIAS can be host specific)
************
CHECKLOG: When and how to check for "logon rights".
"Logon rights" refer to basic site access rights. These may
be (or may not) be used with SEL-specific access privileges (see ALLOW_ACCESS)
CHECKLOG can take four values:
1) NO -- never check (basic access granted to all clients)
3) YES or ALWAYS -- check on every request.
4) INHOUSE -- Access allowed only for INHOUSE and SUPERUSERS.
INHOUSE users are determined by occurence of a
INHOUSE in the client's 'privilege list', or
if the client has an IP address listed in the
INHOUSEIPS.n variables.
Note: if ALWAYS, YES or INHOUSE is selected, then GOSERVE will NOT cache GET
requests (the discussion of the ALLOW_ACCESS variable
describes an exception to this through the use of the CACHE
permission)
Example: checklog='NO'
(CHECKLOG can be host specific)
************
CONTENT_MD5 -- Enable creation of an Content-MD5 response header.
Content-MD5 response headers contain an "MD5 digest" of the body of the
response. Savvy clients can use this information to check the integrity
of transmission (however, it is not proof against tampering).
The MD5 digest is relatively compute intensive, hence general use of it may not
be recommended. In fact, you can use the "advanced options" file to enable the
creation of a content-md5 response header on a selector specific basis.
To disable, set CONTENT_MD5=0
If CONTENT_MD5 = 1, then a dynamic procedure is used to compute the MD5.
If CONTENT_MD5 = 2, then the MD5.EXE program (that comes with SRE-http
ver 1.3f and above) is used to compute the MD5 of files -- MD5.EXE seems
to be better behaved in circumstances that crash the MD5 procedure.
** NOTE: to use MD5.EXE you must have EMX installed! **
Examples:
CONTENT_MD5=1 ; enable creation of Content-MD5 response headers
CONTENT_MD5=2 ; enable creation of Content-MD5 response headers
; using the MD5.EXE program
CONTENT_MD5=0 ; do not create.
Note: as of 1.3h.0400.a, the occassional instability of CONTENT_MD5
generation seems to be solved. Hence, there is less reason
for using MD5.EXE.
**********
DEFAULT -- The "default" (home) page.
Use this when a default request (say, http://www.joe.com/ ) occurs.
Note: it is traditional, but by no means required, to use INDEX.HTML
as your default (as your "home page")
You can enter one, or several, different names. Each will be tried
in turn, if the file exists (relative to the possibly host specific
data directory), it will be used.
You can also use DEFAULT to redirect a request (using a 301 redirection),
say, for an IP Alias that has moved. To do this, just enter the full
URL -- be SURE to include the leading http://
Examples: default='index.htm index.html '
default.zoo='ourzoo.htm'
default.circus='http://silly.places.net/bigtop.htm'
Notes on examples:
* the "generic" DEFAULT dictates that Index.htm be used first;
if not found, index.html is then tried.
* you can NOT include * or ? in DEFAULT filenames.
* default.zoo defines the DEFAULT file for requests to the
ZOO host only.
* default.circus causes request to the default document of the circus
host to be redirected to silly.places.net
(DEFAULT can be host specific)
CAUTION: When using DEFAULT (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
**********
DIR_EXCLUSION: A list of files and subdirectories that the !DIR
(and other) directory listers should exclude.
SRE-http's !DIR special command (and GETAFILE addon) can be instructed
o suppress displaying certain files and subdirectories.
To do this, one uses the DIR_EXCLUSION parameter. DIR_EXCLUSION should
contain a space delimited list of files and subdirectories".
Example: dir_exclusion='Htaccess. /private describe.txt *.CNT '
Note that a / must preceed subdirectories (otherwise, the entry is
interpreted as a file name).
Notes:
* The !dir "special command" is used by the !CREATE option of AUTO_NAME.
* Subdirectories are assumed to be relative to the "requested directory",
and should only be one name deep.
That is, DIR_EXCLUSION='/personal/family ' is invalid.
* The wildcard character (*) can be used in file and directory names.
* For a further discussion of the !dir function, see DIR.DOC.
(DIR_EXCLUSION can be host specific)
**********
DIR_ACCESS and DIR_ACCESS_PRIVS
For extra security, you can use DIR_ACCESS to suppress display of
selected directories. DIR_ACCESS is checked by both the !DIR SRE-http
facility, and the GETAFILE addon.
DIR_ACCESS should contain a space delimited list of "selectors" that
!DIR (and GETAFILE) will limit access to.
More precisely, each item in DIR_ACCESS is compared against the
requested directory; and if any of them match (with wild cards allowed)
then the client must have one of the privileges listed in DIR_ACCESS_PRIVS
(or must be a SUPERUSER).
Example: DIR_ACCESS=' SYSTEM INFO/SECRETS */PRIVATE '
DIR_ACCESS_PRIVS='SPECIAL1 DIRPRIVS '
(DIR_ACCESS and DIR_ACCESS_PRIVS can be host specific)
**********
DIR_OPTIONS: Set the display options of the !dir function.
To control the display option of SRE-http's !dir special command, you should
modify the DIR_OPTIONS parameter. DIR_OPTIONS should contain a
space delimited list of parameters.
The allowed options are:
AUTO_DESCRIBE DESCRIBE DESC_LEN DATEFMT MULTI_SEND
NOSIZE NOTIME NODATE NOICON NOSORT NODIR NO_RECURSE_DIR
SIZEFMT SHOWPARENT TABLE TABLE_BORDER TIMEFMT
For a description of what these options do, see DIR.DOC.
Example: DIR_OPTIONS='notime auto_describe describe datefmt=u '
Notes:
* The !dir special command is used by the !CREATE option of AUTO_NAME.
(DIR_OPTIONS can be host specific)
**********
DISPLAY_ENV -- write "SRE-http" environment variables to PMPRINTF window
Use this as a debugging tool to display the values of the SRE-http
enviroment variables in the PMPRINTF window (and possibly the SREHTTP.LOG
file, if you set PMPRINTF_OPTIONS accordingly).
DISPLAY_ENV = 1 : The SRE-http environment variables (basically,
transforms of everything in INITFILT.80 and REPSTRGS.IN)
are written to the "PMPRINTF" window. This will occur
whenever the environment variables are refreshed
(say, when you change INITFILT.80).
otherwise : Do not write environment variables.
Example
DISPLAY_ENV=0
(DISPLAY_ENV is NOT host specific)
*************
DELIMITERS for KEYPHRASES
SREFILTR does "server side" includes by looking for keyphrases in your
HTML documents. A keyphrase is defined as: delim1 keyword keyvalue delim2.
Delim1 and Delim2 are strings (possibly 1 character) that signal the
location of the keyphrase. These delimiters should be odd,
yet easy to remember (and not likely to occur in your text).
ALTHOUGH WE DO NOT RECOMMEND IT, you can enter several sets of delimiters.
The default set is the HTML comment delimiters: '' .
If you use these, the raw document will not look too wierd should it be
accidentally sent to the client "as is").
For each set of delimiters, You MUST specify both the beginning (DELIM_1)
and end (DELIM_2) delimiter.
Examples:
delim_1.1=""
delim_1.2="{"
delim_2.2="}"
delim_1.3=0
delim_2.3=0
or, if just the ZOO host should recognize a second set of delimiters
delim_1.1=""
delim_1.2=0
delim_2.2=0
delim_1.1.zoo=""
delim_1.2.zoo='{'
delim_2.2.zoo='}'
delim_1.3.zoo=0
delim_2.3.zoo=0
Note: The most important reasons for NOT using several sets of delimiters:
* SSI-Caching will be turned OFF (regardless of value of SSI_CACHE_ON)
* SSI processing will be slower
But if you are willing to accept these performance disadvantages,
then the use of several delimiters should cause NO problems.
(DELIMS can be host specific)
*************************
DNS_CHECK: Force DNS check before access
As a security measure, you might want to look up the IP name of the
client (using the client's IP address and his DNS). If no name can
be found, logon is not allowed.
NO: do not check DNS for an IP name
YES: Force lookup of IP name before allowing access
Although this will provide some security agains "fake" IP addresses, it
will also slow down response time and disable caching by proxy servers.
Furthermore, many legitimate clients may not have "names" (say, if
they are using pooled IP addresses).
Example:
DNS_CHECK='NO'
(DNS_CHECK can be host specific)
********
DO_HTACCESS: Controls whether the HTACCESS method is used.
To provide compatability with HTTPD style servers (such as Don Meyer's
GOHTTP), SRE-http supports the HTACCESS method of access control
(see the description of HTACCESS_FILE in INITIFLT.DOC for details).
DO_HTACCESS can take two values
YES: Enable support of the HTACCESS access control method
NO: Do NOT support HTACCESS.
Example: DO_HTACCESS='YES'
When DO_HTACCESS='YES', SRE-http will check for an HTACCESS file
in the directory (and parent directories) of the requested file.
Note that this control is by "file name", rather then by request selector.
Details on HTACCESS files are in the description of the
HTACCESS_FILE variable.
Details concerning the use of the HTACCESS method can be found at:
http://w3.ag.uiuc.edu/DLM/GoHTTP/htaccess.html
(DO_HTACCESS can be host specific).
*********
FIX_EXPIRE: For fixing the GoServe automatic response header.
For certain responses that return temporary file, setting FIX_EXPIRE > 0
will cause a modifyed "Expires: " response header to be returned.
In particular, it will add FIX_EXPIRE "fractions of a day" to the
current date/time, and use it as the File-Expires date.
In particular, FIX_EXPIRE is used whenever a server-side include containing
HTML document is being returned. It is also used when temporary files are
returned by SRE-http addons (such as by GETAFILE and DOSEARCH), and by
CGI-BIN scripts.
FIX_EXPIRE=0,
do no add an offset to an Expires: response header.
FIX_EXPIRE>0
add fix_expire "days" to an Expires: response header (fix_expire is added to
the current time).
Setting FIX_EXPIRE > 0 can be useful when relatively static (that do not
depend on the current "hour") server side includes are performed.
In such cases, GoServe automatically sets the expiration time to be
the current moment. This can be a hassle for some clients (Netscape
will, incorrectly, reload such "expired" documents if "backed up" to).
Note that a value of FIX_EXPIRE=0.1 = .1 * 24 hours = 2.4 hours.
Example: FIX_EXPIRE=0
(FIX_EXPIRE can be host specific)
Note: Along with this modified expiratoin date, SRE-http ver 1.3A and
above will add a
Cache-Contol: max-age=0
header -- which http/1.1 compliant applications will use instead of the
the Expires: response header.
**********
HEADERS and FOOTERS: Automatically added to all "SSI-enabled" HTML documents.
You can specify a block of HTML code to include at the beginning and the
end of the body of the document. This is done by specifying HEADERS.n
(n=1...) and FOOTERS.n
To suppress this, set HEADERS.1=0 and/or FOOTERS.1=0
Notes:
* HEADERS.n lines are written (consecutively) just after the first
phrase in your document (see example 3 below for an exception
to thisrule)
* FOOTERS.n lines are written just before the last phrase
in your document.
* Headers and footers are NOT added to documents for which server side
includes are suppressed. For example, if you've set SSI_SHTML_ONLY='YES',
then HTML documents that end with a .HTML will NOT have footers and
headers added.
Examples:
1) Simple case:
HEADERS.1=' Our docuuments are supplied as-is '
FOOTERS.1='
goodbye '
2)To suppress headers and footers
HEADERS.1=0
FOOTERS.1=0
3) The "exception":
Headers.1='
This is our site!
'
Whenever the HEADERS.1 lines begins with element,
the header will replace the first element.
HEADERS and FOOTERS can be host specific.
For example:
HEADERS.1.ZOO = ' The ZOO server '
HEADERS1.1.CIRCUS = ' The Circus Site
HEADERS.2.ZOO=0
HEADERS.2.CIRCUS=0
will set up a one-line header for the ZOO and for the CIRCUS "hosts".
*************
HOME_DIR: The "home directory" -- used as a text replacement whenever a ~
is encountered in a request selector.
A typical value of this would be "Users/".
Example: HOME_DIR='USERS/'
(HOME_DIR can be host specific)
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)
NOTES:
* If there is no $ in the HOME_DIR, a simple HOME_DIR for ~
replacement is done. For example, if HOME_DIR=USERS/and the
request selector is /~GERALD/RESUME.HTM, the result would be
/USERS/GERALD/RESUME.HTM
* If a / immediately follows the ~ (in the request selector), the $ is
removed from HOME_DIR (without replacement).
* HOME_DIR substitution occurs BEFORE virtual file lookup and AUTO_NAME
construction, but after ALIAS conversion. Thus, the ~ can point to a
virtual directory (or a subdirectory of a virtual directory).
* HOME_DIR for ~ substitution is also used when resolving filenames
requested in server side includes.
* CAUTION: Since HOME_DIR is used in a direct textual substitution, only
a mild degree of syntax checking is attempted. In particular,
// are converted to /. To be safe, be sure your use of ~ is
internally consistent.
**************
HOSTS. : Stem variable containing information on multiple hosts.
NOTE:
As of ver 1.3d, use of the HOSTS. stem variable is discouraged.
Instead, use the CFGLIST.CFG file (in the CFGS\ subdirectory).
The HOSTS. stem variable(s) is used to define the multiple hosts
(IP addresses) your server will recognize.
Each HOSTS. entry should contain the following comma-delimited information:
IP_address, host_nickname, default_dir
Where:
IP_address is the IP address (numeric or character) of the host.
You should use the full name -- do not use a "local
abbreviation" (that is, don't use bill as a shorthand
for bill.my.org; even though your local dns may recognize it)
host_nickname is the "nickname" that you will use to refer to this host.
It MUST NOT be a number -- that is, it must contain
a non-numeric character. Thus, 234 is invalid, but
N234 is okay.
Note: To indicate that this is a "superceding host" (defined
below), the host_nickname MUST start with a _!
(see the HOSTS.3 example below).
To indicate that this is a "strict-superceding host"
(defined below), the host_nickname MUST start with a _!!
(see the HOSTS.4 example below).
default_directory is the default data directory for this host
Examples:
hosts.1="dh.ag.gov , MY1 , e:\WWW1 "
hosts.2=" 151.122.33.6 , H20 ,e:\www2 "
hosts.3=" forest.ag.gov, _!Woods ,e:\wwwforest "
hosts.4=" trees.ag.gov, _!!Tree ,e:\wwwtrees "
hosts.5=0
If you do NOT have multiple hosts, set hosts.1=0
Note that we recommend that the last hosts.value = 0.
Definition: superceding hosts.
Entries in several of SRE-http's parameter files are either "host
specific" or "non-host specific". Host specific entries are only
checked for requests that are to a particular host, non-host specific
entries are used for all requests.
SRE-http will use a "best match" algorithim (described in IN_FILES.DOC)
to determine which entry to use. This algorithim is a function of
whether the "host" (to which a request was directed) is a "strict-
superceding", "superceding", or a "non-superceding" host. Basically:
Strict Superceding host:
"Host-specific" entries are checked. Non-host specific entries
are NOT checked.
Superceding host:
"Host-specific" entries are checked. If there are ANY matching
host-specific entries, then the best matching host-specific entries
is used. Ifthere are no matching host-specific entries, then the
non-host specific entries are checked.
In other words, if there are ANY matching host-specific
entries, the non-host specific entries will NOT be checked.
Non-superceding hosts,
Both "host-specific" and "non-host specific" entries are checked.
The best match from this combined set of entries is used. Thus,
a non-host specific entry can be used in preference to a host-specific
entry.
Note:
* A Caution on Using IP Aliases:
IP aliases offer a convenient means of
setting up multiple hosts (IP names) while only using one numeric ip address.
Unfortunately, use of IP name aliases requires browsers that understand
HTTP/1.1; specifically, that send the HOST: request header with each request.
When an older browsers (that does not include a HOST: request header) makes
a request, SRE-http will use the numeric IP address (that is, it will
use the "canonical name" for the IP address, rather then the desired alias).
* When using multiple hosts, you can specify many of SRE-http's
parameters in INITFILT.80 and in the various .IN and .CTL files,
to be "host specific".
* You can define HOST entries using both HOSTS. variables (in INITFILT.80)
and the CFGLIST.CFG file.
* See USE_CFGS.DOC for details on the CFGLIST.CFG fle.
For obvious reasons, HOSTS can NEVER be host specific!
****************
HIT_CACHE_LEN and HIT_CACHE_DURATION: Used to limit false hits.
To reduce the number of "false hits" (from clients returning to
your document after a short absence, which may be caused by the
use of a browser's "back" button), a current hits list can be
maintained. If a request matches a request in this list (where
the request selector and the client's IP address are both used),
the "count of hits" will not be augmented. Specifically,
the COUNTER_FILE and the RECORD_ALL_FILE will not be augmented.
There are two methods of storing these current hits: in the
SRE-http's "storage" thread, or in a "file":
1) The SRE-http's "storage thread".
To specify this, set HIT_CACHE_LEN to the number of entries you wish to set
aside. For example:
HIT_CACHE_LEN=1000
2) File. Not as fast, but probably safer if you are storing a lot of hits.
To specify this, set:
HIT_CACHE_LEN='FILE'
A special file in the TEMP/ subdirectory of the GoServe "working"
directory, with the name _HITCACH.80 (or .nnn if nnn is your serverport)
is created and used to store recent hits.
Each selector/client pair will be retained for HIT_CACHE_DURATION minutes.
Note that "overflow" will NOT occur, but the _HITCACH.80 file may
become large. Since "expired" entries are removed, only in rare
circumstances (extremely heavy load, or when HIT_CACHE_DURATION is
very large), will the file size become problemmatic.
To turn of this feature, set HIT_CACHE_LEN=0
Example:
HIT_CACHE_LEN=500
HIT_CACHE_DURATION=5
HIT_CACHE_LEN='FILE'
HIT_CACHE_DURATION=20
Notes:
* In general, we no longer recommend use of the 'FILE' mode of HIT_CACHE_LEN
(the "storage thread" mode is quite stable and can handle a fairly large
number of entries)
* If you are using the FILE mode, a limit of 10,000 entries is imposed.
* HIT_CACHE_LEN and HIT_CACHE_DURATION can NOT be host specific. Note that
hits are stored both by selector and by host nickname.
*****************
HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS"
Switch to turn off and on the "suppresion of OWNER request"
HIT_OWNER_SUPPRESS='YES'
Do not record (in the COUNTER_FILE or RECORD_ALL_FILE)
any request from an OWNERS.
HIT_OWNER_SUPPRESS='NO'
Requests from OWNERS are recorded.
This is provided to limit the number of false hits attributable to
site-maintenance operations (say, from the Webmaster monitoring
her own site).
Example:
HIT_OWNER_SUPPRESS='YES'
Note: the HIT_SUPERUSER_SUPPRESS variable (set in INIT_STA.80)
can be used to extend the "range" of HIT_OWNER_SUPPRESS to
include SUPERUSERS.
***************
HOME_NAME : The name of your organization
The colloquial (not necessarily IP name) of your organization.
This can be included in a document by using the REPLACE HOME_NAME
keyphrase. Note its use in NOT_FOUND_URL.
home_name="DIVISION/AGENCY/DEPARTMENT/GOV"
(HOME_NAME can be host specific)
*******
HTACCESS_FILE : The name of the HTACCESS file.
When DO_HTACCESS='YES', SRE-http will look in the "requested file's"
directory (and its parent's directory) for file(s) with the name
given by HTACCESS_FILE. Typically, this is HTACCESS. or .HTACCESS,
but you can use any name you want (but do NOT include path information).
Example: HTACCESS_FILE='HTACCESS.'
(HTACCESS_FILE can be host specific)
Hint: The HTACCESS_FILE contains access control information, as well as
URL redirection and "default index" information. To use the URL
redirection, you should set up a file containing entries of the form:
old_url : new_url
i.e.
PLANET/JUPITER.HTM : http://www.starts.edu/ss/n5.htm
(note the old_url should not contain http://, and should not contain
the dot address)
(HTACCESS_FILE can be host specific)
*******
INHOUSEIPS. : Stem variable containing IP address of "in-house" clients.
You can specify any number of "in-house IP domains".
You can specify (several) * wildcards; for example: 111.222.33.*
If Logon controls are desired, then clients with these
IP addresses are automatically given access (they don't need to
provide a username and password).
In addition, you can specify extra privileges for each inhouseips. entry.
Examples:
inhouseips.1="151.121.* VIEWMESS CONTROL "
inhouseips.2="JOE.USDA.GOV "
inhouseips.3=0
(All clients from 151.121.* are given VIEWMESS and CONTROL
privileges, in addition to the privileges contained in the
INHOUSE_PRIVS variable)
Notes:
* If you do NOT want to identify "in-house" clients, set inhouseips.1=0
* Note that we recommend that the last inhouseips. value = 0.
* INHOUSEIPS. can be host specific.
************** CAUTION **************
In fact, non-host specific values of INHOUSEIPS will NOT be used
as "default" values!
************** CAUTION **************
For example:
inhouseips.1='BUYER.STORE.COM'
inhouseips.1.candy='MANAGER.STORE.COM CONTROL '
indicates that requests from MANAGER.STORE.COM to the "host"
with a nickname of CANDY should be treated as an "in-House"
request (note that if no HOSTS. are specified, this entry
will never be used). However, requests from BUYER.STORE.COM to
this CANDY host will NOT be treated as an INHOUSEIPS.
*******
INHOUSE. and SUPERUSERS.
The following are special variables used with the INHOUSE.n
and SUPERUSER.n replacement selector (see decripition of the REPLACE
keyphrase). They will be displayed only for "inhouse" and "superusers",
respectively.
Note that INHOUSE.n variables correspond to INHOUSE.n replacement
strings, and SUPERUSER.n variables correspond to SUPERUSER.n
replacement strings.
Examples:
inhouse.1=" (Staff Version) "
inhouse.2=' .. more staff stuff '
superuser.1="(Super User)"
inhouse.3=0
superuser.2=0
We recommend that the last inhouse. and superuser. should equal 0.
Inhouse. and superuser. can be host-specific; i.e.:
INHOUSE.1.CANDY='Special this week: Chocolate'
**************
INHOUSE_PRIVS: Privileges for IN-HOUSE clients.
A space delimited list of privileges to be granted to OWNERS and
IN-HOUSE clients. It is HIGHLY recommended that INHOUSE_PRIVS always contain
INHOUSE as one of the privileges!
Example: inhouse_privs=" INHOUSE SECRET1 "
Note that INHOUSE_PRIVS can be host specific.
For example: INHOUSE_PRIVS.ZOO=' INHOUSE SCHEDULES '
********
INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor
SRE-http can use "non-REXX" processors to interpert CGI-BIN scripts.
To do this, you must tell SRE-http which processor to associate
with a file extension; where the file extension appears on the
"scriptname" (that follows the CGI-BIN/ portion of the request
selector).
This "association" is accomplished with the INTERPRET_TYPES parameter.
INTERPRET_TYPES should be a space delimited string of "type_options".
Each type_option should have the form:
EXT=Interpreter_invocation
For example:
interpret_types=' PL=PERL5 FOO=D:\FAKEIT\FOOEXEC '
The first type_option (PL=PERL5) instructs SRE-http to use the PERL5
program to interpret all CGI-BIN scripts with a .PL extension
(this example assumes that PERL5 can be found in the OS/2 PATH).
The second type_option (FOO=D:\FAKEIT\FOOEXEC) instructs SRE-http to use
D:\FAKEIT\FOOEXEC to interpret CGI-BIN scripts with .FOO extensions.
Note that a fully qualified name is used for this "FOO interpreter".
Of particular interest is the use of one of the OS/2 PERL interpreters;
since there is a slew of PERL scripts out there. It's not that
hard to obtain a PERL interpreter -- see PERL.DOC for details
on one we've had some success with.
Hint: you can include command line "switches" when invoking a "non-REXX"
processor. To do this, use %20 as a space.
For example:
interpret_types='PL=PERL NRX=netrexx%20-run '
means "use PERL5 with .PL scripts, and use netrexx -run with .NRX scripts.
Thus, a selector of /CGI-BIN/foo.nrx would cause the following to be executed:
netrexx -run foo.nrx
REXX processor), use #20
Note: by default, INTERPRET_TYPES=' PL=PERL5 '
(INTERPRET_TYPES can NOT be host specific!)
********
KEEP_ADDONS.n
To speed up processing of commonly used SRE-http addons (i.e.; STATUS.CMD),
you can tell SRE-http to "load an addon into macrospace" (procedures
load more quickly when they are placed into macrospace). To do this,
you need to specify KEEP_ADDONS. entries.
KEEP_ADDONS.0 should equal the number of entries, and KEEP_ADDONS.n
(n=1 .. KEEP_ADDONS.0) should contain the entries (note that this
is a different syntax from other SRE-http stem variables).
Each KEEP_ADDONS.n (n>0) entry should have the form:
KEEP_ADDONS.n=' SEL FULLY_QUALIFIED_FILE'
For example:
keep_addons.0=2
keep_addons.1='STATUS G:\GOSERVE\ADDON\STATUS.CMD '
keep_addons.2='NUSTATUS G:\GOSERVE\ADDON\NUSTATUS.CMD '
Notes:
* the SEL is compared to the requested selector AFTER possible
"alias" modifications.
* you don't need to include a leading /
* keep_addons. entries are updated along with the SRE-http variables.
Thus, if you change an internal parameter in an addon, it might
take a while for the change to take effect (or, you can issue a
!RESET requeset to your server to signal SRE-http to "update
parameters immediately").
IF YOU MUST HAVE AN ADDON BE QUICKLY RESPONSIVE TO CHANGES IN
HARD-CODED PARAMETERS, DO NOT SPECIFY IT IN A KEEP_ADDONS. ENTRY!
* Errors in KEEP_ADDONS. entries are not fatal -- bad entries are ignored.
* If you do NOT specify a FULLY_QUALIFIED_FILE, then SRE-http will
attempt to drop the macrospace procedure associated with the SEL (if no
such procedure exists, it is ignored). This allows you to selectively
purge macrospace of "addon" procedures. For example, inclusion of:
Keep_addons.3='DO_ONCE '
tell SRE-http to "remove the DO_ONCE program from macrospace"
(with no ill consequence if it's not there).
* Addons that are referenced by a keep_addons. entry can be invoked using
the !RUN special directive. When !RUN is used SRE-http will
immediately call the macrospace version of the addon, and not bother
with some unnecessary housekeeping.
Example:
ADVANCED USERS NOTE:
There may be cases where you have a set of addons that you'ld like
to distribute. Rather then distributing the various .CMD files,
you can (using REXXLIB) create & distribute a "macrospace library"
that contains these procedures. That is, users of these procedures
would NOT have the .CMD files, they'ld only have the image of the
macrospace library (let's call it YOURPROCS.RXL).
Since SRE-http always check macrospace for a procedure BEFORE
looking on the disk, if you "preload" YOURPROCS.RXL into macrospace,
SRE-http will find it and NOT look for a matching .CMD file (or .80
file).
There is one requirement: the procedures must have a special name.
To wit, if the procedure is to be requested with a selector of:
/MYPROC1?xxxx
then the macrospace procedure name should be
SREF_nn_ADDON_MYPROC1
where nn is the port you are running the http server on (typically,
nn is equal to 80).
If you want to use selectors of the form
/SET1/MYPROC1?xxxx
then the macrospace procedure should have a name of
SREF_nn_ADDON_SET1_MYPROC1
That is, all periods, / and \ should be converted to _ characters.
HINT: to facilitate loading of YOURPROCS.RXL, you could distribute a
loader.cmd (or some such name) that loads YOURPROCS.RXL,
and is called as one of the CUSTOM_INITS.
For example:
/*load the YOURPROC.RXL "addon procedures into macrospace */
foo=macroload('YOURPROC.RXL')
if foo=0 then
call pmprintf(' Warning: problem loading YOURPROC.RXL')
return 0
KEEP_ADDONS. is NOT Host specific.
********
LOGON_FAIL_FILE
If a logon failure occurs (either due to an incorrect username/password,
or due to logon_limit being violated), SRE-http can
either send a "401 Unauthorized" response; or the contents of
the LOGON_FAIL_FILE.
If LOGON_FAIL_FILE=0, then a "401 Unauthorized" response is sent.
Otherwise, the LOGON_FAIL_FILE is sent as is; with a few substitutions:
phrases are substituted with the request selector.
phrases are substituted with the servername.
phrases are substituted with the WEBMASTER variable.
phrases are substituted with a short description
of the reason for failure
phrases are substituted with a link back to this URL.
Examples:
LOGON_FAIL_FILE=0
LOGON_FAIL_FILE='D:\GOSERVE\LOGFAIL.HTM'
Notes:
* LOGON_FAIL_FILE should be a fully qualified file name.
* If the LOGON_FAIL_FILE is unavailable, a "401 Unauthorized" response is
sent.
* When using #LINK, you probably should advice the client to "wait a
minute before trying again" (given that the problem might be
due to logon_limit being exceeded).
* Reminder: the LOGON_FAIL_FILE is used when the client
fails a "generic" logon (that is, she does not have a valid
username and password). In contrast, the ACCESS_FAIL_FILE
is used when the client does not have sufficient "client privileges".
(LOGON_FAIL_FILE can be host specific)
*****************
MAX_POINTDIST : Used with the POINT type in mappable images.
Max_pointdist is used with server side image maps.
The "point" area is one of the 4 types of areas (circle, rectangles,
polygons, points) used in selecting a URL from a mappable image.
If a selected pixel does not lie in one of the first 3, or does not
lie directly on top of a point; SRE-http determines to which (of
the many possible different points that may appear in the map file)
the selected pixel is closest to. However, if the distance to this
closest point is greater then max_pointdist, then the Default URL is used.
Thus, this limits the region of space "potentially assigned" to each point.
Of course, setting max_pointdist to be very high (say, 100000),
will effectively cancel this limit.
Example: max_pointdist=50
(MAX_POINTDIST can be host specific)
*************
NO_PROCESSING: Suppress server side processing
Switch to dictate whether or not to allow server side processing.
YES - Do NOT do allow server side processing
If YES, then requests for server side processing will cause
a 401 Unauthorized message to be returned to the client.
NO - Allow server side processing.
Note: A NO_SSP permission (in the access_file), overrides a NO_PROCESSING='NO'.
Example: no_processing="NO"
(NO_PROCESSING can be host specific)
************
NO_INTERPRET_CODE: Suppress execution of "in-document" executables.
This is similar to NO_PROCESSING, but not as stringent -- it only applies
to the SELECT and INTERPRET CODE "server side include" keyphrases.
YES- Ignore SELECT and INTERPRET CODE server side include keyphrases.
NO - Process SELECT and INTERPRET CODE server side include keyphrases.
Note that NO_PROCESSING (and NO_SSP) have precedence -- if NO_PROCESSING is
on, the value of NO_INTERPRET_CODE is irrelevant.
Notes:
* A NO_CODE permission (in the access_file) overrides a
NO_INTERPRET_CODE='NO'
* CGI-BIN scripts, INTERPRET FILE, and other "executed files" WILL
be processed if NO_INTERPRET_CODE='YES' (assuming NO_PROCESSING, etc.
is not binding).
Hence:If NO_INTERPRET_CODE='YES', you can still use an equivalent
INTERPRET FILE keyphrase.
* The idea is that users of your site will not be able to cause trouble
by including ill-mannered code into their HTML documents.
In other words:
i) If site administrators will not review HTML documents
posted on their site (say, by students)
ii) Site adminstrators will review CGI-BIN scripts, etc. that these
"students" wish to place on the server.
iii) Site administrators DO want to grant server side processing
and server side include privileges to clients.
Then, a reasonable level of security, without too harshly limiting
flexibility, can be achieved by setting NO_INTERPRET_CODE
(or by judicious use of the NO_CODE permission).
Example: no_interpret_code='NO'
(NO_INTERPRET_CODE can be host specific)
************
NO_INCLUDE: Suppress server side includes.
Switch to dictate whether or not to process server side includes (SSIs).
YES : Do NOT do dynamic page processing.
Files sent as is (if SSI keyphrases occur, they will be sent "as is"
NO : Process server side includes.
If you NEVER include SSI keyphrases, and you want to speed
up processing a bit, set NO_INCLUDE="YES"
Notes:
* A NO_SSI permission (in the access_control_filefile), overrides
NO_INCLUDE=NO.
* A YES_SSI permission (in the access_control_file) overrides
NO_INCLUDE=YES
Example: no_include="NO"
(NO_INCLUDE can be host specific)
**********
NOEXT_TYPE: Determine how to handle "no extension" request selectors.
NOEXT_TYPE is used to instruct SRE-http what to do with requests that
have no extension, do not end in a /, and do not have ? in them. There are
several allowed values of NOEXT_TYPE, any set of which may appear in a
space delimited list:
REDIR : A / is appended to the end, and then the client is
or is "redirected" back to this new (/ appended) URL --
DIR at which time the AUTO_NAME feature kicks in. This solves
potential "resolution of local URL" problems, at the cost of slower
overall response times. Note that REDIR is the default value.
HTM or HTML : Interpret as an HTML file (a .HTM or .HTML is appended to
the end, respectively)
NONE : Use as is
other_string: Append other_string. For example, if NOEXT_TYPE='.GIF',
then .GIF will be appended to the end).
Examples: NOEXT_TYPE="DIR"
NOEXT_TYPE='HTM HTML .SHT .SHTML DIR'
(try several extensions, and then redirect back to xx/)
(NOEXT_TYPE can be host specific)
CAUTION:
When using NOEXT_TYPE (and other types of local redirection)
URL resolution by the client's browser may have unexpected consequences.
See the discussion of "local vs remote redirection" at the bottom of
this document for details!
***************
NOT_FOUND_URL : A message, or response file, to use if the requested resource
is not found.
There are basically three formats of the NOT_FOUND_URL:
1) not_found_url='Message string'
The 'message string' is sent along with a generic "not found url" response.
Note that this message string should be a valid HTML string.
Set it to " " if you want no such message sent.
Example: not_found_url=' Visit the HOME_NAME page? '
Note that the HOME_NAME substring will be replaced with the current
value of the HOME_NAME variable.
2) not_found_url='file=fully_qualified_filename'
If you want to return a "generic" custom document, perhaps one that lists
several choices, you should use a special form of NOT_FOUND_URL.
Specifically:
NOT_FOUND_URL= 'FILE=fully_qualified_file_name'
For example:
NOT_FOUND_URL= 'FILE=d:\www\notfound.htm'
If you are very ambitious, you can also append a custom "reponse code".
For example:
NOT_FOUND_URL= 'FILE=d:\www\notfound.htm, 200 Ok with error '
(note the comma follwing the file name)
The returned document will NOT have server side includes -- it is sent
"as is". There are a few special exception to this rule (for HTML
documents):
i) all occurences of will be replaced with the
request selector.
ii) all occurences of will be replaced with the
server's IP address.
Notes:
* You can specify any type of document (i.e.; an HTML file, a GIF file,
or a plain/text file).
* A fully qualified file is expected: no attempt is made to map a
relative file name to the data directory.
* The file can be anywhere (it need not be in the data directory,
or in virtual directories).
* Historical note: this was the first type of "customized 404 response file"
supported by SRE-http. Although not deprecated, in general we recommend
use of the "virtual" form described below.
That said, there is 1 advantage to this "fully qualified not_found_url" --
you don't have to maintain seperate "path specific" not_found_url files.
3) not_found_url='file=filename.ext'
or
not_found_url='virtual=filename.ext'
When filename.ext contains no path information, SRE-http will look
for a "directory specific" response file (with the name filename.ext).
First, the directory of the request will be checked. If filename.ext
does not exist in this "selector's own directory", SRE-http will
check the next directory, continuing until a matching file is found, or
until the root directory has been checked.
It may be more appropriate to refer to this as a "cascading, directory
(or directory-tree) specific response-file".
Notes:
* At each step, virtual directory matching will be attempted. Thus,
depending on how complicated your virtual directories are, it
is possible for "lower directories" to refer to completely seperate
absolute directories.
* Abstracting from virtual directories, the "directory tree" searched
depends on the type of "not found URL":
> Document (text file, graphics, etc.). Look under the GoServe
data directory (i.e.; D:\WWW).
> CGI-BIN script. Look under the CGI-BIN directory
(i.e.; D:\GOSERVE\CGI-BIN)
> SRE-http addon. Look under the ADDON_DIR directory
(i.e.; D:\GOSERVE\ADDON).
Therefore, is is wise to place copies of (possibly different)
"filename.ext" files in all three "root" directories.
* If filename.ext points to a "server side includable" text/html file,
tbe full gamut of SRE-http's server side includes will be available.
* Both forms are identical -- the "VIRTUAL=" was added (as of ver
1.3B.1298e) as a pneumonic device (to remind you that this
"no path" form of NOT_FOUND_URL refers to a "virtual" filename).
* You can use the "find best match" addon (MTCHFILE.RXX, as illustrated
by MTCHFILE.SHT) to return a list of "candidate matches" (in
the current directory). See MTCHFILE.DOC for details.
NOT_FOUND_URL can be host specific (and HOME_NAME can also
be host specific).
*********
OPTION_HIT_LINE : Used to write OPTION info instead of counts
OPTION_HIT_LINE is used to write out "# hits drawn from an OPTION
passed to me" -- that is, it used with the REPLACE OPTION_HITS keyphrase
Example: OPTION_Hit_line=":: still access # "
Note: OPTION_HIT_LINE is somewhat obsolete -- its major purpose is
now better accomplished by using the HIT_CACHE_LEN parameter
(OPTION_HIT_LINE can be host specific)
*************************
OWNERS: Assigned SUPERUSER privileges
Owners are always given SUPERUSER privileges.
You can specify any number of owners, just seperate each of them
with a space. Note that wildcards are NOT allowed. Furthermore,
you must specify a numeric IP address (not an IP name).
If there are no owners, set owners=0.
Example: owners = " 151.121.65.163 "
(OWNERS can be host specific).
************
PRE_FILTER: Call user written pre-filters.
PRE_FILTER is used to control whether a set of user written "pre-filters"
are called before SREFILTR is given control. It can take 3 values:
NO: Do not call a pre-filter.
YES: Call a pre-filter after checking logon privileges (if the client
does not have logon rights, the pre-filter will not be called)
FIRST: Call a pre-filter as the first action (before checking logon rights)
Note: if the selector matches a PUBLIC_URL, then:
> If PRE_FILTER=FIRST, then the pre filter will be called
> Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is
treated as a NO.)
Example: PRE_FILTER="FIRST"
(PRE_FILTER can be host specific)
************
PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s).
This should point to a list of external procedures (or just to a
single external procedure). Each of them will be called in turn
(or until one of them responds to the client). Note that these
"PREFILTER" files should be in the GoServe working directory.
Examples: PREFILTER_NAME='PREFILTR'
PREFILTER_NAME='PREFILT1.CMD PREFILT9.CMD '
In the first example, note that a .80 (or .nnn if using port nnn) is added to
PREFILTR.
(PREFILTER_NAME can be host specific)
************
POST_FILTER: Call user written post-filters.
POST_FILTER is used to control whether one or more user written
"post-filters " are called before SRE-http is given control.
It can take 2 values:
NO: Do not call a post-filter.
YES: Call a pre-filter after sending response to client.
(POST_FILTER can be host specific)
************
POSTFILTER_NAME: A series of procedures to call as post filters.
POSTFILTER_NAME should contain a list (or just one) procedures that
will be called as "post filters".
As with other external procedures, the procedures should correspond
to files with names like POSTF1.80 (they should be in the GoServe
working directory).
If the POSTFILTER_NAME variable is missing, a value of POSTFILT will be used.
Examples: POSTFILTER_NAME='POSTRCRD.80'
POSTFILTER_NAME='POST1.CMD POSTMAIL '
In the second example, first POST1.CMD will be called, and then POSTMAIL --
note that a .80 (or .nnn if using port nnn) is added to a name when there is
no extension (and no final period).
Notes:
* Post-filters are called AFTER the client has recieved a response.
Therefore, post-filters can NOT be used to modify the response.
* Certain request-specific GoServe functions are NOT available to
post-filter procedures (i.e.; EXTRACT('CLIENTPORT') will not
work).
* POSTFILTER_NAME can be host specific
****************
PUBLIC_URLS.
As of version 1.3A, SRE-http no longer stores PUBLIC_URLS in the INITFILT.80
file. Instead, a seperate file (PUBURLS.IN, in the DATA directory) is used.
Please see PUBURLS.DOC for further details.
**************
PUBLIC_PRIVS. Additional privileges for all clients.
A space delimited list of additional privileges to be granted to all
clients).
Set PUBLIC_PRIVS=" " if no additional privileges are needed.
Examples: public_privs=" PUBLIC MESSBOX=*"
public_privs=' PUBLIC MESSBOX=FORUM1 MESSBOX=PUBGRP* '
Notes:
* PUBLIC_PRIVS are used with requests that match a PUBLIC_URL.
* The MESSBOX=* privilege (the SRE-http default) grants read/write
access to all "message boxes" (assuming Selector and FILE specific
access controls are NOT in place). In contrast, MESSBOX=FORUM1
permits access to the FORUM1 message box. and MESSBOX=PUBGRP*
allows access to PUBGRP01, PUBGRP02, etc.
* The CONTROL privilege allows some of the special (the !xxx) commands.
* The BROADCAST privilege allows the user to "broadcast" e-mail messages
using the SRE-http message facility.
* The VIEWMESS privilege allows a client to download a
SRE-http message box file.
(PUBLIC_PRIVS can be host specific)
******
RANGE_AT_END
Enable checking for range information at the end of a request
string (after a ;). This is an alternative to the
!RANGE special directive.
0 = Do NOT look for this info
1 = Do look
Example:
RANGE_AT_END=0
In general, it's safer to NOT use ;range_info -- use the
!RANGE special directive instead.
*******
RECORD_OPTION : Select whether to record all allowed requests.
Used if you want to keep a running total of requests.
RECORD_OPTION can take several values
NO = Do NOT Keep track of requests
YES = Remove argument list, and keep track of all requests.
YES_ALL = Do not remove argument list, and keep track of all requests.
FILE = Record using the name of the requested file (or script)
If RECORD_OPTION is <> NO, results will be written to the RECORD_ALL_FILE.
Example: record_option="YES"
Notes:
* The "argument list" is the ? (and anything that follows it) in a
request selector.
* If you use YES_ALL or FILE, be prepared for your RECORD_ALL_FILE to
grow quite large.
* Note that RECORD_ALL_FILE can be hand-edited. You may want to add
appropriate "wildcarded" entries (such as /TEMP/*) to keep track of
all temporary files, thereby avoiding the creation of
lots of useless entries.
* The RECORD_CACHE_FILE (see section 2a) is used to control caching
of the RECORD_ALL_FILE.
* See the WRITE_LOGS parameters for an alternative auditing mechanism
(the common-log file).
(RECORD_OPTION can be host specific)
************
REPLACE_RULES.n
The REPLACE_RULES. are used to perform textual substituion on HTML
documents subject to server side includes. Although only attempted
on "SSI" documents, the REPLACE_RULES. are not "server side
includes". Rather, they are textual replacements that occur
throughout the document, regardless of the placement of
HTML elements.
REPLACE_RULES. can be useful as a way of changing values across
a wide range of documents (they emulate style sheets), or
as a shorthand for longer actions.
When specifying REPLACE_RULES.; you must specify REPLACE_RULES.0
to be the number of rules you'll specify. Each REPLACE_RULES.n
should have the form:
REPLACE_RULES.n='old_string==newstring'
All occurences of old_string will be replace by newstring.
Notes:
* == is used to divide the old and new strings.
* spaces are NOT stripped. Thus:
replace_rules.1=$x==THIS is X
will have different effects then:
replace_rules.1= $x== THIS is X
(the latter requires a space before the x, and will add a space
before the THIS)
* the match of old_string is case insensitive; but the newstring
case will be maintained.
* Not only will the original document be subject to REPLACE_RULES, so
will all subsequent server side includes.
* To specify an == in a new or old string, use URL-encoding
(== is %2b%2b).
Note that you can specify = by using a single = sign.
* To not use any REPLACE_RULES; set REPLACE_RULES.0=0
* If any REPLACE_RULES are specified in a selector-specific advanced
options file, they will be used INSTEAD of these "generic" REPLACE_RULES.
That is, these generic REPLACE_RULES will be dropped whenever
SEL-specific REPLACE_RULES are specified).
Please see ADV_OPTS.DOC for more information on selector-specific
REPLACE_RULES.
Example:
REPLACE_RULES.0=2
REPLACE_RULES.1='${=='
This will transform
Customization is ${set1.var1}
into
Customization is
REPLACE_RULES. can be host specific. For example:
REPLACE_RULES.0.HOST2='1'
REPLACE_RULES.1.HOST2=' C.== $ Customiz
where HOST2 is the host-nickname of one of your hosts.
************
SMTP_GATEWAY: Domain name of an SMTP server
The SMTP_GATEWAY is used when e-mail messages are to be sent; as may
be attempted by MESSAGE, FORUM, and several other SRE-http facilties.
This should be the domain name of a SMTP mail server.
Example: SMTP_GATEWAY=MAILBOX.BIG.EDU
Note: You can use your own server as the SMTP gateway by running SENDMAIL.
(SMTP_GATEWAY can be host specific)
***********
SSI_CACHE_ON
SSI_CACHE_ON is used to enable the server side include cache (SSI-cache).
NO : Turn the SSI-Cache off -- HTML documents will not be cached.
YES : Turn the SSI-Cache on.
The SSI-cache is used to store "compiled" versions of HTML documents that
contain server side includes. When a request for such document arrives,
SRE-http will return it (perhaps with further modifications).
Turning off caching is sometimes useful in highly dynamic
environments; say, where INCLUDE files are constantly changing.
Example: SSI_CACHE_ON = 'YES'
Notes:
* For further discussion of SSI-caching, please see the SSICACHE.HTM
file.
* The SSI_CACHE_SIZE variable (set in INIT_STA.80) can also be used
to disable the SSI-Cache.
(SSI_CACHE_ON can be host specific)
*******
SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only
SRE-http can be instructed to attempt server side includes (SSIs) only on
files with a .SHT or .SHTML extension -- files with .HTM (or .HTML)
extension will NOT be checked for server side includes. This can speed
up file transfer, but does require more care when naming html files.
SSI_SHTML_ONLY : NO. All HTML documents will be checked for SSIs.
Note that files with .HTM .SHT .HTML and .SHTML are
assumed to be html documents (more specifically,
mime type text/html documents).
SSI_SHTML_ONLY : YES Only .SHTM and .SHTML files are checked for SSIs.
Notes:
* SSIs are NOT processed when NO_INCLUDE='NO' (or if there is no
NO_SSI permission).
* The list of "SSI capable" files can be modified to include files with
extensions other then .SHT and .SHTML. See the description of the
SSI_EXTENSIONS variable (in the next section of this document) for details.
* A YES_SSI "SEL-specific" permission overrides
SSI_SHTML_ONLY='YES'.
(SSI_SHTML_ONLY can be host specific)
****************
SUPPRESS_GZIP_TE: Suppress on-the-fly gzip encoding
By default, when a client asks for it, SRE-http will GZIP encode a response
"on the fly". While this can save bandwidth, it does add extra processing
burden.
You can suppress this "on the fly" compression by setting
SUPPRESS_GZIP_TE=1
To permit this compression, you should set
SUPPRESS_GZIP_TE=0
Technical Notes:
* Assuming SUPPRESS_GZIP_TE=0, then SRE-http uses the following algorithim:
a) The SREF_GOS procedure (which handles almost all of SRE-http's
transfers) checks for TE: request header. If not found, exit
b) If the resource has GZIP "content-encoding", exit
c) If a TE: request header is found, a GZIP argument is looked for.
If not found, exit.
d) If a GZIP argument is found, and its "quality" parameter is
compared to the IDENTITY quality parameter (where, by default,
IDENTITY has a quality parameter of 0.001). If not greater, then exit.
e) rxGZlib.dll is used to compress the response. Note that the response
may be a file, or a string (as produced by an sre-http addon).
f) If the client is http/1.1, then the response is also "chunked"
g) A Transfer-encoding: Gzip (or Transfer-encoding: gzip,chunked)
response header is added
h) The GZIPped (and possibly chunked) response is sent to the client
* An alternative means of transferring GZIPped (or otherwise compressed)
files is to use content negotiation to return a GZIPped "variant"
(as described in NEGOTIAT.DOC). This requires that you create GZIPped
file(s) and store them in the same directory as the original file --
they will not be GZIPped on the fly.
* As of 1.3h.0010 -- if content-negotiation, or CE_GZIP (as
set in INIT_STA.80 or as an advanced option) is enabled,
then on-the-fly GZIP content encoding is attempted.
Furthremore, on-the-fly GZIP transfer-encoding is NOT attempted.
****************
THE_REALM: "Realm" name to use in requests for username/password.
This is the "realm" which client are "challenged" by --
most browsers will display this "realm" information when asking for
username/password (as when CHECKLOG='ALWAYS' and a non-inhouse
client comes a calling)
Example: the_realm="OUR WEB SITE"
Notes:
* The "SEL-specific realm" (specified in the access file) is used
if it is available.
If no "SEL-specific realm" is available, the value of THE_REALM is used.
* If you set REALM_1ST_PRIV=1 (in INIT_STA.80), then the "first
resource privilege" will be used as the realm name (if no "sel specific"
realm is explicitly specified)
* THE_REALM can be host specific.
For example: THE_REALM.ZOO='ZOO_SITE'
*******
UNALLOWEDIPS : Stem variable of "disallowed" IP addresses.
You can specify a set of ips that are NOT allowed in (a keep out pests
option). The syntax is the same (* allowed, consecutive numbering), as
the INHOUSEIPS. variables.
Note: UNALLOWEDIPS. is ALWAYS checked (even if checklog=NO) -- and if a
match is found, no logon is requested (they can't get in)
Example: unallowedips.1 = "149.126.12.*"
unallowedips.2="136.12.5.212"
unallowedips.3=0
Example2: unallowedips.1="*"
unallowedips.2=0
Only OWNERS and INHOUSEIPS.n clients can get in !
Example3 : unallowedips.1 = 0
means that no one is automatically excluded.
Notes:
* If any UNALLOWEDIPS. are specified, then caching is suppressed.
Thus, in general, we do NOT recommend use of UNALLOWEDIPS.
* UNALLOWEDIPS. is checked after INHOUSEIPS. and OWNERS
* We recommend that the last unallowedips. value = 0.
HINT: In some cases (such as when you want an accurate count of the
number of requests for all your documents), you may wish to
"cache bust". That is, you may wish to prevent proxy servers
from resolving a request to your server. You can do this by
specifying a nonsense unallowedips. For example, set
unallowedips.1='0.0.0.0'
unallowedips.2=0
WE DO NOT RECOMMEND THIS TRICK -- HTTP/1.1'S EFFORTS TO MAKE THE WEB
PROXY SERVER FRIENDLY WILL BENEFIT EVERYONE!
UNALLOWEDIPS. may be specified on a host-specific basis.
************** CAUTION **************
Non-host specific values of UNALLOWEDIPS will NOT be used
as "default" values (see INHOUSEIPS. for details)!
************** CAUTION **************
********
UPLOAD_MAXSIZE: The maximum size (in Kbytes) allowed in a uploaded file.
Uploaded files are placed on the server when a GET_URL or a PUT_FILE
request selector is recieved.
Set this small (say, 20) if you don't want large files dumped onto
your machine. Set it to 0 to disable all file uploads!
Example: upload_MAXSIZE=50
Note:
Uploads using the PUT http method are not limited by the UPLOAD_MAXSIZE
variable.
(UPLOAD_MAXSIZE can be host specific)
********
UPLOAD_MINFREE: Space that must remain after an upload.
The minimum amount of free space (in Kbytes) that must exist in the
upload_DIRECTORY's hard drive after uploading a file with GET_URL or PUT_FILE.
Set this large (say 100000) if you want to be certain that your
hard drive doesn't get filled up).
Example: upload_MINFREE=25000
Note: if either upload_MINFREE or upload_MAXSIZE are violated, file
upload will not occur.
(UPLOAD_MINFREE can be host specific)
*******
USE_STDOUT: In "INTERPRET" keyphrases, use standard output as a means
of writing results to a document.
If USE_STDOUT='YES', then INTERPRET keyphrases will have three
means of inserting data into your document:
1) A string RETURNed (by a RETURN statement in the code block)
or
2a) interpret.results='some string'
2b) All QUEUE (and PUSH) statements will be inserted (after the string stored
in interpret.results
If USE_STDOUT='NO', then ONLY methods 1 or 2a are used (2b, output from
QUEUE and PUSH statements, will be ignored).
With USE_STDOUT='YES', INTERPRET will work similarly to the #EXEC
server side include -- except SAY generated output is NOT retained
(GoServe traps SAY statements, and sends their output to the
PMPRINTF window).
Hence the need to use QUEUE (or PUSH) ...
Example: USE_STDOUT='YES'
Note: INTERPRET "interprets" REXX code blocks (rather then
call them as external procedures). Hence, you do NOT have to
have a RETURN in the code block (if you do, SRE-http will
trap it, and use the RETURNed results; viz method 1 above).
(USE_STDOUT can be host specific)
*******
USER_LOGON_ENABLE: Enable the use of a custom "user logon procedure"
You can instruct SRE-http to use a custom built "user logon procedure"
instead of the built in logon procedure.
To do this, you must set the USER_LOGON_PROC parameter in INIT_STA.80,
and you must set USER_LOGON_ENABLE. Note that if USER_LOGON_PROC
is not specified, then USER_LOGON_ENABLE is ignored.
USER_LOGON_ENABLE extends USER_LOGON_PROC in several ways:
a) You can enable (or suppress) use of the default user_logon_proc
procedure on a host-specific basis
b) You can specify a host specific "user logon" procedure
Permissible values of USER_LOGON_ENABLE are:
NO or 0 = do NOT use a custom user logon procedure
YES or 1 = use the USER_LOGON_PROC procedure
procname = use "procname" as the user logon procedure. That is, override
the value specified in USER_LOGON_PROC.
Advanced users note:
SRE-http uses the REXX "INTERPRET" facility to support user logon procedures.
Since INTERPRET is somewhat slow, you can speed things up by specifying
a special name of a procedure that you've loaded into macrospace.
To do this:
a) set USER_LOGON_ENABLE='SREF_USER_LOGON'.
Or, set USER_LOGON_PROC='SREF_USER_LOGON'
b) Before (or soon after) starting GoServe, load your user logon procedure
into macrospace, using the name "SREF_USER_LOGON".
Note that you can only do this once -- you can not have host-specific
"user logon procedures in macrospace".
Examples:
USER_LOGON_ENABLE='YES'
USER_LOGON_ENABLE.HOST1='NO'
USER_LOGON_ENABLE.HOST2='HOST2LOG.CMD'
USER_LOGON_ENABLE='NO'
USER_LOGON_ENABLE.HERSITE='YES'
USER_LOGON_ENABLE.FLIMFLAM='SREF_USER_LOGON'
Notes:
* see the discussion of USER_LOGON_PROC for details on how SRE-http works
with user logon procedures.
* to reiterate: If USER_LOGON_PROC is not specified (or equals 0), then
USER_LOGON_ENABLE is ignored.
* the default value of USER_LOGON_ENABLE is used when a host-specific
value is not specified.
(USER_LOGON_ENABLE can be host specific)
*******
USER_PRIVS: Additional privileges assigned to registered users.
USER_PRIVS should be a space delimited list of "privileges"
that will be granted to "registered users" -- to clients
who have a username and password for your server (i.e.; for
whom an entry exists in the USERS.IN file).
By default, USER_PRIVS='USER'
Example:
USER_PRIVS='USER REG_1999 '
(USER_PRIVS can be host specific)
*******
VERBOSE: Controls the extent of comments written to the Pmprintf window/
SREHTTP.LOG file..
Set verbose=1 if you want a fair number of status messages written to
the pmprintf window and/or the SREHTTP.LOG file
Set to verbose= 0, and only error messages and certain initialization
messages will be displayed.
Example: verbose=0
(VERBOSE can be host specific)
Notes:
* for even more comments, set VERBOSE=2, 3 or 4.
* see the description of PMPRINTF_OPT for more details on how SRE-http
"audits" transient messages
*********
WEBMASTER: A static variable.
The WEBMASTER variable is used in certain error and status messages.
Note: you might also want to put specify a CONTACT "REPLACEment variable"
in the repstrgs_file file.
Example: webmaster=' Webmaster '
WEBMASTER may be host specific
(i.e.; WEBMASTER.SWEETSHOP='CANDY@SWEET.ISP.COM')
********
WRITE_LOGS: Enable the common-log, browser, and referer logs.
The WRITE_LOGS variable is used to enable recording of all requests
toe the common-log audit file. In addition, browser and referer information
will be written to seperate log files.
YES = Enable these log files
NO = Do NOT record requestsion in these log files.
Example: WRITE_LOGS='YES'
Note: For further details on the common-log, etc. log files, see
SREFLOGS.DOC.
WRITE_LOGS may be host specific.
********
List of files and directory identifier variables.
With one exception, these directories are NOT host specific.
The exception is the ADDON_DIR directory, which can be host specific.
NOTE: If you change these, you MUST re-start GOSERVE!
ADDON_DIR) Directory for SRE-http addons (and INTERPRETable files).
Notes: ADDON_DIR can be host specific.
Alternatively, you can use virtual directories when
invoking an SRE-http addon.
MESSBOX_DIR) Directory containing message boxes,
MAILBOX_DIR) The in-box directory of an SMTP server.
CGI_BIN_DIR) Location of CGI-BIN programs.
TEMPFILE_DIR) Web accessible directory to use for creation of
"temporary" files (by external procedures).
In comparison to the TEMPDATA_DIR, TEMPFILE_DIR
s meant for short-life files (typically created by
a server side program) that are meant to be downloaded
in response to a subsequent request.
Note: The !DELSEND "special action" looks for files in
TEMPFILE_DIR.
UPLOAD_DIR) Default location for uploaded files.
TEMPDATA_DIR) Used for various SRE-http temporary files, such as
_HITCACH.80, _ADDPRIV.80, and the $xxx.80 temporary
"response" files. In comparison to the TEMPFILE_DIR, these
are files that are used by SRE-http, and should NOT be
to be directly accessible to WWW clients.
USERINFO_DIR) Directory used to store client-specific information
(i.e.; client customization data files).
WORKDATA_DIR) Directory containing various SRE-http parameter files.
COUNTER_FILE) "REPLACE HITS" counter file
ERROR_LOG) The error log file (written to by the SREF_ERROR procedure)
RECORD_ALL_FILE) "Record all requests" counter file
SENDFILE_FILE) File used by SENDFILE procedure to keep track of requests.
ACCESS_FILE) File used to control access when ALLOW_ACCESS is binding
UPLOAD_LOG) Record of "uploaded files"
ALIAS_FILE) File containing the aliases.
PUBURL_FILE) Contains public urls.
VIRTUAL_FILE) File containing "virtual directory" selector aliases.
REPSTGS_FILE) REPLACEment string file
USERS_FILE) Username/password file
INTERPRET_FILE) File containing blocks of REXX code for use by the
INTERPRET keyphrase (obsolete, retained for backwards compatability).
Examples:
messbox_dir='e:\goserve\MESSAGE'
mailbox_dir='c:\mptn\etc\mail'
tempfile_dir='e:\WWW\temp'
upload_dir='E:\goserve\upload'
cgi_bin_dir='E:\goserve\CGI_BIN'
counter_file='e:\goserve\DATA\COUNTER.CNT'
record_all_file='e:\goserve\data\recrdall.cnt'
sendfile_file='e:\goserve\DATA\SENDFILE.CNT'
error_log='e:\goserve\data\error.log'
access_file='e:\goserve\cfgs\ACCESS.IN'
tempdata_dir='e:\goserve\temp'
userinfo_dir='e:\goserve\userinfo'
virtual_file='E:\goserve\cfgs\VIRTUAL.IN'
alias_file='e:\goserve\cfgs\ALIASES.IN'
repstrgs_file='e:\goserve\cfgs\REPSTRGS.IN'
user_file='e:\goserve\cfgs\USERS.IN'
interpret_file='e:\goserve\INTERPET.IN'
Note: The various .CNT and .IN files that are shipped with
SRE-http (such as ACCESS.IN) contain additional documentation.
Note that these various filenames are NOT host specific, but
they MAY contain host specific entries!
=============================
2h. Parameters in INIT_STA.80
In addition to the dynamic-parameters contained in INITFILT.80, there are a
number of static-parameters in INIT_STA.80 which the ambitious user may wish
to change. Note that:
* None of these static-parameters are host-specfic.
* In order for changes to these static parameters to take effect, you MUST
restart GoServe
Very ambitious webmasters may wish to tinker with a few parameters
in SREFMON.CMD. Descriptions of these more obscure parameters follows
the descriptions of the parameters in INIT_STA.80.
NOTE: As of ver 1.3d, parameters are no longer set in the SREFILTR.80 file--
all the parameters that were in SREFILTR.80 are now in INIT_STA.80.
---- PARAMETERS in INIT_STA.80 ---
********
ALWAYS_CHECK_PRIVS
When a request selector matches a PUBLIC_URL, SRE-http does not
require the client to have "access privileges". However, the
request may be for a SRE-http addon which may require specific
privileges.
Setting ALWAYS_CHECK_PRIVS=1 tells SRE-http to "get the client
privileges, even if she asked for a PUBLIC_URL. A value of 0
tells SRE-http to NOT lookup client privileges when PUBLIC_URLs
are requested.
Basically, If you know that PUBLIC_URLs NEVER require privilege
information, setting ALWAYS_CHECK_PRIVS=0 will improve performance.
If you aren't sure, the safe choice is to set ALWAYS_CHECK_PRIVS=1.
Example: always_check_privs=1
********
BACKUPSERVERLIST and LOADTHRESHOLD
These variables are used to control "load balancing". SRE-http comes
with a simple load-balancer, but you can easily specify far more
complicated load balancing schemes (i.e.; the BALANCER SRE-http addon).
LOADTHRESHOLD:
If LOADTHRESHOLD=0, then this "load balancing" is not attempted.
Otherwise, load balancing will occur if the number of active clients
is greater then the value given.
BACKUPSERVERLIST:
If BACKUPSERVERLIST=' ', then load balancing is not attempted.
Otherwise, it should contain a list of IP addresses of alternate
(backup) servers (that presumably mirror the main site).
If BACKUPSERVERLIST contains more then one entry (entries should be
seperated by spaces), then a partially random method is used to select
which server to redirect the client to. For example:
2 entries = 2/3 of the redirections go to the first entry.
3 entries = 1/2 go to the first entry (1/4 to 2nd and 3rd)
Examples:
loadthreshold=0
backupserverlist=' '
loadthreshold=6
backupserverlist='www2.oursite.net'
loadthreshold=3
backupserverlist='www2.oursite.net overflow.hersite.net '
backupserverproc='d:\goserve\addon\backsrv2.80'
Citation: The basic idea for the generic balancer is borrowed from
Don Meyer's GoHTTP filter.
**********
CERN_ISMAP
The value(s) in the spaced delimited CERN_ISMAP variable is used
to indicate that this "is an image-map request". You can specify several
different values (though you should only use one of them in a given
"image map" URL).
When one of these identifier-strings appear in a request selector,
SRE-http assumes that the request "is a response from a mappable image"
For example, if CERN_ISMAP='/MAPCERN', then selectors (that are generated
by clicking on a mappable image) of the form:
/MAPCERN/GIFSDIR/USMAP.MAP?123,312
will be interpreted as ...
pixel 123,312, in combination with the instructions contained
in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
the client to (where USMAP.MAP is a CERN style MAP file)
IMPORTANT NOTE: the MAPCERN/ is NOT considered to be part of the directory
name -- it is treated as a flag!
Example:
CERN_ISMAP="MAPCERN/ HTIMAGE/"
Notes
* The trailing / in the above example(s) is optional.
* The "map file location" is interpreted using the regular SRE-http rules
(relative to the GoServe data directory, or to a virtual directory)
* For NCSA style image maps, see the NCSA_ISMAP variable.
*******
CGI_BIN_PIECES
CGI_BIN_PIECES enables the CGI-BIN "send pieces as they become available"
mode.
One problem with cgi-bin scripts is that if you have lengthy output, or a
compute intensive script that writes stuff in spurts, the client has
to wait for everything to be done before recieving any output.
If this takes more then several seconds, the client may get discouraged,
and disconnect. Even worse, if one has the "end client after inactive"
set low (say, 15 seconds), there may be times when the server kills the
request even though a lengthy script has yet to finish.
To deal with these situations, SRE-http can send CGI-BIN output
to the client "as it becomes available". To enable this mode, just set
the CGI_BIN_PIECES parameter:
0 : Do NOT send output in pieces; wait until the script is done,
and then send the whole thing
1 : Send output in pieces, using FILEREXX procedures
Example: CGI_BIN_PIECES=1
Caution:
For reasons we can't figure out, sometimes partial loads of
FILEREXX functions don't seem to "stick" when done from within
a GoServe thread. However, the same calls when done from a
different session (that is, from some program running under
a different invocation of CMD.EXE) work.
Therefore, if you are getting "can't find procedure" errors
(RC=43); you can try running the following program before starting
GoServe:
/* Program to preload filerexx procedures */
say " This will preload several FILEREXX procedures"
if rxfuncquery('fileread_rxf')=1 then do
goti1=RxFuncAdd('Fileread_rxf', 'FILEREXX', 'FILEREAD')
if goti1=1 then
say " Error: unable to load FILEREAD FILEREXX functions "
end
if rxfuncquery('fileopen_rxf')=1 then do
goti2=RxFuncAdd('Fileopen_rxf', 'FILEREXX', 'FILEOPEN')
end
if rxfuncquery('fileclose_rxf')=1 then do
goti3=RxFuncAdd('Fileclose_rxf', 'FILEREXX', 'FILECLOSE')
end
if rxfuncquery('fileclose_rxf')=1 then do
goti3=RxFuncAdd('Fileclose_rxf', 'FILEREXX', 'FILECLOSE')
end
if rxfuncquery('fileseek_rxf')=1 then do
goti3=RxFuncAdd('FileSeek_rxf', 'FILEREXX', 'fileseek')
end
if rxfuncquery('filegetinfo_rxf')=1 then do
goti3=RxFuncAdd('Filegetinfo_rxf', 'FILEREXX', 'filegetinfo')
end
exit
Notes
* on the !CGI-BIN_n server directives:
If you need to use the "send pieces" mode occasionally, and the
"standard" mode on other occasions, you can use the !CGI-BIN_n
(where n=2,3) "server directives" (see SREHTTP.HTM for further
discussion of the !CGI-BIN_n "server directives").
*******
CGI_POST_LONG_GET
Due to limitations on the number of characters that can be included on an OS/2
command line, GET method CGI-BIN requests can not have argument lists
(information after the ?) longer then 245 characters. Furthermore, environment
strings should not be greater then about 1000 characters.
To work around these limits, SRE-http can convert long GET requests into POST
requests.
To do this, set CGI_POST_LONG_GET=nnnn, where nnnn is the size at which
this conversion takes place.
Example: cgi_post_long_get=1000
For this to be useful, your CGI-BIN scripts will need to understand how to
detect and read POSTed information.
Notes:
For backwards compatability:
0 = infinity
1 = 245
Note that if nnnn>245, the "command line argument" will be truncated to
245 characters. Thus, as a general principle you should use QUERY_STRING
to obtain the request line options.
********
CUSTOM_INITS
CUSTOM_INITS can contain a list of REXX procedures to run when first starting
GoServe/SRE-http. Typically, these will be custom-written procedures
that will perform special, one-time actions; such as starting up a database
server, or "preloading" URL's into the GoServe cache.
CUSTOM_INITS should be a comma delimited list, with each entry containing
the name of an external procedure, followed by an optional argument.
If you do NOT want to run any initialization procedures, set CUSTOM_INITS=0.
Examples:
custom_inits=0
custom_inits='preload '
custom_inits='preload , userproc Web Server 1 '
where the "Web Server 1" is an argument that will be sent to the userproc
external procedure.
Notes:
* These procedures are executed very early in the
SRE-http initialization processs (i.e.; before reading INITFILT.80).
* SRE-http waits until these procedures finish. Thus, if these
procedures stay resident, or otherwise take a long time to complete,
YOU SHOULD INVOKE A NEW PROCESS (OR THREAD). That is, the external
procedure should immediately invoke a new process (or thread), and
then exit.
* An (optional) argument list should NOT contain commas!
* External procedures should be stored in files in the GoServe directory.
These files should have the same name as the procedure, and
should have a .CMD (or .80) extension.
For example, if Custom_inits='preload',
then a PRELOAD.CMD file should be in the GoServe directory.
Suggestion:
The PRELOAD addon to SRE-http is a useful example: the PRELOAD.CMD
file (invoked by setting custom_inits='PRELOAD') will call a "preload
URL's" daemon (PRELOAD.RXX).
***********
DEFAULT_ENCRYPTION
The default encryption algorithim. This default is used when an
!ENCRYPT/selector is requested, or when an advanced-options file
contains SET ENCRYPT.
Currently, two algorithims are supported: SRE_A and SRE_B.
Example: DEFAULT_ENCRYPTION='SRE_A'
********
DELAY_SECONDS
Delay_seconds controls how frequently SRE-http
checks input files for updates. Larger values mean more time between
checks. If you never change initialization parameters, etc. you can
set this to a high value (say, 1000) to reduce the load on the server.
Example:
delay_seconds=9
Note: you can always force SRE-http to re-read files by issuing a
!RESET request to your server.
*********
DELTA_ENCODING_ENABLE
Enable support for delta-encoding
0 = disable
1 = allow sel-specific support for delta encoding
2 = allow delta encoding for all requests
Example:
delta_encoding_enable=0
See DELTA.DOC for the details.
*********
DELTA_ENCODING_MAXSIZE
Size of the delta_encoding_cache, in kbytes.
Example:
delta_encoding_maxsize=5000
See DELTA.DOC for the details.
*********
DIGEST_AUTH
Enable the use of "digest" authentication. If you never talk to http/1.1 clients,
you can save some time by suppressing this.
DIGEST_AUTH=1 ; try to use digest authentication
DIGEST_AUTH=0 ; do not use digest authenticaion
Technically speakin, when DIGEST_AUTH=1, then a WWW-Authorize: Digest xxxx
response header is added to the response before a WWW-Authorize: Basic xxx
response header.
**********
DIR_CACHE_DURATION
DIR_CACHE_DURATION is used by SRE-http's !DIR facility. It is the lifespan
(in days, or fractional days) of entries in the "directory listing cache".
Example: DIR_CACHE_DURATION=3
**********
DIR_CACHE_SIZE
DIR_CACHE_DURATION is used by SRE-http's !DIR facility. It is the
maximum size (in Kbytes), of the "directory listing cache".
Example: DIR_CACHE_SIZE=1000
Notes:
* setting DIR_CACHE_SIZE=0 will suppress use of the directory listing
cache.
* directory listing "cache files" are stored in the TEMPDATA_DIR, with
names of _nnnnn.DSH (i.e.; _0000012.DSH). There is also a
_DIRLIST.IDX file used as an index to these listings).
***********
DYNSSI_MAXAGE
The number of seconds a cache can maintain a document that has
"dynamic" SSIs. To force all caches to always revalidate
any document that has a dynamic SSI in it, set
DYNSSI_MAXAGE=0
To allow caches to use a response, that contains "dynamic SSIs"
for two minutes (after which it must revalidate), set
DYNSSI_MAXAGE=120
Notes:
* an s-maxage limit (as specified in PROXY_CACHE) can not exceed this
value (if it does, it will be adjusted down).
* the SSI-phrase is used for resources
that have static SSIs.
***********
EMPTY_PATH_OK
Empty_path_ok is a CGI-BIN option: it controls the value of
the PATH_INFO and PATH_TRANSLATED "environment variables".
In particular, when there is no PATH_INFO sent (i.e.; a
request of /CGI-BIN/TEST-CGI?ARG1 has no PATH_INFO specified),
there are two possibilties:
EMPTY_PATH_OK=1. PATH_INFO (and PATH_TRANSLATED) are set to
an empty string (no spaces). In addition,
the SCRIPTNAME is preceded by /CGI-BIN/.
This seems to be more of a standard (ICS and
the NCSA.1.5.2 servers use it).
EMPTY_PATH_OK=0 PATH_INFO='/' and PATH_TRANSLATE='the GoServe
data directory'.
This is what Don Meyer's GOHTTP uses.
Notes:
* we know of several scripts that expect an empty PATH_INFO environment
variable when none is specified, and will fail if EMPTY_PATH_OK=0.
* to control which is used on a "selector specific basis", you can use
the !CGI-BIN_1 and !CGI-BIN_0 (or !CGI_BIN_2 and !CGI-BIN_3)
"special directives".
***********
ENABLE_ENCRYPTION
Enable SRE-http's encryption. Allowed values include:
0 : disable
1 : enable for non-addon responses
2 : enable for all responses
3 : force encryption of ALL response
1 and 2 are quite similar, but 1 may fail to encrypt responses that are
generated by some older SRE-http addons. However, it's a bit quicker.
See ENCRYPT.DOC for more details.
*********
EVENT_CHECK
Check for events.
SRE-http's monitor daemon can check a set of administrator specified
events. These events, which are specified in EVENTS.CFG,
will be checked every EVENT_CHECK minutes.
To never check events, set EVENT_CHECK=0
Examples:
EVENT_CHECK=0
EVENT_CHECK=15
For details on event checking, see EVENTS.DOC.
**********
GET_DECODE_OPTIONS
By default, when SRE-http sends "GET request options" (the stuff
after a ?) to an addon, it will first "URL decode" them. That is, SRE-http
will convert %2b to +, etc.
While this can save you a step, it can cause trouble when the request may
contain these special characters (i.e.; +, &, and =). Although you
can use the URI argument, you may find it convenient to suppress this
decoding instead.
GET_DECODE_OPTIONS=1 : URL decode
GET_DECODE_OPTIONS=0 : do NOT URL decode.
Example:
GET_DECODE_OPTIONS=1
**********
HEAD_TO_GET
Tell addons that HEAD methods are GET methods -- this is done by
sending GET as the "VERB" argument (see MK_ADDON.HTM for details on
how addons are called). In this case, addons can get the true
verb by using EXTRACT('CLIENTMETHOD')
Enabling this can be help some older addons, that don't recognize
HEAD requests. (note that on HEAD requests goserve never sends
the body of a response, even if one is produced).
To enable this, set head_to_get=1
Example: head_to_Get=0
**********
HIT_SUPERUSER_SUPPRESS
If HIT_OWNER_SUPPRESS is enabled (see description above), then
"OWNERS" will not have their hits recorded (in the RECORD_ALL_FILE
and in the hit counter file).
You can extend the "range" of HIT_SUPERUSER_SUPPRESS to include SUPERUSERs by
setting HIT_SUPERUSER_SUPPRESS=1. That is, if HIT_OWNER_SUPPRESS=1 and
HIT_SUPERUSER_SUPPRESS=1, then requests from OWNERS and from SUPERUSERs
will NOT be recorded.
Otherwise (if HIT_SUPERUSER_SUPPRESS=0), SUPERUSER requests will
be recorded.
Example:
HIT_SUPERUSER_SUPPRESS=1 (the default is 0)
Note: if HIT_OWNER_SUPPRESS=0, then HIT_SUPERUSER_SUPPRESS is ignored
(that is, SUPERUSER requests will be recorded).
**********
NCSA_ISMAP
The value(s) in the spaced delimited NCSA_ISMAP variables are used
to indicate that this "is an image-map request". You can specify several
different values (though you should only use one of them in your "image map"
URL).
When one of these identifier-strings appear in a request selector,
SRE-http assumes that the request "is a response from a mappable image"
For example, if NCSA_ISMAP='/MAPIMAGE', then selectors (that are generated
by clicking on a mappable image) of the form:
/MAPIMAGE/GIFSDIR/USMAP.MAP?123,312
will be interpreted as ...
pixel 123,312, in combination with the instructions contained
in /GISDIR/USMAP.MAP, is used to determine which URL to redirect
the client to (where USMAP.MAP is an NCSA style MAP file)
IMPORTANT NOTE: the MAPIMAGE/ is NOT considered to be part of the directory name --
it is treated as a flag!
Example:
NCSA_ISMAP="MAPIMAGE/ NCSAIMG/"
Notes
* The trailing / in the above example(s) is optional.
* The "map file location" is interpreted using the regular SRE-http rules
(relative to the GoServe data directory, or to a virtual directory)
* For CERN style image maps, see the CERN_ISMAP variable.
*********
KEY_PREFACE
If the REPLACE, INCLUDE, OPTIONS, INTERPRET and SELECT "keywords"
appear at the beginning of real comments (and you are using the
default "server side keyphrase" delimiters of ), you
might want to add a "preface" to these keywords. For example,
you can add the ! character, so that SRE-http will look for
!REPLACE, !INCLUDE, etc.
Note that KEY_PREFACE=0 or KEY_PREFACE='' means "do not add a preface".
Also note that the # can not be used as a preface (since it is
used by the HTTPD-style #INCLUDE keyphrase).
Examples:
KEY_PREFACE='!'
KEY_PREFACE=0
********
LOGON_LIMIT
As a security measure, SRE-http's "authorization facility" can limit
the number of unsuccessful attempts, per IP address per minute. When this
limit is exceeded, for the next minute further attempts (from this IP address
will be immediately denied.
To enable this, set LOGON_LIMIT to the number of logon attempts per minute.
A value of 0 means "no limits".
Examples:
LOGON_LIMIT=0
LOGON_LIMIT=3
Warning: do NOT use LOGON_LIMIT=1 (it causes odd problems)
Note: the authorization facility handles all client answers to
"401 Unauthorized" server responses. These include "logon" requests
and "SEL-specific" access requests.
********
MAIN_SERVER
The numeric IP address of a "main server". The MAIN_SERVER variable
is used to expedite responses to certain requests -- in particular,
HEAD !PING requests from this "main server" are answered quickly, with
no recording (except in the GoServe audit file). One use of this
is to help implement dynamic load balancing.
Example:
Main_server='151.125.21.61'
Special cases:
main_server=0 --- suppress
main_Server='' --- use "own ip" address.
********
MESSAGE_SCRAMBLE
MESSAGE_SCRAMBLE is used to "encrypt" message-box passwords.
You can change it for a wee bit extra security (though security is never going
to be great).
MESSAGE_SCRAMBLE is also used to create "nonces" (nonces are used by digest
authentication).
Example:
message_scramble=12415
( message_scramble should be an integer less than 1 million and greater
then 0).
WARNING: If you change this, existing "message" passwords will not be
decodable! That is, they won't work anymore.
Similarly, outstanding nonces (from clients that retain such
information) will not work.
Note: only the password, which is just used to control deletion rights,
is encrypted.
***********
NO_NO_RECORD
The NO_NO_RECORD option can be used to suppress the !NORECORD directive.
One reason to suppress !NORECORD is to prevent tricky clients
from sneaking by your audit mechanisms.
To disable the !NORECORD directive, set NO_NO_RECORD=1
To enable it, set NO_NO_RECORD=0
***********
PRE_REPLY_PROCEDURE
The PRE_REPLY_PROCEDURE is used to specify an external REXX procedure;
this procecure will be given a chance to modify a response just before
sending it to the client -- it's a "last second" hook into SRE-http.
To clarify: PRE_REPLY_PROCEDURE specifies a rexx procedure that will do
"final" modifications to content that is to be sent to the client.
For example, a PRE_REPLY_PROCEDURE could be used translate text
responses (such as file's determined using the usual SRE-http
aliasing, etc. rules) into a different code-page.
PRE_REPLY_PROCEDURE should be equal to 0, or to a fully qualified filename.
* A value of 0 means "do not call a pre-reply procedure.
* A fully qualified filename should point to a file containing a REXX procedure.
The input and output structure of this procedure are fully described in
PREREPLY.DOC
* Special format: to only use a pre-reply procedure on a selector specific
basis, pre-pend an exclamation point to the filename.
Examples:
PRE_REPLY_PROCEDURE=0
PRE_REPLY_PROCEDURE='E:\GOSERVE\PREREPLY.CMD'
PRE_REPLY_PROCEDURE='!E:\GOSERVE\SRERsync.CMD'
Notes:
* You can use the SET PRE_REPLY 0 "advanced option" to suppress the
use of a pre-reply procedure on a selector specfic basis.
Conversely, you MUST use the SET PRE_REPLY 1 "advanced option" to
enable the use of a "selector specific" pre-reply procedure.
Note that by "selector specific" pre-reply procedure, we do NOT
mean that different selectors can have different pre-reply
procedures; we do mean that "the global pre-reply procedure will
only be called when a selector specific flag allows it".
See ADV_OPTS.DOC for details on the PRE_REPLY advanced option.
* Since this entails an extra step, use of the PRE_REPLY_PROCEDURE will
slow down throughput.
* We recommend using PRE_REPLY_PROCEDURE only when there are no other
alternatives.
* SRE-http will load this procedure into macrospace, under the
name SREF_PREREPLY_PROC.
***********
PROXY_CACHE
PROXY_CACHE is used to control the extent to which GoServe, SRE-http,
and proxy caches will cache responses.
Set PROXY_CACHE=0 to disable, or limit, proxy caching --
PROXY_CACHE can take the following values:
0= disallow all caching
All caching is disallowed: including user-agent caches,
caches on proxy servers, and the SREPROXY "proxy-like" front
end to SRE-http.
1= allow caching
Caching is allowed by user-agents, proxy servers, and SREPROXY.
2= allow storage of response, but force all caches (proxy and user-agent)
to revalidate (using an If-modified or If-no-match) before using.
3= similar to 2, but applies only to shared (proxy) caches. User-agent
caches do not need to re-validate.
Example:
PROXY_CACHE=1
In addition, you can specify a "max-age" -- which is how long
an item can be retained in a cache before it is validated.
By default;
1: infinite max-age
2 and 3: 0 seconds maxage (always re-authenticate)
To do this, simply use
PROXY_CACHE=n_maxage
where
n=0,1,2, or 3
maxage= maximum age of cache entries in seconds.
For example:
PROXY_CACHE=1_86400
PROXY_CACHE=3_1800
In most cases PROXY_CACHE=1 is recommended. However, if you need to accurately
audit the use of all resources, the use of 2 or 3 is a reasonable compromise
(it allows caches to respond to a request, but your server is informed of
each request).
You might also wish to use 1_86400 if your "static" resources occassionally
change (this tells caches to re-validate their cache entry every day).
If you do use PROXY_CACHE=1, and wish to have improved (though
not necessarily 100% accurate) counts, you can use the METER: selector-
specific advanced option (see ADV_OPTS.DOC and HITMETER.DOC for the details).
Note: for resources that contain "dynamic SSI's", the _nnn value
may be reduced to the value of DYNSSI_MAXAGE.
***********
NEVER_IMAGEMAPS
If you never use server side imagemaps, you can save a fraction of a second
(on some requests) by suppressing SRE-http's "check if this is an
imagemap request".
NEVER_IMAGEMAPS=1 : Suppress imagemap checking
NEVER_IMAGEMAPS=0 : Check for imagemaps
Example:
NEVER_IMAGEMAPS=0
***********
NEVER_PUBLICURLS
If you never use PUBLIC_URLs, you can save a fraction of a second
(on some requests) by suppressing SRE-http's "check if this selector
matches a PUBLIC_URL"
NEVER_PUBLICURLS=1 : Do NOT check if this selector matches a public_url
NEVER_PUBLICURLS=0 : Do check.
Example:
NEVER_PUBLICURLS=1
***********
NO_REMOTE_CONFIG
SRE-http is designed to be remotely configurable; with most of
the SRE-http parameters, virtual directories, usernames, etc. settable
by a SUPERUSER running a web browser from anywhere in the world. This is a
great convenience, but can be somewhat of a security risk.
If you desire, you can use the NO_REMOTE_CONFIG parameter to
disable this "remote configuration" feature.
NO_REMOTE_CONFIG can take values of:
0 : Allow remote configuration (by clients with a SUPERUSER privilege)
1 : Disallow remote configuration, but allow configuration (using
the SRE-http configuration forms) from clients sitting at the
server (this entails a check of the client's IP address against
the server's IP address).
2 : Disable all remote configuration -- to modify any SRE-http parameter
you will have to edit the various ascii parameter files.
Example:
NO_REMOTE_CONFIG=0
Note: The CHECKIT parameter in SREFCONF.CMD, CONFIG2.CMD, and the
*CFG.CMD files can also be used to suppress remote configuration.
***********
PMPRINTF_OPT:
To lend extra flexibility to SRE-http's run-time auditing, and to catch a few
bugs in the REXXLIB PMPRINTF; SRE-http now uses its own version
of PMPRINTF (PMPRINTF_SREF), Furthermore, SRE-http uses a seperate
thread to do the actual screen & file output, this thread will
"lazy write" output, with consequent reduction in disk & screen overhead.
You can control the output of PMPRINTF_SREF by setting the PMPRINTF_OPT parameter.
PMPRINTF_OPT can take values of:
1 : Use PMPRINTF window
2 : Use PMPRINTF window and SREHTTP.LOG file
3 : Use SREHTTP.LOG only
SREHTTP.LOG will be written to the GoServe working directory.
Notes:
* Ambitious webmasters can change the name of this log file,
and the "maximum line length", by adjusting a few parameters
in SREFMON.CMD.
* Very ambitious webmasters can change the "lazy write" rate, and
can add a special preface to PMPRINTF output, by adjusting a
few parameters in PMPRINTF.RXX.
* Common-log output that is sent to the PMPRINTF window (when VERBOSE>0)
will NOT be written to the SREHTTP.LOG (that would be redundant, since
it's already being written to the COMMON.LOG file)
***********
PUT_NO_OVERWRITE
When accepting PUT method requests, SRE-http can either overwrite
a pre-existing file, or it can refuse to overwrite.
PUT_NO_OVERWRITE = 1 : do NOT overwrite (send back an error response)
PUT_NO_OVERWRITE = 0 : overwrite
Note that the file is determined by the selector supplied by the
client; after adding the GoServe default data directory (or a virtual
directory).
Example:
PUT_NO_OVERWRITE=1 (the default)
***********
QUICK_INTERP
To facilitate the use of in-line REXX code for server side includes;
you can use a shorthand for the
keyphrase. In particular, you can use a $ instead of INTERPRET FILE:
as in
If you'ld rather use some character other then $, just change the
QUICK_INTERP parameter.
Example:
QUICK_INTERP='$'
Note: Be sure that the values for QUICK_INTERP and QUICK_INTERP_CODE
are different!
***********
QUICK_REPLACE
You can use a shorthand for the
keyphrase. In particular, you can use a % instead of REPLACE:
as in or
If you'ld rather use some character other then %, just change the
QUICK_REPLACE parameter.
Example:
QUICK_REPLACE='%'
***********
QUICK_INTERP_CODE
To facilitate the use of in-line REXX code for server side includes;
you can use a shorthand for the
keyphrase. In particular, you can use a $ instead of INTERPRET CODE:
as in
If you'ld rather use some character other then #, just change the
QUICK_INTERP_CODE parameter.
Example:
QUICK_INTERP_CODE='#'
Note: Be sure that the values for QUICK_INTERP and QUICK_INTERP_CODE
are different!
***********
REALM_1ST_PRIV
If no "sel specific realm" is specified (in the access control file),
the value of the first resource privilege can be used as the realm name.
To enable this, set REALM_1ST_PRIV=1. Otherwise, the DEFAULT_REALM
parameter will be used.
Example:
REALM_1ST_PRIV=0
Note: If you:
use just one resource privilege per selector,
specify REALM_1ST_PRIV=1, and
never set an explicit "sel-specific realms"
then
the "realm" is equivalent to the "resource privilege list".
***********
RECORD_CACHE_LINES:
This controls the size of the "request recorder" cache.
Shrinking the size of this cache (say, if you don't have
many documents) will free up memory. Increasing it (say, you
have a large site, and a lot of RAM) will speed up request
recording. In addition, since the RECORD_ALL_FILE is backed up and
then reset when the cache grows beyond RECORD_CACHE_LINES, a larger
cache may reduce fragmentation of these RECORD_ALL_FILE audit files.
To suppress caching, set RECORD_CACHE_LINES=0
Example:
RECORD_CACHE_LINES=750
************
SEM_MAXWAIT
The "independent threads" that help SRE-http work by waiting on
queues. The waiting is partially contolled by a semaphores, which are
set whenever anything is written to a queue. Since OS/2 can be a mite
slow about writing semaphores, it is sometimes convenient to check
the queue, and then go back to waiting if nothing is there.
To increase the frequency that this "check queue even though the semaphore
hasn't been set" occurs, select a low value of SEM_MAXWAIT. Note that
SEM_MAXWAIT is in milliseconds, so values under 100 are considered low.
A possible drawback is that the smaller SEM_MAXWAIT is, the more
SRE-http will engage in useless queue examinations. The best value to
use should be determined by experimentation.
Example: SEM_MAXWAIT=15000
*********
SSI_EXTENSIONS: File extensions that are equivalent to SHTML.
The SSI_EXTENSIONS variable contains a space delimited list of file extensions
that will be treated as "SHTML" files. That is, when SSI_SHTML_ONLY='YES',
only files with one of with these extensions will have server side
includes added.
If you add to this list, you may also need to specify that the file is a
text/html MIME type. To do this, you should add entries to the MEDIATYP.RXX
file located in the GoServe directory.
Note: SRE-http's default value of ssi_extensions is:
ssi_extensions=' SHT SHTML HTML-SSI HTM-SSI '
****************
SSI_CACHE_SIZE
SSI_CACHE_SIZE is used to set the size of the "server side include cache".
You should enter the size in Kilobytes. For example:
SSI_CACHE_SIZE=5000 (the default)
corresponds to a cache size of 5M.
Notes:
* For further discussion of SSI-caching, please see the SSICACHE.HTM
file.
* Cached files are stored in your TEMPDATA_DIR directory (typically,
GOSERVE\TEMP). They have names of _CS?????.80 (or .nnn, if you are
using port .nnn).
* Once the size of the cached files exceeds this amount, the oldest
entries will be deleted (where oldest is measured in terms of
"last requested").
* Setting SSI_CACHE_SIZE=0 will turn the SSI-Cache off (regardless of
the value of SSI_CACHE_ON).
****************
SSI_CACHE_DURATION
SSI_CACHE_DURATION is used to set (in days) the "lifespan"
of entries in the server side include cache.
After this lifespan has been exceeded, the entry will die.
This helps ensure that documents do not get "too far" out of
date (thus, egregious out-of-sync errors won't last forever).
Examples:
SSI_CACHE_DURATION=0.5 -- a 12 hr. lifespan.
SSI_CACHE_DURATION=30 -- a 30 day lifespan
SSI_CACHE_DURATION=0 -- infinite lifespan
Note:
You can use the SSI keyphrase
to override this "default" value on a file-by-file basis.
****************
SSI_CACHE_STAMP
The SSI_CACHE_STAMP dictates which fields to use when determining
whether a SSI-cache "trigger" file has changed. SSI_CACHE_STAMP
can have one of the following values:
ALL -- Use time,date, and size (if any change, the trigger is considered
to be out-of-sync)
DATE -- Just use the date
TIME -- Just use the time (hr/minute)
DATETIME -- Use the time and date
SIZE -- Just use the size
Note:
You can use the SSI keyphrase,
where stamp is one of the above values, to override this "default"
value on a file-by-file basis.
****************
USER_LOGON_PROC
In some circumstances, you might want to use an external program to
check & store usename/password/privilege information (and thereby
not use SRE-http's USER.IN and ATTRIBS.IN databases, and related procedures).
To do this, set USER_LOGON_PROC=procedure_name, where procedure_name
is an external procedure (either on disk, or preloaded into macrospace).
Examples:
USER_LOGON_PROC=' ' (use SRE-http's procedure)
USER_LOGON_PROC="MY_LOGON" (use the MY_LOGON procedure)
USER_LOGON_PROC="SREF_USER_LOGON" (use the SREF_USER_LOGON
macrospace procedure)
SRE-http will pass 3 arguments to this USER_LOGON_PROC preocedure.
1) The 1st argument is a space delimited list consisting of:
if BASIC authentication is used: USER PASSWORD CLIENT_IP_ADDRESS
if DIGEST authentication is used: USER CLIENT_IP_ADDRESS
(where USER and PASSWORD are extracted from the AUTHENTICATION request header).
2) The 2nd argument is the "servername"
3) The 3rd argument is the host_nickname
This procedure MUST return the following
STATUS PRIVILEGE_LIST
(The privilege list is optional)
The status must be an X, or an integer. These values mean:
X : Excluded -- let the regular SRE-http logon procedures do the job instead.
0 : Logon unsuccessful
>=1 : Logon successful (the value identifies which "record" matched, and is
not currently used -- a value of 1 for all success
will suffice)
<0 : Logon unsuccessful, this (absolute value) is the "nth" try. This
"nth try" value is used by the
LOGON_LIMIT facility of SRE-http. You can
always use 0 for "failure", in which case
the LOGON_LIMIT stuff will not work.
Notes:
* you can use the USER_LOGON_ENABLE procedure to enable or disable the
use of the USER_LOGON_PROC on a host specific basis, or to specify
host specific values of USER_LOGON_PROC.
* see the discussion of USER_LOGON_ENABLE for details on using user logon
procedures on a multi-host server.
****************
WILD_SELS_OK
As a convenience, you can permit asterisk (*) containing selectors, where
the * is treated as a wildcard character.
If such a selector is requested, then SRE will search the appropriate
directory for the a wildcard match, and use that file or display
a directory-style listing of all matches.
For example (assuming the GoServe data directory is D:\WWW):
If the selector is /DINOS/BRON*.JPG (and WILD_SELS_OK=1),
then SRE will find all files that match D:\WWW\DINOS\BRON*.JPG,
and use the shortest one (i.e.; the best match is D:\WWW\DINOS\BRON.JPG)
In fact, you can even instruct SRE to look at all "subdirectories" of
the selector. Thus, the above example one might yield
D:\WWW\DINOS\veggies\brontos.JPG.
WILD_SELS_OK can take the following values:
0 : Do NOT search
1 : Search the own directory
11 : Search the own directory. If multiple matches, display a directory
style listing of the matches (with links to each match)
2 : Search own directory and subdirectories
22 : Search the own directory and subdirectories. If multiple matches,
display a directory style listing of the matches (with links to each
match).
Example: WILD_SELS_OK=1
Notes:
* WILD_SELS_OK is ONLY used with GET requests for files; it is not used
for imagemaps, cgi-bin scripts, POST requests, or "addon"
requests.
* If WILD_SELS_OK=0, then a *-containing selector will always cause
a NOT_FOUND response.
* CAUTION: Use of WILD_SELS_OK can subvert access controls (especially when
you use WILD_SELS_OK=2). The problem is that SRE does NOT
check a "wildcard matched" file (or directory) against the
access control file.
SRE will check the original *-containing selector against the
access control file. Please note that in both the
access control and alias files, the * character has special
meaning -- hence you can not explicitily match a *-containing
selector (but you can "wildcard match" a *-containing selector).
* SRE will use the wildcard derived filename when it checks the HTACCESS
file.
* *-containing selectors will NOT wildcard match directories. That is,
you can only use * in the filename portion of a "directory/filename"
(it's like using a DIR AB*C.DEF /S command)
* You can include multiple *s in the selector. You can NOT include ?s
2i. ---- PARAMETERS in SREFMON.CMD ---
****************
CLEAR_MACROSPACE
SRE-http uses the macrospace procedures it loads from SREFPRC.RXL. If
ANY of the procedures stored in SREFPRC.RXL are already in macrospace,
it will NOT load SREFPRC.RXL. If you frequently update SREFPRC.RXL
(or the .SRF files) this may be a problem -- since the updates will
not get loaded.
There are two ways around this problem:
a) Shutdown GoServe, clear macrospace, and restart GoServe
whenever you update SREFPRC.RXL
(this is what the SRE-http install procedure does).
b) Set CLEAR_MACROSPACE=1, and shutdown/restart GoServe.
When CLEAR_MACROSPACE=1, SRE-http will "clear" macrospace,
and then load SREFPRC2.RXL.
Thus, use of CLEAR_MACROSPACE=1 saves you the trouble of explicitily
clearing macrospace. However, since macrospace is global to OS/2,
such an act may adversely impact other REXX programs.
Thus, use CLEAR_MACROSPACE=1 only if you KNOW that no other REXX
programs are using macrospace!
Example:
clear_macrospace=0 /* do NOT clear macrospace */
***************
CFGS_DIR
Fully qualified name of the directory containing the SRE-http configuration
files. If blank, a default (CFGS under the GoServe working directory) is used.
Examples:
CFGS_DIR='' (use the default; perhaps D:\GOSERVE\CFGS)
CFGS_DIR='D:\SERVER\CFGS1\CFGS'
In general, we STRONGLY recommend setting CFGS_DIR=''.
****************
DOANYWAY_LOOPS
SRE-http will reread its various parameter files whenever it detects a change.
Occassionally, a change may occur that is undetected (typically, when you
are making & saving changes rapidly). To catch such changes, SRE-http will
occasionally automatically re-read configuation files, even if no change is
detected. The DOANYWAY_LOOPS parameter controls this.
DOANYWAY_LOOPS is measured (approximately) in DELAY_SECONDS units (by default,
15 seconds). The default value of DOANYWAY_LOOPS of 300 means "redo every
300 loops", about 1.25 hours.
Example:
doanyway_loops=300
****************
DO_CLEANUP
When CGI-BIN scripts are run, they create several temporary files.
Should a CGI-BIN script abort prematurely, or otherwise fail, these
files will be left behind. In order to keep disk clutter to a minimum,
SRE-http can occasionally remove "orphaned" CGI-BIN temporary files.
DO_CLEANUP=1 : Enable this "orphaned files" removal
DO_CLEANUP=0 : Suppress this "orphaned files" removal
Note that the file time/date is used for this removal. If you have scripts that
stay active for days, you might have problems using DO_CLEANUP=1!
***************
USE_LIB_DIR
Fully qualified name of the directory containing the SRE-http dynamic
macrospace library procedures. If blank, a default (LIB under the
GoServe working directory) is used.
If you installed SRE-http with a non-default "sre-http" library directory,
you must set this.
Examples:
USE_LIB_DIR='' (use the default; perhaps D:\GOSERVE\LIB)
USE_LIB_DIR='D:\PROCS\SRELIB'
In general, we STRONGLY recommend setting USE_LIB_DIR=''.
***************
LOGFILE_MAXSIZE
The maximum size of common, referer, browser and combined log files
(in Kbytes).
When one of these files exceeds this size, it will be renamed using
a sequentially numbered extension. Thus, the first time common.log
gets large,it will be renamed to COMMON.001; and the second time
it will be renamed to COMMON.002 (etc. etc. etc.)
To suppress this auto-renaming, set LOGFILE_MAXSIZE=0
Examples:
LOGFILE_MAXSIZE=0
LOGFILE_MAXSIZE=1000
where 1000 means 1M (1000 kilo bytes).
Notes:
* File sizes are checked occasionally. Thus, on rare occassions the size of
a log file file will exceed this maxsize by a few kbytes.
* Reminder: LOGFILE_MAXSIZE=1000 means "maximum size of 1Mbyte"
* The LOG_TOOBIG parameter (in POSTFCHK.RXX) is no longer used. Thus,
warnings about your log file becoming too large will NO LONGER be written
to the PMPRINTF window.
* For finer control of the renaming of log files, you should set
LOGFILE_MAXSIZE=0, and use the RENLOGS.CMD utility (see SCHEDULDE.DOC
for details on running scheduled events)
****************
MD5_CACHE
The MD5_CACHE is an optional daemon that will take care of computing
MD5 digests (for inclusion in a Content-MD5 response header).
If you set MD5_CACHE to be a non-zero value, then SRE-http
will launch an MD5 daemon (as a seperate process), and this
daemon will create a cache for up to MD5_CACHE entries.
When an MD5 digest is needed, the daemon will first check this cache,
and if a match is found (and the file has not changed), then the
MD5 digest stored in the cache will be used. Otherwise, an MD5 digest
will be computed.
If MD5_CACHE=0, then the MD5 daemon will NOT be launched, and an
MD5 digest will always be re-computed.
Examples:
MD5_CACHE=0 /* no md5 daemon */
MD5_CACHE=800 /* store up to 800 md5 digests */
Notes:
* The MD5_CACHE is only used if CONTENT_MD5=1.
Thus, if CONTENT_MD5=0,
then you might as well set MD5_CACHE=0.
* There are two reasons for using the MD5 daemon
i) For large files, computing the md5 digest may be time consuming;
hence maintaining a cache of values can improve throughput.
ii) As noted above, on rare occasions the MD5 digest procedure will
throw a sys3175 error (and crash goserve). Placing
the daemon in a seperate process isolates this crash from GoServe.
****************
MEDIATYPE_FILE_ALWAYS
To determine the content-type (the mimetype) of a response, SRE-http
uses an "extension to mimetype" mapping strategy.
Basically, the selector's extension (i.e.; HTML in FOO.HTML) is compared
to a list of mappings, the mapping that contains the selector's extension
also contains its mimetype.
By default, SRE-http will use a hard-coded set of mappings. You can
add to, or override, these defaults, by changing the MEDIATYP.RXX file.
MEDIATYPE_FILE_ALWAYS is used to control whether SRE-http will
always read this MEDIATYP.RXX file, or it whether it reads
MEDIATYP.RXX only when none of the default mappings work.
MEDIATYPE_FILE_ALWAYS=0
Only check MEDIATYP.RXX when no default "extension to
mimetype" entry can be found.
MEDIATYPE_FILE_ALWAYS=1
Always check MEDIATYP.RXX, and allow MEDIATYP.RXX
entries to override default entries.
Notes:
* Default entries are hard coded in MEDIATYP.SRF (in the \LIB sudirectory).
* MEDIATYP.RXX is located7 in your GoServe working directory.
* For details on custom assignation of a selectors mimetype, see
SREHTTP.FAQ or see ADV_OPTS.DOC.
* If you NEVER use MEDIATYP.RXX to override defaults, you can speed things
up a bit by setting MEDIATYPE_FILE_ALWAYS=0.
Example:
MEDIATYPE_FILE_ALWAYS=1
****************
NO_DNS
If your access to a DNS is slow, or non-existent, SRE-http can take a
long time to process requests. This is caused by SRE-http waiting
for a timeout on a DNS request (as is needed when resolving a
client's ip name).
You can work around this problem by setting NO_DNS=1.
If NO_DNS=0, then DNS lookups will occur.
If NO_DNS=1, then DNS lookups will NOT occur -- the IP number
will be used instead of the IP name.
Example:
NO_DNS=0
****************
NO_SUPERCEDING_REALM
SRE-http uses "superceding realms" (specified in ATTRIBS.CFG) to
group several types of selector-specific information. This includes
information on whether the selector is a PUB_URL, its redirection
ALIASES, ACCESS controls, and VIRTUAL directory information.
If a selector matches a rule for a superceding realm, then no
other selector-specific information is looked for. That is, entries
in the various .IN files will not be used, and entries in
non-superceding realms will not be examined.
To suppress this special treatment of superceding realms, set
NO_SUPERCEDING_REALM=1 (superceding realm entries will still
be checked, but they will not "supercede" all other kinds
of entries).
For a further description of superceding realms, see IN_FILES.DOC.
Example:
NO_SUPERCEDING_REALM=0
****************
STORAGE_DAEMONS
By default (when STORAGE_DAEMONS=1), SRE-http will launch one instance
of the "variable storage daemon". There may be times where having
multiple instances of this daemon is beneficial. In particular,
if you are heavily using an SRE-http queue (via the SREF_QUEUE procedure),
assigning the queue to the "non-default variable storage daemon" can
improve throughput.
Examples:
STORAGE_DAEMONS=1 : Start one (the default) variable storage daemon
STORAGE_DAEMONS=3 : Start three instances (the default, plus two additional)
For more details on how to use these daemons with SREF_QUEUE, see SREFQUE.DOC
****************
USE_DYNAMIC_LIB:
If you wish to not use a "dynamic macrospace library", set
USE_DYNAMIC_LIB=0
HOWEVER -- you'll have to or create, using MAKELIB.CMD,
a "SREFPRC1.RXL" static macrospace library file, and store it
in your GoServe working directory.
Note that there is one good reason for using a "static" macrospace
library -- when using sre-http macrospace procedures in other (non-goserve)
programs, the dynamic procedures library may not be found -- which means
they won't be available.
In contrast, the static procedures,once loaded,are "all there".
========================================
Section 3. A Comparison of Local vs. Remote Redirection of URL's
One of the strengths of SRE-http is the variety of redirection
mechanisms it offers, where redirection implies "sending the client
a file that is not a direct mapping of the request selector". Redirection
has two general classes: remote and local.
"Remote" redirection, which is what most of the literature simply
calls redirection, involves telling the client's browser that
"the url you have requested has been moved to xxxx", where xxxx may
be any URL -- it need not be on the same server, and it need not have
the same name.
For example, an alias (in the alias-file) of
whatgot http://www.mine.org/dir1/index1.htm
would cause the server to send back a "302" response to the client's
browser whenever a request for "whatgot" arrives. This 302 response,
would instruct the client's browser to automatically request
http://www.mine.org/dir1/index1.htm.
"Local" redirection is handled solely by the server, and involves
substituting the "request selector" with another "request selector".
SRE-http has a number of methods of specifying "local redirection",
such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the
use of aliases of the form:
whatgot dir1/index.htm.
In all these cases, the browser assumes that the document it recieves
is a direct result of the original request selector issued.
While offering a real convenience, with less demands on the client,
local redirection can have undesired effects. In particular, "partial URLS"
in documents that were sent as the result of a local alias
may not work properly.
A short discussion of how browsers handle partial URLs is germane:
When a link (in an HTML document) is specified as a "partial URL"
(such as 
or )
the URL actually requested by the browser is determined by using
the "full" URL that invoked this html document.
For example, if the client asks for, and recieves:
http://www.mine.net/dir1/index.htm,
and index.htm contains a "partial URL" of:
,
the client's browser would then try to get:
http://www.mine.net/dir1/wow.gif.
In other words, when the browser is asked to get a partial url (that does NOT
begin with a /), it will take everything before the last / in the "parent" URL
(of the document that contains this partial URL) and then append the requested
partial URL.
(Actually, if a URL does not begin with http://, it will
append the "begins with / partial URL" to the http://.../ component of
the "full URL".)
The use of the "local redirection" features of SRE-http is
complicated by this "automatic resolution of partial URLS".
If you want to use local redirection you should:
1) fully specify the links in your documents ..
i.e.; use /dir1/foo.gif instead of foo.gif
2) Use a element in the of each document...
i.e.;
3) Don't use local redirection (just use remote redirection). This
entails the use of "remote" aliases instead of AUTO_NAME, DEFAULT,
and NOEXT_TYPE.
========================================
Section 3a. An example of local redirection.
Local redirection, despite its potential pitfalls, does provide some fairly
powerful configuration possibilitles. As an example, consider recording
"successful" transfers of one of several files: STUFF.ZIP and OTHRSTUF.ZIP.
i) The simple method.
Assume an HTML document with the following links
Get our stuff
or, get our other stuff
Also assume that RECORD_OPTION='YES'
When a client invokes one of these links, SRE-http will augment the
appropriate entry in the RECORD_ALL_FILE.
If you wish to record "each individual" request, you could wade through
SRE-http's "common-log" audit file. A better idea is to use SENDFILE with
the COUNTER option:
ii) Using SENDFILE, the above would be:
Get our stuff
or,
get our other stuff
The SENDFILE facility is used to transfer the document; and upon
successful transfer, the appropriate .CNT file is updated.
One nice feature of SENDFILE is that unsuccessful (or aborted) transfers
are explicitily noted. There is a minor problem: many browsers
(i.e.; Netscape) will give the client a default filename of "SENDFILE".
This will probably confuse a number of folks.
Fortunately, it's not hard to avoid this problem by using local redirection.
iii) Using local redirection, we use what looks like a standard URL, with
the following in the HTML document:
Get our stuff
or, get our other stuff
In addition, we include the following entries in the ALIAS_FILE:
stuff.zip sendfile?stuff.zip&counter=file=stuff
othrstuf.zip sendfile?othrstuf.zip&counter=file=othrstuf
When a request for "stuff.zip" arrives, SRE-http uses the
sendfile?stuff.zip&counter=file=stuff alias. The client's browser
doesn't know this, and will assume the file's name is stuff.zip
(which is the desired assumption).
This use of aliases could not be replicated with virtual directories, or with
remote redirection!
--- End of Document.