HTTPd Mapping Rules

WASD Hypertext Services - Technical Overview

[next] [previous][contents]

6 - HTTPd Mapping Rules

URLs paths are mapped to physical file system locations using mapping similar to other HTTPd implementations. WASD's is based on the CERN HTTPd implementation, with one additional script mapping rule. By default, the system-table logical name HTTPD$MAP locates a common mapping rule file, unless an individual rule file is specified using a job- table logical name. Simple editing of the mapping file changes the rules. Comment lines may be included by prefixing them with the hash ``#'' character. Although, there is no fixed limit on the number of rules there are the processing implications of scanning a large, linear database.

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

The server administrationrule mapping facility allows arbitrary paths to be checked against the rule database. See 8.1 - HTTPd Server Reports.

Any changes to the mapping file may be (re)loaded into the running HTTPd server using the following command on the server system:

  $ HTTPD /DO=MAP

Also see 5 - HTTPd Configuration for daemon configuration.

6.1 - Current Server Mapping Rules

A server's currently loaded mapping rules may be interrogated. See 8 - HTTPd Server Administration for further information.

6.2 - Rules

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.

  2. pass template
    pass template result

    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 physical VMS file system specification in URL format. If there is a direct correspondance between the template and result the result may be omitted.

    The PASS directive is also used to reverse-map VMS file specifications to the URL format equivalent.

  3. fail template

    If the URL path matches the template, prohibit access, processing no further rules.

REDIRECT Rule

  1. redirect template result

    If the URL path matches the template, substitute the result string for the path. Process no further rules. The result must be a full URL (http://host/path), and is used to redirect requests to another server on a separate host.

This will probably not be used extensively on the internal WASD network.

EXEC and SCRIPT, Script Mapping Rules

EXEC+ and SCRIPT+

Also see 9 - HTTPd Scripting.

The EXEC and SCRIPT directives have the variants EXEC+ and SCRIPT+. The variants behave in exactly the same fashion and simply mark the rule as representing a CGIplus script environment. See 9.6 - CGIplus Scripting. Caution! If changing rules involving these variants it is advised to restart the server rather than reload. Some conflict is possible when using new rules while existing CGIplus scripts are executing.

The EXEC rules maps CGI script directories.

The SCRIPT rules maps CGI script file names. It is a little different to the EXEC rule and an extension to the CERN rules.

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.

  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/* /ht_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 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.

    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 accessable, a possible security concern if script management is distributed.

  2. 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* /ht_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 /script/* /ht_root/script/*
    

Rule Interpretation

The rules are scanned from first towards last, until a pass, exec or fail is encountered, when processing ceases and final substitution occurs. Maped rules substitute the template with the result and continue to the next rule.

Use of wildcards in template and result:

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

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

Examples of Pass Rule

The result string of these rules should correspond to to a VMS physical file path.

Examples of Fail Rule

Examples of Exec and Script Rules

Examples of Redirect Rule

6.3 - Mapping User Directories (tilde character (``~''))

This server will map user directories using the same mechanisms as for any other. No reference is made to SYSUAF.DAT, user support is accomplished via a combination of mapping rule and logical name. This approach relies on a correspondance between the user name and the home directory name. Hence users are made known by the HTTPd using the name of their top-level directory. As the naming of home directories using the user name is a common practice this mechanism should suffice in the majority of cases. Where there is no such correspondance individual rules could be used for each user.

The PASS rule provides a wildcard representation of users' directory paths. As part of this mapping a subdirectory specifically for the hypertext data should be always included. Never map users' top-level directories. For instance if a user's account home directory was located in the area USER$DISK:[DANIEL] the following rule would potentially allow the user DANIEL to provide hypertext information from the home subdirectory [.WWW] (if the user has created it) using the accompanying URL:

  pass /~*/* /user$disk/*/www/*

  http://host/~daniel/

It is recommended that a separate logical name be created for locating user directories. This helps hide the internal organisation of the file system. The following logical name definition and mapping rule illustrate this point.

  $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED WWW_USER device:[USER.]

  pass /~*/* /www_user/*/www/*

Where users are grouped into different areas of the file system a logical search list may be defined.

  $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED -
           WWW_USER -
           DISK1:[GROUP1.], -
           DISK1:[GROUP2.], -
           DISK2:[GROUP3.], -
           DISK2:[GROUP4.]
    
  pass /~*/* /www_user/*/www/*

As logical search lists have specific uses and some complications (e.g. when creating files) this is the only use for them recommended with this server, although it is specifically coded to allow for search lists in document specifications.

If only a subset of all users are to be provided with WWW publishing access either their account directories can be individually mapped (best used only with a small number) or a separate area of the file system be provided for this purpose and specifically mapped as user space.

Of course, user mapping is amenable to all other rule processing so it is a simple matter to redirect or otherwise process user paths. For instance, the published user name does not need to, or need to continue to, correspond to any real user area, or the user's actual name or home area:

  redirect /~doej/* http://a.nother.host/~doej/*
  pass /~doej/* /www/messages/deceased.html
  pass /~danielm/* /special$www$area/danielm/*
  pass /~Mark.Daniel/* /user$disk/danielm/www/*
  pass /~*/* /www_user/*/www/*

A user directory is always presented as a top-level directory (i.e. no parent directory is shown), although any subdirectory tree is accesssable by default.


[next] [previous][contents]