SREhttp/2 Manual|| Advanced Options || Edit ATTRIBS.CFG || HTACCESS

## Specifying Selector-specfic attibutes

Contents:

- 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

### Introduction

User-configurable, selector-specific attributes are attributes that you (the web site administrator) may wish to set on a request selector specific basis. These include access requirements, controls on how SREhttp will process a request, URL redirections, and other remappings.

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 ATTRIBS.CFG file

ATTRIBS.CFG uses a realm-architecture; an architecture that matches how the WWW is organized.

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

For each request recieved, SREhttp/2 uses these realms by:

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

Additionally, you can define meta-realms -- meta realms allow you to include files into the ATTRIBS.CFG file(s). The use ofe meta-realms can both improve the ease of maintaining your site, and offers some performance advantages when you define many realms.

### Syntax of `ATTRIBS.CFG`

Realms (and sub-realm) are defined in `ATTRIBS.CFG` files (or in included meta-realm files) by a block of several mime-like lines, ending with a blank line. Each mime-like line has the following structure:

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

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

### Appendix 1) A note on wildcard matching

SREhttp/2 uses a wildcard matching algorithim to determine the best match between a request selector and a set of ATTRIB.CFG entries. This section describes this wildcard matching algorithim.

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.

Special feature: | ending the TARGET with a | means no / or \ can be covered by the final *. Thus, if the selector is: `anim/cats/food.1` then `anim/*food.1` will yield a match, but `anim/*food.1|` will not yield a match (since `cats/` contains a /) The purpose of this feature is to "limit" wildcard matches to a single subdirectory (that is, to prevent matches to items in deeper portions of the directory tree)

#### Some wildcard examples:

`/BILL/DOG.HTM` | will match `/BILL/DOG.HTM`
`/JOE/*` | will match `/JOE/FOO.HTM`
`/JOAN/SRCH.HTM?*` | will match `/JOAN/SRCH.HTM?search+me`
`/JOAN/SRCH.HTM?*` | will not match`/JOAN/SRCH.HTM` (`/JOAN/SRCH.HTM*` will match both these examples)
`/PETS/*FOOD/*INDEX.HTM` | will match `/PETS/FOOD/INDEX.HTM,` `/PETS/CAT/FOOD/INDEX.HTM` and `/PETS/PUPPY/FOOD/LAB/INDEX.HTM` but will not match `/PETS/CAT/PUREBRED.HTM`, and `/PETS/FOOD/HELLO.HTM`
`/STORE/*.JPG|` | will match `/STORE/RADIO.JPG` but will not match `/STORE/DEPT1/TV.JPG`

### Appendix 2) An example of an ATTRIBS.CFG file

    ; 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

### Appendix 3) Redirection in SREhttp/2

The `redirect` action can be used for several types of redirection, aliasing, and reassignment:

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.

For all of the above, one specifies a realm in the default or host-specific `ATTRIBS.CFG` file; a realm with a `rule` that matches the request-selector(s) that you wish to redirect, alias, or reassign. This realm should also contain the appropriate `redirect` option, as described below.

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.

  ### Appendix 4) Using Meta-realms

  Basically, meta-realms allow you to include `meta realm files` into your `ATTRIBS.CFG` file. These `meta realm files` are just like `ATTRIBS.CFG` files -- they contain realm definitions, with each realm containing several attributes; such as the `realm, rule,` and `requires` attributes.

  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.

  - Notes: | meta-realms are defined by using a special realm definition: `realm: META:realm_name` `rule: some_rule` `requires: meta_realm_file`
    Note that | the `realm` must start with `META:` you can define more then one rule, but at least one of them must have a `*` (wildcard) in it. No other attribute is used. In particular, the `requires` attribute is not used for access controls -- it is used to specify a `meta_realm_file`.
  The `meta_realm_file` (that must be relative to the possibly host specific CFG subdirectory) must exist. It should contain realm definitions, just like you would include in an `ATTRIBS.CFG` file. The only difference is that the `rules` used in these realm definitions must be a subset of `some_rule`. Thus, only when a request selector matches a meta-realm `rule` will SREhttp/2 check the realms specified in the corresponding `meta realm file`. Meta-realms are especially useful when you have lots of realms defined by wild-carded (`*`) rules. Checking these rules can be slow. Hence, if you can use meta-realms to group these rules into broad categories, SREhttp/2 can reduce lookup time (matching request selector to a rule) by almost an order of magnitude. The realm names used in the `meta_realm_file` (or the several `meta_realm_files`) should not match realm names defined in the ATTRIBS.CFG file.

  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

  Last updated 15 January 2003