<html><head><title>SREhttp/2 FAQ </title></head><body>
<a name="top">*</a>
<pre> 6 January 2003    SREhttp/2 Frequently Asked Questions

<!--                                    
Note: This can be viewed as an HTML document by using the following "selector":
                a href="/!sendas_text_html/sre2k/srehttp2/srehttp.faq"
--> 

                     -------------------------------------

This document contains answers to some "frequently asked questions" about the SREhttp/2
web server for OS/2.

*   <a href="#WHATIS"> What is SREhttp/2 and SRE2003?</a>
*    <a href="#CANDO"> What can SREhttp/2 do?       </a>
*     <a href="#COST"> What does SREhttp/2 cost?  </a>
*   <a href="#CANGET"> Where can I get SREhttp/2? </a>
*  <a href="#INSTALL"> I downloaded the SREHTTP2 .ZIP file, how do I install it? </a>
* <a href="#WONTSTART"> SREhttp/2 won't start -- what should I do? </a>
*   <a href="#OBJECT"> Can SREhttp/2 run under Object REXX.  </a>
* <a href="#SLOWRESP"> The response time seems to be very slow....  </a>

*<a href="#CONFIGURE"> How do I configure SREhttp/2?    </a>
*<a href="#CONGFILES"> Can I edit SREhttp/2's configuration files? </a>
 
*   <a href="#ACCESS"> How can I control access to my site?  </a>
*  <a href="#SELSPEC"> How can I control access to a directory? </a>
*    <a href="#PRIVS"> What are "client privileges" and "required privileges"?</a>
*   <a href="#REALMS"> What's the difference between REALMS and privileges? </a>
*   <a href="#PRIV2S"> I'm still confused about these privilege things?  </a>

*     <a href="#SSIS"> What are the server side include capabilities of SREhttp/2? </a>
*  <a href="#COOKIES"> Can I use cookies with SRE2003 and SREhttp/2? </a>
* <a href="#DEFAULTS"> What about default documents?  </a>
*  <a href="#VIRTDIR"> What are SREhttp/2's virtual directories? </a>
* <a href="#REDIRECT"> How do I redirect a request?  </a>
*<a href="#CUSTOMIZE"> Can I customize SREhttp/2 responses?  </a>
* <a href="#WILDCARD"> How does SREhttp/2 deal with multiple "wildcard" matches? </a>
*     <a href="#HITS"> How can I record the number of hits I get? </a>
*  <a href="#SPEEDUP"> How can I speed up throughput?  </a>
*<a href="#MEDIATYPE"> How do I define new MIME media types?  </a>
*   <a href="#ADDONS"> What are the SREhttp/2 addons?  </a>

                   ------------------------------------------


*** The basics:

* <a name="WHATIS">   What is SREhttp/2 and SRE2003?   </a>

   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.

* <a name="CANDO">    What  can SREhttp/2 do?   </a>

  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.

* <a name="COST">      What does SREhttp/2 cost.  </a>

  $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).

* <a name="CANGET">    Where can I get SREhttp/2  </a>

  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

* <a name="INSTALL">   I downloaded SREHTTP2_xxxx.ZIP, how do I install it?  </a>

  Note that the xxxx stands for the current version. For example SREHTTP2_112B.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


* <a name="WONTSTART"> SREhttp/2 won't start -- what should I do? </a>

     *  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).


* <a name="OBJECT">      Can SREhttp/2 run under Object REXX?       </a>

  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 ...


* <a name="SLOWRESP">      The response time is very slow ...     </a>

  [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).


* <a name="CONFIGURE">    How do I configure SREhttp/2?      </a>

   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

* <a name="CONGFILES">    Can I edit SREhttp/2's configuration files?    </a>

  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:

*  <a name="ACCESS">    How can I control access to my site?    </a>

   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.


* <a name="SELSPEC">    How can I use selector specific access controls to 
                        control access to a directory?                  </a>

   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.


* <a name="PRIVS">    What are "client privileges" and "required privileges" ? </a>

    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.

* <a name="REALMS">    What's the difference between realms and privileges?   </a>

  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.

 
* <a name="PRIV2S">    I'm still confused about these privilege things?    </a>

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.


* <a name="SSIS">     What are the server side include capabilities 
                      of SREhttp/2?                            </a>

   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.

*<a name="SSICACHE">      What is the SSI-Cache?            </a>

   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").  

* <a name="COOKIES">     Can I use cookies with SRE2003 and SREhttp/2?     </a>

   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



* <a name="DEFAULTS">     What about default documents?          </a>

  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.

* <a name="VIRTDIR">    What are SREhttp/2's virtual directories?       </a>

    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


*<a name="REDIRECT">        How do I redirect a request?       </a>

   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.  


* <a name="CUSTOMIZE">        Can I customize SREhttp/2 responses.    </a>

  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).


* <a name="WILDCARD">      How does SREhttp/2 deal with multiple 
                           "wildcard" matches.                     </a>

   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
     

*<a name="HITS">         How can I record the number of hits I get?     </a>

  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


* <a name="SPEEDUP">        How can I speed up throughput?      </a>

  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).
  


* <a name="MEDIATYPE">      How do I define new MIME media types?       </a>

  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


*<a name="ADDONS">            What are the SREhttp/2 addons?       </a>

   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


        
   
<hr>
<!--   ==============================================================   -->

--- End of document.

<p><A HREF="#top">To top of document </a> </pre></body></html>

