<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. As of v5.1
an installation DCL procedure simplifies the initial setup.

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

<COMMENT>(HTML=<P>)

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

<P> Server installation is performed using the 

<COMMENT>(HTML=<A HREF="/ht_root/install.com">INSTALL.COM</A>)

<COMMENT>(HTML/OFF)
INSTALL.COM
<COMMENT>(HTML/ON)

DCL procedure, see <REFERENCE>(head_setup_install).

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

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

<P> Compile and link, or just link supplied object files to produce VMS
executables for the system's version of VMS.

<COMMENT>(HTML=<P>)

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

<P> Using the installation procedure check the operation of the basic package
as recommended in <REFERENCE>(head_quick_check).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Directory Protections\BOLD)

<P> This section checks for correct directory protection in the HT_ROOT:[000000]
tree and prompts to change it to WORLD:RE if it appears incorrect.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Create Server Account\BOLD)

<P> Using the installation procedure create the server account.  For further
information see <REFERENCE>(head_server_account).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Disk Quota\BOLD)

<P> Check if quotas are enabled on the target disk.  Provide an ambit
allocation for the server account.  Review this at some stage.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Copy Server Support and Configuration Files\BOLD)

<P> Using the installation procedure copy the example server support and
configuration files as discussed in <REFERENCE>(head_account_support_files).

<ENDLIST>

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<ENDLIST>

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

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

<COMMENT>(HTML=<P>)

<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

<COMMENT>(HTML=<A HREF="/ht_root/log/server/">HT_ROOT:[LOG.SERVER]</A>) 

<COMMENT>(HTML/OFF)
HT_ROOT:[LOG.SERVER]
<COMMENT>(HTML/ON)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<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 (both AXP and VAX in the one cluster) as one
integrated installation.
<ENDNOTE>

<HEAD1>(ODS-5 Volumes\head_setup_ods5)

<P> The WASD server 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>(Installation DCL Procedure\head_setup_install)

<P> The

<COMMENT>(HTML=<A HREF="/ht_root/install.com">INSTALL.COM</A>)

<COMMENT>(HTML/OFF)
INSTALL.COM
<COMMENT>(HTML/ON)

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 default to <QUOTE>(no).  Read the questions carefully! 

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Directory Protections - \BOLD)
This section checks for correct directory protection in the HT_ROOT:[000000]
tree and prompts to change it to WORLD:RE if it appears incorrect.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Create Server Account - \BOLD)
Creates an unprivileged account for the HTTP server to execute within.  Sets
permissions on files and directories allowing appropriate access for this
account.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Disk Quota - \BOLD)
Check if quotas are enabled on the target disk.  Provide an ambit
allocation for the server account.  Review this at some stage.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Server Support/Configuration Files - \BOLD)
Copies example HTTP server configuration and support files from the [EXAMPLE]
directory to the [HTTP$SERVER] and [LOCAL] directories.  No copy is made
without prompting for permission.

<ENDLIST>

<P> After UNZIPping the package do the following:

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

<P>

<COMMENT>(HTML/OFF)
<P><EMPHASIS>(NOTE:\BOLD)
<COMMENT>(HTML/ON) 

<NOTE>
The installation procedure provides a reasonable, <EMPHASIS>(vanilla),
single-node set-up.  If something different is required a little time and
thought may be required further configuring startup, etc.
<ENDNOTE>

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

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

<HEAD1>(Update DCL Procedure\head_setup_update)

<P>

<COMMENT>(HTML/OFF)
<P><EMPHASIS>(NOTE:\BOLD)
<COMMENT>(HTML/ON) 

<NOTE>
When using WASD's SSL functionality <EMPHASIS>(TWO consecutive updates\BOLD)
will need to be performed.  First, the update of the basic WASD package,
immediately followed by an update of the SSL components
(see <REFERENCE>(head_ssl_quick_start)).
<ENDNOTE>

<P> The

<COMMENT>(HTML=<A HREF="/ht_root/update.com">UPDATE.COM</A>)

<COMMENT>(HTML/OFF)
UPDATE.COM
<COMMENT>(HTML/ON)

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 default to <QUOTE>(no).  Read the questions carefully!

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Server Support/Configuration Files - \BOLD)
Copies changed example HTTP server configuration and support files from the
[EXAMPLE] directory to the [HTTP$SERVER] and [LOCAL] directories.  This copy is
made without prompting for permission.

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<ENDLIST>

<NOTE>(CAUTION!)
<EMPHASIS>(Of course it is best (read mandatory) for the server to be shut
down during an update!\BOLD)
<ENDNOTE>

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

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

<HEAD>(Post-Update\head_post_update)

<P> When confident regarding the success of the update (these activities can be
part of the update DCL procedure).

<LIST>(UNNUMBERED)

<LE> The procedure

<COMMENT>(HTML=<A HREF="/ht_root/updateafter.com">UPDATEAFTER.COM</A>)

<COMMENT>(HTML/OFF)
UPDATEAFTER.COM
<COMMENT>(HTML/ON)

should be executed.  This will remove files known to exist from previous
versions and relocated or no longer required.

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

<COMMENT>(HTML=<P>)

<LE> The directory tree should be purged.

<ENDLIST>

<HEAD1>(Quick-Check\head_quick_check)

<P> Once installed or updated it is possible to check the basic package at any
time using the

<COMMENT>(HTML=<A HREF="/ht_root/freeware_demo.com">FREEWARE_DEMO.COM</A>)

<COMMENT>(HTML/OFF)
FREEWARE_DEMO.COM
<COMMENT>(HTML/ON)

procedure.  Follow the displayed instructions.

<CODE_EXAMPLE>
  @device:[HT_ROOT]FREEWARE_DEMO
<ENDCODE_EXAMPLE>

<P> Problem? <EMPHASIS>(SYSTEM-F-SHRIDMISMAT\SMALLCAPS)? See next section!

<HEAD1>(Re-Linking\head_relinking)

<P> After an 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 5.5-2\head_version_552)

<P> WASD is only officially supported for VMS V6.0 or greater.  However it has
been known to successfully build and run under V5.5-2.  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-2 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 three
directories:

<LIST>(UNNUMBERED)
<LE> HT_ROOT:[HTTP$SERVER]
<LE> HT_ROOT:[LOCAL]
<LE> HT_ROOT:[SCRIPT_LOCAL]
<ENDLIST>

<P> To prevent the overwriting of local configuration files it is suggested
these be placed in the HT_ROOT:[LOCAL] directory.  Startup files will most
probably be placed where-ever the local site manages system startup. These
could be placed in the HT_ROOT:[LOCAL] directory if there is nowhere more 
appropriate.  Authentication databases could also be placed in the [LOCAL]
directory.  The server account's support files (LOGIN.COM, etc.) may be
copied from the HT_ROOT:[EXAMPLE] directory into HT_ROOT:[HTTP$SERVER] and
customized as necessary.

<P> In like manner, local DCL scripts or DCL <EMPHASIS>(wrappers) for
executable scripts should be placed in HT_ROOT:[SCRIPT_LOCAL]. Executables
should continue to be placed in HT_EXE:

<P> Changes that are made in package configuration files, etc., can then be
propagated to the local areas as appropriate.

<HEAD1>(Organizing Documents\head_documents)

<P> It is recommended that the server distribution tree and any document and
other Web-specific data areas be kept separate and distinct. The former in
HT_ROOT:[000000], the latter in something like <EMPHASIS>(WEB:[000000]\BOLD).
This logical device could be provided with the following DCL introduced into
the server startup procedures:

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DSA811:[WEB.]
<ENDCODE_EXAMPLE>

<P> The logical organisation of served data is largely hierarchical, organised
under the Web-server path root, and is achieved via two mechanisms. 

<LIST>(NUMBERED)

<LE> The natural tree structure provided by a hierarchical file system.

<COMMENT>(HTML=<P>)

<LE> The logical hierarchy possible using rules within the mapping file to 
place disparate physical areas into a single logical structure (see 
<REFERENCE>(chapter_mapping_rule)). 

<ENDLIST>

<P> WASD has a single section of the file system for the core Web files, such
as the Division home page, help areas, Web documentation, etc., it can be
accessed using the logical device WEB:[000000]. Incorporated with this are
other subdirectories providing storage for specific collections of data, such
as committee minutes, administration announcements, etc.

<P> Physically distinct areas are used for good physical reasons (e.g. the
area can best be hosted on a task-local disk), for historical reasons (e.g.
the area existed before any Web environment existed) or for reasons of
convenience (e.g. lets put this where access controls already allow the
maintainers to manage it). 

<P> Reasons for an area being physically integrated with the core Web data
area can be legitimate (e.g. there is really nowhere else it reasonably
belongs), convenience (e.g. let's quickly put it here) or by logical necessity
(it really does below as part of the core Web enviroment, e.g. documentation
on HTML, etc.)

<HEAD>(Guidelines\head_data_area_guidelines)

<P> In general, only Web-related files need to go into the core physical Web
file area. All other groupings should, if possible, be decentralised into the
portion of the file system they represent and logically placed in the server's
path using rules in the mapping file. That is, a given project's Web files
should be located in the project's part of the file system. If it doesn't have
any then it may be a candidate for location in the core area. 

<P> When locating a Web area in a physically distinct area it is possible the
maintainers of that data will already have the correct access controls. If
locating an area in the core hypertext environment it will be necessary to
give the mantainer ownership of the directory area (and possibly disk quota),
or provide ACL access if multiple maintains are involved. 

<P> When locating Web-accessable data in a physically distinct area it will be
necessary to update the mapping file with a new rule (see
<REFERENCE>(chapter_mapping_rule)). If located within the core Web area the
rules do not need to be adjusted. 

<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 (see <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>
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.

<HEAD1>(VMS Account\head_server_account)

<HEAD>(The following provides <UNDERLINE>(a guide) to the account:\head_server_guide)

<CODE_EXAMPLE>
  Username: HTTP$SERVER                      Owner:  HyperText Daemon
  Account:  HTTPD                            UIC:    [377,377] ([HTTPD,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:       512  JTquota:       1024
  Prclm:         100  DIOlm:       512  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
(see <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 NETMBX, TMPMBX, PRMMBX, PSWAPM, 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,PRMMBX,PSWAPM,SYSLCK,SYSNAM,SYSPRV,WORLD) 
<ENDCODE_EXAMPLE> 

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

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(HTTPD$AUTH - \BOLD) location of the
authentication/authorization configuration file 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$CONFIG - \BOLD) location of the configuration file 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$MAP - \BOLD) location of the mapping rule file 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$MSG - \BOLD) location of the message file 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$SERVICE - \BOLD) location of the optional service
(virtual host) configuration file

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$SITELOG - \BOLD) location of the optional plain-text site
log file (see <REFERENCE>(head_server_revise))

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$GMT - \BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$LOG - \BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$SSL_CERT - \BOLD) when using the SSL executable this
logical locates the default certificate.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTTPD$STARTUP_SERVER<HELLIPSIS> - \BOLD) can be used to pass
parameters to HTTPd startup.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(CGI-BIN - \BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HT_AUTH - \BOLD) directory containing
authentication/authorization databases (files)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HT_EXE - \BOLD) directory containing the executable images

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HT_LOGS - \BOLD) optional definition, for convenient log 
file specification

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HT_SCRATCH - \BOLD) 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].

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HT_SERVER_LOGS - \BOLD) optional definition, for convenient 
detached server process log file specification 

<ENDLIST>

<P> The following logical name is created by the executing HTTP server and 
defines the name of the control mailbox:

<LIST>(UNNUMBERED)
<LE> <EMPHASIS>(HTTPD<EMPHASIS>(port)$CONTROL\BOLD)
<ENDLIST>

<P> The following logical names are created by the executing HTTP server if 
the HTTPd monitor utility is enabled:

<LIST>(UNNUMBERED)
<LE> <EMPHASIS>(HTTPD<EMPHASIS>(port)$COUNT1\BOLD)
<LE> <EMPHASIS>(HTTPD<EMPHASIS>(port)$COUNT2\BOLD)
<LE> <EMPHASIS>(HTTPD<EMPHASIS>(port)$PID\BOLD)
<LE> <EMPHASIS>(HTTPD<EMPHASIS>(port)$REQUEST\BOLD)
<ENDLIST>

<HEAD>(Server Process Logging Directory\head_log_directory)

<P> The server process log directory (output for the detached HTTP server 
processes) may require explicit access controls for the HTTPd account.  This 
can be done by applying an ACL similar to the following: 

<CODE_EXAMPLE>
  $ SET SECURITY HT_ROOT:[LOG]SERVER.DIR -
    /ACL=((IDENT=HTTP$SERVER,ACCESS=R+W+E, OPTIONS=DEFAULT), -
          (IDENT=HTTP$SERVER,ACCESS=R+W+E), -
          (IDENT=*,ACCESS=NONE, OPTIONS=DEFAULT), -
          (IDENT=*,ACCESS=NONE))
<ENDCODE_EXAMPLE>

<P> As with the ACL on the server executable this can be done once, at 
installation (or, if right over the top, at each server startup).  Appropriate 
disk quotas may also need to be applied.  Also see
<REFERENCE>(head_server_logging).

<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> The startup uses a system batch queue.  This is the only effective way to
initiate the server run-time under the server account across all VMS versions
(that the author knows of anyway, RUN/DETACHED/UIC only changes the UIC). 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 a dual purpose.

<LIST>(NUMBERED)

<LE> In a simple site setup 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.

<COMMENT>(HTML=<P>)

<LE> To customize the startup of a server it is recommended to copy the base
STARTUP_SERVER.COM to a file in the same directory named
STARTUP_SERVER_LOCAL.COM, remembering that the server account must be able to
access the procedure.

<P> Changes may then be made to this local copy to enable SYSUAF
authentication, define job-level logicals, etc.

<COMMENT>(HTML=<P>)

<LE> For a site that wishes to support different services across multiple
nodes in a cluster, or to support multiple HTTPd processes on the one system
(each by implication having differing services, see
<REFERENCE>(head_virtual_services)), this procedure acts as a template for
supporting these (and then is used in the same batch and detached manner
described above).

<P> After deciding on the organisation of nodes and/or services copy this
procedure, locating the files in the same directory as STARTUP.COM, and having
destination file names representing the nodes and/or ports desired.  Ensure any
copies have read and execute permission for the HTTP$SERVER account!

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)

<LE> If multiple nodes in a cluster are to provide different services then
create a file for each system as with the destination name being

<CODE_EXAMPLE>
  STARTUP_SERVER_nodename.COM
<ENDCODE_EXAMPLE>

<LE> If a single system is to provide multiple services using multiple
processes then the target file name must also include the identifying port
number (the first in the service list), as follows

<CODE_EXAMPLE>
  STARTUP_SERVER_nodename_port.COM
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> For any given system, STARTUP.COM searches for these, based on the node
name, and will execute any found, one per node and/or node-port. If none of
these are found it executes the basic STARTUP_SERVER.COM, which itself should
not be modified.

<P> Backward-compatibility is provided for pre-v5.3 installations, with
STARTUP.COM executing HT_ROOT:[HTTP$SERVER]HTTPD_BATCH.COM and
HT_ROOT:[HTTP$SERVER]HTTPD80.COM if none of the above are found.

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

<HEAD>(LOGIN.COM\head_login_com)

<P> This procedure provides the HTTP server account login control.

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

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

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

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(/ACCEPT=\BOLD) comma-separated list of hosts/domains allowed to
connect to the server

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/ALL[=string]\BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/AUTHORIZATION=[SSL,ALL]\BOLD) the <QUOTE>(SSL) keyword causes
all authentication (both SYSUAF and HTA database) to be available only via
<QUOTE>(https:) requests.  See <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. See <REFERENCE>(head_auth_policy).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/CGI_PREFIX=\BOLD) 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) 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/DETACH=\BOLD) 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).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/DO=\BOLD) command to be performed by the executing server (see
<REFERENCE>(head_httpd_control))

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/FILBUF=\BOLD) 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) 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/FORMAT=\BOLD) overrides the configuration parameter
[LogFormat]

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/REJECT=\BOLD) comma-separated list of hosts/domains not
allowed to connect to the server

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/[NO]LOG[=name]\BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/NETBUF=\BOLD) minimum number of bytes in the network read 
buffer

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/PERIOD=\BOLD) overrides the configuration parameter
[LogPeriod]

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/PERSONA[=string]\BOLD) enables detached process scripting. 
When used without the optional string all accounts (appropriately mapped of
course) may have scripts executed under them.  If the optional string is
supplied it specifies the name of a rights identifier the account must be
granted before scripts can be activated under it.  See <QUOTE>(Scripting
Overview, Introduction) for further detail. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/PORT=\BOLD) 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).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/PRIORITY=\BOLD) server process priority (default is 4)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/[NO]PROFILE\BOLD) allows SYSUAF-authenticated username
security profiles to be used for file access (see
<REFERENCE>(head_auth_sysuaf)

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/SERVICE=\BOLD) comma-separated, list of server services
(overrides the [Service] configuration parameter)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/[NO]SSL[=version]\BOLD) 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.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/SUBBUF=\BOLD) number bytes in a subprocess' SYS$OUTPUT buffer

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/[NO]SWAP\BOLD) controls whether the server process may be 
swapped out of the balance set (default is swapping disabled)

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/VERSION\BOLD) merely displays the executable's version string
and the copyright notice

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(/[NO]WATCH=\BOLD) controls the use of the WATCH reporting
facility.  See <REFERENCE>(chapter_watch) for further details.

<ENDLIST>

<P> <EMPHASIS>(Note: \BOLD) buffer sizes apply on a per-request (thread) 
basis, and may be tailored for specific environments at server startup. 

<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 /ALL qualifier (for most directives).  Of
course, these commands are available from batch jobs as well as interactively.
The same functionality is available from the on-line Server Administration
Menu.

<HEAD3>(Accounting\head_server_accounting)

<P> Server counters may be zeroed.  These counters are those visible from the
<EMPHASIS>(statistics) admininstration menu 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 (see <REFERENCE>(head_auth_cache)).

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

<HEAD3>(Cache\head_server_cache)

<P> Server cache control may also be exercised from the server administration
menu, see <REFERENCE>(chapter_server_admin).  The file cache (see
<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>(Logging\head_server_logging)

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

<P> Open a log file. 

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

<P> Optionally open and specify a log file name.  This overrides any
/LOG=<EMPHASIS>(file-name) or HTTPD$LOG specified file name.
The /ALL qualifier is not available. 

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

<P> The log file may be closed and reopened using a different name (allowing
continuous operation but, for example, with daily log files). This overrides
any /LOG=<EMPHASIS>(file-name) or HTTPD$LOG specified file name. 
The /ALL qualifier is not available. 

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

<P> Close the log file. 

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

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

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

<P> The format and period specification of the log may be changed (only takes
effect after the next log file open/reopen).
The /ALL qualifier is not available. 

<CODE_EXAMPLE>
  $ HTTPD /DO=LOG=FORMAT=string
  $ HTTPD /DO=LOG=PERIOD=string
<ENDCODE_EXAMPLE>

<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
menu, see <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> This variant restarts the server immediately regardless of existing
connections.

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

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