Abstract | SRE2002 is an Internet server for OS/2. More precisely, SRE2002 provides a set of functions and capabilties that allow you to implement a web server through a "filter" program that is written in REXX. In addition to a fairly simple filter included with SRE2002, several filter programs are publically available (such as sreLite2 and SREhttp/2) - or you can write your own! |
---|
SRE2002 is designed for small to intermediate sized sites. It's primary strengths are flexibility and ease of customization. Speed, resource use, security, and scalability are not the primary goals. That said, these are operational concerns; and quite a bit can be done to enhance performance along any of these dimensions.
In many ways, SRE2002 is an outgrowth of GoServe, which was designed and created by Mike Cowlishaw. In fact, it is the end of support for GoServe that motivated the creation of SRE2002. In comparison with GoServe, the primary advantage of SRE2002 is increased support for http/1.1 functions, including a greatly improved cache. Just as important, SRE2002 can be readily modified (it's written in REXX) -- we are always interested in suggestions and ideas! Are you are upgrading from GoServe/SRE-http? You can find a number of hints and suggestions in UPGRADER.TXT.
Of course, there is a disclaimer ..
Before choosing & using SRE2002, you must read the disclaimer (in appendix 1). Basically, SRE2002 is gnu style freeware; and is to be used at your own risk. We do try to create a fairly secure product, and we try to quickly fix any problems (or potential problems). However, we can NOT guarantee that SRE2002 has no security holes or is free from other potentials for failure.
More help can be found in ...
- SRE2PRC.HTM contains detailed descriptions of SRE2002 functions.
- SREAPI.TXT contains further details on working with SRE2002
- SRE_DMN.TXT discusses how you to user SRE's functions that create and manipulate daemons, flags, and queues.
- SRE_TASK.HTM discusses SRE2002's built in task manager.
- SRE_DCSH.TXT discusses SRE2002's built in database facility.
- IM_USE.HTM discusses how to use and create SRE2002 Instance Manipulation modules .
Before starting... | if you are less familiar with the http/1.1 protocol, or are new to http servers, you may want to first review some basic terminology. |
To use a different port, all you need to change is the PORT parameter in SRE2002.CFG.
Esc | Shutdown SRE2002 After hitting Esc, it may take a few seconds to shutdown. In some cases, hitting Ctrl-C may be faster. However, it's cleaner to shut down using ESC (various resources will be properly freed up). |
R | Refresh the screen. This is useful if error messages, or other unusual conditions (such as your filter using SAY) causes information to be written to the screen in an uncontrolled fashion. |
M | Modify parameters. This will let you modify the dynamically-modifiable parameters. You can suppress this option by setting the NO_MODIFY_ONTHEFLY option. |
S | Snipe(kill) connections. Use this to list, and selectively close, currently active connections. When in snipe mode, no more connections will be accepted (though currently open connections will continue to be active). |
SREWATCH will start SRE2002, and will monitor its status. If SRE Watch detects that SRE2002 has crashed (or is otherwise hopelessly hung), it will attempt to kill, and then restart, SRE2002. In fact, you can even tell SRE Watch to reboot the machine when things get bad enough.
To run SRE Watch, run the SREWATCH.CMD program (located in the SRE2002 working directory) instead of SRE2002.CMD. You might need to set a few parameters (in SREWATCH.CMD) before the first time you run it, but most people can use it as delivered.
For example: run SREWATCH.CMD from your STARTUP.CMD file, and enable the SRE Watch "reboot if necessary" option,
SRE2002.CFG is a text file that you can modify using any text editor (such
as EPM). You can also modify SRE2002 by entering, from an OS/2 prompt:
SRE2002 -m
You will be presented, in a sequential fashion, with a list of the most
important SRE2002 parameters, and their current values. You can change, or
retain these values; you can also dislay some rudimentary on-line help.
Alternatively, if you enter
SRE2002 -mall
you will be presented with a list of all the parameters contained in
SRE2002.CFG, many of which you'll never need to change.
Note that several SRE2002 filters (such as sreLite2 and SREhttp/2) come with configuration utilties that provide an on-line method of modifying SRE2002.CFG (the server parameters file), HOSTINFO.CFG (the host definition file), and BADIPS.IN (the unallowed IP addresses file).
AUDITFILE | File containing audit and status information |
AUDIT_ITEMS | Specifies what is written to the AUDITFILE |
AUDIT_DELAY | Time span (in minutes) to wait before writing to audit file |
DATADIR | The default "data" directory (your site's root directory) |
DEFAULT_HOSTS | A list of hosts that this server recognizes (complements HOSTINFO.CFG) |
DEFAULT_SOCKET_TIMEOUT | Time to wait on a socket, in seconds |
ENTITY_HEADERS_IGNORE | Entity-headers to ignore when creating auto-etags. |
ERRORFILE | Name of the error log file. |
EXIT_PROC | File (or files) containing custom exit procedures, or 0 |
FILTER | Name of the filter program |
FILTER_VERSION | Descriptive name of the filter program |
FAST_FILTER | Name of "fast-filter" program |
IM_TYPES | Identify Instance Manipulation module |
IM_DEFAULT | The default instance manipulation module |
INIT_PROC | File (or files) containing initialization procedures, or 0 |
LIMITBODY | Maximum size of request body (in Kbytes) |
LIMITCLIENTS | Maximum simultaneous connections |
LIMITHEADER | Maximum size of request headers (in Kbytes) |
LIMITTIMETOTAL | Maximum time allowed per request (in seconds) |
LIMITTIMEWAIT | Maximum time to wait on a maintained connection |
LIMITTIMEINACTIVE | Maximum intra-request idle time (in seconds) |
MAXCOUNTERS | Maximum number of "counter" variables |
MAXCLIENTNAMES | Size (number of entries) in "client name" cache |
MAXSTATVALS | Size (number of entries) to use to compute statistics |
MAXMD5S | Size (number of entries) in MD5 cache |
NO_MODIFY_ONTHEFLY | Suppress on-the-fly modification of parameters |
NO_TASKS | Disable the task manager |
PORT | Port the server is running on |
PRE_REQUEST | File (or files) containing pre-request procedures, or 0 |
PRE_TRANSACTION | File (or files) containing pre-transaction procedures, or 0 |
REQ_CACHE_CALL_ANYWAYS | Call the filter even if request cache is used |
REQ_CACHE_ENABLE | Enable the request cache |
REQ_CACHE_HITFILE | File containing record of cache hits |
REQ_CACHE_RECORD | Record cache hits to the cache_hitfile |
REQ_CACHE_SIZE | Size of "request cache" |
REQ_CACHE_VERIFY | Enable http/1.1 style verification prior to use of cache |
SECURITY_LEVEL | A value that is used by some filters to control who can remotely modify server parameters |
SERVERADDR_USE | IP address to report |
SERVERANAME_USE | Domain name to report |
SERVER_SOFTWARE | Reported name of this server software |
SERVER_SOFTWARE_SHORT | Short reported name of this server software |
STATUS_ITEMS | Specify what to display on status screen |
STATUS_MESSAGE | Short message (displayed on side of status screen) |
TRACKING_ON | Enable SRE2002's "client tracking" facility |
UNALLOWED_FILE | File containing a list of "UnAllowed" IP addresses. |
USER_STATS | List of variables to set up as "statistics" variables |
AUDIT_ITEMS | DATADIR | INIT_PROC |
FILTER | LIMITCLIENTS | PORT |
REQ_CACHE_ENABLE | REQ_CACHE_RECORD | STATUS_ITEMS |
DATADIR | LIMITBODY | LIMITCLIENTS |
LIMITHEADER | LIMITTIMETOTAL | LIMITTIMEWAIT |
LIMITTIMEINACTIVE | SERVER_SOFTWARE | SERVER_SOFTWARE_SHORT |
You can use fractional values. For example:
AUDIT_DELAY=0.25
means "write to audit file every 15 seconds"
Notes:
These options yields the following information.
C : 1A 00:25:07: 131.10.51.21 80 1 15.12.112.3 1104 where: C : -- this is the "client audit item" 1A -- transaction and request number 00:25:07 -- time of connection 31.10.51.21 -- ip address of server 80 -- port of server 15.12.112.3 -- ip address of client 1104 -- port of the client
D : 3A 00:33:50: REQFIELD = If-match If-Unmodified-Since If-None-Match D : 3A 00:33:50: FILE = CHUNK NOWAIT ERASE type text/plain NOCACHE Name G:\SRENEW\TEMP\_17111__.TGZ
D : 3A 00:33:50: Header = HEADER NOAUTO D : 3A 00:33:50: Header = Header Add Date: Sat, 25 Mar 2000 05:33:49 GMT D : 1A 00:25:06: ReqHdr = Referer:do_get@localhost D : 1A 00:25:06: ReqHdr = If-none-match: "dir.d","dir.doc"
Note that you can use the SRE_AUDIT function to write custom messages to the AUDIT file.
Note that the filter does NOT have to use this directory!
Notes:
Furthermore:
If a host is not:
- the canonical host, or
- listed in DEFAULT_HOSTS, or
- defined in HOSTINFO.CFG,
then
- a 400 Bad Request response is returned to the client.
Notes:
Examples. If the host is not the canonical host, and it's not defined in HOSTINFO.CFG...
If DEFAULT_HOSTS is | then the following hosts will be served (using default parameters) |
---|---|
* | All hosts wil be served |
0 | No additional hosts will be served |
foo.bar.net | foo.bar.net will be served. |
foo.bar.* goo.com | goo.com, and any host name that starts with foo.bar., will be served |
Notes:
Basically, the rules for etags are (as defined in RFC2616):
Unfortunately, this can mean that essentially inconsequential changes in entity headers require a new etag (such as changes in file creation dates, or dropping a Content-Length header if chunked transfer encoding is used). The required changes in the etag can diminish the effectiveness of caches and proxy servers, as well as diminish the ability of SRE2002 to use conditional (304) responses to requesst that contain If-None-Match request headers.Since RFC2616 is silent on this issue, SRE2002 uses the ENTITY_HEADERS_IGNORE parameter to select entity-headers to not consider when automatically creating an etag. When you select what to include in this list, you should consider whether it matters that a client may recieve an entity with headers that may not be completely up-to-date, versus the probability that an inconsequential change in an entity-header will unnecessarily suppress caching and conditional responses.
In general, we recommend including the following entity-headers: CONTENT-LENGTH, CONTENT-MD5, EXPIRES, and LAST-MODIFIED.
However, if you have resources subject to unexpected changes in freshness (that is, resources whose expiration times may depend on circumstances), then EXPIRES and LAST-MODIFIED probably should not be included (at the cost of reducing SRE2002's ability to use 304 responses).
Notes:
Examples:
Notes:
parse arg PORT,SERVERNAME,FILTER_DIR
Syntax: IM_TYPES= im_name1 im_file1 , im_name2 im_file2 , ....
where each (case insensitive) im_name1 & im_file1 pair are seperated by a comma:
Example:
Examples:
Notes:
parse arg PORT,SERVERNAME,FILTER_DIR
Example: LIMITBODY=150
Notes:
Note that there are no size restrictions on a single request header -- so long as all request headers (including the request line) are less then LIMITHEADER kbytes.
Example: LIMITHEADER=10
Example: LIMITCLIENTS=15
Example: LIMITTIMETOTAL=160
Notes:
Example: LIMITTIMEWAIT=10
Notes:
Example: LIMITTIMEINACTIVE=20
Notes:
Thus, MAXCOUNTERS should be at least 10.
Examples: MAXCOUNTERS=30
Notes:
Example: MAXCLIENTNAMES=250
Notes:
Currently, SRE2002 maintains statistics on the following measures:
TOTAL_TIME,START_TRANSMIT_TIME, BYTES.
SRE2002 also retains the most recent values of CLIENTADDR (dotted numeric
address) and REQUEST (the request line).
In other words, MAXSTATVALS sets the number of "measures of the most recent responses" to retain.
Example: MAXSTATVALS=100
Notes:
Since computation of an MD5 is mildly CPU intensive (especially for long files), SRE2002 maintains an "MD5" cache. The MD5 cache is used for "permanent" files -- when SRE2002 is asked to compute an MD5 for such a file, SRE2002 can first check it's cache to see if such a value has already been computed.
Examples:
MAXMD5S= 200
MAXMD5S=0 -- do NOT maintain an MD5 cache.
Notes:
If you use the SRE_MD5 function with the MD5 cache enabled, all MD5 computations are serialized. This seems to to help system stability. Thus, if you set MAXMD5S=0, then there will be no MD5 cache, and MD5 computation will not be serialized.
Examples:
NO_MODIFY_ONTHEFLY=1 suppress on the fly modification
NO_MODIFY_ONTHEFLY=0 allow on the fly modification
Notes:
Example: PORT=80
REQ_CACHE_ENABLE=nn | enable, with nn the time-to-live of each entry, in days. Thus, REQ_CACHE_ENABLE=1 means "enable the cache, each item has 24 hour lifespan" |
REQ_CACHE_ENABLE=0 | do NOT attempt to resolve requests from the request cache |
Examples:
Notes:
source | port and ip address info:
serveraddr serverport transaction clientaddr clientport |
request_line | The request line (sent by the client):
verb selector protocol |
hostinfo | The host-nickname to whom this request is directed:
host host_nickname data_directory |
socket | The socket used for this request. |
Examples:
Notes:
parse arg client_address,verbose
REQ_CACHECALL_ANYWAYS can take the following values:
REQ_CACHECALL_ANYWAYS 0 | Do not call the filter after use of the request cache |
REQ_CACHECALL_ANYWAYS * | Always call the filter |
REQ_CACHECALL_ANYWAYS 1 | Always call the filter (same as *) |
REQ_CACHECALL_ANYWAYS A_LIST | Call the filter if any of the "abbreviations" in the spaced delimited A_list matches the selector |
Notes:
Example: REQ_CACHE_HITFILE=LOG\CACHEHIT.LOG
As an alternative to "calling the filter anyways", SRE2002 can maintain a simple log of all requests for which a "request cache" response was used. This log file (specified in REQ_CACHE_HITFILE) contains a running sum, by selector, of the 200 and 30x (unmodified) responses).
REQ_CACHE_RECORD can take the following values:
0 | Do NOT use the cache-hit file |
mmm | Use the cache hit file, and save results very mmm minutes |
Notes:
Example: REQ_CACHE_SIZE=200
REQ_CACHE_VERIFY can take the following values:
0 | never verify (always use cache entry if it exists) |
1 | verify, check Pragma, Cache-Control, If-None-Match, and If-modified request headers. If these are binding (i.e.; if Cache-control: no-cache is specified), then do NOT use the request cache. |
2 | verify, but ignore Pragma and Cache-Control:no-cache request headers (that is, just check etag and date) |
The following values of SECURITY_LEVEL are used by the SIMPLE filter (the simple filter that comes with SRE2002) and the sreLite2 filter.
value of SECURITY_LEVEL | Interpretation |
---|---|
0 | Remote configuration of server parameters is not permitted. Instead, you'll have to hand-edit (using your favorite text editor) the parameter files. In other words, the on-line configuration utilities are totally disabled (at least those that come with SRE2002 or with SRELITE2) |
1 | Remote configuration is only allowed from the server's own machine. In other words, it's not really remote -- you have to be running a browser on the same machine that SRE2002 is running (actually, the client ip address must match the server ip address, so a careful spoofer could cause damage). However, this does permit an "on-site webmaster" to use the on-line (html form based) configuration utilities. |
otherwise |
|
SERVERADDR_USE should be one of:
In general, it is safest to use a value of 0. However, there are cases (such as when your server is behind a NAT-capable router, and has a 192.168.0.nn address) for which the numeric ip address is meaningless. In such cases, set SERVERADDR_USE to the IP address of this site.
Notes:
Examples:
SERVERNAME_USE should be one of:
In general, it is safest to use a value of 0. However, there are cases (such as when your server is behind a NAT-capable router, and has a local name) for which the TCP/IP derived domain name is meaningless. In such cases, set SERVERNAME_USE to the "canonical" domain name of this site.
Notes:
Examples:
Set SERVER_SOFTWARE=0 to use the default name (that is hard coded into SRE2002.CMD).
Example: SERVER_SOFTWARE = SRE2002 for OS/2, ver 1.10
Notes:
Example: SERVER_SOFTWARE_SHORT= SRE2002
Notes:
STATUS_ITEMS should be a space delimited list containing one or more of the following tokens:
ERRORS, CONNECTION, CLIENTS, CLOCK, LASTACCEPT, LIMITS, PEAK,
STATS, VERBOSE
where:
CLIENTS | report number of currently active connections |
CONNECTION | report each connection |
CLOCK | display current time |
ERRORS | report cumulative number of errors. |
LASTACCEPT | display time of most recent connection |
LIMITS | report cumulative number of timeouts |
PEAK | report peak number of connections |
STATS | report summary statistics |
VERBOSE | report various other items |
The tracking facility instructs SRE2002 to store "status" and other "tracking" information. You can the retrieve this tracking information, on a client specific basis, by using SRE_TRACKIT.
For more details on tracking, see Appendix 5.
If you do NOT need this capability, set UNALLOWED_FILE=0
Examples:
UNALLOWED_FILE=BadIPS.IN
UNALLOWED_FILE=0
The UNALLOWED_FILE should contain one IP address per line. Lines that start with a semi-colon are comments (and are ignored), as are blank lines. Note that IP addresses should be the dotted numeric address (do not use domain names).
Alternatively, you can enter IP addresses that contain a *
wildcard character. These entries are used by the
BADIPS.RXX PRE_TRANSACTION procedure.
For example:
125.22.*.1 matches 125.22.0.1 to 125.22.255.1
Examples of UNALLOWED_FILE entries
98.13.61.22 98.13.61.23 ;clients from 98.14.* are not granted access 98.14.*Note that you can add and remove entries from the UNALLOWED_FILE at any time -- SRE2002 will check the UNALLOWED_FILE about once a minute.
Before proceeding, consider this short introduction to how SRE2002 works. Abstracting from configuration and startup issues, and ignoring some fancy tricks one can use, the sequence of events leading to resolution of a request is:
If the client's IP address is listed in the UNALLOWED_FILE, the connection will be immediately closed.
Before doing anything (that is, before reading any bytes from the socket), the transaction-daemon will call PRE_TRANSACTION procedures (if any have been specified).
Before launching the request daemon ...
- the PRE_REQUEST procedures are called (if any have been specified). Depending on the action of the PRE_REQUEST procedure(s), the request daemon may not be invoked.
- if the request cache has been enabled, the request-uri is looked for in the request-cache. If found, the file it points to returned to the client (and the request daemon is not invoked).
If a fast_filter was specified, the request daemon will call it first; and call the regular filter only if the fast-filter was unable to resolve this request.
In some sense, one can think of SRE2002 as providing an interface to the Internet; an interface with an API that a REXX program (a "filter") can use to recieve http requests and send http responses.
Prior to sending a response to the client, the transaction daemon may also apply instance manipulations to the contents. For example, range extraction is built into SRE2002; and other manipulations (such as delta encoding) can be supported via special IM modules for SRE2002.
Note: | "daemons" are independent threads. Actually, in order to avoid operating system overhead, daemons are "recycled", so that rather then ending, they go into a dormant state and await re-invocation. |
source | where, and to whom, the request is sent |
---|---|
request | the request line |
selector | the "selector" portion of the request line |
hostinfo | the host (and host-nickname) to whom the request is sent |
id_info | used to expedite processing of some SRE2002 functions |
request_number | the request number |
authorization_header | the value of a Authorization: request header |
is_alive | flag indicating whether the request is still alive |
In greater detail ...
servaddr | ip address of destination server (may vary if your server
is handling multiple ip addresses)
| port | port that recieved the request
| transaction | the transaction number
| who | numeric IP address of the client
| whoport | port used by the client
| |
From the above example, the selector is samples/foo.bar
host | either the ip name of your site, or the value of a HOST: request header. |
host_nickname | the "host-nickname" assigned to this host, or ' ' (if a host-nickname was not defined for this host) |
datadir | the "default data directory". If no host_nickname is available, this will be the value specified by the DATADIR parameter (in SRE2002.CFG). Otherwise, it's a host-specific data directory (which may be the same as the "default" data directory). |
The first example could be to a site for which no hosts have been defined.
Notes:
Note that the sequence of request numbers is: A,B,..,J,AA,AB,..,AJ,BA,...
Example: 4A
Example: Basic ZGFuOmRhbg==
If IS_ALIVE=1, the request has NOT been satisfied.
Otherwise, it has.
parse arg source,request,sel,MOREINFO,idInfo,reqnum,authh,isalive
SRE2002 includes a library of procedures that can be used when writing filters, or when writing addons for preexisting filters. Note that filters (such as sreLite2 or SREhttp/2) may have their own set of functions -- in many cases these provide additional capabilities that addon/script creators may find useful.
The following briefly describes a few of the more important SRE2002 functions. You can find more complete descriptions in SRE2PRC.HTM.
SRE_AUDIT | write lines to the AUDIT.LOG file |
Syntax: Call sre_audit(source_name,amessage) | |
SRE_AUTH_RESPONSE | return an authorization required response |
Syntax: rcode=sre_auth_response(realm_name) | |
SRE_COMMAND | recieve and send information to the client, etc. |
Syntax: STATUS=SRE_COMMAND('ACOMMAND OPTION',amessage) | |
SRE_DATADIR | return the default (or host specific) data directory |
Syntax: datadir=SRE_datadir() | |
SRE_ERROR_RESPONSE | return a server error response |
Syntax: rcode=sre_error_response(type) | |
SRE_REQFIELD | returns the value of a request header |
Syntax: avalue=SRE_reqfield(header_name) | |
SRE_SERVER | return descriptive name of the server software |
Syntax: sname=SRE_server() | |
SRE_SERVERNAME | return the domain name of the server |
Syntax: sname=SRE_servername() | |
SRE_WRITE_ERROR | write a message to the error log and to the status screen |
Syntax: call sre_write_error(error_message) | |
SRE_WRITE_MESSAGE | write a message to the status screen |
Syntax: call sre_write_message(short_message) |
Copyright 2000,2001,2002 by Daniel Hellerstein. Permission to use this program for any purpose is hereby granted without fee, provided that the author's name not be used in advertising or publicity pertaining to distribution of the software without specific written prior permision. Use of this product, or portions of this product, is subject to the following: 1) Portions of the code are adapted from other authors' work (these are noted where appropriate); you'll need to contact these other authors for appropriate permissions. 2) SRE-http uses several 3rd party dynamic libraries and executables: i) Quercus System's REXXLIB procedure library. The license for REXXLIB gives the author the right to distribute REXXLIB without charge. This right may NOT extend to redistributors (though as of April 2000 it appears that REXXLIB has been released to the public domain). Please contact Quercus Systems for details. ii) MKEY is freeware, and is part of a larger menuing system. For more info, contact the author at m1@uni-one.dl iii) FILEREXX is freeware. The author (Jeff Glatt) can be found on comp.os.os2.rexx. However, he no longer works with os/2. 3) We, the authors of SRE2002 and any potentially affiliated institutions, disclaim any and all liability for damages due to the use, misuse, or failure of the product or subsets of the product. * In particular, SRE2002 and related product are NOT * * guaranteed to be secure. * We do design and code our product with careful attention to potential security holes, and and we try to quickly fix any problems (or potential problems) that may be discovered. However, SRE-http's fundamental design precept is "open-source", with security an important secondary consideration. If you REQUIRE a highly secure web-server, you should carefully review and test SRE2002. In other words, you may need to choose a different server. Furthermore you may also charge a reasonable re-distribution fee for SRE2002; with the understanding that this does not remove the work from the public domain and that the above provisos remain in effect. THIS SOFTWARE PACKAGE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE PACKAGE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR (Daniel Hellerstein) OR ANY PERSON OR INSTITUTION ASSOCIATED WITH THIS PRODUCT BE LIABLE FOR ANY SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE PACKAGE. Lastly, if you would like to modify SRE2002, please contact the authors for the source code (Daniel Hellerstein, danielh@crosslink.net).
Basically, the request cache matches a selector to a file. If such a match exists (if a cache hit occurs), the SRE2002 will return the file to the client, without "calling the filter". By not calling the filter, hence avoiding request resolution overhead, responses can be sent substantially quicker -- 50% time savings are not uncommon.
Actually, even though the filter is not called, some processing will take place for "request cache hits". In particular:The point is that the request cache is not a cache of contents -- it is a cache of what file a selector points to.
- If- conditions will be checked
- Range, or other Instance Manipulation modifications can occur
- A few new headers may be computed (such as current date)
Entries are automatically created in the request cache when:
For more details on 'FILE' mode, see the description of the FILE option in SRE_COMMAND.
Use of the request cache does have a few drawbacks :
The following description is taken from the GoServe documentation, with a few minor changes.SRE2002 and your favorite browser can be run on a stand-alone machine that is not connected to a network, provided that TCP/IP is installed and the loopback driver is started. This is especially useful for developing Web pages offline, or for demonstrations. To do this, two additions are needed to a standard TCP/IP installation.
It's a good idea to have both formats, on two lines:
127.0.0.1 loopy.my.org 127.0.0.1 loopy
Notes:
If you are running OS/2 4.5 or above ..
Instead of the above, you can use the TCP/IP configurator (TCPCFG2):
Even if you are not connected to a network, your browser should not have a proxy or SOCKS server enabled (or it will try and use the network to find it before checking the HOSTS file).
The FAST_FILTER option allows you to do this. If you specify FAST_FILTER, then SRE2002 will:
Fast-filters are essentially the same as normal filters, they are sent the same arguments, and can access the same parameters and functions. There is one difference -- the fast-filter needs to inform SRE2002 as to whether it was successful or not.
To do this, the fast filter should return either:
When enabled (with the TRACKING_ON parameter), SRE2002 will maintain information on the current status of each client. This information is can be read (or modified) by using the SRE_TRACKIT procedure. Note that a shared daemon is used to store this information. Therefore, it may not be completely up to date -- when reading parameters, the actual parameters are not read; rather, their values as of their most recent update is used. Many of the variables that are "tracked" are also available via SRE2002 "EXTRACT" procedure. However, EXTRACT is designed to be used to obtain values of a client (where a client is synonymous with a connection) "own" variables. Basically, SRE_TRACKIT makes it easy to find status information for other clients. Currently, the following client-specific parameters are set by SRE2002. BYTESSENT_REQ bytes sent for this request (possibly reset if multiple requests per connection) BYTESREAD_REQ bytes read for this request (possibly reset if multiple requests per connection) CLIENTADDR dotted numeric IP address of the client RECIEVE RECIEVE can take the following values 0 - not currently sending >0 - amount to be received READHEAD Read header data. READHEAD can take the following values: PENDING Waiting to read ACTIVE Currently reading header END Header has been read READBODY Read body data. READBODY can take the following values: 0 Not yet read START Currently reading body END Body has been read REQUEST the request (within a transaction, starting with 1) SELECTOR the full request selector (as recieved from the client) SEND Currently "sending" information to client. SEND can take the following values: 0 not currently sending >0 sending this many bytes timeout timeout occurred on most recent send broken client broke the connection error error when sending ok piece succesfully sent SENDPIECES # of pieces sent 0 -- send mode not activated START -- send mode activated END -- send mode completed number -- number of pieces sent STATUS Current action being undertaken. STATUS may take the following values: START ERROR_CONN_CLOSE ERROR_LIMIT WAITING ERROR_417 (expectation failed) ERROR_TIMEOUT ERROR_NO_HOST (Host: missing from http/1.1 query) REQ_CACHE_USED (request-cache used) PROCESS_xxx (xxx is one of the SRE_COMMAND options) SNIPE (S "sniping" is currently active) TRANSACTION the transaction In addition, you can set your own "connection specific" values by using SRE_TRACKIT.
; comment lines start with semi-colon ; Entries should be of the form: ip_address , host_nickname , host_datadir ; for example: ; 127,0.0.1 , local1 , f:\www\h1 ; localhost , local1 , f:\www\h1 ; www2.mysite.org , altsite , e:\web\altfilesThe IP_ADDRESS can be a dotted numeric ip address, a domain name, or a local name. SRE2002 will detect what "host" the client is sending the request to and compare this client-provided information to the entries in the HOSTINFO.CFG file.
This comparision almost always uses the Host: request header provided by all modern (post 2.0) browsers. Sometimes, as when you are serving multiple numeric IP addresses, the numeric IP can be used.
If the client-provided host information does NOT match any entry in the HOSTINFO.CFG file (for example, if the HOSTINFO.CFG has no entries), then the request is assumed to be to the "generic" host.
The host_nickname is a shorthand that is often used by SRE2002 filters (such as sreLite2). For example, sreLite2 can place access restrictions on selector, using both the resource name, and the host_nickname.
The host_datadir is the default data directory. Most filter will use this as the "root" of the web tree. That is, the host_datadir is used instead of the DATADIR parameter set in SRE2002.CFG. In other words, the DATADIR parameter is only used for requests to the "generic" host.
Aliases:
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, almost all browsers (such as Netscape 2.0 and above) include aHOST:
request header containing the host to whom this request is directed. SRE2002 (as an http/1.1 compliant server) can use this request header to determine the proper host.
Examples: |
Examples (assuming the above request strings): |
Note that the "slight modifications" consists of 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 SRE2002 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).
Technical Note: | RFC2616 (the http/1.1 spec) defines an
HTTP request URL
as: Basically, the selector is the same thing as the abs_path [ "?" query ] |
The response line (which is always included)
contains status information (such as whether
the request could not be satisfied, or if authorization is required.
The typical response line, for a satisfied request, is:
The response headers contain meta-information on the
response. These includes time and date information, caching information,
server identifiers, and cookie definitions.
Response headers are
divided into three categories: |
The message body is the html-file, image, or other resource the client requested.
Examples: |