The SRE-http Web Server
version 1.3h
Introduction
SRE-http
is an http/1.1 compliant WWW Server for OS/2.
Written in
REXX,
SRE-http is designed to run as filter under
GOSERVE, an IBM EWS Internet Server.
SRE-http provides a
number of useful features including:
This document describes how to use SRE-http.
While not necessary,
the reader should first examine
the documentation that comes with GoServe (GOSERVE.DOC). Knowledge of the
REXX
programming language would also help. However, you can still do a lot of nice stuff with only a
rudimentary understanding of GoServe, or of REXX. Lastly, if you don't know
HTML, the
"markup language" of
the world-wide web (WWW), then it's going to be hard to do anything interesting!
Before reading this manual,
we strongly recommend that you peruse the
SRE-http users guide --
it's a much easier read!
Other useful documentation files include:
Other GoServe filters.....
An older alternative to this
filter is Don Meyer's
GoHTTP HTTP filter system.
GOHTTP offers
CGI-BIN, HTACCESS compatability, common-log auditing, and
rudimentary support for server side includes.
Another alternative is
the InterFilt filter of Derek Sims. It has good support for multiple realms and
multiple hosts, but lacks server side includes and other features.
Notes to upgraders
For most sites, upgrading SRE-http from version 1.2 should present few difficulties -- most of the
user-configurable options have not changed. However, there have been a few changes
to minor features (and a few rarely used features have been dropped). Furthermore, SRE-http
addons should be upgraded; current versions of the addons will work, but will
not be http/1.1 compliant.
Please read
the HISTORY.TXT file for a complete listing of these changes.
Table of Contents
1) Installation Notes
SRE-http consists of a filter
program
(SREFILTR.80 or SREPROXY.80), numerous support procedures and daemons
(such as SREFMON.CMD), sample pages, and various and sundry documentation files.
As noted above, you'll need the latest version (2.52) of the
GoServe
package (note that earlier versions of GoServe lack several features that are needed
to fully implement http/1.1)
- For convenience, let us assume that the GoServe package has been installed in the
\GOSERVE directory (your GoServe working directory),
and the GoServe data directory is set to \WWW.
- Copy SREV13F.ZIP to a
temporary directory and then unzip it in the usual manner
(i.e.;
UNZIP SREV13F)
.
From an OS/2 prompt, run INSTALL (a REXX program
bundled with SRE-http),
and follow the on-line instructions. You will be asked to provide the
names of several directories.
If you select the defaults, INSTALL will create a number of directories.
You will be asked to provide names, we recommend accepting the defaults.
You will also be given the opportunity to set several SRE-http parameters,
and to setup a SUPERUSER. We strongly recommend that you
take this opportunity. In particular, setting up a SUPERUSER
can help avoid later configuration headaches (though if you are
very security conscious, you can skip this without terrible consequence).
After running INSTALL, you can delete the contents of this temporary directory.
- Set up GoServe to run SRE-http:
- Set the
filter
to be SREFILTR.80. To do this,
you can insert http filter srefiltr.80 in the
optional parameters line in GoServe's settings window
(right-mouse click on the GoServe icon ...)
- In certain cases, throughput can be markedly
improved by using the SREPROXY.80 variant of SREFILTR.80.
- For less complicated sites, the sreLite variant of SRE-http can yield significant
improvements
- You can start GoServe now ...
- If you intend to run "server-side" programs, you might want to
increase the following
Limits
:
-
End client after inactive
-
End client after total
- Double check that the
DataDir
option points to the directory containing your
HTML files (for example, \WWW).
- It is HIGHLY recommended that the
Data Directory and the
GoServe Working Directory be
different!
- You must set the Options-Limit-Connection_Maintain value to be greater then 0
(a value between 10 and 30 seconds is reasonable).
- You must have a properly defined TZ variable (it defines the time zone)
in your OS/2 CONFIG.SYS file.
- To view a running log of SRE-http's actions, run the
PMPRINTF
program.
- At this point, the default version of SRE-http is running!
You'll probably
want to change the values of a number of SRE-http's parameters. Although you can do this by
editing the various parameter files (such asINITFILT.80)
with a text editor, for the new user
it is probably easier to run CONFIGUR.HTM -- a HTML front-end to
SRE-http's built-in configurator.
The most straightforward way of doing this is:
- Make sure that GoServe is running on your server, with SREFILTR.80 as its filter.
- Fire up your favorite web browser
- Point it at http://your.server/CONFIGUR.HTM (where your.server is the
address of your http server).
- You will be given the choice of a simple, intermediate, and expert mode
configurator. The simple mode is best suited for new users; it's a bit cumbersome
when making large changes, but is very well documented.
- Hint: If the configurator won't let you in (due to insufficient
privileges), you might want to check the OWNERS variable (in INITFILT.80)
to be sure it points to your IP address. Alternatively, you can use the
SUPERUSER username/password you created during the installation
process.
- If you need to use a port other then 80, you should:
- Change the names of all SRE-http files that end with
.80 to be the .nnn, where nnn is the
desired port (nnn
can be greater then 3 digits if HPFS is being used).
In particular, change
SREFILTR.80, INIT_STA.80 and INITFILT.80
- Enter http PORT nnn FILTER SREFILTR.nnn in the
optional parameters
setting of GoServe.
- Note that it is possible to run multiple instances of the GoServe and
SRE-http;
using different ports, different GoServe working directories (and
possibly different data, etc. directories), and different copies of the
user-configurable files (the .IN, .CNT, and INITFILT.nnn files).
- Remember, when using a port other then 80, clients will
need to include
:nnn
in the IP address of your server.
Now, all you have to do is create some informative, efficiently organized, and eye-catching HTML
documents, paste them together, and add links to the rest of the
net. But that's the fun part.
A note to upgraders As of ver 1.3d, SRE-http will be using
configuration files located in a CFGS\ directory. For information on these
new files, and on how to migrate older configuration files, please see
USE_CFGS.DOC
1.a) Description of the files that comprise SRE-http
The SRE-http package consists of a number of files. These include
the SRE-http REXX programs, the macrospace
procedure library, several user-configurable parameter files, samples of
"counter and control" files, and some sample HTML files. A complete
description of these files is contained in the
file list.
Many of the directories, and files, mentioned above can have their names changed
by modifying variables that are located in INITFILT.80 (the INITFILT_FILE); either by editing
the file with a text editor, or by using the intermediate configurator.
In this documentation
we usually refer to files and directories by their "titles"
(such as GoServe working directory),
but occasionally the "default name" is used
(such as \GOSERVE).
If you change the names of your directories, keep the following in mind:
- If you intend to make temporary files available to clients,
the TEMPFILE_DIR directory should
be a subdirectory of the GoServe data directory.
- For SRE-http's documentation and examples to work properly,
the IMGS and SAMPLES sub-directories should be directly under the
GoServe data directory
New addition: You can now specify host & port specific
configuration files in the CFGlist.CFG
configuration file.
To speed up processing, and to facilitate modularization, SRE-http makes
extensive use of REXX macrospace.
Of greater import, SRE-http uses several daemons ("helper" threads) to handle a number
of tasks (such as username lookup, alias matching, and SSI-document caching).
These daemons are launched
upon the first request to SRE-http. In addition,
SRE-http stores a number of variables in the local (GoServe) environment.
For most users, these implementation
details are unimportant. However, these
threads do use system resources (queues) which remain alive even after
GoServe has been turned off. To free these resources, you can use
the FREEUP.CMD program that is shipped with SRE-http.
Citation:
SRE-http uses the REXXLIB library to access macrospace and to
generate/communicate between threads. A distribution copy of REXXLIB
is supplied with SRE-http, and may be used freely with SRE-http. If you wish
to use REXXLIB in other REXX programs, contact
Quercus Systems for licensing information.
Lastly, SRE-http monitors the parameter files, including INITFILT.80.
Changes to these files will be incorporated into SRE-http's parameters
about every 10 seconds.
1.c) Variables and Parameters
Throughout this documentation reference is made to variables
(aka "parameters")
used to change SRE-http's options and features.
In the interest of thoroughness, this manual discusses the
multitude of SRE-http options
in terms of directly modifying these parameters. However, most
individuals
will probably never need to actually edit a file. Instead,
almost all of the parameters mentioned herein can be
modified using the intermediate-mode
configurator (CONFIG2.HTM). In fact, in most cases the
simple-mode configurator (CONFIG0.HTM) will do the
job -- where appropriate, links to the appropriate section of the
simple-mode configurator will be made available for your browsing pleasure
.
If you are a hands-on kind of administrator, feel free to
directly modify these parameters. If so, you might also
want to read the detailed
descripton of INITFILT.80.
The SRE-http documentation uses some
not-necessarily-intuitively-obvious terms. The following lists a
few of the more important ones. For a more complete list, see the
terminology appendix.
- URL
-
Universal Resource Locator (URL) is a scheme for specifying Internet
resources using a single line of printable ASCII characters. A URL should
contain
a protocol, domain name, port number (optional), the location of the resource, and
an (optional) option list (following a ?).
Examples: - http://your.server.net/dir1/sample.htm
- http://pet.store.com/prices?type=mammals&class=retail
- Request string
- When a client asks for a URL (say, by clicking on a link), a
request string (along with request headers and
a request body) is sent to the server (at the domain name and port listed in
the URL). The request string
consists of three tokens: the http method, the location of the
resource on the server, and the http protocol.
Examples (assuming the above URLs):
- GET /dir1/sample.htm HTTP/1.0
- GET /prices?type=mammal&class=retail HTTP/1.0
- Selector (also referred to as the
request selector )
- The selector is the location of the resource on the
server. Specifically, it's the (slightly modified) second term
in the request string.
Examples (assuming the above request strings):
- dir1/sample.htm
- prices?type=mammal&class=retail
Note that the "slight modifications" consist of:
- dropping the leading /
- decoding URL-encoded characters
(note that the above examples do not include any URL-encoded characters).
In many cases, the connection between the selector and server resource
it refers to is simple (such as when the selector is a filename relative to
the GoServe data directory). In other cases, it is completely virtual
(as when the resource consists of the output of a program that's run using
information provided by the client).
- Selector-specific (usually written as SEL-specific )
- SEL-specific refers to SRE-http configuration
information that is specific to a selector -- such
as resource privileges, or a virtual directory.
The selector is a pointer to a web-server
resource. Typically, this would be a file; but it might refer to
the output of some program run just for this request.
In either case, SRE-http has to match the selector
to the actual resource (an activity that can become rather convoluted!).
In much the same way that OS/2 extended attributes contain
additional information about a file, SRE-http's SEL-specific
information contain additional information about a selector
(needless to say, this information is only used by SRE-http).
Return to table of contents
A summary of this section:
- SRE-http supports multi-hosting. Multiple hosting can occur in
two different manners:
- When multiple numeric IP addresses are handled by a
single computer
- When multiple aliases exist for a single numeric IP address; and
the HOST: request header is provided by the client's browser.
-
SRE-http offers a number of logon controls.
These are used to control basic access to any of the resources
on your server.
- A set of PUBLIC_URLS
can be made available to the general public.
- User specific privileges are used to permit
(or deny) access to your server's resources.
- SEL-specific and directory-specific access controls can be used
to institute more refined access controls.
To use SRE-http in a multi-host environment, you must
specify host-specific entries that assign a
data-directory and a host-nickname to a specific IP
address.
The host-nickname is used throughout
SRE-http's configuration files. It identifies parameters that apply
only to requests directed to one (of possibly many) hosts being
served by SRE-http.
There are two ways of specifying host-specific entries:
- Creating HOSTS. "stem variables" in the INITFILT.80 file.
The simple-mode configurator can be used create
and modify these host-specific entries.
- Creating HOST "definitions" in the CFGLIST.CFG file. This is the recommended
method (new as of March 1999) -- though at this time the on-line configurators
will not modify CFGLIST.CFG.
In either case, for each host entry you need to define an IP address (or alias),
a host-nickname, and a default data directory.
the hosts (either IP addresses
For example, HOST. stem variables (in INITFILT.80) should contain
the following information (in a comma delimited list):
HOSTS.n ='ip_address, host_nickname,default_dir'
Where:
ip_address
is a IP address (integer or numeric)
host_nickname
is the "nickname" you will use when
referring to this host. The host_nickname
must
not
be a number, it must contain at least one non-digit character. Thus, a
host nickname of 1234
is invalid,
but 1234X
is okay.
default_dir
is the default directory for this host (it
is used instead of the GoServe default data directory).
A note on superceding hosts: As of ver 1.3g, there are three
kinds of Hosts:strict-superceding, superceding
and non-superceding. The basic difference is how and when
non-host specific parameters are used to resolve requests to a
defined host.
See IN_FILES.DOC for the details.
If your server recieves request from a host which does not have a matching
HOSTS. entry, it will be treated as "generic" request; that is, the standard
(single host style) default directory, etc. will be used with such requests.
Thus, if all requests (regardless of intended host)
have identical access to your server's resources (its files and programs)
you can ignore this entire section!
Given that you do want to have different resources available to
different hosts, almost all of the SRE-http variables and parameters can be specified
on a "host specific" basis
- To specify "host specific" parameters in the .IN and .CNT files the
host nickname, followed by //, is used.
For example, for a virtual directory entry that maps TIGERS/ to
D:\ANIMALS\TIGERS, but only for requests to ZOO.OURISP.NET; you might specify:
ZOOSITE// TIGERS/ D:\ANIMALS\TIGERS
where ZOOSITE is the host nickname for ZOO.OURISP.NET, and a space separates the
ZOOSITE// from TIGERS/.
- For parameter names (defined in INITFILT.80), host-specific results are
defined by appending a .HOST_NICKNAME to the variable name. For
example,
CHECKLOG.ZOOSITE='NO'
refers to this "ZOOSITE" host.
- A few of SRE-http's parameters are not host specific; such
as the DISPLAY_ENV parameter.
Notes
2.b) Logon Controls
The simple-mode configurator
can be used to enable LOGON, to add users to the USER_FILE,
to add/remove IN-HOUSE clients, and to enable the
LOGON_FAIL_FILE.
Setting LOGON requirements with the CHECKLOG variable
CHECKLOG should have one of the following values:
- NO
- No logon required; unencumbered entry for all clients.
- YES (or ALWAYS)
- Logon required for all requests.
- INHOUSE
- Entry allowed only to clients with INHOUSE or SUPERUSER
privileges.
Allowing unencumbered access to IN-HOUSE users
The INHOUSEIPS. stem variable can be used to specify the numeric IP
addresses of clients who are to be given "IN-HOUSE" status. IN-HOUSE client
do not have to enter logon information, and they are automatically granted
the privileges stored in the INHOUSE_PRIVS variable.
Notes
- INHOUESIPS must be host-specific;
INHOUSEIPS.1.ZOO='151.121.65.143' (see INITFILT.DOC for details).
-
The * character can be used as a "wildcard" in the INHOUSEIPS. stem variables.
- Each INHOUSEIPS. value can include a client specific list of privileges (place
it after the IP address).
Owners have SUPERUSER status
You can give SUPERUSER
privileges to a set of numeric IP addresses by changing
the value of the OWNERS variable.
Notes:
Wildcards are not allowed in the OWNERS variable
OWNERS are given INHOUSE_PRIVS privileges, as well as SUPERUSER privileges.
The OWNERS variable must be host-specific (see INITFILT.DOC
for details).
Logon for non IN-HOUSE users.
If a logon is required, an authorization string (containing
a name and password) is obtained from the
client. SRE-http then examines the USER_FILE
for a match. If a match is found, the request is honored (abstracting
from SEL-specific or directory-specific access controls). Otherwise
the client is asked to re-enter her name and password. Note that entries
in the USER_FILE may be "host specific".
Be aware that ...
- SRE-http ver 1.3h supports both "basic" and "digest" authentication scheme.
Basic authentication is a very simple means of encoding
the username and password, and is easily broken. Digest authentication
is much more difficult to break -- the password is encrypted using
an MD5 algorithim. See ENCRYPT.DOC for
a dicussion of SRE-http encryption capabilites
- Once asked for an authorization, most browsers will include
an "authorization field" in subsequent requests to the same site. Thus,
even if
CHECKLOG=ALWAYS
, the client will only need to enter his
username and password once (that is, she won't need to reenter it each
time a different document is requested).
Keeping out known pests, and detecting fake IP addresses
There may be particular clients (or sets of clients) that must be harshly denied all access
to your site. This can be accomplished by
recording the numeric IP addresses of these "unwanted clients" in the
UNALLOWEDIPS.n stem variables (wildcards are permitted).
Note that the OWNERS and INHOUSEIPS.n
stem variables are checked first. If the
client's numeric IP address appears in either of these lists,
UNALLOWEDIPS.n is not checked. Thus, by setting
UNALLOWEDIPS.1="*"
, you can deny entry to everyone
except OWNERS and IN-HOUSE users.
Also note that on multi-hosted sites, UNALLOWEDIPS. entries must
be "host-specific" (see INITFILT.DOC for details).
For additional security, you can set the DNS_CHECK variable (to YES).
When set to YES, SRE-http will lookup the client's IP name; and if
it does not exist (there is no DNS entry), logon will be denied. This
provdes some security against "spoofers", but it also slows down
response time, and may keep out legitimate users using dynamic (and
possibly unnamed) numeric IP addresses.
Caution: Use of either DNS_CHECK or UNALLOWEDIPS. will cause
"cache busting" -- proxy servers out there on the web will not cache your
documents. Since this can reduce throughput (both for your site's material, and
for the entire web), enabling either of these options is not generally recommended.
The LOGON_FAIL_FILE
If the client does not have "logon rights", SRE-http will use the value
of the LOGON_LIMIT and the LOGON_FAIL_FILE to determine
the response.
- LOGON_LIMIT is used to limit the number of attempts-per-minute.
- If LOGON_LIMIT is exceeded, or the username/password is incorrect,
you can then send the
LOGON_FAIL_FILE as a "response" (rather then continually asking for
the username and password).
For further details, see
the description of LOGON_LIMIT and LOGON_FAIL_FILE in INITFILT.DOC.
Creating your own username/password databases
In many circumstances you may wish to access some other database
of usernames and passwords; say, a database maintained by
a bulletin board system, or a database that is encrtyped.
Although a direct means of accessing such databases is not offered, youa
can instruct SRE-http to user your own custom procedure.
To do this, set the USER_LOGON_PROC parameter
(in INIT_STA.CFG)
to point to a REXX program file that contains this custom procedure
(or, that contains a procedure that calls a database manager or some
other executable).
For more details, see the discussion of USER_LOGON_PROC and USER_LOGON_ENABLE in
INITFILT.DOC
2.c) PUBLIC_URLS
There may be cases where you generally do not want to allow
public access to your
site, except for a set of clearly delimited public areas. For example,
you may have a private site, except for a set of
"who we are" documents. Although one could use
selective access controls
to accomplish this, the use of
PUBLIC_URLS provides a simple and direct
alternative.
These PUBLIC_URLS (which are specifined in CFGS\PUBURLS.IN)
are used to identify server resources
that are "open to the public" -- that can be accessed by clients
who have no logon rights and no access privileges.
Basically, SRE-http compares the request (using
wildcard matching with substitution) against
the entries in PUBURLS.IN.
All requests that match an entry in PUBURLS.IN:
- will be examined for ALIASES and for virtual directory matches
- will be checked for an extension, and
will be examined for AUTO_NAME match (if needed).
- server side includes, and server side processing, will be performed
(provided the NO_INCLUDE and NO_PROCESSING variables are not in force).
- Caching will not be suppressed.
- The PUT and DELETE methods will not be permitted
/permi
- The clients privileges are set to:
-
PUBLICFILES PUBLIC
,
- plus the privileges in the PUBLIC_PRIVS SRE-http parameter,
- plus possible In-house privileges,
- plus privileges that might
be associated with a username/password sent with this request
...
even though this username/password is not required,
the browser might have
used it to gain access to a different resource on your server.
PUBLIC_URLS can also specify literal public_urls. When a
request selector
matches one of these literal public_urls; file transfer
is expedited by:
- Not performing aliasing
- Not using virtual directories and AUTO_NAME
- Not attempting server side includes
- Not attempting AUTO-HEADER.
Notes:
- To speed up processing, you can disable the ALWAYS_CHECK_PRIVS
parameter (in-house and username privileges will not be available).
- In a multi-host environment, the PUBLIC_URLS must be host specific (that
is, "non-host specific" values of PUBLIC_URLS are not
not used as defaults).
- If you do not use PUBLIC_URLS, setting NEVER_PUBLICURLS=1
(in INIT_STA.80) can slightly speed up processing.
- For a more detailed description of how to use PUBLIC_URLS, see
PUBURLS.DOC.
2.d) Assigning client privileges
In several circumstances, SRE-http will check the "client privileges"
before transferring information. In particular,
file transfer when SEL-specific access controls
are in place (i.e.; when ALLOW_ACCESS='NO'
) requires that the
client have appropriate privileges.
In a sense, privileges offer a
convenient shorthand for identifying sets of users.
Privileges are set automatically for:
IN-HOUSE clients are granted privileges stored in their INHOUSEIPS. variable,
OWNERS are granted SUPERUSER privileges.
In addition, IN-HOUSE clients and OWNERS will be granted the
privileges that are listed in the INHOUSE_PRIVS "space delimited
list" variable. It is recommended
that INHOUSE_PRIVS always include the INHOUSE privilege.
For everyone else:
If a logon is required, the privileges are read from the
USER_FILE.
Last of all ..
Privileges listed in the the PUBLIC_PRIVS "spaced
delimited list" variable are given
to everyone.
In addition to the above "static" privileges, clients can be assigned
"dynamic" privileges. These dynamic privileges are typically
set by prior actions (say, filling out a registration form, or
requesting an introductory file), and have a short life expectancy (measured
in minutes). For further discussion of these "dynamic" privileges,
see ADDPRIVS.DOC, and the discussion of the CHECK_ADD_PRIVS
and ADD_PRIVS_PREFIX variables in INITFILT.DOC.
If you start a client privilege with a ? (say, ?PXX12), then
it will be treated as a "secret privilege". Secret privileges
are not used in access controls, and SRE-http utilities
should NOT reveal their values. They are designed to be
by used by addons, such as the DYN_PWD "dynamic password"
addon.
2.e) Accesss control on a selector-specific basis.
The simple-mode configurator
can be used to enable selector-specific access controls, and to add/remove
selector-specific access control entries
There may be cases where you want clients to have unencumbered
access to some, but not to all, the resources of your server.
One way to do this is to assign access privileges on a
which selector specific basis.
The ACCESS_FILE,
and the ALLOW_ACCESS variable, are used to construct these
selector-specific (SEL-specific)
access controls.
ALLOW_ACCESS can take the following values:
- YES
- No limits -- all clients (with logon rights)
are automatically given access rights to the server resource.
- INHOUSE
- IN-HOUSE users (and SUPERUSERs) are given automatic access rights,
all others must have appropriate privileges.
- NO
- No one (except SUPERUSERs) is given automatic access rights,
all others must have appropriate privileges.
When ALLOW_ACCESS is enabled,
SRE-http will examine the ACCESS_FILE
for an entry that
matches the request selector .
- If a matching entry is found, SRE-http
will then extract a SEL-specific resource privileges list. This
is used (along with the client privileges)
to determine if the client is authorized to access the resource.
- If a matching entry is not found, the request will
not be honored.
Additional Features of the Access Control File
In addition to general access rights (do you have any rights to the server
resource), the ACCESS_FILE contains several additional pieces of
SEL-specific information:
Permissions
The permissions list includes
information on:
- suppression of server side
includes and server side processing
- PUT and DELETE permissions
- CACHE enabling
- suppression of aliasing, directory-specific access controls, virtual directory lookup, and post-filtering
The Realm
When ALLOW_ACCESS is enabled, and the client does not have
appropriate privileges, SRE-http will query the client for a new
username/password. When querying, the SEL-specific realm
is displayed (if available). If there is no SEL-specific realm, the
THE_REALM realm is displayed.
ACCESS_FAIL_FILE
If the client does not have access to the server resources represented
by the selector, SRE-http will use
the value of ACCESS_FAIL_FILE to dictate the response. If
ACCESS_FAIL_FILE=0, a username/password will be re-requested. Otherwise,
the ACCESS_FAIL_FILE, or a SEL-specific access failure file, will be
returned. For details, see the discusion of ACCESS_FAIL_FILE in
INITFILT.DOC.
Advanced Options
The SEL-specific advanced options file
allows you to specify several SEL-specific advanced options, including:
- Execution of external REXX procedures prior to returning a requested
document
- Customizing the response headers
- Suppressing specific server-side-includes (such as the header and footer).
- Selector specific mime type
- Specifying selector-specific replacement rules
Notes: Two types of resource privileges
There are two types of resource privileges :
- ONE_OF (the default type).
- The client must have "one of" the ONE_OF privileges.
- MUST_HAVE (start with the & character)
- The client "must have" all the MUST_HAVE privileges.
..... if only one privilege is specified, these two types are equivalent.
Notes: Matching client privileges to resource privileges
SRE-http's privilege matching algorithim is quite simple:
- If a MUST_HAVE privilege appears in the
SEL-specific resource privileges list, then it must
also appear in the client privileges list. If not,
access is denied.
- After checking all of the MUST_HAVE privileges, SRE-http then
compares each ONE_OF privilege to the client privilege list.
If any of these ONE_OF privileges appear, then access is permitted.
Otherwise, access is denied.
- Reiterating: access is denied if there is
no overlap between the client's privileges and the
ONE_OF resource privileges
Notes: SEL-specific permissions
SEL-specific permissions are used to provide SEL-specific
control of the features of SRE-http. That is:
SEL-specific privileges are used to control access to a
resource
SEL-specific permissions are used to control SRE-http features,
assuming that the SEL-specific privileges have been satisfied!
Currently, the following permissions are available:
Suppressing server-side actions
You can suppress server-side-includes, and server-side-processing on a "SEL-specific"
basis by including NO_SSI and NO_SSP permissions (respectively). You can also
suppress "in-document" server-side processing (the SELECT and INTERPRET CODE
keyphrases) by including a NO_CODE permission (note that NO_SSP implies NO_CODE).
Permitting the PUT and DELETE methods
SRE-http understands the PUT and DELETE
HTTP methods. The PUT method
is used to upload a file to your server, and save it using the location
specified in the request. The DELETE method is used to delete
a file, as specified by the location specified in the request.
For security reasons, PUT and DELETE requests will only be honored if
the appropriate permssion (PUT or DELETE
respectively) appears in the permissions list .
Furthermore, when using the PUT_FILE or
GET_URL facilities to upload to a non-upload_directory subdirectory (that is,
to a virtual directory), the PUT permission must apply (to the "selector"
that matched the virtual directory).
Suppressing examination of HTACCESS files
To suppress the use of HTACCESS files for selected server resources, include a
NO_HTACCESS permssion. Note that this will not effect the SHOWDIR
dynamic directory list processor.
Suppressing virtual directory, post-filter, and aliasing
The NO_VIRTUAL, NO_POSTFILTER, and NO_ALIAS permissions will suppress
virtual directory lookup, post-filtering and file recording, and alias lookup
(respectively) on a SEL-specific basis.
Allowing a file to be cached
Whenever there is a possiblity that access to a resource will be
denied to a client, SRE-http will disable caching of the file invoked
by the request selector .
In particular, if CHECKLOG is not equal to "NO", or
if ALLOW_ACCESS is not equal to "YES", then caching
will be suppressed.
While an important security feature, there may be cases where
you are willing to sacrifice some access control in order to speed up
request processing. To achieve this, you can enable caching (on a
URL specific basis) by including CACHE in the
permission list.
Caching a response means: allow proxy servers (anywhere on the web)
to store (and resolve) this response (and its associated selector).
Note that CACHE does not permit the GoServe cache. If you want to allow
the GoServe cache to handle this selector, then
use CACHE*.
Please be aware that the GoServe cache is not http/1.1 compliant. When
the GoServe cache answers a request, it will claim to be an http/1.0 server, and
it will not include cache-control, etag, and other such http/1.1 response headers.
While not necessarily a serious problem, it is a bit strange. Therefore, you
may wish to use CACHE* only for unimportant resources, and to not check the
"call filter anyways" GoServe option. That is, use CACHE* when SRE-http auditing
(and other post-filter actions) are not needed (for example; for
icons and background images).
Notes: Miscellaneous
- Advanced user option:
You can specify REALM-specific resource privileges
which will be added to the explicit SEL-specific resource
privileges list (every selector identified
as belonging to a given realm will have the same
list of REALM-specific resource privileges).
- Entries in the ACCESS_FILE can be "host specific".
- The default ACCESS_FILE is ACCESS.IN.
- Permissions are examined even when ALLOW_ACCESS=YES
- Files requested by server side includes are not subject to
access controls.
- If the ACCESS_FILE does not exist,
then access is disallowed to clients for whom ALLOW_ACCESS is enabled.
The idea is that if there is no matching entry (in the ACCESS_FILE)
for a selector, then the server resources
associated with the selector should not be accessible.
(... and if the ACCESS_FILE is unavailable, then there can't be a match).
- Wildcard matching is supported.
Note that global values of NO_INCLUDE=YES and NO_PROCESSING=YES take precedence
over the SEL-specific SSI and SSP permissions!
- Warning: use of the CACHE or CACHE* permission
can inadvertently subvert access control!
- You might want to include a global wildcard match.
For example:
* NO
-- if not explicitily mentioned, do NOT allow access
* *
-- if not explicitily mentioned, allow access
Return to table of contents
2.f) Directory-specific access control, using HTACCESS files.
To provide compatability with HTTPD style servers (such as Don Meyer's
GOHTTP), SRE-http supports the
HTACCESS method of access control.
This support uses code graciously loaned
to us by Don Meyer, suitably modifed for SRE-http.
Briefly, the HTACCESS method utilizes special HTACCESS
files that are placed
in your various directories (usually with the name HTACCESS.
,
or .HTACCESS
). These files (there may one in each of several
directories) contain entries pointing to password files, user-group files,
and other parameters that
are used to ascertain who shall be given access to the
files in the directory (and its child directories).
HTACCESS control will be checked for all requests.
Note that the presumed location of
the HTACCESS file depends on the type of request:
- Request for documents (including PUT and DELETE method requests) == In the directory of the document
- File uploads == In the target directory of the upload (typically the UPLOAD_DIR directory)
- CGI-BIN requests == In the CGI-BIN directory (or appropriate subdirectory)
- SRE-http's built-in and included facilties == In the GoServe directory
- Other server side processing requests == In the directory containing the requested program.
In all these cases, the "parent" directories are also checked for HTACCESS files.
Notes on the use of the HTACCESS method
- Both methods of access control CAN be active: the
"native" SRE-http "SEL-specific" access is checked first, and then the
"HTACCESS" method of "directory specific" access is checked.
- Since just about all the options provided by the "HTACCESS" method can
be provided by the "native" SRE-http methods:
on speed of throughput grounds
we recommend using the "native" SRE-http
methods (that is, the SEL-specific method) whenever possible.
- For details on enabling SRE-http's support of HTACCESS controls,
see the description of the DO_HTACCESS and
HTACCESS_FILE variables in INITFILT.DOC.
- HTACCESS lookups are suppresed when the request matches a PUBLIC_URLS
(that is, HTACCESS controls, redirection, etc. will not be attempted).
- The HTACCESS files may also contain:
- URL "redirection" information,
- directory-specific default index information,
- dynamic directory list processor parameters
3) Modifying the request
URL's can get long and nasty, documents are often moved, people
often mistpye URLs or don't ask for an exact filename,
and sometimes it's just nice to use shorthands when specifying
the location of your server resources. These actions are
examples of modifications to the request. This section
discusses ways you can conveniently modify
& redirect a request (as recieved from the client).
3.a) Specifying the home page (the default)
When the client sends an empty request, a /
, or
"/?some+options"
,
SRE-http assumes that the client desires the "home page" (the default document).
By tradition (but not necessarily) the default document is a file named
INDEX.HTM located
in the root of the data directory.
The default can be set using the DEFAULT or DEFAULT.HOST_NICKNAME
variable
(that is, DEFAULT may be host specific).
You can use the simple-mode
configurator to set the home page and the directory-specific default
document(s)
Return to table of contents
3.b) Specifying default documents for directories
Often, a request may arrive that specifies a directory, but does not specify a
file. For example, a request for COOLJUNK/JOKES/
does not specify a particular
file, but instead implies "give me the default document for the
COOLJUNK/JOKES subdirectory of the data directory". In these cases,
the AUTO_NAME variable is examined.
AUTO_NAME
should contain a space delimited list of filenames to use when
a request for a "directory" is recieved.
SRE-http will attempt to find these files in this
"requested" directory --
starting with the first name in the AUTO_NAME list.
To assist in this search, a special name,
consisting of *.HTM (or *.HTML) means use the directory_name.htm file.
Lastly, an entry of !CREATE instructs SRE-http to generate a directory
listing of files and subdirectories in the requested directory.
This listing is generated with SRE-http's !DIR
special action. By default, a <PRE> formatted table is
generated, containing (for each file):
- a descriptive icon
- a link to the file
- the file creation date
- the size of the file
If you are interested, it is fairly easy to
modify these display options -- you can even
tell SRE-http to automatically generate a description for each file.
Example
AUTO_NAME=" *.HTM INDEX.HTM "
If the request is for /INFO/MAINE/
,
and your data directory is D:\WWW
, then ...
*.HTM
is interpreted as: D:\WWW\INFO\MAINE\MAINE.HTM
INDEX.HTM
is interpreted as: D:\WWW\INFO\MAINE\INDEX.HTM
Notes
- AUTO_NAME has no effect on calls that do not
specify a directory name --that is,
the document specified in the DEFAULT
variable is used in response to an empty (or /) request.
- AUTO_NAME, and other forms of "local redirection" can cause problems when the client's browser resolves
"partial URLS" -- see INITFILT.DOC for further discussion!
-
If you start a filename (in the AUTO_NAME list) with a /, is is
assumed to
be relative to the data directory (or to a virtual directory).
Otherwise, the file is assumed to be relative to the current
URL (you can include additional path information).
- Instead of *.HTM, you can use *.ext, where ext can be any
other extension (say, HTML, or SHT
For example: auto_name=" *.HTM *.SHT INDEX.HTML PUBS/INDEX.HTM "
(note that PUBS/INDEX.HTM refers to the PUBS directory relative
to the current URL).
- !CREATE should always be
the last item in AUTO_NAME (anything following it will never be reached).
- !SHOWDIR can be used as an alternative to !CREATE -- see
SHOWDIR.DOC
for details.
- For a full featured directory lister, you might want to examine the
GETAFILE addon for SRE-http!
In contrast to explicit request to the root of a directory (that is, requests
that end with a /); requests:
that do not end in a /,
than do not contain a ?, and
that do not have a .extension
can be interpreted in several manners. The NOEXT_TYPE variable is
used to select how such requests are interpreted.
NOEXT_TYPE
can take any mixture of the following values (in a space delimited list):
DIR
or REDIR
: A / is appended to the end of the
request, and the client is
redirected back to the modified URL (that is, a remote redirection
is attempted).
HTM or HTML
: Interpret as an abbreviation for an
HTML file (with extensions of .HTM or .HTML respectively).
NONE
: Interpret as is.
-
other_string
: The other_string is added.
For example, if NOEXT_TYPE=.GIF
,
then .GIF
will be added to these "no extension" requests.
Note that a DIR (or a REDIR) should be the last item in the NOEXT_TYPE list.
Return to table of contents
3.c) Using ~ to specify the home directory
You can use the simple-mode
configurator to set the home-directory
As a convenience, SRE-http will replace occurences of ~ characters
in request selector with a string. Since the ~ is often used to
point to a set of individual "home directories", this replacement string
is stored in the HOME_DIR variable.
To select the home directory , change the value of the
HOME_DIR (or HOME_DIR.HOST_NICKNAME) variable.
Example
If ...
HOME_DIR="BRANCH/STAFF/PERSONAL/"
and
The request
is ~JOES/PAGE.HTM
,
.. then
SRE-http will look for: BRANCH/STAFF/PERSONAL/JOES/PAGE.HTM
(under your data directory, or in a virtual directory).
Notes
- This HOME_DIR "string replacement" does minimal syntax checking
(// are replaced with /). Thus,
one should be careful that the definition of HOME_DIR, and its use in the
the links included in your HTML documents, is consistent.
Advanced Option: Specifying User Subdirectories
In many cases, you may wish clients to limit access to particular
subdirectories of your HOME_DIR
directory. For example,
suppose all "students" have space on the HOME_DIR
directory
of your web server; or HOME_DIR
may be on a LAN drive
accessible as a virtual directory from the web server. These
"student" directories may contain several subdirectories; one of which
is intended for WWW use, while the others are for personal
use.
The goal is to
give clients direct access to the "web" related directories
but not to the "personal" directories.
This goal can be achieved by including a $ in the HOME_DIR
parameter.
Specifically, the $ is replaced by the portion of the
request between the ~ and the first / following this ~
For example: If:
-
HOME_DIR=USERS/$/WWW
- the request is
/~GERALD/RESUME.HTM
Then SRE-http will use: /USERS/GERALD/WWW/RESUME.HTM
For futher details, see the discusssion of the HOME_DIR
parameter in INITFILT.DOC.
3.d) Establishing virtual directories
You can use the simple-mode
configurator to add/remove virtual directories.
By default, SRE-http will match the
request selector
to a file in the
data directory
;
or if the request is for server side processing (such as an SRE-http
addon, or a CGI-BIN script), to a file in the
addon directory
or CGI-BIN directory
.
While a good security feature (files not in these directories are inaccessible),
this can be an inconvenience. To remedy this inconvenience, one can
define "virtual directories" using the VIRTUAL_FILE.
Basically, SRE-http will compare the
starting portion of a URL to see if
it matches an entry in VIRTUAL_FILE. If it does, the
directory listed
in the entry is used (instead of the data directory or addon directory).
Thus, you can make available a wide, but controllable, set of "local"
directories (on or LAN accessible from) your server.
In addition,
"virtual directories" can point to "remote" directories on other http servers --
SRE-http will
attempt to retrieve the file from the remote server;
without using a redirection.
To clarify: to the client, remote virtual directories are indistinguishable
from "local" virtual directories.
In particular, HTML files with server
side includes can be remotely located -- and if the remote server makes
no attempt to process these server side includes, SRE-http will!
For details on the use of the virtual directories, see the description of the
VIRTUAL_FILE .
Note that entries in the VIRTUAL_FILE may be "host specific"
Return to table of contents
3.e) Using "aliases" when responding to requests
ALIASES are used in SRE-http to redefine and redirect
requests
Along with the ALIAS_FILE,
the CHECK_ALIAS parameter controls
whether and when ALIAS checking occurs.
CHECK_ALIAS should have one of the following values:
NO = Suppress ALIAS checking
YES = Enable ALIAS checking
3.e.i) Local redirection
-
To modify simple URLs's. For example:
- You may want to convert a request for
GETINFO
into: INFODIR/GETINFO.HTM
.
3.e.ii) Processing searchable indices
-
The DOSEARCH SRE-http addon (available from
the SRE-http home page), when combined with
an ALIAS, provides a simple means of implementing
text-based searchable indices.
To use SRE-http's searchable index facility,
one should create an alias of the form:
INDXFILE.HTM?* DOSEARCH?FILE=FILE.NAM&TARGET=*
Where
INDXFILE.HTM
is the name of a
searchable index
(that is, an HTML document containing an <ISINDEX> element).
DOSEARCH
instructs SRE-http to
"execute the DOSEARCH addon."
FILE.NAM
is the name (relative to the data directory,
or in a "local" virtual directory) of the ASCII text file to be searched.
Note that the alias will not be activated on the first
request for INDXFILE.HTM -- only upon return (when a ? is appended to
the request selector by the browser) will this alias match occur.
If you want to use some other text search program, you could set up
an alias of the form:
SEARCHIT.HTM?* SRCHREXX?*
- SEARCHIT.HTM is invoked at first (since the request does not contain a ?).
- The SRCHREXX procedure is called
after the client enters the search string (and the client appends a ? to
SEARCHIT.HTM). SRCHREXX should be a REXX procedure located in the
SRCHREXX.CMD (or SRCHREXX.80) file in the ADDON directory; and it
might call a powerful search engine.
3.e.iii)Remote redirection
-
There are 4 ways of using an alias to indicate that a document has been moved to
a new server
(or you can use the simple-mode
configurator to add/remove remote redirections).
target http://new.site.org/newname
- If the request selector
matches target, a "temporary" (HTTP status code 302)
redirection to the new URL (i.e.; http://new.site.org/newname) will be returned
to the client. A full URL must be specified (starting with http://).
-
target !TEMP http://new.site.org/newname
- Same as above, but you can use short-hand's URLS (i.e.; without the http://).
If you do not include an ip address, redirection will be back to your site.
-
target !MOVED http://new.site.org/newname
- Same as above, but the redirection is permanent (HTTP status code 301).
-
target !NOTIFY http://new.site.org/newname
- A "message has been moved" document will be returned to the
client, which will contain a link to its new location. Techincally
speaking, this is not "redirection". Rather, it is a "notification of redirection",
with the intention that the client will change the appropriate links (or bookmarks).
Citation: The code for this is courtesy of Don Meyer!
Examples:
PROJ/P48.HTM http://www.prez.edu/truman.htm
PROJ/LINCOLN/* !MOVED civ.war.org/p1/alinc.htm
Notes:If you do not use !TEMP or !MOVED,
you must specify a full URL-- do not forget the http://.
3.e.iv) Redirecting requests for CGI-BIN scripts
This usage of alias is somewhat obsolete,
use of CGI-BIN virtual directories is now recommended).
If you want to run a CGI-BIN script that is not in your CGI_BIN_DIR
directory, you can use the ALIAS file to provide path information. In this
case, the alias should consist of the CGI-BIN script name (without any
slashes or other path information), followed by the drive and directory
where it can be found.
For example:
If ..
- a selector of
CGI-BIN/MAKEMAP/?NEB+IOWA
is recieved
- The ALIAS file contains a
MAKEMAP D:\EXES\GIS
entry
- MAKEMAP.EXE is a CGI-BIN script located in D:\EXES\GIS
then...
- D:\EXES\GIS\MAKEMAP.EXE will be invoked, with NEB+IOWA placed
into standard input (along with all the other CGI-BIN variables stored in
the environment).
Note that if this MAKEMAP D:\EXES\GIS
entry did not exist,
SRE-http would look for a MAKEMAP program (such as MAKEMAP.CMD) in your CGI_BIN_DIR
directory.
3.e.v) Content Negotiation
SRE-http supports both server-side and
client-side content negotiation.
In either case, you use a special ALIAS to indicate that a given
selector is "negotiable".
The basic syntax of this alias is:
sel !NEGOTIATE
where sel is a selector, and !NEGOTIATE indicates
that sel is a "negotiable" resource.
For example: VARTEST/VAR3.VV !NEGOTIATE
Actually, sel should be a "variant list" -- SRE-http uses
"variant lists" to determine which "alternate" (of several possible
variants) to use.
Alternatively,you can use:
sel !NEGOTIATE variant_file
where sel is a * wildcard containing selector, and variant_file is
a valid selector pointing to the variant file.
For example: INFO/* !NEGOTIATE INFO/MANUALS.LST
INFO/MANUALS.LST would be the "variant file" -- it would be used for
all request selectors that match INFO/*. If you use this "wildcard"
construct, be sure to include an appropriate PATTERN: in the
variant file.
For details on SRE-http's support for content negotiation, including
support for custom "remote variant selection algorithims", see
NEGOTIAT.DOC.
3.e.vi) Notes about Aliases
- Entries in the ALIAS_FILE may be "host-specific"
- Host-specific aliases are checked first. If there is no host-specific alias
that matches the request, then the default (non-host-specific) aliases are checked.
- The use of aliases as a means of identifying the location of a
CGI-Bin script is "not spec", so should be used with caution.
- "Local redirection" using aliases can cause problems when the client's browser resolves
"partial URLS" -- see INITFILT.DOC for further discussion!
- You can use wildcard matches and wildcard
matches with substitution
in your aliases (note the LINCOLN example above). This
is useful if you want to redirect all request for files that used to be in a subdirectory
to some new location.
-
ALIASES are processed before the AUTO-NAME replacement is attempted. Keep
this in mind when considering how to handle requests that arrive with
no extension, no ?, and that do not end with a /.
Return to table of contents
3.f) What to do if no document can be found
Sometimes, despite the use of aliases et al., it may not be possible
to map the request to a file (or other resource) on your server.
In those cases, a 404 Not found
response
is returned to the client, along with a short description. You can put
a customized message in this short description. In particular, you
can put a link to your "home page".
The NOT_FOUND_URL variable
contains this customized message. By default, its value is:
<a href="/"> Visit the HOME_NAME home page? </a>
Note that HOME_NAME
will be replaced by the current (possibly host
specific) value of the HOME_NAME variable.
Thus, the befuddled client merely needs to click on this link to get some kind
of access.
Notes:
- For greater customizaton, you can set NOT_FOUND_URL to point
to a
could not find document response file.
This should be either be a fully qualified file name (this file will be
returned whenever the requested resource can not be found); or,
it can be a pathless filename, in which case the file is assumed to
be relative to the selector's directory.
- HOME_NAME
should contain a
short description of your domain; say:
BIG/SERVICE: Your Friendly Government Agency!
.
Or, you can set HOME_NAME
=" "
to send a generic message.
- Note that HOME_NAME and NOT_FOUND_URL can be HOST specific.
- For further discussion of HOME_NAME and NOT_FOUND_URL, see
INITFILT.DOC.
- Hint: in conjunction with NOT_FOUND_URL you can use the
MTCHFILE.RXX to present the user with
a list of possible matches to your misspelled request.
Return to table of contents
4) Using Server Side Includes
One of the primary advantages of SRE-http is the extensive support for
a variety of server side includes.
These server side includes (SSI's) let you easily create
dynamic documents. In particular, inclusion
of files, text strings,
and transient variables (such as the time, date, and number of requests)
are easy to accomplish, requiring modifications to your HTML documents, and
not to the server software.
SRE-http supports two sets of SSIs -- the NCSA set of SSIs, and
a set of SRE-http-style SSIs. Both sets require the
inclusion of special keyphrases in one's
HTML documents. When an HTML document is
requested, SRE-http will (optionally)
detect these keyphrases,
and perform some sort of textual substitusion.
The basic structure of a keyphrase is:
<!-- KEYWORD
argument
-->
where:
- KEYWORD can be one of several phrases:
- SELECT -- used to selectively include blocks of HTML code
- REPLACE -- used to "replace strings"
- INCLUDE -- used to "include files"
- OPTION -- used to "include
options sent by the
client"
- INTERPRET -- used to "include
the results of a custom-designed REXX routine"
- CACHE -- controls SRE-http's
server side include CACHE
- #cmd -- NCSA HTTPD style server side includes
- argument is a string containing "arguments" that are used, in
conjunction with the keyphrase, to dictate how SRE-http should modify
this document.
Examples:
<-- REPLACE CREATION_DATE --> :
<-- INCLUDE ADDLIST.HTM -- >
<-- #FLASTMOD FILE="srehttp.htm" -->
Alternate keyphrases
In the interests of brevity, and to help avoid conflicts with other
html comments that aren't comments , there are several modifications
you can make to these KEYWORDS.
- If desired, you can add a "preface" (such as the !
character) to the definitions of the first six keywords (i.e.; !REPLACE
is used instead of REPLACE). For further details, see the description in
INITFILT.DOC of the KEY_PREFACE
variable.
- You can use several shorthands:
- % instead of REPLACE
- $ instead of INTERPRET FILE
- # instead of INTERPRET CODE
For further details, see the descriptions in INITFILT.DOC
of the QUICK_INTERPRET, QUICK_INTERPRET_CODE, and
QUICK_REPLACE variables.
Miscellaneous Notes
- When SRE-http finds a keyphrase, it will ALWAYS remove the keyphrase, and
replace it with the file or string dictated by the KEYWORD
argument . This replacement occurs at the position in the document that was
occupied by the keyphrase. If a faulty keyphrase is encountered
(i.e.; a non-supported argument is used),
SRE-http will remove it.
-
The SELECT keyphrase is a little different: it dictates whether the "block of
HTML code" that follows the SELECT keyphrase is to be retained. Thus, it is
best thought of as a "server side exclude" -- the keyphrase is always removed, but
sometimes so is a lot of other stuff!
- The CACHE keyphrase is used to control SRE-http's caching of documents
that contain server side includes (it is not used to control the
GoServe, SREPROXY, or external proxy caches).
- The NSCA HTTPD style server side includes are provided for completeness
sake; some of them are redundant with REPLACE and INCLUDE.
- You can instruct SRE-http to perform server side includes only
on files that have a .SHT or .SHTML extension. See the description
of the SSI_SHTML_ONLY and SSI_EXTENSIONS parameter (in
INITFILT.DOC) for details. Or,
you can use the simple-mode configurator.
- Instead of using <!-- and --> as keyphrase delimiters,
you can specify your own set(s). See the description of DELIM_1 and DELIM_2 in
INITFILT.DOC for details.
- As a more general type of "server side include"; you can use
REPLACE_RULES. -- these perform textual replacements over your entire
document; and may be specified generically (see INITFILT.DOC), or
on a selector specific basis (see ADV_OPTS.DOC).
4.a) Headers and Footers
In addition to server side includes using keyphrases, a multi-line header and
footer can be automatically added to all HTML
documents. The header is added just after the (first) <BODY >
tag in the document (see the notes for an exception to this rule); and the footer is added just before the (last)
</BODY > tag.
To set these, just change the values of the HEADERS.
(for headers) and the FOOTERS. (for footers)
stem variables located in INITFILT.80.
Or, you can use the simple-mode configurator.
Header and Footer Notes
- Headers and Footers can contain keyphrases.
- To suppress addition of a header and/or a footer,
set HEADERS.1=0 and/or FOOTERS.1=0.
- If the HEADER starts with
<BODY>, then the HEADER will replace the first <BODY> element.
-
The various server-side includes are only attempted for HTML files.
-
If you will NEVER have server-side includes, you can set the
NO_INCLUDE variable to equal "YES". This will speed up request
processing a bit.
- HEADERS., FOOTERS., and NO_INCLUDE can be host specific (see INITFILT.DOC for details).
Return to table of contents
4.b) SRE-http style server side includes
4.b.i) The REPLACE keyphrase
Syntax: <!-- REPLACE Varname -->
, where Varname
is
the name of a static or dynamic variable. Note that you can use % instead
of REPLACE.
The REPLACE keyword is used to insert dynamically determined information
and short (static) strings into a document.
SRE-http recognizes the following "built-in" Varnames
(the underlined variables are user-configurable, possibly
host-specific, "static" variables that
can be modified by editing INITFILT.80):
:
- DATE : todays date (i.e.; 27 Aug 1988)
- TIME : current time (local) (i.e.; 4:54pm)
- DATEGMT : current date (at GMT)
- TIMEGMT : current time (GMT) -- a GMT is appended
- CREATION : Short message stating (local) creation time and date of the document
- CREATION_DATE : Creation date of document
- CREATION_TIME : Creation time of document
- SERVERNAME : The IP name of the server (i.e.;
WWW.MYORG.NET). If multiple hosts, this will
be the IP name of the server to whom the request was directed.
- SERVER : the server software (i.e.
GOSERVE ver. 2.52 )
- WEBMASTER : The Webmaster's address
- USERNAME : The client's name, i.e. johndoe.somewear.net
(or his numeric ip address if a name is unavailable)
- HOME_NAME : The host specific colloquial (not necessarily IP) name of this
domain
- URL : The current URL (includes the servername and serverport)
- BROWSER: The name of the web browser the client is using
(sometimes referred to as the 'User-Agent')
- FILTER_NAME : The name of the filter (i.e.; SRE-http ver 1.2).
- REFERER : The address of the server that refered the client to your site
(often unavailable).
- INHOUSE.n : n = an integer. If the user has INHOUSE
privileges (but does not have SUPERUSER
privileges)
then replace with the INHOUSE.n variable
- SUPERUSER.n : n = an integer. If the user has SUPERUSER
privileges
then replace with the SUPERUSER.n variable
- HITS and HITS_FILE: A string stating the number of hits
for the "URL" or the file (respectively),
being requested (the number of hits is stored in the
COUNTER_FILE ).
Note that
a given document may be reached via several different selectors (say,
due to several aliases pointing to the same file), each of which
will have a seperate counter. In contrast, each FILE has a
unique counter. Also note that on multiple host servers,
otherwise similar selectors (that may even point to the same file)
will have seperate URL counter entries -- but (if they do point
to the same file) will have only one FILE entry.
- COUNTS and COUNTS_FILE: Same as HITS, but just the number is displayed.
- OPTION_COUNTS.n and OPTION_HITS.n :
Normally, the same as COUNT and HITS. But, if an option
has been recieved, use the value of the nth
option (rather then number of
hits).
- READ_HEAD or HEADER : Displays (using a <PRE>> format) the "request
header". This can be a handy debugging tool.
- PREFILTER_RESULT : Displays "status" message returned by the
PREFILTR routine. If the PRE_FILTER variable
equals NO, PREFILTER_RESULT will be an empty string.
A special argument can
be used to extract variables from the GoServe environment, which //
contains many variables created by SRE-http.
- VARIABLE.varname will extract the varname
variable, where varname is either in the GoServe/SRE-http environment,
or a value hard coded in INIT_STA.80.
For example,
VARIABLE.HOST_NICKNAME refers to "host nickname" (if available) to whom
this request was directed.
Last of all, if none of the above matches argument , the
custom REPLACEments are searched for a
match (which might be host specific). If a match is found, the
information from this custom REPLACEment is used.
You can even include argument placeholders to this
custom replacement; they will be replaced by arguments
included in the REPLACE keyphrase.
To create custom REPLACEments, you should edit the REPSTRGS.IN file,
or the ATTRIBS.CFG file
(or you can use the simple-mode configurator).
Examples
<!-- REPLACE TIME -->
<!-- % URL -->
<!-- % ODOM MYDOC1 -->
Notes
- To create a host-specific "static" variable,
you should include
a .HOST_NICKNAME. For example, for a host with a nickname of
ZOO, the WEBMASTER should be specified (in INITFILT.80) using:
WEBMASTER.ZOO='MANAGER@ZOO.YOURSTATE.ORG'
.
If a matching
host-specific entry does not exist, the "generic" entry (in this case,
WEBMASTER) would be used.
- Both "built-in" and "user-defined in the ATTRIBS.CFG and REPSTRGS.IN file"
variables can be host specific (using the above syntax in both cases).
- When including static variables in your HTML documents,
the .HOST_NICKNAME should not be appended!
For example, if the ZOO host is asked for INDEX.HTM, and INDEX.HTM
containsthe tag:
<!-- REPLACE WEBMASTER -->; SRE-http would look up the value of the
WEBMASTER.ZOO variable.
In contrast, if the tag were: <!-- REPLACE WEBMASTER.ZOO -->
SRE-http would look for WEBMASTER.ZOO.ZOO.
-
Dynamically determined information consists of variables that are
determined at the moment the request is recieved. For example:
<!-- REPLACE TIME
-->
will cause the current (local) time to be placed in the document.
- Static information is the same for all requests (to a given host). Inclusion of
static variables can be a great convenience when writing sets of HTML
documents, especially if phrases that occur in all these documents are subject to
frequent change (say, a daily message).
- The HIT_CACHE_LEN and HIT_OWNER_SUPPRESS variables can be used to reduce the
number of false hits.
Return to table of contents
4.b.ii) The INCLUDE keyphrase
Syntax: <!-- INCLUDE FileName -->
, where FileName is
the name of the File to be included.
The INCLUDE keyphrase instructs
SRE-http to include the contents of a file
into the requested document
(where argument is the file-to-be-included).
For example, INCLUDE PHONE.LST
would cause the contents of the file PHONE.LST
(in your data directory) to be inserted into the
document.
Examples
<!-- include buttons.bar -->
<!-- include newtoday.txt -->
Special Feature: Browser and Client Specific File Includes
You can use the ByBROWSR.RXX INTERPRETable
utility to selectively
include browser-specific files into your documents. These can be
complete documents (with the "requested document" containing only a stub);
or you can include smaller browser specfic components in an otherwise
all purpose document.
In a similar vein, the
ByCLIENT.RXX INTERPRETable
utility can be used to selectively include files on a "client-specific"
basis, where clients can be identified with cookies, privileges, or
their IP address.
Notes
- It is recommended that
INCLUDE keyphrases appear on seperate lines of a file (with no other HTML
statements or text).
The file is treated as a long string (that contains linefeeds)
and replaces the keyphrase -- anything before or after the keyphrase
(on the same line) will be placed just before and after the contents of
the file.
- FileName is interpreted relative to the Data Directory, or
to a "local" virtual directory .
- The INCLUDE keyphrase will check for potentially fatal, recursive
file INCLUDES, and disallow them. Since this check is very primitive, it
will also disallow multiple INCLUDEs of the same file. If you need to
include a file multiple times
(say, to position a button bar at the top and bottom of your
document), you can use the #INCLUDE keyphrase.
- INCLUDE, in combination with the INTERPRET keyphrase, facilitates
customization of your documents , based on client specific informaton
(such as the
user agent
)!
Return to table of contents
4.b.iii) The OPTION keyphrase
Syntax: <!-- OPTION n -->
, where n is an integer.
The OPTION keyphrase instructs SRE-http to insert the contents of
the n'th OPTION into the document.
OPTIONs are contained in the portion of the request following the ? character.
How to pass OPTIONs to a document
To pass OPTIONs to a document, the selector portion of the request
should have the form:
HTMLFILE.HTM?Your+OPTION+1&OPTION2
- In this example ....
OPTION 1
keyphrases in HTMLFILE.HTM
would be replaced with the string Your OPTION 1
-
OPTION 2
keyphrases in HTMLFILE.HTM
would be replaced with OPTION2
.
-
OPTION 3
keyphrases in
HTMLFILE.HTM will be removed (since only two options appear in
the request).
- URL character decoding
is done on the string following the ? character.
- You can have as many OPTIONs as you like, each seperated by a &.
OPTIONs and searchable indices.
When a browser responds to document containing the <ISINDEX >
element, the request will have the same
HTMLFILE.HTM?word1+word2
format. In order
to properly respond to such "searchable index generated" responses, you should set up an
ALIAS
Examples
<!-- Option 1 -->
<!-- Option 3 -->
Notes
- The OPTION keyphrase is somewhat obsolete -- the use of
cookies may be more appropriate
(see SAMPCOOK.SHT for an example).
- OPTIONs can be useful as a simple means of keeping track of where
the client came from. For example, you can use the OPTIONs keyphrase
to include message about "where you came" from in linked
documents.
The SAMPOPT1.SHT and SAMPOPT2.SHT files bundled with
SRE-http demonstrates this use of OPTION (careful, it causes
problems if disable SSI).
Another example (albeit trickier), is to use
OPTION keyphrases to customize URLS, with the goal of helping
the client return to one of several potential "invoking"
documents.
- The OPTIONs are stored in the OPTLIST. "stem" variable,
with OPTLIST.0 containing the number of OPTIONs recieved.
This information can be used in INTERPRET keyphrases to help customize
documents.
Return to table of contents
4.b.iv) The INTERPRET keyphrase
Typical syntax: <!-- INTERPRET FILE xxx.RXX -->
INTERPRET provides a means of including and executing
a REXX-code-block
There are two major variants of the INTERPRET keyphrase:
-
INTERPRET CODE statment 1 ; statement 2 ; ...
;
where each statement n
is a valid REXX statements (and
each statement is seperated by a semi-colon).
For example:
INTERPRET CODE tmp1=server() ; interpret.result=tmp1
A Shorthand: You can use # instead of INTERPRET CODE
-
INTERPRET FILE Filename arg_list
,
where: -
Filename
is a file containing REXX code
(filename
is assumed to be relative to the SRE-http addon directory,
or to a "local" virtual directory).
-
arg_list
is an optional comma delimited list of
"arguments"
A Shorthand: You can use $ instead of INTERPRET FILE
Example
- If your document contains the keyphrase:
- <!-- INTERPRET FILE GOBED.RXX-->
( or, equivalently,
<!-- $ GOBED.RXX-->
)
- and GOBED.RXX contains:
- tmp1=time('h') ; if tmp1<6 | tmp1>23 then
interpret.results=" <em> It is late, GO TO BED! </em> " ;
then the phrase It is late, GO TO BED! will appear in your
document whenever your local time is between 11:00 P.M and 6 A.M.
In general, the INTERPRETed REXX-code-block
should include one or more of the following:
- A SAY or AUDIT command (for writing status messages)
- Assignment of a (possibly multi-line) string to
the INTERPRET.RESULTS variable. The contents of
INTERPRET.RESULTS is
written into the document (at the location the keyphrase occupies).
- A QUEUE (or PUSH) command -- with each QUEUEd (or PUSHed) string
automatically appended to INTERPRET.RESULTS (see the discussion of
the USE_STDOUT variable in INITFILT.DOC for more details on this #EXEC-like
feature)
- RETURN 'stuff to include'
Notes:
- When processing a REXX code-block, syntax checking is turned on -- coding
errors will cause the code-block to fail, but will not crash GoServe.
INTERPRET FILE
blocks are "interpreted"
by SRE-http -- they are not called as external procedures.
Therefore: an INTERPRET FILE code-block
can not contain
procedures or subroutines
This inconvenience can be partially ameliorated by calling "external" procedures from
within the INTERPRET FILE code block.
- If a
RETURN
is encountered in an INTERPRET file, the "returned"
string is used as the server side include (the value stored
in INTERPRET.RESULTS, and output from PUSH and QUEUE statements, are
ignored).
- The comma delimited
arg_list
can be accessed using
the usual REXX
syntax (i.e.; parse arg aval1,aval2
). You can
include up to 10 arguments.
- The following functions and variables can be accessed by a REXX code block:
servername
: IP name of the server (useful on multi-host servers)
host_nickname
: SRE-http's host nickname (for this servername
)
-
optlist.
: The option list stem variable (the "options"
following a ?
in the request).
-
privset
: A list of the client's privileges (not including
secret privileges).
-
verbose
: The VERBOSE variable (higher values for more PMPRINTF output)
-
docname
: The "action" portion of the request
-
ddir
: The "default data directory" (may be host specific)
-
usedfile
: The fully qualified name of the requested file
-
Get_value(env_var)
: The GET_VALUE
function will return the value of
an SRE-http "environment" variable.
- If you wish to have INTERPRET CODE conditionally include a ssi keyphrase
(say, an <!-- INCLUDE filename.ext --> keyphrase), you should use the special
MKSSI function. MKSSI will wrap the keyphrase with
<!-- and -->, thereby avoiding confusion (since SRE-http
uses the first --> it finds as an end of keyphrase delimiter). For example:
<!-- INTERPRET CODE if SREF_BROWSER_INFO('TABLES')='YES' then ;
return mkssi('INCLUDE TABLEVER.HTM') ;
else ;
return mkssi('INCLUDE TEXTVER.HTM ');-->
- You can use the REDIRECT function to conditionally redirect. For example:
<!-- INTERPRET CODE if extract('clients')>3 then ;
interpret.result=redirect('http://foo.bar.net/busysite.txt') ;
else ;
interpret.result=redirect('pages1/oksite.html',302);-->
Note that a second argument can be included: 301 (permanent redirection),
302 (temporary redirection), and 200 (text message redirect); the
default is 301 (permanent redirection). Also, relative URLs (selectors)
are interpreted relative to your server (and port).
- You can access the GoServe functions (such as the REQFIELD function).
- There are several SRE-http procedures, including string manipulation routines,
that you may find useful.
- If you have multiple
INTERPRETs
in a document, you can
use the GLOBALS. stem variable to retain variables.
All other variables are local to each INTERPRET
keyphrase.
For example, you could set GLOBALS.ATIME=time() in an early INTERPRET
,
and reference GLOBALS.ATIME later in the document (say, to compute the
time it takes to process some intermediate steps).
-
INTERPRET
will be ignored if NO_PROCESSING='YES', or if a NO_SSP permission applies to this selector.
-
INTERPRET CODE
keyphrases will be ignored if
NO_INTERPRET_CODE='YES', or if a NO_CODE permission applies to this selector.
Note that INTERPRET FILE keyphrases are not effected
by NO_INTERPRET_CODE
- When using
INTERPRET CODE
: each statement must end with a semi-colon.
- If your needs are complicated, you might want to
write your own SRE-http addon; typically this would be a
REXX routine that would generate an HTML document that SRE-http
would then return to the client
However, when combined with the other keyphrases, the INTERPRET
keyphrase can accomplish quite a bit of customization!
- DIRINFO.RXX, USETABL2.RXX, BYBROWSR.RXX, MTCHFILE.RXX, and ADDPRIVS.RXX are samples of
INTERPRET FILE
files (ADDPRIVS.RXX uses the arg_list
).
- Obsolete: An INTERPRET_FILE can be used to store
small rexx-code-blocks using a "label" system. However, we no longer
recommend this method.
Return to table of contents
The SELECT, and the #IF, keyphrases are qualitatively different from the other
keyphrases -- they
act as a "conditional server side include" of HTML code that is already
in your document.
The power of SELECT is the ability to check dynamic variables (such as the
client's IP address, or his user agent), and retain or exclude a portion of the
HTML document accordingly.
A SELECT keyphrase expects an argument containing a block of REXX code, just
like the code blocks used in the INTERPRET keyphrase. This
block of code will be interpreted
. The code block
should "exit" with either a RETURN 1
or
RETURN 0
, where:
RETURN 1
: the subsequent HTML text block
is retained
RETURN 0
:the subsequent HTML text block is
deleted.
The "subsequent HTML text block" is delimited by a
SELECT END
keyphrase, and
can be of any length (if no SELECT END
keyphrase is encountered, the remainder of the file is dropped).
Lastly, if there is no RETURN, the code block is retained (i.e.;
the default is RETURN 1).
Example:
<!--SELECT
tmp.1=extract('clientaddr') ;
tmp.2=sref_value('OWNERS',,'INI');
tmp.3=wordpos(tmp.1,tmp.2); ;
if tmp.3=0 then return 0
-->
<em> Hello! You have SuperUser Privileges !! </em>
<!-- SELECT END -->
Note that RETURN 1
is assumed by default,
hence when the clients IP address is listed in the
an OWNER variable (and the code block ends without a return)
the Hello! ...
message will not be deleted.
Notes
- The following variables are available to a SELECT "code block":
host_nickname, optlist., privset, servername, verbose,
ddir, docname, and usedfile
In addition, you can
- access the "GoServe" variables (such as clientaddr, selector,
and serveraddr) using the EXTRACT function.
- access other GoServe functions, such as clientname()
- access SRE-http variables using SREF_VALUE(). In particular,
the initialization variables (set in INITFILT.80)
can be accessed by using avar=SREF_VALUE(varname,,'INI')
- SELECT will not be done if:
NO_PROCESSING='YES', NO_INTERPRET_CODE='YES', or if
either a NO_CODE or a NO_SSP permission applies to this selector.
- SELECT blocks can not be nested. They may
contain other keyphrases.
- Older versions of SRE-http used
SELECT.RESULT=1 and
SELECT.RESULTS=0
instead of RETURN 1
and RETURN 0
(respectively).
This is still supported, but it is not recommended.
- SELECT keyphrases are processed somewhat more slowly then other keyphrases -- for
small replacements, you might want to use INTERPRET keyphrases instead.
Notes:
- The XSSI #IF ssi element can also
be used for conditional includes. #IF
can be nested, but the test conditions (string comparisons)
are simpler.
- If you've played around with the DELIM_1 and DELIM_2 parameters: when
entering the beginning and end SELECT keyphrases, you
must use the same set of delimiters.
Return to table of contents
You can use the simple-mode
configurator to enable caching of server side includes
To improve performance, SRE-http will "cache" HTML documents that
have server side includes (SSI). This caching is of the document
after the SSIs have been performed.
In simple cases SRE-http can send this cached file, without having to repeat the actual
process of SSI lookups, etc. Needless to say, this can greatly
improve server performance.
Note: SSI caching is not the same as allowing proxy servers
(or the GoServe cache, or SREPROXY) to cache a response
For a complete description of SRE-http's SSI-caching algorithim,
and of the various options available for the CACHE keyphrase,
please read SSICACHE.HTM .
What follows is a very brief description of the options available
for the CACHE keyphrase.
- <!-- cache no -->
- Do not cache this document
- <!-- cache asis -->
- Use a cached version "as is"
- <!-- cache notrigger -->
- Do not check the trigger files; but do check the own
file.
- <!-- cache duration nnn -->
- Set the lifespan for this file's cache entry, where nnn is the number
of (possibly fractional) days.
- <!-- cache trigger file1 file2 .. -->
- Check the file-stamps of these fully
qualified files.
- <!-- cache trigger_type stamp -->
- Selects which field(s) of the trigger file-stamps
to check.
Return to table of contents
With only minor exceptions, the server side include syntax of the NCSA HTTPD server is
fully supported by SRE-http.
These are invoked with a keyphrase of:
<!-- #cmd option="value" -->
Where cmd
can be: CONFIG ECHO EXEC FLASTMOD FSIZE IF INCLUDE SET
4.c.i) Details on NCSA HTTPD server side includes
- #INCLUDE: Include a file.
option
can be VIRTUAL or FILE.
If VIRTUAL
then value should be a relative file name
(relative to the data directory or to a "local" virtual directory).
If FILE,
then value is interpreted relative to the directory
containing the
"requested file" (the file that contains this server side include).
Note: #INCLUDEd files will not be checked for
recursive includes. To check for recursive
includes, use the <!-- INCLUDE filename --> keyphrase.
Examples:
<!-- #include virtual="/samples/intro.doc" -->
If your data directory is D:\WWW,
then D:\WWW\SAMPLES\INTRO.DOC will be included.
<!-- #include file="intro.doc" -->
If your data directory is D:\WWW,
and if the selector containing this SSI is /SAMP2/INDEX.HTM
then D:\WWW\SAMP2\INTRO.DOC will be included.
<!-- #include file="/samples/intro.doc" -->
If your data directory is D:\WWW,
and if the selector containing this SSI is /SAMP2/INDEX.HTM
then D:\WWW\SAMP2\SAMPLES\INTRO.DOC will be included.
- #CONFIG: Configure some options.
option
can be:
- ERRMSG: Error message to display when a bad request is made
- SIZEFMT : If
value=ABBREV
, will display kilobytes or
megabytes (as appropriate). Otherwise, displays exact byte count (with
commas added).
- SRE-http modification: ABBREV will generate
nnn.nnM
style abbreviations (i.e.; 3.12M
);
the standard seems to be nnnM
(i.e.; 3M
). If you prefer this terser standard,
use MABBREV instead of ABBREV.
- TIMEFMT: A set of instructions on how to display time and date.
These are based on the strftime C function -- see
TIMEFMT.DOC for a
description of the various options.
Examples:
<!-- #config sizefmt="abbrev" -->
<!-- #config timefmt="%A , %c (%r) ==is %j day of year" -->
<!-- #config errmsg=" Sample error message " -->
- #FLASTMOD: Modification date of a file.
The option
and value
are the same as for #INCLUDE
Examples:
<!-- #flastmod virtual="/samples/intro.doc" -->
<!-- #flastmod file="intro.doc" -->
- #FSIZE: Size of a file
The option
and value
are the same as for #INCLUDE
Examples:
<!-- #fsize virtual="/samples/intro.doc" -->
<!-- #fsize file="intro.doc" -->
- #EXEC: Execute a CGI script.
option
should equal CMD, and value
should be a file name (in the CGI_BIN_DIR directory)
of a CGI script (typically a REXX program or an executable).
Note that the EXEC server side include captures the
output of the script, and includes this output in the
requested document. EXEC will not be done if NO_PROCESSING=YES,
or if a NO_SSP permission applies to this selector.
Example:
<!-- #exec CMD=jcount?index.htm -->
- #ECHO: Value of a variable
option
should be VAR, value
should be a
variable name. This is equivalent to the
REPLACE keyphrase, but with different variable names (although many of them overlap).
The supported variables are:
DOCUMENT_NAME, DOCUMENT_URI, DATE_LOCAL, DATE_GMT, LAST_MODIFIED,
SERVER_SOFTWARE, SERVER_NAME, GATEWAY_INTERFACE, SERVER_PROTOCOL,
SERVER_PORT, REQUEST_METHOD, SCRIPT_NAME,
QUERY_STRING, REMOTE_HOST, REMOTE_ADDR, AUTH_TYPE, AUTH_NAME,
HTTP_ACCEPT, HTTP_REFERER, HTTP_USER-AGENT
Unsupported variables are (they really aren't relevant to server side
includes):
PATH_INFO, PATH_TRANSLATED, REMOTE_IDENT, CONTENT_TYPE, CONTENT_LENGTH
Examples:
Server Software: <!-- #echo var="SERVER_SOFTWARE" -->
GMT date and time: <!-- #echo var=DATE_GMT" -->
Http accept: <!-- #echo var="HTTP_ACCEPT" -->
Http user_agent: <!-- #echo var="HTTP_USER-AGENT" -->
- #IF: Conditional inclusion of HTML
The #IF element has the following syntax:
<!--#if expr="test_condition" -->
some html
<!--#elif expr="test_condition" -->
some other html
<!--#else -->
some default html
<!--#endif -->
The if
element works like an
if statement in a programming language. The test condition
is evaluated and if the result is true, then the text until
the next elif
, else
.
or endif
element is included in the
output stream.
The elif
or else
statements are used if the original test_condition is false.
These elements are optional. Note that the first
true statement is used, and else
is always true (it does NOT take an expr
).
EXAMPLE: the below example will print "in foo" if the DOCUMENT_URI is
/foo/file.html, "in bar" if it is /bar/file.html and "in neither"
otherwise:
<!--#if expr="\"$DOCUMENT_URI\" = \"/foo/file.html\"" -->
in foo
<!--#elif expr="\"$DOCUMENT_URI\" = \"/bar/file.html\"" -->
in bar
<!--#else -->
in neither
<!--#endif -->
Notes:
- #IF ... #ELIF ... #ELSE ... #ENDIF blocks can be nested.
- The SRE-http SELECT ssi element can also
be used for conditional includes. SELECT
can not be nested, but the test conditions can be far
more elaborate (given that you understand REXX).
- #SET: Define a variable
The #SET element has the following syntax:
<!-- #set var="varname" value="a value" -->
These variables can be used (as a textual substitution)
in any HTTPD-style server side include --
just prepend a $ before the varname. For example:
<!-- #set var="foobar" value="hello world" -->
<!-- #echo var="$foobar" -->
Need more information on NCSA HTTPD server side includes
(and
the XSSI extensions)
Return to table of contents
4.d) Order of execution of SSI keyphrases
Server-side includes are processed in the following order:
- The requested document is read into memory.
- Headers and Footers, if specified, are included.
- The document,
(that now includes headers and footers),
is scanned for keyphrases.
- When a keyphrase
is encountered, the appropriate server side include is performed; or if
a SELECT keyphrase is encountered, a server side "exclude" may be conducted.
- After each keyphrase is processed, step 4 is repeated
(from the beginning of the file).
- This process continues until there are no more
keyphrases.
- If you've specified more then one set of keyphrase delimiters,
step 3 will be repeated for each set.
Note that the keyphrases in the latter part of a
document are processed after
freshly included keyphrases.
While not the most efficient algorithim (long documents with many
server side includes will cause a lot of string comparisons),
it does enable recursive processing of all keyphrases
This recursive feature allows for some powerful document manipulation strictly through
the use of keyphrases. In particular, the INTERPRET keyphrase can examine variables
such as the "referer", the "client name", or the "OPTION list", and generate
inclusions that incorporate other keyphrases (which will be
processed on the next
cycle of keyphrase interpretation).
There are several caveats:
- SRE-http will check for potentially fatal recursive
includes,
and disallow them. If this should occur, a simple error comment is
added to the document that is sent to the client. See the description
of the INCLUDE and #INCLUDE keyphrases for some important provisos.
- If you use the AUTO_HEADER feature, you should not
place server side include keyphrases in the <HEAD> portion of your
HTML documents.
- In general, we do not recommend use of the
DO_SEND_PIECE (the
send pieces as they become available) SRE-http option.
If you do use it, note that:
- SSI-caching will be suppressed ,
- You will not be able to dynamically add cookies (say,
with an INTERPRET keyphrase)
- DO_SEND_PIECE is suppressed if:
- there is more then 1 set of
keyphrase delimiters, or
- the FIX_EXPIRE option is being used.
Return to table of contents
5) Imagemaps, CGI-Bin Scripts, and SRE-http addons
The modern web site is apt to provide an array of service to its clients.
These services, which imply more then just the delivery of documents
and images, are based on an interaction between the client and
the server; with the server using information recieved from the
client, recording and otherwise manipulating this data,
and returning some results.
Delivery of this server side processing typically requires
installation of some sort of program that adheres to an application
programming interface (API) for
communicating to web clients via a web server. SRE-http supports
several such API's, including:
NCSA and CERN server side imagemaps
GoServe/SRE-http addons
The Common Gateway Interface (CGI-BIN)
5.a) Using imagemaps
SRE-http provides a simple means of responding to
image maps, using
NCSA or CERN style "MAP" descriptor files. The key is to include a
map-image indicator substring in the the "resource location" of a
URL that points to a .MAP file.
More specifically, when a MAPIMAGE/ substring is encountered in
the action portion of the request, SRE-http will remove MAPIMAGE/, and assume the
remaining portion of the action refers to a NSCA MAP file (similarly, a
MAPCERN/ substring refers to a CERN MAP file).
For example, if the request selector is:
MAPIMAGE/PROJECTS/BRANCH1.MAP?55,123
then the "mappable image" handler would look for
PROJECTS\BRANCH1.MAP
(under the data directory,
or a "local" virtual directory), and use
the instructions therein (in conjunction with the pixel location 55,123)
to "redirect" the client.
5.a.i) Type of regions recognized.
There are four types of regions recognized by SRE-http:
-
Circles
-
Rectangles
-
Polygons
-
Points
- and you should always specify a default URL
The selected pixel will be assigned to the URL associated
with the first Circle
, Rectangle
,
Polygon
, or 'exactly-hit' Point
it matches.
If there is no such match, and
there are Points
specified in the MAP file, then the
URL associated with the closest Point
is used.
However, if the distance to this closest Point
is greater
then the value of the MAX_POINTDIST variable,
or if there are no Points
specified in
the MAP file, the default URL is used.
Notes:
- To modify the map-image indicator substrings used to indicate
a CERN and NCSA imagemap, see the description of the NCSA_ISMAP and CERN_ISMAP variables
in INITFILT.DOC
- The MAP file must be in your data directory,
or a "local" virtual directory
(i.e.; if your data directory is
E:\WWW, then the above example refers to E:\WWW\PROJECTS\BRANCH1.MAP)
- There are several handy "map" making tools available, such as MAPEDIT.
- HTACCESS is never checked for image map requests (but
HTML documents that contain clickable images are subject to HTACCESS controls).
- The SAMPMAP.HTM file that comes with SRE-http (which uses SAMPMAP.MAP and SAMPMAP.GIF) provides a simple example.
- Your MAP file should, but need not, contain fullly specified URLS. The http:// will be added
if missing; and if there is no IP address, your server's address (and port) are added.
- If the selected URL (the URL corresponding to the selected point) is a
"virtual URL" (contains no IP address, and does not start with a /), then
the invoking URL (minus the MAPIMAGE/) is used.
Thus,
- if the selected point is associated with
ANIMALS/TIGER.HTM,
- the .MAP file was /ZOO/GUIDE/CAGES.MAP,
- THEN ...
- the selected URL will be /ZOO/GUIDE/ANIMALS/TIGER.HTM.
- SRE-http's MAPIMAGE procedures are borrowed from Don Meyer's GoHTTP
package!
Please remember that the MAPIMAGE/ "indicator string"
does not refer to the MAPIMAGE/ directory!
Return to table of contents
5.b)Creating SRE-http addons
As an alternative to CGI-BIN scripts, SRE-http addons can provide
a faster (and less convoluted) REXX based method of creating web aware
applications.
The basic idea
is to write an "external" REXX procedure which will do the processing, or which calls
some other executable program (such as a database manager) -- and then tell
SRE-http to call this procedure.
The following steps outline how to do this:
- Create an HTML document that returns an
action
that invokes a Server
Side Processing request. For example, you might include a FORM
element with an ACTION attribute of "/XXX".
- Create a file (that contains your REXX procedure), with the name
xxx.CMD (or xxx.80) , where
xxx is the action name. Note that the
xxx file is relative to the ADDON directory (or a
"local" virtual directory).
For example, if the action name is /PROGS/FAST2, and \GOSERVE\ADDON is your addon directory,
SRE-http will look for \GOSERVE\PROGS\FAST2.CMD.
- This REXX procedure should process the request (using information
passed to it by SRE-http), and it
may call other programs (not necessarily REXX programs).
- xxx should issue GoServe completion
codes (such as VAR, FILE, and STRING).
5.b.i) Calling Syntax
SRE-http will call your addon with several arguments.
The addon can read these arguments using:
parse arg ddir, tempfile, action,list,verb ,uri,user, ,
basedir ,workdir,privset,env_id,transaction,verbose, ,
servername,host_nickname,home_directory,param1,semqueue, ,
prog_file,request_num
The following describes these arguments (note that several of these arguments
are rather arcane or are nearly obsolete):
- ddir
- The data directory, may be host specific (typically, x:\WWW)
- tempfile
- The temporary, "transaction specific" file (i.e.; D:\GOSERVE\TEMP\$341.80)
being used by this request
- action
- The action portion of the request (the portion of a request before a ?)
Example (assuming the GET HTTP method
was used by the client)
- If the request selector is:
/sports/getscore?city=boston&date=July+5+1994
-
then the action is sports/getscore
- list
-
- If verb=GET: the partially cleaned up portion of the request selector
after the ?
(URL decoding is performed).
In the above example, list would be city=boston&date=July+5+1995
- If verb=POST: the body of the request -- without URL decoding.
- verb
- Either GET or POST
- uri
- The "universal resource indicator" -- the
request-line
portion of
the original request string,
as sent by the client to the server --
without cleanup or encoding (but with "special ! directives" removed).
This can be useful if & (and other special characters) may
be text returned by GET method client requests -- in which case
the partial processing done to the list may cause trouble.
Note: http GET
requests have 3 components: a verb, a request line, and a protocol.
- user
- The numeric IP address of the client
- basedir
- The "base directory", where SRE-http (and probably GoServe)
are located.
- workdir
- The fully qualified name of a directory
that the addon can use for "temporary" files.
(set in the TEMPFILE_DIR variable).
- privset
- The list of user privileges granted to this client.
This will be divided into two sections (seperated by a comma). The first
section contains the regular privileges, and the second section contains
the secret privileges (the privileges that start with a ?).
These secret privileges are reported without the leading ?.
- env_id
- A substring that can be used when directly accessing the innards of SRE-http
(rarely used)
- transaction
- The transaction number
- verbose
- The verbose instruction (1 signifies "say intermediate results").
- servername
- The IP name of the "host" this request is addressed to. This is derived
from a HOST: request header, or from the numeric ip address.
- host_nickname
- The SRE-http nickname for the "host".
- home_directory
- The "home directory" (used in ~ replacment)
- param1
- A parameter used for by some older addons (rarely used)
- semqueue
- Semaphore/queue information -- used by the daemon manipulation
procedures (as described in DAEMONS.DOC)
- prog_file
- Fully qualified name of the file (containing this addon). If addon
was "loaded from macrospace", this will be an empty string.
- request_num
- The request number. Note, that in the maintain-connection world of http/1.1,
there may be multiple requests per transaction.
5.b.ii) Return Values
The xxx.CMD procedure should return a
simple status message of the form:
response_code bytes_returned Description Message , file_used
Where:
response_code
: the http response code (typically, 200 for
GET requests and 201 for POST requests)
bytes_returned
: the number of bytes transfered (should not
include response headers)
Description message
(optional) : a descriptive
message (it's transferred to the post-filter)
file_used
(optional) : The program that was run
(must follow a comma)
Examples:
200 12515 Message Succesfully Recieved, D:\GOSERVE\MESSAGES
401 302 Unauthorized access of PRIVATE DATABASE
5.b.iii) Notes
- For further hints on programming to the SRE-http API, see
MK_ADDON.HTM and the
documentation for the SRE-http procedure library
- How does SRE-http recognize a request to run an addon or a
CGI-BIN script?
- If VERB=GET
... SRE-http looks for
a ? character in the request selector , and also checks that the
request is not for a text/html file.
- If VERB=GET and the action portion of the request selector contains
a
CGI-BIN/
, then it's assumed to be a request to run a CGI-BIN script.
- If VERB= POST
... SRE-http assumes it is a request for an addon (or a CGI-BIN script)
- Caution: As a probably-unwise-but-too-late-too-change-now
convenience, on GET method requests the
LIST
parameter has
been URL decoded. While saving programmers a step, this does make it
difficult to detect & and = signs.
Therefore,
careful programmers may wish to use the URI
variable when processing
GET method requests. Alternatively, you may wish to suppress this decoding by
changing the value of the GET_DECODE_OPTIONS parameter in INIT_STA.80
- STATUS.CMD, and STATUS.HTM, contain an example of how to
request Server Side Processing using a REXX
procedure.
- If a syntax error occurs, SRE-http will trap it and return
a simple error message to the client.
- To call an external, non-REXX program from within an
external REXX procedure, use the
address cmd
REXX command.
- If you write HTML code to TEMPFILE (for return to the client), you
should return from your external REXX procedure using:
foo=SREF_GOS('FILE ERASE TYPE text/html NAME ' TEMPFILE )
return response_code #_bytes a message here
- When using an HTML FORM to invoke an SRE-http addon,
we recommend that the "action" contain a leading / character
(this avoids incorrect path assignment by the browser).
- If the NO_PROCESSING variable equals YES,
or the NO_SSP permission is enabled,
then server side processing will not be permitted.
Return to table of contents
5.c)Support for CGI-BIN scripts.
SRE-http supports CGI-BIN scripts (using procedures adapted from
Don Meyer's GoHTTP package). To run CGI-BIN scripts, you'll need to:
- Make sure that the CGI_BIN_DIR points to an existing
directory (i.e.; \GOSERVE\CGI-BIN).
- Copy the CGI-BIN script (such as a REXX file, a binary .EXE file, etc.)
to the
CGI_BIN_DIR directory.
- Invoke it using a standard CGI-BIN request selector . For example:
href=http://foo.bar.net/cgi-bin/test-cgi/morepath/?a+message
.
SRE-http's implementation of CGI-BIN has one major improvment: the ability
to send pieces of the output as they are created. That is, one can:
- wait for the CGI-BIN script to end, and then send all the output it generated
... or
- send output as it is generated
The second option is especially useful when large amounts of output are being
generated (it avoids some troublesome server-timeout & client-impatience
problems). For details see the discussion of the CGI_BIN_PIECES variable
in INITFILT.DOC
SRE-http's implementation of CGI-BIN also includes a few minor modifications:
- A few additional environment variables are created. The most
important one is SREF_PRIVSET -- it contains a list of the client
privileges (but not the secret privileges).
- SRE-http comes with a few sample CGI-BIN scripts (written in REXX).
The TEST-CGI.CMD
file (which is copied to your CGI_BIN_DIR) will display the values of the
CGI-BIN variables (invoke it using /CGI-BIN/TEST-CGI).
Need more information on CGI-BIN ?
By default, CGI-BIN scripts are assumed to be in the CGI_BIN_DIR directory
(say, \GOSERVE\CGI-BIN). Obviously, this can become inconvenient
once you acquire a greater-than-small set of scripts. The obvious
solution is to place the script files in subdirectories.
Unfortunately, there does not seem to be a clearly specified method
of doing this. With this in mind, SRE-http offers two means
of specifying subdirectories containing your CGI-BIN scripts:
- Using "aliases".
This does not require changes to the standard syntax of
CGI-BIN request selectors; i.e.; CGI-BIN/ASCRIPT/PATHINFO/?args ).
The disadvantage is that a seperate alias is need for each script --
even for scripts in the same subdirectory.
- Using the portion of the request selector before the
CGI-BIN/
The notion is to include subdirectory information before
the CGI-BIN/
(the "this is a CGI-BIN script" indicator). SRE-http
will interpret this starting portion as a subdirectory of the CGI_BIN_DIR,
or as a virtual directory (in both cases,the usual HTACCESS controls may apply).
This permits a powerful division of scripts into directories. The disadvantage
is that it doesn't seem to be "spec" (hence may be cumbersome to port).
Requests for CGI-BIN scripts are often followed by /PATHINFO/.
This is typically used by the script (it does
not point to the script).
Example: KIDSTORE/INVENTORY/CGI-BIN/TOYCT?toddler
This invokes the TOYCT program (with an argument of toddler
),
which is located
in (perhaps) \GOSERVE\CGI-BIN\KIDSTORE\INVENTORY\.
5.c.ii) Notes on creating CGI-BIN scripts
- When writing CGI-BIN scripts, keep in mind that a number of
variables are available in the enviroment.
- You can output results with SAY statments.
- Your first SAY statements should declare the MIME type. For example:
Say "Content-type: text/html"
Say
5.c.iii) Using PERL scripts with SRE-http
In order to take advantage of a broad spectrum of CGI-BIN scripts,
SRE-http can use "non-REXX" processors to interpert CGI-BIN scripts.
As long as you have the appropriate interepreter installed on your
server, it's quite easy to do this. All that you need to do is
tell SRE-http (using the INTERPRET_TYPES parameter) which
interpeter to associate with different file extensions -- see
INITFILT.DOC for a details on how to change the INTERPRET_TYPES
parameter.
Of particular interest is the use of one of the OS/2 PERL interpreters;
since there are a slew of PERL scripts out there. In fact, it's not that
hard to obtain a PERL interpreter --
see PERL.DOC for details
on one we've had some success with.
Return to table of contents
6)Miscellaneous SRE-http features
SRE-http has numerous features that allow you to selectively
record and audit requests, upload files, perform "pre-filter" and
"post-filter" actions, and otherwise engage in
sundry trickery and sleight of hand.
6.a) Special commands, and directives, recognized by SRE-http
SRE-http offers a set of special commands,
and special directives for performing
TCP/IP actions, computing statistics on the status of GoServe, and
requesting special server actions. These command all start with
an exclamation point (!), followed by a word or a phrase.
The special commands are basically built-in "server side
programs". In contrast, the special directives are used to
modify SRE-http's logic.
6.a.i) Currently available special directives
- !force/selector
- The
!FORCE
special directive instructs SRE-http to
suppress the LOGON_FAIL_FILE (and ACCESS_FAIL_FILE)
feature when considering the selector
.
This guarantees that unauthorized clients will be presented
with a username/password screen.
!FORCE
is meant to be used in the LOGON_FAIL_FILE and
ACCESS_FAIL_FILE, where it
provides a means by which a client can try again with a different
username/password. It is also used to force re-compilation
of an HTML document with server side includes (in other words, it
suppresses use of the SSI-Cache).
Hint: To avoid problems with NetScape, use !FORCE/xxx
instead of !FORCE?xxx
Examples:
- !FORCE/DIR1/INDEX.HTM
- !FORCE/DIR2/INCS/INDEX.SHT
- !NOBALANCE/selector
-
!NOBALANCE
will suppress all attempts at load balancing --
the recieving server will process the request.
- !CGI-BIN_n (n=0,1,2, or 3)
- Overrides the
CGI_BIN_PIECES
and EMPTY_PATH_OK
parameters on a selector specific basis.
- 0 : Sets EMPTY_PATH_OK=0 and CGI_BIN_PIECES=0
- 1 : Sets EMPTY_PATH_OK=1 and CGI_BIN_PIECES=0
- 2 : Sets EMPTY_PATH_OK=0 and CGI_BIN_PIECES=1
- 3 : Sets EMPTY_PATH_OK=1 and CGI_BIN_PIECES=1
Notes:
-
EMPTY_PATH_OK
controls how CGI-BIN PATH_INFO
is saved to the OS/2 Environment.
CGI_BIN_PIECES
enables the
the send CGI-BIN (stdout) output as it becomes available mode
- For further details on
EMPTY_PATH_OK
and
CGI_BIN_PIECES
, see INITFILT.DOC.
Examples:
- http://foo.bar.net/!CGI_BIN_0/CGI-BIN/TEST-CGI
- http://bar.foo.gov/!CGI_BIN_2/CGI-BIN/WWWPAGE.EXE?Status
- !RANGE
-
The !RANGE special directive instructs SRE-http to send a
range of a resource. !RANGE can be used to send selected bytes,
lines, and sections of a resource to the client. This
can be a convenient way to subset a resource (say, instead of
having multiple files).
Examples:
<A href="!range:bytes=100-1000,10000-120000/outline.doc">
Useful Tools</a>
<A href="!range:lines=-50,200-500,1200-/prices.cur">
Fruit Prices</a>
For further details on the syntax of the
!RANGE directive, see RANGE.HTM
- !RUN
- The !RUN special directive is used to expedite processing of SRE-http
addons. In particular, it is meant to be used with SRE-http addons that
have been referenced in one of the
KEEP_ADDON.
entries.
Examples:
- <a href="/!RUN/GIF_TEXT&font=enviro&text=hello">
- <a href="/!RUN/STATUS?">
When !RUN is used, SRE-http assumes the addon has been preloaded into
macrospace (hence the KEEP_ADDON.
requirement). With
this assumption, it is possible to not bother with a fair amount of overhead --
thereby expediting loading and execution.
For more details, see the description
of KEEP_ADDONS. in INITFILT.DOC.
- !norecord?selector
- Instructs SRE-http to NOT record this request. It has the same
effect as a NO_POSTFILTER permission.
You can disable this option by setting the NO_NO_RECORD parameter.
- !sendas_mimetype_mimesubtype/dir/filename.ext
- The
!sendas
special action is used to force
the server to send the requested file as mimetype/mimesubtype.
This can be useful if you wish to create links to unusually named
text, or html, files. For example, if you have a series of
html documents named CHAP.1, CHAP.2, etc.; you could use links of
the form:
<a href="/!sendas_text_html/mybook/chap.3">Get chapter 3 </a>
Technical note: !sendas
suppresses SRE-http's
extension mapping method of determining the mime type (and subtype);
and uses the explicitly coded mimetype
and mimesubtype
instead.
For information on customizing SRE-http's extension mapping,
see the description of MEDIATYP.RXX.
Special feature If !SENDAS_CHECK_TYPE
is used,
then if no explicit match can be found, the file will be checked for
"all text characters", and if such is the case, will be returned as
text/plain. !SENDAS_CHECK_TEXT
is simliar, except it checks
the file before using the explicit extension (the explicit extension
is used if only the file contains non-text characters).
- !delsend/filename.ext
- !delsend is used to send a file from the SRE-http TEMPFILE_DIR
"temporary file" directory. More precisely, !delsend will look for
filename.ext
in the TEMPFILE_DIR, send it (if it exists), and then delete it.
!delsend is provided to facilitate writing server side programs that
generate several output files -- the client would be sent back
a response containing !delsend links to these several files.
Notes
-
When a
!force
, !norecord
,
!sendas
or !delsend
request is recieved,
the !cmd portion (i.e.; the !sendas_xxx_yyy/,
or the !delsend/)
are immediately stripped off.
Thus, SRE-http's various "SEL-specific" operations (such as access control,
or aliasing) are performed on this "stripped" request selector .
- You can end the !cmd portion with either a ? or
a /. For example, the following two request selectors are equivalent:
-
!sendas_text_plain/hello.lst
-
!sendas_text_plain?hello.lst
Hint: NetScape's redirection can do odd things if you use
a ?.
6.a.ii) Currently available special commands
- !authorize
- SRE-http will send back an "authorization" request. The primary users
of this will be server administrators -- since a !AUTHORIZE link will
repetitively ask for the client's username/password.
- !ping
- 'PINGS' the client.
- !statistics
- View current GoServe statistics.
- !HOST?xxx.yyy.zzz.aaa
- Get information on IP address xxx.yyy.zzz.aaa
- !reset
- Resets various GoServe statistics, and instructs SRE-http to re-read
parameter files immediately (only available to OWNERS, or clients with SUPERUSER
privileges).
- If !reset?params, then statistics will
not be reset.
- !save
- Saves various GoServe statistics to the GOAUDIT.80 audit file.
This is only available to SUPERUSERs, or to users with a CONTROL privilege.
- !ssi
- Used to access information on the SSI-cache. The following
sub-options are recognized:
- !ssi?status : writes a (fairly technical) status report to the PMPRINTF window.
- !ssi?status=short : writes a brief status report to the PMPRINTF window
- !ssi?status=fully_qualified_file_name : writes a report on the SSI-Cache entry
(if it exists) for the
fully_qualified_file_name
- !ssi?reset = Resest (clear) the SSI-cache
- !ssi?remove=fully_qualified_file_name : remove the SSI-Cache entry
(if it exists) for the
fully_qualified_file_name
- !ssi?cleanup = Cleans up the SSI-Cache
Notes:
- The client must have SUPERUSER privileges to invoke these
!SSI options.
- After completion of the !SSI request, a
short status report (in plain-text format) will be returned to the client.
- For an illustration of the use of !SSI, see SSICACHE.HTM
- !variable?var1&var2..
- Returns the value of environment variable var1, etc.
(client must have SUPERUSER privileges to use this).
- !write_cache
- saves the
record_all_file
cache to the record_all_file
- !dir?
dirname
- Invokes SRE-http's built in directory lister; which will create
a list of all files (and subdirectories) of
dirname
.
To modify the various display parameters used by !dir, see the
DIR.DOC
file, or see the description of the DIR_EXCLUSION, DIR_ACCESS, and DIR_OPTIONS
parameters in INITFILT.DOC.
Notes:
- The !CREATE option of the AUTO_NAME parameter
also uses
!dir
to generate a directory listing.
- For a more richly featured directory lister, try the
Get-a-File SRE-http addon.
Return to table of contents
In keeping with http server standards, SRE-http will maintain a
common-log format audit file. Entries in common-log format
audit files have the following structure:
aclient.somehere.org - username [18/Mar/1996:16:24:08 -0500] "GET /SAMPLES/HELLO.HTM HTTP/1.0" 200 1251
Besides offering a compact synopsis, a number of tools exist to help you
analyze common-log files.
Furthermore, as an adjunct to the common-log audit file SRE-http can also
record
the browser used by each request (as well as the referer)
in seperate log files.
Notes
- The WRITE_LOGS parameter is used to enable SRE-http's common-log,
browser, and referer audit files (see INITFILT.DOC for details).
- If post-filter processing has been suppressed (with the NO_POSTFILTER
permission), the request will not be recorded to these audit files.
- The SREFLOGS.INI
file contains log-file control parameters.
For example, you can select seperate log-files for each of several hosts, you
can suppress any of these log-files, and you can suppress auditing of
400 (failure) or 300 (moved) requests.
- The SCHEDULE.CFG file (in the CFGS directory) can be used to
run scheduled programs on an hourly, daily, weekly, or monthly basis.
RENLOGS.CMD (an alternative to the LOGFILE_MAXSIZE parameter) is an
example of such a scheduled-events program.
Return to table of contents
You can use the simple-mode configurator
to enable the common-log audit file and the RECORD_ALL_FILE
running count.
As an alternative to the common-log audit file, SRE-http maintains
a running count of requests in the
RECORD_ALL_FILE . This file contains
a count of requests, broken down by selector or by filename.
Record refers to updating a count of the number
of times a resource has been requested.
It does not mean keeping a record of each hit! If you need
such detailed accounting, you should use the
common-log file (or you can use GoServe's GOAUDIT.80 file).
For customized auditing needs, you can add your own
procedure using the post-filter option
(POSTRCRD.80 is an example of such a procedure).
To enable the RECORD_ALL_FILE, you need to
set the RECORD_OPTION parameter.
RECORD_OPTION can take the following values:
- NO
- Do not maintain a running count
- YES
- Record requests, but remove the the argument list from the selector
(for example; remove
?hi+there
in
ANIMALS/MONKEY.HTM?hi+there
selector
- YES_ALL
- Record requests, do not remove an argument list.
Caution: Use of YES_ALL can lead to a very large
RECORD_ALL_FILE
- FILE
- Record requests by fully qualified file name. In contrast, when YES or YES_ALL
are specified, requests are recorded by selector
Caution: Use of FILE can lead to a very large
RECORD_ALL_FILE -- careful use of wildcard entries is recommended.
RECORD_ALL_FILE: Implementation details
To speed throughput, SRE-http caches the RECORD_ALL_FILE in memory,
with a single thread responsible for updating it (the POSTFCHK thread).
This raises several issues:
- The cache is written to disk on a regular basis (about
once every five minutes). Thus, it is possible for the file
version to be somewhat out of date; and it is possible to loose
entries (say, if the server crashes).
- If you "hand edit" the RECORD_ALL_FILE (say, to add
wildcard entries), SRE-http will
read it into the cache, overwriting any changes that have been recently
made. That is, any requests recieved while you were editing the
file will not be recorded.
- If the cache grows large (over 1000 entries), SRE-http will
start over -- and save the old RECORD_ALL_FILE (you won't loose
information, but it will be spread over a few files).
There is one exception: SRE-http will retain "wild card" entries
(but will reset their count to 0).
Given the above: the RECORD_ALL_FILE should be treated as
an approximate (albeit probably very accurate) count of requests.
To avoid loosing a few minutes of entries that will occur
when you shut down GoServe, you can issue a !WRITE_CACHE request
just beforehand
Notes
- Wildcard matching of entries is supported,
both by "selector " and by "FILE".
- By default, results are written to RECRDALL.CNT -- this can
be modified by changing the RECORD_ALL_FILE
variable.
- Entries in the RECORD_ALL_FILE may be "host specific". However,
when FILE is specified, host information is not used.
- For YES and YES_ALL, each entry in the RECORD_ALL_FILE contains
the request selector (minus the
argument list if RECORD_OPTION=YES), the number of
"honored" requests, and the date of the most recent request.
- For FILE, each entry contains the fully qualified file name, the number of times
the file was requested, and the date of the most recent request. Note
that when FILE is used, information after the ? is ignored (there is
no FILE_ALL option!).
- Only "honored" requests are recorded
-- requests for actions that are not honored (when
ALLOW_ACCESS is enabled) are not recorded.
- If an entry matching the request selector is not found
in RECORD_ALL_FILE, a new entry will be created!
- ... however, a wildcard match is always attempted.
The use of "wildcard matching" is recommended if many
temporary files are likely to be requested. For example,
one should include a "wildcard" for
the "temporary" directory in your RECORD_ALL_FILE
- The size of the RECORD_ALL_FILE cache can be increased or
decreased by changing the RECORD_CACHE_LINES variable.
Or, you can suppress this caching by setting RECORD_CACHE_LINES=0.
See INITFILT.DOC for details.
-
The differences between the RECORD_ALL_FILE method, and placing a
REPLACE HITS (or REPLACE HITS_FILE) keyphrase in all documents, are:
- Nothing is written to the requested file
(the client is not given info on # of hits)
- The RECORD_ALL_FILE is updated,
not the COUNTER_FILE.
- All requests are tracked: including transfer of HTML documents and.GIF files,
and Server Side Processing requests.
Thus, if a REPLACE HITS
keyphrase is included in a document,
and RECORD_OPTION is enabled ,
a "count of requests" will be updated in the
COUNTER_FILE and in
the RECORD_ALL_FILE
- For viewing the RECORD_ALL_FILE, we recommend the
NUSTATUS SRE-http addon.
Return to table of contents
To reduce the number of false hits from clients re-requesting
a URL after a short absence (often caused by the
use of a browser's "back" key), a list of current hits
can be maintained. If a request selector matches a request in this list of
current hits
(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.
In addition to "re-requests", you may also wish to not record
requests from OWNERS (such as the webmaster) -- since these are likely
to be due to site maintenance activity, and not due to interest in the content
of the requested files.
INITFILT.DOC contains details on both of these options: see the
descriptions of the
HIT_CACHE_LEN, HIT_CACHE_DURATION,
and HIT_OWNER_SUPPRESS variables (or you can
use the simple-mode configurator).
Notes
- You can control the size and duration of the
list of current hits by modifying the HIT_CACHE_LEN
and HIT_CACHE_DURATION variables
- You can not record requests from OWNERS by
enabling the HIT_OWNER_SUPPRESS variable.
- Similar request suppression options exists
for the COUNTER.RXX hit-recorder.
Return to table of contents
SRE-http is shipped with support for a simple form of "load balancing". When load balancing
is active, the server will first check the number of active clients.
If this exceeds the number specified in the LOADTHRESHOLD variable, then the
client is redirected to one of the servers listed in the BackupServerList
variable.
For details on how to invoke load balancing, see the description of LOADTHRESHOLD
in INITFILT.DOC
Suggestion:
If you are interested in "dynamic" load balancing (that uses
real-time server-load information); you might be interested in
the Balancer
dynamic load-balancer.
Return to table of contents
In certain cases, you may wish to have a set of
custom written REXX routines
examine the request before yielding control to SRE-http. For example,
you may wish to shunt some special requests to a variety of different
filters.
To do this, set the PRE_FILTER variable:
- PRE_FILTER=NO: no pre-filtering will be attempted.
- PRE_FILTER=YES: a pre-filter (a REXX procedure) will
be called. The pre-filter will be called after
logon privileges have been determined; when individuals do not
have logon privileges, the pre-filter will not be called.
- PRE_FILTER=FIRST: same as PRE_FILTER=YES, except the pre-filter is
called as the very first action (before logon privileges are ascertained).
You can specify the name(s) of the pre-filter procedure file(s)
by setting the
PREFILTER_NAME variable. By default, PREFILTER_NAME="PREFILTR"
(which refers to PREFILTR.80).
When a pre-filter is called, several arguments will be passed. The first
three are generated by GoServe, the second to last is generated by SRE-http and
is not passed when PRE_FILTER=FIRST, and the last offers a means
of transfering results from earlier to later pre-filters.
parse arg source,request,sel,privs,servername,otherargs
source:
myaddr port transaction who whoport
request:
verb selector protocol
sel:
action '?' awords
privset
: list of privileges (including the secret privileges,
which will be seperated from the regular privileges by a comma).
servername
-- ip name of server (useful in multi-host
environments).
Other_args
-- results from prior pre-filter.
The pre-filter should return a comma delimited list:
status , status message
Where status is either 0 or 1:
0= No response to client, SRE-http should continue processing.
1=Response to client, SRE-http should exit (perhaps with response recording)
The Status message will be stored as
PREFILTER_RESULT. Note that the
REPLACE PREFILTER_RESULT
keyphrase
can be used to display this status message.
Notes
- If more then 1 pre-filter is called, the PREFILTER_RESULTS
will be from the last pre-filter specifed in PREFILTER_NAME
- If an earlier pre-filter issues responds to the client (and
issues a GoServe "completion code"), the remaining pre-filters
are skipped.
Return to table of contents
The PREFILTR.80 file that comes with SRE-http contains a
pre-filter that enables support for the GoRemote package.
GoRemote (the "server remote control" package bundled with GoServe)
is typically called as a special filter. By using this pre-filter, GoRemote
will automatically be called (instead of SRE-http) when a GoRemote
specific action is requested.
To do this, you'll need to:
- Make sure you have the GOREMOTE package (GOREMOTE.ZIP), and unarchive it to either the root of
your data directory, or to the GOREMOTE/ subdirectory of your data
directory. You'll need GOS32.GIF, GORM*.HTM and GOREMOTE.* files.
Since there are about a dozen GORM* files, placing them in
a subdirectory is asthetically preferable.
- Copy GOREMOTE.80 to your GoServe working directory. If GOREMOTE was
installed in a GOREMOTE/ directory, copy GOREMOTE.HTM, GOS32.GIF and GORMOK.HTM to the
root of your data directory
- Make sure that PREFILTR.80 (the one that comes with SRE-http) is
also in your GoServe working directory.
- Using CONFIG2.HTM (or by direct modification of the INITFILT.80 file),
set the PRE_FILTER variable to:
- YES = If you want to limit access to GoRemote:
- Clients with SUPERUSER or INHOUSE privileges will be able to
view filter settings and statistics.
- Clients with SUPERUSER privileges will be able to change settings.
- FIRST = If you want all clients to have access to GoRemote
You should also set PREFILTER_NAME='PREFILTR.80'
- Set up a link to GOREMOTE (or GOREMOTE/GOREMOTE if
you installed GOREMOTE in a GOREMOTE subdirectory).
- You do not need to make any other modifications, either
to SRE-http, or to the GoRemote files!
Notes:
- This pre-filter works by capturing all calls to GOREMOTE.*, GOS*.*, and
GOR*.* (or to these files in the GOREMOTE/ directory).
So, if you use this pre-filter, don't create files with these names (though
you can create files with these names in different subdirectories).
- When requesting GOREMOTE, do not use
GOREMOTE.HTM (the GoRemote filter is not expecting to see an extension).
Return to table of contents
In certain cases, you may wish to execute some additional actions
after responding to a client's request. For example, you may
wish to record client specific information in a custom designed audit
file. Or, you may wish to e-mail responsible parties
when certain events occur (such as a file upload). Or you may wish
to do both!
To accomodate such needs, SRE-http can be told to call a
series of "post-filters". As with
the "pre-filter", these post-filters are custom designed REXX procedures.
To enable post-filter calling, set the POST_FILTER variable:
- POST_FILTER=NO: post-filter(s) are not be called.
- POST_FILTER=YES: post-filter(s) are called.
Note: The post-filter(s) are called after a response
has been sent to the client.
Therefore, you can not
use a post-filter to modify the response
sent to the client!
You can specify the names of the (possibly several)
post-filter procedure files by setting the
POSTFILTER_NAME variable. By default, POSTFILTER_NAME="POSTFILT".
To specify several post-filters, just enter a space delimted list.
For example POSTFILTER_NAME="POSTMAIL.80 POSTRECRD.80 "
--
they will be executed in the order of appearance.
Note that if there is no extension, and no ending period, an extension of
.80 is assumed (or .nnn if you are using a non-80 serverport).
When a post-filter is called, several arguments will be passed:
- amessage : a short SRE-http status message
- source : The server address and client address
- request: The request string; the verb, the selector , and the http protocol
- sel: The selector
- tempfile: The temporary file used by this transaction
- servername: The host to whom the request was directed (the
servername)
- host_nickname: The "host nickname" corresponding to
the servername (or blank, if there is no HOSTS. variable for servername)
- USED_FILE: The fully qualified file used by the request:
such as the HTML file requested by the client,
or the CGI script executed by the server.
- TheReferer:
The value of the 'referer' request header -- if set, it contains
the fully qualified URL which contained the link which invoked this request.
- Request_specfic_cache: A pointer to a set of request specific information.
This can be used by the SREF_READ_STATE macrospace procedure (note that
post-filter actions can not issue GoServe commands).
- RESPONSE_STATUS: The response code and the number
of bytes returned. For example: 200 19218.
- The list of privileges
- The list of secret privileges
For a simple example of a post-filter, see the POSTFILT.80 file that comes
with SRE-http. For more useful examples, see POSTMAIL.80 (an
e-mail alert routine) and POSTRCRD.80 (a client info recorder).
The POSTMAIL.80 that comes with SRE-http uses a version of the SREF_MAILIT procedure (contained in
the SREFPRC macrospace procedure library) to
e-mail "event specific" alerts through an SMTP Gateway.
A different (set) of individuals can be notified
for each of a set of events, where events are identified by the
request selector (with wildcard matching supported),
or by the requesting client's IP address.
POSTMAIL.80 contains detailed instructions on how
to generate these e-mail alerts. POSTMAIL.80 also contains a useful
discussion on the use of OS/2's SENDMAIL as an SMTP gateway).
Notes:
- To use this facility, you must set the SMTP_GATEWAY variable to be the address
of your SMTP server. If you do not have access to an SMTP server, you might be able to use OS/2's SENDMAIL
program to set up your server machine as a SMTP server
(see the OS/2 TCP/IP Command Reference for more information on SENDMAIL).
- Ambitious programmers can use SREF_MAILIT for more advanced e-mail purposes.
Return to table of contents
SRE-http provides two built-in "actions" for uploading files,
one HTTP method
for uploading files, and one HTTP method for deleting files.
Each of these has its own advantages
and disadvantages:
- GET_URL: A built-in action for uploading files from another HTTP server
- Requires that the client has ready access to an HTTP server.
- Given this access, uploading is quick and easy.
- PUT_FILE: A built-in action for uploading files from the client's own machine
- Requires that the client be using a browser that supports the
type=file
FORM attribute (such as NetScape 2.01 and above).
- The PUT method.
- Requires that the browser (or other software) know how
to issue a PUT method HTTP request. The DOPUT.CMD program illustrates
the use of the PUT method.
- The DELETE method. This can be used to delete files from
your server. As with the PUT method, it requires a browser that
knows how to issue DELETE method HTTP requests.
General Usage notes:
- GET_URL.
Set up a URL with the GET_URL action,
followed by the
URL of the file you want to get, and the "local name". The request selector
should look like: GET_URL?url=http://a_url&file=relative_file_name
For example:
-
GET_URL?url=http://www.pc.com/price.lst&file=pcprice.1
will copy price.lst
(on the server at www.pc.com
) to a file named PCPRICE.1 (in
the upload directory
).
- PUT_FILE.
Create an HTML FORM with a type=file
attribute. For example:
<FORM enctype="multipart/form-data" ACTION="/put_file" METHOD="post">
Send this file <INPUT TYPE="file" name="relative_filename">
<INPUT TYPE="submit" VALUE="send file">
</FORM>
- The PUT and DELETE HTTP methods are, by default, not permitted.
To allow PUT or DELETE methods, you must include a PUT or a
DELETE permission in the permission list of the
appropriate entry (for the requested selector ) in the ACCESS_FILE.
- As with the more commonly used GET and POST methods,
selectors in PUT and DELETE method requests
are relative to the data directory (or to a local virtual directory).
- You can allow PUT to overwrite preexisting files by setting
PUT_NO_OVERWRITE=0 (in INIT_STA.80). If PUT_NO_OVERWRITE=1, then if
the selector maps to a pre-existing file, an error message will be
sent back to the client.
- PUT and DELETE will not be permitted if ACCEPT_RANGES='NO'
(ACCEPT_RANGES is set in INITFILT.80).
PUT_FILE and GET_URL usage Notes
- PUT_FILE and GET_URL store
results in files relative to the UPLOAD_DIR directory, or to a "local"
virtual directory. Note that if the target is a virtual directory,
a PUT permission must exist for the specified file.
For example, if the relative file name is TODAY/OUTPUT.1, and
TODAY has a virtual directory match, then access controls for TODAY/OUTPUT.1
will be examined for a PUT permission. In contrast, if TODAY has no virtual
directory match, then output is assumed to be to the TODAY subdirectory of
the UPLOAD_DIRECTORY -- and the PUT permission is not needed.
- Files must be less then UPLOAD_MAXSIZE in kbytes size;
and there must be UPLOAD_MINFREE kbytes free (in the UPLOAD_DIR
directory)
after the file is uploaded. If either condition can not be met, the file will
not be uploaded.
- If the filename (after resolving for is directory) exists,
an error message will be returned.
- If you do not specify a local file name, SRE-http will create a
"unique" file name in your UPLOAD_DIR directory.
You can specify "partially random" filenames by including ? characters in the filename.
SRE-http will attempt to create
a unique file name by appropriate substitutions of the ? character. For example:
- if filename=ABC??.TXT,
- and ABC01.TXT exists,
- then SRE-http will use ABC02.TXT.
- For GET_URL: You must completely specify the URL (including the http:// portion).
- A short status report on success of the upload operation is written to the
UPLOAD_LOG file.
- For PUT_FILE: Browsers that do not support the
type=file
FORM attribute will send back garbage (that will be ignored).
- UPLOAD.HTM contains an example of the use of GET_URL and PUT_FILE.
- For PUT method uploads, size limits are not imposed.
Return to table of contents
6.h) Automatic generation of response headers
If desired, SRE-http will parse a requested document, extract all LINK and
META HTTP-EQUIV elements found in the <HEAD>, and create the
appropriate response headers. This is especially useful
in response to HEAD requests.
To do this, set the value of the AUTO_HEADER variable:
- NO : Do not create response headers
- HEAD: Create response headers when a HEAD HTTP method request is recieved for
an HTML document.
- ALWAYS: Create response headers whenever a GET or HEAD request is recieved
for an HTML document.
Notes
- GoServe automatically generates several response headers (such
as content-length and file-creation-date).
- Server side includes (that might be in the <HEAD>) are not processed when a HEAD
request is recieved. Furthermore, server side includes are not processed
when response headers are created, but are processed when
the <HEAD> is returned as part of the document.
Thus, if you intend to use AUTO_HEADER,
we recommend not using server side
includes in the <HEAD> portion of your HTML documents!
- From an HTTP purist basis, the use of AUTO_HEADER="HEAD" would be
discouraged, since the response headers returned by a GET and a HEAD request
would be different. However, since many browsers understand that
LINK and META EQUIV elements (in the <HEAD> section of an
HTML document) are equivalent to response headers, this may not be a
serious drawback.
Return to table of contents
SRE-http recognizes a list of the most frequent MIME media types (using the
extension of the requested file). If you want to add to this list, you
can do so by editing the MEDIATYP.RXX
file located in your
GoServe directory.
Additions to MEDIATYP.RXX may be new media types
(say, an experimental MIME type),
or they may be assignations of a non-standard extension to a common MIME type
(say, .DOCUMENT to text/plain).
Notes
- MEDIATYP.RXX
is checked only when the requested
file has an extension that does not match one of SRE-http's pre-defined
mime types. Therefore, it can not be used to redefine
a built in mime type.
- Instructions on how to modify MEDIATYP.RXX are contained in
the copy of MEDIATYP.RXX that ships with SRE-http.
- If you add new text/html entries, and you want these to be equivalent to
SHTML entries (that is, html entries with server side includes permitted), you
should edit the SSI_EXTENSIONS variable in INIT_STA.80 (see INITFILT.DOC for
details).
Return to table of contents
The SRE-http event monitor
is used to track, and respond to,
the status of the system. Using temporary files and event semaphores,
external processes can use the event monitor to communicate and control
GoServe and SRE-http.
For example:
- An external process could set an event semaphore when a shutdown is
needed. The event monitor can detect this event semaphore, and
close GoServe.
- An administrator can create a temporary file which will signal
GoServe to suspend (to refuse further connections), and then create
a second file to tell GoServe to resume.
- SRE-http can run an external procedure on a scheduled basis, and then
run a second procedure if this procedure sets a simple flag.
For more details, see EVENTS.DOC.
Return to table of contents
7) Some useful facilities provided with SRE-http
SRE-http comes packaged with several useful tools:
a speciallized file-transfer utility, a message box utility, and
client customization tools.
7.a)The DOSEARCH facility
In the interests of space, DoSEARCH is no longer packaged with SRE-http.
However, DOSEARCH is available as an addon from the
SRE-http home page
Return to table of contents
7.b)The SENDFILE facility
SENDFILE is an SRE-http facility that transfers files to a client.
It can record the number of times this file has been completely sent.
In addition, it can be used to sequentially send a set of files.
SENDFILE is invoked with a request selector of:
SENDFILE?file=selector&forcetext=1&COUNTER=option_list&header=response_header
(the &forcetext=1 and &COUNTER=option_list are optional)
SENDFILE will ...
- Check for the existence of a file corresponding to the
selector
(the file that the selector maps to is assumed to be
relative to the data directory or relative to a "local" virtual directory).
- Look in the SENDFILE_FILE
for an occurence of the
selector
. If none exists, create an entry.
- If the
selector
exists (and the entire file was sent), the
"count of requests" for this selector
is augmented. That is, if the client
killed the connection half way through, the count will not
be augmented.
- If a COUNTER=... options is present, COUNTER.RXX will be used (with
the option_list).
- The values of HEADER= options are used as additional response headers.
Examples:
- SENDFILE?file=foo.bar&HEADER=refresh:+2+;+url=/sample/thanku.htm
would cause a Refresh: 2 ; url=/sample/thanku.htm
response header to be sent (2 seconds after SENDFILE transmits the file,
the browser will then request /sample/thanku.htm )
- &HEADER=content-disposition:+attachment;+filename="spiffy.2"&file=foo.bar
would cause a Content-disposition: attachment; filename="spiffy.2"
to be sent (the "save file as" box will offer spiffy.2 as the
default filename)
Note that the value of a HEADER= option must be URL encoded (i.e.; + characters used for spaces).
- If more then one FILE=selector option appears, then SENDFILE will attempt to send each of
the files (that the selectors map to) to the client without requiring further mouse clicks.
In other words, you can simulate a FTP MGET command!
This does require a browser that can handle multipart-mixed documents -- for example, Netscape 2.0 and above.
Example: /SENDFILE?file=/dir1/hello.htm&file=/download/spiffy.zip&file=/dir1/thanks.htm.
First, /dir1/hello.htm is sent to the client; which is immediately followed by
/download/spiffy.zip
(the client will almost certainly be asked to provide a name to save spiffy.zip as). After spiffy.zip has
been transmitted, /dir1/thanks.htm will be sent.
- As a shortcut, you do not need to specify the FILE= -- an option
with no = is assumed to be a FILE= option. For example,
SENDFILE?samples/intro.doc is equivalent to SENDFILE?file=samples/intro.doc
Notes
- If the client breaks the connection before the a file
is completely sent, the SENDFILE_FILE is not modified (the request
is not recorded).
- By default, SENDFILE_FILE
is SENDFILE.CNT.
- When ACCESS_ALLOW is enabled, the
ACCESS_FILE should contain an entry of the form
SENDFILE?*
- The SENDFILE_FILE supports wildcard matching.
- For details on the COUNTER= option_list, see COUNTER.DOC .
-
If
FORCETEXT=YES
, SENDFILE will
assume that all files are of "mime-type text/plain". This
can be a useful trick (it tricks the client into displaying everything
as a text file), but if .GIF (or other non-text files) are chosen,
garbage will be displayed ( use this option with discretion)!
- Entries in the SENDFILE_FILE may be "host specific".
- SRE-http will check that the browser understands multipart-mixed documents
(it looks for a connection: request header, or if the browser claims to be http/1.1 compliant).
If the browser can not handle such documents, only the first FILE=selector statement is processed.
- SENDFILE will only record (in SENDFILE.CNT) the first file sent (that is, only the
file referenced by the first FILE=selector option).
Return to table of contents
7.c) Using Message Boxes
SRE Filter's built-in message box facility provides a mechanism for storing messages
from clients. SRE-http provides a few simple built-in tools for manipulating
these messages boxes. These include:
- A message writer. The message writer is invoked with
a request selector of:
MESSAGE?messbox=messagebox&field1=value&..&fieldn=value
- Two simple facilities (VIEWMESS and ASKMESSBOX) are provided for
viewing an entire message box.
- Message box access can be controlled through the use of
message box privileges.
Of perhaps greater interest, the FORUM, READMAIL,
and MAILLIST
SRE-http addons make extensive use of these
SRE-http messages boxes.
7.c.i) The Message Writer
The message writer is usually invoked with an HTML FORM with ACTION="/MESSAGE" (see
SAMPMBOX.HTM for an example). In addition to an INPUT element identifying
the "message box", you can specify a number of fields (the field name, and its
value, are written to the message box using an e-mail type format). Several
of these fields are treated specially, as explained below:
- MESSBOX (recommended)
- The particular message-box to put the note into.
If a MESSBOX field is not included, the note will be put into the ANYONE message-box.
If MESSBOX names a non-existent message-box,
a new message-box will be create.
- NAME and SUBJECT (recommended)
- These are expected, if not included a dummy value will be created.
Note that each message is automatically given a TIME and DATE stamp.
- FAX, E-MAIL, ADDRESS, and PHONE (optional).
- The name, and value of these fields are written to the message box.
Note that the E-MAIL field is explicitly used by SRE-http's FORUM addon.
- PASSWORD and DURATION
- The PASSWORD and DURATION fields are used by the FORUM addon to control "delete privileges"
for a given message. PASSWORD will be encrypted before being written to the
message box file. Note that messages boxes are not designed for security (the encryption is weak),
so don't use them when confidentiality and integrity are important.
- INDEX
- Including an
INDEX=YES
field will cause MESSAGE to
update an index file (with an .IDX extension). These .IDX files are
used by the FORUM addon to speed up response. Note that this
.IDX file creation will occur after responding to the client (it is
a post-filter type of action) -- the client will not notice any
adverse impact from inclusion of an INDEX=YES
field
(but other clients may be impacted by the extra workload!)
- BROADCAST_LIST
- If included, SRE-http will simultaneously e-mail (through the SMTP gateway
you set with the SMTP_GATEWAY variable) copies of your message to
a list of e-mail addresses. This list, a file with name given by BROADCAST_LIST,
must be in (or under)the MESSBOX_DIR. Furthermore, the client must
have SUPERUSER or BROADCAST privileges, or a privilege equal to the
value of BROADCAST_LIST. If not, SRE-http will send authorization request
back to the client.
- Example: if BROADCAST_LIST=CLASS10.LST, then the client
must have a CLASS10.LST client privilege.
Note that the BROADCAST_LIST file (i.e.; CLASS10.LST) should contain
valid e-mail addresses, one per line.
- BROADCAST_ONLY=YES
- Do not write to message box, just BROADCAST
- BROADCAST_NAME=My_name
- Used in the "from" field of the e-mail message.
- WRITE_TO_FILE=YES
- If included, SRE-http will write an "E-mail" like file (containing
From, To, Date, and Subject fields; followed by the Contents) to your
MAILBOX_DIR directory. These files are designed to be read, and
processed as an "e-mail message to a list-server", by the MAILLIST (and READMAIL)
SRE-http addons.
If you are broadcasting to many recipients, the use of WRITE_TO_FILE
in conjunction with the MAILLIST addon, rather then the BROADCAST_LIST, is recommended.
- Other names (optional).
- The name, and value, of these fields will be written to the message box.
The difference between "other names" and the PHONE, ADDRESS, and FAX "optional"
fields is merely in the order of appearance.
- RESPONSE_FILE
- The RESPONSE_FILE field is used to indicate a file contaning a "response"
to a posted message. If no RESPONSE_FILE is included, a very simple generic
response will be
returned.
- MESSAGE (recommended)..
- The (multi-line) message. It's written last of all.
The direct means of reading a message box is to simply view it using the OS/2 TYPE
command (message boxes are ASCII files, with a .LOG extension, located
in the MESSBOX_DIR directory).
SRE-http also provides a simple mechanism for remotely viewing these
message boxes.
A request selector of VIEWMESS?messbox=message_box
will
cause SRE-http to transfer the message-box-file to the client.
SRE-http also provides a simple routine that generates an HTML document
that displays a list of all available message-boxes,
and let's the client choose which one to view.
This routine can be invoked with a request selector of
askmessbox?An+optional+header
The "optional header" is displayed as an <H2> at the top of the document.
To access a message box with MESSAGE (or with the FORUM
addon),
the client must have
"message box specific" privileges. These are specifed by including
(in the client's privilege list), entries of the form:
MESSBOX=a_message_box.
For example: MESSBOX=FORUM1
would give (read/write) access
to the FORUM1
message box. Note that this is in addition
to any "selector and FILE specific" access controls you may have imposed.
The a_message_box
portion of the privilege can
contain the * "wildcard" character. For example, MESSBOX=FORUM*
would provide access to FORUM1, FORUM2, etc.
On installation, SRE-http includes MESSBOX=*
in the
PUBLIC_PRIVS parameter (the effect of which is to allow
open access all message boxes). You'll need to remove this from
PUBLIC_PRIVS if you want to limit access to message boxes!
Notes
- You can also limit access to message boxes by creating an entry in the
ACCESS_FILE of the form:
MESSAGE* resource_privilege_list
(you may also want to create similar entries for
VIEWMESS and ASKMESSBOX)
Return to table of contents
7.d) The SRE-http procedure library
SRE-http uses a procedure library (that is loaded into
macrospace) to provide many functions.
Several of these routines may be quite useful to the ambitious REXX programmer.
These procedures include:
- SREF_MEDIATYPE: Return the MIME type of a file (based on its extension)
- SREF_REPLACESTRG : Replace substrings
- SREF_MULTI_SEND: Expedites the creation of multi-part documents
- SREF_GRAB_FILE : Wait for file to become unlocked, and then
read it into a variable.
- SREF_FIX_URL : Given a local selector , and servername, and a serverport, return
a legitimate URL (including the http://).
- SREF_WILDCARD : Perform a wildcard substitution.
- SREF_JULDATE: Return the Julian date and time (days since 0/0/0, time in fraction)
- SREF_MAILIT : Send an E-mail message.
- SREF_CGIVARS : Determines one of the "CGI-BIN" variables.
- SREF_BROWSER_INFO: Check on the capabilities of the client's browser.
See SREFPRC.DOC.
for a complete description of these procedures.
Return to table of contents
7.e) Client-specific and browser-specific customization
SRE-http provides two addons that facilitate the creation of
customized documents. Both of them are invoked with an
<!-- INTERPRET FILE --> server side include:
BYCLIENT.RXX:
ByCLIENT.RXX is used to specify a set of files to be #INCLUDEd on
a client-specific basis. Identification of clients is based on
either a special cookie, the client privileges, or IP address.
ByBROWSR: ByBROWSR.RXX
is used to specify a set of
files to include on a browser-specific basis. Browsers are identified
by their user-agent; which are then matched (possibly using * wildcards)
to one of several file-mapping rules.
Suggestion:For a highly dynamic (cookie based) means of customizing documents,
check out the CUSTOMIZ
addon.
Return to table of contents
8) SRE-http addons
In addition to all the features/options/utilities packaged with
SRE-http, there are an ever-increasing number of SRE-http addons
available.
Note that the SRE-http addons use a somewhat non-standard
interface. However, given the flexibility and power of the
GoServe/SRE-http API , these addons are often considerably
faster then equivalent CGI-BIN scripts, and can often provide
services (such as server push) that would be almost impossible
with standard CGI-BIN
You can find & download the latest SRE-http addons from
the
SRE-http home page.
The following (non-exhaustive) list of currently available addons is
provided to tease your appetite:
-
FORUM: A news-group and list-server discussion-group package.
The FORUM addon consists of several components, including:
- FORUM:
The FORUM component provides a simple, but
fairly complete, multi-threaded "news group" like capability. The basic
output of FORUM is a list of "links" to messages in the message box.
The list is organized hierarchically, with indentation used to indicate
discussion threads.
Clinking on a link causes
just that message (and its various "fields") to be displayed. The client then
has a number of options: including sending a response to the message poster (given that an
e-mail address is available), posting a new message to the message box (either
as a response to the message, or a as new entry in the discussion thread), or
viewing the next message or the next thread.
- READMAIL:
The READMAIL component will transfer incoming e-mail
to SRE-http message boxes. This mail is read from the
incoming mail directory of an SMTP-gateway running
on your server; for example, the SMTP-gateway provided by OS/2's
SENDMAIL daemon. By combining READMAIL, and the BROADCAST_LIST
option of MESSAGE, a simple "list server with automatic archiving" can
be implemented.
-
BBS: A full featured "web based bulletin board system"
BBS is a WWW bulletin board system. BBS features include:
- Individual file descriptions can be displayed, along with
file size and creation date.
- Directory specific inclusion files (i.e.; FILES.BBS) and exclusion
files can be used to control file and sub-directory display.
- Optional "automatic descriptions" can be generated for
HTML, .ZIP, and text files.
- .ZIP files can be "opened and displayed", with subsequent retrieval
of a specific file from within the .ZIP archive
- Netscape 2.01, and other HTML 3.0 compliant browsers, can upload
files by using a FORM containing a file="type" element.
- Uploads and downloads can be recorded on a per user basis.
- A flexible access control mechanism allows customizaton of which
file areas a user can peruse.
- Downloads can be disallowed if a user's "download to upload" ratio grows
too large.
- Directory specific headers, footers, and "exclusion lists" can
be specified.
- Optional caching of directory-listings can greatly speed up throughput.
- GOSWISH: A front-end (+ more) to the
freeware SWISH
search engine. SWISH is used to index
the many directories comprising your web-site. It creates
a compact index that it can search quickly for matching words.
GOSWISH, the SRE-http front-end, enables you to search this from
an HTML form. In addition, GOSWISH will automatically create
a description. You can also use GOSWISH to create
a "description index", which you can then search for matches.
- GETAFILE: A directory displayer, with user-settable display features
GETAFILE is a similar to SRE-http's !DIR dynamic directory display facility.
It is somewhat easier to configure, and has a few extra bells and whistles.
- CALC: A character-mode scientific calculator with a web interface
CALC is a WWW-accessible scientific calculator.
It uses a keyboard interface, and
is based on an aging DOS program. On the other hand, it's quite feature
rich: multiple equations and temporary variables can be specified, trigonometric functions
are fully supported, analytic derivatives can be taken, and more...
Did we say non-exhaustive? Some of the other addons include:
Customiz: a client-customization utility
(using cookies)
GIF_TEXT: a text-to-gif converter (using numerous
fancy-multi-colored fonts)
WWWthumb: a create & deliver grahpical thumbnails utility
and much more!
Return to table of contents
Appendix 1) User-configurable SRE-http files.
SRE-http is managed and customized through a set of ascii (text)
configuration files. In this appendix,
we list these configuration files, indicating what they do and where
to find more information about them.
But first, some preliminary notes...
- Unless otherwise noted, these
configuration files will be located in the CFGS\
subdirectory of your GoServe working directory.
Note that and "audit, count, and selector-specific files" are
usually in the DATA\
subdirectory of your GoServe working directory.
-
All
of SRE-http's configuration files are text-based -- you can
always edit them with your favorite text editor (such as EPM).
Many of the files can also be modified using the on-line
SRE-http confgiurator.
FileName | description | more info |
Host specific parameter files |
Files that specify additional host and port specific parameter
files.
|
CFGLIST.CFG |
CFGLIST.CFG is used to specify host-specific information,
including HOST definitions (assignations of IP addresses/aliases
to SRE-http HOST_NICKNAMES), and to define host (and port) specific
configuration files.
| USE_CFGS.DOC contains a detailed
description of the CFGLIST.CFG.
|
General SRE-http variables |
Files that specify basic SRE-http parameters, and files
used for other non-request-specific purposes.
|
INITFILT.80 |
INITFILT.80 contains a number of SRE-http parameters.
These are parameters that are global to all requests. They are
also parameters that are can be changed on the fly -- you do not
need to restart GoServe.
| INITFILT.DOC contains a detailed
description of the various parameters contained in INITFILT.80
You can modify INITFILT.80 parameters using the
intermediate configurator. Or,
you can run EDITINIT.CMD (from an OS/2 command prompt on the
server).
|
INIT_STA.80 |
INIT_STA.80 is similar to INITFILT.80 -- it contains global parameters.
However, these parameters tend to be a bit more obscure. More importantly,
they only are read when GoServe/SRE-http start -- so for changes to
take effect, you must restart GoServe.
| INITFILT.DOC contains a detailed
description of the various parameters contained in INIT_STA.80
To modify INIT_STA.80, you can run EDITINIT.CMD
(from an OS/2 command prompt on the server).
|
USERS.IN |
The SRE-http USERS.IN file is used to register users. Each entry in
USERS.IN contains a username, a password, and an optional list of
client privileges.
|
USERS.DOC contains a detailed description of
SRE-http's USERS.IN file.
The SRE-http manual describes
SRE-http's logon controls.
|
REPSTRGS.IN |
SRE-https REPSTRGS.IN file is used to specify "replacement strings"
for use with the <!-- REPLACE astring --> server side include. |
REPSTRGS.DOC contains a detailed description
of SRE-http's REPSTRGS.IN file.
|
SCHEDULE.CFG |
SRE-http has a simple scheduling daemon that will run programs
on a hourly, daily, weekly, or monthly basis. You specify
what you want to run via the SCHEDULE.CFG file, which is located in
the CFGS\ subdirectory (of your GoServe working directory).
|
SCHEDULE.DOC contains a detailed description
of SRE-http's SCHEDULE.CFG file.
|
Selector-specific attributes |
User-configurable, selector-specific attributes are attributes
that you (the web site administrator) may wish to set on a request-selector
basis. These include access requirements, controls on how SRE-http will
process a request, URL redirections, and other remappings.
|
ALIASES.IN |
The ALIASES.IN file is used to modify and transform the request selector.
This includes local and remote redirection, specifying searchable
indices, and specification of negotiable resources.
|
IN_FILES.DOC contains a detailed
description ALIASES.IN. You can modify ALIASES.IN with the
intermediate configurator.
|
ACCESS.IN |
The ACCESS.IN file is used to control access to your server's
resource on a selector specific basis. This access control
is based on a comparison of a client's "privileges" and the
privileges assigned to a selector.
|
IN_FILES.DOC contains a detailed
description ACCESS.IN. You can modify ACCESS.IN with the
intermediate configurator.
|
PUBURLS.IN |
PUBURLS.IN is used to specify "public URLS".
Public-urls are defined as
resources for which access (and logon) controls are not imposed.
|
PUBURLS.DOC contains a detailed
description PUBURLS.IN.
|
VIRTUAL.IN |
VIRTUAL.IN is used to specify virtual directories.
Virtual directories are used to allow access to files not in a default
directory. The typical use is to allow requests for documents to be
in a subdirectory not under the "GoServe data directory".
|
IN_FILES.DOC contains a detailed
description VIRTUAL.IN. You can modify VIRTUAL.IN with the
intermediate configurator.
|
ATTRIBS.CFG |
ATTRIBS.CFG is used to set selector-specific attributes using
a "realm-oriented" architecture. It supplements (or replaces)
ACCESS.IN, ALIASES.IN, PUBURLS.IN, and VIRTUAL.IN.
ATTRIBS.CFG can also be used to specify users (as a supplement
to USERS.IN), and to specify replacement strings (as a supplement
to REPSTRGS.IN)
|
IN_FILES.DOC contains a detailed
description ATTRIBS.CFG. You can modify ATTRIBS.CFG with the
intermediate configurator.
|
Advanced options files |
SRE-http's selector-specific advanced-option files
provide a set of less-frequently needed,
"advanced-options" to the ambitious webmaster.
These advanced-options include execution of "mid-filter" procedures,
customization of response headers,
specifying the Content-type, and enabling of content encryption.
| ADV_OPTS.DOC contains a detailed
description of SRE-http advanced options. You can
modify ACCESS.IN or ATTRIBS.CFG (using the
intermediate configurator) to specify these files
(by default, they should be placed in the DATA\ subdirectory of
your GoServe working directory).
|
Counter and Audit Files |
Unless otherwise specified,
the various counter and audit files are located in
the DATA\ subdirectory of the GoServe working directory.
|
COMMON.LOG and other LOG files |
SRE-http supports auditing using standard COMMON.LOG, BROWSER.LOG,
REFERER.LOG and COMBINED.LOG files.
| SREFLOGS.DOC contains a detailed
description of SRE-http's implementation of common log files.
|
RECRDALL.CNT |
The RECORD_ALL_FILE (with default name RECRDALL.CNT) is used to record all
actions, such as transfers of files and requests for server side processing.
It is used when RECORD_OPTION is enabled.
|
CNTFILES.DOC contains a detailed description
of the structure of RECRDALL.CNT. Note that the RECORD_CACHE_LINES
parameter is used to control "caching" of RECRDALL.CNT.
|
GOAUDIT.80 |
GOAUDIT.80 is GoServe's audit file. It is located in the
GoServe working directory. |
GOAUDIT.80 is described in the GoServe documentation (GOSERVE.DOC).
You can use GoServe's
Option-Audit tab to control what is written to GOAUDIT.80.
|
SENDFILE.CNT |
The SENDFILE_FILE counter file (with default name SENDFILE.CNT) is u
by the SENDFILE facility to record transferals. SENDFILE is especially
useful when transfering large files, since SENDFILE will only record
a "hit" if the entire file is successfully sent.
|
CNTFILES.DOC contains a detailed description
of the structure of SENDFILE.CNT.
The SRE-http manual describes how to use
the SENDFILE facility.
|
COUNTER.CNT |
The counter file is used to record the number of requests (also known as the
number of hits) for this document. It is used whenever a <!--REPLACE HITS --> or a
<!-- REPLACE COUNTS --> server-side include keyphrase is processed.
|
CNTFILES.DOC contains a detailed description
of the structure of COUNTER.CNT.
|
COUNTER.RXX |
COUNTER.RXX is a flexible "number of hits" generator and request-information
recorder. It can be used in server side include to provide
a textual counter (as an alternative to <!--REPLACE HITS -->).
Or, it can be used in an in-line image to provide an odometer style,
graphical counter. In contrast to <!--REPLACE HITS -->, COUNTER.RXX
stores hit counts in seperate selector (or file) specific files.
|
COUNTER.DOC contains a detailed description
of how to use COUNTER.RXX. provides a demo
of COUNTER.RXX (andof <!--REPLACE HITS -->).
XCOUNT.CMD and JCOUNT.CMD |
XCOUNT.CMD and JCOUNT.CMD are two cgi-bin scripts that provide hit counter
capabilities.
| See CNTDEMO1.SHT for a demo.
| |
Return to table of contents
The currently known limitations of the SRE-http package include:
- Technically speaking, SRE-http ver 1.3 is conditionally compliant
with the http/1.1 spec. Conditional compliance means that all of the features
that must be supported are implemented, but not all of the
should be supported options are available (though most of the
more important & interesting should options are implemented).
- SRE-http has not been tested with proxy servers (some users
report good success using SRE-http with INJOY)
- SRE-http does not support SSL. However, SRE-http ver 1.3h
does support:
- "digest" authentication, which (given that one's browser knows how to use
digest authentication) provides
much better password protection that the older "basic" authentication.
Since non-http/1.1 browsers will probably be with us for several years,
SRE-http also supports a quasi-digest authentication method, that requires
clients to generate dynamic passwords
(using a program on their own machine).
- A proprietary form of file encryption using a "shared secret". This requires that
you distribute SRE-http decryption software to clients.
In other words, SRE-http is designed as relatively full-featured package
for non-cutting edge small-to-medium
load sites being maintained by non-professionals
A2.b) Summary of SRE-http Features
The following summarizes most of SRE-http's features:
- Multiple hosts (either unique IP addresses, or multiple aliases
per IP address) are supported.
- Seperate data directories, aliases, etc. can be specified for
each supported host
- Logon requirements may be required of no one, everyone, or the general public.
- A set of public resources can be specifed, which will
be available to all clients.
- OWNERS (with SUPERUSER privileges) and IN-HOUSE users can
be automatically detected (using their numeric IP address), with logon
requirements waived.
- A set of "unallowed" numeric IP addresses can be specified.
- Wildcards can be used in the list of IN-HOUSE and "unallowed"
numeric IP addresses
- Custom logon procedures can be optionally used
- Several tools for resolving and redirecting requests are provided
- A "directory specific" document can be sent when a request selector
specifying a directory, but no file is name, is recieved
- Instead of a default document; a "directory listing" can be
produced, with file descriptions generated for all
plain, html, and .ZIP files. These
directory listings can be cached, and used for subsequent
requests.
- ALIASes can be used to redirect requests for moved documents,
to resolve commonly occuring "misspelled requests", and to transfer
specific files from anywhere on your server.
- Server-side and client-side content negotiation is supported.
- A customized "not found" document (complete with suggested link) can
be sent when the requested document is missing.
- ...or a selectable list of nearest matches to the requested
file can be returned.
- The ~ shorthand for the "home directory" is supported. In addition, ~
can point to www-specific subdirectories of the "home directory"
- Transfer of files from outside the "default data directory" is easily supported
through the use of "virtual directories".
- Transfer, with optional processing, of files from remote servers
(without using redirection) is supported through the
use of "remote" virtual directories.
- * wild card character(s) in selectors can be
used to request a "best matching" document.
- A variety of server-side includes are easily achieved
- Global replacment-rules, that are not dependent on
HTML-like statements, can be specified on either a
general or file-specific basis.
- A special caching algorithim selectively caches documents
that contain server side includes
- Headers and Footers can be included in all HTML documents
- Recursively processed keyphrases, that dictate
server side includes, can be placed in your HTML documents
- Dynamic and Static String REPLACEments
- Inclusion of files (from anywhere on your system)
- Inclusion of OPTIONs that appear in the request selector (information after a ?)
- Execution of REXX-code blocks, and insertion of the results
- SELECTive excludes of HTML code blocks
- The NSCA HTTPD server side include syntax is fully implemented
- The SET and IF..ELSEIF..ELSE XSSI Apache Extensions
to the NCSA HTTPD SSI syntax is implemented.
- Easy-to-use support for client-specific and browser-specific
customization of HTML documents
- Standard server features include:
- NCSA style IMAGEMAPS are supported, and easily requested.
- Searchable indices on text files are easy to setup
- A flexible mechanism for controlling
access to explicit selectors
(and the files they correspond to);
including definitions of realms as a set of selectors.
- Support for the HTACCESS method of access control
- Several mechanisms for recording hits
- Several forms of redirection can be specified
- A simple form of load balancing is supported
- Support for "common-log" format audit files (as well as
browser and referer log files)
- Special SRE-http built-in features include:
- A file display and transfer facility with easy
directory traversal
- A simple but powerful "text file" search facility
- Dynamic assignation of "short-term" privileges to clients
- Extraction of a range (bytes or lines) of a resource using
options specified in the selector
- Tracking of recent hits to prevent recording of repetitive requests
- Optional limits on frequency of unsuccesful "logon" attempts, with
options for custom response files in the event of "logon" or "access"
denial.
- Implementation of "byte range retrieval" (which is used
by Adobe Acrobat to access subsections of documents)
- Response headers can be automatially generated, using LINK and META
HTTP-EQUIV elements in the <HEAD> portion of the document.
- A Content-MD5 digest can be added to all, or to a select set, of responses
- On-the-fly GZIP transfer-encoding is supported (both sending and recieving).
GZIP and COMPRESS are also understood as content-encodings.
- Partial support for delta-encoding
- Several file upload methods are supported
- Client directed retrieval of files from other HTTP servers
- Browsers that support the
type=file
FORM attribute (such as NetScape 2.01),
can upload files from their own machines.
- The PUT verb, with byte ranges, can be permitted on a per selector (or
per "set of selectors") basis
- The DELETE method can be permitted on a per selector (or
per "set of selectors") basis
- User written server side processing (gateway programs) options include:
- Support for SRE-http addons (REXX routines that return results directly to the client).
- CGI-BIN scripts (both REXX and binary executables, and PERL scripts
if you have a PERL interpreter installed) are
supported (using procedures adapted from the GoHTTP package).
- A "pre-filter" can be called prior to invoking SRE-http
- SRE-http comes with a special pre-filter that
implements the the GoRemote package.
- A "post-filter" can be called after SRE-http has responded to the request.
- SRE-http comes with a special post-filter that uses socket calls, to an SMTP
server, to e-mail "event specific" alerts.
Return to table of contents
The following terms are used in this documentation. Please forgive any non-standard uses
you may encounter (better yet, let me know).
You might also want to review the
basic terminology for extended descriptions of a few key concepts.
- The \ and / characters
- The / character is used in URLs to
"indicate hierarchical structures, such as directories". It is equivalent to
the \ OS/2 (and DOS) character. Thus, / that appear in a request selector are
converted into \ when SRE-http needs to find a file.
- Action
- The action is the "location" portion of a request
selector.
- If the GET method was used -- it's the part
after the first / (that ends the domain name) and before the first ? (or the
end of the request selector , if no ? is present).
Examples:
-
In
http://foo.bar.org/calc/calc.htm
,
the action woud be calc/calc.htm
.
- In:
http://foo.bar.net/workdir/myfile.htm?not+readyl
,
the action would be is workdir/myfile.htm
.
- In:
http://young.kids.com/toys/demo?dogs+cats
,
the action would be toys/demo
- If the POST method was used, the request selector (not including a
leading / character) is the action (there should never be a ? in a POST
method request string). All other information is
contained in the "body" of the request. SRE-http assumes that all POST method
requests are for Server Side Processing.
- Addon directory
- The addon directory (with a value given by the ADDON_DIR parameter)
is where SRE-http's external procedures should be
stored. For example, several external procedues shipped with SRE-http
(i.e; the simple and intermediate configurator) should be located in this directory.
- Alias -- converting selectors
- SRE-http uses "aliases" to perform textual substitution. Typically, an alias is
used to replace a simple request selector with a more complicated one. In addition, aliases are
used for several special purposes: implementing "searchable indices", document redirections,
and specification of the location of CGI-BIN scripts.
- Alias -- virtual hosts
- A given IP address can be used by several hosts: including the
host associated
with the "canonical" name, and hosts associated with one of several aliases.
Unfortunately, TCP/IP requests
arrive with only the numeric IP address, making it difficult for the server
to determine to which host the request is directed to. However, HTTP 1.1 compliant
browsers (such as NetScape 2.01) will include a
HOST:
request header containing the host to whom this request is directed; and
SRE-http can use this request header (if present) to determine the
proper host.
- Client
- The Client (sometimes referred to as the requester)
is the individual requesting a URL -- where the URL may point to a file,
or may invoke Server Side Processing.
Typically, the request was generated by someone running a Web Browser, and
clicking on a link or submitting a FORM.
- CGI-BIN
- CGI (Common Gateway Interfact) - BIN is a standard by which server side ("gateway")
programs can be invoked. It uses environment variables to pass data, as well as
standard input and output. SRE-http supports CGI-BIN, using procedures adapted
from the GoHTTP package. One nice feature of SRE-http
is an ability to call alternate
(non-REXX) interpreters for specific scripts (such as PERL when a script has
a .PL extension).
Although this support should permit use of many CGI-BIN
scripts, the use of the "native" SRE-http interface (using
REXX procesures that are passed information in the argument list) offers
advantages to ambitous programmers
- The Default Data Directory
- The Default Data Directory is the root directory of your
web site -- it (and its subdirectories) are the usual locations
for the HTML documents, images. In simple cases, the GoServe
data directory is used as the the Default Data
Directory. On multiple-hosts server, each host can
be granted its own Default Data Directory.
A simple example might help:
- a request selector of MYFILES/PROJECT1/BIGTASK.HTM is recieved
- your default data directory is E:\WWW
then, SRE-http will look in E:\WWW\MYFILES\PROJECT1 for the BIGTASK.HTM file.
A Note On Data Security in SRE-http
In general, the only files available for clients
are those in (or under) the Data Directory. Exceptions to this rule include:
- Files explicitly transferred by user-supplied executable code
(i.e; REXX procedures). Note that
user-written Rexx code
may be invoked by a CGI-BIN script or a SRE-http addon, or by INTERPRET, #EXEC
and SELECT keyphrases.
- A !TRANSFER "alias" can be used to access files from anywhere on the server.
- Files specified by literal PUBLIC_URLS.
- Virtual directories can point to anywhere.
- ELEMENT
- ELEMENT's are the constituent parts of an HTML document. They
dictate the structure, layout, and display characteristics of an
HTML document. ELEMENTS are identified using HTML tags,
where an HTML tag consists of text within
< and > characters. Often, a start
and stop tag are used.
For example:
<H1> Welcome </H1>
: defines a "level 1 Header"
<A href="/morejunk/stuff.htm"> More info? </A>
:
defines a link to a local document.
- File Names: Fully qualified and Relatve
- SRE-http can treat File Names as "fully qualified" names or
as "relative" names. Fully qualified names should be fully
pathed -- containing the
complete path to the file (sometimes the drive letter will be missing, in which
case the GoServe drive is usually assumed). Relative names are assumed to be in
subdirectories of some assumed default. For example, when a client asks for a file name,
it is assumed to be relative to the data directory (or to a matching
virtual directory).
- FORMS
- The HTML FORM element is used to create a fill-in form.
A FORM element
typically contains an ACTION attribute, as well as a number of elements
that provide editable fields (for the client to fill in or to otherwise
select). Typically a form is designed in tandem with a server-side program.
Although not the only
way to generate a Server Side Processing Request
(one can use sets of detailed URLS),
FORMS are probably the easiest for the average client to deal with.
- Hosts
- It is possible for one server machine to handle requests to
multiple IP addresses. This "multiple hosting" (also refered to as
multi-homing) can occur either by
having the server handle several numeric IP addresses, or by
the existence of multiple aliases for a single numeric IP address.
- Host nickname
- SRE-http uses host nicknames when identifying
which host a parameter applies to. Besides being a convenience,
it allows several hosts to point to identical resources (given that each
host has the same host nickname).
- HTTP : Hyper Text Transfer Protocol
- The rules by which web-aware clients and servers communicate.
- HTTP method (also known as the VERB)
- SRE-http recognizes five HTTP methods: GET, POST, HEAD, DELETE, and PUT.
- GET requests contain all information (action name and optional parameter list) in the
request string (with the parameter list placed after a ? character)
- POST requests
contain only the action name in the request string (the "body" of the request contains
the parameter list). Currently, SRE-http assumes that all POST requests
are requests for Server Side Processing.
- HEAD method requests are sent "meta information" on the requested file, the
file itself is not sent.
- PUT method requests are used to upload information to the file pointed to by
a request selector . SRE-http will only honor PUT method requests if specific
permissions are granted for that selector (as set in the ACCESS_FILE).
- DELETE method requests are used to delete (the file pointed) a requested
selector . SRE-http will only honor DELETE method requests if specific
permissions are granted for that selector (as set in the ACCESS_FILE).
- HTML
-
Hyper Text Markup Language (HTML)
is the protocol used to create
documents designed for display by WWW browsers (such as Netscape, Mosaic, MS Internet
Explorer,and IBM Web Explorer). Basically, HTML consists of a set of formatting commands,
which are included in a file containing the text to be displayed.
SRE-http uses file extensions to identify HTML documents. By default,
the following extensions are used: .HTML, .HTM, .SHT, and .SHTML.
You can add to this list by modifying
MEDIATYP.RXX.
Although there is a formal HTML standard (currently 3.2, with
4.0 under discussion),
it is not rigidly adhered to. In particular,
NetScape and Microsoft have their own extensions.
- Imagemap
- An image map (sometimes called a mappable image) is an inline image which, when
clicked with the mouse, returns a pixel location to the server. Typically, the
server then translates the pixel location into a URL, and redirects the client
to that URL (which might be on an all together different server). SRE-http supports
image maps using the MAPIMAGE/ "indicator string", along with NCSA and CERN style "MAP"
files to use in translating pixel locations to URL's.
Note that some browsers (such as
NETSCAPE 2.0) support "client side mappable images",
which require no action by the server (but
which require an HTML element not understood by many other browsers).
- IN-HOUSE
- IN-HOUSE refers to clients that are "in-house"; specifically, they
have had INHOUSE privileges assigned to them. The idea is that one often
wants to differentiate members of your "organization" from the rest of the
world, and place fewer
limits on what they can obtain from the server.
- Macrospace
- Marospace is best thought of as a global procedure cache used by OS/2.
When REXX programs are asked to load external procedures, they first look
in macrospace. For efficiency reasons,
SRE-http makes extensive use of macrospace.
- Privileges
- SRE-http uses "privileges" to control access to selected resources.
There are two classes of privileges:
- "resource" privileges which are
assigned to server resources (such as files, or directories), using
entries in the ACCESS_FILE.
- client privileges which are granted to clients (based on their IP address,
or their explicit username/password).
Resource privileges can be ONE_OF privileges ("or" privileges") or
MUST_HAVE privileges ("and" privileges). Client privileges may be
static (assigned using INITFILT.80 or the USER_FILE), or may be
dynamic (set on the fly as a function of the client's earlier requests).
- Request selector
- When a client sends a request to a server, it contains three components:
the http method, the selector, and the http protocol.
For example: GET /FOO1/BAR.HTM HTTP/1.0
In this documentation, the term request selector refers to
this middle component, with leading / stripped, and character decoding performed.
In the above example, the request selector would be FOO1/BAR.HTM.
Note that if a GET HTTP method was used, the request selector may contain
information following a ? (for example, SHOWINFO?database=Prices&item=apples).
- Response Header
- The response header contains "meta-information" about the requested document.
GoServe automatically sends a few response headers
(such as content length and file creation date).
In addition, using the
LINK
and HTTP-EQUIV
tags in the <HEAD> portion of your document,
you can instruct SRE-http to automatically add other response headers.
- Searchable Index
- A searchable index is a document that points to a file that is to be searched.
One can think of a searchable index as:
.. the front end to a gateway program,
and the file you search as the database
represented by the document.
Typically, a searchable index contains the <ISINDEX> element.
- SEL-specific
- SEL-specific means "a piece of information
specific to a request selector .
Clarifying, this means that SRE-http will use the value of the request selector
to find information (such as resource privilege information).
Thus, SEL-specific resource privileges
really means "privileges associated with a particular request selector
(coming up with terminology isn't easy ....)
Note: the SRE-http documentation sometimes uses the term
URL-specific
to mean SEL-specific
(its a holdover from an earlier revision of the documentation).
- Server Side Includes
- Server side includes refer to on-the-fly modifications of requested HTML
documents.
Inclusions can be static, in which case the use of server side includes is mostly
to benefit the creation and maintenance of these documents. Dynamic
includes refer to information that changes, such as the current time and date --
obviously, these can not be specified in the document a priori,
but must be determined at
the time of request.
- Server Side Processing
- Often, the server provides computational services to clients. An example of
this is a client specified search of a
database, with the results displayed using an 'attractive" HTML document
(generated just for this search). Or, the client might request a map of
some portion of the U.S, displaying a choice of geographic features. Such
actions require the server to execute some kind of program (perhaps a REXX program,
or perhaps some other executable).
SRE-http addons, and
CGI-BIN scripts, are typical means by which Server Side Processing is provided
to clients.
- Server Side Processing Request
- A Server Side Processing request is, generically speaking,
"a set of parameters, sent by a client, and an action name,
that dictate
Server Side Processing". Often these are generated by a client responding
to a FORM element in an HTML document (alternatively, they may be "hand coded"
into a URL included in a HTML document). Server Side Processing requests are
recognized by:
- If the GET method was used:
the presence of a ?options string after a "non-HTML"
action name; where options contains
the "set of parameters".
Notes:
-
SRE-http assumes that, regardless of the presence of a ? in the request
selector ,
all action
names that end with a .HTM, .HTML, .SHT, or .SHTML are requests for HTML documents (that is,
are not requests for server side processing),
-
Actions which require no parameters must have
a ? trailing the action name.
- Server side programs are sometimes referred to as gateway programs.
- If the request selector starts with CGI-BIN/ , then it's
assumed to be a request for a CGI-BIN script.
- If the POST method was used, SRE-http assumes a Server Side Processing Request,
with the request selector treated as the action (which identifies the
program to run), and the "set of parameters" contained
in the "body" of the request.
- STEM. variables
- STEM variables are REXX's way of implementing arrays. A STEM variable consists
of a NAME.INDEX1.INDEX2 syntax (that is, with a . used to indicate "array indices"). SRE-http
uses STEM variables for several of its configuration parameters.
- SUPERUSER status
- Clients with SUPERUSER status are granted full privileges. Currently, this
includes:
- Never having to logon (SUPERUSERs are INHOUSE users)
- Automatically granted CONTROL
privileges (can perform remote server resets)
- File uploads are never blocked.
- URL: Uniform Resource Locator.
- URL's are a scheme for specifying Internet
resources using a single line of printable ASCII characters. A URL should
contain
a protocol, domain name, port number (optional), the location of the resource, and
an (optional) option list (following a ?).
In this documentation, the URL term connotes "a link coded into an HTML document".
Upon selecting such a link, the client sends back a request string that
contains the verb (the HTTP method), the request selector , and
the http protocol (typically, HTTP/1.0)
Example:given a URL of
http://www.crosslink.net/calc/calc.htm
the resulting request selector would be calc/calc.htm
- URL character encoding
- Since several characters have very specific meanings in the HTTP protocol (such
as the & and the > characters), and since spaces are not allowed in request
strings, a set of
character encoding rules are needed to transmit such characters.
Caution: When handcoding URL's with an option list following a ? and
seperated by &
characters, you must encode the & character.
For example:
- INCORRECT:
<A HREF="/GETAFILE?dir=PUBLIC/&showdate=YES">
- CORRECT:
<A HREF="/GETAFILE?dir=PUBLIC/&showdate=YES">
- Web Browser
- A Web Browser is a program that can communicate over the
Internet, and that is capable of displaying HTML documents.
NetScape, Mosaic. and IBM Web Explorer are examples of Web Browsers.
- Wildcard matching
- Wildcard matching use the * as a wildcard character in a natural
fashion.
Examples:
/JOE/* will match /JOE/FOO.HTM
/JOAN/SRCH.HTM?* will match /JOAN/SRCH.HTM?search+me
/JOAN/SRCH.HTM?* will NOT match /JOAN/SRCH.HTM
(/JOAN/SRCH.HTM* will match BOTH these examples)
/PETS/*INDEX.HTM will match
/PETS/INDEX.HTM, /PETS/CAT/INDEX.HTM and /PETS/PUPPY/LAB/INDEX.HTM
but will NOT match
/PETS/CAT/PUREBRED.HTM
SRE-http files that support wildcard matching are:
ALIAS_FILE, RECORD_ALL_FILE,
SENDFILE_FILE, ACCESS_FILE, and the PUBLIC_URL stem variables.
The COUNTER_FILE does not support wildcard matching.
- Wildcard matching with substitution
- Wildcard matching with substitution is similar to wildcard matching.
However, rather then being a "many to one" match, it is a "many to many" match.
The basic rule is that both a "target" and a "replacement" should contain
* characters. When a wildcard match between the target and a candidate occurs,
the "covered portion of the candidate" is inserted into
the "replacement". In other words, the * character in the
replacement is deleted, and the "covered portion" is inserted.
Example:
- If the request selector is:
project/jillwork.htm
- and there is an alias of:
project/* /research/ongoing/*
- SRE-http will convert the request selector to
/research/ongoing/jillwork.htm
- GoServe Working Directory
- The GoServe Working Directory in the directory containing GOSERVE.EXE (typically,
\GOSERV). You
should copy the various SRE-http files to it (see the
installation section
for details).
Return to table of contents
For questions, contact
Daniel Hellerstein.