                                     ?                                         WASD Hypertext Services <                                         - Technical Overview      %                    5th September 1998   I                    Version 5.2 release of the WASD VMS Hypertext Services 0                    HTTP server (September 1998).                      Supercedes:  *                      23rd July 1998 (v5.1)+                      30th March 1998 (v5.0) .                      15th November 1997 (v4.5),                      1st October 1997 (v4.4)+                      1st August 1997 (v4.3) )                      1st July 1997 (v4.2) )                      1st June 1997 (v4.1) ,                      1st October 1996 (v3.4)G                      1st December 1995 (initial freeware release, v3.1) +                      9th August 1995 (v2.3) (                      1st May 1995 (v2.1)                      Please Note  G                    As of July 1997 High Frequency Radar Division (HFRD) F                    underwent a change of role and name. It is now WideF                    Area Surveillance Division (WASD). This package has8                    been renamed in accordance with that.                      Abstract   I                    This document is a technical overview of the implemen- H                    tation of the WASD VMS HyperText Transport Daemon. ItH                    contains information on server startup, configurationG                    and CGI scripting. Previous versions contained brief H                    descriptions of the major code modules of the server,I                    these have now been removed to a document of their own                     (see below).                  H                    Also see "WASD Hypertext Environment" for informationE                    on using the WASD VMS Hypertext Services and "WASD F                    Nuts and Bolts" for technical information on server-                    design and implementation.   H                    It is strongly suggested those using printed versionsI                    of this document also access the Hypertext version. It @                    provides online access to some examples, etc.                      Author   !                    Mark G. Daniel 8                    Senior Information Technology Officer2                    Wide Area Surveillance Division>                    Defence Science and Technology Organisation  2                    Mark.Daniel@dsto.defence.gov.au  )                    +61 (8) 82596031 (bus) )                    +61 (8) 82596673 (fax)                       PO Box 1500                    Salisbury'                    South Australia 5108                       Printed Copy   ?                    This book may be available for printing to a F                    PostScript printer. Use a browser to access a print.                    menu in this same location.  E                    Some of the online demonstrations may not work due C                    to the local organisation of the Web environment G                    differing from WASD where it was originally written.                                              ii                 .                    WASD VMS Hypertext Services  8                    Copyright  1996-1998 Mark G. Daniel.  I                    This package is free software; you can redistribute it F                    and/or modify it under the terms of the GNU GeneralC                    Public License as published by the Free Software E                    Foundation; version 2 of the License, or any later                     version.   G                    This package is distributed in the hope that it will H                    be useful, but WITHOUT ANY WARRANTY; without even theG                    implied warranty of MERCHANTABILITY or FITNESS FOR A I                    PARTICULAR PURPOSE. See the GNU General Public License $                    for more details.  E                    You should have received a copy of the GNU General H                    Public License along with this package; if not, writeG                    to the Free Software Foundation, Inc., 675 Mass Ave, ,                    Cambridge, MA 02139, USA.                       Eric A. Young  B                    This package can include cryptographic softwareI                    (SSLeay) copyright by Eric Young (eric@CryptSoft.com):   ]                       This library is free for commercial and non-commercial use provided ... N                       Eric Young should be given attribution as the author ...2                       copyright notice is retained  #                    MadGoat Software   H                    For supporting non-Digital-TCP/IP (UCX) this software>                    uses the NETLIB package by Matthew Madison:  H                       permission is granted to copy and redistribute ...,                       for no commercial gain  (                    Ohio State University  G                    This package contains software provided with the OSU F                    (DECthreads) HTTP server package, authored by David                    Jones:   D                       Copyright 1994,1997 The Ohio State University.V                       The Ohio State University will not assert copyright with respectT                       to reproduction, distribution, performance and/or modificationS                       of this program by any person or entity that ensures that all U                       copies made, controlled or distributed by or for him or it bear S                       appropriate acknowlegement of the developers of this program.   N                                                                            iii                 $                    RSA Data Security  G                    This software contains code derived in part from RSA &                    Data Security, Inc:  \                       permission granted to make and use derivative works provided that suchW                       works are identified as "derived from the RSA Data Security, Inc. ]                       MD5 Message-Digest Algorithm" in all material mentioning or referencing '                       the derived work.   #                    Bailey Brown Jr.   G                    LZW compression is implemented using code derived in I                    part from the PBM suite. This code is copyright by the #                    original author:   X                       * GIF Image compression - LZW algorithm implemented with Tree type:                       *                         structure.L                       *                         Written by Bailey Brown, Jr.H                       *                         last change May 24, 1990?                       *                         file: compgif.c                        * \                       *  You may use or modify this code as you wish, as long as you mention7                       *  my name in your documentation.                       Other  G                    OpenVMS, Digital TCP/IP Services for OpenVMS, VAX C, %                    DEC C, VAX and AXP A                    are registered trademarks of Digital Equipment                     Corporation.   G                    MultiNet is a registered trademark of Cisco Systems,                     Inc.   H                    Pathway is a registered trademark of Attachmate, Inc.  H                    TCPware is a registered trademark of Process Software                    Corporation.                                    iv                       P                Contents_________________________________________________________  P                Chapter_1__Introduction__________________________________________      P                Chapter_2__HyperText_Transport_Protocol_Daemon_-_Overview________  P                2.1    Server Features........................................2-1  P                2.2    Server Behaviour.......................................2-2  P                2.3    TCP/IP Packages........................................2-3  P                2.4    International Features.................................2-4  P                2.5    HTTP Methods Usage.....................................2-5  P                       2.5.1     GET..........................................2-6  P                       2.5.2     POST & PUT...................................2-6  P                       2.5.3     DELETE.......................................2-8  P                Chapter_3__New_to_WASD?_Start_Here!______________________________  P                Chapter_4__Installation_and_Update_______________________________  P                4.1    Installation DCL Procedure.............................4-3  P                4.2    Update DCL Procedure...................................4-4  P                4.3    Quick-Check............................................4-5  P                4.4    Re-Linking.............................................4-5  P                4.5    Local Setup Suggestions................................4-6  P                4.6    Organizing Documents...................................4-6  P                4.7    Reporting Problems.....................................4-8  P                Chapter_5__Server_Account_and_Environment________________________  P                5.1    VMS Account............................................5-1  P                5.2    Account Support Files..................................5-2  P                5.3    HTTPd Command Line.....................................5-6  P                       5.3.1     Server Startup...............................5-6  1                                               iii                  M                    5.3.2     Server Command Line Control..................5-7   M                      5.3.2.1       Accounting.............................5-8   M                      5.3.2.2       Authentication.........................5-8   M                      5.3.2.3       Cache..................................5-8   M                      5.3.2.4       DCL/Scripting Subprocesses.............5-8   M                      5.3.2.5       DECnet Scripting Connections...........5-9   M                      5.3.2.6       Logging................................5-9   M                      5.3.2.7       Mapping................................5-9   M                      5.3.2.8       Shutdown and Restart..................5-10   M             5.4    Multi-Homed Hosts With Digital TCP/IP.................5-10   M             Chapter_6__Server_Configuration__________________________________   M             6.1    Content-Type Configuration.............................6-1   M                    6.1.1     Explicitly Specifying Content-Type...........6-2   M             6.2    Directives.............................................6-3   M             6.3    Multi-Homed and Multi-Port Services...................6-15   M             6.4    Access Logging........................................6-16   M                    6.4.1     Log Format..................................6-16   M                    6.4.2     Log Period..................................6-18   M                    6.4.3     Log Per-Service.............................6-19   M                    6.4.4     Log Naming..................................6-19   M             Chapter_7__Message_Configuration_________________________________   M             7.1    Behaviour..............................................7-1   M             7.2    Message File Format....................................7-2   M             7.3    Supplied Message Files.................................7-4   M             Chapter_8__Mapping_Rules_________________________________________   M             8.1    VMS File System Specifications.........................8-2   M             8.2    Rules..................................................8-3   M             8.3    Rule Interpretation....................................8-5   M             8.4    Mapping Examples.......................................8-6   M             8.5    Conditional Mapping....................................8-8   M             8.6    Mapping User Directories (tilde character ("~"))......8-11   .                                             iv                 M             Chapter_9__Authentication_and_Authorization______________________   M             9.1    Permissions, Path and User.............................9-3   M             9.2    Authorization Configuration File.......................9-4   M             9.3    Authorization Configuration Examples...................9-7   M                    9.3.1     KISS.........................................9-8   M             9.4    Databases, Authentication and Group...................9-10   M             9.5    Server Authorization Administration...................9-11   M             9.6    SYSUAF-Authenticated Users............................9-11   M             9.7    Controlling Server Write Access.......................9-15   M             9.8    User Password Modification............................9-16   M             Chapter_10__Secure_Sockets_Layer_________________________________   M             10.1   SSL Configuration.....................................10-4   M             10.2   Certificate Management................................10-6   M             10.3   SSLeay................................................10-8   M             10.4   SSL References........................................10-8   M             Chapter_11__Server_Administration________________________________   M             11.1   Breaking-in To The Server!............................11-2   M             11.2   HTTPd Server Reports..................................11-3   M             11.3   HTTPd Server Revise...................................11-7   M             11.4   HTTPd Server Action...................................11-8   M             Chapter_12__Scripting____________________________________________   M             12.1   Caution!..............................................12-1   M             12.2   Scripting Environment.................................12-2   M             12.3   Script Run-Time.......................................12-3   M             12.4   CGI Compliance........................................12-4   M                    12.4.1    Example DCL Scripts.........................12-8   M             12.5   Raw HTTP Output.......................................12-9   M             12.6   Raw HTTP Input.......................................12-11   M             12.7   CGIplus Scripting....................................12-11   M             12.8   DECnet Scripting.....................................12-17   M                    12.8.1    Script System Environment..................12-19   M                      12.8.1.1      Proxy Access.........................12-20   M                      12.8.1.2      DECnet Objects.......................12-20   M                      12.8.1.3      Reducing Script Latency..............12-21   M                      12.8.1.4      DECnet/OSU Startup...................12-22   .                                              v                 M                    12.8.2    CGI........................................12-22   M                    12.8.3    OSU (DECthreads) Emulation.................12-23   M                    12.8.4    User Scripts...............................12-26   M             12.9   Java Scripts.........................................12-28   M             12.10  HTTP Persistant-State Cookies........................12-29   M             Chapter_13__Cache________________________________________________   M             13.1   Cache Suitability Considerations......................13-3   M             13.2   Cache Content Validation..............................13-5   M             13.3   Cache Configuration...................................13-5   M             13.4   Cache Control.........................................13-6   M             Chapter_14__Server_Performance___________________________________   M             14.1   File Record Format....................................14-4   M             14.2   Subprocess-based Scripting............................14-4   M             14.3   DECnet-based Scripting................................14-6i  M             14.4   SSL...................................................14-7V  M             14.5   Suggestions...........................................14-7e  M             Chapter_15__HTTPd_Web_Update_____________________________________2  M             Chapter_16__Utilities____________________________________________   M             16.1   Echo Facility.........................................16-1   M             16.2   Where Facility........................................16-14  M             16.3   Xray Facility.........................................16-2r  M             16.4   StreamLF Utility......................................16-23  M             16.5   HTTPd Monitor.........................................16-21  M             16.6   Server Workout (stress-test)..........................16-47      .                                             vi    d                M             Chapter__1_______________________________________________________                Introduction    M                As of July 1997 High Frequency Radar Division (HFRD) underwentcJ                a change of role and name. It is now Wide Area SurveillanceK                Division (WASD). This package has been renamed in accordancet                with that.n  K                This document provides an technical overview of the WASD VMSpL                HTTP server. It is primarily written for use internal to WASDK                and assumes that perpsective without apology. Any additionalrM                usage is subordinate to its role within WASD. The software has L                been written expressly for supporting an intra-organisationalG                hypertext environment on a VMS platform (June 1997 note:SL                since first writing this the industry has settled on the termJ                intranet). It too, is unreservedly tailored to this purposeL                and the requirements of WASD. All programs were designed onlyL                to specifically comply with the requirements of VAX C and DECC                C, within a DEC TCP/IP Services for VMS environment.   J                The document assumes a basic understanding of the hypertextH                technologies and uses terms without explaining them (e.g.H                HTTP, HTML, URL, CGI, SSI, etc.) The reader is refered toK                documents specifically on these topics (these are often best 7                consulted on-line, on the Internet WWW).   M                Also see "WASD Hypertext Environment" for information on usingl1                the WASD VMS hypertext facilities.   L                It is strongly suggested those using printed versions of thisM                document also access the Hypertext version. It provides onlinen/                demonstrations of some concepts.f                  Objectivesy  M                The primary impetus for an internal Web environment was a 1993nJ                decision by Division management to make as much informationH                as possible, both administrative and research, internallyM                available on-line (to use the current term . . . an intranet).9K                Early experimentation with a Gopher implementation soon madeoM                way for the obvious advantages of the emerging Web technology.t  I                It then became the objective of this author to make all offH                our systems' VMS-related resources available via HTTP andL                HTML, regardless of the underlying data or storage format. AnL                examination of the WASD package will show that this objective)                is substantially achieved.   N                                                              Introduction  1-1 U               (                Reasons For a Local HTTPd  E                Reasons for developing a local HTTP server are few bute                compelling:  H                o  The WASD (then HFRD) Web implementation began mid-1994&                   (October 1997 note).  K                o  It was prefered to support the hypertext environment on a M                   VMS platform. This is currently (1995) the most widely usedd9                   and accessable environment within WASD.i  M                o  Existing servers (and there are quite a few variations) are J                   largely Unix based, although it is being supported (to aM                   greater or lesses extent) across a wide range of platforms. M                   Ports to VMS, if they exist, are often in progress or half- M                   baked, employing Unixisms that don't translate elegantly to &                   the VMS environment.  J                o  The VMS version of the CERN server (3.0-6) was evaluated"                   during mid-1994:  L                   -  It is not multi-threaded under VMS (i.e. cannot supportK                      concurrent clients). For example, a lengthy search may B                      delay other clients for unacceptable periods.  J                   -  Its performance was good with document transfers, but7                      became poor when running a script.   J                   -  It is acknowleged in the release notes that it cannotG                      handle a client cancelling a data transfer (a not-tI                      uncommon action). This was confirmed experimentally.   E                o  An early version of the OSU (DECthreads) server was G                   evaluated via documentation mid-1994. 1998 . . . I ampI                   reticent to make comments on now such a widely deployed                    package :^)   G                o  HyperText Transport Protocol, in its current form, iseI                   relatively simple to implement to the level required to 8                   support intra-Divisional requirements.  J                o  As of December 1995 the server has worked extremely wellE                   and has a number of facilities tailored for the VMS I                   environment. It can continue to be utilized until therenK                   are overwhelming reasons for implementing something else.w  H                o  As of June 1997 the server and its associated softwareL                   continues to evolve and provide a stable and effective VMSL                   Web environment, even with the advent of a small number of.                   commercial VMS Web products.               1-2  Introduction                      M             Chapter__2_______________________________________________________r  :             HyperText Transport Protocol Daemon - Overview    G                The most fundamental component of the WASD VMS HypertextoG                Services environment is the HTTPd, or HyperText ProtocoloI                Transport Daemon, or HTTP server. It has a single-process, 7                multi-threaded, asynchronous I/O design.                  2.1 Server Features   H                The package provides a complete implementation of a basic*                HTTP/1.0 server, including:  ;                o  concurrent, multi-threaded client supportn  G                o  "DELETE", "GET", "HEAD", "POST" and "PUT" HTTP methods                   support   L                o  optional enhanced privacy using Secure Sockets Layer (SSL)E                   technology (USA domestic, full-strength encryption)e  I                o  "If-Modified-Since:" / "304 Not Modified" functionality L                   (document is only sent if modified since time specified by                   client)   G                o  HTTP/1.0 de-facto persistent connections (i.e. "Keep-_K                   Alive:", reducing the number of TCP/IP connects required)v  E                o  versatile directory listing (generic and VMS-style).  H                o  CGI-compliant subprocess scripting (with configurable,D                   automatic, MIME content-type initiated activation)  J                o  "CGIplus" scripting (offering reduced latency, increasedF                   throughput and reduced system impact when scripting)  D                o  DECnet-based CGI scripting (with connection reuse)  L                o  user account scripting (provided using the DECnet environ-                   ment).  K                o  OSU (DECthreads server) scripting emulation, with connec- L                   tion reuse (as per OSU 3.3a), allowing many OSU scripts to(                   be employed unmodified  H                o  script processor (e.g. PERL) configurable on file type                   (extension)   <                o  Server-Side Includes (HTML pre-processing)  N                            HyperText Transport Protocol Daemon - Overview  2-1 .  .            D                o  configurable cache, with time-based and forced re-%                   validation (reload)   F                o  clickable-image support (both NCSA and CERN formats)  8                o  smart rule mapping (conditional rules)  J                o  "Basic" and "Digest" user authentication and path/group-%                   based authorization   F                o  optional SYSUAF-authentication and VMS user security3                   profile based file access control_  J                o  Web-standard, "common" and "combined" access log formatsI                   (allowing processing by most log-analysis tools), along.G                   with a user-definition capability allowing custom log.                   formats.  L                o  logging periods, where log files automatically change on aM                   daily, weekly or monthly basis (keeps log files ordered and &                   at a managable size)  F                o  host-level access control, on per-host or per-domain)                   acceptance or rejection.  G                o  single server can support multi-homed (host name) and.(                   multiple port services  K                o  customizable message database (capable of supporting non- =                   English and concurrent, multiple languages)   H                o  on-line server configuration, including reports on re-L                   quests, loaded configuration, mapping rules, authorization=                   information and graphical activity displays.                2.2 Server Behaviour  K                The HTTPd executes permanently on the server host, listening M                for client connection requests on TCP/IP port 80 (by default). M                It provides concurrent services for a (technically) unlimitted L                number of clients (constrained only by the server resources).G                When a client connects the server performs the following.                tasks:.  3                1. creates a thread for this request.  ;                2. reads and analyzes the HTTP request sent,c>                   depending on the nature of the request . . .  =                   o  transfer of a file (possibly from cache)   3                   o  processing of an SSI HTML file6  A                   o  processing of a clickable-image mapping file.  &                   o  directory listing  ?             2-2  HyperText Transport Protocol Daemon - Overview                  1                   o  file/directory create/update   *                   o  server administration  +                   o  web file-system update   2                   o  interpretation of a menu file  E                   o  spawn a subprocess to to provide a CGI scripting.!                      environment:   #                     -  standard CGI.  #                     -  WASD CGIplus   G                   o  connects to a DECnet object to provide a scripting !                      environment:e  #                     -  standard CGI   0                     -  OSU (DECthreads) emulated  I                3. closes the connection to the client and disposes of the.(                   thread data structures  L                For I/O intensive activities like file transfer and directoryI                listing, the AST-driven code provides an efficient, multi- J                threaded environment for the concurrent serving of multiple                clients.   J                For scripts, the technique of using multi-threaded, concur-K                rent, spawned subprocesses or network processes, attached torJ                standard input/output streams, provides a versatile, exten-J                sible, powerful scripting environment. Any DCL procedure orK                image executing within the process can behave essentially as K                an HTTP server. This capability is employed to easily extend K                the basic services provided by the core daemon code. An HTTP J                script/server for this environment does not need to concernI                itself with network activities, it merely reads and writes.-                from the standard I/O streams.r               2.3 TCP/IP Packages.  L                The WASD server supports Digital TCP/IP Services (UCX) with a                native image.  D                The "UCX" version is also known to work under TCPwareG                v5.n (UCX compatibility emulation) from Process Software                 Corporation.a  G                Using the excellent freeware NETLIB package from MadGoatLM                Software (Matthew Madison), this server can also (potentially)S                support  9                o  Cisco MultiNet for OpenVMS, any version_  ;                o  PathWay from Attachmate Inc., any version   N                            HyperText Transport Protocol Daemon - Overview  2-3    1            H                o  TCPware from Process Software Corporation, any version  L                o  CMU TCP/IP (VAX only) v6.5 or later is not supported! (too=                   much variation from mainstream IP packages)   K                NETLIB requires VAX/VMS v5.2 or later, or OpenVMS Alpha v1.5                 or later.  L                NETLIB must be obtained and installed separately. This is notI                a difficult undertaking for there is a familiar VMSINSTAL-25                driven installation and configuration..  M                The WASD NETLIB support was developed using v2.1, which may be.                obtained from  1                http://www.madgoat.com/netlib.html.  -                ftp://ftp.madgoat.com/madgoat/.  M                NETLIB support within the WASD server is tested in-house using.M                the Digital TCP/IP Services package. Other TCP/IP packages may.,                or may not perform as tested.  &             2.4 International Features  H                As of version 4.4 the HTTP server has undergone a limitedC                degree of internationalization. The impetus for this.F                development was the use of the package in some EuropeanA                countries where English is not the first language.   M                As this was not within the original critera while building the M                server it has meant an extensive rewrite of some functionality I                within the code (I hope it's appreciated ;^) The objective I                is to provide users of the server with a more familiar and H                therefore more comfortable environment. Unfortunately theH                server administrators are still confronted by an English-I                language interface and documentation, but then the package.<                doesn't pretend to be international software!                  Aspects  J                The international features only apply to the server, not to                scripts!   !                o  Server Messagesa  H                   The server uses an administrator-customizable databaseJ                   of messages that can contain multiple language instancesJ                   of some or all messages, using the Latin-1 character setH                   (ISO8859-1). Although the base English messages can beM                   completely changed and/or translated to provide any message L                   text required or desired, a more convenient approach is toH                   supplement this base set with a language-specific one.  ?             2-4  HyperText Transport Protocol Daemon - Overview1 i               H                   One language is designated the prefered language. ThisH                   would most commonly be the language appropriate to theG                   geographical location and/or clientele of the server._H                   Another language is designated the base language. ThisM                   must have a complete set of messages and is a fall-back for.J                   any messages not configured for the additional language.I                   Of course this base language would most commonly be the.+                   original English version.   G                   More than just two languages can be supported. If the L                   browser has prefered languages set the server will attemptM                   to match a message with a language in this preference list. M                   If not, then the server-prefered and then the base language H                   message would be issued, in that order. In this way itJ                   would be possible to simultaneously provide for English,I                   French, German and Swedish audiences, just for example.a  F                   For message configuration information see Chapter 7.                  o  Server Dates  I                   Dates appearing in server-generated, non-administrativenL                   content (e.g. directory listings, not META-tags, which useJ                   Web-standard time formats) will use the natural languageI                   specified by any SYS$LANGUAGE environment in use on the @                   system or specifically created for the server.  *                o  Conditional Rule Mapping  L                   Mapping rules map requested URL paths to physical or otherK                   paths (see Chapter 8). Conditional rules are only appliedeL                   if the request matches criteria such as prefered language,H                   host address (hence geographical location to a certainJ                   extent), etc. This allows requests for generic documentsE                   (e.g. home pages) to be mapped to language versionse4                   appropriate to the above criteria.  K                   For example, requests originating with a language prefer-tM                   ence of "en, fr" from ".au" can receive an English version,dM                   whilst requests prefering "de, se, en" from ".de" and ".se"aC                   receive German and Swedish versions respectively.)  F                   For conditional mapping information see Section 8.5.  "             2.5 HTTP Methods Usage  J                This section describes WASD-specific characteristics of the2                available HTTP/1.0 request methods.    N                            HyperText Transport Protocol Daemon - Overview  2-5 f  m                         2.5.1 GETc  M                Of course, the GET method is used to access documents suppliedaI                by the server. There is nothing WASD server-specific aboutr                this method.s               2.5.2 POST & PUT  I                The WASD HTTPd does not differentiate between POST and PUT 5                methods, both are handled identically.i                  Script Handling  M                The "normal" usage of the POST method is to return data from aoK                <FORM>..</FORM> construct to a script running on the server.aK                In this regard WASD is no different to other any web server;aM                the form data is delivered to the script's standard input as an7                stream of URL-encoded text. For example:w  Y                   name=Fred+Nurk&address=Fred%27s+House%0D%0A0+Nowhere+Lane&submit=Submit   J                Note that WWW_CONTENT_LENGTH will be the length of the form<                data. See Chapter 12 for further information.  #                File Creation/Upload   K                If the client sends data back to the server using either theWK                POST or the PUT methods, without a script being mapped to be L                executed in response to that data, the WASD HTTPd will createJ                a file corresponding to the specified path. The data stream%                may be text or binary.r  L                Of course, for the server to accept POST and PUT data in thisK                manner, authentication and authorization must be enabled andb5                allow such access to the request path.e  K                The data stream is processed according to MIME content-type:f  3                o  application/x-www-form-urlencoded   D                   The server specially processes "application/x-www-A                   form-urlencoded" POSTS (i.e. those generated byeI                   <FORM>...</FORM>, allowing files to be created directlydL                   from HTML forms. The processing eliminates any field namesM                   from the URL-encoded data stream, placing only field valuescK                   into the file. This capability can be quite useful and is 9                   demonstrated in the Update HTTPd module   *                   <online hypertext link>.  %                o  multipart/form-data   ?             2-6  HyperText Transport Protocol Daemon - Overview                  J                   This server can process a request body according to RFC-L                   1867, "Form-based File Upload in HTML". As yet it is not aL                   full implementation. It will not process "multipart/mixed"G                   subsections. The implementation is basic, providing aaH                   facility to allow the upload of a file into the serverH                   administered file system. The ACTION= parameter of theJ                   <FORM> tag must specify the directory (as a URL path) in:                   which the uploaded file will be created.  J                   The following example HTML illustrates how a form may beJ                   used to upload a file from the browser host file system:  ^                      <FORM METHOD=POST ACTION="/web/directory/" ENCTYPE="multipart/form-data">F                      <INPUT TYPE=submit VALUE=" Upload document ... ">>                      <INPUT TYPE=file SIZE=50 NAME=uploadfile>                      </FORM>  )                   <online hypertext link>   M                   NOTE: This capability has only been tested against Netscape J                   Navigator versions 2 and 3. VMS Netscape Navigator 3.0b5H                   hangs if an upload of a variable-record format file isM                   attempted. Stick to STREAM-LF or fixed, or convert the file                    to STREAM-LF.m                  o  text/htmle                   text/plain  M                   Text file created according to the path, VMS record type isT                   STREAM-LF.                  o  image/gif *                   application/octet-stream"                   etc., etc., etc.  J                   Any other MIME type is considered binary and the created8                   file is made an UNDEFINED record type.  !                Directory Creationh  K                A directory will be created by the HTTPd if a directory path E                is provided with the POST or PUT methods. For example:i  /                   /dir1/dir2/dir-to-be-created/S                  File Deletion  J                A file will be deleted by the HTTPd if the file path endingM                with a wildard version specification is provided with the POST +                or PUT methods. For example:   1                   /dir1/dir2/file-to-be.deleted;*d  N                            HyperText Transport Protocol Daemon - Overview  2-7    b            !                Directory Deletion   K                A directory will be deleted by the HTTPd if a directory path K                ending with a wildard version specification is provided witho4                the POST or PUT methods. For example:  1                   /dir1/dir2/dir-to-be-deleted/;*a               2.5.3 DELETE  D                The DELETE method should delete the file or directory2                corresponding to the supplied path.                                                                            ?             2-8  HyperText Transport Protocol Daemon - OverviewD h  d                M             Chapter__3_______________________________________________________l  $             New to WASD? Start Here!    G                This chapter provides a quick guide to getting your WASD)E                package installed, configured and serving. This covers M                initial installation. As of v5.1 an installation DCL procedure ,                simplifies the initial setup.                  1. Unzip Package   J                   Install the files following the guidelines in Chapter 4.  !                2. INSTALL Package   L                   Server installation if performed using the INSTALL.COM DCL-                   procedure, see Section 4.1.   !                   o  Link Package   N                      Link the supplied object files to produce VMS executables5                      for the system's version of VMS.e  "                   o  Check Package  L                      Using the installation procedure check the operation ofE                      the basic package as recommended in Section 4.3.g  *                   o  Directory Protections  L                      This section checks for correct directory protection inJ                      the HT_ROOT:[000000] tree and prompts to change it to6                      WORLD:RE if it appears incorrect.  *                   o  Create Server Account  G                      Using the installation procedure create the servereF                      account. For further information see Section 5.1.                     o  Disk Quotap  L                      Check if quotas are enabled on the target disk. ProvideL                      an ambit allocation for the server account. Review this#                      at some stage.t  @                   o  Copy Server Support and Configuration Files  F                      Using the installation procedure copy the exampleK                      server support and configuration files as discussed ina!                      Section 5.2.   #                3. Configure PackageT  N                                                  New to WASD? Start Here!  3-1 n  o            J                   Following the execution of the INSTALL.COM procedure theK                   package should require only minor, further configuration.(  =                   Initially two files may require alteration.   J                   1. The startup file, possibly to set the local HTTPD$GMTK                      logical. Consider using the STARTUP_LOCAL.COM file fordN                      other site-specific requirements. Information is provided$                      in Section 5.2.  I                   2. The only configuration that should require immediateoK                      attention will be to the mapping rules, see Chapter 8.e  J                   More generally server runtime configuration involves theH                   considerations discussed in Section 4.6 along with the$                   following aspects:  N                   o  Configuring the HTTP server run-time characteristics, see                      Chapter 6.   I                   o  Mapping request paths to the VMS file system, and tosA                      other things such as scripts, see Chapter 8.r  N                   o  Customizing some messages (or all if non-English language1                      environment), see Chapter 7.   E                   o  Establishing an authentication and authorization 0                      environment, see Chapter 9.                  4. Start Server  E                   Execute the startup procedure. Get your browser and                    connect!  +                5. Find Out What's Wrong :^(t  H                   Of course something will not be right! This can happenL                   with the initial configuration and sometimes when changingL                   configuration. The server provides information messages inA                   it's run-time log, look in HT_ROOT:[LOG.SERVER]c  I                   Remember, the basic installation's integrity can alwayshI                   be checked as described in Chapter 4, Section 4.3. This L                   uses the configuration files from the [EXAMPLE] directory,K                   so provided these have not been altered the server shouldy:                   execute in demonstration mode correctly.  4                   Can't resolve it? See Section 4.7.    )             3-2  New to WASD? Start Here!                      M             Chapter__4_______________________________________________________t  #             Installation and Updatei    M                The WASD package and updates will always be distributed as ZIPa                archives.  L                The ZIP archive will contain brief installation instructions.C                Use the following command to read this and any otherd$                information provided.  4                   $ UNZIP -z device:[dir]archive.ZIP  J                For complete package distributions the archive will containM                the complete directory tree. Hence to install or do a completeaG                update it is necessary to SET DEFAULT into the top-leveltG                directory of the disk the package is to be installed on.t  /                   $ SET DEFAULT device:[000000]H  I                For updates to portions of the package only the tree below I                HT_ROOT:[000000] is provided, hence it is necessary to SET <                DEFAULT to HT_ROOT:[000000] before UNZIPping.  0                   $ SET DEFAULT HT_ROOT:[000000]  J                In either case it is recommended to check the integrity of,L                then list the contents of, the archive before UNZIPping. This&                may be done as follows:  4                   $ UNZIP -t device:[dir]archive.ZIP4                   $ UNZIP -l device:[dir]archive.ZIP  H                A complete installation/update (the former) will have the                structure:i  <                    Archive:  HT_ROOT:[000000]HTROOT430.ZIP;1  ^                     WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 Mark G.Daniel.^                     This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.Q                     This is free software, and you are welcome to redistribute it V                     under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.  0                      *  Complete v4.3.0 package.5                      *  $ SET DEFAULT device:[000000]i>                      *  $ UNZIP "-V" device:[dir]HTROOT430.ZIP  K                     VMS file attributes saved ... use UnZip 5.n+ on OpenVMS   .                     Archive created 1-AUG-1997  N                                                   Installation and Update  4-1 t  f            2                     Length    Date    Time    Name2                     ------    ----    ----    ----A                          0  07-30-97  14:15   ht_root/$_read_1st/ ?                          0  07-30-97  14:15   ht_root/aacrt060/ ;                          0  07-30-97  14:15   ht_root/auth/ :                          0  07-30-97  14:15   ht_root/axp/B                       5360  07-30-97  13:23   ht_root/changes.html:                          0  07-30-97  14:15   ht_root/doc/                    .                    .                    .F                      16896  07-30-97  09:23   ht_root/vax/wwwrkout.exeM                      16384  07-30-97  09:21   ht_root/vax/wwwrkout_netlib.exe 5                     ------                    -------a7                   19109754                    996 filese  >                An update (the latter) will have the structure:  C                    Archive:  HT_ROOT:[000000]HTROOT430_UPD_01.ZIP;1d  ^                     WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 Mark G.Daniel.^                     This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.Q                     This is free software, and you are welcome to redistribute it V                     under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.  ]                      *  Mostly minor updates to scripts and utilities for the v4.3.0 package.tS                      *  A couple nuisance-value-bugs have also been fixed in these.dV                      *  SDM2HTM can now generate <FRAMESET> documents (see [DOC]*.COM)  K                     VMS file attributes saved ... use UnZip 5.n+ on OpenVMSn  .                     Archive created 6-AUG-1997  2                     Length    Date    Time    Name2                     ------    ----    ----    ----B                      42957  08-04-97  07:57   src/utils/wwwrkout.cL                      59664  08-04-97  07:57   src/utils/obj_axp/wwwrkout.objL                      19674  08-04-97  07:57   src/utils/obj_vax/wwwrkout.obj>                      26624  08-04-97  07:57   axp/wwwrkout.exeE                      27136  07-30-97  09:21   axp/wwwrkout_netlib.exe                     .                    .                    .=                      45056  08-05-97  11:02   vax/sdm2htm.exeaE                        617  08-05-97  09:23   doc/all_docs_framed.comtI                         44  08-05-97  09:23   doc/all_docs_not_framed.com =                        544  08-05-97  09:22   doc/readme.htmlv5                     ------                    ------- 6                    2773107                    90 files  (             4-2  Installation and Update                 H                The archive may then be UNZIPped. If this is a completelyK                new installation a new directory tree will be created. If anoJ                update to an existing installation the tree will be created8                "over-the-top" of the existing structure.                  When updating:p  H                o  Some insurance on the directory tree is recommended inI                   case the update should fail or otherwise be unusable orcL                   problematic (of course, this is good advice whenever aboutH                   to make major changes to anything!) This may be in theM                   format of a regular site backup, special pre-update backup,oJ                   or special pre-update ZIP archive of the directory tree.M                   The latter two could be accomplished using commands similar #                   to the following:"  Q                      $ BACKUP HT_ROOT:[000000...] location:HTROOT.BCK/SAVE/VERIFYi  J                      $ ZIP "-V" location:HTROOT.ZIP device:[HT_ROOT...]*.*3                      $ ZIP "-T" location:HTROOT.ZIP   I                   If using ZIP then ensure that a previous version of the I                   target ZIP file does not already exist. If it does thenrH                   that version is updated, a new version is not created.  8                o  New files and directories are created.  M                o  For existing files a new version is created (the first timetK                   this is about to occur the UNZIPper requests permission - I                   either "A" for all, or "y" or "n" or a per-file basis).t  *             4.1 Installation DCL Procedure  L                The INSTALL.COM procedure assists with the first installationG                of WASD. It provides a vanilla setup, using the standard D                directories and account environment described in thisI                document. All sections prompt before performing any actiona#                and default to "no".i  /                It performs the following tasks:   M                1. Link Executables - Links the package object code to produceu6                   images for the local version of VMS.  L                2. Server Quick-Check - Executes a procedure that runs up theL                   HTTPd in demonstration mode. Allows evaluation/checking of5                   the basic package. See Section 4.3.e  I                3. Directory Protections - This section checks for correcteG                   directory protection in the HT_ROOT:[000000] tree andeK                   prompts to change it to WORLD:RE if it appears incorrect.   N                                                   Installation and Update  4-3 i  y            I                4. Create Server Account - Creates an unprivileged account L                   for the HTTP server to execute within. Sets permissions onL                   files and directories allowing appropriate access for this                   account.  H                5. Disk Quota - Check if quotas are enabled on the targetK                   disk. Provide an ambit allocation for the server account. ,                   Review this at some stage.  J                6. Server Support/Configuration Files - Copies example HTTPK                   server configuration and support files from the [EXAMPLE]tL                   directory to the [HTTP$SERVER] and [LOCAL] directories. No@                   copy is made without prompting for permission.  <                After UNZIPping the package do the following:  0                   $ SET DEFAULT device:[HT_ROOT]                   $ @INSTALL  F                NOTE: The installation procedure provides a reasonable,E                vanilla, single-node set-up. If something different issI                required a little time and thought may be required further7(                configuring startup, etc.  L                Support files to consider when customizing startup, etc. (see/                Section 5.2 for further detail):p                  o  STARTUP.COMa  #                o  STARTUP_LOCAL.COMh  !                o  HTTPD_BATCH.COM                   o  HTTPD80.COM                   o  LOGIN.COMf  $             4.2 Update DCL Procedure  G                The UPDATE.COM procedure assists with subsequent updatesdF                of WASD. It assumes a vanilla setup, using the standardD                directories and account environment described in thisI                document. All sections prompt before performing any actionO#                and default to "no".m  3                It provides the following functions:s  M                1. Link Executables - Links the package object code to produce56                   images for the local version of VMS.  L                2. Server Quick-Check - Executes a procedure that runs up theL                   HTTPd in demonstration mode. Allows evaluation/checking of5                   the basic package. See Section 4.3.   (             4-4  Installation and Update t  l            M                3. Server Support/Configuration Files - Copies changed example F                   HTTP server configuration and support files from theF                   [EXAMPLE] directory to the [HTTP$SERVER] and [LOCAL]F                   directories. This copy is made without prompting for                   permission.   M                4. Post-Update Cleanup - Prompts for permission to execute the 8                   post-update procedure described below.  J                5. Purge Files - Prompts for permission to purge the entire+                   HT_ROOT:[000000...] tree.c  D                After UNZIPping the updated package do the following:  0                   $ SET DEFAULT HT_ROOT:[000000]                   $ @UPDATE/                  Post-Update  H                When confident regarding the success of the update (theseC                activities can be part of the update DCL procedure).p  H                o  The procedure UPDATEAFTER.COM should be executed. ThisM                   will remove files known to exist from previous versions and 2                   relocated or no longer required.  3                      $ SET DEFAULT HT_ROOT:[000000]o#                      $ @UPDATEAFTERc  6                o  The directory tree should be purged.               4.3 Quick-Checka  J                Once installed or updated it is possible to check the basicL                package at any time using the FREEWARE_DEMO.COM procedure. ItK                should detect the TCP/IP agent in use (if not specify UCX orfI                NETLIB as a parameter). Follow the displayed instructions.   0                   @device:[HT_ROOT]FREEWARE_DEMO  ?                Problem? SYSTEM-F-SHRIDMISMAT? See next section!m               4.4 Re-Linking  M                After an update to the operating system the package may refuse_2                to start, reporting a message like:  C                   %DCL-W-ACTIMAGE, error activating image WHAT$EVER)\                   -CLI-E-IMGNAME, image file DKA0:[SYS0.SYSCOMMON.][SYSLIB]WHAT$EVER_SHR.EXEL                   -SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image  N                                                   Installation and Update  4-5 n  l            G                This implies the executables require re-linking for yourgH                particular version of VMS. This can be accomplished quiteI                simply, perform the linking section only of the update DCL &                procedure, Section 4.2.    '             4.5 Local Setup SuggestionsV  I                Package updates will never contain anything in these three                 directories:e  '                o  HT_ROOT:[HTTP$SERVER]t  !                o  HT_ROOT:[LOCAL]   (                o  HT_ROOT:[SCRIPT_LOCAL]  L                To prevent the overwriting of local configuration files it isJ                suggested these be placed in the HT_ROOT:[LOCAL] directory.H                Startup files will most probably be placed where-ever theG                local site manages system startup. These could be placed H                in the HT_ROOT:[LOCAL] directory if there is nowhere moreI                appropriate. Authentication databases could also be placedoK                in the [LOCAL] directory. The server account's support files I                (LOGIN.COM, etc.) may be copied from the HT_ROOT:[EXAMPLE] E                directory into HT_ROOT:[HTTP$SERVER] and customized as                 necessary.e  D                In like manner, local DCL scripts or DCL wrappers forM                executable scripts should be placed in HT_ROOT:[SCRIPT_LOCAL]. B                Executables should continue to be placed in HT_EXE:  J                Changes that are made in package configuration files, etc.,H                can then be propagated to the local areas as appropriate.  $             4.6 Organizing Documents  J                It is recommended that the server distribution tree and anyJ                document and other Web-specific data areas be kept separateJ                and distinct. The former in HT_ROOT:[000000], the latter inH                something like WEB:[000000]. This logical device could beI                provided with the following DCL introduced into the server "                startup procedures:  K                   $ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DSA811:[WEB.]   L                The logical organisation of served data is largely hierarchi-M                cal, organised under the Web-server path root, and is achieved "                via two mechanisms.  L                1. The natural tree structure provided by a hierarchical file                   system.   (             4-6  Installation and Update                 G                2. The logical hierarchy possible using rules within thetG                   mapping file to place disparate physical areas into ae;                   single logical structure (see Chapter 8).,  H                WASD has a single section of the file system for the coreI                Web files, such as the Division home page, help areas, Web H                documentation, etc., it can be accessed using the logicalD                device WEB:[000000]. Incorporated with this are otherK                subdirectories providing storage for specific collections ofwM                data, such as committee minutes, administration announcements,                 etc.   K                Physically distinct areas are used for good physical reasonsiG                (e.g. the area can best be hosted on a task-local disk), K                for historical reasons (e.g. the area existed before any Web L                environment existed) or for reasons of convenience (e.g. letsK                put this where access controls already allow the maintainersk                to manage it).e  L                Reasons for an area being physically integrated with the coreL                Web data area can be legitimate (e.g. there is really nowhereK                else it reasonably belongs), convenience (e.g. let's quickly L                put it here) or by logical necessity (it really does below asK                part of the core Web enviroment, e.g. documentation on HTML,_                etc.)                  Guidelines   E                In general, only Web-related files need to go into the J                core physical Web file area. All other groupings should, ifM                possible, be decentralised into the portion of the file system M                they represent and logically placed in the server's path using H                rules in the mapping file. That is, a given project's WebH                files should be located in the project's part of the fileL                system. If it doesn't have any then it may be a candidate for)                location in the core area.e  H                When locating a Web area in a physically distinct area itI                is possible the maintainers of that data will already have F                the correct access controls. If locating an area in theF                core hypertext environment it will be necessary to giveJ                the mantainer ownership of the directory area (and possiblyK                disk quota), or provide ACL access if multiple maintains are                 involved.  I                When locating Web-accessable data in a physically distinct J                area it will be necessary to update the mapping file with aL                new rule (see Chapter 8). If located within the core Web area4                the rules do not need to be adjusted.  N                                                   Installation and Update  4-7                 "             4.7 Reporting Problems  G                This package, as is generally the case with freeware, isiE                mainly developed and supported outside of the author's E                main occupation and working hours. Reports of problems F                and bugs (while not necessarily welcome :^), as well asG                general queries, are responded to as soon a practicable. G                If the documentation is inaccurate or could benefit from I                clarification in some area please advise of this also (theIJ                better the documentation the less queries you have to field7                personally . . . or so the theory goes).   K                With all reports please include the version of the server or M                script, and the hardware platform, operating system and TCP/IP *                package and version in use.  J                If a server error message is being generated please examineM                the HTML source of the error page. The "<META...>" informationrK                contains version information as well as valuable source code I                module and line information. Include this with the report.3  M                If the server is exiting with a server-generated error message J                this information also contains module and line information.3                Please include this with the report.2  M                Image crash dumps may also be generated, although these are ofo<                less value than the case of the previous two.  I                Reports may be e-mailed to Mark.Daniel@dsto.defence.gov.aue                                          (             4-8  Installation and Update    c                M             Chapter__5_______________________________________________________   *             Server Account and Environment    D                The HTTP server account should be a standard account,K                preferably in a group of its own (definitely at least a non-aL                system, non-user group), with sufficient quotas to handle the                 expected traffic.                 5.1 VMS Account   H                NOTE: Server process quotas must be sufficient to supportK                the expected traffic load. In particlular PRCLM must supporteK                expected script usage. BYTLM, BIOLM, DIOL, FILLM and PGFLQUOeK                are all significant considerations. Symptoms of insufficient.&                process quotas include:  J                o  Textual pages OK, but pages with a significant number of5                   images having some or all "broken".   M                o  Scripts failing mysteriously, particularly when multiple in #                   use concurrently.l  L                A general rule is more is better, after all, it will only use#                as much as it needs!   =                The following provides a_guide to the account:   U                   Username: HTTP$SERVER                      Owner:  HyperText Daemon d                   Account:  HTTPD                            UIC:    [377,377] ([HTTPD,HTTP$SERVER])N                   CLI:      DCL                              Tables: DCLTABLES1                   Default:  HT_ROOT:[HTTP$SERVER]e!                   LGICMD:   LOGIN /                   Flags:  Restricted DisNewMail 5                   Primary days:   Mon Tue Wed Thu Fri =                   Secondary days:                     Sat SunsX                   Primary   000000000011111111112222  Secondary 000000000011111111112222X                   Day Hours 012345678901234567890123  Day Hours 012345678901234567890123X                   Network:  ##### Full access ######            ##### Full access ######X                   Batch:    ##### Full access ######            ##### Full access ######E                   Local:    -----  No access  ------            -----e             No access  ------eE                   Dialup:   -----  No access  ------            -----b             No access  ------dE                   Remote:   -----  No access  ------            -----h  N                                            Server Account and Environment  5-1 p  u                         No access  ------lV                   Expiration:            (none)    Pwdminimum:  6   Login Fails:     0H                   Pwdlifetime:         90 00:00    Pwdchange:      (pre-             expired)F                   Last Login:            (none) (interactive), 11-MAY-(             1995 08:44 (non-interactive)K                   Maxjobs:         0  Fillm:       300  Bytlm:       300000OK                   Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0oK                   Maxdetach:       0  BIOlm:       512  JTquota:       1024tK                   Prclm:         100  DIOlm:       512  WSdef:         1000.K                   Prio:            4  ASTlm:       600  WSquo:         2000 K                   Queprio:         0  TQElm:       100  WSextent:     20000 K                   CPU:        (none)  Enqlm:       256  Pgflquo:     200000 (                   Authorized Privileges:$                     NETMBX    TMPMBX%                   Default Privileges: $                     NETMBX    TMPMBX    %             5.2 Account Support Files   L                NOTE: Support procedures often change between versions. It isJ                always advisable to check the versions documentation before&                installing or updating.  :                Examples may be found in HT_ROOT:[EXAMPLE].  &                <online hypertext link>                   HTTPd Executables  ?                Two server executables are built by the package.s  M                o  HTTPD.EXE - This provides native support for Digital TCP/IP !                   services (UCX).   E                o  HTTPD_NETLIB.EXE - This provides NETLIB support for *                   packages other than UCX.  K                Two additional executables are built by the SSL package (seeo                Chapter 10).e  F                o  HTTPD_SSL.EXE - This provides SSL for Digital TCP/IP!                   services (UCX).a  K                o  HTTPD_SSL_NETLIB.EXE - This provides SSL based on NETLIB,a.                   for packages other than UCX.      /             5-2  Server Account and Environmente    o                            Privileged Imageo  L                As this image is to be installed with privileges unauthorizedH                use should be prevented by applying an ACL similar to the6                following against the executable image:  3                   $ SET SECURITY HT_EXE:HTTPD.EXE -cO                     /ACL=((IDENT=HTTP$SERVER,ACCESS=R+E),(IDENT=*,ACCESS=NONE))   K                This can be done once, at installation, or for peace-of-mind @                (a.k.a. VMS-ish paranoia) at each server startup.  L                As the HTTP$SERVER account should be completely unprivileged,K                and the HTTPd image requires NETMBX, TMPMBX, PRMMBX, PSWAPM, E                SYSNAM and SYSPRV privileges (see the "Nuts and Bolts" H                document for a description of how and why the server usesF                these privileges). It must be installed using a command(                similar to the following:  @                   $ INSTALL = "$SYS$SYSTEM:INSTALL/COMMAND_MODE"`                   $ INSTALL ADD HT_EXE:HTTPD.EXE /PRIVILEGE=(ALTPRI,PRMMBX,PSWAPM,SYSPRV,SYSNAM)                  Logical Names  M                The following logical names are essential for the operation of C                the HTTPd server and must be defined before startup:   L                o  HTTPD$AUTH -  location of the authentication/authorizationH                   configuration file (defined system-wide, or in the job+                   table if server-specific)e  M                o  HTTPD$CONFIG -  location of the configuration file (definednF                   system-wide, or in the job table if server-specific)  I                o  HTTPD$MAP -  location of the mapping rule file (definedOF                   system-wide, or in the job table if server-specific)  L                o  HTTPD$MSG -  location of the message file (defined system-?                   wide, or in the job table if server-specific)v  M                o  HTTPD$GMT -  offset from GMT (e.g. "+10:30", "-01:15"). FortM                   systems supporting DTSS (e.g. DECnet-Plus) this logical maycL                   be left undefined, with server time being calculated using8                   the SYS$TIMEZONE_DIFFERENTIAL logical.  I                o  HTTPD$LOG -  if logging is enabled and no log file name M                   specified on the command line, this logical must be defined J                   to locate the file. When a logging period is in use thisK                   logical need only contain the directory used to store thee                   logs.   F                o  HTTPD$SSL_CERT -  when using the SSL executable thisB                   logical locates the required server certificate.  N                                            Server Account and Environment  5-3 O  0            K                o  CGI-BIN -  system logical defining a search list with the I                   architecture-specific executable directory first, localDL                   script directory second, then the common script directory,(                   as a concealed device.  N                o  HT_AUTH -  directory containing authentication/authorization#                   databases (files)b  F                o  HT_EXE -  directory containing the executable images  I                o  HT_LOGS -  optional definition, for convenient log file                    specificationT  G                o  HT_SERVER_LOGS -  optional definition, for conveniento@                   detached server process log file specification  J                The following logical name is created by the executing HTTPB                server and defines the name of the control mailbox:  #                o  HTTPDport$CONTROLe  L                The following logical names are created by the executing HTTP>                server if the HTTPd monitor utility is enabled:  "                o  HTTPDport$COUNT1  "                o  HTTPDport$COUNT2                  o  HTTPDport$PID   #                o  HTTPDport$REQUEST   /                Server Process Logging Directorye  M                The server process log directory (output for the detached HTTP M                server processes) may require explicit access controls for theEL                HTTPd account. This can be done by applying an ACL similar to                the following:,  :                   $ SET SECURITY HT_ROOT:[LOG]SERVER.DIR -N                     /ACL=((IDENT=HTTP$SERVER,ACCESS=R+W+E, OPTIONS=DEFAULT), -=                           (IDENT=HTTP$SERVER,ACCESS=R+W+E), -rC                           (IDENT=*,ACCESS=NONE, OPTIONS=DEFAULT), -i0                           (IDENT=*,ACCESS=NONE))  H                As with the ACL on the server executable this can be doneH                once, at installation (or, if right over the top, at eachK                server startup). Appropriate disk quotas may also need to bes1                applied. Also see Section 5.3.2.6.   /             5-4  Server Account and Environmento T  O                            STARTUP.COM  J                Putting all this together the HTTP server startup procedureK                becomes something similar to the supplied example. It shouldpI                be called from SYSTARTUP_VMS.COM or the site's equivalent.t  /                See HT_ROOT:[EXAMPLE]STARTUP.COM                    STARTUP_LOCAL.COM  E                This file is automatically executed by the STARTUP.COMaK                procedure immediately before the server is actually started..G                It is provided to supply all the local site's additionalyK                startup requirements. Place site-specific server environment:D                startup in here, leaving STARTUP.COM alone as much as                possible.  5                See HT_ROOT:[EXAMPLE]STARTUP_LOCAL.COMu                  HTTPD_BATCH.COM  J                This procedure is SUBMITted by the server STARTUP.COM usingE                the HTTP server account, and simply creates a detachedgK                process under the control of HTTPD80.COM, or its equivalent.sJ                A parameter may be provided to this procedure. This roughlyM                represents the port number of a server but actually representsmM                a file HTTPD'number'.COM which controls a specific server, seei                below.O  3                See HT_ROOT:[EXAMPLE]HTTPD_BATCH.COMk                  HTTPD80.COM  K                This procedure is suggested for controlling the execution oftI                the HTTPd server and it's image. It is run in the detachedEH                process created by HTTPD_BATCH.COM. Multiple instances ofI                this file may be created, each having a unique number, forlL                controlling multiple servers, either on an individual node orM                within a cluster. Actually, just any unique string may be useda#                for indentification.   /                See HT_ROOT:[EXAMPLE]HTTPD80.COMe                  LOGIN.COM  M                This procedure provides the HTTP server account login control.   -                See HT_ROOT:[EXAMPLE]LOGIN.COMs    N                                            Server Account and Environment  5-5    S            "             5.3 HTTPd Command Line  M                Command-line qualifiers provide some server startup control as .                well as server runtime control.                5.3.1 Server Startup  I                When starting up the server several characteristics of thesL                server may be specified using qualifiers on the command line.B                If not specified appropriate defaults are employed.  K                o  /ACCEPT= comma-separated list of hosts/domains allowed top'                   connect to the servere  M                o  /AUTHORIZATION=SSL the "SSL" parameter causes all authenti-eL                   cation (both SYSUAF and HTA database) to be available only8                   via "https:" requests (see Chapter 10)  I                o  /CGI_PREFIX= the prefix to the CGI symbol names created K                   for a script (defaults to "WWW_", similar to the CERN VMSe(                   HTTPd, see Chapter 12)  K                o  /DO= command to be performed by the executing server (seet                    Section 5.3.2)  G                o  /FILBUF= number of bytes in the read buffer for filesiE                   open for processing (i.e. menu files, image mapping J                   configuration files, pre-processed HTML files, etc., not(                   direct file transfers)  L                o  /FORMAT= overrides the configuration parameter [LogFormat]  L                o  /REJECT= comma-separated list of hosts/domains not allowed*                   to connect to the server  D                o  /[NO]LOG[=name] either disables logging (overridesM                   configuration directive), or enables logging and optionally G                   specifies the log file name (also see section Logical E                   Names, logging is disabled by default). If the file M                   specification is "SYS$OUTPUT" the server issues log entriesaM                   to <stdout>, allowing user-defined log formats to be easilys&                   checked and refined.  M                o  /NETBUF= minimum number of bytes in the network read bufferc  K                o  /OUTBUF= number of bytes in the output buffer (for directaK                   file transfers, buffered output from menu interpretation,)+                   HTML-preprocessing, etc.)   L                o  /PERIOD= overrides the configuration parameter [LogPeriod]  L                o  /PORT= overrides the configuration parameter [Port] BUT isM                   in turn overridden by the [Service] configuration parameteriM                   and /SERVICE= qualifier (is really only useful for use with &                   the /DO= qualifier).  /             5-6  Server Account and Environment                  C                o  /PRIORITY= server process priority (default is 4)y  L                o  /[NO]PROFILE allows SYSUAF-authenticated username securityF                   profiles to be used for file access (see Section 9.6  L                o  /PROMISCUOUS[=password] server will accept any authentica-K                   tion username/password pair (used for testing, demonstra-t                   tions, etc.)  D                o  /SERVICE= comma-separated, list of server servicesC                   (overrides the [Service] configuration parameter)   K                o  /[NO]SSL[=version] controls Secure Sockets Layer protocolrG                   behaviour. The version can be any of "2", "3" or "23" K                   (i.e. both 2 and 3, and the default) specifying which SSLh;                   protocol version the server will service.   J                o  /SUBBUF= number bytes in a subprocess' SYS$OUTPUT buffer  F                o  /[NO]SWAP controls whether the server process may beE                   swapped out of the balance set (default is swappingo                   disabled)o  G                o  /[NO]SYSUAF[=ID,SSL] allows or disallows (D) usernamehF                   authentication using the server system's SYSUAF (seeI                   Section 9.6, the optional "SSL" parameter causes SYSUAFaK                   authentication to be available only via "https:" requests I                   (see Chapter 10), and the optional "ID" parameter makesoL                   SYSUAF authentication only available to account possessing9                   a specific identifier. See Section 9.6.v  J                o  /VERSION merely displays the executable's version string*                   and the copyright notice  M                Note:  buffer sizes apply on a per-request (thread) basis, and K                may be tailored for specific environments at server startup.t  -             5.3.2 Server Command Line Controle  I                A foreign command for the HTTPD control functionality willsM                need to be assigned in the adminstration users' LOGIN.COM, forc                example:   *                   HTTPD == "$HT_EXE:HTTPD"2                   !HTTPD == "$HT_EXE:HTTPD_NETLIB"  I                Some control of the executing server is available from the G                DCL command line on the system on which it is executing.UI                This functionality, via the "/DO=" qualifier, is availableiG                to the privileged user. If a non-default server port, or I                multiple servers on the one system are being used, then ithI                will be necessary to provide a "/PORT=" qualifier with anysH                command, and possibly issue it multiple times. Of course,F                these commands are available from batch jobs as well as                interactively.a  N                                            Server Account and Environment  5-7                              5.3.2.1 Accounting  F                Server counters may be zeroed. These counters are thoseH                visible from the statistics admininstration menu item and/                when using the HTTPDMON utility.   "                   $ HTTPD /DO=ZERO  "             5.3.2.2 Authentication                  See Chapter 9.   G                The authorization rule file (HTTP$AUTH) may be reloaded.a  '                   $ HTTPD /DO=AUTH=LOAD   G                The authentication cache may be purged, resulting in re- I                authentication for all subsequent authorization-controlled K                accesses. This may be useful when disabling authorization or M                if a user has been locked-out due to too many invalid password                 attempts.  (                   $ HTTPD /DO=AUTH=PURGE               5.3.2.3 Cache   I                Server cache control may also be exercised from the server G                administration menu, see Chapter 11. The file cache (see-J                Chapter 13) may be enabled, disabled and have it's contents;                purged (declared invalid and reloaded) using   &                   $ HTTPD /DO=CACHE=ON'                   $ HTTPD /DO=CACHE=OFF )                   $ HTTPD /DO=CACHE=PURGE   .             5.3.2.4 DCL/Scripting Subprocesses  F                These commands can be useful for flushing any currentlyI                executing CGIplus applications from the server, enabling atM                new version to be loaded with the next access. See Chapter 12.n  M                All scripting subprocesses, busy with a request or not, can be3@                deleted (this may cause the client to lose data).  (                   $ HTTPD /DO=DCL=DELETE  L                A gentler alternative is to delete idle subprocesses and mark@                busy ones for deletion when completed processing.  '                   $ HTTPD /DO=DCL=PURGES  /             5-8  Server Account and Environment  0  Q            0             5.3.2.5 DECnet Scripting Connections  I                All DECnet connections, busy with a request or not, can berE                disconnected (this may cause the client to lose data).   /                   $ HTTPD /DO=DECNET=DISCONNECT   L                Purging is a better alternative, disconnecting idle tasks andA                marking busy ones for disconnection when complete.   *                   $ HTTPD /DO=DECNET=PURGE               5.3.2.6 Loggingi  K                Server logging control may also be exercised from the serverP3                administration menu, see Chapter 11.                   Open a log file.   &                   $ HTTPD /DO=LOG=OPEN  J                Optionally open and specify a log file name. This overridesC                any /LOG=file-name or HTTPD$LOG specified file name.   0                   $ HTTPD /DO=LOG=OPEN=file-name  M                The log file may be closed and reopened using a different nametJ                (allowing continuous operation but, for example, with dailyI                log files). This overrides any /LOG=file-name or HTTPD$LOGC#                specified file name.)  2                   $ HTTPD /DO=LOG=REOPEN=file-name  "                Close the log file.  '                   $ HTTPD /DO=LOG=CLOSE   @                Unwritten log records may be flushed to the file.  '                   $ HTTPD /DO=LOG=FLUSH   L                The format and period specification of the log may be changedL                (only takes effect after the next log file open/reopen) using  /                   $ HTTPD /DO=LOG=FORMAT=string /                   $ HTTPD /DO=LOG=PERIOD=string                5.3.2.7 MappingT                  See Chapter 8.,  @                The mapping rule file (HTTP$MAP) may be reloaded.  !                   $ HTTPD /DO=MAP   N                                            Server Account and Environment  5-9 S  E            (             5.3.2.8 Shutdown and Restart  D                Server shutdown may also be exercised from the server3                administration menu, see Chapter 11.u  K                The server may be shut down, without loss of existing clientrJ                requests. Connection acceptance is stopped and any existingB                requests continue to be processed until conclusion.  "                   $ HTTPD /DO=EXIT  K                The server may be immediately and unconditionally shut down.R  &                   $ HTTPD /DO=EXIT=NOW  K                The server may be restarted, without loss of existing clientrJ                requests. Connection acceptance is stopped and any existingG                requests continue to be processed until conclusion. ThisaI                effectively causes the server to exit normally and the DCLd/                wrapper procedure to restart it.e  %                   $ HTTPD /DO=RESTARTO  I                This variant restarts the server immediately regardless ofm$                existing connections.  )                   $ HTTPD /DO=RESTART=NOWc  5             5.4 Multi-Homed Hosts With Digital TCP/IP   G                A multi-homed host responds to connections for more than I                one network address. Details on configuring Digital TCP/IP J                (UCX) for this behaviour may be found in the Digital TCP/IPH                Management manual, section on "Subnetwork Routing" (3.4.8J                in the November 1995 edition) and Digital TCP/IP ManagementF                Command Reference, section on "SET INTERFACE" (NovemberJ                1995 edition). The server configuration parameter [Service]L                allows for the processing of requests for multiple host-namesM                and/or ports (see Section 6.2) while conditional mapping rulest?                enhance this basic capability (see Section 8.5).   L                Assuming an alternate, unused host name exists (for example):                     $ UCX c                   UCX> SET HOST "second.host.name" /ADDRESS=131.185.30.2 /ALIAS=("second","SECOND")s                   UCX> [EXIT]                    $   L                The system IP interface can be determined as follows (in thisF                example it is SE0, the LO0 is the localhost interface):  0             5-10  Server Account and Environment f  t            %                   UCX> SHOW INTERFACE,T                                                                              Packetsa                   Interface   IP_Addr         Network mask          Receive          Send     MTUe  a                    SE0        131.185.30.1    255.255.0.0            595567        262764    1500 d                    LO0        127.0.0.1       255.0.0.0                   1           573   65535  ?/                   UCX> SHOW INTERFACE SE0 /FULLo                    Interface: SE0`                     IP_Addr: 131.185.30.1      NETWRK: 255.255.0.0       BRDCST: 131.185.255.255V                                         Ethernet_Addr: AA-00-04-00-59-04    MTU:  1500                   .                    .O                   . :                     Restarting attempts                  0:                     Successful restarts                  0  K                Note the network and broadcast masks of the interface above.OL                The basic procedure then is to create a pseudo-interface (theA                "A" added to the hardware device name) as follows:   `                   UCX> SET INTERFACE SEA0 /HOST="second" /NET=255.255.0.0 /BROAD=131.185.255.255/                   UCX> SET PROTOCOL IP /FORWARD   M                After the above commands the interfaces should appear as shown                 below:g  %                   UCX> SHOW INTERFACE_T                                                                              Packetsa                   Interface   IP_Addr         Network mask          Receive          Send     MTU   a                    SE0        131.185.30.1    255.255.0.0            595567        262764    1500 a                    SEA0       131.185.30.2    255.255.0.0               169            99    1500 d                    LO0        127.0.0.1       255.0.0.0                   0          2263   65535  ?  M                These commands can be done interactively, during each startup, M                or placed in the permanent UCX configuration database once, as                 follows:   g                   UCX> SET CONFIG INTERFACE SEA0 /HOST="second" /NET=255.255.0.0 /BROAD=131.185.255.255r6                   UCX> SET CONFIG PROTOCOL IP /FORWARD  -                Note: Originating Host Addressa  J                Digital TCP/IP Services v4.1 at least, appears to determineI                an outgoing connection's originating host address from thehL                IP address of the "highest" pseudo-interface defined (in thisM                case from the SEA0, resulting in an apparent source address ofdK                131.185.30.2). This can cause some confusion on remote hostsiK                as to the origin of a connection, and otherwise be generallys                undesirable.   N                                           Server Account and Environment  5-11 C               L                A solution appears to be to assign the primary address to theM                last defined interface. This means the original interface muste!                be removed using a,  1                   UCX> SET CONFIG NOINTERFACE SE0b  H                then explicitly redefining it and then the new interface,K                ensuring the first is the non-primary address and the secondu                the primary.e                                                                                  0             5-12  Server Account and Environment                     M             Chapter__6_______________________________________________________s                Server Configuration    J                WASD's HTTPd configuration was originally a subset based onK                the CERN HTTPd. It has now evolved considerably. By default, J                the system-table logical name HTTPD$CONFIG locates a commonJ                configuration file, unless an individual configuration fileJ                is specified using a job-table logical name. Simple editingH                of this file changes the configuration. Comment lines mayI                be included by prefixing them with the hash "#" character. H                Configuration file directives are not case-sensitive. AnyG                changes to the configuration file can only be enabled by J                restarting the HTTPd process using the following command on!                the server system:   %                   $ HTTPD /DO=RESTARTo  M                A server's currently loaded configuration can be interrogated.v6                See Chapter 11 for further information.  *             6.1 Content-Type Configuration  D                HTTP uses a quasi-standard implementation of the MIMEI                (Multi-purpose Internet Mail Extensions) specification foraJ                identifying the type of data returned in a response. A MIMEJ                content-type consists of a plain text string describing theL                data as a type and slash-separated subtype, as illustrated in&                the following examples:                     text/htmlI                   text/plain                   image/gif                    image/jpeg*                   application/octet-stream  M                The content-type is returned to the client as part of the HTTPdL                response, the client then using this information to correctlyG                process and present the data contained in that response.   G                In common with most HTTP servers WASD uses a file's type L                (extension, suffix, e.g. ".HTML", ".TXT", ".GIF") to identifyJ                the data type within the file. The [AddType] directive (seeL                below) is used in configuration to bind a file type to a MIMEM                content-type. To make the server recognise and return specific K                content-types the [AddType] directives matches file types to                 content-types.)  N                                                      Server Configuration  6-1 a               J                NOTE: When adding a totally new content-type to the config-J                uration be sure also to bind an icon to that type using theK                [AddIcon] directive (see below). When this is not done a di- ?                rectory listing shows "[?]" in place of an icon.   M                With the VMS file system there is no effective file character- M                istic or algorithm for identifying a file's content without an L                exhaustive examination of the data contained there-in . . . aI                very expensive process (and probably still inconclusive inc@                many cases), hence the reliance on the file type.  I                If a file type is not recognised (i.e. no [AddType] corre-vI                sponding to the file type) then by default WASD identifiesSI                its data as application/octet-stream (i.e. essentially bi-hL                nary data). Most browsers respond to this content-type with aM                download dialog, allowing the data to be saved as a file. Most4L                commonly these unknown types manifest themselves when authorsK                use "interesting" file names to indicate their purpose. Here <                are some examples the author has encountered:                     README.VMS                   README.1ST                   READ-ME.FIRST $                   BUILD.INSTRUCTIONS,                   MANUAL.PT1 (.PT2,  . . . )  E                If the site administrator would prefer another defaultiJ                content-type, perhaps "text/plain" so that any unidentifiedG                files default to plain text, then this may be configuredfH                by specifying that content-type as the description of the@                catch-all file type entry. Examples (use one of):                     [AddType] *                   *  internal/x-unknown  -D                   *  internal/x-unknown  -  application/octet-stream6                   *  internal/x-unknown  -  text/plainC                   *  internal/x-unknown  -  something/else-entirelyo  M                It is the author's opinion that unidentified file types should K                remain as binary downloads, not "text" documents, which they J                are probably more often not, but it's there if it's wanted.  4             6.1.1 Explicitly Specifying Content-Type  H                When accessing files it is possible to explicitly specifyI                the identifying content-type to be returned to the browsernJ                in the HTTP response header. Of course this does not changeG                the actual content of the file, just the header content-gM                type! This is primarily provided to allow access to plain-textzL                documents that have obscure, non-"standard" or non-configured                file extensions.v  %             6-2  Server ConfigurationC a  L            F                It could also be used for other purposes, "forcing" theK                browser to accept a particular file as a particular content-CJ                type. This can be useful if the extension is not configuredJ                (as mentioned above) or in the case where the file containsM                data of a known content-type but with an extension conflictingcH                with an already configured extension specifying data of a&                different content-type.  M                Enter the file path into the browser's URL specification fieldrJ                ("Location:", "Address:"). Then, for plain-text, append the&                following query string:  0                   ?httpd=content&type=text/plain  H                For another content-type substitute it appropriately. ForF                example, to retrieve a text file in binary (why I can't                imagine :^) use  >                   ?httpd=content&type=application/octet-stream  "                This is an example:  /                <online hypertext demonstration>s  M                It is posssible to "force" the content-type for all files in aiM                particular directory. Enter the path to the directory and theny                add  .                   ?httpd=index&type=text/plain  L                (or what-ever type is desired). Links to files in the listingE                will contain the appropriate "?httpd=content&type=..."=*                appended as a query string.  "                This is an example:  /                <online hypertext demonstration>e               6.2 Directives  J                NOTE: The format of the configuration file has been changedK                between version 3 and version 4. This was to support on-line L                server configuration and administration (see Chapter 11). TheM                version 3 format will still be read by the HTTPd but the firstiK                time the configuration is updated on-line it is saved in the 1                version 4 format, described below.   M                The example configuration file for the WASD HTTP server can be                 viewed.  &                <online hypertext link>  N                                                      Server Configuration  6-3                 K                Some directives take a single parameter, such as an integer, F                string or boolean value. Other directives can/must haveL                multiple parameters. The version 4 configuration requires theK                directive to be placed on a line by itself and each separate,M                parameter on a separate line following it. All parameter linese@                apply to the most recently encountered directive.  E                Note that all boolean directives are disabled (OFF) bynL                default. This is done so that there can be no confusion aboutH                what is enabled and disabled by default. To use directiveA                controlled facility it must be explicitly enabled.r  :                1. [Accept] host/domain name (default: all)  L                   One or more (comma-separated if on the same line) internetL                   host/domain names, with "*" wildcarding for host/subdomainJ                   matching, to be explicitly allowed access. If DNS lookupF                   is not enabled hosts must be expressed using numericE                   addresses (see [DNSLookup] directive). Also see theoG                   [Reject] directive. Reject directives have precedencemJ                   over Accept directives. The Accept directive may be used!                   multiple times.                      Examples:N                        [Accept]n/                      *.wasd.dsto.defence.gov.au "                      131.185.250.*  5                2. [ActivityDays] integer (default: 0)   M                   Specifies the number of days to record activity statistics,uI                   available in report form from the server administrationfJ                   menu (see Section 11.2). Zero disables this data collec-H                   tion. The maximum is 28 days. 11520 bytes per day, andK                   80640 per week, is required to store the per-minute data..  D                3. [AddIcon] icon-URL ALT-text template  (no default)  M                   Specifies a directory listing icon and alternative text forSB                   the mime content type specified in the template.                     Examples:(                        [AddIcon]8                      /icon/-/doc.gif    [HTM]  text/html9                      /icon/-/text.gif   [TXT]  text/plainI8                      /icon/-/image.gif  [IMG]  image/gif  )                4. [AddBlankIcon] icon-URLi0                   [AddDirIcon] icon-URL ALT-text3                   [AddParentIcon] icon-URL ALT-text B                   [AddUnknownIcon] icon-URL ALT-text (no defaults)  %             6-4  Server Configurationd s  t            K                   Specifies a directory listing icon for these non-content-a,                   type parts of the listing.                     Examples:   8                      [AddBlankIcon]    /icon/-/blank.gifA                      [AddDirIcon]      /icon/-/dir.gif      [DIR] A                      [AddParentIcon]   /icon/-/back.gif     [<--] A                      [AddUnknownIcon]  /icon/-/unknown.gif  [???]a  G                5. [AddType] .suffix representation encoding script-nameN+                   description  (no default)t  I                   Binds a file suffix (extension, type) to a mime contenteH                   type. The script name is used to auto-script against aL                   specified file type. The description is used as documenta-.                   tion for directory listings.                     Examples:t                        [AddType]I                      .html  text/html   -       HyperText Markup Languagee:                      .txt   text/plain  -       plain text;                      .gif   image/gif   -       image (GIF)-B                      .hlb   text/x-script /Conan  VMS Help libraryQ                      .decw$book   text/x-script   /HyperReader    Bookreader booklF                      *  internal/x-unknown -  application/octet-stream9                      #*  internal/x-unknown -  text/plainm  J                   (Versions prior to 3.2 used this configuration directiveK                   for the MIME content-type to determine whether a file wasrM                   transfered record-by-record or in binary. This is no longereL                   required and should be removed from existing configuration                   files.)   B                6. [AuthBasic] ENABLED|DISABLED (default: DISABLED)  H                   Enables or disables BASIC username authentication. See                   Chapter 9.  :                7. [AuthCacheMinutes] integer (default: 60)  E                   The number of minutes authentication information isnI                   cached before being revalidated from the authenticationCK                   source. Zero disables caching (with a resultant impact onnI                   performance as each request requiring authentication isO6                   validated directly from the source).  C                8. [AuthDigest] ENABLED|DISABLED (default: DISABLED)S  I                   Enables or disables Digest username authentication. See                    Chapter 9.  :                9. [AuthDigestGetLife] integer (default: 0)  N                                                      Server Configuration  6-5 5  .            H                   The number of seconds a digest nonce for a GET request;                   (read) can be used before becoming stale.   :               10. [AuthDigestPutLife] integer (default: 0)  @                   The number of seconds a digest nonce for a PUTI                   (/POST/DELETE ... write) request can be used before be-                    coming stale.0  :               11. [AuthFailureLimit] integer (default: 10)  G                   The number of unsuccessful attempts at authentication D                   before the username is disabled. Once disabled anyM                   subsequent attempt is automatically refused without furtheroM                   reference to the authentication source. A disabled usernamet?                   can be reenabled by simply purging the cache.o  C               12. [AuthRevalidateUserMinutes] integer (default: 60)5  K                   The number of minutes between authenticated requests thatRM                   user authentication remains valid before the user is forcedhH                   to reenter the authentication information (via browserJ                   dialog). Zero disables the requirement for revalidation.                 13. [AuthVMS]f  K                   (Retired in v4.4, server /SYSUAF qualifier provides this)   .               14. [Busy] integer (default: 10)  L                   The maximum number of concurrent client connections beforeK                   a "server too busy right now ... try again shortly" error ,                   is returned to the client.  >               15. [Cache] ENABLED|DISABLED (default: DISABLED)  9               16. [CacheChunkKBytes] integer (default: 0)   I                   Granularity of memory blocks allocated to file data, in                    kilobytes.  8               17. [CacheEntriesMax] integer (default: 0)  F                   Maximum number of files loaded into the cache beforeH                   entries are reused removing the original contents from                   the cache.  ;               18. [CacheFileKBytesMax] integer (default: 0)   I                   Maximum size of a file before it is not a candidate for -                   being cached, in kilobytes.e  :               19. [CacheFrequentHits] integer (default: 0)  L                   Minimum, total number of hits an entry must sustain beforeJ                   being a candidate for [CacheFrequentSeconds] assessment.  =               20. [CacheFrequentSeconds] integer (default: 0)   %             6-6  Server Configuration  v  A            K                   If a file has been hit at least [CacheFrequentHits] times H                   in total and the last was within the number of secondsJ                   here specified it will not be a candidate for reuse. See                   Chapter 13.T  >               21. [CacheHashTableEntries] integer (default: 0)  )                   Size of the hash table.   <               22. [CacheTotalKBytesMax] integer (default: 0)  F                   Maximum memory allocated to the cache, in kilobytes.  =               23. [CacheValidateSeconds] integer (default: 0)r  L                   The interval after which a cache entry's original, contentI                   revision time is revalidated against the file's currentiJ                   revision time. If not the same the contents are declared'                   invalid and reloaded.P  F               24. [CommentedInfo] ENABLED|DISABLED (default: DISABLED)  G                   Includes, as META information, the software ID of theaD                   server and any relevant VMS file specification for*                   directory listings, etc.  ;               25. [DclCgiPlusLifeTime] integer (default: 0)t  I                   This value represents time in minutes. If this value is M                   zero CGIplus subprocess may persist indefinitely (excluding-I                   explicit and proactive server purging). If non-zero theeG                   CGIplus subprocess is terminated the specified numberwJ                   of minutes after it last processed a request. This helpsF                   prevent sporadically used scripts from clogging up a                   system.   G               26. [DclFullRequest] ENABLED|DISABLED (default: DISABLED)o  G                   Versions of the server prior to 4.3 supplied the fullmH                   request (header then body) to the script. This was notM                   fully CGI-compliant. Versions 4.3 and following supply only M                   the body, although the previous behaviour may be explicitly D                   selected by enabling this configuration parameter.  5               27. [DclHardLimit] integer (default: 0)p  I                   The maximum number of DCL/CGI script processing subpro- L                   cesses that may ever exist concurrently (works in conjunc-+                   tion with [DclSoftLimit].t  ;               28. [DclScriptRunTime] string (default: none)   E                   One or more file type (extension) specification and 9                   scripting verb pairs. See Section 12.3.n  5               29. [DclSoftLimit] integer (default: 0)A  N                                                      Server Configuration  6-7 F  t            F                   The number of DCL/CGI script processing subprocessesH                   after which idle subprocesses are deleted to make roomJ                   for new ones. The [DclHardLimit] should be approximatelyH                   25% more than the [DclSoftLimit]. The margin exists toI                   allow for occasional slow run-down of deleted/finishing L                   subprocesses. If these limits are not set (i.e. zero) theyL                   are calculated with [Busy] using "[DclSoftLimit] = [Busy]"M                   and "[DclHardLimit] = [DclSoftLimit] + [DclSoftLimit] / 4".   I               30. [DclSpawnAuthPriv] ENABLED|DISABLED (default: DISABLED)   K                   By default, when a DCL/scripting subprocess is spawned ithK                   inherits the server's currently enabled privileges, whichcK                   are none, not even TMPMBX or NETMBX. If this parameter ishM                   enabled the subprocess is created with the server account's K                   SYSUAF-authorized privileges (which should never be othera<                   than NETMBX and TMPMBX). Use with caution.  :               31. [DclZombieLifeTime] integer (default: 0)  I                   This value represents time in minutes. If this value is M                   zero the use of persistant DCL subprocesses is disabled. If L                   non-zero the zombie subprocess is terminated the specifiedK                   number of minutes after it last processed a request. This K                   helps prevent zombie processes from clogging up a system. !                   See Chapter 12.e  <               32. [DECnetReuseLifeTime] integer (default: 0)  H                   The number of minutes a DECnet scripting connection isL                   maintained with the network task. Zero disables connection                   reuse.  =               33. [DECnetConnectListMax] integer (default: 0)m  L                   The size of the list used to manage connections for DECnetI                   scripting. Zero effectively allows the server to use as @                   many DECnet scripting connections as demanded.  C               34. [DirAccess] ON|OFF| SELECTIVE (default: DISABLED)l  K                   Controls directory listings. SELECTIVE allows access only H                   to those directories containing a file .WWW_BROWSABLE.I                   The WASD HTTPd directory access facility always ignoreseK                   directories containing a file named .WWW_HIDDEN. Also seeo.                   the [DirWildcard] directive.  H               35. [DirDescription] ON|OFF| SELECTIVE (default: DISABLED)  D                   Retired in v5.0, replaced by [DirDescriptionLines]  <               36. [DirDescriptionLines] integer (default: 0)  %             6-8  Server Configuration                  J                   Non-Zero enables HTML file descriptions during listings.I                   Generating HTML descriptions involves opening each HTMLrL                   file and searching for <TITLE>...</TITLE> and <H1>...</H1>H                   text to generate the description. This is an obviouslyL                   resource-intensive activity and on busy servers or systemsK                   may be disabled. Any non-zero number specifies the numberoM                   of lines to be searched before quitting. Set to a very high H                   number to search all of files' contents (e.g. 999999).  =               37. [DirLayout] string (default: I__L__R__S__D)   L                   Allows specification of the directory listing layout. ThisH                   is a short, case-insensitive string that specifies theH                   included fields, relative placement and optionally theK                   width of the fields in a directory listing. Each field is L                   controlled by a single letter and optional leading decimalJ                   number specifying its width. If a width is not specifiedJ                   an appropriate default applies. An underscore is used toL                   indicate a single space and is used to separate the fields/                   (two consecutive works well)..  &                   o  C - creation date  D                   o  D - description (generally best specified last)  J                     o  D:L - for files, make a link out of the description                        text   >                   o  I - icon (takes no field-width attribute)  M                   o  L - link (highlighted anchor using the name of the file)u  ?                   o  N - name (no link, why bother? who knows!)   0                   o  O - owner (can be disabled)  &                   o  R - revision date                     o  S - sizet  7                     o  S:B - in bytes (comma-formatted)t  6                     o  S:D - decimal kilos (see below)  M                     o  S:F - kilo and mega are displayed to one decimal placet  B                     o  S:K - in kilo-bytes (and fractions thereof)  B                     o  S:M - in mega-bytes (and fractions thereof)  I                   o  U - upper-case file and directory names (must be the %                      first character)n  N                                                      Server Configuration  6-9 P  u            4                   The following shows some examples:  4                      [DirLayout]       I__L__R__S__D6                      [DirLayout]       I__L__R__S:b__D3                      [DirLayout]       I__15L__S__D 4                      [DirLayout]       UI__15L__S__D1                      [DirLayout]       15L__9R__S 2                      [DirLayout]       15N_9C_9R_S6                      [DirLayout]       I__L__R__S:d__D7                      [DirLayout]       25D:l__S:b__C__Rn  H                   The size of files is displayed by default as 1024 byteM                   kilos. When using the "S:k", "S:m" and "S:f" size modifiers M                   the size is displayed as 1000 byte kilos. If it is preferedlM                   to have the default display in 1000 byte kilos then set thel1                   directory listing layout using:t  6                      [DirLayout]       I__L__R__S:d__D  K                   If unsure of the kilo value being used check the "<META>" 7                   information in the directory listing.i  D               38. [DirNoImpliedWildcard] ON|OFF  (default: DISABLED)  E                   When a directory is accessed having no file or type D                   component and there is no welcome page available aF                   directory listing is generated. By default any otherF                   directory accessed from this listing has the impliedG                   wildcards "*.*" added, consequently forcing directorymK                   listings. If enabled, this directive ensures no wildcards L                   are added, so subsequent directories accessed with welcome@                   pages display the pages, not a forced listing.  ?               39. [DirNoPrivIgnore] ON|OFF  (default: DISABLED)l  I                   To prevent browsing through directories (perhaps due tonJ                   inadvertant mapping) that have file permissions allowingJ                   no WORLD access the server stops listing and reports theJ                   error the first time a protection violation occurs. ThisK                   behaviour may be changed to ignore the violation, listing.:                   only those files to which it has access.  8               40. [DirOwner] ON|OFF  (default: DISABLED)  H                   Allows specification and display of the RMS file owner                   information.  G               41. [DirPreExpired] ENABLED|DISABLED  (default: DISABLED)t  K                   Directory listings and trees may be pre-expired. That is,cK                   the listing is reloaded each time the page is referenced. I                   This is convenient in some environments where directory I                   contents change frequently, but adds considerable over-/J                   head and so is disabled by default. Individual directory  &             6-10  Server Configuration    -            K                   listings may have the default behaviour over-ridden usingI;                   syntax similar to the following examples:e  ;                      /dir1/dir2/*.*?httpd=index?expired=yese:                      /dir1/dir2/*.*?httpd=index?expired=no8                      /tree/dir2/?httpd=index?expired=yes<                      /tree/dir1/dir2/?httpd=index?expired=no  B               42. [DirReadme] TOP|BOTTOM | OFF (default: DISABLED)  H                   If any of the files provided using the [DirReadMeFile]I                   directive are located in the directory the contents are I                   included at the top or bottom of the listing (or not at G                   all). Plain-text are included as plain-text, HTML arefG                   included as HTML allowing markup tags to be employed.i  :               43. [DirReadMeFile] FILE.SUFFIX (no default)  G                   Specifies the names and order in which a directory is L                   checked for read-me files. This can be enabled or disabledM                   using the [DirReadme] directive. Plain-text are included askL                   plain-text, HTML are included as HTML allowing markup tags!                   to be employed.                      Examples:   $                      [DirReadMeFile]                       readme.html                      readme.htm                       readme.                      readme.txtn                      readme.1st-  :               44. [DirWildcard] OFF|ON (default: DISABLED)  J                   This enables the facility to force the server to provideK                   a directory listing by providing a wildcard file specifi- K                   cation, even if there is a home (welcome) document in thelM                   directory. This should not be confused with the [DirAccess]aD                   directive which controls directory listing itself.  B               45. [DNSLookup] ENABLED|DISABLED (default: DISABLED)  J                   Enables or disables connection request host name resolu-H                   tion. This functionality may be expensive (in terms ofK                   processing overhead) and make serving granularity coarserdL                   if DNS is involved. If not enabled and logging is, the en-L                   try is logged against the numeric internet address. If notI                   enabled any [Accept], [Reject] directive, etc., must bee1                   expressed as numeric addresses.A  L                   This functionality significantly slows request processing.!                   See Chapter 14.a  N                                                     Server Configuration  6-11 e               K                   NOTE: From version 4.4 the HTTPd processes initial client I                   connection at AST delivery level. Some NETLIB-supportednM                   TCP/IP packages cannot perform host name resolution at thisaI                   level and will "hang". If using NETLIB with [DNSlookup] D                   enabled and this seems to occur disable it (NETLIBE                   DNSlookup certainly does work with Digital TCP/IP).   G               46. [ErrorRecommend] ENABLED|DISABLED (default: DISABLED)(  M                   Provides a short message recommending action when reportingcL                   an error to a client. For example, if a document cannot be#                   found it may say:i  ?                      (document, or bookmark, requires revision)c  H               47. [ErrorSourceInfo] ENABLED|DISABLED (default: DISABLED)  H                   When an error message is generated META information isM                   included showing the server version with source code moduleeJ                   and line reporting the error. This is useful informationG                   during development and often during general use. Onlyt/                   disable if this concerns you.                  48. [ErrorInfo]s  H                   (Retired in v4.4, message configuration provides this)  !               49. [ErrorSysAdmin]/  H                   (Retired in v4.4, message configuration provides this)  5               50. [InputTimeout] integer (default: 2)e  G                   Number of minutes to allow a connection request to bewJ                   in progress without submitting a complete request header(                   before terminating it.  @               51. [Logging] ENABLED|DISABLED (default: DISABLED)  L                   Enables or disables the request log. Logging can slow downI                   request processing and adds overhead. The log file namenI                   must be specified using the /LOG qualifier or HTTPD$LOG 2                   logical name (see Logical Names.  :               52. [LogExcludeHosts] string (default: none)  L                   One or more (comma-separated if on the same line) internetL                   host/domain names, with "*" wildcarding for host/subdomainI                   matching, requests from which are not placed in any logcM                   files. If DNS lookup is not enabled hosts must be expressed J                   using numeric addresses (see [DNSLookup] directive). UseI                   for excluding local or web-maintainer's host from logs.o  &             6-12  Server Configuration    r                               Example:  &                      [LogExcludeHosts]/                      *.wasd.dsto.defence.gov.au "                      131.185.250.*  6               53. [LogFormat] string (default: COMMON)  H                   Specifies one of three pre-defined formats, or a user-6                   definable format. See Section 6.4.1.  4               54. [LogNaming] string (default: none)  L                   When [LogPeriod] or [LogPerService] directives are used toK                   generate multiple log files this directive may be used toCC                   modify the naming of the file. See Section 6.4.4.n  4               55. [LogPeriod] string (default: none)  J                   Specifies a period at which the log file is changed. See                    Section 6.4.2.  F               56. [LogPerService] ENABLED|DISABLED (default: DISABLED)  H                   When multiple services are specified (see Section 6.3)I                   a separate log file will be created for each if this ish-                   enabled. See Section 6.4.3.M  @               57. [Monitor] ENABLED|DISABLED (default: DISABLED)  F                   Allows monitoring via the HTTPDMON utility (see Sec-E                   tion 16.5. Adds slight request processing overhead.   7               58. [OutputTimeout] integer (default: 10)i  J                   Number of minutes to allow a request to be output before!                   terminating it.G  .               59. [Port] integer (default: 80)  7                   IP port number for server to bind to.r  7               60. [PutMaxKBytes] integer (default: 250)u  G                   Maximum size of an HTTP POST or PUT method request in                    Kilobytes.  8               61. [PutVersionLimit] integer (default: 3)  E                   File created using the POST or PUT methods have theh2                   specified version limit applied.  ;               62. [Reject] host/domain name (default: none)p  L                   One or more (comma-separated if on the same line) internetL                   host/domain names, with "*" wildcarding for host/subdomainI                   matching, to be explicitly denied access. If DNS lookup F                   is not enabled hosts must be expressed using numericE                   addresses (see [DNSLookup] directive). Also see the   N                                                     Server Configuration  6-13 n  d            G                   [Accept] directive. Reject directives have precedencenH                   of Accept directives. The Reject directive may be used!                   multiple times.e                     Example:                        [Reject] /                      *.wasd.dsto.defence.gov.au "                      131.185.250.*  7               63. [RequestHistory] integer (default: 0)   H                   The server can keep a list of the most recent requestsL                   accessable from the server administration menu. This valueI                   determines the number kept. Zero disables the facility.cK                   Each retained request consumes 256 bytes and adds a small 6                   amount of extra processing overhead.  ,               64. [Search] path (no default)  I                   Specifies the physical path to the default query-string[(                   keyword search script.                     Examples:B  1                      Search /ht_root/script/queryu  /               65. [Service] string (no default)   K                   This parameter allows SSL, multi-homed hosts and multiple D                   port serving to be specified, see Section 10.1 and                   Section 6.3.  <               66. [SSI] ENABLED|DISABLED (default: DISABLED)  E                   Enables or disables Server Side Includes (HTML pre-                    processing).  D               67. [SSIaccesses] ENABLED|DISABLED (default: DISABLED)  E                   Enables or disables Server Side Includes (HTML pre-I2                   processing) file access counter.  @               68. [SSIexec] ENABLED|DISABLED (default: DISABLED)  E                   Enables or disables Server Side Includes (HTML pre- :                   processing) DCL execution functionality.  <               69. [StreamLF] integer (default: 0 (disabled))  F                   Enables or disables automatic conversion of VARIABLEI                   record format documents (files) to STREAM-LF, which areiJ                   much more efficient with this server. The integer is theJ                   maximum size of a file in kilobytes that the server willL                   attempt to convert. Zero disables the conversion. Also see"                   [StreamLFpaths].  5               70. [StreamLFpaths] string (no default)   &             6-14  Server Configuration                 J                   Specifies which path(s) automatic conversion of VARIABLEL                   record format files to STREAM-LF is allowed. If no path isM                   provided all conversion is disabled. To allow conversion oni:                   all paths use "/*". Also see [StreamLF].                     Example:  $                      [StreamLFpaths]                      /ht_root/*a                      /web/*   4               71. [Welcome] file.suffix (no default)  G                   Specifies the names and order in which a directory is I                   checked for home page files. If no home page is found a 1                   directory listing is generated.                      Examples:r                        [Welcome]                      home.html                      home.htmi                      home.menu                      home.mnup  3             6.3 Multi-Homed and Multi-Port Servicesf  J                By default the server is defined by the local host name andH                port specified by either [port] or /PORT. The WASD serverI                is capable of concurrently supporting a number of servicesAI                on different port numbers and, if the system is configuredsF                to be multi-homed (see Section 5.4), more than one hostG                name. Using the [Service] configuration parameter or theaH                /SERVICE qualifier the server creates an HTTP service forM                each specified. If the host name is omitted it defaults to theeI                local host name. If the port is omitted it defaults to 80.r  H                This rather contrived example show a server configured to9                provide four services over two host names.o                     [Service] 0                   alpha.wasd.dsto.defence.gov.au                   8080/                   beta.wasd.dsto.defence.gov.aua4                   beta.wasd.dsto.defence.gov.au:8000  J                This capability combined with conditional rule mapping (seeL                Section 8.5) offers versatile and powerful service provision.G                The first port specified in the service list becomes theiH                "official" port of the server, using the local host name.  N                                                     Server Configuration  6-15 n  i                         6.4 Access Logging  H                WASD provides a versatile access log, allowing data to beH                collected in Web-standard common and combined formats, asJ                well as allowing customization of the log record format. ItH                is also possible to specify a log period. If this is doneJ                log files are automatically changed according to the periodI                specified. Exclude requests from specified hosts using thec9                [LogExcludeHosts] configuration parameter.i               6.4.1 Log Format  E                The configuration parameter [LogFormat] and the server L                qualifier /FORMAT specifies one of three pre-defined formats,F                or a user-definable format. Most log analysis tools canF                process the three pre-defined formats. There is a smallH                performance impost when using the user-defined format, asJ                the log entry must be specially formatted for each request.  K                1. COMMON - This is the most common, base logging format for @                   Web servers. COMMON is the default log format.  K                2. COMMON_SERVER - This is an optional format used, for one,[H                   by the NCSA server. It is basically the common format,J                   with the server host name appended to the line (used for8                   multi-homed servers, see Section 6.3).  L                3. COMBINED - This is an optional format used, for one again,L                   by the NCSA server. It too is basically the common format,@                   with the HTTP referer and user agent appended.                  User-Defined   J                The user-defined format allows customised log formats to beI                specified using a selection of commonly required data. ThenJ                specification must begin with a character that is used as aK                substitute when a particular field is empty (use "\0" for noeI                substitute, as in the "windows log format" example below).e  H                Two different "escape" characters introduce the following                parameters:                   A "!" followed by  4                o  AR - authentication realm (if any)  7                o  AU - authenticated user name (if any)   ?                o  BB - bytes in body (excludes response header)   :                o  BY - bytes in response (includes header)  K                o  CN - client host name (or address if DNS lookup disabled)   &             6-16  Server Configuration d  u            %                o  CA - client addresss  ;                o  EM - request elapsed time in millisecondsd  A                o  ES - request elapsed time in fractional seconds   %                o  ME - request methodg  B                o  PA - request path (not to be confused with "RQ")  4                o  QS - request query string (if any)  '                o  RF - referer (if any).  :                o  RQ - complete request string (see below)  +                o  RS - response status code:  '                o  SN - server host namei  +                o  SC - script name (if any)   7                o  SM - request scheme (http: or https:)r  "                o  SP - server port  7                o  TC - request time (common log format)b  )                o  TG - request time (GMT)h  0                o  TV - request time (VMS format)  !                o  UA - user agentn                   A "\" followed by  F                o  0 - a null character (used to define the empty field                   character)  #                o  ! - insert an "!"i  "                o  \ - insert a "\"  &                o  n - insert a newline  J                o  q - insert a quote (so that in DCL the quotes won't need                   escaping!)  "                o  t - insert a TAB  K                Any other character is directly inserted into the log entry.i  N                                                     Server Configuration  6-17 r  y            $                Note on "PA" and "RQ"  I                The "PA" and "RQ" have distinct roles. In general the "RQ"SJ                (request) directive will always be used as this is the fullI                request string; script component (if any), path string andtL                query string component (if any). The "PA" directive is merelyK                the path string after any script and query string componentsf!                have been removed.L                  Examples   =                1. The equivalent of the common log format is:e  5                      -!CN - !AU [!TC] \q!RQ\q !RS !BY   @                2. The combined log format could be specified as:  E                      -!CN - !AU [!TC] \q!RQ\q !RS !BY \q!RF\q \q!UA\qe  L                3. The O'Reilly WebSite "windows log format" would be created                   by:i  S                      \0!TC\t!CA\t!SN\t!AR\t!AU\t!ME\t!PA\t!RQ\t!EM\t!UA\t!RS\t!BB\t   I                4. The common log format with appended request duration in 2                   seconds could be provided using:  9                      -!CN - !AU [!TC] \q!RQ\q !RS !BY !ESa               6.4.2 Log Period  J                The access log file may have a period specified against it,J                producing an automatic generation of log file based on thatK                period. This allows logs to be systematically named, orderedhL                and kept to a managable size. The period specified can be one                ofd                  o  DAILY   !                o  weekly as . . .s                   MONDAY                   TUESDAYo                   WEDNESDAYl                   THURSDAY                   FRIDAY                   SATURDAY                   SUNDAY                  o  MONTHLYy  J                The log file changes on the first request after midnight ofJ                the new period. When using a weekly period the new log fileK                comes into effect on the first request following midnight one!                the specified day.   &             6-18  Server Configuration r  i            I                When using a periodic log file, the file name specified by H                HTTPD$LOG or the configuration parameter [LogFileName] isF                partially ignored, only partially because the directoryJ                component of it is used to located the generated file name.=                The periodic log file name generated comprises   "                o  server host name                  o  server port                   o  year (YYYY)a                  o  month (MM)                  o  day (DD)  *                as in the following example  5                   HT_LOGS:WASD_80_19971013_ACCESS.LOGc  M                For the daily period the date represents the request date. FortL                the weekly period it is the date of the previous (or current)M                day specified. That is, if the request occurs on the WednesdayeL                for a weekly period specified by Monday the log date show theG                last Monday's. For the monthly period it uses the first.   !             6.4.3 Log Per-Servicei  K                By default a single access log file is created for each HTTPEF                server process. Using the [LogPerService] configurationJ                directive a log file for each service provided by the HTTPd.                is generated (see Section 6.3).               6.4.4 Log Naming  K                When per-period or per-service logging is enabled the accesstM                log file has a name generated. Part of this name is the host'snL                name or IP address. By default the host name is used, howeverJ                if the host IP address is specified the dot-numeric addressK                is used, hyphens being substituted for the periods. AcceptediF                values for the [LogNaming] configuration directive are:                   o  NAME (default)                  o  ADDRESSu  L                Examples of generated per-service (non-per-period) log names:  ,                   HT_LOGS:WASD_80_ACCESS.LOG7                   HT_LOGS:131-185-250-202_80_ACCESS.LOG   J                Examples of generated per-period (with/without per-service)                log names:i  5                   HT_LOGS:WASD_80_19971013_ACCESS.LOGL@                   HT_LOGS:131-185-250-202_80_19971013_ACCESS.LOG  N                                                     Server Configuration  6-19                     M             Chapter__7_______________________________________________________   !             Message Configurations    B                Message configuration is provided for two purposes.  J                1. Some sites would prefer to customize or extend the basicH                   information provided to clients when an error or other                   event occurs.   L                2. Sites that do not use English as a first language may wishH                   to provide some or all of the defined messages using a$                   prefered language.  M                Not all messages provided by the WASD server are customizable,0J                only those generated for non-administrative content. As theI                WASD server can also report using information derived from I                the standard VMS message service (via sys$getmsg())  it istK                assumed a language-local implementation of this is in use as I                well. Unfortunately for the non-first-language-English WebdI                and system administrators, the menus and messages used forSH                administration purposes, etc., are still only in English.K                The intent of this facility is to provide non-administrationeF                clients only with a more familiar language environment.  K                Also note that the message database only applies to messagessH                generated by the server, not to any generated by scripts,                etc.h               7.1 Behaviour   E                When an error, or other message or string, needs to beAH                provided for the client the message database is accesssed-                using the following algorithm.n  H                1. If the client request has specified a list of preferedJ                   languages using the "Accept-Language:" HTTP header fieldK                   the message database is checked for support of that/those J                   languages. If one is found then that language is used to%                   access the message.   E                2. If none is found, or the client has not specified auG                   prefered language, the client host address is checkedyH                   against any list of hosts/domains provided against theG                   language (see below). If a match occurs the specified #                   language is used.l  N                                                     Message Configuration  7-1                 K                3. If neither of the above results in a message language the M                   base language is used (the highest numbered language). ThisbM                   must have a complete set of messages or the server will nots                   start!    #             7.2 Message File Formate  J                By default, the system-table logical name HTTPD$MSG locatesJ                a common message file, unless an individual message file isJ                specified using a job-table logical name. Simple editing ofM                the message file changes the messages (after a server restart,uJ                of course). Comment lines may be included by prefixing themM                with the hash character ("#"), and lines continued by ensuring1G                the last character is a backslash ("\"). The server will I                concurrently support an additional 3 languages to the base K                English (although this can be increased by recompilation :^)   I                Care must be taken with the message file or the server may                 refuse to start  G                As illustrated below the message file comprises a seriesrJ                of sections. Directives enclosed by square-brackets provide1                information to the message loader.u  %                   # this is a commentr                     [version] 4.4 &                   [language] 1 se *.se+                   [language] 2 de *.de,*.su5!                   [language] 3 en                      [general]r  -                   en 01 Sanity check failure. Q                   de 01 (the same message but in German, which I cannot speak :^) W                   se 01 (the same message but in Swedish, which I also cannot speak :^) (                   en 02 String overflow.Q                   de 02 (the same message but in German, which I cannot speak :^)s;                   se 01 (the same message but in Swedish, \n2                   which I still cannot speak :^) \I                   this has also been continued over two additional lines!I/                   en 03 Heap allocation failed. '                   en 04 calloc() failedS0                   en 05 Request calloc() failed.(                   en 06 Server too busy.-                   en 07 Server access denied.i-                   en 08 Facility is disabled.e/                   en 09 Wildcard not permitted. 1                   en 10 Directory layout problem.h  &                   [next-section, etc.]  &             7-2  Message Configuration                 G                The square-bracketed section headings have the following                 functions.d  F                1. [version] -  Ensures the correct database version isL                   available for the server version attempting to use it. TheL                   message file always needs checking for this version numberG                   being changed at server updates, although the version F                   may remain fixed at a previous server version numberG                   if there have been no changes to the message databasehK                   during subsequent server versions. This must be the first (                   directive in the file.  H                2. [language] -  Creates space for assigning the new lan-L                   guage's messages. The number specifies an order within theL                   languages, each must be different, but only the lowest andK                   highest (prefered and base respectively) have operational K                   significance. The highest number should always be English I                   to provide a fall-back message. A short string provides.H                   an identifier for the language. This identifier shouldJ                   be the same as the identifying string in the browser re-I                   quest "Accept-Language:" header field (e.g. "en", "se",RK                   "de", "fr", etc.) Following the language identifier is anmJ                   optional host/domain list. Multiple hosts/domains may beK                   specified by separating each with a comma. The specifica-aL                   tions may contain wildcards. All the [language] directivesH                   should be grouped at the start of the file immediatelyK                   following the [version] directive. Setting the language'ssK                   ordering number to zero disables the language completely.tG                   All messages associated with it will then be ignored.i  I                3. [group-name] -  The messages are divided into groupings K                   to make them easier to manage. Each group begins with the '                   group name directive.a  L                4. en 01 message -  Each message in a group is assigned usingI                   using this format. The string identifying the language,sI                   then the message number (the leading zero just improvessK                   the format, strictly it is not required), then the actualiI                   message itself. The message can be of arbitrary length. M                   Long messages may be continued on following lines using the5-                   "\" continuation character.g  K                The base language (the highest numbered, which should alwayseK                be English) must have precisely the right number of messages I                required by the server, too few or too many and the server K                will not start! Additional languages do not have to reassign M                every message! The base language will supply any not assigned. K                A message number of zero is disabled and completely ignored.   K                If messages contain HTML tags that markup must not interfere <                with the general HTML page it is used within.  N                                                     Message Configuration  7-3 t               H                Some messages are a composite of multiple strings each ofJ                which is used on a different part of the one page (e.g. forL                the [upd] edit-page). Each of the strings is delimited by theJ                vertical bar "|". Care must be taken when customizing theseJ                strings that the overall number stays the same and that theI                length of each does not become excessive. Although it willSK                not disrupt the server it may significantly disrupt the pageN                layout.  H                All message numbers must be included. To provide an emptyL                string for any one message (not recommended) provide the line9                with nothing following the message number.a  &             7.3 Supplied Message Files  L                Any non-English message files that are provided to the authorH                will be included for general use (please take the time toJ                support this endeavour) in the HT_ROOT:[EXAMPLE] directory.  &                <online hypertext link>  G                Note that message files can become out-of-date as servereF                versions change, requiring modifications to the messageM                database. Check the version information and/or comments at thetJ                top of candidate message files, however even slightly datedM                files may serve as a good starting point for a locale-specific                 message base.                                              &             7-4  Message Configuration d  e                M             Chapter__8_______________________________________________________                Mapping Rulesn    ;                Mapping rules are used in four primary ways.o  A                1. To map a request path onto the VMS file system.u  K                2. To process a request path according to specified criteria J                   resulting in an effective path that is different to that,                   supplied with the request.  I                3. To identify requests requiring script activation and totM                   parse the script from the path portion of that request. The ?                   path portion is then independently re-mapped.   L                4. To conditionally map to different end-results based on one2                   or more criteria of the request.  F                Mapping is basically for server-internal purposes only.J                The only time the path information of the request itself isK                modified is when a script component is removed. At all other <                times the path information remains unchanged.  F                Hence, path authorization is always applied to the pathH                supplied with the request, not to the results of any ruleL                mapping that may have occured! This means authorization pathsJ                may be administered without any ambiguity introduced by any+                rule mapping that may occur.n  J                By default, the system-table logical name HTTPD$MAP locatesL                a common mapping rule file, unless an individual rule file isH                specified using a job- table logical name. Simple editingG                of the mapping file changes the rules. Comment lines may I                be included by prefixing them with the hash "#" character. M                Although, there is no fixed limit on the number of rules therelJ                are the processing implications of scanning a large, linear                database.  J                Rules are given a basic consistency check when loaded (i.e.G                server startup, map reload, etc.) If there is an obviouscG                problem (unknown rule, missing component, etc., path not G                absolute) a warning message is generated and the rule is K                not loaded into the database. This will not cause the serveroJ                startup to fail. These warning messages may be found in the"                server process log.  E                The server administration rule mapping facility allowseI                arbitrary paths to be checked against the rule database inA+                real-time. See Section 11.2.   N                                                             Mapping Rules  8-1                 I                Any changes to the mapping file may be (re)loaded into the M                running HTTPd server using the following command on the serveri                system:  !                   $ HTTPD /DO=MAPo  ;                Also see Chapter 6 for daemon configuration.   #                Server Mapping Rules   M                A server's currently loaded mapping rules may be interrogated.p6                See Chapter 11 for further information.  .             8.1 VMS File System Specifications  H                The VMS file system in mapping rules is always assumed toJ                begin with a device or concealed device logical. SpecifyingG                a Master File Directory (MFD) component, the [000000] isLJ                completely optional, although always assumed to be implied.K                The mapping functions will always insert one if required foriJ                correct file system syntax. That is, if the VMS file systemK                mapping of a path results in a file in a top-level directoryaK                an MFD is inserted if not explicitly present in the mapping.f7                For example, both of the following pathso  %                   /dka100/example.txt ,                   /dka100/000000/example.txt  +                would result in a mapping tot  ,                   DKA100:[000000]EXAMPLE.TXT  H                The MFD is completely optional when both specifying pathsF                in mapping rules and when supplying paths in a request.G                Similarly, when supplying a path that includes directory ?                components the MFD is completely optional, as in   /                   /dka100/dir1/dir2/example.txt 6                   /dka100/000000/dir1/dir2/example.txt                  both mapping to  /                   DKA100:[DIR1.DIR2]EXAMPLE.TXTi  L                Implication: When using logical names in file system mappingsK                they must be able to be used as concealed devices and cannotlL                be logical equivalents of directory specifications. ConcealedF                device logicals are created using the following syntax:  ;                   $ DEFINE LOGICAL_NAME device:[dir1.dir2.] [                   $ DEFINE LOGICAL_NAME /TRANSLATION=CONCEALED physical_device:[dir1.dir2.]a               8-2  Mapping Rules y  e                         8.2 Rules   $                MAP, PASS, FAIL Rules  %                1. map template resulti  F                   If the URL path matches the template, substitute theJ                   result string for the path and use that for further ruleM                   processing. Both template and result paths must be absolute (                   (i.e. begin with "/").                  2. pass template &                   pass template result2                   pass template "999 message text"  F                   If the URL path matches the template, substitute theL                   result if present (if not just use the original URL path),.                   processing no further rules.  J                   The result should be a either a physical VMS file systemL                   specification in URL format or an HTTP status-code messageJ                   (see below). If there is a direct correspondance betweenD                   the template and result the result may be omitted.  K                   The "PASS" directive is also used to reverse-map VMS fileiC                   specifications to the URL path format equivalent._  J                   An HTTP status-code message can be provided as a result.L                   The server then generates a response corresponding to thatJ                   status code containing the supplied message. Status-codeG                   results should be enclosed in one of single or doubleoM                   quotes, or curly braces. See examples. A 3nn status resultssL                   in a redirection response with the message text comprisingM                   the location. Codes 4nn and 5nn result in an error message. M                   Other code ranges (e.g. 0, 1nn, 2nn, etc.) simply cause the K                   connection to be immediately dropped, and can be used for ;                   that purpose (i.e. no indication of why!)d                  3. fail template   H                   If the URL path matches the template, prohibit access,H                   processing no further rules. The template path must be1                   absolute (i.e. begin with "/").                   REDIRECT Rule  *                1. redirect template result  M                   If the URL path matches the template, substitute the result K                   string for the path. Process no further rules. The result G                   must be a full URL (http://host/path), and is used to I                   redirect requests to another server on a separate host.   N                                                             Mapping Rules  8-3 h               4                EXEC and SCRIPT, Script Mapping Rules                   EXEC+ and SCRIPT+  #                Also see Chapter 12.t  K                The "EXEC" and "SCRIPT" directives have the variants "EXEC+"nM                and "SCRIPT+". The variants behave in exactly the same fashion H                and simply mark the rule as representing a CGIplus scriptI                environment. See Section 12.7. Caution!  If changing rules K                involving these variants it is advised to restart the server K                rather than reload. Some conflict is possible when using new B                rules while existing CGIplus scripts are executing.  <                The "EXEC" rules maps CGI script directories.  L                The "SCRIPT" rules maps CGI script file names. It is a littleH                different to the "EXEC" rule and an extension to the CERN                rules.   L                Both rules must have a template and result, and both must endM                in a wildcard asterisk. The placement of the wildcards and the K                subsequent functionality is slightly different however. Both.J                template and result paths must be absolute (i.e. begin with                "/").  &                1. exec template result  E                   The "EXEC" rule requires the template's asterisk toeH                   immediately follow the slash terminating the directoryG                   specification containing the scripts. The script namenM                   follows immediately as part of the wildcard-matched string.f                   For example:  4                      exec /htbin/* /ht_root/script/*  K                   If the URL path matches the template, the result, includ-yM                   ing the first slash-terminated part of the wildcard-matchedwJ                   section, becomes the URL format physical VMS file speci-I                   fication the script to be executed. What remains of theoK                   original URL path is used to create the path information.e+                   Process no further rules.   I                   Hence, the "EXEC" rule will match multiple script spec- I                   ifications without further rules, the script name being K                   supplied with the URL path. Hence any script (i.e. proce-oM                   dure, executable) in the specified directory is accessable,.J                   a possible security concern if script management is dis-                   tributed.   (                2. script template result               8-4  Mapping Rules e               G                   The "SCRIPT" rule requires the template's asterisk totF                   immediately follow the unique string identifying theL                   script in the URL path. The wildcard-matched string is theJ                   following path, and supplied to the script. For example:  :                      script /conan* /ht_root/script/conan*  J                   If the URL path matches the template, the result becomesL                   the URL format physical VMS file specification for the DCLJ                   procedure of the script to be executed (the default fileK                   extension of ".COM" is not required). What remains of thecK                   original URL path is used to create the path information. +                   Process no further rules.   4                                                 Note  E                         The wildcard asterisk is best located immedi- D                         ately after the unique script identifier. InC                         this way there does not need to be any pathrF                         supplied with the script. If even a slash fol-C                         lows the script identifier it may be mapped H                         into a file specification that may or may not be1                         meaningful to the script.h  E                   Hence, the "SCRIPT" rule will match only the scriptoE                   specified in the result, making for finely-granulareI                   scripting at the expense of a rule for each script thusbK                   specified. It also implies that only the script name needl5                   precede any other path information.   I                   It may be thought of as a more efficient implementation I                   of the equivalent functionlity using two CERN rules, as 7                   illustrated in the following example:)  /                      map /conan* /script/conan* /                      exec /cgi-bin/* /cgi-bin/*   #             8.3 Rule Interpretations  K                The rules are scanned from first towards last, until a pass,eJ                exec, script or fail is encountered, when processing ceasesI                and final substitution occurs. Mapped rules substitute the F                template with the result and continue to the next rule.  7                Use of wildcards in template and result:h  E                o  The template may contain one or more asterisk ("*")eJ                   wildcard symbols. These match zero or more characters upH                   until the character following the wildcard (or end-of-M                   string). If no wildcard is present then the path must matchn'                   the template exactly.n  N                                                             Mapping Rules  8-5 t               L                o  The result may contain one or more asterisk ("*") wildcardF                   symbols. It must not contain more wildcards than theL                   template. The result wildcards are expanded to replace theK                   matching characters of the respective template wildcards.gI                   Characters represented by wildcards in the template notrG                   represented by a corresponding wildcard in the result J                   are ignored. Non-wildcard result characters are directlyI                   inserted in reconstructed path. Non-wildcard characterseH                   in the template are ignored. If the result contains no@                   wildcards it completely replaces the URL path.                  8.4 Mapping Examples  L                The example mapping rule file for the WASD HTTP server can be                viewed.  &                <online hypertext link>  "                Example of Map Rule  L                The result string of these rules may or may not correspond toK                to a VMS physical file system path. Either way the resultinguC                rule is further processed before passing or failing.f  I                1. The following example shows a path "/web/unix/shells/c"aK                   being mapped to "/web/software/unix/scripts/c", with this 6                   being used to process further rules.  9                      map /web/unix/* /web/software/unix/*   $                Examples of Pass Rule  M                The result string of these rules should correspond to to a VMS "                physical file path.  M                1. This example shows a path "/web/rts/home.html" being mappedeH                   to "/user$rts/web/home.html", and this returned as the                   mapped path.  4                      pass /web/rts/* /user$rts/web/*  T                2. This maps a path "/icon/bhts/dir.gif" to "/web/icon/bhts/dir.gif",7                   and this returned as the mapped path.   7                      pass /icon/bhts/* /web/icon/bhts/*s  I                3. This example illustrates HTTP status code mapping. EachsK                   of these does basically the same thing, just using one of K                   the three possible delimiters according to the characters E                   required in the message. The server generates a 403 M                   response with has as it's text the following message. (Also 8                   see the conditional mapping examples.)               8-6  Mapping Rules e  l            =                      pass /private/* "403 Can't go in there!"rE                      pass /private/* '403 "/private/" is off-limits!'sD                      pass /private/* {403 Can't go into "/private/"}    $                Examples of Fail Rule  L                1. If a URL path "/web/private/home.html" is being mapped the3                   path would immediately be failed.   (                      fail /web/private/*  H                2. To ensure all access fails, other than that explicitlyF                   passed, this entry should be included the the rules.                        fail /*  0                Examples of Exec and Script Rules  H                1. If a URL path "/htbin/ismap/web/example.conf" is beingM                   mapped the "/ht_root/script/" must be the URL format equiv-oK                   alent of the physical VMS specification for the directoryhL                   locating the script DCL procedure. The "/web/example.conf"J                   that followed the "/htbin/ismap" in the original URL be-J                   comes the translated path for the script. See Chapter 125                   for other information on scripting.r  /                      exec /cgi-bin/* /cgi-bin/*p  L                2. If a URL path "/conan/web/example.hlb" is being mapped theK                   "/ht_root/script/conan" must be the URL format equivalentsJ                   of the physical VMS specification for the DCL procedure.K                   The "/web/example.hlb" that followed the "/conan/" in the J                   original URL becomes the translated path for the script.D                   See Chapter 12 for other information on scripting.  :                      script /conan* /ht_root/script/conan*  '                Example of Redirect Rulea  D                1. If a URL path "/AnotherGroup/this/that/other.html"@                   is being mapped the URL would be redirected to4                   "http://host/this/that/other.html"  A                      redirect /AnotherGroup/* http://host/group/*c          N                                                             Mapping Rules  8-7 j               #             8.5 Conditional Mapping   H                The purpose of conditional mapping is to apply rules onlyK                after certain criteria other than the initial path match aretM                met. These criteria serve to create conditional mapping rules,e2                and were introduced in version 4.4.  G                THIS OFFERS A POWERFUL TOOL TO THE SERVER ADMINISTRATOR!n  L                Conditional mapping can be applied on the following criteria:  +                o  authenticated remote userl  )                o  client internet addresst  ,                o  browser-accepted languages  1                o  browser-accepted character setsl  0                o  browser-accepted content-types  /                o  browser identification string   ;                o  host and port specified in request header.  /                o  HTTP method (GET, POST, etc.)a  <                o  proxy/gateway host(s) request forwarded by  E                o  request scheme (protocol . . . "http:" or "https:")                   o  server name                   o  server port   I                Note that path authorization is always applied to the pathaH                supplied with the request, not to the results of any ruleL                mapping that may have occured! This means authorization pathsM                may be administered without any ambiguity being implied by anyn+                rule mapping that may occur.   I                Conditionals must follow the rule and are delimited by "["eL                and "]". Multiple, space-separated conditions may be includedI                within one "[...]". This behaves as a logical OR (i.e. themM                condition only needs one matched to be true). Multiple "[...]"oH                conditionals may be included against a rule. These act asG                a logical AND (i.e. all must have at least one conditionlF                matched). If a condition begins with a "!" it acts as aH                negation operator (i.e. matched strings result in a falseL                condition, unmatched strings in a true condition). The resultL                of an entire conditional may also be negated by prefixing the                "[" with a "!".  L                If a conditional, or set of conditionals, is not met the rule%                is completely ignored.                8-8  Mapping Rules t               C                Matching is done by simple, case-insensitive, stringEH                comparison, using the wildcards "*", matching one or moreB                characters, and "%", matching any single character.  J                White-space (spaces and TABs), wildcards and the delimitingG                "[" and "]", are forbidden characters and cannot be usedsM                within condition matching strings, nor can they be encoded foraM                inclusion in any way (for simplicity and speed of processing). M                These characters are uncommon in the information being matchedgL                against, but if one does occur then "match" it using a single(                character wildcard ("%").  M                While conditionals are powerful adjuncts to smart serving they M                do add significant overhead to rule mapping and should be used !                with this in mind.[                  Conditionals   I                o  ac: - browser-accepted content types ("Accept:" request                    header field)y  F                o  al: - browser-accepted languages ("Accept-Language:"'                   request header field)r  J                o  as: - browser-accepted character sets ("Accept-Charset:"'                   request header field)h  I                o  fo: - request forwarded by proxy/gateway host(s) ("For-l0                   warded:" request header field)  J                o  hh: - host and port request directed to ("Host:" request                   header field)   =                o  ho: - browser host internet name or address   +                o  me: - request HTTP methodu  K                o  sc: - request scheme (protocol), "http", and if SSL is ina.                   use "https" (see Chapter 10)  #                o  sn: - server nameo  #                o  sp: - server portt  6                o  ru: - authenticated remote user name  D                o  ua: - browser ("User-Agent:" request header field)      N                                                             Mapping Rules  8-9 m  e                            Examplesr  H                NOTE: It is possible to spoof (impersonate) internet hostC                addresses. Therefore any controls applied using hosttH                name/address information cannot be used for authorization;                purposes in the strictest sense of the term.   J                1. The following example shows a rule being applied only ifH                   the client host is within a particular subnet. This isM                   being used to provide a "private" home page to those in the M                   subnet while others get a "public" page by the second rule.   =                      pass / /web/internal/ [ho:131.185.250.*] !                      pass / /web/   E                2. This is a similar example to the above, but showingtI                   multiple host specifications and specifically excludingoK                   one particular host using the negation operator "!". This K                   could be read as pass if ((host OR host) AND (not host)).   ]                      pass / /web/internal/ [ho:*.fred.com ho:*.george.com] [!ho:you.fred.com]b!                      pass / /web/R  E                3. The next example shows how to prevent browsing of a G                   particular tree except from specified host addresses.   U                      pass /web/internal/* /web/SorryNoAccess.html [!ho:131.185.250.*] )                      pass /web/internal/*i  F                   This could be used to prevent browsing of the serverE                   configuration files (an alternative to this sort of L                   approach is to use the authorization file, see Chapter 9).  X                      pass /ht_root/local/* /web/SorryNoAccess.html [!ho:131.185.250.201]  J                4. This example performs much the same task as the previousE                   one, but uses whole conditional negation to preventsE                   browsing of a particular tree except from specified H                   addresses (as well as using the continuation characterM                   to provide a more easily comprehended layout . . . note theaM                   trailing spaces as required). This could be read as pass ife-                   not (host OR host OR host).n  C                      pass /web/internal/* /web/SorryNoAccess.html \s                      ![\'                      ho:131.185.250.* \C'                      ho:131.185.251.* \ &                      ho:131.185.45.1 \-                      ho:ws2.wasd.dsto.gov.au\l                      ])                      pass /web/internal/*a               8-10  Mapping Rules  i  a            F                5. This example demonstrates mapping pages according toI                   geography or language preference (it's a bit contrived,                    but . . . )i  B                      pass /doc/* /web/doc/french/* [ho:*.fr al:fr]C                      pass /doc/* /web/doc/swedish/* [ho:*.se al:se] 3                      pass /doc/* /web/doc/english/*e  K                6. How to exclude specific browsers from your site (how manye+                   times have we seen this!)   N                      # I had to pick on a well-known acronym, no offence Bill!=                      pass /* /web/NoThankYou.html [ua:*MSIE*]t  E                7. This example allows excluding certain requests from L                   specific addresses. This could be read as pass if ((method+                   is POST) AND (not host)).s  J                      pass /* /web/NotAllowed.html [me:POST] [!ho:*.my.net]  H                8. The following illustrates using the server name and/orG                   server port to conditionally map servers executing onrG                   clustered nodes using the same configuration file, orpI                   for multi-homed/multi-ported hosts. Distinct home pagescI                   are maintained for each system, and on BETA two serverscJ                   execute, one on port 8000 that may only be used by those=                   within the specified network address range.o  C                      pass / /web/welcome_to_Alpha.html [sn:alpha.*] I                      pass / /web/welcome_to_Beta.html [sn:beta.*] [sp:80] [                      pass /* /sorry_no_access.html [sn:beta.*] [sp:8000] [!ho:*.my.sub.net] S                      pass / /web/welcome_to_Beta_private.html [sn:beta.*] [sp:8000]   G                9. Each of these three do basically the same thing, just F                   using the three possible delimiters according to theJ                   characters required in the message. The server generatesM                   a 403 response with has as it's text the following message.o  P                      pass /private/* "403 Can't go in there!" [!ho:my.host.name]X                      pass /private/* '403 "/private/" is off-limits!' [!ho:my.host.name]W                      pass /private/* {403 Can't go into "/private/"} [!ho:my.host.name]a  G                Note that rule processing for any particular path may be <                checked using the server administration menu.  @             8.6 Mapping User Directories (tilde character ("~"))  C                This server will map user directories using the same C                mechanisms as for any other. No reference is made to I                SYSUAF.DAT, user support is accomplished via a combination J                of mapping rule and logical name. This approach relies on aI                correspondance between the username and the home directoryeF                name. Hence users are made known by the HTTPd using theG                name of their top-level directory. As the naming of homek  N                                                            Mapping Rules  8-11 c  c            G                directories using the username is a common practice thiseM                mechanism should suffice in the majority of cases. Where there K                is no such correspondance individual rules could be used forfI                each user. User scripts can also be supported using WASD'slK                DECnet scripting environment. See Section 12.8.4 for furtheri                detail.  K                The "PASS" rule provides a wildcard representation of users' F                directory paths. As part of this mapping a subdirectoryM                specifically for the hypertext data should always be included.sF                Never map users' top-level directories. For instance ifF                a user's account home directory was located in the areaF                USER$DISK:[DANIEL] the following rule would potentiallyK                allow the user DANIEL to provide web documents from the home I                subdirectory [.WWW] (if the user has created it) using the                  accompanying URL:  /                   pass /~*/* /user$disk/*/www/*i  &                   http://host/~daniel/  H                It is recommended that a separate logical name be createdJ                for locating user directories. This helps hide the internalJ                organisation of the file system. The following logical nameA                definition and mapping rule illustrate this point.a  W                   $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED WWW_USER device:[USER.]   .                   pass /~*/* /www_user/*/www/*  G                Where users are grouped into different areas of the filed;                system a logical search list may be defined.a  A                   $ DEFINE /SYSTEM /EXEC /TRANSLATION=CONCEALED -.%                            WWW_USER -e-                            DISK1:[GROUP1.], -e-                            DISK1:[GROUP2.], - -                            DISK2:[GROUP3.], -c*                            DISK2:[GROUP4.]  .                   pass /~*/* /www_user/*/www/*  J                As logical search lists have specific uses and some compli-J                cations (e.g. when creating files) this is the only use forM                them recommended with this server, although it is specifically J                coded to allow for search lists in document specifications.  H                If only a subset of all users are to be provided with WWWH                publishing access either their account directories can beL                individually mapped (best used only with a small number) or aL                separate area of the file system be provided for this purpose5                and specifically mapped as user space.p               8-12  Mapping Rules                  D                Of course, user mapping is amenable to all other ruleK                processing so it is a simple matter to redirect or otherwise L                process user paths. For instance, the published username doesJ                not need to, or need to continue to, correspond to any realA                user area, or the user's actual name or home area:r  @                   redirect /~doej/* http://a.nother.host/~doej/*;                   pass /~doej/* /www/messages/deceased.htmlt>                   pass /~danielm/* /special$www$area/danielm/*?                   pass /~Mark.Daniel/* /user$disk/danielm/www/*t.                   pass /~*/* /www_user/*/www/*  L                A user directory is always presented as a top-level directoryM                (i.e. no parent directory is shown), although any subdirectory .                tree is accesssable by default.                                                                      N                                                            Mapping Rules  8-13                     M             Chapter__9_______________________________________________________   ,             Authentication and Authorization    G                Authentication is the verification of a user's identity,aM                usually through a username/password combination. Authorization I                is allowing a certain action to be applied to a particular >                path based on authentication of the originator.  D                Generally, authorization is a two step process. FirstI                authentication, using a username/password database. SecondeL                authorization, determining what the username is allowed to do$                for this transaction.  H                Authentication environments can get complex very quickly,K                don't forget to "keep it simple, stupid", see Section 9.3.1.                   Overviewp  F                Server authorization is performed using a configurationG                file, authentication database and optional authorizationfF                grouping database, and is based on per-path directives.F                There is no user-configured authorization necessary, orG                possible! In the configuration file paths are associatedbF                with the authentication and authorization environments,J                and so become subject to the HTTPd authorization mechanism.H                Reiterating . . . WASD HTTPd authorization administrationH                involves those two aspects, setting authorization againstK                paths and administering the authentication and authorizationt                databases.p  L                AUTHORIZATION IS ALWAYS APPLIED TO THE PATH SUPPLIED WITH THEL                REQUEST, not to the results of any rule mapping that may haveJ                occured! This means authorization paths may be administeredD                without ambiguity. With requests containing a script,M                authorization is performed on both script and path components. M                First script access is checked for any authorization, then the L                path component is independently authorized. Either may result5                in an authorization challenge/failure.   I                For the WASD HTTPd user authentication can be done via the M                server system's SYSUAF database (not recommended except except M                when employing SSL or in the most secure of LAN environments), 7                see Section 9.6 for further information.T  H                The authentication database name can be refered to as theJ                realm, and refers to a collection of username/passwords. It3                can be the system's SYSUAF database.   N                                          Authentication and Authorization  9-1                 I                The authorization database can be refered to as the group,sE                and refers to a collection of usernames and associatedo                permissions.r  F                Separate databases are not always necessary, permissionM                information can be stored in the same database as the passwordeI                information. Paths are generally authorized on a per-groupvJ                basis. Path access can be also be restricted on an internetF                host name/domain, internet address and/or authenticatedI                username basis. If only a small number of usernames are to H                be associated with a path it is possible to list them allJ                against the path and have permissions derived directly from3                the authentication database (realm).l  $                Authentication Policy  G                A policy regarding when authorization can be used may bebK                established for the server. This can restrict authenticationiF                challenges to "https:" (SSL) requests (see Chapter 10),I                thereby ensuring that the authorization environment is noteJ                compromised by use in non-encrypted transactions. Two HTTPd'                qualifiers provide this.   ?                o  /AUTHORIZATION=SSL  restricts all authentica- I                   tion/authorization transactions to the SSL environment.   K                o  /SYSUAF=SSL  restricts only SYSUAF authenticated transac- /                   tions to the SSL environment.   C                Note also that individual paths may be restricted toeE                SSL requests using either the mapping conditional rulenJ                configuration or the authorization configuration files. See8                Conditionals and Access Restriction List.  M                In addition two configuration parameters have a direct role in 3                an established authorization policy.e  L                o  [AuthFailureLimit]  sets the maximum unsuccessful attemptsJ                   allowed before a username is then always refused authen-I                   tication. After this limit is reached the cache must beoJ                   purged to re-allow the user access, see Section 5.3.2.2.  I                o  [AuthRevalidateUserMinutes]  sets the number of minutes L                   between successive authentication attempts before the userM                   is forced to reenter the authentication data (via a browseri7                   dialog). Zero disables this function.         1             9-2  Authentication and Authorizations l  e            &                Authentication Failures  I                Details of authentication failures are logged to the HTTPdp                process log.   H                o  %HTTPD-W-AUTHFAIL  indicates a failure to authenticateH                   (incorrect username/password). The number of failures,H                   the realm name, the user name and the originating hostF                   are provided. Isolated instances of this are only ofI                   moderate interest. Consecutive instances may indicate aqI                   user thrashing about for the correct password, but theyd:                   usually give up before a dozen attempts.  F                o  %HTTPD-I-AUTHFAILOK  advises that a previous failureG                   to authenticate has now successfully done so. This ise,                   essentially informational.  L                o  %HTTPD-W-AUTHFAILIM  indicates the number of failures haveH                   exceeded the [AuthFailureLimit], after which automaticK                   refusal begins. This message should be of concern and therI                   circumstances investigated, especially if the number of -                   attempts becomes excessive.   #                Authorization Scheme   I                The term authorization scheme refers to the HTTP method of H                authenticating the user. The WASD HTTPd can employ one orG                other, or both of the "Basic" and "Digest" schemes. BothpK                schemes use a username/password mechanism, with Digest beingnL                preferable because the password is transmitted encrypted, andG                with Basic only encoded (and therefore easily readable).   1                                              Note   E                      The Digest scheme has, to date, only been tested H                      against NCSA X Mosaic 2.7-4b, which seems to behaveG                      a little flakey when reloading documents, and does 8                      not elegantly support stale nonces.  *             9.1 Permissions, Path and User  H                Both paths and usernames have permissions associated withM                them. A path may be specified as read-only, read and write, or L                write-only (yes, I'm sure someone will want this!) A usernameH                may be specified as read capable, read and write capable,H                or only write capable. For each transaction these two areI                combined to determine the maximum level of access allowed. M                The allowed action is the logical AND of the path and username                 permissions./  N                                          Authentication and Authorization  9-3                 L                The permissions may be described using the HTTP method names,E                or using the more concise abbreviations R, W, and R+W.p  M                ______________________________________________________________ M                Path/User___DELETE_GET____HEAD___POST___PUT___________________   9                READ or R   no     yes    yes    no     no   :                WRITE or W  yes    no     no     yes    yes  :                R+W         yes    yes    yes    yes    yes  9                DELETE      yes    yes    no     no     nom  9                GET         no     yes    no     no     nos  9                HEAD        no     no     yes    no     no   9                POST        no     no     no     yes    nop  M                PUT_________no_____yes____no_____no_____yes___________________   0             9.2 Authorization Configuration File  G                Requiring a particular path to be authorized in the HTTP D                transaction is accomplished by applying authorizationF                requirements against that path in a configuration file.K                This is an activity distinct from setting up and maintainingcJ                any authentication/authorization databases required for the                environment.   M                By default, the system-table logical name HTTPD$AUTH locates a]L                common authorization configuration file, unless an individualL                rule file is specified using a job-table logical name. SimpleK                editing of the file changes the configuration. Comment lineseM                may be included by prefixing them with the hash "#" character,mL                and lines continued by placing the backslash character "\" as,                the last character on a line.  H                Configuration directives begin either with a "[realm]" orL                "[realm;group]" specification, or with the forward-slash of aL                path specification. Following the path specification are HTTPI                method keywords controlling group and world permissions to/M                the path, and any access-restricting request scheme ("https:") :                and/or host address(es) and/or username(s).  @                o  REALM -  Square brackets are used to enclose aJ                   [realm;group] specification, introducing a new authenti-I                   cation grouping. Within these brackets is specified thelL                   realm (and database) name, and then an optional group (andJ                   database) name separated by a semi-colon. All path spec-I                   ifications following this are authenticated against the I                   specified realm database, and permissions obtained from[  1             9-4  Authentication and Authorizationw o  t            M                   the group database (or authentication database if group notcI                   specified), until the next [realm;group] specification.m  E                   The following shows the format of an authenticationa2                   database only (realm) directive.  .                      [authentication-database]  J                   This the format of a directive using both authenticationE                   and authorization databases (both realm and group).l  G                      [authentication-database ; authorization-database]   H                o  PATH -  Paths are usually specified terminated with anI                   asterisk wildcard. This implies that any directory treesI                   below this is included in the access control. WildcardsdL                   may be used to match any portion of the specified path, orJ                   not at all. Following the path specification are controlG                   keywords representing the HTTP methods or permissionsbL                   that can be applied against the path, and optional access-J                   restricting list of host address(es) and/or username(s),J                   separated using commas. Access control is against eitherF                   or both the group and the world. The group access isJ                   specified first followed by a semi-colon separated worldJ                   specification. The following show the format of the pathJ                   directive, see the examples below to further clarify the                   format.h  I                      /root/path/  group-access-list,group-permissions ; \ E                                   world-access-list,world-permissionsg  F                The same path cannot be specified against two differentI                realms. The reason lies in the HTTP authentication schema,iK                which allows for only one realm in an authentication dialog.pD                How would the server decide which realm to use in theH                authentication challenge? Of course, different parts of aM                given tree may have different authorizations, however any treeeI                ending in an asterisk results in the entire sub-tree beingoL                controlled by the specified authorization environment, unlessK                a separate specification exists for some inferior portion ofe                the tree.                  Reserved Realms  L                The following realm names (authentication database names) are7                reserved and have special functionality.   G                1. EXTERNAL -  Any authentication and authorization willoH                   be done in some way by an external CGI script. None is*                   attempted by the server.  N                                          Authentication and Authorization  9-5 E  E            J                2. WORLD -  This refers to any request and is not authenti-H                   cated in any way, only the permissions associated withL                   the path are applied to the request. The reserved username=                   "WORLD" becomes the authenticated username.T  M                3. VMS -  Use the VMS system's SYSUAF database to authenticate J                   the username. For "http:" requests the username/passwordJ                   pairs are transmitted encoded but not encrypted, this isL                   not recommended. For "https:" requests, using the implicitL                   security offered by SSL (see Chapter 10) the use of SYSUAF6                   authentication is considered viable.  G                   By default accounts with SYSPRV authorized are alwaysiK                   rejected to discourage the use of potentially significantiG                   usernames (e.g. SYSTEM). Accounts that are disusered,iI                   have passwords that have expired or that are captive ora=                   restricted are also automatically rejected.   :                   See Section 9.6 for further information.                   Reserved Username  2                The following username is reserved.  L                1. WORLD -  If a path is authorized using the WORLD realm theM                   pseudo-authenticated username becomes "WORLD". Any log will M                   reflect this username and scripts will access a WWW_REMOTE_.K                   USER containing this value. Although not forbidden, it iseL                   not recommended this string be used as a username in other                   realms.a  &                Access Restriction List  J                If a host name, protocol identifier or username is includedK                in the path configuration directive it acts to further limit H                access to matching clients (path and username permissionsI                still apply). If more than one are included a request mustsF                match each. If multiple host names and/or usernames areL                included the client must match at least one of each. Host andL                username strings may contains the asterisk wildcard, matchingK                one or more consecutive characters. This is most useful wheniJ                restricting access to all hosts within a given domain, etc.  M                o  Host Names -  may be specified as either alphabetic (if DNSoK                   name resolution is enabled, see [DNSlookup] configurationdJ                   directive) or numeric addresses. When a host restrictionF                   occurs there is never an attempt to authenticate anyL                   associated username. Hence applying host restrictions veryI                   effectively prevents an attack from outside the allowed L                   addresses. The reserved word #localhost refers to the host2                   name the server is executing on.  1             9-6  Authentication and Authorizationa o               L                o  Request Scheme -  (protocol) either "http:" or secured via                    "https:" (SSL)  J                o  User Names -  are indicated by a leading circumflex, theA                   "~" character (similar or username URL syntax).                   For example  G                   /web/secret/* *.three.stooges,~Moe,~Larry,~Curly,readd  K                restricts read access to Curly, Larry and Moe accessing fromi6                within the three.stooges network, while  N                   /web/secret/* https:,*.three.stooges,~Moe,~Larry,~Curly,read  K                applies the further restriction of access via "https:" (SSL)h                only.  E                Note that it more efficient to place protocol and host 3                restrictions at the front of a list.t  4             9.3 Authorization Configuration Examples  M                1. In the following example the authentication realm is "WASD" G                   and the permissions group "SOCIALCLUB". The directive K                   allows those authenticated from the WASD realm and in the L                   SOCIALCLUB group to read and write, and the world to read.  &                      [WASD;SOCIALCLUB]1                      /web/socialclub/* r+w ; read   G                2. This example illustrates restricting access according H                   internet address. Both the group and world restrictionH                   is identical, but the group address is being specifiedH                   numerically, while the world access is being specifiedI                   alphabetically (just for the purposes of illustration).SM                   This access check is done doing simple wildcard comparison, E                   and makes numerical specifications potentially morenH                   efficient because they are usually shorter. The secondJ                   line restricts that path's write access even further, to)                   one username, "BLOGGS".   &                      [WASD;SOCIALCLUB]W                      /web/socialclub/* 131.185.45.*,get,post; *.dsto.defence.gov.au,get h                      /web/socialclub/accounts/* 131.185.45.*,~BLOGGS,get,post; *.dsto.defence.gov.au,get  M                3. In the following example the authentication realm and groupsL                   are a single database, "ADMIN". The first directive allowsK                   those in the ADMIN group to read and write, and the worldeK                   to read ("get,post;get"). The second line restricts write M                   and even read access to ADMIN group, no world access at all                    ("get,post").r  N                                          Authentication and Authorization  9-7 e  f                                  [ADMIN]1                      /web/everyone/* get,post;get /                      /web/select/few/* get,posto  K                4. With this example usernames are used to control access to M                   the specified paths. These usernames are authenticated fromnI                   the COMPANY database. The world has read access in bothe                   cases.                        [COMPANY]>                      /web/docs/* ~Howard,~George,~Fred,r+w ; r4                      /web/accounts/* ~George,r+w ; r  I                5. The following example shows a path specifying the localHK                   system's SYSUAF being used to authenticate any usernames.AL                   Whenever using SYSUAF authentication it is strongly recom-K                   mended to limit the potential hosts that can authenticatesM                   in this way by always using a host-limiting access restric-n7                   tion list. The world get read access.m                        [VMS]<                      /web/local/area/* 131.185.250.*,r+w ; r  I                6. To restrict server administration to browsers executing J                   on the server system itself and the SYSUAF-authenticatedG                   username DANIEL use a restriction list similar to the                    following.                        [VMS]=                      /httpd/-/admin/*  #localhost,~daniel,r+w   H                7. The following example illustrates providing a read andM                   writable area (GET, POST and PUTable) to hosts in the local E                   network without username authentication (careful!).                         [WORLD];                      /web/scratch/*  *.local.hosts.only,r+w                9.3.1 KISS  F                WASD authorization allows for very simple authorizationD                environments and provides the scope for quite complexH                ones. The path authentication scheme allows for multiple,G                individually-maintained authentication and authorizationsD                databases that can then be administered by autonomousH                managers, applying to widely diverse paths, all under theA                ultimate control of the overall Web administrator.e  G                Fortunately great complexity is not generally necessary.   I                Most sites would be expected to require only an elementary I                setup allowing a few selected Web information managers the.L                ability to write to selected paths. This can best be providedM                with the one authentication database containing read and writea  1             9-8  Authentication and AuthorizationI    v            I                permissions against each user, with and access-restrictionn-                list against individual paths.n  G                For example. Consider a site with five departments, each E                of which wishes to have two representatives capable oftK                administering the departmental Web information. There is oneo=                authentication database, named after the site:d                     HYPOTHETICAL  K                In that database are twelve names, the first two the overallhJ                Web administrators, capable of administering all authorizedL                paths, another two from each department makes up another ten:                      WEB1       r+w                    WEB2       r+w                    JOHN       r+w                    PAUL       r+w                    GEORGE     r+w                    RINGO      r+w                    CURLY      r+w                    LARRY      r+w                    MOE        r+w                    SHEMP      r+w                    MAC        r+w                    MYER       r+w  B                The authorization configuration file then contains:                      [HYPOTHETICAL]H                   # allow web masters (!) to use the administration menuK                   #                       to revise web configuration filesi7                   # world has no access (read or write)aY                   # access is only allowed from a browser on the same system as the HTTPdo<                   /httpd/-/admin/*  #localhost,web1,web2,r+w<                   /ht_root/local/*  #localhost,web1,web2,r+wY                   # allows BOGUS_R_AND_D department representatives to maintain their web H                   # this may only be done from within the company subnet)                   # world has read access U                   /web/dept/bogus_R_and_D/*   150.15.30.*,John,Paul,web1,web2,r+w ; r =                   # and so on for the rest of the departmentseX                   /web/dept/real_R_and_D/*    150.15.30.*,George,Ringo,web1,web2,r+w ; rK                   # (the next uses line continuation just for illustration)n;                   /web/dept/marketing/*       150.15.30.*,\_J                                               Curly,Larry,web1,web2,r+w ;\2                                               readU                   /web/dept/production/*      150.15.30.*,Moe,Shemp,web1,web2,r+w ; rWT                   /web/dept/inventory/*       150.15.30.*,Mac,Myer,web1,web2,r+w ; r                   [WORLD] Q                   # we need a spot for general POSTing (world has no read access)n>                   # (just for the purposes of illustration :^)#                   /web/world/*  r+w   N                                          Authentication and Authorization  9-9 _  _            3             9.4 Databases, Authentication and Groupu  J                At this point it should be stressed that the HTTPd-specificH                (HTA) authentication and group databases are identical inF                internal structure and administration, it is merely theI                role they assume that differentiates them. The role of thesF                database is purely a function of where they are used inJ                the configuration file realm directive, the first mentionedJ                becomes the authentication database, any subsequent, secondJ                database assumes the role of group database (otherwise thatD                role is also assumed by the authentication database).  &                Authentication Database  F                An authentication, or realm database contains usernamesJ                and associated passwords. Passwords are verified using thisG                database. Passwords are always stored in encrypted form.r  H                When using an HTTPd-specific database it can also be usedF                to contain per-user permissions, that control access toC                configured paths. In this role it acts as both realmtC                (authentication) and group (authorization) database.l  I                It is also possible for the system's SYSUAF database to be-I                used for authentication purposes. Of course HTTPd-specificeJ                permissions cannot be stored in this database, but if usingK                SYSUAF-authenticated usernames a VMS security profile can benG                used to control access to served files, see Section 9.6.   K                Warning ... when using Digest authentication, an authentica-aK                tion database cannot simply be renamed to represent a group- L                name change, as the database name is encrypted as part of the                MD5 Digest!  %                Authorization Database   L                An authorization, or group database, contains a collection ofK                usernames and their associated permissions within the group. H                That is, can that user read and/or write paths configuredE                against that group. A group database is never used fora6                password verification (authentication).  K                An authorization database is not always necessary. If only a J                small number of users need to be authorized against a givenJ                path they can be specified individually using a "~username"4                format (see Access Restriction List).        2             9-10  Authentication and Authorization n  d            &                Database Administration  H                The same server administration menu is used to administerJ                authentication/authorization databases, see Section 9.5 and                Section 11.3.  G                There is a thirty-one character limit on database names,nH                and a fifteen character limit on usernames and passwords.F                All database and user names are case-insensitive. BASICL                authentication scheme passwords are case insensitive, howeverJ                DIGEST authentication scheme passwords should all be either=                upper or lower case, mixed case will not work.e  3             9.5 Server Authorization Administrationl  F                The same server administration menu is used to maintainG                both the authentication and authorization databases, seet                Section 11.3.  L                The server authorization databases can be initially set-up by:                breaking-in to the server, see Section 11.1  J                A server's currently loaded path authorization and user au-L                thentication information may be administered and interrogatedJ                on-line using the server administration facility. See Chap-)                ter 11 for further detail.p  *             9.6 SYSUAF-Authenticated Users  G                The ability to authenticate using the system's SYSUAF iseH                controlled by the server /SYSUAF qualifier. By default it                is disabled.   )                Authentication Identifiersi  I                When SYSUAF authentication is enabled, by default all non-oI                privileged, active accounts are capable of authentication.sE                Restriction of this to those actually requiring such a L                capability is provided using VMS rights identifiers. When theJ                /SYSUAF=ID qualifier is employed a VMS account must possessI                one of two specific identifiers before it is allowed to belK                used for server authentication. Note that this mechanism can M                also allow privileged accounts to be so used . . . deploy with                 discretion!                  1. WASD_VMS_R  ?                   This identifier provides at most read access.n                  2. WASD_VMS_RWa  N                                         Authentication and Authorization  9-11 a  i            F                   This identifier provides read and write access (path5                   protections still apply of course).e  M                Other identifiers provide further control for the way in whicho5                the authenticated account may be used.                    1. WASD_VMS_HTTPS  L                   Use of the authenticated account is restricted to "https:"!                   (SSL) requests.                   2. WASD_VMS_PWD  M                   The account is allowed to change it's SYSUAF password (!!).aK                   It is recommended this facility only be employed with SSLy                   in place.d  I                   Password modification is enabled by including a mappinge5                   rule to the internal change script.   :                      map /http/-/change/* /http/-/change/*  M                   The authorization configuration file must provide authenti-                    cated access.e                        [VMS]5                      /httpd/-/change/vms/* https:,r+we  '                   Also see Section 9.8.L  (                3. WASD_VMS__<group-name>  L                   This form allows a suitably named identifier to be createdL                   for use in providing group-membership via the SYSUAF. NoteM                   the double-underscore separating the fixed from the locallydK                   specified portion. Using these identifiers it is possiblemL                   to limit paths to SYSUAF-authenticated accounts possessingK                   the requisite identifier in manner similar to non-SYSUAF-dH                   authentication groups. An account possessing the WASD_M                   VMS__TESTING identifier is allowed write access to the paths+                   in the following example:n  "                      [VMS;TESTING]3                      /web/project/testing/* r+w ; re  H                All four rights identifiers must exist for the /SYSUAF=IDJ                facility to be used (even though none may be granted to anyK                account). The identifiers may be created using the AUTHORIZEs/                utility with following commands:   *                   $ SET DEFAULT SYS$SYSTEM!                   $ MCR AUTHORIZEe1                   UAF> ADD /IDENTIFIER WASD_VMS_R 2                   UAF> ADD /IDENTIFIER WASD_VMS_RW5                   UAF> ADD /IDENTIFIER WASD_VMS_HTTPS 3                   UAF> ADD /IDENTIFIER WASD_VMS_PWD   2             9-12  Authentication and Authorization                 K                They can then be provided to desired accounts using commandsf(                similar to the following:  >                   UAF> GRANT /IDENTIFIER WASD_VMS_RW <account>  !                and removed using:   ?                   UAF> REVOKE /IDENTIFIER WASD_VMS_RW <account>c  I                Note that it is possible to create nil-access VMS accountseM                that may be used solely for WASD server authentication. Create M                a standard VMS account in a group dedicated for this function, K                specifying /NOINTERACTIVE /NONETWORK /NOBATCH /FLAG=DISMAIL.   M                Be aware that, as with all successful authentications, and dueCK                to the WASD internal authentication cache, changing databasecM                contents does not immediately affect access. Any change in the M                RIGHTSLIST won't be reflected until the cache entry expires or ;                it is explicitly flushed (see Section 11.4).:                  SYSUAF and SSL   H                When SSL is in use (see Chapter 10) the username/passwordG                authentication information is inherently secured via therK                encrypted communications of SSL. To enforce access to be viatI                SSL add the following to the HTTPD$MAP configuration file:r  N                   /whatever/path/you/like/*  "403 Access denied."  ![sc:https]  M                or alternatively the following to the HTTPD$AUTH configuratione                file:                     [REALM]A3                   /whatever/path/you/like/*  https:*  L                Note that this mechanism is applied after any path and methodE                assessment made by the server's authentication schema.r  F                The qualifier /SYSUAF=SSL provides a powerful mechanismG                for protecting SYSUAF authentication, restricting SYSUAFgE                authenticated transactions to the SSL environment. TheiF                combination /SYSUAF=(SSL,ID) is particularly effective.  .                Also see Authentication Policy.                  Security Profilel  H                It is possible to control access to files and directoriesJ                based on the VMS security profile of a SYSUAF-authenticatedG                remote user. This functionality is implemented using VMS G                security system services involving SYSUAF and RIGHTSLISTeH                information. The feature must be explicitly allowed usingH                the server /PROFILE qualifier. By default it is disabled.  N                                         Authentication and Authorization  9-13                 G                When a SYSUAF-authenticated user (i.e. the VMS realm) issH                first authenticated a VMS security-profile is created andI                stored in the authentication cache. A cached profile is an L                efficient method of implementing this as it obviously removesJ                the need of creating a user profile each time a resource isK                assessed. If this profile exists in the cache it is attached K                to each request authenticated for that user. As it is cachedeK                for a period, any change to a user's security profile in thedL                SYSUAF or RIGHTSLIST won't be reflected in the cached profileM                until the cache entry expires or it is explicitly flushed (see                 Section 11.4).   G                When a request has this security profile all accesses to/L                files and directories are assessed against it. When a file orM                directory access is requested the security-profile is employed H                by a VMS security system service to assess the access. IfL                allowed, it is provided via the SYSTEM file protection field.K                Hence it is possible to be eligible for access via the OWNERnL                field but not actually be able to access it because of SYSTEMK                field protections! If not allowed, a "no privilege" error is                 generated.   I                Of course, this functionality only provides access for the E                server, IT DOES NOT PROPAGATE TO ANY SCRIPT ACCESS. If H                scripts must have a similar ability they should implementF                their own scheme (which is not too difficult, ) see HT_J                ROOT:[SRC.MISC]CHKACC.C based on the CGI variable WWW_AUTH_K                REALM which would be "VMS" indicating SYSUAF-authentication,x=                and the authenticated name in WWW_REMOTE_USER.b  !                Performance Impacts  I                If the /PROFILE qualifier has enabled SYSUAF-authenticatedcJ                security profiles, whenever a file or directory is assessedF                for access an explicit VMS security system service callI                is made. This call builds a security profile of the objectvH                being assessed, compares the cached user security profileG                and returns an indication whether access is permitted ordJ                forbidden. This is addition to any such assessments made by1                the file system as it is accessed.   I                This extra security assessment is not done for non-SYSUAF- =                authenticated accesses within the same server.   L                For file access this extra overhead is negligible but becomesJ                more significant with directory listings ("Index of") whereG                each file in the directory is independently assessed for                 access.    2             9-14  Authentication and Authorization    w            /             9.7 Controlling Server Write Accessa  I                Write access by the server into VMS directories (using the K                POST or PUT HTTP methods) is controlled using VMS ACLs. This L                is in addition to the path authorization of the server itselfI                of course! The requirement to have an ACE on the directory M                prevents inadvertant mapping/authorization of a path resultingn>                in the ability to write somewhere not intended.  A                Two different ACEs implement two grades of access.   M                1. If the ACE grants CONTROL access to the server account then I                   only VMS-authenticated usernames with security profiles K                   can potentially write to the directory. Only potentially, L                   because a further check is made to assess whether that VMS9                   account in particular has write access.   L                   This example shows a suitable ACE that applies only to the%                   original directory:A  3                      $ SET SECURITY directory.DIR - X                        /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL)  J                   This example shows setting an ACE that will propagate to@                   created files and importantly, subdirectories:  3                      $ SET SECURITY directory.DIR - l                        /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL), -Z                              (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE+CONTROL))  G                2. If the ACE grants WRITE access then the directory can G                   be written into by any authenticated username for the "                   authorized path.  L                   This example shows a suitable ACE that applies only to the%                   original directory:   3                      $ SET SECURITY directory.DIR - P                        /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE)  J                   This example shows setting an ACE that will propagate to@                   created files and importantly, subdirectories:  3                      $ SET SECURITY directory.DIR - d                        /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+EXECUTE+DELETE), -R                              (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+EXECUTE+DELETE))  E                To assist with the setting of the required ACEs an ex-.D                ample, general-purpose DCL procedure is provided, HT_)                ROOT:[EXAMPLE]AUTHACE.COM.2  N                                         Authentication and Authorization  9-15 P  i            *             9.8 User Password Modification  K                The server provides for users to be able to change their own J                HTA passwords (and SYSUAF if required). This functionality,F                though desirable from the administrator's viewpoint, isI                not mandatory if the administrator is content to field anypL                password changes, forgotten passwords, etc. Keep in mind thatL                passwords, though not visible during entry, are passed to the3                server using clear-text form fields.m  K                Password modification is enabled by including a mapping rulea:                to the internal change script. For example:  7                   map /http/-/change/* /http/-/change/*e  M                Any database to be enabled for password modification must haveoM                a writable authorization path associated with it. For example:e                     [GROUP] -                   /httpd/-/change/group/* r+w   !                   [ANOTHER_GROUP]d5                   /httpd/-/change/another_group/* r+we  D                Use some form of cautionary wrapper if providing this                functionality:   5                   <H2>Change Your Authentication</H2>e  !                   <BLOCKQUOTE><I> `                   Change the password used to identify yourself to the REALM Web environment for`                   some actions.  Note that this <U>not</U> an operating system password, nor hasU                   it anything to do with it.  Due to the inherent weaknesses of usingb^                   non-encrypted password transmissions on networks <FONT COLOR="#ff0000"><U>DO_                   NOT</U> use a password you have in use anywhere else, especially an operatings`                   system password!</FONT> You need your current password to make the change.  Ifb                   you have forgotten what it is contact <A HREF="/web/webadmin.html">WebAdmin</A>,Q                   preferably via email, for the change to be made on your behalf. #                   </I></BLOCKQUOTE>e                     <UL>G                   <LI><A HREF="/httpd/-/change/REALM/">REALM</A> realm.                    </UL>r              2             9-16  Authentication and Authorization u  n                M             Chapter__10______________________________________________________                 Secure Sockets Layer    F                This section is not a tutorial on SSL. It contains onlyL                information relating to WASD's use of it. Refer to the listedG                references, Section 10.4, for further information on SSLl                technology.  M                Enhancing privacy with SSL, certificate management and varyingy?                browser behaviours is not for the faint-hearted!o  E                The Secure Sockets Layer protocol (SSL) is designed to F                provide privacy between two communicating applications,G                in the case of HTTP between the browser (client) and the F                HTTPd (server). It provides other capabilities, such asH                client authentication, but these are not considered here.G                SSL operates by establishing an authenticated, encryptedrJ                communication path between the two applications, "wrapping"I                the entire application protocol, such as HTTP, in a securenK                link, providing complete privacy for the entire transaction.uL                In this way security-related data such as user identificationM                and password, as well as sensitive transaction information caneA                be effectively protected from unauthorized access.   L                WASD implements SSL using a freely available software library3                known as "SSLeay", see Section 10.3.a  M                SSL functionality is not supplied with the basic WASD package. J                In part this is due to the relative bulk of this component,K                but also considers patent issues and USA export restrictionsnK                on some cryptographic technology that would impact the basictK                package's potential for download out of the USA. For furtherYF                comment on this aspect check the SSLeay FAQ section "IsJ                this legal?". No recommendations are made by this author onH                the use of the SSLeay package in any particular locality,L                except to comment that it is in commercial and non-commercialH                use in many applications across Europe, North America and                Australasia.s  H                The WASD SSL component is available as a separate, easilyM                integrated package, either with complete SSLeay source or just J                SSLeay object libraries, some SSLeay utility object modulesL                for building executables and WASD support files. Obtain these8                from the same source as the main package.    N                                                     Secure Sockets Layer  10-1 w                               SSL Overhead   M                SSL adds a significant overhead to an HTTP transaction for thee!                following reasons.R  G                o  An initial connection establishment, where the clientiJ                   and server exchange cryptographic data and authorize the                   transaction.  K                o  The transaction transfer, where all application data mustfG                   be processed by the CPU into an encrypted stream, andt6                   back . . . very expensive processes.  K                o  The encrypted data contains more bytes than the raw data,d3                   increasing network transfer time.   I                o  Other miscellaneous SSL handshaking for the life of theh                   transaction.  G                For these reasons SSL HTTP is slower and has far greaterSE                impact on the server system CPU than standard HTTP andtH                therefore should only be used when transaction privacy isJ                required, not as a general HTTP service. Also, if a generalL                HTTP and an SSL HTTP service is provided on a multi-processorI                system, with one or other or both experiencing significant G                traffic, then the two services should be run in separate                 processes.   !                SSL Access Controlm  G                When authorization is in place (see Chapter 9) access tocG                username/password controlled data/functionality benefitsYJ                enormously from the privacy of an authorization environmentJ                inherently secured via the encrypted communications of SSL.K                SSL may be used as part of the site's access control policy,cL                as whole-of-site, see Authentication Policy, or on a per-pathC                basis, see Conditionals and Access Restriction List.                   Interoperability   J                WASD SSL has been tested against the following browsers (if?                any others are tested please advise the result).T                &             10-2  Secure Sockets Layer                   M                ______________________________________________________________tM                Browser_______Version_______OK____Comment_____________________T  L                Netscape      v3.0          yes   accepts CA (both ".PEM" andJ                Navigator     (Digital            ".CRT"), initiates serverL                              Unix)               certificate dialog on firstA                                                  "https:" connect   L                Netscape      v3.02         yes   accepts CA (both ".PEM" andJ                Navigator     (WinNT)             ".CRT"), initiates serverL                                                  certificate dialog on firstA                                                  "https:" connect   K                Netscape      v3.03 (VMS)   yes   accepts CA(both ".PEM" andvJ                Navigator                         ".CRT"), initiates serverL                                                  certificate dialog on firstA                                                  "https:" connectc  L                Netscape      v4.03         yes   accepts CA (both ".PEM" andJ                Navigator     (WinNT)             ".CRT"), initiates serverL                                                  certificate dialog on firstA                                                  "https:" connecta  L                Netscape      v4.05         yes   accepts CA (both ".PEM" andJ                Navigator     (Digital            ".CRT"), initiates serverL                              Unix)               certificate dialog on firstA                                                  "https:" connect   J                MS Internet   3.02 (WinNT)  no    accepts CA (".CRT" only),M                Explorer                          but then refuses to transacttJ                                                  SSL requests claiming theK                                                  site is not certified by aw?                                                  well-known CA!   J                MS Internet   4.0 (WinNT)   yes   accepts CA (".CRT" only),M                Explorer                          initiates server certificateaI                                                  dialog on first "https:"d8                                                  connect  M                Cryptozilla   08-APR-1998   yes   This in-development browser,SI                              (WinNT)             implements full-strengtheI                                                  encryption (USA domesticoI                                                  grade), and demonstratespI                                                  WASD SSL's full-strength M                                                  capability. In Cryptozilla'scF                                                  case the DES-CBC3-SHAH                                                  cipher, using a 168-bitM                __________________________________key,_was_negotiated.________v  N                                                     Secure Sockets Layer  10-3 y  l            "             10.1 SSL Configuration  ?                SSL installation creates the major directory HT_ J                ROOT:[SRC.SSLEAY-0_9_0b] containing at the least the SSLeayL                copyright notice, object libraries, object modules for build-L                ing executables, example certificates, and some other supportM                files and documentation. If a complete source package has beene8                obtained the tree is considerably larger.  K                The example HTTPd startup procedure already contains support M                for the SSL executable. If this has been used as the basis for K                startup then only the respective boolean needs to be altered J                to use the SSL rather than the standard executable. The SSLF                executable supports both standard HTTP services (ports)I                and HTTPS services (ports). These must be configured usinghI                the [service] parameter. SSL services are distinguished byaL                specifying "https:" in the parameter. The default port for an"                SSL service is 443.  K                The following example illustrates creating two standard HTTPoJ                services, one on the default port 80, another on port 8000,K                and two SSL services, the first on the default port 443, thel#                second on port 8443.l                     [Service] 0                   alpha.wasd.dsto.defence.gov.au5                   alpha.wasd.dsto.defence.gov.au:8000f8                   https://alpha.wasd.dsto.defence.gov.au=                   https://alpha.wasd.dsto.defence.gov.au:8443s  H                The "/SSL" qualifier controls which version(s) of the SSLG                protocol the server will support; "2", "3" or "23" (i.e.eI                versions 2 and 3, also the default). Using /NOSSL disablesw:                the SSL functionality of an SSL executable.  M                The one further requirement of an SSL server is a certificate.wK                This is located using the HTTPD$SSL_CERT logical name duringe                startup.T                  SSL Quick-Start  J                If the basic WASD v5.n package is installed, configured andI                performing satisfactorily the following steps give a quicky*                outline for support of SSL.  J                1. UNZIP the WASD SSL package. The ZIP archive will containL                   brief installation instructions. Use the following commandB                   to read this and any other information provided.  7                      $ UNZIP -z device:[dir]archive.ZIPr  M                2. Once UNZIPped it will be necessary to link the executables. ?                   This should be performed using the UPDATE.COMa  &             10-4  Secure Sockets Layer                 L                   It assumes a vanilla setup, using the standard directoriesI                   and account environment described in this document. All M                   sections prompt before performing any action and default toeM                   "no". The SSL parameter indicates the SSL components should-                   be processed.i  3                      $ SET DEFAULT HT_ROOT:[000000]v"                      $ @UPDATE SSL  F                3. Once linked the UPDATE.COM procedure will prompt forJ                   permission to execute the demonstration/check procedure.  K                   It is also possible to check the SSL package at any other G                   time using the FREEWARE_DEMO.COM procedure. It should G                   detect the TCP/IP agent in use (if not specify UCX or I                   NETLIB as a parameter). It is necessary to specify thatTG                   it is to use the SSL executable. Follow the displayedf                   instructions.   9                      $ @HT_ROOT:[000000]FREEWARE_DEMO SSLc  3                4. Modify server startup procedures.   9                   o  Using pre-existing, non-v5.n Startup   I                     1. Modify the server startup procedure to INSTALL and K                        the HTTPD80.COM procedure (or equivalent) to use the K                        HTTPD_SSL.EXE executable (or HTTPD_SSL_NETLIB.EXE as #                        appropriate)   D                     2. Modify the server startup procedure to defineD                        a logical HTTPD$SSL_CERT locating the exampleM                        certificate at HT_ROOT:[EXAMPLE]HTTPD.PEM, for example   P                            DEFINE /SYS HTTPD$SSL_CERT HT_ROOT:[EXAMPLE]HTTPD.PEM  '                   o  Using v5.n Startup   G                      Modify the "PROVIDE_SSL" symbol to be 1 (or true).E  J                5. Modify the HTTPD$CONFIG configuration file to specify anG                   SSL service. For example the following creates both a I                   standard HTTP service on the default port 80 and an SSLt1                   service on the default port 443h                        [Service].                      alpha.dsto.defence.gov.au6                      https://alpha.dsto.defence.gov.au  ?                6. Shutdown the server completely, then restart.   J                7. To check the functionality (on default ports) access the                   server via  "                   o  Standard HTTP  +                         http://host.domain/s  N                                                     Secure Sockets Layer  10-5                                    o  SSL HTTPL  ,                         https://host.domain/  M                8. Once the server has been proved functional with the example F                   certificate it is recommended that a server-specificM                   certificate be created using the CA.COM procedure described I                   in Section 10.2. This may then be used by placing it inhJ                   the appropriate local directory, changing the HTTPD$SSL_K                   CERT logical definition in the startup and restarting thea                   server.   '             10.2 Certificate Managemente  G                This section is not a tutorial on certificates and theirnH                management. Refer to the listed references, Section 10.4,6                for further information on this aspect.  I                Certificates associate a public cryptographic key with thehH                identity of the certificate holder, usually an individualK                or server. It includes a distinguishing name, identificationeI                and signature of the certificate authority (CA, the issuertJ                and guarantor of the certificate), and the period for whichH                the certificate is valid, possibly with other, additional                information.a  G                The server uses a certificate to establish it's identity E                during the initial phase of the SSL protocol exchange. G                Each server should have a unique certificate. An example/M                certificate is provided with the WASD SSL package. This is the M                default used by the example startup procedure and will sufficeiI                to demonstrate the server's functionality. If a "live" SSLeL                site is required a unique certificate issued by a third-partyK                Certificate Authority is desirable. A working alternative torI                obtaining one of these certificates is provided by the HT_nJ                ROOT:[SRC.SSLEAY-0_9_0b.WASD]CA.COM procedure, which allowsH                the user to act as a certificate authority (CA) and issueL                identifying certificates. Because the CA is non-authoritativeI                (not a well-known CA) these certificates have little valuecF                except to allow SSL transactions to be established with                 trusting clients.  L                This procedure allows CA as well as server certificates to beM                issued, as well as providing foreign command symbols for other K                certificate management utilities. For usage requirements and I                parameters check the commentary in the procedure preamble.a  I                CA certificates can be loaded into browsers to allow sites_K                using that CA to be accessed by that browser without further L                dialog. Both Netscape Navigator (v3.n & v4.n) and MS InternetI                Explorer (v4.n) automatically invokes a server certificate   &             10-6  Secure Sockets Layer f  a            F                load dialog when it encounters a site using a valid but*                unknown server certificate.  J                A manual load is accomplished by requesting the certificateF                in a format appropriate to the particular browser. ThisK                triggers a browser dialog with the user to confirm or refusehK                the loading of that certificate into the browser Certificatee"                Authority database.  J                To facilitate loading CA certificates into a browser ensureE                the following entries are contained in the HTTP$CONFIGn"                configuration file:                     [AddIcon]tH                   /httpd/-/binary.gif  [BIN]  application/x-x509-ca-cert                     [AddType] L                   .CRT  application/x-x509-ca-cert  -  DER certifcate (MSIE)X                   .PEM  application/x-x509-ca-cert  -  Privacy Enhanced Mail certificate  L                The following would load the WASD testing CA certificate in a"                format suitable for  )                o  Navigator (v3.n, v4.n):u  ?                      /ht_root/src/ssleay-0_9_0b/wasd/cacert.pemS  .                o  MS Internet Explorer (v4.n):  ?                      /ht_root/src/ssleay-0_9_0b/wasd/cacert.crt   H                Navigator should be able to load using either certificateC                format. MSIE v3.n will load and report on the ".CRT" E                certificate quite contentedly, but then will not allowaG                it to be used because it does not represent a well-known K                Certficate Authority. MSIE v4.n seems able to use the ".CRT""                certificate.?  1                Changing Server or CA Certificates   F                If a site's server or CA certificate is changed and theM                server restarted any executing browsers will probably complain K                (Netscape Navigator reports an I/O error). In this case open J                the browser's certificate database and delete any relevant,K                permanently stored certificate entry, then close and restartSF                the browser. The next access should initiate the serverJ                certificate dialog, or the CA certificate may be explicitly                reloaded.    N                                                     Secure Sockets Layer  10-7                              10.3 SSLeays  L                WASD implements SSL using a freely available software libraryL                known as "SSLeay" (pronounced "S-S-L-E-A-Y", i.e. all lettersK                spelt), authored and copyright by Eric Young and Tim Hudson.nL                It is not a GNU-licensed package, but does makes unrestrictedG                commercial and non-commercial use available. The FAQ forh%                SSLeay may be found atc  3                http://www.psy.uq.oz.au/~ftp/Crypto/   F                This should be consulted for all information on the SSL+                technology employed by WASD.r  K                If the SSLeay component of WASD is installed it can be foundg                ati  *                HT_ROOT:[SRC.SSLEAY-0_9_0b]  H                The previous version of SSLeay, 0.8.1, provided with WASDL                v5.0.0, can also be linked and will work with WASD v5.1.0. ItK                is preferable to move to SSLeay v0.9.0b as known bugs in the I                previous version have been fixed in this one (ignoring therM                issue of new bugs being introduced ;^). If v0.8.1 is installed "                it will be found at  )                HT_ROOT:[SRC.SSLEAY-0_8_1]w  G                It has been necessary to make minor modifications to the H                0.9.0b distribution to support VMS (there was rudimentaryC                support that looked like a hang-over from a previousrJ                distribution). These changes are very minor and designed toL                address the differences in VMS and DECC versions. All changesI                to source can be found by searching for "MGD" in [...]*.C,e-                [...]*.H and [...]*.COM files.   F                These changes have been made only to support WASD's useF                of the package, they are not proposed as general SSLeay>                modifications, i.e. they were purely pragmatic!  J                Our thanks to the authors of and contributors to the SSLeayM                package, although if there is a documentation boffin out theree4                please contact eric@CryptSoft.com :^)               10.4 SSL References   G                The following provide a starting-point for investigating_D                SSL and SSLeay further (verified available at time of                publication).  >                o  http://www.netscape.com/newsref/std/SSL.htmlC                   Netscape Communication Corporation's SSL Overview"  6                o  http://www.psy.uq.oz.au/~ftp/Crypto/                   SSLeay FAQ.a  &             10-8  Secure Sockets Layer                 I                o  http://www.camb.opengroup.org/www/prism/wwwj/index.htmlp0                   A good introduction to SSLeay.  E                o  http://www.camb.opengroup.org/~fjh/Papers/cook/ssl_                    cook.htmliF                   An excellent overview of managing certification with                   SSLeay.   E                o  http://www.consensus.com/security/ssl-talk-faq.html .                   SSL-Talk discussion list FAQ                                                                                N                                                     Secure Sockets Layer  10-9 o  c                M             Chapter__11______________________________________________________   !             Server Administration"    H                All server configuration files, with the execption of theK                authentication databases, are plain text and may be modifiedtI                with any prefered editor. However the majority of this canC>                also be administered on-line through a browser.  K                A menu of server administration functions is provided by the                 server.  &                <online hypertext link>  K                In addition a Web Update facility allows some administration B                of file system portions of the Web. See Chapter 15.  K                If authorization is in use (see Chapter 9) it is recommended K                that the path to these reports be controlled via authentica- L                tion and authorization, using both host and username restric-/                tions, similar to the following:e  "                   [WHATEVER-REALM]L                   /httpd/-/admin/*  host.ip.addr,~WebMaster,~WhoEverElse,r+w  F                If a full authorization environment is not required butJ                administration via browser is still desired restrict accessJ                to browsers executing on the server system itself, using anJ                appropriate SYSUAF-authenticated username (start the server,                using the /SYSUAF qualifier):                     [VMS]d<                   /httpd/-/admin/*  #localhost,~username,r+w  L                If SSL is in use (see Chapter 10) then username/password pri-K                vacy is inherently secured via the encrypted communications.tI                To restrict server administration functions to this secure K                environment add the following to the HTTPD$MAP configurationi                file:  E                   /httpd/-/admin/*  "403 Access denied."  ![sc:https]   J                When using the revise capability of the administration menuF                it is necessary to comply with all the requirements forI                Web update of files. This is discussed in general terms inSJ                Chapter 15. Revision of server configuration files requiresI                path permissions allowing write access for the username(s)eK                doing the administration, as well as the required ACL on thesK                target directory (in the following example HT_ROOT:[LOCAL]).t  N                                                    Server Administration  11-1 o  u                               [VMS] <                   /httpd/-/admin/*  #localhost,~username,r+w<                   /ht_root/local/*  #localhost,~username,r+w  K                It is possible to allow general access to the administrationdH                menu and reports while restricting the ability to intiateF                server actions such as a restart! Using the WORLD realmF                against the path is necessary, for the obvious securityM                reason, the server administration module will not allow itself.J                to be used without an authenticated username, provided as a,                pseudo-authenticated "WORLD".                     [VMS] D                   /httpd/-/admin/control/*  #localhost,~username,r+w                   [WORLD]r$                   /httpd/-/admin/* r  +             11.1 Breaking-in To The Server!   K                The server's authentication/authorization environment can beuJ                circumvented under special circumstances. Note that this isM                not possible without administrator action and persists only astF                long as the administrator actually performs the action!  J                This provision exists for only four foreseeable situations:  -                1. ad hoc server configuration   I                2. initial configuration of the authentication environmentt  6                3. loss of the administrator's password  8                4. demonstration/experimentation purposes                  Methodd  E                If performing the initial authentication configuration   B                make_sure_the_HT_AUTH_logical_is_correctly_defined.  L                Manually start a new instance of the server on a non-standardM                port using the /PROMISCUOUS qualifier. This can be done at the.C                command line. There is now a security hole. Example:l  /                   $ HTTPD = "$HT_EXE:HTTPD.EXE"rG                   $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUSy  M                This server with then allow access using any username/passwordvJ                combination. Even if not completely paranoid it's perhaps aL                good idea to append a specific password to the qualifier, the:                server will then only authenticate to that.  T                   $ SPAWN /WAIT HTTPD /NOLOG /SERVICE=8088 /PROMISCUOUS=VERYCAUTIOUS  '             11-2  Server Administratione n  i            L                Access this instance of the server with a browser and use the*                server administration menu.    1                   http://host:port/httpd/-/admin/   K                It is now possible to review server-generated reports, check G                rule mappings, create databases, enter username details,AL                change the administrator's password to something known, etc.,M                etc. Shutdown that server again (ctrl-Y) and the security holek                disappears.  F                Note that if a site authorization rule already maps theF                administration menu path or configuration file path theJ                server may report duplicate path errors. This is due to theI                /PROMISCUOUS startup effectively introducing the followingeJ                two rules, ensuring the menu and configuration files can beM                accessed regardless of anything already in or missing from the "                authorization file.                     [PROMISCUOUS] <                   # access to the server administration menu&                   /httpd/-/admin/* r+wU                   # access to write into the "usual" location for configuration filesa&                   /ht_root/local/* r+w  L                Other rules may be placed in the local configuration file forL                the [PROMISCUOUS] realm specifically for use during this modeM                of access. They will not apply during normal server operation.MF                Be sure they are placed before other rules in the file.  %             11.2 HTTPd Server Reports   L                The server provides a number of internally generated reports.  F                It is possible to use this facility standalone, without;                configuring authorization, see Section 11.1.F  J                1. Statistics -  Server process up-time, CPU-time and otherF                   resources consumed, number of connections processed,L                   number of requests of each HTTP method, type of processingJ                   involved (HTTPd module used), number of bytes processed,                   etc.  L                2. Configuration -  A tabular summary of the server's currentL                   configuration. This is a convenient method for viewing the9                   information from the HTTPD$CONFIG file.   M                3. Message -  A tabular report of the server's current messageuL                   database, multiple languages shown if configured that way.  6                4. Mapping -  All loaded mapping rules.  N                                                    Server Administration  11-3    e            M                   In addition a query-form interface allows the user to inputdL                   a path and watch the rules as the server resolves it. NoteL                   that conditionals are not applied to rules when doing thisI                   checking (generally not possible such a situation), andoL                   so these cannot be assessed. As a result it is possible toL                   see multiple paths indicated as matched. The resulting VMSM                   specification and/or script specification will indicate thef!                   actual mapping.   G                5. Path Authorization -  If authorization is in use (seesH                   Chapter 9) this report lists the paths with associated3                   authorization and access control.   F                6. User Authentication -  List any users that have beenI                   authorized since the server was last started, the realm H                   authorized from, the group it applies to (if any), andL                   what the user's capabilities are (allowed HTTP methods). AI                   time-stamp and counters provide additional information.s  K                7. Cache -  Allows monitoring of cache behaviour and perfor-oI                   mance, as well as the files currently in the cache. For.5                   further information see Chapter 13.t  E                8. DCL Scripting -  Provides some DCL, CGI and CGIpluse(                   scripting information.  L                   o  DCL module statistics (same information as displayed inL                      the server statistics report). These are cumulative forC                      the entire life of the system (unless zeroed).e  N                   o  Subprocess information shows how many actual subprocessesI                      exist at the time of the report, as indicated by the M                      PID and bolded, non-zero liftime (in minutes). The soft- I                      limit specifies how many CGIplus scripts are allowed J                      to continue existing before the least used is deletedF                      and the hard-limit show how many subprocesses mayJ                      actually exist at any one time (the margin allows forL                      subprocess deletion latency). A count of how many timesI                      the CGIplus subprocesses have been explicitly purgedtJ                      (button available on this report page). The life-timeJ                      of zombie processes (in minutes, zero implying use ofN                      zombies is disabled) and the number that have been purgedM                      due to expiry. CGIplus subprocess life-time (in minutes,gN                      zero implying indefinite), the number purged due to life-L                      time expiry and the number of CGIplus subprocesses thatM                      the server has actually purged (deleted) to maintain thel7                      soft-limit margin specified above.   H                   o  Each of the allocated subprocess data structures isL                      listed. There may be zero up to hard-limit items listedM                      here depending on demand for DCL activities and the life M                      of the server. Items with a PID shown indicate an actual   '             11-4  Server Administrationa i  e            L                      subprocess existing. This can be a zombie subprocess orM                      a CGIplus subprocess. If no subprocess is indicated then M                      the other information represents the state the last time5L                      the item's associated subprocess completed. InformationI                      includes the script (URL-style path) or DCL command,tM                      total count of times the item has been used and the lastfJ                      time it was. The zombie count indicates the number ofL                      time the same subprocess finished a request and enteredM                      the zombie state. The CGIplus column indicates it is/wastN                      a CGIplus script and shows the total number of times thatN                      particular script has been/was used. If the subprocess isL                      currently in use the client information show the client                      host name.c  E                   o  If any subprocesses are associated with any dataeI                      structure a purge button is provided that forces allMH                      subprocesses to be deleted. This can be useful if aH                      new script image is compiled and it is required allN                      scripts now use this. If a script is currently processingG                      a request the subprocess deletion occurs when thateL                      processing is complete. The purge button does not forceJ                      a subprocess to delete, so a second button forces allI                      subprocesses to delete immediately. This can be usedoK                      to forceably clear errant scripts, etc., but be warneddA                      script processing is indiscrimately stopped!a  L                9. DECnet Scripting -  DECnet module information shows totalsL                   for DECnet scripting usage and the DECnet connection list.  H                   This list will grow, up to the specified configurationI                   maximum, as conconurrent scripting demand occurs. Main-sJ                   tained connections are indicated by the bolded, non-zeroK                   lifetime (in minutes). When this reaches zero the task is L                   disconnected. The current/last task for that connection isJ                   indicated, along with the number of times the connectionK                   was reused and a total number of uses for that list item.   J                   Purge and force buttons allow current links to be brokenD                   after request completion or forcibly disconnected.  L               10. Memory -  Provides a report and does an integrity check onL                   each of the Virtual Memory (VM) zones employed by the WASD                   HTTPd.  J               11. Request -  Lists current requests (always shows at leastF                   your own connection accessing this report :^) and ifE                   enabled by configuration a history list of the mostII                   recent requests. Enabled by the configuration parameter #                   [RequestHistory].   N                                                    Server Administration  11-5 9               I               12. SSL -  The SSL report lists counts of the number of SSLlJ                   transactions initiated and completed, along with sessionF                   cache statistics. If the current request was via SSLI                   it also lists the ciphers available and current sessionn                   information.  M               13. Activity -  Provide a graphical snapshot of server activitya$                   of a given period.  F                   This is dynamic data, held in memory only, and so isD                   current only from the latest server startup. It isH                   enabled by the configuration parameter [ActivityDays].L                   The administration menu provides several, represented as aM                   period of hours before the present time. Number of requests4M                   and bytes sent to the client are represented by a histogramnL                   with respective means for each during the period by a lineK                   graph. A greyed area indicates no data available for thatoH                   time (i.e. before the latest server startup, or in the                   future).  J                   Activity data is accumulated on a per-minute basis. ThisH                   is the maximum granularity of any report. When reportsI                   are selected that can display less than this one minute M                   granularity (i.e. with periods greater than four hours) thepJ                   value shown is the peak of the number of minutes sampledL                   for display. This better represents the load on the server5                   than would a mean of those samples.m  M                   For browsers recognised as capable (with v4.3 of the server K                   these are Netscape Navigator 3.0ff and Microsoft Internet I                   Explorer 3.02ff) this report is JavaScript-enabled, and9I                   if in focus the browser refreshes itself at an interval_G                   appropriate to the reporting period. If not in focus, H                   the report is automatically refreshed when the browser-                   is brought back into focus.n  K                   The graph is an image map, various regions of which alloweJ                   the selection of other reports with different periods orK                   durations. This allows previous periods to be examined atvJ                   various levels of detail using the graph for navigation.L                   Various sections may have no mapping as appropriate to the!                   current report.   H                   The following example shows the layout for a four hourD                   report. The upper and lower sections have distinctG                   functions. The middle 50% of the upper section allows J                   the same end time (most commonly the current hour) to beI                   examined over twice the current period, in this case it M                   would be over eight hours. The left 25% allows the previous I                   fours hours to be viewed (if such data exists), and for H                   non-current reports the right 25% allows the next fourH                   hours to be viewed. The lower half can be divided into  '             11-6  Server Administrationa (  r            M                   sections representing hours or days depending on the period M                   of the current report. This allows that period to be viewedSM                   in greater detail. For single hour reports this section, ofs(                   course, is not mapped.  E                   Remember that the URL of the mapped section will betH                   displayed in the status bar of the browser. As the URLH                   contains time components it is not a difficult task toM                   decipher the URL displayed to see the exact time and periode!                   being selected.e    F                      +-----------+-----------------------+-----------+F                      | previous  |     same end time     | next      |F                      | 4 hours   |   double the period   | 4 hours   |F                      |           |                       |           |F                      |           |                       |           |F                      +-----------+-----------+-----------+-----------+F                      | hour 1    | hour 2    | hour 3    | hour 4    |F                      | period: 1 | period: 1 | period: 1 | period: 1 |F                      |           |           |           |           |F                      |           |           |           |           |F                      +-----------+-----------+-----------+-----------+  $             11.3 HTTPd Server Revise  M                The server provides a limited configuration revision facility.i  E                1. Configuration -  A form-driven interface allows the G                   current configuration of the server to be altered on- K                   line. This configuration may then be saved to the on-diskeK                   file and then the server could be restarted using the new I                   parameters. The source of the current configuration cansL                   be either the server itself (from it's volatile, in-memoryH                   parameters) or from the on-disk configuration file. InI                   addition it is possible to directly edit and update thev                   on-disk file..  L                2. Message -  No form-driven interface is currently availableF                   for changing the messages. However it is possible toG                   directly edit and update the on-disk file. The serverfI                   can then be restarted to use the modified database (see                     Section 11.4).  L                3. Mapping -  No form-driven interface is currently availableH                   for changing the mapping rules. However it is possibleK                   to directly edit and update the on-disk file. The mappingtK                   rules could then be reloaded, changing the current server_+                   rules (see Section 11.4).   N                                                    Server Administration  11-7 P  I            M                4. Path Authorization -  No form-driven interface is currentlyuJ                   available for changing the path authorization configura-J                   tion. However it is possible to directly edit and updateK                   the on-disk file. The path authorization directives could L                   the be reloaded, changing the current server authorization%                   (see Section 11.4).i  H                5. User Authentication -  User authentication comprises aM                   number of dialogues that allow the authentication databases84                   to be administered. These include:  '                   o  creating databases   '                   o  deleting databases   D                   o  accessing databases for administering usernames  7                   o  listing usernames within databases   %                   o  adding usernames   '                   o  deleting usernames   B                   o  modifying username permissions and other data  K                   o  reseting in-server (cached) authentication information   A                   Chapter Chapter 9 covers authentication detail.k  $             11.4 HTTPd Server Action  J                The server allows certain run-time actions to be initiated.M                Many of these functions can also be initiated from the command %                line, see Section 5.3.i                  Control Section  J                1. Server Restart/restartNOW/Exit/exitNOW -  Caution ... noG                   confirmation! The difference between restart/exit andsH                   restartNOW/exitNOW is the former waits for any currentD                   requests to be completed, while the latter does itD                   immediately regardless of any current connections.  G                2. Logging On/Off/Flush -  The HTTPD$LOG logical must becF                   configured to allow access logging to be enabled and*                   disabled from this menu.  M                3. Caching On/Off/Purge -  Caching may be enabled and disablediG                   in an ad hoc fashion using these controls. When beingpM                   disabled after being enabled all previous data is retained.fM                   If subsequently reenabled that data is then again available K                   for use. This allows convenient assessment of the subject F                   or even object benefits on the cahing. If purged all3                   entries in the cache are removed.1  '             11-8  Server Administrationr o  s            +                Configuration Action Section   J                1. Statistics Zeroed -  All counters are zeroed (except the2                   number-of-times-zeroed counter!)  M                2. Mapping Rules Reload -  Reloads the path mapping rules from ;                   the on-disk file into the running server.a  L                   Caution!  If changing CGIplus script mapping it is advisedI                   to restart the server rather than reload. Some conflictII                   is possible when using new rules while existing CGIplusu(                   scripts are executing.  M                3. Path Authorization Reload -  Reloads the path authorization K                   directives from the on-disk file into the running server.   K                4. User Authentication Cache Purge -  For efficiency reasonsoL                   authenticated user information is cached for a limited pe-M                   riod within the running server. All this cached informationiJ                   may be completely purged using this action, forcing sub-I                   sequent requests to be reauthenticated from the on-diske                   database.u                                                        N                                                    Server Administration  11-9 s  p                M             Chapter__12______________________________________________________h               Scriptingo    G                This chapter is not a tutorial on authoring CGI scripts.pK                There exists a plague of references in the popular computing G                press covering aspects of this technology, usually quite C                comprehensive. This chapter merely outlines the WASDlM                implementation details, which are in general very much vanilla                 CGI.t  H                Scripts are mechanisms for creating simple HTTP services,L                sending data to (and sometimes receiving data from) a client,F                extending the capabilities of the basic HTTPd. AnythingJ                that can write to SYS$OUTPUT can be used to generate scriptL                output. A DCL procedure or an executable can be the basis forM                a script. Simply TYPE-ing a file can be provide script output. I                Scripts execute in processes separate from the actual HTTPnE                server but under it's control and interacting with it.i  D                NOTE:  WASD can manage a script's process environmentI                either as a subprocess spawned by the HTTP server, or as auK                network process created using DECnet. By default it supportsdJ                subprocess-based CGI scripts without further configuration.I                If DECnet-based CGI scripting or OSU (DECthreads) emulated 5                scripting is desired see Section 12.8.   H                Scripts are enabled using the exec or script rules in theM                mapping file (see Chapter 8). The script portion of the resultmH                must be a URL equivalent of the physical VMS procedure or(                executable specification.               12.1 Caution!s  L                Scripts are executed within unprivileged subprocesses spawnedK                by the HTTP server. These subprocesses are owned by the HTTPnK                server account (HTTP$SERVER). Script actions can potentially H                affect server behaviour. For example it is possible for aK                script to issue an "HTTPD/DO=EXIT=NOW" command, or to createnJ                or modify logical name values in the JOB table (e.g. changeK                the value of LNM$FILE_DEV altering the logical search path).cL                Obviously these types of actions are undesirable. In additionJ                scripts can access any WORLD-readable and modify any WORLD-H                writable resource in the system/cluster, opening a windowG                for information leakage or mischievous/malicious actionsoL                (some might argue that anyone with important WORLD-accessableJ                resources on their system deserves all that happens to them  N                                                                Scripting  12-1 s  r            K                - but we know they're out there :^) Script authors should be K                aware of any potential side-effects of their scripts and Web5L                administrators vigilant against possible malicious behaviours-                of scripts they do not author.-  H                As of version 4.2 it has become possible to exercise someL                control over the privileges of spawned subprocesses, allowingJ                enviroments that require scripts to have minimum privilegesM                (e.g. NETMBX, TMPMBX for IPC) to provide them using the serverI>                account's authorized privileges. See Chapter 6.  &             12.2 Scripting Environment  K                WASD HTTPd scripting underwent a major redesign between v4.1cH                and v4.2. This was to provide a faster and more efficientL                scripting environment. It provided the opportunity for a muchI                needed review of the DCL mechanism within the server. As apK                result two capabilities not found in earlier versions becameoI                available, persistant subprocesses (see below) and CGIplus "                (see Section 12.7).  M                Process creation under the VMS operating system is notoriously G                slow and expensive. This is an inescapable overhead when D                scripting via child processes. An obvious strategy isF                to avoid, at least as much as possible, the creation ofM                subprocesses. The only way to do this is to share subprocessesuJ                between multiple scripts/requests, addressing the attendantH                complications of isolating potential interactions betweenM                requests. These could occur through changes made by any scriptsJ                to the subprocess' enviroment. For VMS this involves symbolL                and logical name creation, and files opened at the DCL level.K                In reality few scripts need to make logical name changes and L                symbols are easily removed between uses. DCL-opened files areL                a little more problematic, but again, in reality most scripts6                doing file manipulation will be images.  J                A reasonable assumption is that for almost all environmentsM                scripts can quite safely share subprocesses with great benefithJ                to response latency and system impact (see Section 14.2 forH                a table with some comparative performances). If the localM                environment requires absolute script isolation for some reasonrM                then this subprocess-persistance may easily be disabled with ab3                consequent trade-off on performance.   H                NOTE: With the form of subprocess management used in v4.2I                and following, BYTLM can become an issue. When setting the I                HTTPd account BYTLM quota allow approxiamtely 12,500 byteseM                per subprocess that can be concurrently active, plus a generaltH                allowance (technically, allow 1.0 x /NETBUF= plus 1.0 x +L                0.5 x + 0.5 x /SUBBUF=). That is if the subprocess hard-limitM                (see below) is 20 then BYTLM should be set to at least 250,000a               12-2  Scriptingn                 K                plus 50,000. Of course in such a case PRCLM should be set tosJ                at least 20, preferably 40. These and other relevant quotasH                may be monitored using the HTTPDMON utility or the server#                administration menu.a                    Zombies  D                The term zombie is used to describe subprocesses whenJ                persisting between uses (the reason should be obvious, theyM                are neither "alive" (processing a request) nor are they "dead" L                (deleted) :^) Zombie subprocesses have a finite time to existI                (non-life-time?) before they are automatically purged from L                the system (see Chapter 6). This keeps process clutter on the#                system to a minimum.n                12.3 Script Run-Time  I                Scripts are merely executed or interpreted files. Although K                by default VMS executables and DCL procedures can be used as K                scripts, other run-time environments may also be configured.bH                For example, scripts written for the Perl language may beF                transparently given to the Perl interpreter in a scriptG                subprocess. This type of script activation is based on atL                unique file type (extension following the file name), for theM                Perl example this is most commonly ".PL", or sometimes ".CGI".oJ                Both of these may be configured to automatically invoke theM                site's Perl interpreter, or any other run-time environment for                 that matter.e  K                This configuration is performed using the [DclScriptRunTime]fI                parameter, where a file type is associated with a run-timehI                environment. This parameter takes two components, the fileoL                extension and the run-time verb. The verb may be specified asK                a simple, globally-accessable verb (e.g. one embedded in thefI                CLI tables), or in the format to construct a foreign-verb,hM                providing reasonable versatility. Run-time parameters may alsoiI                be appended to the verb if desired. The server ensures themL                verb is foreign-assigned if necessary, then used on a commandK                line with the script file name as the final parameter to it.   K                The following is an example showing a Perl run-time environ-xK                ment being specified. The first line assumes the "Perl" verbnJ                is globally accessable on the system (e.g. perhaps providedI                by the DCL$PATH logical) while the second (for the sake ofmM                illustration) shows the same Perl interpreter being configured G                for a different file type using the foreign verb syntax.e  $                   [DclScriptRunTime]                   .PL PERL%                   .CGI $PERL_EXE:PERL   N                                                                Scripting  12-3                 K                A file contain a Perl script then may be activated merely byn6                specifying a path such as the following  %                   /cgi-bin/example.pln  J                To add any required parameters just append them to the verb                specified.   $                   [DclScriptRunTime]9                   .XYZ XYZ_INTERPRETER -vms -verbose -etctB                   .XYZ $XYZ_EXE:XYZ_INTERPRETER /vms /verbose /etc  K                If a more complex run-time environment is required it may besK                necessary to wrap the script's execution in a DCL procedure.s  %                Script File Extensionsd  J                The WASD server does not require a file type (extension) toH                be explicitly provided when activating a script. This canH                help hide the implementation detail of any script. If theK                script path does not contain a file type the server searches H                the script location for a file with one of the known fileG                types, first ".COM" for a DCL procedure, then ".EXE" for H                an executable, then any file types specified using scriptH                run-time configuration directive, in the order specified.  K                For instance, the script activated in the Perl example above L                could have been specified as below and (provided there was noL                "EXAMPLE.COM" or "EXAMPLE.EXE" in the search) the same script(                would have been executed.  "                   /cgi-bin/example               12.4 CGI Compliances  F                The HTTPd scripting mechanism is designed to be WWW CGIL                (Common Gateway Interface) compliant, based in part on by theL                INTERNET-DRAFT authored by D.Robinson (drtr@ast.cam.ac.uk), 8                January 1996.  &                CGI Compliant Variables  D                Environment variables are created in a similar way toG                the CERN VMS HTTPd implementation, where CGI environmenteK                variables are provided to the script via DCL global symbols.aH                Each CGI variable symbol name is prefixed with "WWW_" (byL                default, although this can be changed using the "/CGI_PREFIX"I                qualifier, see Section 5.3, this is not recommended if thetK                WASD VMS scripts are to be used, as they expect CGI variablei6                symbols to be prefixed in this manner).               12-4  Scripting                  *                Extensions to CGI Variables  F                In line with other CGI implemenations, additional, non-H                compliant variables are provided to ease CGI interfacing.J                These provide the various components of the query string. AK                keyword query string and a form query string are parsed into )                separated variables, namede                      WWW_KEY_number                   WWW_KEY_COUNT ,                   WWW_FORM_form-element-name  %                See the example below.   $                CGI Variable Capacity  J                DCL symbol values are limited to approximately 1024 charac-J                ters. The CGI interface will provide symbols with values upL                to that limit if required. This should be sufficient for most                circumstances.   (                CGI Variable Descriptions  >                Remember, all variables are prefixed by "WWW_".  M                ______________________________________________________________aM                Name__________________Description___________"Standard"_CGI____8  =                AUTH_GROUP            authentication group  no /                                      (or empty)   =                AUTH_REALM            authentication realm  nob/                                      (or empty)   >                AUTH_TYPE             authentication type   yes6                                      (BASIC or DIGEST)  >                CONTENT_LENGTH        "Content-Length:"     yes8                                      from request header  >                CONTENT_TYPE          "Content-Type:" from  yes3                                      request header1  =                FORM_field            query string "&"      non3                                      separated formn-                                      elements   >                GATEWAY_INTERFACE     "CGI/1.1"             yes    N                                                                Scripting  12-5 t             M                ______________________________________________________________ M                Name__________________Description___________"Standard"_CGI____   C                HTTP_ACCEPT           any list of browser-  optional 5                                      accepted content *                                      types  C                HTTP_ACCEPT_CHARSET   any list of browser-  optionale7                                      accepted characterf)                                      sets   C                HTTP_ACCEPT_LANGUAGE  any list of browser-  optional 7                                      accepted languages   C                HTTP_AUTHORIZATION    any from request      optionaln+                                      headerb  C                HTTP_COOKIE           any cookie sent by    optional /                                      the client   C                HTTP_FORWARDED        any proxy/gateway     optional 9                                      hosts that forwarded 0                                      the request  C                HTTP_HOST             host and port         optionalt5                                      request was sent '                                      toc  C                HTTP_IF_MODIFIED_     any last modified     optionalm4                SINCE                 GMT time string  C                HTTP_PRAGMA           any pragma directive  optionalG6                                      of request header  C                HTTP_REFERER          any source document   optional 9                                      URL for this request   C                HTTP_USER_AGENT       client/browser        optionalo3                                      identification +                                      stringi  =                KEY_n                 query string "+"      not7                                      separated elements   =                KEY_COUNT             number of "+"         no 7                                      separated elementsc  >                PATH_INFO             virtual path of data  yes5                                      requested in URL   >                PATH_TRANSLATED       VMS file path of      yes6                                      data requested in(                                      URL               12-6  Scriptingd i  a          M                _______________________________________________________________M                Name__________________Description___________"Standard"_CGI____p  >                QUERY_STRING          un-URL-decoded        yes5                                      string followingt/                                      "?" in URLi  >                REMOTE_ADDR           IP host address of    yes0                                      HTTP client  >                REMOTE_HOST           IP host name of HTTP  yes+                                      clienta  >                REMOTE_USER           authenticated remote  yes9                                      user name (or empty),  >                REQUEST_METHOD        "GET", "PUT", etc.    yes  =                REQUEST_SCHEME        "http:" or "https:"   noo  =                REQUEST_TIME_GMT      GMT time request      noe-                                      receiveds  =                REQUEST_TIME_LOCAL    Local time request    no -                                      receivede  >                SCRIPT_NAME           name of script        yes9                                      being executed (e.g.c.                                      "/query")  =                SERVER_GMT            offset from GMT       no 4                                      (e.g. "+09:30")  >                SERVER_NAME           IP host name of       yes2                                      server system  >                SERVER_PROTOCOL       HTTP protocol         yes4                                      version (always0                                      "HTTP/1.0")  >                SERVER_PORT           IP port request was   yes0                                      received on  >                SERVER_SOFTWARE       software ID of HTTP   yesM                ______________________server__________________________________   )                CGI Variable Demonstration   K                The basic CGI symbol names are demonstrated here with a call G                to a script that simply executes the following DCL code:c  %                   $ SHOW SYMBOL WWW_*f!                   $ SHOW SYMBOL *t  M                Note how the request components are represented for "ISINDEX"-,K                style searching (third item) and a forms-based query (fourth   N                                                                Scripting  12-7 t  c                            item).p  /                <online hypertext demonstration>   #                CGI Compliant Outputd  K                Script output must behave in a CGI-compliant fashion (by waytH                of contrast, see Section 12.5). That is, a CGI script mayG                redirect the location of the document, using a Location:mH                header line, or may supply a data stream beginning with aJ                Content-Type: header line. Both must be followed by a blank                line.  I                If the script output begins with a CGI-compliant "Content-eI                Type: text/ . . . " (text document) the HTTPd assumes thateH                output will be line-oriented and requiring HTTP carriage-H                control (each record/line terminated by a line-feed), andJ                will thereafter ensure each record it receives is correctlyJ                terminated before passing it to the client. In this way DCLI                procedure output (and the VMS CLI in general) is supporteduL                transparently. Any other content-type is assumed to be binary3                and no carriage control is enforced.r  &             12.4.1 Example DCL Scripts  C                A simple script to provide the system time might be:n  ,                   $ say = "write sys$output"=                   $! the next two lines make it CGI-compliant 2                   $ say "Content-Type: text/plain"                   $ say ""6                   $! start of plain-text script output                   $ show times  J                A script to provide the system time more elaborately (using                HTML):r  ,                   $ say = "write sys$output"=                   $! the next two lines make it CGI-complianth1                   $ say "Content-Type: text/html"                    $ say ""0                   $! start of HTML script output                    $ say "<HTML>"C                   $ say "Hello ''WWW_REMOTE_HOST'"  !(CGI variable)i                   $ say "<P>" I                   $ say "System time on node ''f$getsyi("nodename")' is:" 0                   $ say "<H1>''f$cvtime()'</H1>"!                   $ say "</HTML>"c                 12-8  Scriptinga n  a                          12.5 Raw HTTP Output  L                A script does not have to output a CGI-compliant data stream.J                If it begins with a HTTP header status line (e.g. "HTTP/1.0M                200 OK"), HTTPd assumes it will supply a raw HTTP data stream,cK                containing all the HTTP requirements. This is the equivalentlL                of the no-parse-header, or "nph . . . " named scripts of some                environments.  L                Any such script must observe the HyperText Transfer Protocol.K                Every line must be terminated by a carriage-return and line- J                feed (represented as "\r""\n"), or as a minimum by a singleL                line-feed. In particular, the type of the data being returnedK                by the scripts must be included in an HTTP header sent prior M                to the data itself. Headers for the two most common data types M                will be illustrated here. Note that the blank line is strictly 3                necessary, it terminates the header.                   Plain-Text   %                   HTTP/1.0 200 ok\r\n .                   Content-Type: text/plain\r\n                   \r\n                  HTMLu  %                   HTTP/1.0 200 ok\r\n -                   Content-Type: text/html\r\nb                   \r\n  "                Raw HTTP DCL Script  H                The following example show a non-CGI-compliant DCL scriptK                similar in function to the CGI-compliant one above. Note theoJ                full HTTP header and each line explicitly terminated with a2                carriage-return and line-feed pair.                            N                                                                Scripting  12-9 o  r            "                   $ cr[0,8] = %x0d"                   $ lf[0,8] = %x0a,                   $ say = "write sys$output"C                   $! the next line determines it is raw HTTP streamt8                   $ say "HTTP/1.0 200 Success''cr'''lf'";                   $ say "Content-Type: text/html''cr'''lf'" :                   $! response header separating blank line$                   $ say "''cr'''lf'"0                   $! start of HTML script output%                   $ say "<HTML>''lf'" 7                   $ say "Hello ''WWW_REMOTE_HOST'''lf'" "                   $ say "<P>''lf'">                   $ say "Local time is ''WWW_TIME_LOCAL'''lf'"&                   $ say "</HTML>''lf'"                     Raw HTTP C Script  L                When scripting using the C programming language and providingM                a full HTTP response there can be considerable efficiencies to M                be gained by providing a binary output stream from the script.lL                This may be simply provided using a code construct similar to;                following to reopen <stdout> in binary mode.v  W                   /* reopen output stream so that the '\r' and '\n' are not filtered */f                   #ifdef __DECCl[                      if ((stdout = freopen ("SYS$OUTPUT", "w", stdout, "ctx=bin")) == NULL)f*                         exit (vaxc$errno);                   #endif  I                This is used consistently in WASD scripts. Of course after :                that the full HTTP header must be supplied.  %                      fprintf (stdout,r,                   "HTTP/1.0 200 Success\r\n\.                   Content-Type: text/html\r\n\                   \r\n\e                   <HTML>\n\i                   Hello %s\n\e                   <P>\n\&                   System time is %s\n\                   </HTML>\n",h/                      getenv("WWW_REMOTE_HOST"),t/                      getenv("WWW_TIME_LOCAL"));i                         12-10  Scripting e  m                         12.6 Raw HTTP Inpute  G                The logical name SYS$INPUT (with a synonym of HTTP$INPUTgH                for backward compatibility), <stdin> for C Language basedK                scripts, defines a mailbox providing a stream containing theiJ                request body (if any). This is available for procedures and7                executables to explicitly open and read.   H                Note that this is a raw stream, and HTTP lines (carriage-L                return/line-feed terminated sequences of characters) may haveM                be blocked together for network transport. These would need to 2                be explicity parsed by the program.  J                NOTE: Versions of the server prior to 4.3 supplied the fullK                request (header then body) to the script. This was not fully H                CGI-compliant. Versions 4.3 and following supply only theF                body, although the previous behaviour may be explicitlyK                selected using the configuration parameter [DclFullRequest].i  "             12.7 CGIplus Scripting  L                Common Gateway Interface ... plus lower latency, plus greater7                efficiency, plus far less system impact!   K                I know, I know! The term CGIplus is a bit too_cute but I had:$                to call it something!  I                CGIplus attempts to eliminate the overhead associated with H                creating the subprocess and then executing the image of aJ                CGI script. It does this by allowing the subprocess and anyI                associated image/application to continue executing betweenyI                uses, eliminating any startup overheads. This reduces bothiF                the load on the system and the request latency. In thisJ                sense these advantages parallel those offered by commercialG                HTTP server-integration APIs, such as Netscape NSAPI andsM                Microsoft ISAPI, without the disadvantages of such proprietoryhM                interfaces, the API complexity, language dependency and server #                process integration.   L                CGIplus is not as complex (and consequently nor as versatile)E                as another approach to improving CGI performance, Open <                Market's FastCGI, see http://www.fastcgi.com/  H                CGIplus design is generic enough to be easily implementedE                by other server architectures if found desirable. (For I                example, it is imagined Unix platforms would implement the K                CGIplus variable stream using named pipes one of which would H                be designated by the CGIPLUSIN environment variable.) TheL                CGIplus-specific script environment and example code has beenL                made as platform-neutral as possible, providing potential forL                a more wide-spread adoption. Existing CGI scripts can rapidlyI                and elegantly be modified to additionally support CGIplus.   N                                                               Scripting  12-11 i  a            L                The capability of scripts to easily differentiate between andK                operate in both standard CGI and CGIplus environments with aeA                minimum of code revision offers great versatility.i    "                CGIplus Performance  I                A simple performance evaluation indicates the advantage of H                CGIplus. See Section 14.2 for some test results comparingI                the non-persistant-process, persistant-process and CGIplus                 environments.  K                Without a doubt, the subjective difference in activating themK                same script within the standard CGI and CGIplus environments "                is quite startling!  "                CGIplus Programming  L                The script interface is still CGI, which means a new API doesL                not need to be learned and existing CGI scripts are simple to                modify.  4                See examples in HT_ROOT:[SRC.CGIPLUS]  '                <on-line hypertext link>   E                Instead of having the CGI variables available from the J                environment (generally accessed via the C Language getenv()H                standard library call) a CGIplus script must read the CGII                variables from CGIPLUSIN. They are supplied as a series of H                records (lines) containing a CGI variable name (in upper-G                case), an equate symbol and then the variable value. The L                line will never contain more than 1024 characters. The formatH                may be easily parsed and as the value contains no encoded/                characters may be directly used.t  '                Requirements when using:   L                o  The read will block between subsequent requests and so may8                   be used to coordinate the application.  D                o  The first record read in any request can always beE                   discarded. This is provided so that a script may be K                   synchronized outside of the general CGIplus variable read D                   loop (the DCL and Perl examples use this feature).  G                o  The CGIplus variable stream should be completely read K                   (up until the blank line, see below) before beginning anyr%                   request processing.   I                o  The CGIplus variable stream should ALWAYS BE COMPLETELY <                   READ (up until the blank line, see below).               12-12  Scripting C  T            L                o  An empty record (blank line) indicates the end of a singleK                   request's CGIplus variable stream. Reading MUST be haltedCF                   at this stage. Request processing may then commence.  M                After processing, the CGIplus script can loop, waiting to read >                the details of the next request from CGIPLUSIN.  F                Request output (to the client) is written to SYS$OUTPUTI                (<stdout>) as per normal CGI behaviour. End of output MUST I                be indicated by writing a special EOF record to the outputoJ                stream. This is bit of a kludge, and the least elegant partM                of CGIplus design, but it is also the simplest implementation. K                A unique EOF sequence is generated for each use of DCL via a K                zombie or CGIplus subprocess. A non-repeating series of bits L                most unlikely to occur in normal output is employed . . . butJ                there is still a very, very, very small chance of prematureD                termination of output (one in 2^280 I think!) See HT_D                ROOT:[SRC.HTTPD]DCL.C for how the value is generated.  H                The CGIplus EOF string is obtained by the script from theI                logical name CGIPLUSEOF, defined in the script subprocess' G                process table, using the scripting language's equivalentHI                of F$TRNLNM(),  SYS$TRNLNM(), or a getenv() call (in the C K                standard library). This string will always contain less than L                64 characters and comprise only printable characters. It mustH                be written at the conclusion of a request's output to theK                output stream as a single record (line) but may also containpJ                a <CR><LF> or just <LF> trailing carriage-control (to allowH                for programming language requirements). It only has to beK                evaluated once, as the processing begins, remaining the same J                for all requests over the life-time of that instance of the                script.  L                HTTP input (raw request stream, header and any body) is still-                available to a CGIplus script._                  Code Examples  H                Of course a CGIplus script should only have a single exitF                point and should explicitly close files, free allocatedI                memory, etc., after processing a request (i.e. not rely onDK                image run-down to clean-up after itself). It is particularlyHG                important when modifying existing scripts to work in theyI                CGIplus environment to ensure this requirement is met (whoSH                of us hasn't thought "well, this file will close when the$                image exits anyway"?)  D                It is a simple task to design a script to modify it'sI                behaviour according to the environment it is executing in.MJ                Detecting the presence or absence of the CGIPLUSEOF logicalL                is sufficient indication. The following C code fragment shows  N                                                               Scripting  12-13 n               M                simultaneously determining whether it is a standard or CGIplus L                environment (and setting an appropriate boolean), and getting7                the CGIplus EOF sequence (if it exists).   !                   int  IsCgiPlus; '                   char  *CgiPlusEofPtr;   O                   IsCgiPlus = ((CgiPlusEofPtr = getenv("CGIPLUSEOF")) != NULL);_  J                The following C code fragment shows a basic CGIplus requestL                loop, reading lines from CGIPLUSIN, and some basic processingG                to select required CGI variables for request processing.                       if (IsCgiPlus)                   {O!                      char  *cptr;y'                      char  Line [1024],s,                            RemoteHost [128];&                      FILE  *CgiPlusIn;  P                      if ((CgiPlusIn = fopen (getenv("CGIPLUSIN"), "r")) == NULL)                      {2                         perror ("CGIplus: fopen");!                         exit (0);f                      }                        for (;;)t                      {H                         /* will block waiting for subsequent requests */                          for (;;)                         { S                            /* should never have a problem reading CGIPLUSIN, but */ M                            if (fgets (Line, sizeof(Line), CgiPlusIn) == NULL)                             {8                               perror ("CGIplus: fgets");'                               exit (0);                             }V                            /* first empty line signals the end of CGIplus variables */6                            if (Line[0] == '\n') break;<                            /* remove the trailing newline */Q                            if ((cptr = strchr(Line, '\n')) != NULL) *cptr = '\0';I  Q                            /* process the CGI variable(s) we are interested in *//G                            if (!strncmp (Line, "WWW_REMOTE_HOST=", 16))i;                               strcpy (RemoteHost, Line+16);                          }e  ?                         (process request, signal end-of-output)s                      }                   }   G                CGI scripts can write output in record (line-by-line) or H                binary mode (more efficient because of buffering by the C               12-14  Scripting e  o            J                RTL). When in binary mode the output stream must be flushedL                immediately before and after writing the CGIplus EOF sequenceJ                (note that in binary a full HTTP stream must also be used).K                This code fragment shows placing a script output stream into 2                binary mode and the flushing steps.  W                   /* reopen output stream so that the '\r' and '\n' are not filtered */ X                   if ((stdout = freopen ("SYS$OUTPUT", "w", stdout, "ctx=bin")) == NULL)'                      exit (vaxc$errno);                      do {  '                      (read request ...)w  /                      /* HTTP response header */ \                      fprintf (stdout, "HTTP/1.0 200 ok\r\nContent-Type: text/html\r\n\r\n");  '                      (other output ...)T  #                      if (IsCgiPlus)W                      {O                         /* the CGIplus EOF must be an independant I/O record */o(                         fflush (stdout);>                         fprintf (stdout, "%s", CgiPlusEofPtr);(                         fflush (stdout);                      }  &                   } while (IsCgiPlus);  J                If the script output is not binary (using default <stdout>)J                it is only necessary to ensure the EOF string has a record-#                delimiting new-line.s  :                   fprintf (stdout, "%s\n", CgiPlusEofPtr);  F                Other languages may not have this same requirement. DCLM                procedures are quite capable of being used as CGIplus scripts.v  4                See examples in HT_ROOT:[SRC.CGIPLUS]  '                <on-line hypertext link>   G                Whenever developing CGIplus scripts/applications (unlike M                standard CGI) don't forget that after compiling, the old image J                must be purged from the server before trying out the new!!!6                (I've been caught a number of times :^)  I                Scripting subprocesses may be purged or deleted using (seem                 Section 5.3.2.4):  (                   $ HTTPD /DO=DCL=DELETE'                   $ HTTPD /DO=DCL=PURGEy  N                                                               Scripting  12-15 1  2            #                Other Considerationsp  H                Multiple CGIplus scripts may be executing in subprocessesG                at any one time. This includes multiple instances of any I                particular script. It is the server's task to track these, F                distributing appropriate requests to idle subprocesses,G                monitoring those currently processing requests, creating K                new instances if and when necessary, and deleting the least- K                used, idle CGIplus subprocesses when configurable thresholds H                are reached. Of course it is the script's job to maintainE                coherency if multiple instances may result in resource G                conflicts or race conditions, etc., between the scripts.   I                The CGIplus subprocess can be given a finite life-time set L                by configuration parameter (see Chapter 6). If this life-timeJ                is not set then the CGIplus will persist indefinitely (i.e.K                until purged due to soft-limits being reached, or explicitlyTI                purged/deleted). When a life-time has been set the CGIplus K                subprocess is automatically deleted after being idle for the K                specified period (i.e. not having processed a request). This I                can be useful in preventing sporadically used scripts from 5                cluttering up the system indefinitely.p  K                In addition, an idle CGIplus script can be terminated by thenK                server at any time the subprocess soft-limit is reached (thehI                subprocess SYS$DELPRC()ed)  so resources should be largelycJ                quiescent when not actually processing. Of course a CGIplusL                subprocesses may also be manually terminated from the command$                line (e.g. STOP/ID=).  M                Some CGIplus scripting information and management is available"D                via the server administration menu, see Section 11.2.  #                CGIplus Rule MappingT  K                CGIplus scripts are differentiated from standard CGI scripts M                in the mapping rule configuration file using the "script+" andr1                "exec+" directives. See Chapter 8.   L                Scripts capable of operating in both standard CGI and CGIplusK                environments may simply be accessed in either via rules such                 asy  ,                   exec /cgi-bin/* /cgi-bin/*1                   exec+ /cgiplus-bin/* /cgi-bin/*t  G                while specific scripts can be individually designated as                 CGIplus using  E                   script+ /cgiplus_example* /cgi-bin/cgiplus_example*m               12-16  Scripting $  U            I                Caution!  If changing CGIplus script mapping it is advised J                to restart the server rather than reloading the rules. SomeG                conflict is possible when using new rules while existing -                CGIplus scripts are executing.d    !             12.8 DECnet Scriptinga  F                "Imitation is the sincerest form of flattery" - proverb  J                NOTE:  WASD requires no additional configuration to supportL                subprocess-based scripting. The following information applies9                only if DECnet-based scripting is desired.s  H                By default WASD executes scripts within subprocesses, butF                can also provide scripting using DECnet for the processH                management. DECnet scripting is not provided to generallyI                supplant the subprocess-based scripting but augment it foro%                certain circumstances:i  G                o  To provide an environment within WASD where OSU-basedeM                   scripts (both CGI and OSU-specific) may be employed without                    modification.   K                o  To allow nodes without a full HTTP service to participate J                   in providing resources via a well-known server, possibly:                   resources that only they have access to.  F                o  Load-sharing amongst cluster members for high-impact5                   scripts or particularly busy sites.   1                o  Provide user-account scripting.   !                DECnet Performancea  A                Any DECnet based processing incurs some overheads.a  *                o  connection establishment  ,                o  NETSERVER image activation  <                o  NETSERVER maintenance (such as logs, etc.)  @                o  activation of DECnet object image or procedure  *                o  DECnet object processing  <                o  activation by object of image or procedure  (                o  DECnet object run-down  F                o  NETSERVER image reactivation on completion of object                   processing  N                                                               Scripting  12-17 e               J                As of version 5.2 WASD provides reuse of DECnet connectionsD                for both CGI and OSU scripting, in-line with OSU v3.3H                which provided reuse for OSU scripts. This means multipleJ                script requests can be made for the cost of a single DECnetH                connection establishment and task object activation. ThisJ                functionality provides substantial performance improvementsM                as indicated by Section 14.3. Note that the OSU task proceduresJ                requires the definition of the logical name WWW_SCRIPT_MAX_M                REUSE representing the number of times a script may be reused.d<                The WASD startup procedures can provide this.  L                In practice both the WASD CGI and OSU scripts seem to provide)                acceptable responsiveness.f                  Rule Mapping   F                DECnet-based scripts are mapped using the same rules asM                subprocess-based scripts, using the SCRIPT and EXEC rules (see J                Chapter 8 for general information on mapping rules). DECnetJ                scripts have a DECnet node and task specification string asJ                part of the mapping rule. There are minor variations withinK                these to further identify it as a WASD or an OSU script. SeetH                Section 12.8.4 for information on mapping user scripting.  L                The specification string follows basic VMS file system syntaxM                (RMS), preceding the file components of the specification. ThepK                following example illustrates declaring that paths beginning K                with FRODO will allow the execution of scripts from the CGI- ;                BIN:[000000] directory on DECnet node FRODO.   2                   exec /FRODO/* /FRODO::/cgi-bin/*  L                In similar fashion the following example illustrates a scriptM                "frodo_show" that might do a "SHOW SYSTEM" on node FRODO. Notei5                that these rules are case-insensitive.   D                   script /frodo-showsys /frodo::/cgi-bin/showsys.com  G                Both of the above examples would use the WASD CGI DECnet J                environment (the default if no task specification string isK                provided). By including task information other environments, K                in particular the OSU scripting enviroment, can be specified H                for the script to be executed within. The default task isK                named CGIWASD and can also be explicitly specified (althoughnM                this behaviour would be the same as that in the first example)   @                   exec /frodo/* /frodo::"task=cgiwasd"/cgi-bin/*  K                All task specification strings may also use zero as the task                 abreviation.   =                   exec /frodo/* /frodo::"0=cgiwasd"/cgi-bin/*n               12-18  Scripting                 I                To execute a script within the OSU environment specify the G                standard OSU task executive WWWEXEC, as in the following                 example:   >                   exec /osu/* /FRODO::"task=wwwexec"/cgi-bin/*  K                This would allow any URL beginning with "/osu/" to execute a -                script in the OSU environment.                   Local Systemr  I                To specify any script to execute on the same system as thepE                HTTP server specify the node name as zero or SYS$NODE.   =                   exec /decnet/* /0::"task=cgiwasd"/cgi-bin/*tA                   exec /osu/* /sys$node::"task=wwwexec"/cgi-bin/*   B                Mapping rules are included in the examples (see HT_K                ROOT:[EXAMPLE]) providing this. After the DECnet environment(K                has been started any CGI script may be executed on the local K                system via DECnet by substituting "/decnet/" for "/cgi-bin/"aH                as the script path, and any OSU script available by usingJ                "/osu/". Behaviour is indeterminate, though it shouldn't beM                catastrophic, if one is invoked using the incorrect path (i.e.zI                an OSU script using /decnet/ or a CGI script using /osu/).   ,             12.8.1 Script System Environment  H                The target system must have sufficient of the WASD serverL                environment to support the required CGI script activation andI                activity. If the target system is actually the same system.G                as the HTTP server then it already exists, or if part oftH                the local system's cluster, then providing this should beI                relatively straight-forward. If the target system has nonenG                of the server environment then at a minimum it must havehJ                the logical name CGI-BIN defined representing the directoryK                containing the required DECnet object procedure and scripts.I7                The following fragment illustrates this:r  Q                   $ DEFINE /SYSTEM /TRANSLATION=(CONCEALED) CGI-BIN device:[dir.]y  D                In this directory must be located the WASDCGI.COM andF                WWWEXEC.COM procedures required by the network task. OfL                course other parts of the environment may need to be provided0                depending on script requirements.          N                                                               Scripting  12-19    u            !             12.8.1.1 Proxy Accesss  E                The local system must have proxy access to each targetdI                scripting system (even if that "target" system is the samesI                system as the HTTP server). This involves creating a proxylG                entry in each target hosts's authorization database. The M                following example assumes the existance of a local HTTP$SERVERuH                account. If it does not exist on the target node then oneI                must be created with the same security profile as the HTTPt                server's.  F                Caution! If unsure of the security implications of thisI                action consult the relevant VMS system management security                 documentation.b  E                The zero represents the system the server is currently                 executing on.  *                   $ SET DEFAULT SYS$SYSTEM!                   $ MCR AUTHORIZEoE                   UAF> ADD /PROXY 0::HTTP$SERVER HTTP$SERVER /DEFAULT   F                It is necessary to ensure the account has permission toJ                write into it's home directory. A network process creates aL                NETSERVER.LOG (Phase-IV) or NET$SERVER.LOG (DECnet-Plus) fileJ                in the home directory, and will fail to start if it cannot!  #             12.8.1.2 DECnet Objectss  M                To provide DECnet scripting DECnet object(s) must be specified H                for any system on which the scripts will be executed. TheM                DECnet object is the program or procedure that is activated atiM                the target system inside of a network-mode process to interacts$                with the HTTP server.  (                DECnet-Plus (OSI/Phase-V)  I                DECnet-Plus uses the NCL utility to administer the network M                environment. The following NCL scripting shows the creation of =                a network application for the WASD CGI object:                      $ MCR NCL{C                   CREATE NODE 0 SESSION CONTROL APPLICATION CGIWASD ]                   SET NODE 0 SESSION CONTROL APPLICATION CGIWASD ADDRESSES = {NAME=CGIWASD} -                    ,CLIENT =  -*                   ,INCOMING ALIAS = TRUE -*                   ,INCOMING PROXY = TRUE -+                   ,OUTGOING ALIAS = FALSE - *                   ,OUTGOING PROXY = TRUE -(                   ,NODE SYNONYM = TRUE -=                   ,IMAGE NAME = CGI-BIN:[000000]CGIWASD.COM - &                   ,INCOMING OSI TSEL =               12-20  Scripting "               :                To create a DECnet-Plus OSU WWWEXEC object:                     $ MCR NCLi]                   SET NODE 0 SESSION CONTROL APPLICATION WWWEXEC ADDRESSES = {NAME=WWWEXEC} -=                   ,CLIENT =  -*                   ,INCOMING ALIAS = TRUE -*                   ,INCOMING PROXY = TRUE -+                   ,OUTGOING ALIAS = FALSE - *                   ,OUTGOING PROXY = TRUE -(                   ,NODE SYNONYM = TRUE -=                   ,IMAGE NAME = CGI-BIN:[000000]WWWEXEC.COM -1&                   ,INCOMING OSI TSEL =  M                These must be executed at each system (or server) startup, and J                may be executed standalone, as illustrated, or incorporatedL                in the NCL script SYS$STARTUP:NET$APPLICATION_STARTUP.NCL forI                automatic creation at each system startup. Examples may bey*                found in HT_ROOT:[EXAMPLE].                  Phase-IV   M                DECnet Phase-IV uses the NCP utility to administer the networkmL                environment. The following NCP commands may be used each timeK                during server startup to create the required DECnet objects. L                With Phase-IV the SET verb may be replaced with a DEFINE verbJ                and the commands issued just once to permanently create theI                objects (a SET must also be done that first time to createu9                working instances of the DEFINEd objects).)  -                To create a DECnet CGI object:                      $ MCR NCP N                   SET OBJECT CGIWASD NUMBER 0 FILE CGI-BIN:[000000]CGIWASD.COM  5                To create a DECnet OSU WWWEXEC object:k                     $ MCR NCP\N                   SET OBJECT WWWEXEC NUMBER 0 FILE CGI-BIN:[000000]WWWEXEC.COM  :                Examples may be found in HT_ROOT:[EXAMPLE].  ,             12.8.1.3 Reducing Script Latency  J                Script system network process persistance may be configuredJ                using NETSERVER logical names. These can control the numberJ                and quiescent period of the server processes. These logicalH                names must be defined in the LOGIN.COM of the HTTP server3                account on the target script system.i  I                o  NETSERVER$SERVERS_username -  This logical controls thepL                   number of network server processes that are kept availableM                   at any one time. Defining this logical results in a minimum G                   of the specified number of quiescent server processesO  N                                                               Scripting  12-21 e  e            I                   maintained. This can improve script response latency byeG                   circumventing the need to create a process to servicemH                   the request, at the cost of cluttering the system with&                   NETSERVER processes.  @                      DEFINE /JOB NETSERVER$SERVERS_HTTP$SERVER 5  K                o  NETSERVER$TIMEOUT -  This logical controls the duration a J                   quiescent network process persists before being deleted.L                   The default period is five minutes. The following examplesH                   first show reducing that to thirty seconds, the secondK                   increasing it to one hour. Again, this can improve scriptiH                   response latency by circumventing the need to create aL                   process to service the request, at least during the periodB                   a previously created process continues to exist.  ?                      DEFINE /JOB NETSERVER$TIMEOUT "0 00:00:30"a?                      DEFINE /JOB NETSERVER$TIMEOUT "0 01:00:00"u  '             12.8.1.4 DECnet/OSU Startup   H                The example STARTUP.COM and STARTUP_DECNET.COM proceduresC                found in the HT_ROOT:[EXAMPLE] directory provide the F                essentials for DECnet/OSU scripting. If the INSTALL.COME                startup environment is used setting the PROVIDE_DECNET J                symbol to 1 in STARTUP.COM will create the DECnet scripting1                environment during server startup.w               12.8.2 CGI  J                CGI scripts may be transparently executed within the DECnetL                scripting environment. This means that the script is executedD                within a network process, on the target system (whichI                could be the local system), instead of within a subprocessqG                on the local system. Other than that the WASD DECnet CGIdI                environment behaves identically to the standard subprocess F                CGI environment. CGIplus scripting is not supported andD                if CGIplus-only scripts are executed the behaviour is                indeterminate.r  L                An example of making the HELP database on a system other thanM                that hosting the HTTP server (using the CONAN script) would be +                done using the mapping rulesa  .                   map /FRODO/help /FRODO/help/?                   script /FRODO/help/* /FRODO::/cgi-bin/conan/*i  2                and for the example DCL SHOW script  <                   script /FRODO/show* /FRODO::/cgi-bin/show*               12-22  Scripting e  f            -             12.8.3 OSU (DECthreads) Emulationh  M                The OSU, or DECthreads, server is the most widely deployed VMS"M                HTTP server environment, authored by David Jones and copyrightbD                the Ohio State University. See http://kcgl1.eng.ohio-F                state.edu/www/doc/serverinfo.html for more information.  D                The WASD HTTP server provides an emulation of the OSUH                scripting environment. This is provided so that OSU-basedK                scripts (both CGI-style and OSU-specific) may be employed byiM                WASD with no modification. As this emulation has been designedUJ                through examining OSU code and lots of trial and error it'sK                behaviour may be incomplete or present errors. A list of OSUrM                scripts known to work with WASD is provided at the end of thist2                section, see Known Working Scripts.  F                Supported scripts include only those that depend on theC                OSU WWWEXEC object and dialog for all functionality.DD                Any script that uses other OSU-specific functionalityF                is not supported. Interactions between WASD's and OSU'sD                authentication/authorization schemes may be expected.  H                Please remember this is a first-cut of reverse-engineeredK                technology. The author would like to know of any OSU scriptsCK                the WASD emulation barfs on, and will attempt to address theo:                associated limitation(s) and/or problem(s).                  OSU Setup  K                Software necessary for supporting the OSU scripting environ- K                ment (e.g. WWWEXEC.COM) and selected OSU scripts (mainly for M                testing purposes) have been extracted from the OSU v3.3a pack-PL                age and included in the HT_ROOT:[SRC.OSU] directory. This hasE                been done within the express OSU licensing conditions.   @                   Copyright 1994,1997 The Ohio State University.R                   The Ohio State University will not assert copyright with respectP                   to reproduction, distribution, performance and/or modificationO                   of this program by any person or entity that ensures that all Q                   copies made, controlled or distributed by or for him or it bear O                   appropriate acknowlegement of the developers of this program.   J                An example DECnet and OSU scripting startup may be found inK                HT_ROOT:[EXAMPLE]. This should be called from or used withineK                the HTTP server startup. It includes two logical definitionsmF                required for common OSU scripts. Other tailoring may be1                required for specific OSU scripts.       N                                                               Scripting  12-23 r  d            %                OSU - General Commentsb  K                David Jones, the author of the DECthreads (OSU) HTTP server, G                outlines his reasons for basing OSUs scripting on DECnetsL                (reproduced from a USENET NEWS reply to a comment this author2                made about DECnet-based scripting).  Z                   ------------------------------------------------------------------------  L                   From           JONESD@er6.eng.ohio-state.edu (David Jones):                   Organization   The Ohio State University9                   Date           12 Aug 1997 09:04:11 GMTe\                   Newsgroups     vmsnet.sysmgt,comp.os.vms,comp.infosystems.www.servers.miscO                   Message-ID     <5sp8ub$brs$1@charm.magnus.acs.ohio-state.edu>   Z                   ------------------------------------------------------------------------  +                    . . .  some text omittedb  S                   Since I was comfortable with DECnet, I based the scripting systemfS                   for the OSU server around it.    The key reasons to use netservert?                   processes rather than spawning sub-processes:e  U                       1. DECnet automatically caches and re-uses netserver processes,yY                          whereas there were well-known performance problems with spawningi'                          sub-processes.s  Z                       2. DECnet processes are detached processes, so you don't worry aboutV                          the effect of scripts consuming pooled quotas (e.g. bytlm) on1                          the HTTP server process.t  [                       3. Creation/connection with the DECnet server process is asynchronousra                          with respect to the server so other operations can proceed concurrently. ]                          Spawning is done in supervisor mode, blocking the server's operationgK                          until the child process is completely initialized.r  Y                       4. With DECnet, scripts can be configured to run on different nodes ,                          for load balancing.  U                       5. In addition to the standard 'WWWEXEC' object, you can createa\                          other 'persistent' DECnet objects that the server communicates with\                          as scripts. (this was implemented years before OpenMarket's FastCGI#                          proposal).T  Y                       6. CGI is not the be-all end-all of scripting.  The dialog phase ofgT                          OSU's scripting environment allows scripts to do things CGIZ                          is incapable of, such as ask the server to translate an arbitraryT                          path and not just what followed the script name in the URL.  Z                   People grouse all the time about the installation difficulties caused by]                   it's reliance on DECnet,  the reason shown above were cited to show that it -                   wasn't made so capricously.W  +                    . . .  some text omittedp               12-24  Scripting /  F            N                   David L. Jones               |      Phone:    (614) 292-6929?                   Ohio State Unviversity       |      Internet: ^                   2070 Neil Ave. Rm. 122       |               jonesd@kcgl1.eng.ohio-state.eduL                   Columbus, OH 43210           |               vman+@osu.edu  =                   Disclaimer: Dogs can't tell it's not bacon.g  J                The OSU server's DECnet scripting is not based on arbitraryH                considerations. This author does not disagree with any ofK                the concerns, and as may be seen from WASD documentation the L                design of WASD also directly addresses points 1, 3 and 5 withH                the use of persistant subprocesses and CGIplus. CertainlyK                DECnet-based scripting addresses the very legitimate point 4 L                (and also allows nodes with specific resources to participateI                without installing full HTTP server environments). For all G                practical purposes point 2 may be addressed by adjusting J                process quotas. Point 6 is only too true (possibly at leastD                until Java servers and servlets become ubiquitous :^)  $                Known Working Scripts  G                The following is a list of OSU-specific scripts that thehK                WASD v5.1 implementation has either been developed or testediK                against, and any installation notes or other WASD specifics.oH                The author would like to know of any OSU scripts the WASDA                emulation has problems or works successfully with.m  L                o  All of the scripts, etc. provided in the HT_ROOT:[SRC.OSU]+                   directory. These include:u                      o  cgi_symbols                     o  cgi-mailtog  !                   o  html_preproc                       o  set_dcl_env                     o  testcgi                     o  testforms                     o  tmail                      o  vmshelpgate                     o  webbook                  o  helpgate  F                   Comment out the Conan The Librarian mappings for theF                   "/help" path and provide the following in HTTPD$MAP:  N                                                               Scripting  12-25                 E                      # first make "/help" into a script specificatione5                      map /help* /htbin/helpgate/help*eJ                      # general rule mapping "/htbin" to OSU DECnet scripts<                      exec /htbin/* /0::"0=wwwexec"/cgi-bin/*O                      # map the non-script part of the path back to just "/help"p6                      pass /htbin/helpgate/help* /help*  L                   It is possible to support both HELP environments (althoughJ                   helpgate will not work without owning the "/help" path),J                   merely provide another mapping for Conan with a slightly.                   different path, for example:  '                      map /chelp /chelp/ 5                      script /chelp/* /cgi-bin/conan/*e  $                o  HTML pre-processor  K                   Yes, backward compatibility can be provided for those oldMG                   OSU .HTMLX files in your new WASD environment ;^) All:H                   that is needed is a file type mapping to the script in6                   the HTTPD$CONFIG configuration file.                        [AddType]I                      .HTMLX  text/html  /htbin/html_preproc  OSU SSI HTML.                  o  showtime                  o  mgmt               12.8.4 User Scriptsc  J                The WASD DECnet environment provides a simple mechanism forI                executing scripts within accounts other than the server's.sI                This allows configured users to write and maintain scriptseJ                within their own areas and have them execute as themselves.K                Both standard CGI and OSU scripting may be provided for with                 this facility.   H                Of course there is always a down-side. Be careful to whomK                this capability is granted. User scripts are executed within L                a user network-mode process created by DECnet. Script actionsL                cannot generally affect server behaviour, but they can accessK                any WORLD-readable and modify any WORLD-writable resource inIK                the system/cluster, opening a window for information leakage I                or mischievous/malicious actions. Script authors should be G                aware of any potential side-effects of their scripts and G                Web administrators vigilant against possible destructiveY8                behaviours of scripts they do not author.  H                User scripting is not enabled by default. To provide thisL                facility mapping rules into the user area must be provided inJ                much the same way as for user directories, See Section 8.6.               12-26  Scripting C  D            D                The "EXEC" rule provides a wildcard representation ofJ                users' script paths. As part of this mapping a subdirectoryJ                specifically for the web scripts should always be included.H                Never map users' top-level directories. For instance if aI                user's account home directory was located in the area WWW_ K                USER:[DANIEL] the following rule would potentially allow thenH                user DANIEL to provide scripts from the home subdirectoryJ                [.WWW.CGI-BIN] using the accompanying rules (first for CGI,'                second for OSU scripts):   D                   exec /~*/cgi-bin/* /0""::/www_user/*/www/cgi-bin/*O                   exec /~*/osu-bin/* /0""::"0=wwwexec"/www_user/*/www/cgi-bin/*h  L                Scripts located in these directories are accessable via paths%                such as the following:   '                   /~daniel/cgi-bin/testa  $                Explicit User Account  K                Using mapping rules it is possible to explicitly specify the M                user account for a particular script or scripts to be executed H                within. This may be useful if an application has quota orJ                other resource requirements that are desired to be withheldM                from the HTTP server account (i.e. it can provide a measure ofBF                isolation between the server and application accounts).  M                   exec /whatever-bin/* /0"WHATEVER"::/whatever_root/cgi-bin/* X                   script /dowhatever/* /0"WHATEVER"::/whatever_root/cgi-bin/dowhatever/*                  Proxy Access:  M                For each user account permitted to execute local scripts proxypH                access to that account must be granted to the HTTP server                account.s  F                Caution! If unsure of the security implications of thisI                action consult the relevant VMS system management securityh                documentation.   *                   $ SET DEFAULT SYS$SYSTEM!                   $ MCR AUTHORIZEE?                   UAF> ADD /PROXY <node>::HTTP$SERVER <account>   H                For example, the following would allow the HTTP server to@                execute scripts on behalf of the username DANIEL.  7                   UAF> ADD /PROXY 0::HTTP$SERVER DANIELe    N                                                               Scripting  12-27    -                         12.9 Java Scriptsa  E                Java classes may be used to perform CGI scripting with K                WASD. They may be designed as standard CGI scripts (with the M                inevitable latency of the class loading) or as CGIplus scripts =                (with the attendant benefit of lower latency).S  H                Note that Java scripts must always be mapped and executedJ                using the CGIplus path, however some can behave as standardJ                CGI scripts, exiting after responding to the request, whileG                others can persist, responding to multiple requests (seeyJ                Section 12.7). The CGIplus path is always necessary as JavaM                does not have direct access to a process' general environment, H                the traditional way of passing CGI variables, so the WASDI                implementation uses the CGIplus data stream to provide CGIu                information.   K                WASD provides a class to allow a relatively simple interface K                to the CGI environment for both GET and POST method scripts.uM                This and a collection of demonstration scripts may be found in 0                the HT_ROOT:[SRC.JAVA] directory.  L                Developed using the first-release JDK1.1 beta kit for OpenVMS                Alpha V7.1.                  Requirementsi  L                o  Ensure the Java class file type is mapped to the Java run->                   time in the HTTPD$CONFIG configuration file.  '                      [DclScriptRunTime] 6                      .CLASS  @CGI-BIN:[000000]JAVA.COM  E                o  The following content types are configured, also ini                   HTTPD$CONFIG.t                        [AddType]D                      .CLASS  application/octet-stream  -  Java class6                      .JAVA  text/plain  -  Java sourceD                      .JAR  application/octet-stream  -  Java archive@                      .PROPERTIES  text/plain  -  Java properties  G                o  The CGI-BIN logical includes the HT_ROOT:[JAVA] classp2                   directory in the server startup.  I                      $ JAVA_ROOT = F$TRNLNM("HT_ROOT") - ".]" + ".JAVA.]"t@                      $ DEFINE /SYSTEM /TRANSLATION=(CONCEALED) -G                               CGI-BIN 'EXE_ROOT','SCRIPT_LOCAL_ROOT', - 7                               'SCRIPT_ROOT','JAVA_ROOT'O               12-28  Scripting R  /            /             12.10 HTTP Persistant-State Cookiese  F                The WASD server is cookie-aware. That is, if the clientI                supplies a "Cookie:" request header line it is passed to a H                CGI script as "WWW_HTTP_COOKIE" CGI variable symbol. If aL                cookie is not part of the request this symbol does not exist.M                A script may use the "Set-Cookie:" response header line to set                 cookies.g  M                Here is a small demonstration of cookie processing using a DCLo                script.  /                <online hypertext demonstration>                                                                           N                                                               Scripting  12-29                     M             Chapter__13______________________________________________________a               Cacheo    I                WASD HTTPd provides an optional, configurable, monitorablenM                file data and revision time cache. File data, so that requestsvF                for documents can be fulfilled without reference to theK                underlying file system, potentially reducing request latencyeH                and more importantly improving overall server performanceJ                and system impact, and file revision time, so that requestsI                specifying an "If-Modified-Since:" header can also benefit                 from the above.  L                Note that it is a file-system cache. Only documents generatedH                from the file system are cached, not from any potentiallyH                dynamic sources, such as scripts, directory listings, SSIJ                documents, etc. The reason should be obvious. Only the fileM                system provides a reliable mechansim for ensuring the validityoL                of the cached data (i.e. has the original changed in some way                since loaded?)i  M                Files are cached according to mapped path (not necessarily the L                same path supplied with the request) and not by the file nameJ                represented by any path. This is a design decision targetedL                at avoiding any access to RMS before searching the cache. For@                example, the ambiguous reference to the directory                     /ht_root/o  K                may result in the following file being accessed (due to home                 page resolution)e  +                   HT_ROOT:[000000]HOME.HTML   G                and the contents returned to the client and consequently E                cached. Each time the path "/ht_root/" is subsequently H                requested it will be path hit and serviced from the cache1                entry without any recourse to RMS.e  L                Of course the same file may be requested with the unambigious                pathi  $                   /ht_root/home.html  L                which is completely different to the first instance, althoughH                ultimately accessing the same file. Hence one file may beE                cached multiple times against distinct paths. AlthoughCI                isolated instances of this are possible, the likelihood ofHI                significant resources being consumed in practice should be                 quite low.(  N                                                                    Cache  13-1 u  E            %                Why Implement Caching?-  F                Caching, in concept, attempts to improve performance byI                keeping data in storage that is faster to access than it's M                usual location. The performance improvement can be assessed in -                three basic ways; reduction of   H                o  response when accessing the data (latency and transfer                   time)e  2                o  processing involved (CPU cycles)  H                o  impact on the usual storage location (file system I/O)  J                This cache is provided to address all three. Where networksI                are particularly responsive a reduction in request latencysI                can often be noticable. It is also suggested a cache "hit"tH                may consume less CPU cycles than the equivalent access toI                the (notoriously expensive) VMS file system. Where serverssJ                are particularly busy or where disk subsystems particularlyG                loaded a reduction in the need to access the file systemeI                can significantly improve performance while simultaneously L                reducing the impact of the server on other system activities.K                The author's feeling is though, that for most VMS sites highpL                levels of hits are not a great concern, and for these cachingM                can easily be left disabled, particularly if the file system's ,                virtual I/O cache is enabled.  H                A comparison between cached and non-cached performance is&                provided in Chapter 14.  L                Why take so long to implement caching? (introduced in versionG                4.5) Well, WASD's intranet services are not particularly H                busy sites. This coupled with powerful hardware has meantL                performance has not been an overriding concern. However, thisJ                cache module came about because I felt like creating it andM                it was an obvious lack of functionality within the server, nota9                because WASD (the organisation) needed it.                   Terminology  /                This is what is meant when used.e  M                o  "hit" refers to a request path being found in cache. If thehM                   data is still valid the request can be supplied from cache.r  I                o  "load"ing the cache refers to reading the contents of ad)                   file into cache memory.   L                o  "valid" means that the file from which the cached data wasM                   originally read has not had it's revision date changed (theoJ                   implication being is the file contents have not changed.               13-2  Cachem e               1             13.1 Cache Suitability Considerations   L                A cache is not always of benefit! It's cost may outweigh it's                return.  L                Any cache's efficiencies can only occur where subsets of dataJ                are consistently being demanded. Although these subsets mayH                change slowly over time a consistent and rapidly changingE                aggregate of requests lose the benefit of more readily'G                accessable data to the overhead of cache management, duenG                to the constant and continuous flushing and reloading of,G                cache data. This server's cache is no different, it willfD                only improve performance if the site experiences someK                consistency in the files requested. For sites that have onlyeK                a small percentage of files being repeatedly requested it is J                probably better that the cache be disabled. The other majorJ                consideration is available system memory. On a system whereJ                memory demand is high there is little value in having cacheM                memory sitting in page space, trading disk I/O and latency forvL                paging I/O and latency. On memory-challenged systems cache is&                probably best disabled.  I                To help assessment of the cache's efficiency for any giventC                site monitor the administration menu's cache report.n  H                Two sets of data provide complementary information, cache1                activity and file request profile.   M                o  Activity information summarizes the cache search behaviour, 7                   in particular that of the hash table..  H                   The "searched" item, indicates the number of times theM                   cache has been searched. Most importantly, this may includepL                   paths that can never be cached because they represent non-M                   file requests (e.g. directory listings). Requests involving I                   scripts, and some others, never attempt a cache search.e  H                   The "hit" item, indicates the number of times the hashE                   table directly provided a cached path. This is very                    efficient.  I                   The "miss" item, indicates the number of times the hash I                   table directly indicated a path was not cached. This is 6                   decisive and is also very efficient.  L                   The "collision" item, indicates the number of times multi-M                   ple paths resolved to the same hash table entry. CollisionsnL                   require further processing and are far less efficient. TheM                   sub-items, "collision hits" and "collision misses" indicateHK                   the number of times that further processing resulted in ao0                   found or not-found cache item.  N                                                                    Cache  13-3                 I                   A large number of cache misses compared to searches maypK                   only indicate a large number of non-cachable requests and M                   so depending on that further datum is not of great concern. K                   A large proportion of collisions (say greater than 12.5%)hI                   is however, indicating either the hash table size needs I                   increasing (1024 should be considered a minimum) or the F                   hashing algorithm in the software need reviewing :^)  F                o  Files information summarizes the site's file request                   profile.  I                   With the "loads not hit" item, the count represents the J                   cumulative number of files loaded but never subsequentlyL                   hit. If this percentage is high it means most files loadedI                   are never hit, indicating the site's request profile isB2                   possibly unsuitable for caching.  J                   The item "hits" respresents the cumulative, total numberH                   of hits against the cumulative, total number of loads.K                   The percentage here can range from zero to many thousandseD                   of percent :^) with less than 100% indicating poorI                   cache performance and from 200% upwards better and goodDK                   performance. The items "1-9", "10-99" and "100+" show theeH                   count and percentage of total hits that occured when aM                   given entry had experienced hits within that range (e.g. if L                   an entry has had 8 previous hits, the ninth increments theJ                   "1-9" item whereas the tenth and eleventh increments the%                   "10-99" item, etc.)   D                   Other considerations also apply when assessing theK                   benefit of having a cache. For example, a high number and J                   percentage of hits can be generated while the percentageG                   of "loads not hit" could be in the also be very high.eI                   The explanation for this would be one or two frequently I                   requested files being hit while most others are loaded, L                   never hit, and flushed as other files request cache space.M                   In situations such as this it is difficult to judge whetheryJ                   cache processing is improving performance or just adding                   overhead.h                  Recommendation   L                Monitor the site's cache behaviour and adjust parameters from;                an assessment based on the guidelines above.   J                Again, the author's suggestion is, that for most VMS sites,K                high levels of access are not a great concern, and for these/3                caching can easily be left disabled.                  13-4  Cacheb v  p            )             13.2 Cache Content Validation   J                The cache will automatically revalidate the file data afterD                a specified number of seconds ([CacheValidateSeconds]G                configuration parameter), by comparing the original fileeK                revision time to the current revision time. If different theuI                file contents have changed and the cache contents declarediI                invalid. If found invalid the file transfer then continuesmL                outside of the cache with the new contents being concurrently'                reloaded into the cache.b  L                Cache validation is also always performed if the request usesM                "Pragma: no-cache" (i.e. as with the Netscape Navigator reloadAJ                function). Hence there is no need for any explicit flushingJ                of the cache under normal operation. If a document does notJ                immediately reflect any changes made to it (i.e. validationL                time has not been reached) validation (and consequent reload)5                can be "forced" with a browser reload.n  H                If a site's contents are relatively static the validationL                seconds could be set to an extended period (say 3600 seconds,G                one hour) and then rely on an explicit "reload" to forcee,                validation of a changed file.  H                The entire cache may be purged of cached data either fromJ                the server administration menu or using command line server3                control, as in the following example9  )                   $ HTTPD /DO=CACHE=PURGE   $             13.3 Cache Configuration  F                The cache is controlled using HTTPD$CONFIG file config-E                uration directives. A number of parameters control theGH                cache's behaviour. See the example configuration file HT_/                ROOT:[EXAMPLE]HTTPD$CONFIG.CONF.t  5                o  Cache enables and disables caching.C  H                o  CacheChunkKBytes sets the granularity of memory blocksM                   allocated to file data (in kilobytes). To reduce the numbersJ                   of, and possible blocks sizes of memory, being requestedL                   (potentially improving memory allocation performance) dataM                   allocated to cache is done in multiples of this chunk size.y  H                o  CacheEntriesMax and CacheTotalKBytesMax provide growthG                   limits to cache expansion. Maximum entries limits the L                   number of files loaded into the cache before entries beginH                   to be reused (flushing the original contents). MaximumK                   total kilobytes allocated to the cache provides a ceilingiK                   on the memory consumed. These parameters operate to limitpG                   each other (i.e. if one reaches it's limit before thepA                   other, the other will not grow further either).e  N                                                                    Cache  13-5 T  $            F                o  CacheFileKBytesMax provides a limit on file size (inH                   kilobytes). Files larger than the specified limit will"                   never be cached.  G                o  CacheFrequentHits and CacheFrequentSeconds attempt to I                   reduce unproductive reuse of cache entries by providing F                   the cache with some indication of what constitutes aG                   frequently hit entry. If it is frequently hit then itPI                   should not be immediately reused when there is a demandiF                   for cache space. The first parameter sets the numberH                   of hits an entry must sustain before being a candidateF                   for "CacheFrequentSeconds" assessment. If a file hasF                   been hit at least "CacheFrequentHits" times in totalJ                   and the last hit was within the number of seconds set byK                   "CacheFrequentSeconds" it will not be flushed and reused.PL                   If it has not been hit within the specified period it will                   be reused.  M                o  CacheHashTableEntries sets the size of the hash table, used M                   to rapidly index into the cached paths. Generally bigger isiL                   better (each entry consumes four bytes, hence 1024 entriesL                   consume 4096 bytes). Due to the hashing algorithm employedK                   the size should be in magnitudes of two (e.g. 1024, 2048,sL                   etc.), if not, the specified amount is rounded down to the-                   nearest (e.g. 1000 to 512).   G                o  CacheValidateSeconds The interval after which a cache H                   entry's original, content revision time is revalidatedK                   against the file's current revision time. If not the same I                   the contents are declared invalid and reloaded. SettingbM                   this to a greater period reduces disk I/O but revised filessH                   may not be obvious within an acceptable timer unless a8                   re-validation is forced with a reload.               13.4 Cache Control  E                The cache may be enabled, disabled and purged from theeG                server administration menu (see Chapter 11). In additionsK                the same control may be exercised from the command line (see #                Section 5.3.2) using   &                   $ HTTPD /DO=CACHE=ON'                   $ HTTPD /DO=CACHE=OFF )                   $ HTTPD /DO=CACHE=PURGE   L                If cache parameters are altered in the configuration file theK                server must be restarted to put these into effect. DisablingOG                the cache on an ad hoc basis (from menu or command line)uI                does not alter the contents in any way so it can merely belL                reenabled with use of the cache's previous contents resuming.               13-6  Cachee a  (            M                In this way comparisions between the two environments may morel                easily be made.                                                                                                N                                                                    Cache  13-7 o  e                M             Chapter__14______________________________________________________e               Server Performance    L                The server has a single-process, multi-threaded, asynchronousH                I/O design. On a single-processor system this is the mostL                efficient approach. On a multi-processor system it is limitedL                by the single process context (ignoring scripts which executeF                within their own context). An obvious improvement wouldG                be to have multi-processor threading or a pool of server I                processes, one per CPU, servicing requests. The latter maye5                be the approach of future refinements.t  K                The server has been tested with up to 30 concurrent requestsuL                originating from 6 different systems and continues to provideL                an even distribution of data flow to each client (albeit more                slowly :^)t  L                Test results are all obtained using the native Digital TCP/IPE                Services executable. The NETLIB image may provide very I                slightly lower results due to the additional NETLIB layer.e1                These results are indicative only!i  .                Simple File Request Turn-Around  L                Two sets of data are now reported, one with caching disabled,!                the other enabled.y  L                A series of tests using batches of 200 accesses were made andJ                the results averaged. The first test returned an empty fileJ                measuring response and file access time, without any actualH                transfer. The second and third requested files of 16K andI                64K characters respectively, testing performance with morenH                realistic scenarios. All were done using one and then ten#                concurrent requests.   I                The test system was a lightly-loaded AlphaServer 2100, VMSeH                v7.1 and DEC TCP/IP 4.2. No Keep-Alive: functionality wasM                employed so each request required a complete TCP/IP connectioneM                and disposal, although the WWWRKOUT utility (see Section 16.6)iJ                was used on the same system as the HTTP server, eliminatingL                actual network transport. DNS (name resolution) was disabled.0                The command lines are show below.        N                                                       Server Performance  14-1    c            P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -2                   /PATH="/ht_root/exercise/0k.txt"Q                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 - 2                   /PATH="/ht_root/exercise/0k.txt"P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -3                   /PATH="/ht_root/exercise/16k.txt"eQ                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -r3                   /PATH="/ht_root/exercise/16k.txt"dP                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -3                   /PATH="/ht_root/exercise/64k.txt" Q                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -y3                   /PATH="/ht_root/exercise/64k.txt"   H                The following results were derived using the v5.2 server.  6                                         Cache Disabled  M                ______________________________________________________________d4                                             DurationM                Response______Concurrent_____(seconds)______Requests/Second___c  =                0K            1              2.11           95r  >                0K            10             1.70           117  =                16K           1              3.04           66   =                16K           10             2.50           80i  =                64K           1              6.71           30t  M                64K___________10_____________5.10___________39________________c  5                                         Cache Enableda  M                ______________________________________________________________ 4                                             DurationM                Response______Concurrent_____(seconds)______Requests/Second___   >                0KB           1              0.95           210  >                0KB           10             0.82           244  >                16KB          1              1.86           107  >                16KB          10             1.60           125  =                64KB          1              4.74           43e  M                64KB__________10_____________4.25___________47________________p  I                Significantly, with both environments, throughput actuallysG                improves at ten concurrent requests (probably due to themG                latency of the serial TCP/IP connection/disconnection iniG                one-by-one, compared to several happening concurrently).t  $             14-2  Server Performance                 M                Note that the response and transfer benefits decline noticablytE                with file size (transfer time). The difference betweencG                cached and non-cached with the zero file size (no actualaG                data transfer involved) gives some indication of the rawoJ                difference in response latency, some 220% improvement. ThisK                is a fairly crude analysis, but does give some indication of "                cache efficiencies.    0                Simple File Request Transfer Rate  D                The simple text file request under similar conditionsF                indicates a potential transfer rate well in excess of 1I                Mbyte per second. (Remember, both client and server are oneJ                the same system, so the data, although being transported byM                TCP/IP networking, is not actually ending up out on a physicalhL                network.) This serves to demonstrate that server architectureD                should not be the limiting factor in file throughput.  O                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=10 - ;                   /PATH="/sys$common/sysexe/tnt$server.exe"aP                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=10 -;                   /PATH="/sys$common/sysexe/tnt$server.exe" O                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=10 -i=                   /PATH="/sys$common/sysexe/cxx$compiler.exe"lP                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=10 -=                   /PATH="/sys$common/sysexe/cxx$compiler.exe"r  H                The following results were derived using the v5.2 server.  5                                         Transfer Rate   M                ______________________________________________________________r9                                                  Duration M                Response______________Concurrent__(seconds)___Mbytes/Second___   @                2.4MB (4700 blocks)   1           6.4         3.8  @                2.4MB (4700 blocks)   10          5.7         4.2  @                6.9MB (13442 blocks)  1           40          1.7  M                6.9MB_(13442_blocks)__10__________17__________4.0_____________   K                Significantly, there were no dramatic drops in transfer rate K                between one and ten concurrent requests! In fact an increase                 in throughput!       N                                                       Server Performance  14-3 u  i            #             14.1 File Record Format   H                The server can handle STREAM, STREAM_LF, STREAM_CR, FIXEDK                and UNDEFINED record formats very much more efficiently than %                VARIABLE or VFC files.o  G                With STREAM, FIXED and UNDEFINED files the assumption is I                that HTTP carriage-control is within the file itself (i.e.rJ                at least the newline (LF), all that is required required byJ                browsers), and does not require additional processing. WithH                VARIABLE record files the carriage-control is implied andJ                therefore each record requires additional processing by theJ                server to supply it. Even with variable record files havingI                multiple records buffered by the HTTPd before writing themnK                collectively to the network improving efficiency, stream andnH                binary file reads are by Virtual Block and are written toH                the network immediately making the transfer of these very                 efficient indeed!  L                So significant is this efficiency improvement a module existsJ                to automatically convert VARIABLE record files to STREAM-LFM                when detected by the file transfer module. This is disabled byvK                default but the user is strongly encouraged to enable it andeL                to ensure that stream format files are provided to the serverG                by other hypertext generating and processing utilitites.a  +             14.2 Subprocess-based Scriptingh  L                Persistant-subprocesses are probably the most efficient solu-L                tion for child-process scripting under VMS. See Section 12.2.G                The I/O still needs to be on-served to the client by thei                server.  K                A simple performance evaluation shows the relative merits of J                the three scripting environments available. Two results areK                provided here. Both were obtained using the WWWRKOUT utility M                (see Section 16.6) accessing the same CGI test utility script, I                HT_ROOT:[SRC.CGIPLUS]CGIPLUSTEST.C, which executes in both L                standard CGI and CGIplus environments. A series of 200 accessJ                were made and the results averaged. The first test returnedG                only the HTTP header, evaluating raw request turn-aroundoH                time. The second test requested a body of 16K characters,H                again testing performance with a more realistic scenario.H                No Keep-Alive: functionality was employed so each requestK                required a complete TCP/IP connection and disposal, although K                the WWWRKOUT utility was used on the same system as the HTTPpL                server, eliminating actual network transport. DNSLookup (hostL                name resolution) was disabled. The test system was a lightly-I                loaded AlphaServer 2100, VMS v7.1 and DEC TCP/IP 4.2.) Thea,                command lines are show below:  $             14-4  Server Performance i               P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -0                   /PATH="/cgi-bin/cgiplustest?0"P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -1                   /PATH="/cgi-bin/cgiplustest?16"oQ                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -"4                   /PATH="/cgiplus-bin/cgiplustest?0"Q                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 - 5                   /PATH="/cgiplus-bin/cgiplustest?16"a  H                The following results were derived using the v5.2 server.  5                                         CGI Scripting3  M                ______________________________________________________________ 6                                               DurationN                Response______Concurrent_______(seconds)________Requests/Second  D                0KB           1                14.7             13.65  C                0KB           10               8.60             23.3   C                16KB          1                13.69            14.6   M                16KB__________10_______________8.68_____________23.0__________   7                                       CGIplus Scriptinge  M                ______________________________________________________________a6                                               DurationN                Response______Concurrent_______(seconds)________Requests/Second  C                0KB           1                4.20             47.6m  C                0KB           10               4.31             46.4h  C                16KB          1                4.32             46.3t  M                16KB__________10_______________4.39_____________45.6__________e  G                Again significantly, throughput actually improved at ten M                concurrent requests (probably due to the latency of the serial I                TCP/IP connection/disconnection in one-by-one, compared tor/                several happening concurrently).   G                Although these results are indicative only, they do show H                CGIplus to have a potential for improvement over standardJ                CGI in the order of 200%, a not inconsiderable improvement.J                Of course this test generates the output stream very simplyD                and efficiently and so excludes any actual processingH                time that may be required by a "real" application. If theK                script/application has a large activation time the reductionfL                in response latency could be even more significant (e.g. Perl2                scripts and RDBS access languages).  N                                                       Server Performance  14-5 t               '             14.3 DECnet-based Scriptinge  J                Using the same environment as when testing subprocess-basedH                CGI scripts (see above) this series of tests assesses theL                performance of the same script being executed using DECnet toM                manage the processes. DECnet Phase-IV was in use on a VMS v7.1t                 AlphaServer 2100.  P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -/                   /PATH="/decnet/cgiplustest?0" P                   $ WWWRKOUT /SIM=1 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -1                   /PATH="/decnet/cgiplustest?200"tQ                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 - /                   /PATH="/decnet/cgiplustest?0"sQ                   $ WWWRKOUT /SIM=10 /NOBREAK /NOVARY /NOHEAD /NOOUT /COUNT=200 -s1                   /PATH="/decnet/cgiplustest?200"g  H                The following results were derived using the v5.2 server,>                which now provides for DECnet connection reuse.  B                            DECnet CGI Script - No Connection Reuse  M                ______________________________________________________________n4                                             DurationM                Response______Concurrent_____(seconds)______Requests/Second___o  >                0KB           1              32.4           6.2  >                0KB           10             50.0           4.0  >                16KB          1              25.8           7.8  M                16KB__________10_____________22.8___________8.8_______________a  C                           DECnet CGI Script - With Connection Reusem  M                ______________________________________________________________ 4                                             DurationM                Response______Concurrent_____(seconds)______Requests/Second___e  ?                0KB           1              17.8           11.5   ?                0KB           10             11.9           16.8   ?                16KB          1              18.4           10.9   M                16KB__________10_____________12.2___________16.4______________       $             14-6  Server Performance o  n                             Some Observations  J                This section comments on non-persistant scripts (i.e. thoseH                that must run-up and run-down with each request - generalK                CGI behaviour). As may be seen from comparing the two tables L                connection reuse offers distinct benefits in reduced responseJ                times, consistency of response times and overall thoughput,H                showing a difference of some 200% over non-reuse (similarD                improvements were reported with the OSU 3.3a server).  D                With ten simultaneous and back-to-back scripts and noI                connection reuse many more network processes are generated L                than just ten. This is due to the NETSERVER maintenance tasksL                such as log creation and purging, activating and deactivatingK                the task, etc., adding latency into this script environment. M                The throughput was generally still lower than with subprocess- K                based scripting (11.5 against 14.7 for single requests, 16.8n9                against 23.3 for ten concurrent requests).o  J                While earlier versions cautioned on the use of DECnet-basedJ                scripting this has been relaxed somewhat through connection                reuse.                14.4 SSL  G                At this time there are no definitive measurements of SSLtF                performance (see Chapter 10), as work on an SSL versionG                of the WWWRKOUT utility has not yet been undertaken. OnesJ                might expect that because of the CPU-intensive cryptographyL                employed in SSL requests that performance, particularly whereJ                concurrent requests are in progress, would be significantlyK                lower. In practice SSL seems to provide more-than-acceptableT                responsiveness.               14.5 Suggestions  M                Here are some suggestions for improving the performance of thecM                server, listed in approximate order of significance. Note thatiI                these will have proportionally less impact on an otherwisel%                heavily loaded system.   G                1. Disable host name resolution (configuration parametergL                   [DNSLookup]). This can slow processing significantly. MostI                   log analysis tools can convert numeric addresses so DNSu<                   resolution is often an unnecessary burden.  J                   This can actually make a remarkable difference. The sameJ                   test provided very different throughputs with DNS lookupD                   enabled and disabled (v4.5 server, cache enabled).  N                                                       Server Performance  14-7               N                   ____________________________________________________________+                                    duration N                   _________________(seconds)________requests/second___________  6                   DNSLookup ON     6.30             32  N                   DNSLookup_OFF____0.95_____________210_______________________  D                2. Ensure served files are not VARIABLE record formatH                   (see above). Enable STREAM-LF conversion using a valueE                   such as 250 (configuration parameter [StreamLF] ando#                   [StreamLFpaths]).   H                3. Use persistant-subprocess DCL/scripting (configuration-                   parameter [ZombieLifeTime])   @                4. Use CGIplus-capable scripts whenever possible.  C                5. Enable caching (configuration parameter [Cache]).   F                6. Disable logging (configuration parameter [Logging]).  L                7. Set the HTTP server process priority higher, say to 6 (use0                   startup qualifier /PRIORITY=).  K                8. Reduce to as few as possible the number of mapping rules.o  L                9. Use a pre-defined log format (e.g. "common", configuration)                   parameter [LogFormat]).r  G               10. Disable request history (configuration parameter [Re- !                   questHistory]).   F               11. Disable activity statistics (configuration parameter"                   [ActivityDays]).                                $             14-8  Server Performance _  _                M             Chapter__15______________________________________________________                HTTPd Web Update    M                The Update facility allows Web documents and file environments J                to be administered from a standard browser. This capabilityM                is available to Web administrator and user alike. Availability M                and capability depends on the authorization environment within                 the server.  H                It should be stressed that this is not designed as a fullK                hypertext administration or authoring tool, and for document D                preparation relies on the editing capabilities of theH                <TEXTAREA> widget of the user's browser. It does however,M                allow ad-hoc changes to be made to documents fairly easily, as K                well as allowing documents to be deleted, and directories too&                be created and deleted.  I                Consult the current Update documentation for usage detail.4  &                <online hypertext link>  '                Update Access Permission   G                If SSL is in use (see Chapter 10) then username/passwordeM                privacy of the authorization environment is inherently secured G                via the encrypted communications. To restrict web updatesI                functionality to this secure environment add the followings3                to the HTTPD$MAP configuration file:y  ;                   /upd/*  "403 Access denied."  ![sc:https]   G                Of course, the user must have write (POST/PUT) access toeI                the document or area on the server (i.e. the path) and the K                server account have file system permission to write into the                  parent_directory.  G                The server will report "Insufficient privilege or objecttK                protection violation ... /path/document" if it does not havet@                file system permission to write into a directory.  K                Also see Section 9.7 for information on write access controle&                for the server account.        N                                                         HTTPd Web Update  15-1                     M             Chapter__16______________________________________________________N               UtilitiesN    M                Foreign commands for external utilities (and the HTTPD control K                functionality) will need to be assigned in the adminstration E                users' LOGIN.COM. Alternatives should be used when the A                environment supported through NETLIB. For example:   *                   HTTPD == "$HT_EXE:HTTPD"2                   !HTTPD == "$HT_EXE:HTTPD_NETLIB"0                   HTTPDMON == "$HT_EXE:HTTPDMON"8                   !HTTPDMON == "$HT_EXE:HTTPDMON_NETLIB"0                   STREAMLF == "$HT_EXE:STREAMLF"0                   WWWRKOUT == "$HT_EXE:WWWRKOUT"8                   !WWWRKOUT == "$HT_EXE:WWWRKOUT_NETLIB"               16.1 Echo Facility  J                Ever had to go to extraordinary lengths to find out exactlyE                what your browser is sending to the server? The server4H                provides a request echo facility. This merely returns theJ                complete request as a plain-text document. This can be usedJ                for for checking the request header lines being provided byJ                the browser, and can be valuable in the diagnosis of POSTed                forms, etc.  J                This facility must be enabled through a mapping rule entry.  (                   script /echo/* /echo/*  G                It may then be used with any request merely by insertingSM                "/echo" at the start of the path, as in the following example.   ?                   http://wasd.dsto.defence.gov.au/echo/ht_root/l               16.2 Where Facility   H                Need to locate where VMS has the HTTPd files? This simpleI                facility maps the supplied path then parses it to obtain aeJ                resulting VMS file specification. This does not demonstrate0                whether the path actually exists!  J                This facility must be enabled through a mapping rule entry.  *                   script /where/* /where/*  N                                                                Utilities  16-1 i               G                It may then be used with any request merely by inserting E                "/where" at the start of the path, as in the followingn                example.   @                   http://wasd.dsto.defence.gov.au/where/ht_root/               16.3 Xray Facility  L                The Xray facility returns a request's complete response, bothK                header and body, as a plain text document. Being able to seeuK                the internals of the response header as well as the contentseL                of the body rendered in plain text can often be valuable when'                developing scripts, etc.   J                This facility must be enabled through a mapping rule entry.  (                   script /Xray/* /Xray/*  G                It may then be used with any request merely by inserting-M                "/xray" at the start of the path, as in the following example.t  ?                   http://wasd.dsto.defence.gov.au/xray/ht_root/n  !             16.4 StreamLF Utility   L                This utility converts VARIABLE format files to STREAM_LF. TheM                WASD HTTPd server access STREAM_LF files in block/IO-mode, fariJ                more efficiently that the record-mode required by variable-L                record format files. Use "STREAMLF/HELP" for some basic usage                information.e  H                NOTE  This server can also be configured to automaticallyH                convert any VARIABLE record format files it encounters to                STREAM_LF.i               16.5 HTTPd Monitor  K                The HTTP server may be monitored using the HTTPDMON utility. I                This utility continuously displays a screen of information )                comprising three sections:b  %                1. Process InformationaJ                   HTTPd process information includes its up-time, CPU-timeH                   consumed (excluding any subprocesses), I/O counts, and%                   memory utilization.s  !                2. Server CountersWI                   The server counters keep track of the total connectionsrM                   received, accepted, rejected, etc., totals for each request H                   type (file transfer, directory listing, image mapping,                   etc.).               16-2  Utilitiesa                                  3. Latest RequestE                   This section provides the response status code, and J                   some transaction statistics, the service being accessed,K                   originating host and HTTP request. Note that long requestBK                   strings may be truncated (indicated by a bolded elipsis).g  I                The following shows example output (after overnight server                 testing):  ^                  Port: 80    HTTPDMON v1.6.0 AXP (HTTPd v5.1)   Saturday,  4-JUL-1998 09:35:30  D                  Process: HTTPd:80  PID: 20200467  User: HTTP$SERVERG                       Up: 0 13:52:33.62  CPU: 0 06:21:11.35  Restart: 0sY                  Pg.Flts: 2192  Pg.Used: 6%  WsSize: 9280 (4640kB)  WsPeak: 5888 (2944kB) V                      AST:   13/600   BIO:    4/512   BYT:      0/122016  DIO:    2/512V                      ENQ:    2/600   FIL:    4/100   PRC:      3/50       TQ:    6/200  \                  Connect: 365756  SSL: 0 (0%)  Acc/Rej/Bsy: 365756 / 0 / 0  Cur/Peak: 0 / 15U                    Parse: 378338  Error: 0  Forbidden: 0  Redirect-Rem/Loc: 0 / 12582 F                   DELETE: 0  GET: 341316  HEAD: 37022  POST: 0  PUT: 0M                    Admin: 0  Cache: 8 / 113449 (0)  DECnet-CGI/OSU: 0 - 0 / 0 a                      DCL: 87408  CGI/plus: 50475 / 50437 (50202)  Spawn/Cur: 1767 / 3  Dir: 25237_V                     File: 12591 (0)  IsMap: 0  Menu: 0  Put: 0  SSI: 63093  Upd: 37856  T                      1xx: 0  2xx: 328403  3xx: 0  4xx: 25200  5xx: 12152  (0 errors)@                       Rx: 30,002,610  Tx: 2,950,147,996  (bytes)  V                     Time: 04 08:35:15  Status: 200  Rx: 80  Tx: 24822  Duration: 2.003=                  Service: http://gamma.dsto.defence.gov.au:80 E                     Host: gamma.dsto.defence.gov.au (131.185.250.202) /                  Request: GET /tree/ht_root/*.*a  D                The "/HELP" qualifier provides a brief usage summary.  H                This information is, in part, obtained from the following                logical names:r  "                o  HTTPDport$COUNT1  "                o  HTTPDport$COUNT2                  o  HTTPDport$PID,  #                o  HTTPDport$REQUESTt  G                The server counter values are carried over when a server G                (re)starts (provided the system has stayed up). To reseteK                the counters use the on-line server administration menu (seee                Chapter 11).a  J                If [DNSlookup] is disabled for the HTTP server the HTTPDMONJ                utility attempts to resolve the numeric address into a hostI                name. This may be disabled using the /NORESOLVE qualifier.n  N                                                                Utilities  16-3                 -             16.6 Server Workout (stress-test)t  K                The WWWRKOUT ("World Wide Web Workout") utility exercises aniH                HTTP server, both in the number of concurrent connectionsF                maintained and in the number of back-to-back sequentialI                connection requests and data transfers. A native UCX image 8                and a separate NETLIB image are provided.  H                This utility can be used to stress-test the WASD VMS HTTPG                server (or any other), or to make comparisons between itTJ                and other servers. When stress-testing a server, evaluatingG                performance or just using it to try and break a test-bedsH                server, it is best used from multiple, autonomous systems                concurrent.  H                It sets up and maintains a specified number of concurrentK                connections to a server. It reads a buffer of data from each/J                connection in turn, where data is waiting (does not block),I                until the document transfer is complete and the connectioneE                closed by the server. It then closes the local end andcI                immediately reuses the now-free socket to initiate another_L                sequence. If enabled (it is by default), the utility attemptsJ                to reflect the real-world in varying the data transfer rateG                for each connection, by setting the number of bytes read I                during each read loop differently for each connection. AllK,                transfered data is discarded.  F                The data transfer rate for each connection is displayedH                at connection close. It is by default it is the effectiveJ                transfer rate, that is the rate from opening the connectionK                to closing it, and so includes request processing time, etc. J                If the "/NOEFFECTIVE" qualifier is employed it measures the0                document data transfer rate only.  F                Although a single document path may be specified on theJ                command line it is preferable to supply a range of documentK                paths, one per line in a plain text file. Each document path J                and/or type specified should be different to the others, toM                exercise the server and file system cache. Any number of pathssL                may be specified in the file. If the file is exhausted beforeL                the specified number of connections have been established theK                file contents are recycled from the first path. If a path oreL                a file of paths is not specified the utility just continually-                requests the welcome document.c  K                To assess a server's total throughput choose paths that leadeK                to large documents (> 50K), where the overhead of connection-F                setup, rule processing and transfer initiation are lessI                significant than the data transfer itself. The buffer sizeeM                variation functionality should be disabled using the "/NOVARY"aK                qualifier when assessing data transfer rates. ResponsivenessoE                is better assessed using small documents (< 2K), where                16-4  Utilitiess                 G                the overhead of the non-data-transfer activities is more                 significant.r  E                WWWRKOUT [server_host_name[:port]] [path] [qualifiers]e  J                o  /[NO]BREAK will randomly break a small number of connec-M                   tions during the data transfer (tests server recovery under &                   those circumstances)  K                o  /BUFFER= number of bytes to be read from server each time K                   (default is 1024, will be modified by the default "/VARY"t                   qualifier)  M                o  /COUNT= total number of connections and requests to be done "                   (default is 100)  L                o  /[NO]EFFECTIVE measures data transfer rate from request toJ                   close (if "/NOEFFECTIVE" is applied the rate is measured+                   during data transfer only.  B                o  /FILEOF= file name containing paths to documents  7                o  /HELP display brief usage information   /                o  /OUTPUT= file name for outpute  @                o  /PATH= single path to document to be retrieved  F                o  /PORT= IP port number of HTTP server (default is 80)  0                o  /SERVER= HTTP server host name  M                o  /SIMULTANEOUS= number of simultaneous connections to be sety4                   up at any one time (default is 10)  G                o  /[NO]VARY varies the size of the read buffer for eachc.                   connection (default is vary)                  Examples:                     $ WWWRKOUT=                   $ WWWRKOUT www.server.host "/web/home.html" C                   $ WWWRKOUT www.server.host:8080 /FILEOF=PATHS.TXT b                   $ WWWRKOUT /SERVER=www.server.host /PORT=8080 /NOBREAK /NOVARY /FILEOF=PATHS.TXTX                   $ WWWRKOUT www.server.host:8080 /FILEOF=PATHS.TXT /NOEFFECTIVE /NOVARY_                   $ WWWRKOUT www.server.host /FILEOF=PATHS.TXT /COUNT=500 /SIMUL=20 /BUFFER=512c  D                The "/HELP" qualifier provides a brief usage summary.    N                                                                Utilities  16-5