<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(New to WASD? Start Here!\chapter_newbies)

<P> This chapter provides a quick guide to getting your WASD package
installed, configured and serving. This covers initial installation.

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Unzip Package\BOLD)

<P> Install the files following the guidelines in <REFERENCE>(chapter_install). 
<EMPHASIS>(Note\BOLD) that more than one archive may be needed
(<REFERENCE>(head_setup_source_object)).

<LE> <EMPHASIS>(INSTALL Package\BOLD)

<P> Server installation is performed using the INSTALL.COM procedure
(<REFERENCE>(head_setup_install)).

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Build Package - \BOLD)
Compile and link, or just link supplied object files to produce VMS
executables for the system's version of VMS.

<LE> <EMPHASIS>(Check Package - \BOLD)
Check basic operation of the package (<REFERENCE>(head_quick_check)).

<LE> <EMPHASIS>(Create Server and Scripting Accounts - \BOLD)
Create two independent accounts, one for executing the server, the other for
executing scripts (<REFERENCE>(head_server_account)).  If quotas are enabled on
the target disk provides an ambit allocation for these accounts.  Review this
at some stage.

<LE> <EMPHASIS>(Set Package Security - \BOLD)
This sections traverses the newly installed tree and sets all package
directories and files to required levels of access
(<REFERENCE>(head_config_secure)).

<LE> <EMPHASIS>(Copy Support and Configuration Files - \BOLD)
Copy the example server support and configuration files
(<REFERENCE>(head_account_support_files)).

<LE> <EMPHASIS>(Install Scripts - \BOLD)
Selectively copy groups of scripts from package build directories into the
scripting directories.

<ENDLIST>

<LE> <EMPHASIS>(Configure Package\BOLD)

<P> Following the execution of the INSTALL.COM procedure the package should
require only minor, further configuration.

<P> <EMPHASIS>(Initially\BOLD) two files may require alteration.

<LIST>(NUMBERED)

<LE> The startup file, possibly to set the local HTTPD$GMT logical.  Consider
using the STARTUP_LOCAL.COM file for other site-specific requirements
(<REFERENCE>(head_account_support_files)).

<LE> The only configuration that should require immediate attention will be to
the mapping rules (<REFERENCE>(chapter_mapping_rule)).

<ENDLIST>

<P> <EMPHASIS>(More generally\BOLD) server runtime configuration involves
the considerations discussed in <REFERENCE>(head_organ_site) along with the
following aspects:

<LIST>(UNNUMBERED)

<LE> Configuring the HTTP server run-time characteristics
(<REFERENCE>(chapter_config)).

<LE> Mapping request paths to the VMS file system, and to other things such as
scripts (<REFERENCE>(chapter_mapping_rule)).

<LE> Customizing some messages (or all if non-English language environment)
(<REFERENCE>(chapter_msg_config)).

<LE> Establishing an authentication and authorization environment
(<REFERENCE>(chapter_authorization)).
<ENDLIST>

<LE> <EMPHASIS>(Start Server\BOLD)

<P> Execute the startup procedure.  Get your browser and connect!

<LE> <EMPHASIS>(Find Out What's Wrong :^<OPAREN>\BOLD)

<P> Of course <EMPHASIS>(something) will not be right!  This can happen with
the initial configuration and sometimes when changing configuration.  The
server provides information messages in it's run-time log, look in the
HT_ROOT:[LOG_SERVER] directory.

<P> Remember, the basic installation's integrity can always be checked
as described in
<COMMENT>(HTML/OFF)
<REFERENCE>(chapter_install),
<COMMENT>(HTML/ON)
<REFERENCE>(head_quick_check).

This uses the configuration files from the [EXAMPLE] directory, so provided
these have not been altered the server should execute in
<EMPHASIS>(demonstration mode) correctly.

<P> Can't resolve it? See <REFERENCE>(head_setup_problems).

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Installation and Update\chapter_install)

<P> The WASD package and updates will always be distributed as ZIP archives.

<P> It generally pays to use the latest version of VMS UNZIP available. 
Archives will contain a comment about the minimum version required, check that
as described in the next paragraph. To show the version of the current UNZIP
utility, use

<CODE_EXAMPLE>
  $ UNZIP -v
<ENDCODE_EXAMPLE>

<P> The ZIP archive will contain brief installation instructions.  Use the
following command to read this and any other information provided.

<CODE_EXAMPLE>
  $ UNZIP -z device:[dir]archive.ZIP
<ENDCODE_EXAMPLE>

<P> It is recommended to check the integrity of, then list the contents of, the
archive before UNZIPping.

<CODE_EXAMPLE>
  $ UNZIP -t device:[dir]archive.ZIP
  $ UNZIP -l device:[dir]archive.ZIP
<ENDCODE_EXAMPLE>

<HEAD>(Paranoid?\head_setup_paranoid)

<P> <EMPHASIS>(Are you sure you got what you thought you did?\BOLD) 
Not keen on importing even one trojan into your site?  You may wish to confirm
the archive you are about to install is what was originally released.  The
MD5DIGEST utility may ease your (now) troubled mind.  See
<REFERENCE>(head_md5digest).

<HEAD>(Installation UNZIP\head_unzip_install)

<P> For complete package distributions the archive will contain the complete
directory tree.  Hence to install or do a complete update it is necessary to
SET DEFAULT into the top-level directory of the disk the package is to
be installed on.

<CODE_EXAMPLE>
  $ SET DEFAULT device:[000000]
<ENDCODE_EXAMPLE>

<P> A complete installation/update will have the structure:

<CODE_EXAMPLE>
   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.
    This is free software, and you are welcome to redistribute it
    under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
   
     *  Complete v4.3.0 package.
     *  $ SET DEFAULT device:[000000]
     *  $ UNZIP "-V" device:[dir]HTROOT430.ZIP
   
    VMS file attributes saved ... use UnZip 5.n+ on OpenVMS
   
    Archive created 1-AUG-1997

    Length    Date    Time    Name
    ------    ----    ----    ----
         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/
      5360  07-30-97  13:23   ht_root/changes.html
         0  07-30-97  14:15   ht_root/doc/
   .
   .
   .
     16896  07-30-97  09:23   ht_root/vax/wwwrkout.exe
    ------                    -------
  19109754                    996 files
<ENDCODE_EXAMPLE>

<HEAD>(Update UNZIP\head_unzip_update)

<P> For updates to portions of the package only the tree below HT_ROOT:[000000]
is provided, hence it is necessary to SET DEFAULT to HT_ROOT:[000000] before
UNZIPping.

<CODE_EXAMPLE>
  $ SET DEFAULT HT_ROOT:[000000]
<ENDCODE_EXAMPLE>

<P> An update will have the structure:

<CODE_EXAMPLE>
   Archive:  HT_ROOT:[000000]HTROOT430_UPD_01.ZIP;1
   
    WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 Mark G.Daniel.
    This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
    This is free software, and you are welcome to redistribute it
    under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
   
     *  Mostly minor updates to scripts and utilities for the v4.3.0 package.
     *  A couple nuisance-value-bugs have also been fixed in these.
     *  SDM2HTM can now generate <LITERAL>(<FRAMESET>) documents (see [DOC]*.COM)
   
    VMS file attributes saved ... use UnZip 5.n+ on OpenVMS
   
    Archive created 6-AUG-1997
   
    Length    Date    Time    Name
    ------    ----    ----    ----
     42957  08-04-97  07:57   src/utils/wwwrkout.c
     59664  08-04-97  07:57   src/utils/obj_axp/wwwrkout.obj
     19674  08-04-97  07:57   src/utils/obj_vax/wwwrkout.obj
     26624  08-04-97  07:57   axp/wwwrkout.exe
   .   
   .   
   .   
     45056  08-05-97  11:02   vax/sdm2htm.exe
       617  08-05-97  09:23   doc/all_docs_framed.com
        44  08-05-97  09:23   doc/all_docs_not_framed.com
       544  08-05-97  09:22   doc/readme.html
    ------                    -------
   2773107                    90 files
<ENDCODE_EXAMPLE>

<HEAD>(Existing Installations\head_install_existing)

<P> When installing either a full archive or to a lesser extent an update
archive <QUOTE>(over the top) of an existing installation consider the
following.

<LIST>(UNNUMBERED)

<LE> Some <EMPHASIS>(insurance) on the directory tree is recommended in case
the update should fail or otherwise be unusable or problematic (of course, this
is good advice whenever about to make major changes to anything!)  This may be
in the format of a regular site backup, special pre-update backup, or special
pre-update ZIP archive of the directory tree.  The latter two could be
accomplished using commands similar to the following:

<CODE_EXAMPLE>
  $ BACKUP HT_ROOT:[000000...] location:HTROOT.BCK/SAVE/VERIFY

  $ ZIP "-V" location:HTROOT.ZIP device:[HT_ROOT...]*.*
  $ ZIP "-T" location:HTROOT.ZIP
<ENDCODE_EXAMPLE>

<CP> If using ZIP then ensure that a previous version of the target ZIP file
does not already exist.  If it does then that version is updated, a new
version is not created.

<LE> For existing files a new version is created (the first time this is about
to occur the UNZIPper requests permission - either <QUOTE>(A) for all, or
<QUOTE>(y) or <QUOTE>(n) or a per-file basis).

<LE> It is possible to <EMPHASIS>(selectively) extract portions of a tree if
something has become damaged.  This would be accomplished by specifying what
needs to be extracted from the archive (instead of the default
<EMPHASIS>(all)), as illustrated by the following example where only the Alpha
object modules are extracted.

<CODE_EXAMPLE>
  $ SET DEFAULT device:[000000]
  $ UNZIP "-V" device:[dir]archive-AXP.ZIP ht_root/src/httpd/obj_axp/*.*
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD1>(Source Archive, Object Module Archives\head_setup_source_object)

<P> The complete package, source code, documentation, examples, etc., is
provided in a single main archive.  Installation and other build procedures
allow the entire package to be compiled and linked from this if prefered.  This
requires a later version of DEC C (preferably v5.<EMPHASIS>(n) or greater). 
VAX C is no longer supported.

<P> In addition, for those unable or not wishing to fully build the
distribution, two other platform-specific archives are available, AXP (Alpha)
and VAX, containing a complete set of object modules, allowing the package to
be built via a link operation only.

<P> If a complete build is planned then only the main archive is required.  If
a link-only build then an additional archive for each architecture must be
UNZIPped as described above.  This applies to both full installations and
subsequent updates.  The archives will be clearly identified with the
architecture type, as illustrated in this example.

<CODE_EXAMPLE>
  $ UNZIP "-V" device:[dir]archive-AXP.ZIP
  $ UNZIP "-V" device:[dir]archive-VAX.ZIP
<ENDCODE_EXAMPLE>

<NOTE>
The WASD distribution and package organisation fully supports
mixed-architecture clusters (AXP, IA64 and/or VAX in the one cluster) as one
integrated installation.
<ENDNOTE>

<HEAD1>(Accessable Volume\head_setup_volume)

<P> Unlikely as it might be to install the package on a private or otherwise
protected volume, the server and scripting accounts being unprivileged in
themselves, require access sufficient to read, write and delete files from the
volume (disk).  The following illustrates how to check this and what the
protections should look like.  Generally any device that an unprivileged user
can use the server accounts can use.

<CODE_EXAMPLE>
  $ SHOW SECURITY /CLASS=VOLUME $1$DKA0:

  ALPHASYS object of class VOLUME
       Owner: [1,1]
       Protection: (System: RWCD, Owner: RWCD, Group: RWCD, World: RWCD)
       Access Control List: <LITERAL>(<empty>)
<ENDCODE_EXAMPLE>

<HEAD1>(ODS-5 Volumes\head_setup_ods5)

<P> The WASD package has been successfully installed on and used from ODS-5
(extended file specification) volumes.  Note that the installation procedures
and file system organisation of the package tree has been designed for ODS-2
compliance.  As long as this is maintained there should be no issues with
actually having it resident on an extended file system compliant volume.  (Of
course the issue of installing WASD on an ODS-5 volume is completely separate
from it's ability to serve the contents of an ODS-5 volume!)

<HEAD1>(Package Directory Structure\head_setup_directories)

<P> The package directories and content are organised as follows.  Note that
only some of these can be accessed by the server (and therefore seen in
server-generated directory listings) due to directory and file protections
(<REFERENCE>(head_config_secure_package)).

<P>
<CENTER_LINE>(<EMPHASIS>(Package Directory Structure\BOLD))
<TABLE>
<TABLE_SETUP>(2\15)
<TABLE_HEADS>(Directory\Description)
<TABLE_ROW>([AXP-BIN]\Alpha executable script files)
<TABLE_ROW>([AXP]\Alpha build and utility area)
<TABLE_ROW>([CGI-BIN]\architecture-neutral script files)
<TABLE_ROW>([DOC]\package documentation)
<TABLE_ROW>([EXAMPLE]\package examples)
<TABLE_ROW>([EXERCISE]\package test files)
<TABLE_ROW>([HTTP$NOBODY]\scripting account default home area)
<TABLE_ROW>([HTTP$SERVER]\server account default home area)
<TABLE_ROW>([IA64-BIN]\IA64 executable script files)
<TABLE_ROW>([IA64]\IA64 build and utility area)
<TABLE_ROW>([INSTALL]\installation, update and security procedures)
<TABLE_ROW>([LOCAL]\site configuration files)
<TABLE_ROW>([LOG]\site access logs)
<TABLE_ROW>([LOG_SERVER]\server process (SYS$OUTPUT) logs)
<TABLE_ROW>([RUNTIME]\graphics, help files, etc.)
<TABLE_ROW>([SCRATCH]\working file space for scripts)
<TABLE_ROW>([SCRIPT]\example architecture-neutral scripts)
<TABLE_ROW>([SRC]\package source files)
<TABLE_ROW>([STARTUP]\package startup procedures)
<TABLE_ROW>([VAX-BIN]\VAX executable script files)
<TABLE_ROW>([VAX]\VAX build and utility area)
<ENDTABLE>

<HEAD1>(Installation DCL Procedure\head_setup_install)

<P> The INSTALL.COM procedure assists with the first installation of
WASD.  It provides a  <EMPHASIS>(vanilla) setup, using the standard directories
and  account environment described in this document.  All sections prompt
before performing any action and generally default to <QUOTE>(no).  Read the
information and questions carefully! 

<P> After UNZIPping the package do the following:

<CODE_EXAMPLE>
  $ SET DEFAULT device:[HT_ROOT]
  $ @INSTALL
<ENDCODE_EXAMPLE>

<P> It performs the following tasks:

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Build Executables - \BOLD)
Either compile sources and link, or just link package object code to produce
images for the local version of VMS.   If the system has a suitable SSL toolkit
the installer is requested whether an SSL enabled version be built.

<LE> <EMPHASIS>(Check Package - \BOLD)
Executes a procedure that runs up the HTTPd in demonstration mode.  Allows
evaluation/checking of the basic package (<REFERENCE>(head_quick_check)).

<LE> <EMPHASIS>(Create Server and Scripting Accounts - \BOLD)
Create two, independent accounts, one for executing the server, the other for
executing scripts (<REFERENCE>(head_server_account)).  If quotas are enabled on
the target disk provides an ambit allocation for these accounts.  Review this
at some stage.

<LE> <EMPHASIS>(Set Package Security - \BOLD)
This section traverses the newly installed tree and sets all package
directories and files to required levels of access.  For directory settings see
<REFERENCE>(head_config_secure_package).           

<LE> <EMPHASIS>(Copy Support and Configuration Files - \BOLD)
Copy the example server support and configuration files
(<REFERENCE>(head_account_support_files)).

<LE> <EMPHASIS>(Install Scripts - \BOLD)
Selectively copy groups of scripts from package build directories into the
scripting directories.

<ENDLIST>

<P> Support files to consider when customizing startup, etc. (see
<REFERENCE>(head_account_support_files) for further detail):

<LIST>(SIMPLE)
<LE> STARTUP.COM
<LE> STARTUP_LOCAL.COM
<LE> STARTUP_SERVER.COM
<ENDLIST>

<HEAD1>(Update DCL Procedure\head_setup_update)

<P> The UPDATE.COM procedure assists with subsequent updates of WASD. 
It assumes a <EMPHASIS>(vanilla) setup, using the standard directories and
account  environment described in this document.  All sections prompt before
performing any action and generally default to <QUOTE>(no).  Read the questions
carefully!

<P>Of course it is best (read mandatory) for the server to be shut down during
an update!

<CODE_EXAMPLE>
  $ HTTPD/DO=EXIT/ALL
<ENDCODE_EXAMPLE>

<P> After UNZIPping the updated package do the following:

<CODE_EXAMPLE>
  $ @UPDATE
<ENDCODE_EXAMPLE>

<P> It provides the following functions:

<LIST>(NUMBERED)

<LE> <EMPHASIS>(Build Executables - \BOLD)
Either compile sources and link, or just link package object code to produce
images for the local version of VMS.  If the system has a suitable SSL toolkit
the installer is requested whether an SSL enabled version be built.

<LE> <EMPHASIS>(Server Quick-Check - \BOLD)
Executes a procedure that runs up the HTTPd in demonstration mode.  Allows
evaluation/checking of the basic package (<REFERENCE>(head_quick_check)).

<LE> <EMPHASIS>(Server Support/Configuration Files - \BOLD)
Copies changed example HTTP server configuration and support files from the
[EXAMPLE] directory to the [HTTP$SERVER], [LOCAL] and [STARTUP] directories. 

<LE> <EMPHASIS>(Update Scripts - \BOLD)
Selectively copy groups of scripts from package build directories into the
scripting directories.

<LE> <EMPHASIS>(Reapply Package Security - \BOLD)
This section traverses the updated tree and sets all package directories and
files to required levels of access.  For directory settings see
<REFERENCE>(head_config_secure_package).

<LE> <EMPHASIS>(Post-Update Cleanup - \BOLD)
Prompts for permission to execute the post-update procedure described below.

<LE> <EMPHASIS>(Purge Files - \BOLD)
Prompts for permission to purge the entire HT_ROOT:[000000...] tree.

<ENDLIST>

<P> If declined during the update procedure the post-update steps 6 and 7 can
be performed at any subsequent time using

<CODE_EXAMPLE>
  $ SET DEFAULT HT_ROOT:[000000]
  $ @UPDATE CLEANUP
  $ PURGE [...]
<ENDCODE_EXAMPLE>

<HEAD1>(Quick-Check\head_quick_check)

<P> Once installed or updated it is possible to check the basic package at any
time using the [INSTALL]DEMO.COM procedure.  This invokes the server image
using the /DEMO qualifier allowing some behaviours not possible under general
use.  Follow the displayed instructions.  Basically, the server should start
and become reachable via port number 7080. So, to test its availability, using
your prefered browser enter the URL listed on line starting with
<QUOTE>(%HTTPD-I-SERVICE) and the WASD welcome page should be displayed.

<CODE_EXAMPLE>
  $ @HT_ROOT:[INSTALL]DEMO.COM

                         *******************************
                         *  WASD PACKAGE DEMONSTRATOR  *
                         *******************************
  
  If you have the SSL package then just add "SSL" as parameter 1!
  
  When finished using demonstrator abort server execution using control-Y
  (a subprocess will be spawned to preserve current process environment)
  
  Use a browser to access the "%HTTPD-I-SERVICE" shown when the server starts.
  
  The server will be running in promiscuous mode!
  Any username with the password specified below can be used for authentication.
  Enter a string to use as a password when later prompted by your browser.
  
  Password (for demo authentication)? []: anyoldpassword
  
  %DCL-S-SPAWNED, process SYSTEM_24 spawned
  %DCL-S-ATTACHED, terminal now attached to process SYSTEM_24
  %HTTPD-I-SOFTWAREID, HTTPd-WASD/8.5.0 OpenVMS/AXP
  WASD VMS Hypertext Services, Copyright (C) 1996-2004 Mark G.Daniel.
  This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
  This is free software, and you are welcome to redistribute it
  under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
  %HTTPD-I-STARTUP, 02-JAN-2004 21:53:09
  %HTTPD-I-SYSTEM, Digital AlphaStation 500/333 VMS V7.3-2
  %HTTPD-W-SYSPRV, operating with implicit SYSPRV (UIC group 1)
  %HTTPD-I-TCPIP, Compaq TCPIP$IPC_SHR V5.4-15 (18-SEP-2003 21:58:05.32)
  %HTTPD-I-MODE, INTERACTIVE
  %HTTPD-I-ODS5, supported by Alpha VMS V7.3-2
  %HTTPD-I-GMT, +10:30
  %HTTPD-I-INSTANCE, supervisor
  %HTTPD-I-GBLSEC, created global section of 16 page(let)s
  %HTTPD-I-INSTANCE, 1 process
  %HTTPD-I-INSTANCE, process name HTTPd:7080
  %HTTPD-W-AUTH, 1 informational, 1 warning, 0 errors at load
  1.w PROMISCUOUS authenticating any username with specified password!
  2.i Cache for 32 records of 768 bytes in local storage of 49 page(let)s
  %HTTPD-I-SCRIPTING, as HTTP$NOBODY
  %HTTPD-I-DCL, subprocess scripting
  %HTTPD-I-ACTIVITY, created global section of 816 page(let)s
  %HTTPD-I-SERVICE, http://klaatu.local.org:7080
  %HTTPD-I-DEMO, demonstration mode
  1.i subprocess scripting
  2.i promiscuous authentication
  3.i directory access control files ignored
  4.i [DirAccess] enabled
  5.i [DirMetaInfo] enabled
  6.i [DirWildcard] enabled
  7.i [Logging] disabled
  8.i [ReportBasicOnly] disabled
  9.i [ReportMetaInfo] enabled
  %HTTPD-I-BEGIN, 02-JAN-2004 21:53:10, accepting requests
<ENDCODE_EXAMPLE>

<P> When <EMPHASIS>(http://the.host.name:7080) is accessed the browser
should display something resembling

<CODE_EXAMPLE>
<COMMENT>(HTML=<BLOCKQUOTE><TABLE CELLPADDING=10 CELLSPACING=0 BORDER=0><TR><TD BGCOLOR="#cccccc"><PRE>)

       == / \           Welcome. This page provides some basic<COMMENT>(HTML=&nbsp;&nbsp;&nbsp;)
     /<EMPHASIS>(W A S D\BOLD)\          information on, and access to, the    
  Empowered by VMS      <EMPHASIS>(<QUOTE>(<UNDERLINE>(WASD VMS Hypertext Services))\BOLD)
     \/---\__/          package version 8.5 
           ==
<COMMENT>(HTML=</PRE></TD></TR></TABLE></BLOCKQUOTE>)
<ENDCODE_EXAMPLE>

<NOTE>
The WASD server which is started by the [INSTALL]DEMO.COM procedure does not
have the full environment setup at that time.  It is deliberately limited to
the single process context.  For instance, do not try to execute the
command-line directives described in this document.
<ENDNOTE>

<HEAD1>(<QUOTE>(Clone) Procedure\head_clone_procedure)

<P> The [INSTALL]CLONE.COM procedure assists in creating a ZIP archive
of an existing WASD installation suitable for recreating the server on another
system without the necessity of a full installation.  This could be used to
populate a series of systems with pre-configured servers.

<HEAD1>(Re-Linking\head_relinking)

<P> After a major update to the operating system the package may refuse to
start, reporting a message like:

<CODE_EXAMPLE>
  %DCL-W-ACTIMAGE, error activating image WHAT$EVER
  -CLI-E-IMGNAME, image file DKA0:[SYS0.SYSCOMMON.][SYSLIB]WHAT$EVER_SHR.EXE
  -SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image
<ENDCODE_EXAMPLE>

<P> This implies the executables require re-linking for your particular version
of VMS.  This can be accomplished quite simply, perform the linking section
only of the update DCL procedure, <REFERENCE>(head_setup_update).

<HEAD1>(VMS 6.0 and 6.1 \head_version_6061)

<P> <EMPHASIS>(Persona) scripting requires a minimum VMS V6.2 to provide the
$PERSONA services required for this functionality.  If unsure about
<EMPHASIS>(persona) scripting please consult the <QUOTE>(Scripting Overview)
document.   Equivalent functionality on earlier versions of VAX VMS is
available using the PERSONA_MACRO build option.  This will be prompted for by
the INSTALL.COM and UPDATE.COM procedures if VAX VMS V6.0 or V6.1 is detected. 
It is completely optional functionality, the default for these versions is
merely to report that persona scripting is unavailable.

<P> A kernel-mode MACRO module is used to provide sufficient functionality to
support non-server account scripting.  This module makes a momentary
modification to the server process username in kernel data structures allowing
a detached (scripting) process to be created under that account.  The standard
WASD server STARTUP.COM procedure will detect whether the MACRO module has been
compiled into the executable and INSTALL the image with CMKRNL privilege if
required.

<NOTE>
Although this approach has been used by a number of tools and applications and
has proved quite reliable it is still a mechanism unsupported by the operating
system proper and so may have a (potentially) undesirable impact on system
integrity.
<ENDNOTE>

<P> An alternative is to run the server as a NETWORK mode process.

<HEAD1>(VMS 5.5-<EMPHASIS>(n) \head_version_552)

<P> WASD is only officially supported for VMS V6.0 or greater.  However
pre-7.<EMPHASIS>(n) versions have been known to successfully build and run
under VMS V5.5-<EMPHASIS>(n).  It will, in all probability, require the
AACRTL060 kit (which is part of DECC for this version of VMS, or can be
obtained and installed separately).

<P> One issue was a difficulty in using the CGI-BIN logical.  This was isolated
to the hyphen it contains and resolved by changing the definition of this in
STARTUP.COM, using instead <QUOTE>(CGI-BIN).  This is now the default for the
example startup procedure, allowing both 5.5-<EMPHASIS>(n)  and later VMS
versions to function correctly.

<HEAD1>(Local Setup Suggestions\head_setup_suggestions)

<P> Package updates <EMPHASIS>(will never\BOLD) contain anything in these
directories:

<LIST>(SIMPLE)
<LE> HT_ROOT:[HTTP$NOBODY]
<LE> HT_ROOT:[HTTP$SERVER]
<LE> HT_ROOT:[LOCAL]
<LE> HT_ROOT:[STARTUP]
<ENDLIST>

<P> To prevent the overwriting of local configuration files it is suggested
these be placed in the HT_ROOT:[LOCAL] directory. Local authentication
databases could also be placed in the [LOCAL] directory. Startup files can be
placed where-ever the local site manages system startup. These could be placed
in the HT_ROOT:[STARTUP] directory. 

<HEAD1>(Reporting Problems\head_setup_problems)

<P> This package, as is generally the case with freeware, is mainly developed
and supported outside of the author's main occupation and working hours. 
Reports of problems and bugs (while not necessarily welcome :^), as well as
general queries, are responded to as soon as practicable.  If the documentation
is inaccurate or could benefit from clarification in some area please advise of
this also (the better the documentation the less queries you have to field
personally <HELLIPSIS> or so the theory goes).

<P> With all reports please include the version of the server or script, and
the hardware platform, operating system and TCP/IP package and version in use.

<P> If a server error message is being generated please examine the HTML source
of the error page.  The <QUOTE>(<LITERAL>(<META...>)) information contains
version information as well as valuable source code module and line
information.  Include this with the report.

<P> If the server is exiting with a server-generated error message this
information also contains module and line information.  Please include this
with the report.

<P> The WATCH facility (<REFERENCE>(chapter_watch)) is often a powerful
tool for problem investigation.  It is also very useful when supplying
details during problem resolution.  <EMPHASIS>(When supplying WATCH output as
part of a problem report please ZIP the file and include it an an e-mail
attachment.\BOLD)  Mailers often mangle the report format making it difficult
to interpret.

<P> Image crash dumps may also be generated, although these are of less value
than the case of the previous two.

<P> Reports may be e-mailed to
<LINE>

<COMMENT>(HTML=
<A HREF="mailto:Mark.Daniel@wasd.vsm.com.au.au">Mark.Daniel@wasd.vsm.com.au.au</A>
)

<COMMENT>(HTML/OFF)
<UNDERLINE>(Mark.Daniel@wasd.vsm.com.au.au)
<COMMENT>(HTML/ON)

<P> Should the above address present problems or provide no response for an
extended period then use
<LINE><UNDERLINE>(Mark.Daniel@dsto.defence.gov.au)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Server Account and Environment\chapter_server_account)

<P> The HTTP server account should be a standard account, preferably in a
group of its own (definitely at least a non-system, non-user group), with 
sufficient quotas to handle the expected traffic. 

<NOTE>(Process Quotas!)
Server process quotas must be sufficient to support the expected traffic load. 
In particlular PRCLM must support expected script usage.  BYTLM, BIOLM, DIOL,
FILLM and PGFLQUO are all significant considerations.
<ENDNOTE>

<P> Symptoms of insufficient process quotas include:

<LIST>(UNNUMBERED)

<LE> Textual pages OK, but pages with a significant number of images having
some or all <QUOTE>(broken).

<LE> Scripts failing mysteriously, particularly when multiple in use
concurrently.

<LE> Server and associated scripts all apparently waiting MWAIT or RWAST
states.

<ENDLIST>

<CP> A general rule is more is better, after all, it will only use as much as
it needs!  To assist with setting a reasonable BYTLM quota the WATCH report
provides some feedback on server  BYTLM usage.  See <REFERENCE>(chapter_watch)
for further details.

<NOTE>(TCP/IP Agent Resources!)
On an associated topic; some TCP/IP agents require particular internal
resources to be adjusted against given loads (e.g. buffer space allocations). 
Symptoms of resource starvation may be TCP/IP services, including WASD,
<QUOTE>(pausing) for significant periods or associated processes entering
miscellaneous wait states, etc., during processing.  Please ensure such TCP/IP
agents are appropriately dimensioned for expected loads.
<ENDNOTE>

<HEAD1>(VMS Server Account\head_server_account)

<P> The following provides <UNDERLINE>(a guide) to the account.

<CODE_EXAMPLE>
  Username: HTTP$SERVER                      Owner:  WASD Server
  Account:  HTTPD                            UIC:    [077,001] ([HTTP$SERVER])
  CLI:      DCL                              Tables: DCLTABLES
  Default:  HT_ROOT:[HTTP$SERVER]
  LGICMD:   LOGIN
  Flags:  Restricted DisNewMail
  Primary days:   Mon Tue Wed Thu Fri
  Secondary days:                     Sat Sun
  Primary   000000000011111111112222  Secondary 000000000011111111112222
  Day Hours 012345678901234567890123  Day Hours 012345678901234567890123
  Network:  ##### Full access ######            ##### Full access ######
  Batch:    ##### Full access ######            ##### Full access ######
  Local:    -----  No access  ------            -----  No access  ------
  Dialup:   -----  No access  ------            -----  No access  ------
  Remote:   -----  No access  ------            -----  No access  ------
  Expiration:            (none)    Pwdminimum:  6   Login Fails:     0
  Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired)
  Last Login:            (none) (interactive), 11-MAY-1995 08:44 (non-interactive)
  Maxjobs:         0  Fillm:       300  Bytlm:       500000
  Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0
  Maxdetach:       0  BIOlm:      2048  JTquota:       1024
  Prclm:         100  DIOlm:      1024  WSdef:         1000
  Prio:            4  ASTlm:      2000  WSquo:         5000
  Queprio:         0  TQElm:       100  WSextent:     20000
  CPU:        (none)  Enqlm:       256  Pgflquo:     500000
  Authorized Privileges:
    NETMBX    TMPMBX
  Default Privileges:
    NETMBX    TMPMBX
<ENDCODE_EXAMPLE>

<HEAD1>(VMS Scripting Account\head_scripting_account)

<P> The following provides <UNDERLINE>(a guide) to the account.

<CODE_EXAMPLE>
  Username: HTTP$NOBODY                      Owner:  WASD Scripting
  Account:  HTTPD                            UIC:    [076,001] ([HTTP$NOBODY])
  CLI:      DCL                              Tables: DCLTABLES
  Default:  HT_ROOT:[HTTP$NOBODY]
  LGICMD:   LOGIN
  Flags:  Restricted DisNewMail
  Primary days:   Mon Tue Wed Thu Fri
  Secondary days:                     Sat Sun
  Primary   000000000011111111112222  Secondary 000000000011111111112222
  Day Hours 012345678901234567890123  Day Hours 012345678901234567890123
  Network:  ##### Full access ######            ##### Full access ######
  Batch:    ##### Full access ######            ##### Full access ######
  Local:    -----  No access  ------            -----  No access  ------
  Dialup:   -----  No access  ------            -----  No access  ------
  Remote:   -----  No access  ------            -----  No access  ------
  Expiration:            (none)    Pwdminimum:  6   Login Fails:     0
  Pwdlifetime:         90 00:00    Pwdchange:      (pre-expired)
  Last Login:            (none) (interactive), 11-MAY-1995 08:44 (non-interactive)
  Maxjobs:         0  Fillm:       300  Bytlm:       500000
  Maxacctjobs:     0  Shrfillm:      0  Pbytlm:           0
  Maxdetach:       0  BIOlm:      2048  JTquota:       1024
  Prclm:         100  DIOlm:      1024  WSdef:         1000
  Prio:            4  ASTlm:      2000  WSquo:         5000
  Queprio:         0  TQElm:       100  WSextent:     20000
  CPU:        (none)  Enqlm:       256  Pgflquo:     500000
  Authorized Privileges:
    NETMBX    TMPMBX
  Default Privileges:
    NETMBX    TMPMBX
<ENDCODE_EXAMPLE>

<HEAD1>(Account Support Files\head_account_support_files)

<NOTE>
Support procedures often change between versions.  It is always advisable to
check the versions documentation before installing or updating.

<COMMENT>(....................................................................)

<COMMENT>(HTML=
Examples may be found in
<A HREF="/ht_root/example/">HT_ROOT:[EXAMPLE]</A>.
)

<COMMENT>(HTML/OFF)
Examples may be found in HT_ROOT:[EXAMPLE].
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<ENDNOTE>

<HEAD>(HTTPd Executables\head_httpd_exe)

<P> Two server executables can be built by the package.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(HTTPD.EXE - \BOLD) basic server

<LE> <EMPHASIS>(HTTPD_SSL.EXE - \BOLD) SSL-enabled server
(<REFERENCE>(chapter_ssl)).

<ENDLIST>

<HEAD>(Privileged Image\head_server_install)

<P> As this image is to be installed with privileges unauthorized use should 
be prevented by applying an ACL similar to the following against the 
executable image: 

<CODE_EXAMPLE>
  $ SET SECURITY HT_EXE:HTTPD.EXE -
    /ACL=((IDENT=HTTP$SERVER,ACCESS=R+E),(IDENT=*,ACCESS=NONE))
<ENDCODE_EXAMPLE>

<P> This can be done once, at installation, or for peace-of-mind 
<EMPHASIS>((a.k.a. VMS-ish paranoia)) at each server startup. 

<P> As the HTTP$SERVER account should be completely unprivileged, and the 
HTTPd image requires CMKRNL, NETMBX, TMPMBX, PRMGBL, PRMMBX, PSWAPM, SHMEM (VAX
only), SYSGBL, SYSLCK, SYSNAM, SYSPRV and  WORLD privileges (see the
<QUOTE>(Nuts and Bolts) document for a description of how and why the server
uses these privileges).  It must be installed using a command similar to the
following:

<CODE_EXAMPLE>
  $ INSTALL = "$SYS$SYSTEM:INSTALL/COMMAND_MODE"
  $ INSTALL ADD HT_EXE:HTTPD.EXE -
    /PRIVILEGE=(ALTPRI,CMKRNL, PRMGBL,PRMMBX,PSWAPM,SHMEM,-
                SYSGBL,SYSLCK,SYSNAM,SYSPRV,WORLD) 
<ENDCODE_EXAMPLE> 

<HEAD>(STARTUP.COM\head_server_startup)

<P> Putting all this together the HTTP server startup procedure becomes 
something similar to the supplied example.  It should be called from
SYSTARTUP_VMS.COM or the site's equivalent.

<P> This procedure will support simple and quite complex sites. It works
closely with STARTUP_SERVER.COM (see below). It is designed to accept
parameters from the command-line or as pre-assigned symbols. Operating in this
fashion should mean that no modifications will need to be made to the
procedure itself. Startup characteristics are essentially determined by DCL
symbol values. Some symbols are booleans, switching functionality off and on,
others require string values. When relevant startup values are not assigned a
reasonable default will be applied. See the following examples.

<P> Startup characteristics can be determined by supplying symbol assignment
values as command-line parameters when calling the procedure.

<CODE_EXAMPLE>
  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP WASD_DECNET=1 WASD_SSL=1 -
  WASD_SSL_CERTIFICATE="HT_ROOT:[LOCAL]ALPHA.PEM"
<ENDCODE_EXAMPLE>

<P> Startup characteristics can also be determined by assigning the symbol
values before calling the procedure itself.

<CODE_EXAMPLE>
  $ WASD_DECNET = 1
  $ WASD_SSL = 1
  $ WASD_SSL_CERTIFICATE = "HT_ROOT:[LOCAL]ALPHA.PEM"
  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP
<ENDCODE_EXAMPLE>

<P> On version of VAX VMS prior to 6.2 the startup uses a system batch queue.
By default SYS$BATCH is used.  If a node does not have a SYS$BATCH then one
must be created.  If a clustered node's SYS$BATCH is configured to run on a
cluster-common batch queue (i.e. not necessarily on the startup node) then a
node-specific queue must be specified.

<CODE_EXAMPLE>
  $ @$1$DKA0:[HT_ROOT.LOCAL]STARTUP WASD_DECNET=1 WASD_BATCH_QUEUE=THIS$BATCH
<ENDCODE_EXAMPLE>

<P> Check the procedure itself for detail on symbol names and functionality.

<COMMENT>(HTML=
<P> See <A HREF="/ht_root/example/startup.com">
HT_ROOT:[EXAMPLE]STARTUP.COM</A>
)

<COMMENT>(HTML/OFF)
<P> See HT_ROOT:[EXAMPLE]STARTUP.COM
<COMMENT>(HTML/ON)

<HEAD>(STARTUP_LOCAL.COM\head_server_startup_local)

<P> This file is automatically executed by the STARTUP.COM procedure
immediately before the server is actually started.  It is provided to supply
all the local site's additional startup requirements.  Place site-specific
server environment startup in here, leaving STARTUP.COM alone as much as
possible.

<COMMENT>(HTML=
<P> See <A HREF="/ht_root/example/startup_local.com">
HT_ROOT:[EXAMPLE]STARTUP_LOCAL.COM</A>
)

<COMMENT>(HTML/OFF)
<P> See HT_ROOT:[EXAMPLE]STARTUP_LOCAL.COM
<COMMENT>(HTML/ON)

<HEAD>(STARTUP_SERVER.COM\head_httpd_startup_server_com)

<P> This procedure serves two purposes.

<LIST>(NUMBERED)

<LE> Server startup:

<LIST>(UNNUMBERED)

<LE> If on VAX VMS V6.2 or earlier it is submitted to the SYS$BATCH queue
during startup.  The batch portion creates a detached process, which then again
uses this procedure as input, supporting the executing HTTPd.

<LE> With more modern versions and architectures of VMS the procedure becomes
SYS$COMMAND for a detached process created directly during the execution of
STARTUP.COM.

<ENDLIST>

<LE> The procedure then controls the activation of the HTTPd executable image
during normal restarts and exits, and exits after fatal server error.

<ENDLIST>

<COMMENT>(HTML=
<P> See <A HREF="/ht_root/example/startup_server.com">
HT_ROOT:[EXAMPLE]STARTUP_SERVER.COM</A>
)

<COMMENT>(HTML/OFF)
<P> See HT_ROOT:[EXAMPLE]STARTUP_SERVER.COM
<COMMENT>(HTML/ON)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Other Resources\head_account_other_resources)

<P> Other resources required or consumed by the package.

<HEAD>(Global Pages/Sections\head_global_pages)

<P> Accounting and request data made available to the server monitor utility
(HTTPDMON) is provided by shared global memory.  This requires one global
section (SYSGEN parameter GBLSECTIONS) and 16 global pages (SYSGEN parameter
GBLPAGES).  The activity statistics available from the Server Admininistration
facility requires one  global section and 816 global pages.  These two global
sections are permanent.

<P> If multiple server <EMPHASIS>(instances) are to be employed one more
global section is required for a standard server (a shared authentication
cache), or two more for an SSL server (a shared session cache), with another if
reverse proxy verify is enabled, plus a variable number (some tens) of global
pages.  These global sections are temporary.

<P> If there are insufficient global sections or pages the server will fail to
start for all requirements except the activity statistics, this will just be
disabled.  Startup messages advise on current usage. 

<P> As permanent, system-accessable global sections are deployed it may be
necessary to explicitly delete them after ad hoc server experimentation, etc.
(<REFERENCE>(head_server_command_startup)).  The startup qualifier
/GBLSEC=NOPERM disables the creation of permanent global sections eliminating
this requirement.

<HEAD>(Logical Names\head_server_logical_names)

<P> The following logical names are used in the operation of the HTTPd 
server and most must be defined before startup (system-wide, or in the job
table if server-specific).  These are usually created by STARTUP.COM during
server startup.

<P>
<CENTER_LINE>(<EMPHASIS>(Package Logical Names\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Logical Name\Description)

<TABLE_ROW>(HTTPD$AUTH\Location of the authentication/authorization
configuration file.) 

<TABLE_ROW>(HTTPD$CONFIG\Location of the configuration file.)

<TABLE_ROW>(HTTPD$MAP\Location of the mapping rule file.)

<TABLE_ROW>(HTTPD$MSG\Location of the message file.)

<TABLE_ROW>(HTTPD$SERVICE\Location of the optional service (virtual host)
configuration file.) 

<TABLE_ROW>(HTTPD$SITELOG\Location of the optional plain-text site log file
(<REFERENCE>(head_server_revise)).)

<TABLE_ROW>(HTTPD$GMT\Offset from GMT (e.g. <QUOTE>(+10:30), <QUOTE>(-01:15)).
For systems supporting DTSS (e.g. DECnet-Plus) this logical  may be left
undefined, with server time being calculated using the
SYS$TIMEZONE_DIFFERENTIAL logical.)

<TABLE_ROW>(HTTPD$LOG\If logging is enabled and no log file name
specified on the command line, this logical must be defined to locate the
file.  When a logging period is in use this logical need only contain the
directory used to store the logs.)

<TABLE_ROW>(HTTPD$SSL_CERT\When using the SSL executable this logical locates
the default certificate.)

<TABLE_ROW>(HTTPD$STARTUP_SERVER\Can be used to pass parameters to HTTPd
startup.)

<TABLE_ROW>(AXP_BIN\Directory containing Alpha script executables.)

<TABLE_ROW>(CGI-BIN\System logical defining a search list with
the architecture-specific executable directory first, local script directory
second, then the common script directory, as a concealed device.)

<TABLE_ROW>(CGI_BIN\Directory containing archtecture-neutral script files.)

<TABLE_ROW>(CGI_EXE\Directory containing architecture-specific script
executables.)

<TABLE_ROW>(HT_AXP\Directory containing Alpha executable images.)

<TABLE_ROW>(HT_AUTH\Directory containing authentication/authorization databases
(files).)

<TABLE_ROW>(HT_EXE\Directory containing the executable images.)

<TABLE_ROW>(HT_IA64\Directory containing IA64 executable images.)

<TABLE_ROW>(HT_LOGS\Optional definition, for convenient log file specification.)

<TABLE_ROW>(HT_SCRATCH\Location of an optional directory that
scripts can use for temporary storage.  Must be read+write+delete accessable to
the server account.  The HTTPD$CONFIG [DclCleanupScratchMinutesMax] directive
controls whether automatic cleanup scans of this area delete any files that are
older than [DclCleanupScratchMinutesOld].)

<TABLE_ROW>(HT_SERVER_LOGS\Optional definition, for convenient  detached server
process log file specification.) 

<TABLE_ROW>(HT_VAX\Directory containing VAX executable images.)

<TABLE_ROW>(IA64_BIN\Directory containing IA64 script executables.)

<TABLE_ROW>(VAX_BIN\Directory containing VAX script executables.)

<ENDTABLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(HTTPd Command Line\head_httpd_command_line)

<P> Command-line qualifiers provide some server startup control as well as
server runtime control.

<HEAD2>(Server Startup\head_server_command_startup)

<P> When starting up the server several characteristics of the server may be 
specified using qualifiers on the command line.  If not specified appropriate 
defaults are employed.  For recommended methods of passing parameters to the
executable at server startup see <REFERENCE>(head_httpd_startup_server_com).

<P>
<CENTER_LINE>(<EMPHASIS>(Server Image Command-Line Parameters\BOLD))
<TABLE>
<TABLE_SETUP>(2\20)
<TABLE_HEADS>(Parameter/Qualifier\Description)

<TABLE_ROW>(/ACCEPT=\Comma-separated list of hosts/domains allowed to
connect to the server.)

<TABLE_ROW>(/ALL[=string]\Has two roles.  When starting a server up
assigns that server to a specific, non-default group of servers (for
cluster-wide server control and proxy cache management).  When using the server
control /DO= using /ALL specifies to do the action to all servers in the
group.)

<TABLE_ROW>(/AUTHORIZATION=[SSL,ALL]\The <QUOTE>(SSL) keyword causes
all authentication (both SYSUAF and HTA database) to be available only via
<QUOTE>(https:) requests (<REFERENCE>(chapter_ssl)).  The <QUOTE>(ALL)
keyword forces the server to deny access to any path that does not have
authorization in place against it (<REFERENCE>(head_auth_policy)).)

<TABLE_ROW>(/CGI_PREFIX=\The prefix to the CGI symbol names created 
for a script (defaults to <QUOTE>(WWW_), similar to the CERN VMS HTTPd, see 
<QUOTE>(Scripting Environment) document).)

<TABLE_ROW>(/CLUSTER\Apply control /DO= to all instances in the
cluster (default is to per-node instances only).)

<TABLE_ROW>(/DEMO\Places the server into demonstration mode designed
to allow full package capabilities to be demonstrated.  Used by the
[INSTALL]DEMO.COM procedure.)

<TABLE_ROW>(/DETACH=\For VMS 6.2 and later this qualifier allows a
DCL procedure to be specified as input to a directly detached process (in
conjunction with /USER).)

<TABLE_ROW>(/DO=\Command to be performed by the executing server
(<REFERENCE>(head_httpd_control)).)

<TABLE_ROW>(/FILBUF=\Number of bytes in the read buffer for files 
open for processing (i.e. menu files, image mapping configuration files,
pre-processed HTML files, etc., not direct file transfers).)

<TABLE_ROW>(/FORMAT=\Overrides the configuration parameter [LogFormat].)

<TABLE_ROW>(/GBLSEC=DELETE\Allows a monitor-associated
permanent global section to be explicitly deleted.  When a server starts it
creates system-accessable, permanent global sections in which to store
accounting and request data.  As this is permanent it would be possible for a
site, perhaps experimenting with servers over a range of ports, to consume
significant amounts of global pages and sections.  This qualifier allows such
sections to be deleted.  See also the /GBLSEC=NOPERM described immediately
below.)

<TABLE_ROW>(/GBLSEC=NOPERM\Disables the creation of permanent global
sections.  They are automatically deleted when the server image exits.)

<TABLE_ROW>(/REJECT=\Comma-separated list of hosts/domains not
allowed to connect to the server.)

<TABLE_ROW>(/[NO]LOG[=name]\Either disables logging (overrides 
configuration directive), or enables logging and optionally specifies the log 
file name (also see section <REFERENCE>(head_server_logical_names), logging 
is disabled by default).  If the file specification is <QUOTE>(SYS$OUTPUT) the
server issues log entries to <LITERAL>(<stdout>), allowing user-defined log
formats to be easily checked and refined.)

<TABLE_ROW>(/NOMONITOR\Allows the update of the data read by HTTPDMON
to be disabled.)

<TABLE_ROW>(/NETBUF=\Minimum number of bytes in the network read 
buffer.)

<TABLE_ROW>(/NETWORK\Run the server and any scripting processes as
NETWORK mode rather than the default detached OTHER mode.)

<TABLE_ROW>(/OUTBUF=\Number of bytes in the output buffer 
(for direct file transfers, buffered output from menu interpretation,
HTML-preprocessing, etc.))

<TABLE_ROW>(/PERIOD=\Overrides the configuration parameter
[LogPeriod].)

<TABLE_ROW>(/PERSONA[=<EMPHASIS>(ident-name),<LINE>
RELAXED,AUTHORIZED,<LINE>
RELAXED=AUTHORIZED]\
Enables detached process scripting.  When used without the
<EMPHASIS>(ident-name) all non-privileged accounts (appropriately mapped of
course) may have scripts executed under them.  If the optional
<EMPHASIS>(ident-name) is supplied it specifies the name of a rights identifier
the account must be granted before scripts can be activated under it.  The
RELAXED, AUTHORIZED and RELAXED=AUTHORIZED further control the use of persona
functionality with privileged accounts.  See <QUOTE>(Scripting Overview,
Introduction) for further detail.)

<TABLE_ROW>(/PORT=\Overrides the configuration parameter [Port] BUT
is in turn overridden by the [Service] configuration parameter and /SERVICE=
qualifier (is really only useful for use with the /DO= qualifier).)

<TABLE_ROW>(/PRIORITY=\Server process priority (default is 4).)

<TABLE_ROW>(/[NO]PROFILE\Allows SYSUAF-authenticated username
security profiles to be used for file access (<REFERENCE>(head_auth_sysuaf)).)

<TABLE_ROW>(/PROMISCUOUS[=password]\Server will accept any
authentication username/password pair (used for testing, demonstrations, etc.))

<TABLE_ROW>(/PROXY=string\Allows proxy maintainance activitied to be
executed from the command line (e.g. from batch jobs, etc.).  See
<REFERENCE>(head_proxy_caching_management).)

<TABLE_ROW>(/SCRIPT=AS=\Specifies the username of the default
scripting account.)

<TABLE_ROW>(/SERVICE=\Comma-separated, list of server services
(overrides the [Service] configuration parameter).)

<TABLE_ROW>(/[NO]SSL[=version]\Controls Secure Sockets Layer protocol
behaviour.  The version can be any of <QUOTE>(2), <QUOTE>(3) or <QUOTE>(23)
(i.e. both 2 and 3, and the default) specifying which SSL protocol version the
server will service.)

<TABLE_ROW>(/SUBBUF=\Number bytes in a (sub)process' SYS$OUTPUT buffer.)

<TABLE_ROW>(/[NO]SWAP\Controls whether the server process may be 
swapped out of the balance set (default is swapping disabled).)

<TABLE_ROW>(/[NO]SYSUAF[=ID,<LINE>PROXY,SSL,WASD]\Allows or disallows (D)
username authentication using the server system's SYSUAF
(<REFERENCE>(head_auth_sysuaf)), the optional <QUOTE>(SSL) keyword causes SYSUAF
authentication to be available only via <QUOTE>(https:) requests
(<REFERENCE>(chapter_ssl)), the optional <QUOTE>(PROXY) keyword allows SYSUAF
proxying, and the optional <QUOTE>(ID) keyword makes SYSUAF authentication only
available to account possessing a specific identifier
(<REFERENCE>(head_auth_sysuaf)).   The <QUOTE>(WASD) keyword makes the
deprecated, "hard-wired" WASD identifier environment available to this server.
See <REFERENCE>(head_auth_wasd_identifier).)

<TABLE_ROW>(/USER\For VMS 6.2 and later this qualifier allows the
/DETACH qualifier to directly create a detached process executing as the
specified username.)

<TABLE_ROW>(/VERSION\Displays the executable's version string and the copyright
notice.)

<TABLE_ROW>(/[NO]WATCH=\Controls the use of the WATCH reporting
facility.  See <REFERENCE>(chapter_watch) for further details.)

<ENDTABLE>

<HEAD2>(Server Command Line Control\head_httpd_control)

<P> A foreign command for the HTTPD control functionality will need to be 
assigned in the adminstration users' LOGIN.COM, for example: 

<CODE_EXAMPLE>
  $ HTTPD == "$HT_EXE:HTTPD"

  $ HTTPD == "$HT_EXE:HTTPD_SSL"
<ENDCODE_EXAMPLE>

<P> Some control of the executing server is available from the DCL command
line on the system on which it is executing. This functionality, via the /DO=
qualifier, is available to the privileged user. If a non-default server port
then it will be necessary to provide a /PORT= qualifier with any command.

<HEAD>(Multi-Server/Cluster-Wide\head_server_multiple)

<P> If multiple servers are executing on a host or cluster it is possible to
control all of them by adding the /CLUSTER or /ALL qualifiers.  Of course,
these commands are available from batch jobs as well as interactively.  The
same functionality is available from the online Server Administration facility.

<HEAD3>(Accounting\head_server_accounting)

<P> Server counters may be zeroed.  These counters are those visible from the
<EMPHASIS>(statistics) Server Admininstration item and when using the HTTPDMON
utility.

<CODE_EXAMPLE>
  $ HTTPD /DO=ZERO
<ENDCODE_EXAMPLE>

<HEAD3>(Authentication\head_server_authentication)

<P> See <REFERENCE>(chapter_authorization).

<P> The authorization rule file (HTTP$AUTH) may be reloaded.

<CODE_EXAMPLE>
  $ HTTPD /DO=AUTH=LOAD
<ENDCODE_EXAMPLE>

<P> The authentication cache may be purged, resulting in re-authentication for
all subsequent authorization-controlled accesses. This may be useful when
disabling authorization or if a user has been locked-out due to too many
invalid password attempts (<REFERENCE>(head_auth_cache)).

<CODE_EXAMPLE>
  $ HTTPD /DO=AUTH=PURGE
<ENDCODE_EXAMPLE>

<P> A <QUOTE>(skeleton-key) username and password may be entered, amongst
things allowing access to the Server Administration facility
(<REFERENCE>(chapter_server_admin)).

<CODE_EXAMPLE>
  $ HTTPD <LITERAL>(/DO=AUTH=SKELKEY=_<username>:<password>[:<period>])
<ENDCODE_EXAMPLE>

<HEAD3>(Cache\head_server_cache)

<P> Server cache control may also be exercised from the Server Administration
page (<REFERENCE>(chapter_server_admin)).  The file cache
(<REFERENCE>(chapter_cache)) may be enabled, disabled and have it's contents 
purged (declared invalid and reloaded) using

<CODE_EXAMPLE>
  $ HTTPD /DO=CACHE=ON
  $ HTTPD /DO=CACHE=OFF
  $ HTTPD /DO=CACHE=PURGE
<ENDCODE_EXAMPLE>

<HEAD3>(DCL/Scripting Subprocesses\head_server_subprocesses)

<P> These commands can be useful for flushing any currently executing CGIplus
applications from the server, enabling a new version to be loaded with the
next access. See <QUOTE>(Scripting Environment) document.

<P> All scripting subprocesses, busy with a request or not, can be deleted
(this may cause the client to lose data).

<CODE_EXAMPLE>
  $ HTTPD /DO=DCL=DELETE
<ENDCODE_EXAMPLE>

<P> A gentler alternative is to delete idle subprocesses and mark busy ones
for deletion when completed processing.

<CODE_EXAMPLE>
  $ HTTPD /DO=DCL=PURGE
<ENDCODE_EXAMPLE>

<HEAD3>(DECnet Scripting Connections\head_decnet_connections)

<P> All DECnet connections, busy with a request or not, can be disconnected
(this may cause the client to lose data).

<CODE_EXAMPLE>
  $ HTTPD /DO=DECNET=DISCONNECT
<ENDCODE_EXAMPLE>

<P> Purging is a better alternative, disconnecting idle tasks and marking busy
ones for disconnection when complete.

<CODE_EXAMPLE>
  $ HTTPD /DO=DECNET=PURGE
<ENDCODE_EXAMPLE>

<HEAD3>(Instances\head_server_instance)

<P> The number of server instances (<REFERENCE>(head_config_instances)) may be
set from the command line.  This overrides any configuration file directive and
applies at the next startup.  Any configuration directive value may be used
from the command line.

<CODE_EXAMPLE>
  $ HTTPD /DO=INSTANCE=MAX
  $ HTTPD /DO=INSTANCE=CPU
  $ HTTPD /DO=INSTANCE=<EMPHASIS>(integer)
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(Note that the server must be restarted for this to take
effect\BOLD), that this can be applied to the current node only or to all
servers within a cluster, and that it remains in effect until explicitly
changed to <QUOTE>(MAX) allowing the HTTPD$CONFIG configuration directive
[InstanceMax] to once again determine the number of instances required.  The
same functionality is available from the Server Administration page
(<REFERENCE>(head_server_action)).

<HEAD3>(Logging\head_server_logging)

<P> Server logging control may also be exercised from the server administration
menu (<REFERENCE>(chapter_server_admin)).

<P> Open the access log file(s). 

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=OPEN
<ENDCODE_EXAMPLE>

<P> Close the access log file(s). 

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=CLOSE
<ENDCODE_EXAMPLE>

<P> Close then reopen the access log file(s). 

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=REOPEN
<ENDCODE_EXAMPLE>

<P> Unwritten log records may be flushed to the file(s).

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=FLUSH
<ENDCODE_EXAMPLE>

<NOTE>(OBSOLETE)

The following directives have been rendered obsolete due to the increasing
complexity of WASD access logging.

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=FORMAT=string
  $ HTTPD /DO=LOG=OPEN=<EMPHASIS>(file-name)
  $ HTTPD /DO=LOG=PERIOD=string
  $ HTTPD /DO=LOG=REOPEN=<EMPHASIS>(file-name)
<ENDCODE_EXAMPLE>

<ENDNOTE>

<HEAD3>(Mapping\head_server_mapping)

<P> See <REFERENCE>(chapter_mapping_rule).

<P> The mapping rule file (HTTPD$MAP) may be reloaded.

<CODE_EXAMPLE>
  $ HTTPD /DO=MAP
<ENDCODE_EXAMPLE>

<HEAD3>(Shutdown and Restart\head_server_shutdown)

<P> Server shutdown may also be exercised from the Server Administration
page (<REFERENCE>(chapter_server_admin)).

<P> The server may be shut down, without loss of existing client requests.
Connection acceptance is stopped and any existing requests continue to be
processed until conclusion.

<CODE_EXAMPLE>
  $ HTTPD /DO=EXIT
<ENDCODE_EXAMPLE>

<P> The server may be immediately and unconditionally shut down.

<CODE_EXAMPLE>
  $ HTTPD /DO=EXIT=NOW
<ENDCODE_EXAMPLE>

<P> The server may be restarted, without loss of existing client requests.
Connection acceptance is stopped and any existing requests continue to be
processed until conclusion.  This effectively causes the server to exit
normally and the DCL <EMPHASIS>(wrapper) procedure to restart it.

<CODE_EXAMPLE>
  $ HTTPD /DO=RESTART
<ENDCODE_EXAMPLE>

<P> The <EMPHASIS>(now) variant restarts the server immediately regardless of
existing connections.

<CODE_EXAMPLE>
  $ HTTPD /DO=RESTART=NOW
<ENDCODE_EXAMPLE>

<P> The when-<EMPHASIS>(quiet) variant restarts the server whenever request
processing drops to zero for more than one second.  It allows (perhaps
non-urgent) changes to be put into effect through restart when everything has
gone <QUOTE>(quiet) and no demands are being placed on the server.

<CODE_EXAMPLE>
  $ HTTPD /DO=RESTART=QUIET
<ENDCODE_EXAMPLE>

<HEAD3>(Secure Sockets Layer\head_do_ssl)

<P> If the optional SSL component is installed and configured these directives
become effective.

<P> If X.509 authentication is enabled the Certificate Authority (CA)
verification list can be reloaded.

<CODE_EXAMPLE>
  $ HTTPD /DO=SSL=CA=LOAD
<ENDCODE_EXAMPLE>

<P> If a private key password is not included with the encode key it is
requested by the server during startup.  The following example shows the
directive and its resulting prompt.  When entered the password is not echoed.

<CODE_EXAMPLE>
  $ HTTPD /DO=SSL=KEY=PASSWORD
  Enter private key password []:
<ENDCODE_EXAMPLE>

<HEAD3>(Throttle\head_do_throttle)

<P> Unconditionally release all queued requests for immediate processing.

<CODE_EXAMPLE>
  $ HTTPD /DO=THROTTLE=RELEASE
<ENDCODE_EXAMPLE>

<P> Unconditionally terminate all requests queued waiting for processing. 
Clients receive a 503 <QUOTE>(server too busy) response.

<CODE_EXAMPLE>
  $ HTTPD /DO=THROTTLE=TERMINATE
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)
