...
1 November 1999 SRE-http Frequently Asked Questions
Note: This can be viewed as an HTML document by using the following "selector":
a href="!sendas_text_html/samples/srehttp.faq"
(assuming that the document resides in the /samples "web directory"
on an SRE-http server)
-------------------------------------
This document answers the following questions:
* What is SRE-http and GoServe?
* What can SRE-http do?
* What does SRE-http cost?
* Where can I get SRE-http?
* I downloaded SREV13F.ZIP, how do I install it?
* SRE-http won't start -- what should I do?
* Can SRE-http run under Object REXX.
* The response time seems to be very slow....
* How do I configure SRE-http?
* Can I edit SRE-http's configuration files?
* How can I control access to my site?
* How can I control access to a directory?
* What are "client privileges" and "resource privileges"?
* What's the difference between REALMS and privileges?
* I'm still confused about these privilege things?
* How can I limit the capabilities of different users?
* How can I limit off-site links to our images?
* What are the server side include capabilities of SRE-http?
* Can I use cookies with GoServe and SRE-http?
* I am having trouble with uploads, what should I do?
* What about default documents?
* What are SRE-http's virtual directories?
* How do I redirect a request?
* Can I customize SRE-http responses?
* How does SRE-http deal with multiple "wildcard" matches?
* How can I send a "thank you" note after a file download?
* How can I record the number of hits I get?
* How can I speed up throughput?
* How do I define new MIME media types?
* How can I prevent NetScape from reloading files too frequently?
* What are the SRE-http addons?
* How is SRE-http multi-threaded?
To users of Don Meyer's GoHTTP -- where appropriate, this document notes
the similarities between the two filters. You might want to pay special
attention to:
What are "client privileges" and "resource privileges"?
How do I redirect a request?
What are SRE-http's virtual directories?
How can I control access to my site?
------------------------------------------
*** The basics:
* What is SRE-http and GoServe?
SRE-http is an http/1.1 compliant World Wide Web server for OS/2.
More precisely, SRE-http is a "filter" for the GoServe OS/2 Internet Server.
GoServe, an IBM EWS "freeware" product, is an HTTP and Gopher server.
GoServe requires a "filter", written in REXX, to interpret and process
requests for resources. SRE-http is one of several such filters.
* What can SRE-http do?
In a nutshell:
SRE-http is a http/1.1 compliant web server OS/2. SRE-http 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. SRE-http is also well suited for REXX proficient
individuals interested in creating a highly customized site.
* What does SRE-http cost.
$0.00. You may freely distribute SRE-http, and you may dissect, subsect,
and otherwise utilize its source code. Please be aware of the standard
"use at own risk" disclaimer, and the fact that SRE-http is in NO way
an official or unofficial product of the U.S government.
* Where can I get SRE-http
The latest version of SRE-http (it's constantly being updated) can be
found at http://www.srehttp.org/. SRE-http is also
available from a number of file repositories: the latest version
will always be on hobbes (http://hobbes.nmsu.edu/ -- search for SREHTTP)
**** Installing SRE-http
* I downloaded SREV13F.ZIP, how do I install it?
i) Create a temporary directory somewhere on your hard drive,
ii) Copy SREV13F.ZIP to this temporary directory
iii) Using UNZIP, unzip SREV13F.ZIP
iv) Read the READ.ME file
v) Run the INSTALL program (type INSTALL from an OS/2 prompt)
By the way: SRE-http ver 1.3h is designed to work with GoServe 2.52 (and
above). Earlier versions (2.45 to 2.50) of GoServe will work,
but several http/1.1 features can not be supported with versions
of GoServe prior to 2.52.
* SRE-http won't start -- what should I do?
* Are you using GoServe 2.52? If not, you'll need to download it
(from http://www2.hursley.ibm.com/goserve)
* You must set the Options-Limit-Connection_maintain to some positive
number (say, 15).
* Is the GoServe working directory pointing to the directory you
installed SRE-http into?
* Is the GoServe data directory (Options-Datadir) 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 GoServe. PMPRINTF opens a small window into which
GoServe/SRE-http 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).
Advanced Users Note:
If you are willing to sacrfice full compliance with http/1.1, you
can force SRE-http to ignore some of these prerequisites by
setting the CHECK_COMPLIANCE parameter in SREFMON.CMD.
* Can SRE-http run under Object REXX?
SRE-http was designed to run under "classic" REXX (technically, REXXSAA).
Unfortunately, for several reasons, the current version of SRE-http
(ver 1.3h) will NOT run object REXX.
If you really want to use SRE-http and Object Rexx, you might
be interested in obtaining ver 1.2g of SRE-http, and some
special modifications of ver 1.2g. However, besides lacking
many features of the current version, experience has shown that
this combination (modified 1.2g and Object Rexx) is not very stable.
For details, see the "are you using OBJECT REXX" link on the
SRE-http home page.
Author's note: If there is real interest in using SRE-http in an
Object REXX environment, I might be persuadable ...
* The response time is very slow ...
For unknown reasons, on some Warp 4.0 machines running version 4.0 of TCP/IP,
SRE-http 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 SRE-http?
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 SRE-http's
installation defaults, you can just point your web browser at:
http://your.browser.wherever/configur.htm
You will then be given the choice between a "simple-mode",
"intermediate mode", and "expert mode" configurator. New users
will probably like the "simple mode" best.
Both the simple and intermediate modes make heavy use of HTML
FORMS. The simple mode has a "one, well-documented, form
per parameter" philosophy. The intermediate mode has a
"one, not-so-well-documented, form for a large set of parameters"
The advantage of the simple mode is ease of use. The disadvantage
is that it does not give you access to some of the more obscure
SRE-http parameters.
Hint: If SRE-http denies you access to the configurator, you should
check the OWNERS variable (in INITFILT.80) to make sure it's
that same as your browser's IP address. Or, use the
username/password that the INSTALL procedure asked you to
supply (or did you skip that part)?
* Can I edit SRE-http's configuration files?
For those who like to make their changes quickly, you may want
to directly edit the SRE-http 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 most important configuration files are:
INITFILT.80, INIT_STA.80, ATTRIBS.CFG, ALIASES.IN, ACCESS.IN,
VIRTUAL.IN, PUBURLS.IN, and USERS.in
All of these files are installed to the CFGS\ subdirectory of your
GoServe "working" directory (the directory you installed SREFILTR.80 to).
If you plan on editing INITFILT.80 or INIT_STA.80, you should read INITFILT.DOC
first. ATTRIBS.CFG and the various .IN files are described in
IN_FILES.DOC.
*** Some more specific questions:
* How can I control access to my site?
SRE-http contains three levels of access controls:
*) LOGON controls: a "can you get into our site" control.
*) Directory specific: directory specific controls using HTACCESS files.
*) Resource specifc: "SEL-specific" access controls contained in
ACCESS.IN and ATTRIBS.CFG.
Logon controls pertain to all requests. You can tell SRE-http
to check none, some, or all requests for username/password authorization
(using the BASIC authorization scheme).
For details on "logon controls", see the description of the CHECKLOG,
OWNERS, INHOUSEIPS, and UNALLOWEDIPS variables in INITFILT.DOC.
Or, check out the appropriate sections in the "simple mode" configurator.
Of greater interest are the "directory specific" and "SEL-specific"
access control methods. The HTACCESS method (using code graciously
provided by Don Meyer) uses special "HTACCESS" files located in the
directory (and in the parent directories) of the requested file.
This (or these) HTACCESS files contain information on who has access
rights to files in the directory (and in child directories).
In contrast, "SEL-specific" access controls compare the request selector
against a list of "selectors". This list (which may contain wildcarded
entries) dictates who can access these selectors. Note that, in contrast
to HTACCESS files, there is one globally maintained list, rather then
seperate "HTACCESS file" per directory.
Note that we use the term "SEL-specific" to mean "Selector-specific",
where the "selector" is the slightly-modified middle portion of
the client's request string.
For example, 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 selector of
dir1/redsox.htm
In other words, SEL-specific access controls are
sensitive to how you code links in your HTML documents.
The choice of method is a matter of taste and convenience -- controlling
directories is a sure way to prevent access to files, but controlling
selectors is more flexible. In fact, these two methods (SEL-specific and
directory-specific) can be used jointly, which implies multiple checks. But
be careful when using both methods, it is possible to get stuck in
authorization loops!
Since "SEL-specific" controls are native to SRE-http, they will tend
to be faster. Therefore, our recommendation is to use the SEL-specific
method.
Lastly, to allow unhindered access to selected clients, or to a subset of
your site, you can use INHOUSEIPS. (in INITFILT.80) or the PUBURLS.IN
file.
* You can circumvent access controls for selected server resources by
by using "PUBLIC_URLS" (in PUBURLS.IN(. When the client's
"request selector" matches a PUBLIC_URLS, access controls are not
attempted.
* INHOUSEIPS. parameters are similar to the IDENT method of
authorization (but INHOUSEIPS. does not obtain or use
username@ information). Basically, if a client's IP address
matches one of a set of "INHOUSEIPS", she is given access
to the site (though she may still need resource/directory specific
privileges). Note that these INHOUSEIPS entries may contain wildcard
characters.
* By the way, the simple mode configurator can be used to create,
and INHOUSEIPS. parameters. For information on how to specify
PUBLIC_URLS, see PUBLURLS.DOC.
* How can I use selector specific access controls to
control access to a directory?
Since "SEL-specific" can refer to "a set of resources on your server"
(via the use of the * wildcard), and since selectors typically point
to directories, "SEL-specific" controls are easily used to control
access to files in a subdirectory.
A simple example follows:
1) Place an entry in ACCESS.IN of the form
Relative_DIR_NAME/* A_Privilege
For example:
ROCKETS/* ROCKETEERS
(...to access selectors beginning with ROCKETS/, the client
must have a ROCKETEERS priviliege).
2) Place an entry in the USERS_FILE (e.g.; USERS.IN) of the form:
username password privilege_list
For example:
OBRIEN JORDIX2 ROCKETEERS
(.. User OBRIEN, with password JORDIX2, has a ROCKETEERS privilege).
3) Set ALLOW_ACCESS="NO" (in INITFILT.80)
(... SRE-http will check privileges for all requests).
4) you might want to add a
* *
entry to the ACCESS.IN file to signal "all other
files/directories are open access".
Summarizing this example:
When the client asks for anything in (or under) the ROCKETS subdirectory
(of your GoServe data directory), SRE-http will challenge the user
for a username and password. If the client enters a username
with the correct privileges (such as OBRIEN), he will be allowed entry.
Notes:
* If CHECKLOG='ALWAYS', SRE-http will only "re-challenge"
the client if his initial logon privileges did NOT contain a
matching privilege.
* The simple mode SRE-http configurator can be used to add
(and remove) both SEL-specific access controls and
username/password entries.
* You can also use ATTRIBS.CFG to define "realms", with a realm defined
as a set of selectors. One can then assign "required privileges"
to each of these realm.
* What are "client privileges" and "resource privileges" ?
SRE-http 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". In fact, one could simply
define the client's username as a (or as the only) privilege
(the ADD_USER_NAME variable is used for just that purpose!).
The point is that by allowing multiple privileges per username,
a given client can be placed in many different groups of users.
"Resource privileges", contained in SEL-specific access
control entries (in ACCESS.IN) or in "realm definitions" (in ATTRIBS.CFG)
refers to these "client privileges". Resource privlieges can be thought
of as a list of "groups of users". In the extreme case of each username
having a single privilege (equal to her username), the "resource
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 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.
In comparison to the HTACCESS method:
* The PASSWD.LST file is akin to SRE-http's USERS.IN file
(albeit one that's directory specific); but with each entry
(in PASSWD.LST) assigned just an "own name" client privilege.
* The GROUPS.LST file is akin to a privilege, with each entry
in GROUPS.LST dictating which users have the "groupname" privilege.
* What's the difference between realms and privileges?
SRE-http's SEL-specific access control method is based on the notion of
"privileges". Basically, a "client's privileges" are compared to a
"resource's privileges", and if they match (as discussed above), access is granted.
Resource privileges can be assigned directly to selectors using
ACCESS.IN. Alternatively, resource priviliges can be defined to a "realm",
using the ATTRIBS.CFG.
The "define realms" method corresponds to how most browsers use
"realms". 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.
The basic point is that the notion of "realms" is part of the http mindset,
and SRE-http supports this notion via the ATTRIBS.CFG file. In particular,
ATTRIBS.CFG defines a realm using "selector matching" rules; one can
have several (possibly wildcarded) rules defining a given realm.
Note the key point -- realms are defined as collections of selectors --
a collection that span your hard drives in complicated ways.
And though use of ATTRIBS.CFG file is now recommended, advanced users may
find it easier to use ACCESS.IN to carefully specify access controls on
a per selector basis.
Advanced users note:
In ACCESS.IN, you can define "SEL-specific realms" (see IN_FILES.DOC for
details). This is a semi-obsolete feature which is NOT THE SAME as the
realms defined in ATTRIBS.CFG.
* 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 simple- mode configurator to add a set of users.
For each user, you provide a username, password, and a
list of client privileges.
2) Use the simple-mode configurator to create "SEL-specific"
access-control entries. For each entry you'll specify the request
string (perhaps ending with a *), a list of resource
privileges, and an (optional) realm. In most cases, you'll only
need to define one "resource privilege" per selector; and you
can even use this one resource privilege as the realm name (see
the description, in INITFILT.DOC, of REALM_1ST_PRIV for details).
That's all you have to do -- user's with a "client privilege" that
matches ANY ONE of a "selector's" resource privileges will be granted
access rights to it. If they haven't entered a username/password
before hitting a protected server resource, the (optional) realm (or,
the 1st resource privilege), will be displayed on their browser's
authorization screen.
* How can I limit the capabilities of different users
of my server?
The use of "SEL-specific" permissions allows one to control what
capabilities of the server are avaiable to different users.
Of particular interest are the following permissions:
NO_SSI : All server-side includes will be suppressed
NO_SSP : All server side processing will be suppressed
NO_CODE: INTERPRET CODE and SELECT keyphrases will be
suppressed (these are "in-document" executable
statements).
Note that these permissions are applied on a "SEL-specific" basis (using
ACCESS.IN) or on a "sub-realm" basis (using ATTRIBS.CFG).
Thus, a given client may have "server side include" privileges
on some parts of your web-site, but not on other parts.
* How can I prevent other web sites from using
images stored on our server?
If other sites are using your server to "store" files, such as interesting
.GIFs for use as in-line images, you may find this annoying. For example,
you may maintain a publicly accessbile clip-art collection, which you
are happy to give away. However, you don't want lazy websters to
use inline images that point to the files on your server.
To preclude such sneaky tricks, you should use the "additional privileges"
facility of SRE-http. Basically, you issue a short-term
client privilege to all clients who "visit" your site (say, who
loads up the welcome screen for your clip-art collection).
This short-term client privilege is then required for all
requests for the actual clip-art files. Thus, a request coming out of
the blue (with no prior request for the "welcome" screen) will NOT
be assigned the short-term privileges, and access will be denied.
The following outlines what you need to implement the above:
*) Assume you have a /CLIPART directory, with lots of .GIF files in it.
**) Assume that your "welcome to clipart" page is called
/CLIPART/HELLO.HTM
1) Set SRE-http's variables:
CHECK_ADD_PRIVS='YES'
ALLOW_ACCESS='NO'
ACCESS_FAIL_FILE=1
(you will have to hand-edit INITFILT.80 to change CHECK_ADD_PRIVS
and ACCESS_FAIL_FILE. Note that any non-0 value of ACCESS_FAIL_FILE
will do)
2 Add the following entries to your ACCESS.IN file
/CLIPART/HELLO.HTM *
/CLIPART/*.GIF !GETCLIP , , , -1
(the -1 signals "do NOT ask for authorization in event of failure")
3) Add the following line to /CLIPART/HELLO.HTM
<!-- INTERPRET FILE ADDPRIVS.RXX GETCLIP , 30 -->
That's it! You might want to add a * * line to ACCESS.IN (assuming
your site is otherwise open access).
For further discussion of "dynamic privileges", see ADDPRIVS.DOC
* What are the server side include capabilities
of SRE-http?
A major advantage of SRE-http 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.
SRE-http supports two classes of server side includes, instances of
which can be freely intermingled in your documents:
i) The SRE-http syntax.
The SRE-http 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 SRE-http. It overlaps
largely with the SRE_Filter syntax, with a few extra file-information
and time/date display features, and a CGI execution capacity.
More importantly, it's something of a standard.
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, SRE-http 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".
SRE-http 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"). If you are still curious, SSICACHE.HTM contains a more detailed
discussion.
* Can I use cookies with GoServe and SRE-http?
The short answer is YES -- the 'HEADER ' GoServe "return code",
and the REQFIELD() function can be used to read and write cookies.
SRE-http offers a few conveniences when processing cookies:
*) The INTERPRET "keyphrase" of SRE-http provides a convenient
means of reading and creating cookies; and of changing
the contents of document based the values of the cookies.
*) SREF_GET_COOKIE, a "macrospace" procedure provided with SRE-http,
facilitates "cookie extraction".
Notes:
* A good description of cookies can be found at:
http://home.netscape.com/newsref/std/cookie_spec.html
* A short example of how SRE-http works with cookies can be found
in SAMPCOOK.SHT and SAMPCOOK.RXX
* I am having trouble with uploads, what should I do?
SRE-http's implementation of "file uploads" requires
the use of an HTML document that contains a special type
of FORM. This should be constructed as:
<FORM enctype="multipart/form-data" ACTION="/put_file" METHOD="post">
Some stuff here:
<INPUT TYPE="file" name="userfile" value="filename.ext">
More stuff
</FORM>
For an example of such a document, you can look at the
"PUT_FILE" portion of the UPLOAD.HTM file that comes with SRE-http.
In addition, an HTML 3.x aware browser (netscape 2.01 and above),
that knows how to properly deal with such FORMs, has to upload this
document.
But before you start, you should check the following variables in
your INITFILT.80 file (or you can use SRE-http intermediate mode
configurator).
UPLOAD_DIR :Change this to your desired "upload directory:
Example: UPLOAD_DIR = 'g:\GOSERV\upload '
These next are automatically set upon installation, and are probably
okay; but you might want to check them just for fun.
UPLOAD_MINFREE : Minimum space (in Kbytes) that must exist on
your disk after upload
Example: UPLOAD_MINFREE= 20000
UPLOAD_MAXSIZE : Maximum size of file upload (in Kbytes)
Example: UPLOAD_MAXSIZE=1000
UPLOAD_LOG : Location of a "log" file, a short note on
recieved uploads are written here.
Example:UPLOAD_LOG = 'g:\GOSERV\UPLOAD\UPLOAD.LOG '
With these setting in place, with your HTML document ready to rock
(again, see UPLOAD.HTM for an example), and with your client running
NetScape 2.01; everything should be ready to go!?
That is, when the client requests this form, Netscape gives
her a file-browse box. When the form is submitted, Netscape
appends the file, and SRE-http writes it to a file name
Note that some installations have intermittent problems with
uploads. The latest fix packs (FP5 and above for Warp 4.0) seem
to help a lot, as does use of GoServe 2.52.
You may also want to change the limit on body size (say, to 1M if
you might get large uploads).
!!!! Reviewing: !!!!!
1) Check your INITFILT.80 settings (especially the UPLOAD_DIR parameter)
2) Create an HTML document with a special FORM element
(see UPLOAD.HTM for an example)
3) You might need to change some Goserve settings
4) Request your html document with netscape 2.01 (other browsers
might work. .. but WebEx 1.1d does NOT understand this type of FORM
element)
By the way, UPLOAD.HTM contains a discussion on how to specify the
filename that SRE-http should use when saving the file.
You may also want to look at SREHTTP.HTM for further discussion of
the PUT_FILE facility of SRE-http.
* What about default documents?
SRE-http recognizes two types of "default documents" -- those for
"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 DEFAULT='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 GoServe 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". In order
to find this "default document", the AUTO_NAME variable is used.
For example, if AUTO_NAME='INDEX.HTML *.HTM ', then SRE-http
would first look for MULE/INDEX.HTML, and then look for MULE/MULE.HTM.
Note: depending on the value of the NOEXT_TYPE variable,
a request for http://foo.bar.net/mule could also
be interpreted as a "request for the default document
in the MULE subdirectory"
Consider the following examples:
http://foo.bar.net -- empty request; uses the DEFAULT
http://foo.bar.net/ -- empty requests, use the DEFAULT
http://foo.bar.net/index -- depends on the value of NOEXT_TYPE.
By default, SRE-http assumes this is a request to the "INDEX"
subdirectory, and will try to use look for the AUTO_NAME files
in this INDEX subdirectory. In the likely event that there
is no INDEX subdirectory, a "could not find resource" error
message will be returned to the client.
http://foo.bar.net/index. --- Looks for INDEX.; which probably does not
exist. If it does exist, given the empty extension, SRE-http will
transfer it as a "text/plain" file (you can change this by
modifying MEDIATYP.RXX).
http://foo.bar.net/index.htm -- Looks for INDEX.HTM
http://foo.bar.net/index.html -- Looks for INDEX.HTML
Now let's consider the behavior of the REPLACE HITS server side include.
Because REPLACE HITS records on a "selector specific basis", and because
it's sort of difficult to indicate an "empty selector", SRE-http records
"empty requests" using a listing of --DEFAULT--. Let's suppose that
DEFAULT='INDEX.HTM'. Now consider an request to INDEX.HTM -- it would be
recorded under a listing of INDEX.HTM. Thus, you would need to add up
the INDEX.HTM and -DEFAULT- entries to find the true total number of
requests that yielded INDEX.HTM.
If this is a disagreeable notion, you might want to use REPLACE HITS_FILE
-- it stores entries by fully-qualified file name; in the above example,
empty requests would be stored under D:\WWW\INDEX.HTM (assuming that D:\WWW
is your GoServe default data directory).
* What are SRE-http's virtual directories?
By default, SRE-http will match a request selector to a file in the
"GoServe data directory". While a good security feature (files not in or
under the GoServe data directory are inaccessible), this can be an
inconvenience.
To remedy this inconvenience, one can define "virtual directories"
Basically, SRE-http 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 -- SRE-http will attempt to retrieve the file
from the remote server, without using a redirection!
For details on the use of the virtual directories, see the
description of VIRTUAL.IN in IN_FILES.DOC, or see the
desciption of the REDIRECT: DIR action in the DEFREALM section
of IN_FILES.DOC.
Or, you can use the configurator!
Note: Compared to Don Meyer's GOHTTP filter:
* GOHTTP's use of "aliases" corresponds to SRE-http's use of
"virtual directories",
* GOHTTP's use of "redirection" (via the REDIRECT.LST files)
corresponds to SRE-http's use of "aliases".
An example of the use of virtual directories:
i) Assume that the Goserve 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 entries should be included in VIRTUAL.IN
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 SRE-http is the variety of redirection
mechanisms it offers, where redirection implies "sending the client
a file that is not a direct mapping of the request selector. Redirection
has two general classes: remote and local.
"Remote" redirection, which is what most of the literature simply
calls redirection, involves telling the client's browser that
"the url you have 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.
To do remote redirection, you need to add an entry to the list of aliases
contained in ALIASES.IN, either by editing with your
favorite text editor, or by using the configurator. Or, you can include
a REDIRECT: MOVED action in ATTRIBS.CFG.
For example, an entry (in the alias-file) of
whatgot http://www.mine.org/dir1/index1.htm
would cause the server to send back a "302" response to the client's
browser whenever a request for "whatgot" arrives. This 302 response,
would instruct the client's browser to automatically request
http://www.mine.org/dir1/index1.htm.
The above could be accomplished with an entry in ATTRIBS.CFG; such as:
Realm: redir1
rule: whatgot
redirect: moved= http://www.mine.org/dir1/index1.htm
"Local" redirection is handled solely by SRE-http, and involves
directly modifying the "request selector."
SRE-http has a number of methods of specifying "local redirection",
such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the
use of entries (in ALIASES.IN) of the form:
whatgot dir1/index.htm.
Local redirections actually involve textual substitution (after SRE-http
has recieved the request). Among other advantages, this gives you quite a
bit of control over how "SRE-http facilities, and external procedures"
percieve the request.
Note that the above could be accomplished with an entry in ATTRIBS.CFG;
such as:
Realm: redir2
rule: whatgot
redirect: internal = dir1/index1.htm
Notes:
* A CAUTION on local redirection and partial urls:
When using aliases for "local redirection", partial URL resolution by
the client's browser may have unexpected consequences. See the
discussion of "local vs remote redirection" in INITFILT.DOC for details!
* On Using HTACCESS files for redirection:
In addition to the use of the ALIASES.IN, the REDIRECTFILE parameter
of HTACCESS files can be used for "directory specific" redirections
(see the description of the HTACCESS_FILE variable, in INITFILT.DOC,
for more details).
* Compared to Don Meyer's GOHTTP filter:
* GOHTTP's use of "aliases" corresponds to SRE-http's use of
"virtual directories",
* GOHTTP's use of "redirection" (via the REDIRECT.LST files)
corresponds to SRE-http's use of "aliases".
* Can I customize SRE-http responses.
In a number of circumstances, SRE-http 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, SRE-http 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 (for details,
see the descriptions in INITFILT.DOC):
No file found:
The NOT_FOUND_URL parameter can be assigned a
short string, which will be displayed in the middle of a
generic message. Alternatively, you specify a special
"not found" response file (typically, an HTML document
that you create)
Logon denied:
SRE-http 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 LOGON_FAIL_FILE.
Access to a server resource denied:
If a request is denied due to insufficient "SEL-specific" privileges,
SRE-http can either reprompt the client for a different username,
or it can send her a custome written response file. This default
name of this file is set with the ACCESS_FAIL_FILE parameter.
In addition, you can specify "SEL-specific accesss failure response
files" -- see the descriptions of the ACCESS_FILE (in SREHTTP.HTM,
or in the sample IN_FILES.DOC) for details on this advanced
option.
! And if you want to really get fancy, you can use the CUSTOMIZ addon
to customize, on a client specific basis, the appearance of your pages !
* How does SRE-http deal with multiple
"wildcard" matches.
When SRE-http attempts to match a selector to an "alias", "virtual
directory", or "access control entry", it is possible that several entries
will be "wildcard" matches. Depending on the action, several different
rules are used (in all cases, if an exact match exists, it's always used):
*VIRTUAL Directories: The longest "abbreviation match" is used:
Example: If the selector is FOOD/FRUIT/ORANGES.HTM
and VIRTUAL.IN contains:
/FOOD D:\SNACKS\*
/FOOD/FRUIT E:\HEALTHY*
then the /FOOD/FRUIT entry will be used (since both match, but
/FOOD/FRUIT is longer then /FOOD
*ACCESS control, PUBLIC_URLS, and ALIASES: 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.
That is, if more then one of these entries appears in ACCESS.IN,
then the one earlier in the list is used.
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).
Furthermore, ACCESS, PUBLIC_URLS, and ALIAS matching suport "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
* ATTRIBS.CFG: Same as above 2.
Depending on the "action", either an "abbreviation match" or a
"wildcard match" is attempted.
* RECORDALL, and others
A "single wildcard" algorithim is used (you can NOT include more
then one * character). Using the above example, the following
entries are used (with earlier ones have precedence).
FOOD/FRUIT/*
FOOD/*.HTM (more characters after the *)
FOOD/*
(these 4 entries can appear in any order in this file, with no
effect on precedence).
For further details, see the various "sample" configuration files shipped
with SRE-http.
* How can I send a "thank you" note after
a browser is finished downloading a file?
In Nestcape (and probably MSIE) a response header of the form:
refresh: 4 ; url=/adir/afile.ext
will cause the cleint's browser to obtain /adir/afile.ext 4 seconds after
the current file (or other resource) has been obtained -- and this works for
any content-type (html documents, gifs, .zip files, etc.).
So, how one can instruct SRE-http to include such a response header?
Answer: It's easy -- use the Advanced-options!
Basically:
1) in ACCESS.IN; specify an "advanced options" file for the selector(s)
for which you wish some kind of "thank you" note to be sent.
Note: You can use the intermediate configurator to add these "advanced
options files" to "selector specific" entries in ACCESS.IN.
2) Create these "advanced options" files (as specified in the ACCESS.IN)
-- they should be in or under the SRE-http data directory
(i.e.; \goserve\data)..
3) Include in the advanced options files entries of the form:
HEADER ADD Refresh: 5 ; url=/adir/afile.ext
where the 5 can be any time (in seconds) to pause, and
/adir/afile.ext is a selector for netscape to grab after this pause.
Actually, the advanced options file can contain just this entry; no
other entries need appear (for further details, see ADV_OPTS.DOC).
You can also use "pre-send" documents -- say,an html document that states
"you asked for x, wait a minute and I'll give it to you". To do this:
1) create a link to a "pre-send" html document
2) include, in this "pre-send" document, a line in the section of
the form:
<meta HTTP-EQUIV="Refresh" Content="9 ; URL=/adir/afile.ext" >
where 9 is the pause, and /adir/afile.ext is the file to be downloaded.
You can even combine a "pre-send" and "thank you" notes by appropriately
defining (in ACCESS.IN) an advanced-options file for /adir/afile.ext.
* How can I record the number of hits I get?
SRE-http provides a wide variety of tools for recording the number
of hits you recieve. These include:
1) The RECORD_ALL_FILE. The RECORD_ALL_FILE is used to record
the number of times ALL of your files are requested (on a
file-by-file basis). It does NOT record individual requests, nor
does it place a "number of hits" line into a requested document.
The RECORD_OPTION parameter of SRE-http is used to
turn this option on or off.
2) The COUNTER_FILE is used to record, and display, total hits
for explicit files. The COUNTER_FILE is accessed by the
REPLACE HITS SRE-http "server side include"
keyphrase (there are several variants of this keyphrase).
3) The SENDFILE_FILE is used to record files that are
transfered with SRE-http's SENDFILE facility.
4) COUNTER.RXX is used to track hits requests on a file-specific
basis, and can record individual requests (as well as
total requests). COUNTER.RXX can be invoked as a server
side include (using a INTERPRET COUNTER.RXX xxx
keyphrase), or it can be invoked by SENDFILE.
Lastly, the output of COUNTER.RXX is highly configurable.
5) XCOUNT.CMD is a CGI-BIN script that generates
a simple odometer for specific files (it's meant to be
included as an in-line image).
JCOUNT.CMD is similar, but is called using an
#EXEC xxx style server side include (both of
these are courtesy of Don Meyer).
6) The GOAUDIT.80 file contains tons of stuff, you can use it
(but you'll have to wade through a lot of verbiage).
7) SRE-http supports the common-log audit files, and there are
lots of tools out there for analyzing common-log files.
For details on the above choices, see SREHTTP.HTM, INITFILT.DOC, and
COUNTER.DOC. Power users will probably like COUNTER.RXX the best,
(and when used with SENDFILE, COUNTER.RXX can be used with any type
of file, not just HTML documents).
One last point: A nice feature of the COUNTER_FILE and
RECORD_ALL_FILE is the ability to NOT augment the counter when
repetitive requests (from the same client) are recieved --
check out the descriptions of the HIT_CACHE_LEN, HIT_CACHE_DURATION,
and HIT_OWNER_SUPPRESS variables in INITFILT.DOC
(note that COUNTER.RXX has similar features).
* How can I speed up throughput?
The best way to speed up throughput is to use the SREPROXY
variant of SRE-http. SREPROXY is a "proxy-like" front end
for SRE-http. It can detect "cached" resources, and
respond to them quickly (without needing to check the various
SRE-http aliases, access controls, etc.)
Note that these cached resources do NOT refer to the GoServe cache
but to the http/1.1 style "proxy caches" (that may be cached by any
proxy anywhere on the web). Since SREPROXY is not a http/1.1
(or even http/1.0) proxy, we call it "proxy-like"; but since
it only talks to one server, adherence to spec is not necessary.
Alternatively, if you are running a simple site (non-fancy ssis,
not a lot of scripts, etc); then the SRELITE variant of SRE-http
can be several times faster.
For other speed up hints, see the introduction to INITFILT.DOC
* 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 SRE-http what
Content-type response header to send to the client.
a) defining "file extension" mime types.
By default, SRE-http 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 MEDIATYP.RXX file located in the GoServe directory
... the default version of MEDIATYP.RXX contains detailed
instructions.
Notes:
* The MEDIATYPE_FILE_ALWAYS parameter (described in INITFILT.DOC)
is used to selectively suppress checking of MEDIATYP.RXX.
* The default list of extension-to-mimetype mappings is
contained in the MEDIATYP.SRF file located in SRE-http's
LIB subdirectory. Ambitious webmasters can change
this file (and then recompile using MAKELIB.CMD).
* You can define host-specific entries in MEDIATYP.RXX.
b) defining selector specific mime types.
The ACCESS.IN (or ATTRIBS.CFG) file can be used to define selector
specific mimetypes. In particular, you can can set a MIME "advanced
option"; either by including an Option: Mime entry in ATTRIBS.CFG, or
specifying a selector-specific advanced options that contains
a Option: Mime entry.
For the details, see ADV_OPTS.DOC.
Notes:
* you can modify ACCESS.IN and ATTRIBS.CFG using SRE-http's intermediate
configurator.
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 SRE-http 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:
View our latest FOOBAR instructions?
or
see the foobar.htm source code?
For details on the use of this "special prefix", see SREHTTP.HTM.
Note:
* You may also wish to define a subset of text/html resources to be "server
side include capable". To do this, you need to set the SSI_SHTML_ONLY
variable to 'YES', and edit the SSI_EXTENSIONS variable (located in
INIT_STA.80).
* Methods b and c will override both the default mimetype assignation
(as specified in MEDIATYP.SRF), and the MEDIATYP.RXX "extension-to-
mimetype" assignment of mimetype.
* Method c overrides b. Thus, using a !SENDAS_type_subtype is the ultimate
means of dictating what the Content-type response header will be (assuming
you aren't invoking a server-side script).
* How can I prevent NetScape from reloading files
too frequently?
Certain browsers (NetScape 2.x seems to be the most stringent about this)
are quite serious about reloading "expired" documents WHENEVER you
refresh them. That is, not only will such documents be loaded afresh
upon the first request of a session, but even if you "back button" to
it, Netscape will reload it!
There are many cases where SRE-http (actually, GoServe by default) will
return a document with an "immediate expire" (i.e.; documents
with server side includes, and results of CGI-bin scripts). Hence,
this "feature" of NetScape can be quite annoying.
To alleviate this annoyance, you can set the FIX_EXPIRE variable to
a "time delay". When this time delay is greater then 0, the
expiration date will be augmented (correctly accounting for
new-dates and GMT). This eliminates the over zealous refresh
activity of NetScape, but retains the "don't keep this
temporary file around forever" notion.
Further details are contained in the description of the FIX_EXPIRE
variable in INITFILT.DOC.
* What are the SRE-http addons?
As an alternative to the CGI-BIN script interface, one can
write REXX routines that are called directly by SRE-http,
without the somewhat convoluted use of environment strings
that CGI-BIN scripts depend on.
Currently, there are several addons available for SRE-http.
A few of these addons are:
FORUM: A "news-group and list-server" discussion-group package
BBS: A full featured "web based bulletin board system"
GETAFILE: A directory displayer, with user-settable display features
GOSWISH: A front-end (and more) to the freeware SWISH search engine.
These addons can be obtained from the SRE-http home page at
http://www.srehttp.org/apps/
You can also run PERL scripts as SRE-http addons -- for the details,
see SRE-http's PERL.DOC file.
* How is SRE-http multithreaded.
Both GoServe and SRE-http are multi-threaded. GoServe uses 3 threads for its
own internal workings, and then allocates a temporary thread to each request.
That is, when a request arrives, GoServe will launch SRE-http in its
own thread. After SRE-http has responded to the request, it exits and
the thread dies.
In addition to these GoServe threads and the temporary threads, SRE-http
launches a number of "daemons" in their own non-temporary threads;
which will be active until GoServe is stopped.
These SRE-http daemons are used for number of operations. The primary uses
are to retain SRE-http configuration information in a readily accessed
format. For example, the username database, the list of virtual
directories, and the access control entries are all attended to be a
daemon. When SRE-http needs this information, it "asks the daemon";
thereby avoiding the hassle involved with reading the raw configuation
files. In addition, daemons are used for non-time sensitive tasks.
These include "logging", PMPRINTF display, and various post-filter operations.
The following lists the thread identifications that typically will occur
(on some very slow or very fast machines, this ordering may be different).
You can use a system monitor, such as WATCHCAT, to observe the status of
these threads.
1 to 3 : GoServe threads.
4 : The first temporary, request specific thread
5 : The SRE-http monitor (it launches/maintains the daemons)
6 : The front end to PMPRINTF
7 : The variable storage thread
8 : The access control thread
9 : The alias resolution thread
10 : The public-urls thread.
11 : The username thread
12 : The virtual directory thread
13 : The SSI-cache thread
14 : The postfilter thread
15 : SREPROXY: "proxy cache" thread
Other threads are used for :
* additional temporary, request specific threads.
* other daemons (such as the SRE-Data daemons)
-----------------------------------------------------------
--- End of document.
To top of document