WASD VMS Web Services - Install and Config

16 - Request Processing Configuration
16.1 - Rule Interpretation
16.2 - VMS File System Specifications
16.3 - Traditional File Specifications (ODS-2)
16.4 - Extended File Specifications (ODS-5)
    16.4.1 - Characters In Request Paths
    16.4.2 - Characters In Server-Generated Paths
16.5 - Rules
    16.5.1 - MAP, PASS, FAIL Rules
    16.5.2 - REDIRECT Rule
    16.5.3 - USER Rule
    16.5.4 - EXEC/UXEC and SCRIPT, Script Mapping Rules
    16.5.5 - SET Rule
16.6 - Reverse Mapping
16.7 - Mapping Examples
16.8 - Virtual Servers
16.9 - Conditional Mapping
16.10 - Mapping User Directories (tilde character ("~"))
    16.10.1 - Using The SYSUAF
    16.10.2 - Without Using The SYSUAF
16.11 - Cross Origin Resource Sharing
[next] [previous] [contents] [full-page]

By default, the logical name WASD_CONFIG_MAP locates a common mapping rule file. Simple editing of the mapping file and reloading into the running server changes the processing rules. The [IncludeFile] is a directive common to all WASD configuration, allowing a separate file to be included as a part of the current configuration (4.1 - Include File Directive).

Mapping rules are used for a number of different request processing purposes.

  1. To map a request path onto the VMS file system. That is, to map from web-space into file-space.
  2. To map from file-space back into web-space. There is often not a one-to-one correspondance between file specifcations and web paths.
  3. To process a request path according to specified criteria resulting in an effective path that is different to that supplied with the request.
  4. To identify requests requiring script activation and to parse the script from the path portion of that request. The path portion is then independently re-mapped.
  5. To conditionally map to different end-results based on one or more criteria of the request or environment.
  6. To provide differing virtual sites depending on the actual service accessed by the client.

Mapping is basically for server-internal purposes only. The only time the path information of the request itself is modified is when a script component is removed. At all other times the path information remains unchanged. Path authorization is always applied to the path supplied with the request.

Rules are given a basic consistency check when loaded (i.e. server startup, map reload, etc.) If there is an obvious problem (unknown rule, missing component, etc., path not absolute) a warning message is generated and the rule is not loaded into the database. This will not cause the server startup to fail. These warning messages may be found in the server process log.

Changes to the mapping configuration file can be validated at the command-line before reload or restart. This detects and reports any syntactical and fatal configuration errors but of course cannot check the intent of the rules. 

$ HTTPD /DO=MAP=CHECK

A server's currently loaded mapping rules may also be interrogated from the Server Administration menu (see "WASD VMS Web Services - Features and Facilities"; 8 - Server Administration).

16.1 - Rule Interpretation

The rules are scanned from first towards last, until a matching final rule is encountered (PASS, EXEC, SCRIPT, FAIL, REDIRECT, UXEC and USER) when the mapping pass concludes. Non-final rules (MAP and SET) perform the appropriate action and continue to the next rule. One, two or more passes through the rules may occur due to implicit processing (if the path contains a script component) or by explicit restart (SET map=restart).

String Matching

The basis of path mapping is string pattern matching, comparing the request specified path, and optionally other components of the request when using configuration conditionals (7 - Conditional Configuration), to a series of patterns, usually until one of the patterns matches, at which stage some processing is performed. Both wildcard and regular expression based pattern matching is available. All rules have a template (string pattern to match against the path). Some rules have a result (how to restructure the components matching from the template).

Virtual Servers

As described in 4.3 - Virtual Services virtual service syntax may be used with mapping rules to selectively apply rules to one specific service. If virtual services are configured rule interpretation sees only rules common to all services and those specific to its own service (host address and port). In all other aspects rule interpretation applies as described above.

Processing Overhead

Naturally, each rule that needs to be processed adds a little to consumed CPU, introduces some latency, and ultimately reduces throughput. The test-bench has shown this to be acceptably small compared to the overall costs of responding to a request. Using the ApacheBench tool on a COMPAQ Professional Workstation XP1000 with 2048MB, VMS V8.3, TCP/IP Service 5.7 and WASD v10.1, with a simple access to /wasd_root/exercise/0k.txt showed approximately 744 requests/second throughput using the following mapping file. 

pass /wasd_root/exercise/*

After adding various quantities of the same intervening rule 

pass /wasd_root/example/* 
pass /wasd_root/example/* 
  .
  .
  .
pass /wasd_root/example/* 
pass /wasd_root/exercise/*
the following results were derived.

Mapping Overhead
Intervening RulesRequests/SThroughput
0744baseline
100701-5.8%
200665-10.6%
500571-23.3%
1000461-38.4%

Although this is a fairly contrived set-up and actual real-world rule-sets are more complex than this, even one hundred rules is a very large set, and it does indicate that for all intents and purposes mapping rules may be used to achieve desired objectives without undue concern about impact on server throughput.

16.2 - VMS File System Specifications

The VMS file system in mapping rules is always assumed to begin with a device or concealed device logical. Specifying a Master File Directory (MFD) component, the [000000] is completely optional, although always implied. The mapping functions will always insert one if required for correct file system syntax. That is, if the VMS file system mapping of a path results in a file in a top-level directory an MFD is inserted if not explicitly present in the mapping. For example, both of the following paths 

/dka100/example.txt
/dka100/000000/example.txt
would result in a mapping to 
DKA100:[000000]EXAMPLE.TXT
The MFD is completely optional when both specifying paths in mapping rules and when supplying paths in a request. Similarly, when supplying a path that includes directory components, as in 
/dka100/dir1/dir2/example.txt
/dka100/000000/dir1/dir2/example.txt
both mapping to 
DKA100:[DIR1.DIR2]EXAMPLE.TXT
LOGICAL NAMES
When using logical names in file system mappings they must be able to be used as concealed devices and cannot be logical equivalents of directory specifications. You must be able to perform a 
$ DIRECTORY logical-name:[000000]
to be able to use the specification as a WASD mapping rule.

Concealed device logicals are created using the following syntax: 

$ DEFINE LOGICAL_NAME device:[dir1.dir2.]
$ DEFINE LOGICAL_NAME /TRANSLATION=CONCEALED physical_device:[dir1.dir2.]
$ DEFINE LOGICAL_NAME /TRANSLATION=CONCEALED -
physical_device1:,physical_device2:
$ DEFINE LOGICAL_NAME /TRANSLATION=CONCEALED -
physical_device3:[dir1.dir2.],physical_device4:[dir1.dir3.]

The logical name may be multi-valued and provided the DIRECTORY command can be used successfully with them (as described above) should be amenable to WASD directory listing producing equivalent results.

16.3 - Traditional File Specifications (ODS-2)

For ODS-2 volumes, when during rule mapping of a path to a VMS file specification an RMS-invalid character (e.g. "+") or syntax (e.g. multiple periods) is encountered a dollar symbol is substituted in an attempt to make it acceptable. This functionality is often useful for document collections imported to the local web originating from, for instance, a Unix site that utilizes non-VMS file system syntax. The default substitution character may be changed on a per-path basis using the SET rule (16.5.5 - SET Rule).

16.4 - Extended File Specifications (ODS-5)

OpenVMS Alpha V7.2 introduced a new on-disk file system structure, ODS-5. This brings to VMS in general, and WASD and other Web servers in particular, a number of issues regarding the handling of characters previously not encountered during (ODS-2) file system activities. ODS-2 and ODS-5 volumes should be automatically distinguished by the server however it is possible to force interpretation using a path mapping rule (16.5.5 - SET Rule).

16.4.1 - Characters In Request Paths

There is a standard for characters used in HTTP requests paths and query strings (URLs). This includes conventions for the handling of reserved characters, for example "?", "+", "&", "=" that have specific meanings in a request, characters that are completely forbidden, for example white-space, control characters (0x00 to 0x1f), and others that have usages by convention, for example the "~", commonly used to indicate a username mapping. The request can otherwise contain these characters provided they are URL-encoded (i.e. a percentage symbol followed by two hexadecimal digits representing the hexadecimal-encoded character value).

There is also an RMS standard for handling characters in extended file specifications, some of which are forbidden in the ODS-2 file naming conventions, and others which have a reserved meaning to either the command-line interpreter (e.g. the space) or the file system structure (e.g. the ":", "[", "]" and "."). Generally the allowed but reserved characters can be used in ODS-5 file names if escaped using the "^" character. For example, the ODS-2 file name "THIS_AND_THAT.TXT" could be named "This^_^&^_That.txt" on an ODS-5 volume. More complex rules control the use of character combinations with significance to RMS, for instance multiple periods. The following file name is allowed on an ODS-5 volume, "A-GNU-zipped-TAR-archive^.tar.gz", where the non-significant period has been escaped making it acceptable to RMS.

The WASD server will accept request paths for file specifications in both formats, URL-encoded and RMS-escaped. Of course characters absolutely forbidden in request paths must still be URL-encoded, the most obvious example is the space. RMS will accept the file name "This^ and^ that.txt" (i.e. containing escaped spaces) but the request path would need to be specified as "This%20and%20that.txt", or possibly "This^%20and^%20that.txt" although the RMS escape character is basically redundant.

Unlike for ODS-2 volumes, ODS-5 volumes do not have "invalid" characters, so no processing is performed to ensure RMS compliance.

16.4.2 - Characters In Server-Generated Paths

When the server generates a path to be returned to the browser, either in a viewable page such as a directory listing or error message, or as a part of the HTTP transaction such as a redirection, the path will contain the URL-encoded equivalent of the canonical form of an extended file specification escaped character. For example, the file name "This^_and^_that.txt" will be represented by "This%20and%20that.txt".

When presenting a file name in a viewable page the general rule is to also provide this URL-equivalent of the unescaped file name, with a small number of exceptions. The first is a directory listing where VMS format has been requested by including a version component in the request file specification. The second is in similar fashion, but with the tree facility, displaying a directory tree. The third is in the navigation page of the UPDate menu. In all of the instances the canonical form of the extended file specification is presented (although any actual reference to the file is URL-encoded as described above).

16.5 - Rules

These are the categories of mapping rules.

16.5.1 - MAP, PASS, FAIL Rules

  1. map template result

    If the URL path matches the template, substitute the result string for the path and use that for further rule processing. Both template and result paths must be absolute (i.e. begin with "/").

  2. pass template
    pass template result
    pass template "999 message text"

    If the URL path matches the template, substitute the result if present (if not just use the original URL path), processing no further rules.

    The result should be a either a physical VMS file system specification in URL format or an HTTP status-code message (see below). If there is a direct correspondance between the template and result the result may be omitted.

    NOTE
    The PASS directive is also used to reverse-map VMS file specifications to the URL path format equivalent. See 16.6 - Reverse Mapping.

    An HTTP status-code message can be provided as a result. The server then generates a response corresponding to that status code containing the supplied message. Status-code results should be enclosed in one of single or double quotes, or curly braces. See examples. A 3nn status results in a redirection response with the message text comprising the location. Codes 4nn and 5nn result in an error message. Other code ranges (e.g. 0, 1nn, 2nn, etc.) simply cause the connection to be immediately dropped, and can be used for that purpose (i.e. no indication of why!)

  3. fail template

    If the URL path matches the template, prohibit access, processing no further rules. The template path must be absolute (i.e. begin with "/").

16.5.2 - REDIRECT Rule

  1. redirect template result

    If the URL path matches the template, substitute the result string for the path. Process no further rules. Redirection rules can provide result URLs in one of a number of formats, each with a slightly different behaviour.

    1. The result can be a full URL ("http://host.domain/path/to/whatever"). This is used to redirect requests to a specific service, usually on a another host. A result may or may not contain a fixed query string ("/path/to/whatever?one=two").
    2. If the scheme (e.g. "http:") is omitted the scheme of the current request is substituted. This allows HTTP requests to be transparently redirected via HTTP and HTTPS (SSL) requests via HTTPS (e.g. "//host.domain/path/to/whatever", note the leading double-slash).
    3. In a similar fashion both the scheme and the host name may be omitted (e.g. "///path/to/whatever", note the leading triple-slash). The server then substitutes the appropriate request scheme and host name before returning the redirection to the client.
    4. If the scheme is provided but no host component the current request's host information is substituted and the redirection made using that (e.g. "https:///secure/path/to/whatever". This effectively allows a request to be redirected from standard to SSL, or from SSL to standard HTTP on the same server.
    5. Alternatively, it may be just a path ("/path/to/whatever", a single leading slash), which will cause the server to internally generate an entire new request structure to process the new path (i.e. request redirection is not returned to the client).
      NOTE
      Internal redirection (as this is termed) is a fundamental mechanism available with WASD to completely change the request path and/or query string components for the request - transparently to the client. It is essentially a complete rewrite of the request.
    6. Full request URI rewriting (path and any query string) is available using the map=uri path SETing (16.5.5 - SET Rule).
    7. Only if the last character in the result is a question mark ("?") will any query string in the original be propagated into the redirection URL (that is the original request "/original/test.txt?plus=query" is mapped using "redirect /original/* /path/to/*?" does the resulting URL become "/path/to/test.txt?plus=query").

16.5.3 - USER Rule

The USER rule maps a VMS user account default device and directory (i.e. home directory) into a request path. That is, the base location for the request is obtained from the VMS systems SYSUAF file. This is usually invoked by a request path in the form "/~username/", see 16.10 - Mapping User Directories (tilde character ("~")) for more detailed information.

  1. user template result

    If the path matches the template then the result is substituted, with the following conditions. At least one wildcard must be present. The first wildcard in the result substitutes the username's home directory into the path (in place of the "~username"). Any subsequent wildcard(s) substitute corresponding part(s) of the original path.

    If the user DANIEL's default device and directory were 

    USER$DISK:[DANIEL]
    the following rule 
    user /~*/* /*/www/*
    would result in the following path being mapped and used 
    /user$disk/daniel/www/

NOTE
Accounts that possess SYSPRV, are CAPTIVE, have been DISUSERED or that have expired passwords will not be mapped. A "directory not found" error report is returned.

16.5.4 - EXEC/UXEC and SCRIPT, Script Mapping Rules

Also see WASD Web Services - Scripting for further information.

The EXEC/UXEC and SCRIPT directives have the variants EXEC+/UXEC+ and SCRIPT+. These behave in exactly the same fashion and simply mark the rule as representing a CGIplus script environment.

The EXEC/UXEC rules maps script directories.

The SCRIPT rules maps script file names. It behaves a little differently to the EXEC rule, essentially supplying in a single rule the effect of a MAP then an EXEC rule.

Both rules must have a template and result, and both must end in a wildcard asterisk. The placement of the wildcards and the subsequent functionality is slightly different however. Both template and result paths must be absolute (i.e. begin with "/").

  1. exec template result

    The EXEC rule requires the template's asterisk to immediately follow the slash terminating the directory specification containing the scripts. The script name follows immediately as part of the wildcard-matched string. For example: 

    exec /htbin/* /wasd_root/script/*

    If the URL path matches the template, the result, including the first slash-terminated part of the wildcard-matched section, becomes the URL format physical VMS file specification the script to be executed. What remains of the original URL path is used to create the path information. Process no further rules.

    Hence, the EXEC rule will match multiple script specifications without further rules, the script name being supplied with the URL path. Hence any script (i.e. procedure, executable) in the specified directory is accessible, a possible security concern if script management is distributed.

  2. exec template (run-time-environment)result

    A variation on the "exec" rules allows a Run-Time Environment (RTE) to be mapped. An RTE is a persistant scripting environment not unlike CGIplus. The essential difference is an RTE provides an environment in which a variety of scripts can be run. It is often an interpreter, such as Perl, where the advantages of persistance (reduced response latency and system impact) are available. For more information on RTEs and how they operate see the WASD Scripting Environment document.

    The RTE executable is specified in parentheses prefixed to the mapping result, as show in this example: 

    exec /pl-bin/* (cgi-bin:[0000000]perlrte.exe)/wasd_root/src/perl/*

  3. script template result

    The SCRIPT rule requires the template's asterisk to immediately follow the unique string identifying the script in the URL path. The wildcard-matched string is the following path, and supplied to the script. For example: 

    script /conan* /wasd_root/script/conan*

    If the URL path matches the template, the result becomes the URL format physical VMS file specification for the DCL procedure of the script to be executed (the default file extension of ".COM" is not required). What remains of the original URL path is used to create the path information. Process no further rules.

    NOTE
    The wildcard asterisk is best located immediately after the unique script identifier. In this way there does not need to be any path supplied with the script. If even a slash follows the script identifier it may be mapped into a file specification that may or may not be meaningful to the script.

    Hence, the SCRIPT rule will match only the script specified in the result, making for finely-granular scripting at the expense of a rule for each script thus specified. It also implies that only the script name need precede any other path information.

    It may be thought of as a more efficient implementation of the equivalent functionlity using two CERN rules, as illustrated in the following example: 

    map /conan* /script/conan*
exec /cgi-bin/* /cgi-bin/*

  4. uxec template result

    The UXEC rule is an analog to the EXEC rule, except it is used to map user scripts. It requires two mapping asterisks, the first for the username, the second for the script name. It must be used in conjunction with a SET script=as=~ rule. For example: 

    SET   /~*/cgi-bin/*  script=as=~
UXEC  /~*/cgi-bin/*  /*/www/cgi-bin/*

    For further information see User Account Scripting and the "Scripting Overview, Introduction".

Script Location

It is conventional to locate script images in WASD_ROOT:[AXP-BIN] or WASD_ROOT:[VAX-BIN] (depending on the platform), and procedures, etc. in WASD_ROOT:[CGI-BIN]. These multiple directories are accessible via the single search list logical CGI-BIN.

Script files can be located in area completely outside of the WASD_ROOT tree. Two approaches are available.

  1. Modify the search list CGI-BIN to include the additional directories. Only should be done with extreme care.
  2. Use mapping rules to make the script accessible. This can be done by using the EXEC or SCRIPT rule to specify the directory directly as in these examples 
    exec /mycgi-bin/* /site_local_scripts/bin/*
script /myscript* /web/myscripts/bin/myscript.exe*
    or by using the MAP rules to make a hierarchy of script locations obvious and accessible, as in this example 
    map /cgi-bin/myscripts/* /cgi-bin_myscripts/* 
exec /cgi-bin_myscripts/* /web/myscripts/bin/*

EXEC Directories and EXEC Files

Generally directories are specified as locations for script files. This is the more common application, with the EXEC rules used as in this example 

exec /cgi-bin/* /cgi-bin/*

Mapping a file type into an EXEC behaviour is also supported. This allows all files within the specified path and with the matching file suffix (extension) to be activated as scripts. Of course a script runtime must be available for the server to be able activate it. The following example demonstrates mapping all files ending in .CGI in the /web/ tree as executable scripts. 

exec /web/*.cgi* /web/*.cgi*
WARNING
Remember scripts are executables. Enabling scripting in a general user area allows any user to write and execute any script, by default under the scripting account. Deploy with discretion.

16.5.5 - SET Rule

The SET rule does not change the mapping of a path, it just sets one or more characteristics against that path that affect the subsequent processing in some way. It is a general purpose rule that conveniently allows the administrator to tell the server to process requests with particular paths in some ad hoc and generally useful fashion. Most SET parameters are single keywords that act as boolean switches on the request, some require parameter strings. Multiple space-separated parameters may be set against against the one path in a single SET statement.

Of course, as with all mapping rules, paths containing file types (extensions) may be specified so it is quite easy to apply settings to particular groups of files. Multiple settings may be made against the one path, merely separate set directives from each other with white-space. If a setting string is required to contain white-space enclose the string with single or double quotes, or curly brackets. The following example gives a small selection of potential uses. 

# examples of SET rule usage
# --------------------------
# disable caching for selected paths
set /wasd_root/src/* NOcache
set /sys$common/* NOcache
# enable stream-LF conversion in selected directory trees
set /web/* stmlf
set /wasd_root/* stmlf
# respond with Cyrillic character set(s) from relevant directories
set /*/8859-5/* charset=ISO-8859-5
set /*/koi8-r/* charset=KOI8-R
# the Sun Java tutorial when UNZIPped contains underscores for invalid characters
set /vms/java/tutorial/* RMSchar=_
# if a request has "/plain-text/" in its path then ALWAYS return as plain-text!
set /*/plain-text/* content=text/plain
map /*/plain-text/* /*/*
# same for "/binary/"
set /*/binary/* content=text/plain
map /*/binary/* /*/*
# indicate extended file specifications on this path
set /Documents/* ODS=5
pass /Documents/* /ods5_device/Documents/*
# throttle this script's execution, 5 executing, unlimited waiting
set /cgi-bin/big_script* throttle=5
# disable server script search for this RTE
set /onerte/*  script=nofind
exec /onerte/* (CGI-BIN:[000000]ONERTE.EXE)/wasd_root/src/one/*

Postfix SET Rule

Path SETings may appended to any rule that contains both a template and result. This makes it possible to apply path SETings using matching final rules. For example a matching PASS rule does not require a separate, preceding SET rule containing the same path to also apply required SETings. This is more efficient (requiring less pattern matching) and tends to make the rule set less cluttered. 

# examples of postfix SET rule usage
# ----------------------------------
# if a request has "/plain-text/" in its path then ALWAYS return as plain-text!
map /*/plain-text/* /*/* content=text/plain
# same for "/binary/"
map /*/binary/* /*/* content=text/plain
# indicate extended file specifications on this path
pass /Documents/* /ods5_device/Documents/* ODS=5
# throttle this script's execution, 5 executing, unlimited waiting
script /big_script* /cgi-bin/big_script* throttle=5

16.6 - Reverse Mapping

Path mapping is required to get from web-space into file-space, and that mapping is not necessarily one-to-one. That is, /web/doc/ may not be WEB:[DOC] but for example, DKA0:[WEB.DOC] so that mapping would be 

pass /web/* /dka0/web/*

Mapping paths in reverse is needed to get something like DKA0:[WEB.DOC]THIS.TXT (that may come from a $SEARCH result) back into the web-space of /web/doc/this.txt. So WASD needs paths that may be mapped using the result back to the template. In simple mappings the one rule can serve both purposes. In some situations explicit, extra rules are needed.

The above example is trivial, and if WASD needs to turn something like DKA0:[DOC]THIS.TXT into a web-space representation (URI) it makes the file-space specification into URI syntax (i.e. /dka0/web/doc/this.txt) and then scans the rules comparing that to result strings in the MAP rules. When one matches, the template component is used to generate a web-space representation - the reverse of what was done when the request was initially being processed.

The non-trivial example is often associated with concealed, search-list devices. For example, the somewhat contrived 

$ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DKA100:[WEB1.],DKA200:[WEB2.]
with which the mapping from web- to file-space can be 
pass /web/* /web/*
using the logical device, and quite naturally maps into file-space. WASD's file-system actions are complex and low-level, often needing to access to the underlying device (and so tend to $PARSE NOCONCEAL). Results from the above mapping can come back DKA100:[WEB1]THIS.TXT and DKA200:[WEB2]THAT.TXT and so the above mapping can't be used to get back into web-space because there is no template with a matchable rule.

In such a case there is a need to add explicit reverse-mapping rules (often immediately following the forward mapping rule for convenience of grouping, but rules are also a little position sensitive so some skill is required) for the purpose of getting the underlying file specifications into a form for web consumption. In the above scenario an example would be 

pass /web/* /web/*
pass /web/* /dka100/web1/*
pass /web/* /dka200/web2/*
where the latter two are never hit during forward mapping (because the first rule will always map a request URI beginning /web/...) but will be hit during reverse-mapping. If a reverse mapping exhausts the rules before finding a match the NO:[REVERSE.MAPPING.FOR.THIS]FILE.PATH! mapping is explicitly generated.

It is not always straight-forward and sometimes a decision is necessary about how the web-space is to be presented to the clients. For instance, while you easily can have multiple web-space views of the one file-space area, it is less straight-forward to have multiple web-space reverse mappings of the one file-space (as normally only the first matching rule will ever be reverse-mapped).

16.7 - Mapping Examples

The example mapping rule file for the WASD HTTP server can be viewed.

Example of Map Rule

The result string of these rules may or may not correspond to to a VMS physical file system path. Either way the resulting rule is further processed before passing or failing.

  1. The following example shows a path "/web/unix/shells/c" being mapped to "/web/software/unix/scripts/c", with this being used to process further rules. 
    map /web/unix/* /web/software/unix/*

Examples of Pass Rule
  1. This example shows a path "/web/rts/home.html" being mapped to "/user$rts/web/home.html", and this returned as the mapped path. 
    pass /web/rts/* /user$rts/web/*
  2. This maps a path "/icon/bhts/dir.gif" to "/web/icon/bhts/dir.gif", and this returned as the mapped path. 
    pass /icon/bhts/* /web/icon/bhts/*
  3. This example illustrates HTTP status code mapping. Each of these does basically the same thing, just using one of the three possible delimiters according to the characters required in the message. The server generates a 403 response with has as its text the following message. (Also see the conditional mapping examples.) 
    pass /private/* "403 Can't go in there!"
pass /private/* '403 "/private/" is off-limits!'
pass /private/* {403 Can't go into "/private/"}

Examples of Fail Rule
  1. If a URL path "/web/private/home.html" is being mapped the path would immediately be failed. 
    fail /web/private/*
  2. To ensure all access fails, other than that explicitly passed, this entry should be included the the rules. 
    fail /*

Examples of Exec and Script Rules

  1. If a URL path "/htbin/ismap/web/example.conf" is being mapped the "/wasd_root/script/" must be the URL format equivalent of the physical VMS specification for the directory locating the script DCL procedure. The "/web/example.conf" that followed the "/htbin/ismap" in the original URL becomes the translated path for the script. 
    exec /cgi-bin/* /cgi-bin/*
  2. If a URL path "/pl-bin/example/this/directory/and-file.txt" is being mapped the script name and filename become "/pl-bin/example" and "WASD_ROOT:[SRC.PERL]EXAMPLE.PL" respectively, the path information and translated become "/this/directory/and-file.txt" and "THIS:[DIRECTORY]AND-FILE.TXT", and the interpreter (run-time environment) activated to interpret the script is CGI-BIN:[000000]PERLRTE.EXE. 
    exec /pl-bin/* (cgi-bin:[000000]perlrte.exe)/wasd_root/src/perl/*
  3. If a URL path "/conan/web/example.hlb" is being mapped the "/wasd_root/script/conan" must be the URL format equivalent of the physical VMS specification for the DCL procedure. The "/web/example.hlb" that followed the "/conan/" in the original URL becomes the translated path for the script. 
    script /conan* /wasd_root/script/conan*

Example of Redirect Rule
  1. If a URL path "/AnotherGroup/this/that/other.html" is being mapped the URL would be redirected to "http://host/this/that/other.html" 
    redirect /AnotherGroup/* http://host/group/*

16.8 - Virtual Servers

As described in 4.3 - Virtual Services, virtual service syntax may be used with mapping rules to selectively apply rules to one specific service. This example provides the essentials of using this syntax. Note that service-specific and service-common rules may be mixed in any order allowing common mappings (e.g. for scripting) to be shared. 

# a mapping rule example of virtual servers
[[alpha.domain.name:80]]
# ALPHA is the only service allowing access to VMS help directory
pass /sys$common/syshlp/*
[[beta.domain.name:80]]
# good stuff is only available from BETA
pass /good-stuff/*
# BETA has its own error report format, the others share one
pass /errorreport /httpd/-/errorreportalpha.shtml  
[[gamma.domain.name:80]]
# gamma responds with documents using the Cyrillic character set
set /* charset=ISO-8859-5
[[*]]
# common file and script mappings
exec /cgi-bin/* /cgi-bin/*
exec+ /cgiplus-bin/* /cgi-bin/*
script+ /help/* /cgiplus-bin/conan/*
pass /errorreport /httpd/-/errorreport.shtml  
# now the base directories for all documents
[[alpha.domain.name:80]]
/* /web/alpha/*
[[beta.domain.name:80]]
/* /web/beta/*
[[gamma.domain.name:80]]
/* /web/gamma/*
[[*]]
# catch-all rule (just in case :-)
pass /* /web/*

The Server Administration page WATCH report provides the capability to view the rule databse as well as rule mapping during actual request processing, using the WATCH facility.

16.9 - Conditional Mapping

Deprecated and Discouraged
See 7 - Conditional Configuration for current funtionality.

As this has been deprecated for some years now the documentation for this functionality has been removed.

For backward-reference see the "WASD Hypertext Services - Technical Overview" document for release v9.3 or earlier.

16.10 - Mapping User Directories (tilde character ("~"))

The convention for specifying user web areas is "/~username/". The basic idea is that the user's web-available file-space is mapped into the request in place of the tilde and username.

16.10.1 - Using The SYSUAF

The USER rule maps a VMS user account default device and directory (i.e. home directory) into a request path (16.5.3 - USER Rule). That is, the base location for the request is obtained from the VMS systems SYSUAF file. A user's home directory information is cached, to reduce load on the authorization databases. As this information is usually quite static there is no timeout period on such information (although it may be flushed to make room for other user's). Cache contents is include in the Mapping Rules Report and is implicitly flushed when the server's rules are reloaded.

The following is a typical usage of the rule. 

USER  /~*/*  /*/www/*

Note the "/www" subdirectory component. It is stongly recommended that users never be mapped into their top-level, but into a web-specific subdirectory. This effectively "sandboxes" Web access to that subdirectory hierarchy, allowing the user privacy elsewhere in the home area.

To accomodate request user paths that do not incorporate a trailing delimiter after the username the following redirect may be used to cause the browser to re-request with a more appropriate path (make sure it follows the USER rule). 

REDIRECT  /~*  ///~*/

WASD also "reverse maps" VMS specifications into paths and so requires additional rules to provide these mappings. (Reverse mapping is required during directory listings and error reporting.) For the continuing example the following rules would be required (and in the stated order). 

USER  /~*/*  /*/www/*
REDIRECT  /~*  ///~*/
PASS  /~*/*  /user$disk/*/www/*

Where user home directories are spread over multiple devices (physical or concealed logical) a reverse-mapping rule would be required for each. Consider the following situation, where user directories are distributed across these devices (concealed logicals) 

USER$GROUP1:
USER$GROUP2:
USER$GROUP2:
USER$OTHER:

This would require the following mapping rules (in the stated order). 

USER  /~*/*  /*/www/
PASS  /~*/*  /user$group1/*/www/*
PASS  /~*/*  /user$group2/*/www/*
PASS  /~*/*  /user$group3/*/www/*
PASS  /~*/*  /user$other/*/www/*

Accounts with a search list as a default device (e.g. SYS$SYSROOT) present particular complications in this schema and should be avoided.

NOTE
Accounts that possess SYSPRV, are CAPTIVE, have been DISUSERED or that have expired passwords will not be mapped. A "directory not found" error report is returned. This error was chosen to make it to make more difficult to probe the authorization environment, determining whether accounts exist or not.

Of course vanilla mapping rules may be used to provide for special cases. For instance, if there is requirement for a particular, privileged account to have a user mapping that could be provided as in the following (rather exagerated) example. 

PASS  /~system/*  /sys$common/sysmgr/www/*
USER  /~*/*  /*/www/
PASS  /~*/*  /user$disk/*/www/*

User Account Scripting

In some situations it may be desirable to allow the average Web user to experiment with or implement scripts. With WASD 7.1 and later, and VMS V6.2 and later, this is possible. Detached scripting must be enabled, the /PERSONA startup qualifier used, and appropriate mapping rules in place. If the SET "script=as=" mapping rule specifies a tilde character then for a user request the mapped SYSUAF username is substituted.

The following example shows the essentials of setting up a user environment where access to a subdirectory in the user's home directory, [.WWW] with script's located in a subdirectory of that, [.WWW.CGI-BIN]. 

UXEC  /~*/cgi-bin/*  /*/www/cgi-bin/*  script=as=~ 
USER  /~*/*  /*/www/*
REDIRECT  /~*  /~*/
PASS  /~*/*  /dka0/users/*/*

For more detailed information see the "Scripting Overview, Introduction".

16.10.2 - Without Using The SYSUAF

Deprecated and Discouraged
See 16.10 - Mapping User Directories (tilde character ("~")) for current funtionality.

As this has been deprecated for some years now the documentation for this functionality has been removed.

For backward-reference see the "WASD Hypertext Services - Technical Overview" document for release v9.3 or earlier.

16.11 - Cross Origin Resource Sharing

Cross-site HTTP requests are HTTP requests for resources from a domain different to the domain of the resource making the request. For instance, a resource loaded from domain one (http://domain.example) such as an HTML web page, makes a request for a resource on domain two (http://domain.foo), such as an image, using the img element (http://domain.foo/image.jpg). This occurs very commonly on the web today. Pages load a number of resources in a cross-site manner, including CSS stylesheets, images and scripts, and other resources.

Cross-site HTTP requests initiated from within browser-based applications have been subject to well-known restrictions, for well-understood security reasons. In particular, this meant that an actively processing web application could only make HTTP requests to the domain it was loaded from, and not to other domains. Developers expressed the desire to safely evolve capabilities to make cross-site requests, for better, safer web applications. The Web Applications Working Group within the W3C has recommended the new Cross-Origin Resource Sharing (CORS) mechanism, which provides a way for web servers to support cross-site access controls, which enable secure cross-site data transfers.

Basic References

This section is not a CORS reference, just the WASD implementation. Readers are referred to more authoritative CORS resources.

http://www.w3.org/TR/cors/
http://www.html5rocks.com/en/tutorials/cors/
http://en.wikipedia.org/wiki/Cross-origin_resource_sharing
http://developer.mozilla.org/en-US/docs/HTTP/Access_control_CORS

WASD CORS

WASD supports CORS using mapping rules. This means cross-origin requests are evaluated prior to accessing any resources or activating any scripts, etc. If the request has an "Origin: .." header and the path has been set cors=origin=.. the server performs preflighted and request checks. If CORS authorised adds CORS response headers. If not CORS authorised adds nothing. Some significant understanding of the purpose and operation of CORS is required to tailor the provision of the required response headers.

RuleDescription
CORS=AGE=integer seconds Access-Control-Max-Age: response header
CORS=CRED=true|false Access-Control-Allow-Credentials: response header
CORS=EXPOSE=header[,header2,header3] Access-Control-Expose-Headers: response header
CORS=HEADERS= Access-Control-Allow-Headers: response header
CORS=METHODS=method[,method2,method3] Access-Control-Allow-Methods: response header
CORS=ORIGIN=URL|* Access-Control-Allow-Origin: response header

WASD CORS Examples

  1. For a request containing 

    OPTIONS /resources/post-here/ HTTP/1.1
Host: bar.other
...
Origin: http://foo.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER
    with the mapping rules 
    SET /resources/post-here/* \
    CORS=origin=* CORS=methods=POST,GET,OPTIONS \
    CORS=headers=X-PINGOTHER CORS=age=3600
    would produce a response 
    HTTP/1.1 200 OK
...
Content-Length: 0
Connection: Keep-Alive
Content-Type: text/plain
Access-Control-Allow-Origin: http://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER
Access-Control-Max-Age: 3600

  2. For a request containing 

    GET /resources/credentials/ HTTP/1.1
Host: bar.other
...
Connection: keep-alive
Referer: http://foo.example/examples/credential.html
Origin: http://foo.example
    with the mapping rules 
    SET /resources/credentials/* \
    CORS=origin=http://foo.example CORS=credEntials=true
    would produce a response 
    HTTP/1.1 200 OK
...
Content-Length: 106
Connection: Keep-Alive
Content-Type: text/plain
Access-Control-Allow-Origin: http://foo.example
Access-Control-Allow-Credentials: true

...

[next] [previous] [contents] [full-page]