Specifying Selector-specfic attibutes

• Introduction
• The ATTRIBS.CFG file
  option_file
  failure
  option
  permissions
  realm & meta realms
  redirect
  requires & meta realm files
  rule
  desc
  hosts
• Appendix 1. A note on wildcard matching
• Appendix 2. An example of an ATTRIBS.CFG file
• Appendix 3. Redirection in SREhttp/2
• Appendix 4. Using meta-realms

Under SREhttp/2, selector-specific attributes are specified by defining realms in the ATTRIBS.CFG file(s).

Notes:

The ATTRIBS.CFG files (like all SREhttp/2 configuration files) are text files SREhttp/2 uses a default ATTRIBS.CFG file (typically located in the SREHTTP2\CFG directory). SREhttp/2 also uses host-specific versions of ATTRIBS.CFG (typically located in subdirectories under the SREHTTP2\CFG directory) (see HOSTDATA.HTM for more details on SREhttp/2's host-specific parameter files). In addition to realms listed in the ATTRIBS.CFG files, you can use meta-realms to include additonal realms. You can use the SREhttp/2 configurator to modify parameters in any of the ATTRIBS.CFG files. As an alternative to ATTRIBS.CFG, you can use directory-specific HTACCESS files

The basic idea of this realm-architecture:

1. a site's resources (documents, images, scripts, etc.) can be sorted into realms
2. each of these realms may have numerous sub-realms
3. access to your server's resources can be defined on a realm specific basis -- a given client can be granted access to resources in only a subset of a site's realms.
4. other attributes, such as redirection instructions, and customization of how SREhttp/2 will process the request, can be defined on a realm, or sub-realm, basis
5. A realm, or a sub-realm, can contain:
   • one resource (a single selector), or
   • set of similarly named resources (a single, wildcarded selector), or
   • several similarly named resources

1. Comparing the request-selector to the realms defined in the default and host-specific ATTRIBS.CFG files.
   This comparison uses rules that are assigned to each realm (and to each sub-realm).
2. If a matching rule is found (either an exact match, or a wild card match), then the selector is assigned to the realm (or sub-realm).

    action: options

The valid actions are:

Each block must contain a REALM and a RULE.
desc	-- a short (60 character) description
option_file	-- specify an advanced options file
failure	-- specify an access failure file
option	-- specify an advanced option
permissions	-- specify SREhttp/2 permissions
realm	-- the name of this realm or subrealm(REQUIRED). Alternatively, this can specify a meta-realm.
redirect	-- url redirection, or virtual directory assignment
requires	-- resources privileges needed for access
rule	-- selectors (possibly *'ed) to assign to this realm (REQUIRED)
hosts	-- a list of host-nicknames dictating when this realm may be used

The following describes these actions in greater detail:

failure	Specify how to respond when access is denied Failure complements the FAIL_FILE parameter in SREHTTP2.CFG. Syntax: failure: -1 If no access, do NOT ask for authorization. failure: 0 (or failure: ) use the default fail_file (or send an authorization response) filename.ext a file name. If not fully qualified, it will be relative to the host-specific CFG directory. Notes: As with permissions, if a sub-realm's faiulre is not specified, it will be inherited from its parent realm. If there is no failure defined for the sub-realm or its parent realm, the possibly host specific FAIL_FILE is used. You can specify a host-specific (but not selector- specific) not-found file -- which is used instead of the generic 404 Not Found response. The FAIL_FILE parameter can suppress use of selector-specific failure parameter. If the FAIL_FILE is an html document (say as indicated by an .HTML extension), then a few simple text substitutions will occur. For the details, see the description of the FAIL_FILE parameter. Examples:     failure: UNALLOWED.RSP     failure: 0
option	Specify an advanced option Syntax:     option: an_advanced_option The an_advanced_option can be any of the SREhttp/2 advanced options, as described in ADV_OPTS.HTM. Notes: As with permissions, if a sub-realm's option are not specified, it will be inherited from its parent realm. option complements option_file You can specify multiple option: lines -- with one option per line. Examples: option: set fix_expire 0.5 option: ssi_no_footer option: REPLACE_RULES=</HEAD>==<BASE href="http://www.x.org"></HEAD>
option_file	Specify an advanced options file. Syntax:     option_file: file_name file_name should be a relative file name; which will be relative to the CFG directory for the host (that is specified in HOSTDATA.CFG). For the default, this is usually the SREHTTP2\CFG directory. For more details on advanced options files, see ADV_OPTS.HTM Notes: option_file complements OPTION you can use ADV as an abbreviation for option_file Example: option_file: ADV2.CTL
permissions	Specify the "permissions" to use for selectors that belong to this realm. Syntax:     permission: permission_list permission_list is a spaced delimited list of SRE-http "permissions". Currently available permissions include: NO_SSI DO_SSI NO_SSP CACHE NOCACHE LOG NO_LOG NO_CUSTOM_USERNAME PUT DELETE NO_DIR HTACCESS NO_HTACCESS Notes: If you define a sub-realm without specifying any PERMISSIONS, then it will inherit the PERMISSIONS of its parent realm. If a realm's permissions have not been specified (and have not been inherited from a parent realm), then the value of the (possibly host-specific) PERMISSIONS_DEFAULT parameter is used. NO_SSI Suppress server side includes (SSI) in HTML files DO_SSI Prcoess server side includes (SSI) in HTML files Note: NO_SSI and DO_SSI are only used when the resource has a text/html mimetype NO_SSP Suppress server side processing: suppress addons, cgi scripts, and executable code in HTML files. Note: to just suppress executable code in HTML files, you can use the #EXEC and INTERPRET SSI suppression options CACHE Allow caching of this selector by proxies and by the SRE2003 request cache (this is ignored if the response does not use a permanent file). Note: If access controls are in place, then by default caching is disabled. Use of CACHE allows one to override this default rule. NOCACHE Do NOT cache this selector. NOCACHE overrides CACHE and CACHE*. LOG Permit writing of log information to the common, brower, and referer log files. NO_LOG Suppress writing of log information to the common, brower, and referer log files. Note that NO_LOG supercedes LOG. Also note that LOG and NO_LOG supercede the LOG_SUPPRESS parameter. NO_CUSTOM_USERNAME Suppress use of a custom username procedure PUT Allow PUT method requests to "copy information to" the directory represented by this selector. Notes: The PUT permssion can also be used by SREhttp/2 addons, such as GET_URL and PUT_FILE The PUT_OVERWRITE selector specific option also controls the behavior of PUT method requests. DELETE Allow DELETE method request to "delete" the file represented by this selector. NO_DIR Do not permit automatic creation of a directory. This suppresses the !DIR option of the DEFAULTS SREhttp/2 parameter. HTACCESS Use the HTACCESS access-control method. Depending on the value of the HTACCESS parameter, this may have no effect (the HTACCESS parameter can completely disable the HTACCESS method). NO_HTACCESS Do not use the HTACCESS access-control method. Example: permission: NO_SSI NO_SSP NO_CACHE
realm (required)	Identify the realm,or specify a meta-realm. Syntax: realm: main_realm    or realm: main_realm.sub_realm    or realm: META:meta_realm_name Notes: the meta_realm_name identifes a set of realms, which will be specified in a meta realm file. The meta realm file is specified using the requires attribute. PUBLIC is a special main_realm -- it signifies open access resources: an implicit Requires: 0 is used any explicit Requires: are ignored. for requests in the PUBLIC realm (or subrealms of PUBLIC), SREhttp/2 will make no attempt to find the requesting client's privileges. That is, username/password lookup will not occur. Caching is enabled Sub_Realm entries will always use the Requires: values of their Main_Realms. If no Main_Realm has been defined (for this Sub_Realm), a Requires: 0 is used. For permission, failfile, options and hosts; Main_Realm values will be used only if there is no explicit value defined for a sub-realm. Subrealms can be more then 1 deep. Thus, FOO.BAR.UP is legitimate (though the default values are those of FOO.). When SREhttp/2 returns an authorization request to a client, it will use the Main_Realm. For example, if a request matches R1.S3.T4, then R1 is the realm reported to the client.   Examples:   realm: foo1   rule: /dog/*   requires: priv1   permissions: no_ssp This defines the foo1 Main_Realm. Selectors that match /dog/* will need a priv1 client privilege, and will have a no_ssp permission.   realm: foo1.bar1   rule: /dog/planets/*   permissions:no_ssi This defines the bar1 Sub_Realm of the foo1 Main_Realm. Selectors that match /dog/planets/* will need a priv1 client privilege (since this uses the requires: defined for foo1), and will have a no_ssi permission.   realm: public   rule: /sol/* This defines a public realm. Note that public realms always use Requires: 0 .   realm: foo1.bar1.s2   rule: /gasgiants/* This defines the bar1.s2 Sub_Realm of the foo1 Main_Realm. Selectors that match /gasgiants/* will need a priv1 client privilege (since this uses the requires: defined for foo1), and will have a no_ssp permission (that it inherits from foo1).   realm: META:greenbean   rule: /veggies/*   requires: veg1.rlm This specifies the greenbean meta-realm. The veg1.rlm file (which is relative to the possibly host specific CFG subdirectory) contains the various realm definitions that make up this meta-realm. All of these realms (that are specified in veg1.rlm) must have rules that also satisfy the /veggies/* rule.
requires	Identify the required privileges a client needs to access this realm, or specify a meta realm file. Syntax: requires: priv_list    or requires: meta_realm_file priv_list priv_list is a space delimited list of required privileges. Two kinds of privileges can be specified in the list of required privileges: ONE_OF and MUST_HAVE. ONE_OF: the client must have at least one of the ONE_OF privileges MUST_HAVE: the client must have all of the MUST_HAVE privileges. MUST_HAVE privileges are identified by a preceding &. meta_realm_file meta_realm_file is a file containing additional realm definitions to include. It must be relative to the possibly host specific CFG subdirectory. Notes: The realm definitions in meta realm files are no different then realm definitions in an ATTRIBS.CFG file. The only constraint is that they must have rules that are subsets of the *'ed (wildcarded) rule used in the meta-realm's rule. to include a meta realm file the realm attribute must start with META: priv_list notes: If requires is not specified, then the value of the (possibly host-specific) REQUIRES_DEFAULT parameter is used. Subrealms must inherit the required privileges of their main realm -- you can not specify different sets of resource privileges for different subrealms under the same main realm Thus: requires can not be used in subrealm entries! For the PUBLIC realm, REQUIRES is ignored (an implicit REQUIRES: 0 is used). Reiterating: Sub-realms inherit the REQUIRES values of their parent realm. You can not set sub-realm specific REQUIRES For further discussion of client privileges, see USERS.HTM   Examples: requires: 0 requires: * requires: MARS PLUTO requires:FRUIT VEGETABLES &WATER the client must have a WATER privilege, and at least one of the FRUIT or VEGETABLE privileges. requires: mrealm1.rlm mrealm1.rlm is a meta realm file
redirect	Redirect or redefine a request See Appendix 3 for a complete description of how SREhttp/2 uses redirection. Syntax:     redirect: mode = xxx mode can be: dir, internal, literal, negotiate, perm, or temp dir a "virtual directory". XXX is a fully qualified directory. For more details, please see the dicussion of virtual directories Appendix 3. internal an alias. XXX is a selector, which can contain multiple wildcard (*) characters. For more details, please see the discussion of local redirection in Appendix 3. literal a "literal" transfer. XXX is a fully qualified file name, which can contain multiple wildcard (*) characters. For more details, please see the discussion of literal assignment in Appendix 3. negotiate identifies a "negotiable resource". This resource contains content-negotiation information. XXX is usually empty, but in certain cases it can point to a variant-list file & its directory. For more details, please see the discussion of content-negotiation in Appendix 3. perm "a permanent redirection" (301). XXX is a local or fully qualified URI. It may contain mulitple wildcards. For more details, please see the discussion of redirection in Appendix 3. temp "a temporary redirection" (302). XXX is a local or fully qualified URI. It may contain mulitple wildcards For more details, please see the discussion of redirection in Appendix 3. notify "a notified redirection". XXX is a local or fully qualified URI. It may contain mulitple wildcards For more details, please see the discussion of redirection in Appendix 3. Redirect notes: There can be at most ONE (or none) redirect: actions per entry. The url in a redirect: perm (or redirect: temp) can be local, or it can be fully specified (starting with http://). The following synonyms can be also be used: ALIAS: xxx for REDIRECT: INTERNAL = xxx LITERAL: xxx for REDIRECT: LITERAL= xxx VIRTUAL: xxx for REDIRECT: DIR=xxx MOVE: xxx for REDIRECT: PERM=xxx TEMPMOVE: xxx for REDIRECT: TEMP = xxx NOTIFY: xxx for REDIRECT: NOTIFY=xxx NEGOTIATE: xxx for REDIRECT: NEGOTIATE=xxx   Examples:   redirect: temp= http://www.yahoo.com/   redirect: dir=d:\foobar\*   alias: /newsels/*
rule (required)	Specify matching rules for idenfitying selectors that belong to this realm. Syntax:     rule: a_selector a_selector may contain multiple wildcard (*) characters. Some simple examples include: rule: /xxx/yyy/foo.htm rule: /zzz/* Notes: one can define rule: several times within a single entry -- multiple rule actions are cumulative. Thus, several different selector matching rules can be used to identify a variety of resources all of which belong to the given realm (or to a given subrealm) Realm assignation is done by comparing a rule to the request selector. More precisely, to the request selector after URL-decoding and after all !Special commands and directives have been removed. Appendix 1 discusses how SREhttp/2 uses wildcards when matching selectors to a rule.
desc (strictly optional)	A short description of this entry Syntax:     desc: a short description desc is used for informational purposes. It is similar to including a comment (lines starting with a ;). There are a few differences -- since desc lines are part of the entry, they are more cleanly removed by SREhttp/2 utilities. In contrast, comments are left behind, which can clutter up your ATTRIBS.CFG file after a while. The desc descriptions can be looked up on a selector specific basis
hosts (strictly optional)	Hosts is used to control when this realm will be used. If specified, hosts should be a host-nickname, or a space delimited list of host-nicknames. For a given request, the host-nickname (of the host to whom this request was sent) is compared against this list. If the host-nickname does not appear in this list, then the realm will not be used (for this request). However, if you do not specify a hosts attribute, then this additional test will not be made. The hosts attribute is useful ... in the DEFAULT ATTRIBS.CFG file, when there are several non-superceding hosts. when a host-nickname is used by more then one host (that is, when several host-nickname entries specify the same ATTRIBS.CFG file). Basically, hosts is a shortcut -- instead of specifying several (possibly small) ATTRIBS.CFG files, you can use hosts to apply selected realm(s) only to a subset(s) of the hosts that could otherwise use it. For example, suppose you have lots of hosts that each have a few realms defined, and that also use a number of realms in common. These common realms can be easily defined in the DEFAULT ATTRIBS.CFG file. But what if there are a few realms that should only apply to the DEFAULT host? By using a Hosts: DEFAULT attribute on these realms, you can easily enforce this limitation. Summarizing A client's request consists of a selector and a host (where host is synonymous with servername). SREhttp/2 assigns a host-nickname to all hosts. If you have not explicitily defined a host-nickname for particular host, a host-nickname of DEFAULT is used. Each host-nickname can have a set of realms defined. These realm definitions are contained either in a host-specific ATTRIBS.CFG file, or in the DEFAULT ATTRIBS.CFG file. Each of these realms can have a host attribute. If defined, a realm will only be used if the host-nickname of a request is specified in this host attribute. Thus, when a SREhttp/2 considers which realm a request belongs to, the set of realms considered... are defined in either the host-specific, or the DEFAULT ATTRIBS.CFG file. do not have a hosts attribute, or have a host attribute that contains the host-nickname (of this request). Notes In sub-realms, hosts (like permissions) can inherit the value of their main-realms hosts. The host-nicknames are case-insensitive.

In order to determine selector-specific attributes, SREhttp/2 will check the entries contained in ATTRIBS.CFG. More precisely, SREhttp/2 will examine entries in the default and host-specific ATTRIBS.CFG file.

When an exact match is found between the request selector and a rule, then this matching entry is used. If there is no exact match, then the request selector is compared against all wilcard entries. Entries are checked using a multiple wildcard, with multiple substitutions algorithim (where the * character acts as a wildcard).

If several entries can match the selector...

1. Exact matches always take precedence
2. The wildcard match that has the most "early character" matches wins.
   Thus, if your selector is FOOD/FRUIT/ORANGES.HTM
   then the order (with first being chosen before last) is:
   • FOOD/FRUIT/ORANGES.HTM (the exact match)
   • FOOD/FRUIT/*HTM
   • FOOD/FRUIT/*
   • FOOD/*IT/*HTM
   • FOOD/*.HTM
   • FOOD*
   Note that entries can appear in any order in ATTRIBS.CFG, with no effect on precedence.

Some wildcard examples:

; selectors starting with /temp/* are directly mapped to h:\temp
realm: r0
rule: /temp/*
redirect: dir=h:\temp\*

; redirect some requests
realm: r1
desc: some graphical programs were moved
rule: blendgif.htm 
rule: mkgiftxt.htm
redirect: moved=http://www.srehttp.org/apps/

; all selectors starting with pubfiles/* are PUBLIC
realm: public
rule: pubfiles/*

; a "low auditing" class of PUBLIC resources
realm: public.1
rule: morepubfiles/*
permissions: no_postresponse
redirect: literal=f:\pubs\*
desc: these public files are not interesting to track

; selectors to HTML (or other static files) resources, that start 
; with temp/*, are accessible by anyone with a valid username;
; and their "root directory" is f:\temp\*
realm: r2 
requires: *
rule: temp/*
redirect: !HTML dir=f:\temp\*  

realm: send1
rule: scores/yankees
literal: e:\baseball\yanks.txt

realm: r2.3  
host: danny
rule: yahoo
redirect: move = http://www.yahoo.com

realm: r3 
rule: srehttp_faq
redirect: internal=/samples/srehttp.faq
permissions: yes_ssi

realm: r4
rule: config2.*
requires: superuser
permissions: no_alias
redirect: temp=http:/www.mysite.org/config2.*

realm: r5.a.1
rule: /inhouse/foobar.htm
permissions: no_ssi

realm:r4.b
rule: config3.*
option_file: foo.ctl
permissions: no_postresponse
option: ssi_no_header
option: ssi_no_footer

realm: manual
rule: /manual/*
negotiate: mans/manual1.lst

realm: intr
rule: intro.txt
option: set content_md5 1

realm r5
rule: /inhouse/*
requires: inhouse

realm: sort_of_secret
rule: my_tales/*
permissions: NO_DIR

realm:defonly
desc: this redirection should only be used with request to the default
rule: /disclaim.txt
hosts: DEFAULT 
literal: f:\legal\disclaim_2003.txt

1. virtual directories: -- for use as the root directory when mapping web requests to files.
2. internal redirection: -- map a request to a different selector, without notifying the client
3. literal assignment: -- map a request directly to a file.
4. content-negotiation: -- map a selector to different resources, depending on the value of various request headers.
5. permanent, temporary, and notify redirection -- redirect the client to a different URI.

Virtual directories

Virtual directories are used to allow access to files not in a default directory. The typical use is to allow requests for documents to be in a subdirectory not under the default (or host-specific) SRE2003 data directory

Virtual directories can also be used to:

• specifying the location of a cgi-bin script
• specifying the location of an sre-http add-on
• specifying where an uploaded file should be placed

What are virtual directories	When SREhttp/2 recieves a request, it must map the request selector to a resource on the server. For example, by matching an HTML request to a .HTM (or .HTML) file. Typically, this is done by treating the request selector as a relative file name, relative to a data directory. If a virtual directory is not specified, then a default (or host-specific) data directory is used as a root directory. That is, the request selector is mapped to a file that is relative to this root directory. Basically, virtual directories are used to specify a selector-specfic root directory.
Specifying virtual directories	Virtual directories are specified with a   redirect: dir= xxx or, synonymously, with ...   virtual= xxx where: xxx is a fully qualified directory (that may, or may not, end with a \). Requirements: Realms that specify a virtual directory must have only one rule The rule must end with an asterisk (an *). Example: realm: faq1 rule: /info/* redirect: dir=f:\wwwnew\faqs
Usage	Given that a virtual directory is defined for a request-selector, the filename (that this request selector refers to) is determined by: appending the portion of the request-selector covered by the * to the end of the virtual directory Using the above example: a request-selector of: /info/guide.html would map to: f:\wwwnew\faqs\guide.html

Advanced usage: virtual directory by request type

You can specify multiple virtual directories, with different virtual directories used for different types of requests. To do this, use:   redirect:dir=!type xxx , ... , !type xxx where... xxx is as described above !type is one of: !HTML, !ADDON, !CGI, !UPLOAD These types refer to the type of request for which the immediately following xxx will be used. Respectively, these are !HTML : requests for static documents (HTML, text, images, etc.) !ADDON : requests to run SREHttp/2 addons !CGI : requests to run CGI-BIN scripts (see the example below -- the syntax is a bit different) !UPLOAD : PUT requests to upload to the server Example: Given the realm:    realm: test1    rule: /testme/*    redirect: dir= !HTML d:\www2 , !ADDON d:\progs\web then a request for an HTML file:     /testme/hello.html maps to:     d:\www2\testme\hello.html however, a request for an SREhttp/2 addon:     /testme/status2.cmd?user=andrew maps to:     d:\progs\web\status2.cmd

Examples

realm: foo1 rule: /state16/* redirect: dir=d:\usa\maine STATE16/AROOSTOK/AG.HTM would map to D:\USA\MAINE\AROOSTOK\AG.HTM realm: goo1 rule: ACTION2/* redirect: dir= !addon E:\programs\task2 The !addon signals that the E:\PROGRAMS\TASK2 virtual directory will only be used for requests that invoke SREhttp/2 add-ons. For example:    /action2/getafile.cmd?dir=foodir1 would execute (as an SREhttp/2 addon):    E:\programs\task2\GETAFILE.CMD while    /action2/gogo.htm would map to    D:\www\action2\gogo.htm (assuming that D:\WWW was the default data directory). realm: cgi3 rule: /MYSTUFF/* redirect: dir= !cgi E:\SCRIPTS\PERSONAL When /MYSTUFF/CGI-BIN/BIG_CGI.CMD?xx is requested, E:\SCRIPTS\PERSONAL\BIG_CGI.CMD is used (as a CGI-BIN script). Note: the CGI-BIN should not be included in the rule or in the redirect!

---

Internal redirection

Internal redirection, which is also called aliasing, refers to transforming request-selectors, and then resolving this transformed selector. Internal redirection comes in handy:

• to handle misspellings and abbreviations of URIs
• to implement searchable indices
• as a fast redirection from to a resource on the same site.

Specifying Internal Redirection	Internal redirection is specified with a   redirect: internal= xxx or, synonymously, with ...   alias= xxx where: xxx is a selector xxx may have 0, 1, or more wildcards (*) in xxx Requirements: Realms that specify internal redirection can have several rules Each rule may have wildcards (*) Example: realm: faq2 rule: /info/* rule: /help/* redirect: internal=/faqs/*
Usage	Given that a internal redirection is defined for a request-selector, the redefined request selector is determined by: If the rule is an exact match, then the xxx (from above) is used as is. If the rule is a wildcard match, then SREhttp/2 will replace wildcarded portions of xxx with the corresponding parts of the request-selector. This redefined version of xxx is then used as is. In either case: SREhttp/2 acts as though the redefined version of xxx was requested by the client. Using the above example: given a request-selector of:   /info/guide.html, or   /help/guide.html the redefined selector is:/faqs/guide.html

Advanced Usage: Iterating

You can iterate an internal redirection by prefacing xxx with !REPEAT. For example: redirect: internal= !REPEAT /faqs/* Iteration means that SREhttp/2 will repeat the attribute lookup, using the internally redirected selector (instead of the original selector). If this repeated lookup yields a match, then the attributes of that match are used, rather then the attributes of the original match. Example: Selector: /info/2001/autos.html Realms: realm: faq2 rule: /info/* rule: /help/* redirect: internal= !repeat /faqs/* option: ssi_no_header realm: faq2.2001 rule: /faqs/2001/* redirect: internal=/archive/yr01/text/* option: ssi_no_footer yields: /info/2001/autos.html is internally redirected to /faqs/2001/autos.html which, because of the !REPEAT, is than internally redirected to /archive/yr01/text/auto.html Furthermore, the ssi_no_footer option will be used. The ssi_no_header option will not be used. Note that /info/2002/auto.html would yield /faqs/2002/auto.html and a ssi_no_header option. Notes: !Repeat is case insensitive You can have up to four repeats. If there are more then four, a 500 Internal Server Error response will be returned (this constrained imposed in order to avoid infinite loops). Since repeat lookups do take a bit of time, it is wise to not use them excessively. The requires: and other attributes of earlier matches in a repeated lookup are ignored. Thus, access controls only apply to the final result!

Notes:

Wildcard substitution occurs only if a * appears in the rule and in the xxx. When this occurs, and the request selector wildcard matches the rule, a textual substitution will occur in the xxx. Specifically, the * in the xxx will be removed, and the portion of the request selector covered by the * (in the rule) will be inserted in its place. Example: request selector: /CATS/A14.HTM realm:   Realm: foo3   Rule: /CATS/*   Redirect: internal= /SHOP1/PETS/FELINES/PUREBRED/* will yield:   /SHOP1/PETS/FELINES/PUREBRED/A14.HTM Note that the A14.HTM in the request selector is covered by the * in the rule, and is then used to replace the * in the xxx. A caution regarding unwanted aliasing: Unless you explicitly want to internall redirect actual files, directories, etc. be sure that internal redirection rules do not match pre-existing files, directories, etc. {be especially careful if you are using any wildcard matches) A caution on internal redirection and partial urls: When using aliases for internal redirection, URL resolution by the client's browser may have unexpected consequences. In particular, the client will resolve partial URLS relative to the original request-selector, and not to the redefined request selector. Therefore, internal redirection is not appropriate if redirecting a request for an HTML document that contains many partial URLS. Instead, use Redirect: perm.

Examples:

realm: goo1 rule: /INDEX rule: /INDX redirect: internal=/index.htm * Replaces alternate spellings of /INDEX.HTM realm: search1 rule: TESTSRCH.HTM?* redirect: internal= DOSEARCH?file=/congress.dat&searchfor=*&delim=$ * Implements a searchable index (using SREhttp/2's DOSEARCH utility) CONGRESS.DAT will be searched using the search list provided by the client

---

Literal assignment

Literal assignment is used to directly map a request-selector to a file. It's a cross between virtual directories and internal redirection -- you use it to assign a request-selector (possibly wildcarded) directly to a file. Actually, by using wildcards you can assign sets of request-selectors to files (using wildcard substitution).

Specifying Literal Assignment	Literal assignment is specified with a    redirect: literal= xxx or, synonymously, with ...    literal= xxx where: xxx is a file-pattern you may have 0, 1, or more wildcards (*) in xxx Requirements: Realms that specify literal assignment can have several rules Each rule may have wildcards (*) Example: realm: zoo1 rule: /cats/tigers.htm redirect: literal=f:\animals\felines.htm
Usage	Given that a literal assignment redirection is defined for a request-selector, the redefined request selector is determined by: If the rule is an exact match, then the xxx file-pattern is used -- SREhttp/2 will retrieve it (if xxx is an HTML file, SSIs may be done). If the rule is a wildcard match, then SREhttp/2 will replace wildcarded portions of xxx with the corresponding parts of the request-selector. This redefined version of xxx is then used as the file-pattern.
Examples:	realm: send1 rule: scores/yankees literal: e:\baseball\yanks.txt * Note that literal assignment occurs before automatic add-slash and redirect realm: goo2 rule: GETMAP?* redirect: literal= e:\MAPS\* * A request of GETMAP?AZ.JPG yields E:\MAPS\AZ.JPG * This example assumes that 1 argument is appended to the selector (say by a FORM of type GET)

---

Content negotiation

Content negotiation refers to the choosing of a best representation of a web resource from several alternatives. SREhttp/2 supports several http/1.1 compliant mechanisms for performing content negotiation.

For details on how to use content-negotiation in SREhttp/2, see NEGOTIAT.HTM.
Specifying Content Negotiation	Content negotiation is specified with a    redirect: negotiate= xxx or, synonymously, with ...    negotiate= xxx where: xxx is usually empty or is a single period (.). However, in certain cases xxx can point to a special listing file, in which case it has the syntax of:     a_selector filename where... a selector. If specified, it is the selector that points to the variant list. a filename is optional. If specified, it is the exact location of the variant-list. If you specify a filename, the selector must also be specified, and should point to the path contained in filename. you may have 0 or 1 wildcard (*) in the selector component of xxx Requirements: Realms that specify redirections can have several rules Each rule may have 0 or 1 wildcard (*) Example: realm: testns rule: VARTEST/VAR1.LST* negotiate: .
Usage	Negotiation is used to tell SREhttp/2 that the request-selector should be used as instructions for content-negotiation. That is, the contents of the file pointed to by the request selector should not be returned by the client. Instead, the file is interpreted as a variant list, which is used to help choose some other file, with the choice being determined by the current values of various request headers. Thus, one usually does not include wildcards in the rule, and one usually specifies a period (or equivalently, nothing) after the negotiate: . However, you can use a wildcarded rule and place the name of the variant-list file after the negotiate: (in the selector portion of xxx). Example: Realm: TestN1 Rule: /manual/* Redirect: negotiate= /manual/manuals.lst Which means use the variant list in /MANUAL/MANUALS.LST for all request-selectors that match MANUAL/* Caution: If you use this wildcarded construct, the variant list must contain an appropriate PATTERN: entry.
Notes:	The xxx can either be: a . or nothing a selector, which points to a variant-list file. This variant-list file may be in a different directory. Considering the above example, instead of /MANUAL/MANUALS.LST, one could specify /DOCUMENTS/NEW_MANUALS/MANUALS.LST A selector, followed by a fully qualified file name. For example: negotiate= /docs/new/manuals.lst F:\PROJ1\INFO\MANUALS.LST The fully qualified file is used as the variant list file, Furthermore, variants (listed in the variant-list file) are relative to the path of this fully qualified file. The selector is used to form URI's that point to variant files. These URIs should point to the same path as the fully qualified file.
For details on how to use content-negotiation in SREhttp/2, see NEGOTIAT.htm.

---

Permanent, temporary, and notify redirection

Permanent and temporary redirection corresponds to returning a 301 or a 302 http response. Upon reciept of this simple (no content-body) response, the client should immediately issue a request for the URI you specify in your redirection.

Notify redirection is not a true http redirection. Instead, SREhttp/2 will send a normal (200) html response that contains a link directing the client to the new location of the resource.

Specifying Redirection	Permanent redirection is specified with a    redirect: perm= xxx or, synonymously, with ...    move= xxx and... Temporary redirection is specified with a    redirect: temp= xxx or, synonymously, with ...    tempmove= xxx and... Notify redirection is specified with a    redirect: notify= xxx or, synonymously, with ...    notify= xxx where: xxx is a fully qualified, or relative, URI you may have 0, 1, or more wildcards (*) in xxx Requirements: Realms that specify redirections can have several rules Each rule may have wildcards (*) Example: realm: movies rule: /films/* redirect: move=http://www.coolflicks.com/cinema10/*
Usage	Given that a permanent (or temporary or notify) redirection is defined for a request-selector, the redefined request selector is determined by: If the rule is an exact match, then the xxx URI is used as the location for the redirection. If the rule is a wildcard match, then SREhttp/2 will replace wildcarded portions of xxx with the corresponding parts of the request-selector. This redefined version of xxx is then used as the location. Notes: For permanent and temporary redirection: Location is used in a location: response header. For notify redirection: location is used as the target of a link (that is, as the xxx in <a href="xxx">). The only difference between permanent and temporary redirection is whether a 301 or 302 response code is sent to the client (where 301 signifies permanent, and 302 signifies temporary).
Examples:	realm: goo3 rule: YAH* rule: WAH* redirect: move=http://www.yahoo.com/ * All requests starting with YAH or WAH are sent to the yahoo home page. realm: goo3 rule: /USGS/* redirect: temp=http://www.usgs.gov/tiger/* * Requests starting with /USGS/ are temporarily redirected to: http://www.usgs.gov/tiger/ Thus, a request-selector of /USGS/RIVERS.DAT is redirected to: http://www.usgs.gov/tiger/rivers.dat. realm: goo4 rule: /joedir/cv.htm redirect: notify= http://college.tfar.edu/C/JOE/CV.HTM * A "notification of moved resource" -- client recieves an html document telling her the resource has been moved to http://college.tfar.edu/C/JOE/CV.HTM with a link to this new location realm: goo4 rule: /sales/event.html redirect: move= /oldsales/event13.html * Redirect to a different selector on the same site. realm: elephant rule: pachyderm/events.html redirect: notify=www3.oursite.com/elephant.shtml option: Header add refresh: 15; url=http://www3.oursite.com/elephant.shtml option: set notify_message You will soon be redirected to our elephant site ... * Notifies the client that the pachyderm/events.html has been moved, and informs the client that this will be automatically obtained. After 15 seconds, most browsers will automatically fetch this new URI.

Use of meta-realms offers several advantages:

1. If can be convenient to keep related sets of realms together, with their definitions in their own file.
   For example, if you want to allow a user to manage access to realms defined by a path, but you do not want to give her superuser privileges, you can define her realms in a meta-realm file, and let her edit this file (say, using FTP, or SREhttp/2's file upload capabilities).

2. When you have many realms, the use of meta-realm files helps to optimize SREhttp/2's data structures, leading to quicker lookups.

Example....

ATTRIBS.CFG realm: meta:joe rule:/joe/* require: joe.rlm realm: allpix rule: *.BMP *.GIF perm: cache no_log realm: meta:bob rule: /bob/* require: robert.rlm JOE.RLM ; realms in the JOE realm realm: JOE_PHOTOS rule: /joe/photos/private/* require: view1 realm: JOE_FAVORITES rule: /joe/docs/favorites/* redirect: temp=http://joesite.foo.net/* ROBERT.RLM ; realms in the BOB realm realm: BPWD rule: /bob/password.lst require: superuser realm: SHOES rule: /bob/shoes/* redirect: internal=/bob/clothing/footwear/* realm: temps rule: /bob/*.tmp options: set expires 1s