*
6 January 2003 SREhttp/2 Frequently Asked Questions
-------------------------------------
This document contains answers to some "frequently asked questions" about the SREhttp/2
web server for OS/2.
* What is SREhttp/2 and SRE2003?
* What can SREhttp/2 do?
* What does SREhttp/2 cost?
* Where can I get SREhttp/2?
* I downloaded the SREHTTP2 .ZIP file, how do I install it?
* SREhttp/2 won't start -- what should I do?
* Can SREhttp/2 run under Object REXX.
* The response time seems to be very slow....
* How do I configure SREhttp/2?
* Can I edit SREhttp/2's configuration files?
* How can I control access to my site?
* How can I control access to a directory?
* What are "client privileges" and "required privileges"?
* What's the difference between REALMS and privileges?
* I'm still confused about these privilege things?
* What are the server side include capabilities of SREhttp/2?
* Can I use cookies with SRE2003 and SREhttp/2?
* What about default documents?
* What are SREhttp/2's virtual directories?
* How do I redirect a request?
* Can I customize SREhttp/2 responses?
* How does SREhttp/2 deal with multiple "wildcard" matches?
* How can I record the number of hits I get?
* How can I speed up throughput?
* How do I define new MIME media types?
* What are the SREhttp/2 addons?
------------------------------------------
*** The basics:
* What is SREhttp/2 and SRE2003?
SREhttp/2 is an http/1.1 compliant World Wide Web server for OS/2.
More precisely, SREhttp/2 is a "filter" for the SRE2003 Internet Interface.
Basically, SRE2003 provides and "API" that facilitates working with
http requests. SREhttp/2 uses this "API" to implment an http/1.1 web server.
Other filters exist for SRE2003, including a Simple filter that comes
packaged with SRE2003. For those who do not need the rich feature set
of SREhttp/2, use of this Simple filter (or the SRELite/2 filter) may be
advantageous.
* What can SREhttp/2 do?
In a nutshell:
SREhttp/2 is a http/1.1 compliant web server OS/2. SREhttp/2 is designed
for non-cutting edge, small-to-medium load sites being maintained
by non-professionals who want a high degree of functionality in an
easily maintained system. SREhttp/2 is also well suited for REXX proficient
individuals interested in creating a highly customized site.
* What does SREhttp/2 cost.
$0.00. You may freely use, and freely distribute SREhttp/2.
You may dissect, subsect, and otherwise utilize its source code.
Please be aware of the standard "use at own risk" disclaimer (see the disclaimer
package with SREhttp/2).
* Where can I get SREhttp/2
The latest version of SREhtt/2p (it's constantly being updated) can be
found at http://srehttp2.srehttp.org/. SREhttp/2 is also
available from a number of file repositories: the latest version
will always be on hobbes (http://hobbes.nmsu.edu/ -- search for SREHTTP2)
**** Installing SREhttp/2
* I downloaded SREHTTP2_xxxx.ZIP, how do I install it?
Note that the xxxx stands for the current version. For example SREHTTP2_112C.ZIP.
i) Create a temporary directory somewhere on your hard drive,
ii) Copy SREHTTP2_xxxxF.ZIP to this temporary directory
iii) Using UNZIP, unzip SREHTTP2_xxxx.ZIP
iv) Read the READ.ME file
v) Run the INSTALL program (type INSTALL from an OS/2 prompt)
Reminder: to use SREhttp/2, you MUST have SRE2003 installed.
SRE2003 can be found at http://sre2003.srehttp.org
* SREhttp/2 won't start -- what should I do?
* Are you using SRE2003? Is it running?
* Is the SRE2003 FILTER parameter (in SRE2003.CFG) pointing to the directory you
installed SREhttp/2 into (the INSTALL.CMD installation program SHOULD set this up
properly)?
* Is the SRE2003 DATADIR parameter (in SRE2003.CFG) pointing to the
"root of your web tree".
If you still have problems after checking the above, you should obtain
PMPRINTF.EXE from http://www2.hursley.ibm.com/goserve) and run
it before you start SRE2003. PMPRINTF opens a small window into which
SRE2003 & SREhttp/2 can write status and error messages -- often, these
will indicate what your problem is.
If you are still stuck, feel free to contact Daniel Hellerstein
(danielh@crosslink.net).
* Can SREhttp/2 run under Object REXX?
SREhttp/2 and SRE2003 were designed to run under "classic" REXX (technically, REXXSAA).
Unfortunately, for several reasons, the current version of SREhttp/2
will NOT run object REXX.
Author's note: If there is real interest in using SREhttp/2 in an
Object REXX environment, I might be persuadable ...
* The response time is very slow ...
[this pertains to version of OS/2 prior to 2001]
For unknown reasons, on some Warp 4.0 machines running version 4.0 of TCP/IP,
SREhttp/2 has horrid response times (many seconds to return simple documents).
This has been solved by upgrading to TCP/IP version 4.02t
(you can find fix packs at http://service5.boulder.ibm.com/pspfixpk.nsf
or ftp://ps.software.ibm.com/ps/products/tcpip/rsu/stack/latestv4.html).
* How do I configure SREhttp/2?
Most people will probably want to use the built in configurator.
This configurator is designed to be run via your web brower.
Assuming you did not make major modifications to SREhttp/2's
installation defaults, you can just point your web browser at:
http://your.browser.wherever/sre2k/srehttp2/configs.htm
You can then configure one of several configuration files -- most of which
can have default and host-specifc versions.
You are also offered several shortcuts, for common configuration tasks.
Hint: If SREhttp/2 denies you access to the configurator, you should
* check the SECURITY_LEVEL parameter in SRE2003.CFG
* check the serveraddr_use and serveraddr_inhouse variables in SRE2003.CFG
* check for a SUPERUSER user entry in USERS.CFG
* Can I edit SREhttp/2's configuration files?
For those who like to make their changes quickly, you may want
to directly edit the SREhttp/2 configuration files, and not
bother with the configurator. The configuration files are
all text (ascii) files, which you can modify with your favorite
text edtior (such as OS/2's EPM editor).
The configuration files for the "default" host are in the SREHTTP2\CFG directory.
For each host you define, you can also create "host-specfic" configuration files --
they will be located in subdirectories of SREHTTP2\CFG.
The most important configuration files are:
attribs.cfg --- Define selector-specific attributes
counter.cfg --- Configure the hit-counter utility
hostdata.cfg --- Host definitions
logs.cfg --- Configuration parameters the SREhttp/2 log files
preloads.cfg --- Define auxillary procedures used by SREhttp/2
manager.cfg --- Configure the file-manager utility
mimetype.cfg --- Mimetype definition
ssi_vars.cfg --- Server-side-include variables
sre_util.cfg --- Parameters for the SREhttp/2 utilities
srehttp2.cfg --- Basic parameters for SREhttp/2
users.cfg --- Define username/password entries
*** Some more specific questions:
* How can I control access to my site?
SREhttp/2 uses required privileges, in conjunction with client privileges,
to control access. Required privileges are assigned on a host and selector-specific
basis, while client privileges are assigned by username or by IP address.
Required privileges are defined in the possibly host-specific ATTRIBS.CFG file.
Username, and IP addresses, are defined in the possibly host-specific USERS.CFG file.
Note on "selector":
a URL of
http://foo.bar.net/dir1/redsox.htm
would generate a request string of
GET /dir1/redsox.htm http/1.0
which yields a "request" selector of
dir1/redsox.htm
In other words, selector-specific access controls are
sensitive to how you code links in your HTML documents.
* How can I use selector specific access controls to
control access to a directory?
Selector specific can refer to "a set of resources on your server".
This is specified via the use of the * wildcard when defining a selector.
* What are "client privileges" and "required privileges" ?
SREhttp/2 uses "privileges" to provide flexibility and brevity
when assigning (and determining) access rights.
"Client privileges" are assigned to clients in a variety of
fashions (typically as part of their username/password
authentication). In a sense, "client privileges" can be thought of
as shorthands for "groups of users".
The point is that by allowing multiple privileges per username,
a given client can be placed in many different groups of users.
"Required privileges" are assigned as selector-specfic attributes, in
the possibly host-specific ATTRIBS.CFG file.
Required privlieges can be thought of as a list of "groups of users".
In the extreme case of each username having a single privilege (say, equal
to her username), the "required privileges" list the acceptable users!
Advanced users note:
If you start a client privilege with a ? (say, ?PXX12), then
this will be treated as a "secret privilege". Secret privileges
are NOT used in access controls, and SREhttp/2 utilities
should NOT reveal their values. They are designed to be
by used by addons, such as the "dynamic password" and "encryption"
addons.
* What's the difference between realms and privileges?
SREhttp/2's selector specific access control method is based on the notion of
"privileges". More precisely, SREhttp/2 uses "realms" to identify resources
that are subject to access controls/ Realms are defined with one or more rules,
where each rule specifies a (possibly wildcarded) selector.
Basically, most browsers will store a username and password
on an IP address and realm specific basis. When a server asks for
authorization, it will tell the browser what "realm" the
resource belongs to. Assuming that the username (and password) for
this ip-address/realm combination is available (say, due to an earlier request
for another resource), then the browser will return the appropriate
username and password.
Note that realms are defined as collections of selectors --
a collection that span your hard drives in complicated ways.
* I'm still confused about these privilege things?
It's actually simpler then it reads, especially if you don't need the
fancier features. Let's sketch out one such "simple" approach:
1) Use the configurator to "define a new user" (do it for as many users
as you need to define.
For each new user, provide a username, password, and a
list of client privileges.
2) Use the configurator to "restrict access to a resource".
Define privileges that match the one (or more) of the privileges
defined for the users.
That's all you have to do -- user's with a "client privilege" that
matches ANY ONE of a "selector's" require privileges will be granted
access rights to it. If they haven't entered a username/password
before hitting a protected server resource, the client will be asked
for his username and password.
Note: you can also define "INHOUSEIPS." entries, which allow automatic
assignation of client privileges via the client's IP address.
* What are the server side include capabilities
of SREhttp/2?
A major advantage of SREhttp/2 is the ease with which a variety
of Server Side Includes (SSIs) can be invoked-- just by adding special
keyphrases to your HTML document. Even better, these server side
includes are processed recursively -- so a server side include
can invoke further server side includes.
SREhttp/2 supports two classes of server side includes, instances of
which can be freely intermingled in your documents:
i) The SREhttp/2 syntax.
The SREhttp/2 syntax supports a variety of server side includes,
such as:
a) Inclusion of a file
b) Inclusion of a set of "dynamic variables" (such as time/date)
c) Inclusion of user defined "static variables"
d) Execution of a REXX program, with inclusion of "QUEUED"
output
e) SPECIAL Feature: Exclusion of a portion of a document,
based on the results of user written REXX code
f) Headers and Footers can be added to all documents.
ii) The NCSA HTTPD syntax.
The NCSA HTTPD syntax is supported by SREhttp/2.
For more information on the NCSA HTTPD server side includes,
check out http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
iii) Apache Extensions
The SET and IF Apache extensions to the NCSA HTTPD syntax are
also supported. These can be used for creating conditional
html documents.
* What is the SSI-Cache?
To improve performance, SREhttp/2 can "intelligently" cache
documents that contain server-side includes. In simple cases,
these cached entries can be sent to the client "as is" -- relieving
the server of the need to reprocess the "server side includes". Needless
to say, this can yield major performance advantages.
The "intelligently" refers to those not-so-simple cases where the server
side includes are "dynamic". "Dynamic" server side includes are items that
change over time, client, and circumstance. A few obvious examples
include the current time, the "number of hits", and the client's IP address.
Obviously, one can't cache-return dynamic server side includes "as is".
SREhttp/2 solves this dilemna by "partially caching". Basically, "static"
includes are performed (such as file INCLUDES), and placemarkers are
created for the "dynamic" includes. This can substantially diminish the
workload, especially in cases where large file include (such as a standard
menu bar) are combined with minor dynamic includes (such as the current
"hit").
* Can I use cookies with SRE2003 and SREhttp/2?
SREhttp/2 offers a few conveniences when processing cookies:
* The INTERPRET "keyphrase" of SREhttp/2 provides a convenient
means of reading and creating cookies; and of changing
the contents of document based the values of the cookies.
* Several procedures, in the SRE2003 and SREhttp/2 procedure library, make it
easy to read and write cookies.
* A good description of cookies can be found at:
http://home.netscape.com/newsref/std/cookie_spec.html
* What about default documents?
SREhttp/2 recognizes uses the DEFAULT paramter (in SREHTTP2.CFG) to
deal with "empty requests", and those for "requests to a directory".
When an empty request arrives, the DEFAULT variable is used to indicate
what document to return. For example, if DEFAULTS='INDEX.HTML', then
a request for http://foo.bar.net/ would result in D:\WWW\INDEX.HTML
being returned (assuming that D:\WWW is your default data directory).
"Requests to a directory" refers to requests that mention a directory
name, but no file. For examplem, a request for http://foo.bar.net/mule/
refers to the "default document in the MULE subdirectory".
The DEFAULTS parameter is used for these types of requests also --
with a few tricks that allow you to look for more then one file,
to use the "subdirectory name as the file name", or to generate a
directory listing of the directory.
Note: if the last portion of a request, following the last /, does NOT contain
a ".", SREhttp/2 can treat this as last portion as a directory name.
In other words, SREhttp/2 will append a "/".
For more details, see the ADD_SLASH parameter in SREHTTP2.CFG.
* What are SREhttp/2's virtual directories?
By default, SREhttp/2 will match a request selector to a file in the
"default data directory". While a good security feature (files not in or
under the default data directory are inaccessible), this can be an
inconvenience.
To remedy this inconvenience, one can define "virtual directories"
Basically, SREhttp/2 will compare the starting portion of the client's
request to see if it matches one of your virtual directory entries. If it
does, the target directory listed in the matching entry is used
(instead of the data directory).
Thus, you can make available a wide, but controllable, set of
directories (on or LAN accessible from) your server.
Furthermore, virtual directories can point to "remote" directories on
other http servers -- SREhttp/2 will attempt to retrieve the file
from the remote server, without using a redirection!
An example of the use of virtual directories:
i) Assume that the default data directory is D:\WWW
ii) Assume you want to provide access to the following files;
D:\WWW\TELLME.HTM, D:\WWW\BIRDS\PARROT.HTM,
E:\SOUND\NATURE\CHIRP.WAV, E:\SOUND\NATURE\MORE\TWEET.WAV,
E:\PHOTOS\SKY\FLYING.JPG
iii) Two virtual directories should be defined (you can use the configurator):
NATURE/ --> E:\SOUND\NATURE*
PHOTOS2/ --> E:\PHOTOS\SKY*
Given i,ii, and iii; the following links can be used
HTML anchor ---> points to ---> file
href="/TELLME.HTM" D:\WWW\TELLME.HTM
href="/BIRDS/PARROT.HTM" D:\WWW\BIRDS\PARROT.HTM
href="/NATURE/CHIRP.WAV" E:\SOUND\NATURE\CHIRP.WAV
href="/NATURE/MORE/TWEET.WAV" E:\SOUND\NATURE\MORE\TWEET.WAV
href="/PHOTOS2/FLYING.JPG" E:\PHOTOS\SKY\FLYING.JPG
* How do I redirect a request?
One of the strengths of SREhttp/2 is the variety of redirection
mechanisms it offers, where redirection implies "sending the client
a file that is not a direct mapping of the request selector. Redirection
has two general classes: remote and local.
"Remote" redirection, which is what most of the literature simply
calls redirection, involves telling the client's browser that
"the url you have been requested has been moved to xxxx", where xxxx may
be any URL -- it need not be on the same server, and it need not have
the same name.
You can use the configurator to define a redirection.
For example, suppose you define a temporary redirection of:
whatgot -- to --> http://www.mine.org/dir1/index1.htm
This causes the server to send back a "302" response to the client's
browser whenever a request for "whatgot" arrives. This 302 response,
would instruct the client's browser to automatically request
http://www.mine.org/dir1/index1.htm.
"Local" redirection is handled solely by SREhttp/2, and involves
directly modifying the "request selector."
Local redirections actually involve textual substitution (after SREhttp/2
has recieved the request). Among other advantages, this gives you quite a
bit of control over how "SREhttp/2 facilities, and external procedures"
percieve the request.
Notes:
* A CAUTION on local redirection and partial urls:
When a request selector is subject to "local redirection", partial URL
resolution by the client's browser (of URIs contained with text/html
documents) may have unexpected consequences.
* Can I customize SREhttp/2 responses.
In a number of circumstances, SREhttp/2 will generate an error or status
response. For example, if a request file does not exist, or if a client
does not have access rights to a file, SREhttp/2 will send a somewhat terse
response (but at least it's not a totally terse "401 Unauthorized"
displayed all by itself)!
Currently, you can customize a few of these responses:
No file found:
The NOT_FOUND_FILE parameter (in SREHTTP2.CFG) can be used
to specify a special "no such resource" response file.
Access denied:
SREhttp/2 can either reprompt the client for a different username
and password, or it can send her a custom written response
file. This file's name is set with the FAIL_FILE parameter (in
SREHTTP2.CFG).
* How does SREhttp/2 deal with multiple
"wildcard" matches.
When SREhttp/2 attempts to match a selector to a "realm", it is possible
that several rules will be "wildcard" matches.
When this happens, a multiple wildcard match algorithim is used.
Example: If the selector is FOOD/FRUIT/ORANGES.HTM
Then the following all match; with earlier entries used first.
FOOD/FRUIT/*HTM
FOOD/FRUIT/*
FOOD/*IT/*HTM
FOOD/*.HTM
FOOD*
(these entries can appear in any order in this file, with no
effect on precedence).
Note that you can use multiple wildcards for multiple replacements.
For example, an entry (in ALIASES.IN) of:
school/*/personal/*/pictures* arg1=*:arg2=*
And a request of:
school/grade8/personal/killebrew/pictures/family.jpg
would yield:
arg1=grade8;arg2=killebrew
* How can I record the number of hits I get?
SREhttp/2 provides a wide variety of tools for recording the number
of hits you recieve. These include:
1) The SRE2002 auditing mechanism
2) Common-log auditing of all requests
3) Tracking number of requests, by request selector
4) SENDFILE: a send-and-record-success utility
5) Server side includes to insert hit-counters
6) A COUNTER utility to insert fancy hit counters
* How can I speed up throughput?
The best way to speed up throughput is to enable the SRE2003 request cache.
The request cache provides a "proxy-like" front end
for SREhttp/2. It can detect "cached" resources, and
respond to them quickly (without needing to check the various
SREhttp/2 access control, redirection checks, etc).
* How do I define new MIME media types?
There are several ways of defining resource specific mimetypes.
More specifically, there are several ways of tell SREhttp/2 what
Content-type response header to send to the client.
a) defining "file extension" mime types.
By default, SREhttp/2 maps file extensions to mime types. For
example, .HTM and .HTML files are assumed to be text/html
resources, and .GIF files are assumed to be image/gif
resources.
To:
* define a new file-extension-to-mimetype mapping,
* to map a non-standard extension to a standard MIME media type,
* or to redefine one of the default mappings,
just edit the possibly host-specific MIMETYPE.CFG configuration files.
b) defining selector specific mime types.
You can assign a mimetype as one of the selector specific attributes.
c) defining the mimetype in the URL.
When you code a link in your HTML documents, you can use the
!SENDAS special prefix to tell SREhttp/2 what mimetype to use
for the desired resource. This can be useful if you want to
use a special mimetype. For example, to allow clients to either
an HTML document, or to view its source code:
a href="foobar.htm" -- view as html
or
a href="!SENDAS_TEXT_PLAIN/foobar.htm" -- view as text
* What are the SREhttp/2 addons?
As an alternative to the CGI-BIN script interface, one can
write REXX routines that are called directly by SREhttp/2,
without the somewhat convoluted use of environment strings
that CGI-BIN scripts depend on.
SREhttp/2 comes with several addons (such as those comprising the SRE-Utilities
bundle). Additional addons can be obtained from the SREhttp/2 home page at
http://srehttp2.srehttp.org/apps/download.sht
--- End of document.
To top of document