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

<CHAPTER>(DECnet & OSU\chapter_scripting_decnet)

<P> <EMPHASIS>(<QUOTE>(Imitation is the sincerest form of flattery))
- proverb

<NOTE>(Please Note)
WASD requires no additional configuration to support subprocess-based
scripting.  The following information applies only if DECnet-based scripting
is desired.
<ENDNOTE>

<P> By default WASD executes scripts within subprocesses, but can also provide
scripting using DECnet for the process management. DECnet scripting is not
provided to generally supplant the subprocess-based scripting but augment it
for certain circumstances:

<LIST>(UNNUMBERED)

<LE> To provide an environment within WASD where OSU-based scripts (both CGI
and OSU-specific) may be employed without modification.

<COMMENT>(HTML=<P>)

<LE> To allow nodes without a full HTTP service to participate in providing
resources via a well-known server, possibly resources that only they have
access to.

<COMMENT>(HTML=<P>)

<LE> Load-sharing amongst cluster members for <EMPHASIS>(high-impact) scripts
or particularly busy sites.

<COMMENT>(HTML=<P>)

<LE> Provide user-account scripting.

<ENDLIST>

<HEAD>(DECnet Performance\head_decnet_performance)

<P> Any DECnet based processing incurs some overheads.

<LIST>(UNNUMBERED)

<LE> connection establishment
<LE> NETSERVER image activation
<LE> NETSERVER maintenance (such as logs, etc.)
<LE> activation of DECnet object image or procedure
<LE> DECnet object processing
<LE> activation by object of image or procedure
<LE> DECnet object run-down
<LE> NETSERVER image reactivation on completion of object processing

<ENDLIST>

<P> As of version 5.2 WASD provides reuse of DECnet connections for both CGI
and OSU scripting, in-line with OSU v3.3 which provided reuse for OSU scripts.
This means multiple script requests can be made for the cost of a single DECnet
connection establishment and task object activation. This functionality
provides substantial performance improvements as indicated by
<QUOTE>(Technical Overview, Performance, DECnet Observations). Note that the
OSU task procedure  requires the definition of the logical name
WWW_SCRIPT_MAX_REUSE representing the number of times a script may be reused.
The WASD startup procedures can provide this.

<P> In practice both the WASD CGI and OSU scripts seem to provide acceptable
responsiveness.

<HEAD>(Rule Mapping\head_decnet_mapping)

<P> DECnet-based scripts are mapped using the same rules as subprocess-based
scripts, using the SCRIPT and EXEC rules (see
<QUOTE>(Technical Overview, Mapping User Directories) for general information
on mapping rules). DECnet scripts have a DECnet node and <EMPHASIS>(task
specification string) as part of the mapping rule. There are minor variations
within these to further identify it as a WASD or an OSU script. See
<REFERENCE>(head_cgi_user_decnet) for information on mapping user scripting.

<P> The specification string follows basic VMS file system syntax (RMS),
preceding the file components of the specification.  The following example
illustrates declaring that paths beginning with FRODO will allow the execution
of scripts from the CGI-BIN:[000000] directory on DECnet node FRODO.

<CODE_EXAMPLE>
  exec /FRODO/* /FRODO::/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> In similar fashion the following example illustrates a script
<QUOTE>(frodo_show) that might do a <QUOTE>(SHOW SYSTEM) on node FRODO.  Note
that these rules are case-insensitive.

<CODE_EXAMPLE>
  script /frodo-showsys /frodo::/cgi-bin/showsys.com
<ENDCODE_EXAMPLE>

<P> Both of the above examples would use the WASD CGI DECnet environment (the
default if no task specification string is provided). By including task
information other environments, in particular the OSU scripting enviroment,
can be specified for the script to be executed within. The default task is
named CGIWASD and can also be explicitly specified (although this behaviour
would be the same as that in the first example)

<CODE_EXAMPLE>
  exec /frodo/* /frodo::"task=cgiwasd"/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> All task specification strings may also use zero as the task abbreviation.

<CODE_EXAMPLE>
  exec /frodo/* /frodo::"0=cgiwasd"/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> To execute a script within the OSU environment specify the standard OSU
task executive WWWEXEC, as in the following example:

<CODE_EXAMPLE>
  exec /osu/* /FRODO::"task=wwwexec"/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> This would allow any URL beginning with <QUOTE>(/osu/) to execute a script
in the OSU environment.

<HEAD>(Local System\head_decnet_local)

<P> To specify any script to execute on the same system as the HTTP server
specify the node name as zero or SYS$NODE.

<CODE_EXAMPLE>
  exec /decnet/* /0::"task=cgiwasd"/cgi-bin/*
  exec /osu/* /sys$node::"task=wwwexec"/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> Mapping rules are included in the examples

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

<COMMENT>(HTML=
(see <A HREF="/ht_root/example/">HT_ROOT:[EXAMPLE]</A>)
)

<COMMENT>(HTML/OFF)
(see HT_ROOT:[EXAMPLE])
<COMMENT>(HTML/ON)

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

providing this. After the DECnet environment has been started any CGI script
may be executed on the local system via DECnet by substituting
<QUOTE>(/decnet/) for <QUOTE>(/cgi-bin/) as the script path, and any OSU
script available by using <QUOTE>(/osu/). Behaviour is indeterminate, though
it shouldn't be catastrophic, if one is invoked using the incorrect path (i.e.
an OSU script using /decnet/ or a CGI script using /osu/).

<HEAD1>(Script System Environment\head_decnet_script_system)

<P> The target system must have sufficient of the WASD server environment
to support the required CGI script activation and activity. If the target
system is actually the same system as the HTTP server then it already exists,
or if part of the local system's cluster, then providing this should be
relatively straight-forward. If the target system has none of the server
environment then at a minimum it must have the logical name CGI-BIN
defined representing the directory containing the required DECnet object
procedure and scripts. The following fragment illustrates this:

<CODE_EXAMPLE>
  $ DEFINE /SYSTEM /TRANSLATION=(CONCEALED) CGI-BIN device:[dir.]
<ENDCODE_EXAMPLE>

<CP> In this directory must be located the WASDCGI.COM and WWWEXEC.COM
procedures required by the network task.  Of course other parts of the
environment may need to be provided depending on script requirements.

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

<HEAD2>(Proxy Access\head_decnet_proxy)

<P> The local system must have <EMPHASIS>(proxy access) to each target
scripting system (even if that <QUOTE>(target) system is the same system as
the HTTP server). This involves creating a proxy entry in each target hosts's
authorization database. The following example assumes the existance of a local
HTTP$SERVER account. If it does not exist on the target node then one must be
created with the same security profile as the HTTP server's.

<NOTE>(Caution!)
If unsure of the security implications of this action consult the relevant
VMS system management security documentation.
<ENDNOTE>

<P> The zero represents the system the server is currently executing on.

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> ADD /PROXY 0::HTTP$SERVER HTTP$SERVER /DEFAULT
<ENDCODE_EXAMPLE>

<P> It is necessary to ensure the account has permission to write into
it's home directory.  A network process creates a NETSERVER.LOG (Phase-IV) or
NET$SERVER.LOG (DECnet-Plus) file in the home directory, and will fail to start
if it cannot!

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

<HEAD2>(DECnet Objects\head_decnet_objects)

<P> To provide DECnet scripting DECnet <EMPHASIS>(object(s)) must be specified
for any system on which the scripts will be executed. The DECnet object is the
program or procedure that is activated at the target system inside of a
network-mode process to interact with the HTTP server.

<HEAD>(DECnet-Plus (OSI/Phase-V)\head_decnet_objects_plus)

<P> DECnet-Plus uses the NCL utility to administer the network environment. The
following NCL scripting shows the creation of a network application for the
WASD CGI object:

<CODE_EXAMPLE>
  $ MCR NCL
  CREATE NODE 0 SESSION CONTROL APPLICATION CGIWASD
  SET NODE 0 SESSION CONTROL APPLICATION CGIWASD ADDRESSES = {NAME=CGIWASD} -
  ,CLIENT =  -
  ,INCOMING ALIAS = TRUE -
  ,INCOMING PROXY = TRUE -
  ,OUTGOING ALIAS = FALSE -
  ,OUTGOING PROXY = TRUE -
  ,NODE SYNONYM = TRUE -
  ,IMAGE NAME = CGI-BIN:[000000]CGIWASD.COM -
  ,INCOMING OSI TSEL =
<ENDCODE_EXAMPLE>

<P> To create a DECnet-Plus OSU WWWEXEC object:

<CODE_EXAMPLE>
  $ MCR NCL
  SET NODE 0 SESSION CONTROL APPLICATION WWWEXEC ADDRESSES = {NAME=WWWEXEC} -
  ,CLIENT =  -
  ,INCOMING ALIAS = TRUE -
  ,INCOMING PROXY = TRUE -
  ,OUTGOING ALIAS = FALSE -
  ,OUTGOING PROXY = TRUE -
  ,NODE SYNONYM = TRUE -
  ,IMAGE NAME = CGI-BIN:[000000]WWWEXEC.COM -
  ,INCOMING OSI TSEL =
<ENDCODE_EXAMPLE>

<P> These must be executed at each system (or server) startup, and may be
executed standalone, as illustrated, or incorporated in the NCL script
SYS$STARTUP:NET$APPLICATION_STARTUP.NCL for automatic creation at each system
startup.

<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].
<COMMENT>(HTML/ON)

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

<HEAD>(Phase-IV\head_decnet_objects_iv)

<P> DECnet Phase-IV uses the NCP utility to administer the network
environment. The following NCP commands may be used each time during server
startup to create the required DECnet objects. With Phase-IV the SET verb may
be replaced with a DEFINE verb and the commands issued just once to
permanently create the objects (a SET must also be done that first time to
create working instances of the DEFINEd objects).

<P> To create a DECnet CGI object:

<CODE_EXAMPLE>
  $ MCR NCP
  SET OBJECT CGIWASD NUMBER 0 FILE CGI-BIN:[000000]CGIWASD.COM
<ENDCODE_EXAMPLE>

<P> To create a DECnet OSU WWWEXEC object:

<CODE_EXAMPLE>
  $ MCR NCP
  SET OBJECT WWWEXEC NUMBER 0 FILE CGI-BIN:[000000]WWWEXEC.COM
<ENDCODE_EXAMPLE>

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

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

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

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

<HEAD2>(Reducing Script Latency\head_decnet_latency)

<P> Script system network process persistance may be configured using
NETSERVER logical names. These can control the number and quiescent period of
the server processes. These logical names must be defined in the LOGIN.COM of
the HTTP server account on the target script system.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(NETSERVER$SERVERS_<EMPHASIS>(username) - \BOLD) This logical
controls the number of network server processes that are kept available at any
one time. Defining this logical results in a minimum of the specified number
of quiescent server processes maintained. This can improve script response
latency by circumventing the need to create a process to service the request,
at the cost of cluttering the system with NETSERVER processes.

<CODE_EXAMPLE>
  DEFINE /JOB NETSERVER$SERVERS_HTTP$SERVER 5
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(NETSERVER$TIMEOUT - \BOLD)
This logical controls the duration a quiescent network process persists
before being deleted. The default period is five minutes. The following
examples first show reducing that to thirty seconds, the second increasing it
to one hour. Again, this can improve script response latency by circumventing
the need to create a process to service the request, at least during the
period a previously created process continues to exist.

<CODE_EXAMPLE>
  DEFINE /JOB NETSERVER$TIMEOUT "0 00:00:30"
  DEFINE /JOB NETSERVER$TIMEOUT "0 01:00:00"
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<HEAD2>(DECnet/OSU Startup\head_decnet_startup)

<P> The example STARTUP.COM and STARTUP_DECNET.COM procedures found in the

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

<COMMENT>(HTML=
<A HREF="/ht_root/example/">HT_ROOT:[EXAMPLE]</A>)

<COMMENT>(HTML/OFF)
HT_ROOT:[EXAMPLE]
<COMMENT>(HTML/ON)

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

directory provide the essentials for DECnet/OSU scripting.  If the INSTALL.COM
startup environment is used setting the PROVIDE_DECNET symbol to 1 in
STARTUP.COM will create the DECnet scripting environment during server startup.

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

<HEAD1>(CGI\head_decnet_cgi)

<P> CGI scripts that use HTTP GET (the default) may be transparently executed
within the DECnet scripting environment. This means that the script is
executed within a network process, on the target system (which could be the
local system), instead of within a subprocess on the local system. Other than
that the WASD DECnet CGI environment behaves identically to the standard
subprocess CGI environment. CGIplus scripting is not supported and if
CGIplus-only scripts are executed the behaviour is indeterminate.

<P> Scripts that wish to use HTTP POST will need to read the request body from
the NET$LINK stream, rather than from HTTP$INPUT as with subprocess based
scripts.  End of body is indicated by an empty record rather than EOF.  Scripts
may quite simply be made to function appropriately in both environments.  The
following C code fragment illustrates this.

<CODE_EXAMPLE>
  if (getenv ("NET$LINK") == NULL)
  {
     /* via subprocess CGI */
     while (ReadCount = fread (Buffer, 1, sizeof(Buffer), stdin))
     {
        /* processing, processing ... */
     }
  }
  else
  {
     /* via DECnet CGI */
     if ((stdin = freopen ("NET$LINK", "r", stdin)) == NULL)
        exit (vaxc$errno);

     while (fgets (Buffer, sizeof(Buffer), stdin) != NULL)
     {
        /* check for end of stream */
        if (Buffer[0] == '\n' && Buffer[0] == '\0') break;

        /* processing, processing ... */
     }
  }
<ENDCODE_EXAMPLE>

<P> An example of making the HELP database on a system other than that hosting
the HTTP server (using the CONAN script) would be done using the mapping rules

<CODE_EXAMPLE>
  map /FRODO/help /FRODO/help/
  script /FRODO/help/* /FRODO::/cgi-bin/conan/*
<ENDCODE_EXAMPLE>

<CP> and for the example DCL SHOW script

<CODE_EXAMPLE>
  script /FRODO/show* /FRODO::/cgi-bin/show*
<ENDCODE_EXAMPLE>

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

<HEAD1>(OSU (DECthreads) Emulation\head_decnet_osu)

<P> The OSU, or <EMPHASIS>(DECthreads) server is the most widely deployed VMS
HTTP server environment, authored by David Jones and copyright the Ohio State
University. See

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

<COMMENT>(HTML=
<A HREF="http://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html">
http://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html</A>
)

<COMMENT>(HTML/OFF)
http://kcgl1.eng.ohio-state.edu/www/doc/serverinfo.html
<COMMENT>(HTML/ON)

for more information.

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

<P> The WASD HTTP server provides an emulation of the OSU scripting
environment. This is provided so that OSU-based scripts (both CGI-style and
OSU-specific) may be employed by WASD with no modification. As this emulation
has been designed through examining OSU code and lots of trial and error it's
behaviour may be incomplete or present errors. A list of OSU scripts known to
work with WASD is provided at the end of this section, see
<REFERENCE>(head_decnet_osu_known).

<P> Supported scripts include only those that depend on the OSU WWWEXEC object
and dialog for all functionality. Any script that uses other OSU-specific
functionality is not supported. Interactions between WASD's and OSU's
authentication/authorization schemes may be expected.

<P> OSU scripts expect to get the path information unmapped, whereas WASD
always additionally maps any path after the script component has been derived
from the request URI.  It may be necessary to ensure OSU scripts are activated
with the associated path SET to provide what they expect.  For example:

<CODE_EXAMPLE>
  set /htbin/* mapONCE
  set /osu/* mapONCE
<ENDCODE_EXAMPLE>

<P> The author would like to know of any OSU scripts the WASD emulation
<EMPHASIS>(barfs) on, and will attempt to address the associated limitation(s)
and/or problem(s).

<HEAD>(OSU Setup\head_decnet_osu_setup)

<P> Software necessary for supporting the OSU scripting environment (e.g.
WWWEXEC.COM) and selected OSU scripts (mainly for testing purposes) have been
extracted from the OSU v3.4 package and included in the

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

<COMMENT>(HTML=
<A HREF="/ht_root/src/osu/">HT_ROOT:[SRC.OSU]</A>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.OSU]
<COMMENT>(HTML/ON)

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

directory.  This has been done within the express OSU licensing conditions.

<CODE_EXAMPLE>
  Copyright 1994,1997 The Ohio State University.  
  The Ohio State University will not assert copyright with respect
  to reproduction, distribution, performance and/or modification 
  of this program by any person or entity that ensures that all 
  copies made, controlled or distributed by or for him or it bear 
  appropriate acknowlegement of the developers of this program.
<ENDCODE_EXAMPLE>

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

<P> An example DECnet and OSU scripting startup may be found in

<COMMENT>(HTML=
<A HREF="/ht_root/example/">HT_ROOT:[EXAMPLE]</A>.
)

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

This should be called from or used within the HTTP server startup. It includes
two logical definitions required for common OSU scripts. Other tailoring may
be required for specific OSU scripts.

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

<HEAD>(OSU - General Comments\head_decnet_osu_comments)

<P> David Jones, the author of the DECthreads (OSU) HTTP server, outlines his
reasons for basing OSUs scripting on DECnet (reproduced from a USENET NEWS
reply to a comment this author made about DECnet-based scripting).

<CODE_EXAMPLE>
  ------------------------------------------------------------------------

  From           JONESD@er6.eng.ohio-state.edu (David Jones)
  Organization   The Ohio State University
  Date           12 Aug 1997 09:04:11 GMT
  Newsgroups     vmsnet.sysmgt,comp.os.vms,comp.infosystems.www.servers.misc
  Message-ID     <LITERAL>(<5sp8ub$brs$1@charm.magnus.acs.ohio-state.edu>)

  ------------------------------------------------------------------------

  <EMPHASIS>(<HELLIPSIS> some text omitted)

  Since I was comfortable with DECnet, I based the scripting system
  for the OSU server around it.    The key reasons to use netserver
  processes rather than spawning sub-processes:

      1. DECnet automatically caches and re-uses netserver processes,
         whereas there were well-known performance problems with spawning
         sub-processes.

      2. DECnet processes are detached processes, so you don't worry about
         the effect of scripts consuming pooled quotas (e.g. bytlm) on
         the HTTP server process.

      3. Creation/connection with the DECnet server process is asynchronous
         with respect to the server so other operations can proceed concurrently.
         Spawning is done in supervisor mode, blocking the server's operation
         until the child process is completely initialized.

      4. With DECnet, scripts can be configured to run on different nodes
         for load balancing.

      5. In addition to the standard 'WWWEXEC' object, you can create
         other 'persistent' DECnet objects that the server communicates with
         as scripts. (this was implemented years before OpenMarket's FastCGI
         proposal).

      6. CGI is not the be-all end-all of scripting.  The dialog phase of
         OSU's scripting environment allows scripts to do things CGI
         is incapable of, such as ask the server to translate an arbitrary
         path and not just what followed the script name in the URL.

  People grouse all the time about the installation difficulties caused by
  it's reliance on DECnet,  the reason shown above were cited to show that it
  wasn't made so capricously.

  <EMPHASIS>(<HELLIPSIS> some text omitted)

  David L. Jones               |      Phone:    (614) 292-6929
  Ohio State Unviversity       |      Internet:
  2070 Neil Ave. Rm. 122       |               jonesd@kcgl1.eng.ohio-state.edu
  Columbus, OH 43210           |               vman+@osu.edu

  Disclaimer: Dogs can't tell it's not bacon.
<ENDCODE_EXAMPLE>

<P> The OSU server's DECnet scripting is not based on arbitrary
considerations. This author does not disagree with any of the concerns, and as
may be seen from WASD documentation the design of WASD also directly addresses
points 1, 3 and 5 with the use of persistant subprocesses and CGIplus.
Certainly DECnet-based scripting addresses the very legitimate point 4 (and
also allows nodes with specific resources to participate without installing
full HTTP server environments). Point 2 is not an issue with the use of
detached scripting processes, or for all practical purposes addressed by
adjusting account quotas to support the required number of subprocesses. Point
6 is only too true (possibly at least until Java servers and
<EMPHASIS>(servlets) become ubiquitous :^)

<HEAD>(Known Working Scripts\head_decnet_osu_known)

<P> The following is a list of OSU-specific scripts that the WASD
implementation has either been developed or tested against, and any
installation notes or other WASD specifics. The author would like to know of
any OSU scripts the WASD emulation has problems or works successfully with.

<LIST>(UNNUMBERED)

<LE> All of the scripts, etc. provided in the

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

<COMMENT>(HTML=
<A HREF="/ht_root/src/osu/">HT_ROOT:[SRC.OSU]</A>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.OSU]
<COMMENT>(HTML/ON)

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

directory.  These include:

<LIST>(UNNUMBERED)
<LE> cgi_symbols
<LE> cgi-mailto
<LE> html_preproc
<LE> set_dcl_env
<LE> testcgi
<LE> testform
<LE> tmail
<LE> vmshelpgate
<LE> webbook
<ENDLIST>

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(helpgate\BOLD)
<P> Comment out the <EMPHASIS>(Conan The Librarian) mappings for the
<QUOTE>(/help) path and provide the following in HTTPD$MAP:

<CODE_EXAMPLE>
  # first make "/help" into a script specification
  map /help* /htbin/helpgate/help*
  # general rule mapping "/htbin" to OSU DECnet scripts
  exec /htbin/* /0::"0=wwwexec"/cgi-bin/*
  # map the non-script part of the path back to just "/help"
  pass /htbin/helpgate/help* /help*
<ENDCODE_EXAMPLE>

<CP> It is possible to support both HELP environments (although
<EMPHASIS>(helpgate) will not work without owning the <QUOTE>(/help) path),
merely provide another mapping for <EMPHASIS>(Conan) with a slightly different
path, for example:

<CODE_EXAMPLE>
  map /chelp /chelp/
  script /chelp/* /cgi-bin/conan/*
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(HTML pre-processor\BOLD)
<P> Yes, backward compatibility can be provided for those old OSU .HTMLX
files in your new WASD environment ;^) All that is needed is a file type
mapping to the script in the HTTPD$CONFIG configuration file.

<CODE_EXAMPLE>
  [AddType]
  .HTMLX  text/html  /htbin/html_preproc  OSU SSI HTML
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> showtime
<LE> mgmt

<ENDLIST>

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

<HEAD1>(User Scripts\head_cgi_user_decnet)

<P> The WASD DECnet environment provides a simple mechanism for executing
scripts within accounts other than the server's.  This allows configured users
to write and maintain scripts within their own areas and have them execute as
themselves.  Both standard CGI and OSU scripting may be provided for with this
facility.

<P> Of course there is always a down-side.  Be careful to whom this
capability is granted.  User scripts are executed within a user network-mode
process created by DECnet. Script actions cannot generally affect server
behaviour, but they can access any WORLD-readable and modify any WORLD-writable
resource in the system/cluster, opening a window for information leakage or
mischievous/malicious actions. Script authors should be aware of any potential
side-effects of their scripts and Web administrators vigilant against possible
destructive behaviours of scripts they do not author.

<P> User scripting is not enabled by default.  To provide this facility mapping
rules into the user area must be provided in much the same way as for user
directories, see <QUOTE>(Technical Overview, Mapping User Directories).  

<P> The <QUOTE>(EXEC) rule provides a wildcard representation of users'
script paths. As part of this mapping a subdirectory specifically for the web
scripts should always be included. <EMPHASIS>(Never\BOLD) map users' top-level
directories. For instance if a user's account home directory was located in the
area WWW_USER:[DANIEL] the following rule would potentially allow the user
DANIEL to provide scripts from the home subdirectory [.WWW.CGI-BIN] using the
accompanying rules (first for CGI, second for OSU scripts):

<CODE_EXAMPLE>
  exec /~*/cgi-bin/* /0""::/www_user/*/www/cgi-bin/*
  exec /~*/osu-bin/* /0""::"0=wwwexec"/www_user/*/www/cgi-bin/*
<ENDCODE_EXAMPLE>

<P> Scripts located in these directories are accessable via paths such as the
following:

<CODE_EXAMPLE>
  /~daniel/cgi-bin/test
<ENDCODE_EXAMPLE>

<HEAD>(Explicit User Account\head_decnet_explicit_user)

<P> Using mapping rules it is possible to explicitly specify the user account
for a particular script or scripts to be executed within.  This may be useful
if an application has quota or other resource requirements that are desired to
be withheld from the HTTP server account (i.e. it can provide a measure of
isolation between the server and application accounts).

<CODE_EXAMPLE>
  exec /whatever-bin/* /0"WHATEVER"::/whatever_root/cgi-bin/*
  script /dowhatever/* /0"WHATEVER"::/whatever_root/cgi-bin/dowhatever/*
<ENDCODE_EXAMPLE>

<HEAD>(Proxy Access\head_cgi_user_proxy)

<P> For each user account permitted to execute local scripts proxy access to
that account must be granted to the HTTP server account.

<NOTE>(Caution!)
If unsure of the security implications of this action consult the relevant
VMS system management security documentation.
<ENDNOTE>

<CODE_EXAMPLE>
  $ SET DEFAULT SYS$SYSTEM
  $ MCR AUTHORIZE
  UAF> ADD /PROXY <LITERAL>(<node>)::HTTP$SERVER <LITERAL>(<account>)
<ENDCODE_EXAMPLE>

<P> For example, the following would allow the HTTP server to execute scripts
on behalf of the username DANIEL.

<CODE_EXAMPLE>
  UAF> ADD /PROXY 0::HTTP$SERVER DANIEL
<ENDCODE_EXAMPLE>

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