[L-Soft(TM) logo] [Online manuals]

Installation guide for LISTSERV® 1.8d for OpenVMS™

Copyright © L-Soft International, 1994-1999

Last update: 1 March 1999



For changes  to LISTSERV from version  1.8c to 1.8d, please  download the
LISTSERV 1.8d release notes from ftp://ftp.lsoft.com/documents/relnotes .

There are now two versions of  LISTSERV: A "Classic" version and a "Lite"
version. For  a description of  the differences between  LISTSERV Classic
and LISTSERV Lite, please see the URL 

                 http://www.lsoft.com/listserv-lite.html

LISTSERV Lite is user-supported, via the mailing list

                   LISTSERV-LITE@PEACH.EASE.LSOFT.COM

Please do not send questions regarding LISTSERV Lite to L-Soft's normal
support addresses.

Contents:
 Statement of Year 2000 Compliance for L-Soft's Products
 Quick installation
 Technical requirements
 NJE mode vs TCP/IP mode
 The LISTSERV account
 The LISTSERV directory tree
 LISTSERV and MX
 LISTSERV and PMDF(R)
 Starting up LISTSERV
 LISTSERV Executables
 LISTSERV and JNET(R)
 IMPORTANT - License Activation Key
 Registering the server
 Automatic Registration for LISTSERV Lite Servers
 List creation
 Deleting a list
 Note to customers migrating from VM
 File server functions
 Installing the LISTSERV web archive and administration interface
 Failover facility
 Upgrading your LISTSERV installation
 Contacting L-Soft Support
 Documentation and where to get more help 

***********************************************************
* Statement of Year 2000 Compliance for L-Soft's Products *
***********************************************************

Beginning with version  1.8d, LISTSERV will be Year  2000 Compliant under
all supported architectures except for VM, contingent on operating system
support for Year 2000.

LISTSERV (and LMail)  for VM will become Year 2000  Compliant when L-Soft
no longer  has S/370  customers to  support (which  will happen  in 1999,
given that the version of VM used  on the S/370 platform is not Year 2000
Compliant and the S/370 does not support XA).

Beginning with version 1.1b, LSMTP will  be Year 2000 Compliant under all
supported architectures.

**********************
* Quick installation *
**********************

We recommend that you take a  few moments to read this installation guide
before starting the  installation of LISTSERV. The  software is delivered
in VMSINSTAL format, either on magnetic media or electronically, as a ZIP
file. To extract the VMSINSTAL savesets from the ZIP file, type:

 $ UNZIP :== $directory:UNZIP.EXE
 $ UNZIP xxxxxx.ZIP 

You can  get a copy  of UNZIP.EXE  from L-Soft, or  from a number  of FTP
servers. Then, to begin installation, login as SYSTEM and type:

 $@SYS$UPDATE:VMSINSTAL LSV018 directory

**************************
* Technical requirements *
**************************

LISTSERV requires:

1. VAX/VMS version 6.1 or higher, or OpenVMS AXP version 6.2 or higher.

2. Wingra Technologies' JNET(R) product, version 3.5 or higher, or any
TCP/IP product with a socket interface, such as MultiNet(R), UCX,
TCPware, or WIN/TCP. Other TCP/IP products may require you to relink the
LSV.EXE manually with the appropriate libraries. 

3. L-Soft international, Inc.'s, LSMTP mailer product, or MadGoat's
Message Exchange (MX) version 4.1 or higher, or Innosoft International's
PMDF(R) product, version 4.2 or higher. Please note that if you choose to
use LSMTP you must also install either MX or PMDF(R) if you want local
mail delivery to VMSMail mailboxes.

4. To reduce development costs in light of the dwindling number of VAX
customers, L-Soft switched from VAX C to DEC C with version 1.8c.
Thus, the DEC C RTL is now a pre-requisite for the VAX version of
LISTSERV. This RTL is included with VAX/VMS 6.1 or higher.

If your  TCP/IP package includes an  SMTP server, you may  wonder why you
need  to install  an additional  mail package  when you  have no  trouble
sending mail to/from the Internet with  what you have. The reason is that
you  need to  interface LISTSERV  to the  mail package  - when  a message
arrives for  the LISTSERV address,  or for one  of the mailing  lists, it
must  be passed  to LISTSERV  for processing.  Reading the  corresponding
MAIL.MAI files is not an  acceptable solution, because important SMTP and
RFC822 information  is lost in the  process of gatewaying the  message to
VMSmail. Thus, you  need an interface that intercepts  the message before
it is  passed to  VMSmail, and  delivers it to  LISTSERV. Both  LSMTP and
Version 4.1 of  MX include a built-in LISTSERV interface,  and L-Soft has
developed a LISTSERV "channel program" for PMDF(R) version 4.2 and above.
While you can of course use other mail packages if you develop a suitable
LISTSERV interface for them, it is simpler to install a product for which
the work has already been done and  tested. This is the reason why L-Soft
recommends the use  of either LSMTP, PMDF(R) or MX.  (Remember that LSMTP
does not interface  directly to VMSMail and you will  need either PMDF(R)
or MX  in addition to  LSMTP if you want  local mail delivery  to VMSMail
mailboxes.)

For more information on L-Soft's  LSMTP product, write to SALES@LSOFT.COM
or call +1 (800) 399-5449 (from the  US and Canada) or +1 (301) 731-0440.
You can also find more information about LSMTP at http://www.lsoft.com .

For more information  on PMDF(R), write to Sales@INNOSOFT.COM  or call +1
(818) 919-3600.  MX is a free  product, available via anonymous  FTP from
FTP.SPC.EDU and a number of other sites.

Note:

L-Soft  international,  Inc. ("L-Soft")  does  not  warrant or  make  any
representation  whatsoever  regarding  either  PMDF(R)  or  MX,  the  use
thereof, or the  results of such use, except insofar  as their ability to
successfully interface  to the  LISTSERV product  is concerned.  Under no
condition  shall L-Soft  be liable  for any  indirect, consequential,  or
incidental damage  arising from the  use, the result  of the use,  or the
inability to use  such products. The products are warranted  as per their
respective vendor's licensing agreements. 

***************************
* NJE mode vs TCP/IP mode *
***************************

LISTSERV  can operate  in  either TCP/IP  or NJE  mode.  In TCP/IP  mode,
LISTSERV communicates  with other  servers over  the Internet,  using the
SMTP protocol. In NJE mode, LISTSERV communicates with other servers over
BITNET, using  the NJE protocol.  It is  possible to install  support for
both TCP/IP and NJE modes, but only one mode can be active at a time.

NJE mode requires the JNET(R) software  package. JNET(R) is assumed to be
installed if  the JANSHR logical  name is  defined. JANSHR points  to the
JNET(R) shareable image.  JNET(R) does not need to have  been started for
NJE support to be installed. However, the JNET(R) logical names should be
defined before starting the installation.

TCP/IP mode requires one of several TCP/IP packages. Like JNET(R), TCP/IP
packages are identified by looking  for library or shareable image files.
Similarly, your  TCP/IP packages does not  need to have been  started for
TCP/IP  support to  be installed,  but the  logical names  do need  to be
defined. If multiple TCP/IP libraries are  found, you will be required to
choose one.  You should choose  the TCP/IP  package that will  be running
when LISTSERV  is running in TCP/IP  mode. If you later  decide to switch
TCP/IP packages, you will need to reinstall LISTSERV.

************************
* The LISTSERV account *
************************

The LISTSERV account will be created  by this installation if it does not
already exist. LISTSERV is created with the following settings:

        UIC     = the UIC specified
        Default = the root device and directory specified.
        Access  = Full Batch, No Network, No Local, No Dialup, and No
                  Remote.
        CPUTIME = 0 (no CPU Time limit)
        PGFLQUO = 32768 (for VAX) 65536 (for AXP)
        WSDEF   = 1024
        WSQUOTA = 2048
        WSEXTENT= 16384
        Privileges (Authorized and Default) = 
                  SYSNAM,SYSPRV,SYSLCK,TMPMBX[,EXQUOTA][,WORLD]

The UIC of  the LISTSERV account is  used as the owner UIC  for all files
created under LISTSERV_ROOT.  Thus, a user with the same  UIC as LISTSERV
will have full access to the LISTSERV files. Similarly, users in the same
UIC group as LISTSERV will have group access to the LISTSERV files. It is
recommended that LISTSERV  be given a unique  UIC in a group  that is not
populated by (nonprivileged) interactive users.

By  default, LISTSERV's  login  directory  is the  root  of the  LISTSERV
directory  tree. This  is not  a  requirement. The  only requirement  for
LISTSERV's login  directory is that  LISTSERV needs to have  write access
and enough disk quota (or EXQUOTA privilege) to create its .LOG files.

The access restrictions  on the LISTSERV account are  recommended but not
required.  Full batch  access is  required, since  the LISTSERV  detached
process  is  created by  SUBMITting  a  batch  job  under a  username  of
LISTSERV.

If disk  quotas are enabled  on the  device containing the  LISTSERV root
directory,  LISTSERV will  either need  the EXQUOTA  privilege or  a disk
quota entry on that device.

In addition to  the privileges listed above, you may  need to enable some
privileges  for  LISTSERV-NJE.   The  JNET(R)  "Application  Programmer's
Reference"  lists the  privileges required  for a  program that  uses the
JNET(R)  Application  Program  Interface.  If you  are  planning  to  run
LISTSERV in NJE mode, LISTSERV will  also need the privileges listed. For
versions 3.5 and  3.6 of JNET(R), the only  additional privilege required
is WORLD, which is automatically added when you select NJE support. 

*******************************
* The LISTSERV directory tree *
*******************************

You will be required to specify  the root of the LISTSERV directory tree.
If the  LISTSERV account  already exists,  it will  default to  the login
directory of the LISTSERV account. LISTSERV refers to this directory tree
by the  concealed logical  name LISTSERV_ROOT. The  following directories
are created by the installation:

        LISTSERV_ROOT:[000000]  - where the .EXE and startup files are
                                  located.
        LISTSERV_ROOT:[MAIN]    - where most data files are located.  Also,
                                  used as a work area.
        LISTSERV_ROOT:[SPOOL]   - Incoming and outgoing mail spool directory.
        LISTSERV_ROOT:[TMP]     - Temporary (scratch) file directory.

*******************
* LISTSERV and MX *
*******************

Message Exchange  (MX) is a  freeware electronic mail  interface. Version
4.1  introduced  some additional  LISTSERV  support.  MX now  includes  a
LISTSERV agent which communicates directly with the local LISTSERV server
passing on commands. If MX V4.1  is installed and the LISTSERV support is
installed but  not enabled, the  installation will attempt to  enable the
LISTSERV support.  Like JNET(R), MX does  not need to be  started for the
installation to determine  that it is there, but the  MX logical names do
need to be defined.

Once the installation is finished, if  MX is already running and you wish
to start the LISTSERV agent, use the following commands:

     $ @SYS$STARTUP:LISTSERV_STARTUP LOGICALS
     $ @SYS$STARTUP:MX_STARTUP LSV
     $ RUN MX_EXE:MCP
     MCP> RESET ROUTER/CLUSTER
     MCP> EXIT 

This sequence of commands will not  be needed to start the LISTSERV agent
every time. If you enable the  LISTSERV support in MX, the LISTSERV agent
will be started every time that MX is started.

Note: You will need to reset the  MX ROUTER process every time you create
a new list.

************************
* LISTSERV and PMDF(R) *
************************

PMDF(R) is  a commercial electronic  mail interface produced  by Innosoft
International,   Inc.   This   installation   provides   an   executable,
PMDF_CHANNEL.EXE,   to   interface    between   PMDF(R)   and   LISTSERV.
PMDF_CHANNEL.EXE uses  the PMDF(R)  Application Program  Interface, which
was  introduced in  version 4.2.  The  installation uses  several of  the
PMDF(R) logical  names, so,  like JNET(R),  PMDF(R) does  not need  to be
started, but the logical names need to be defined.

If  PMDF(R) version  4.2 or  higher  is found,  PMDF_CHANNEL.EXE will  be
copied to LISTSERV_ROOT:[PMDF] and  LSV_CHANNEL_MASTER.COM will be copied
to PMDF_COM:. LSV_CHANNEL_MASTER.COM is executed by PMDF(R) to handle the
LISTSERV channel; it contains the line:

     $ run listserv_root:[pmdf]pmdf_channel 

You will need to add  the following lines to PMDF_ROOT:[TABLE]PMDF.CNF to
activate the LISTSERV channel: 

     lsv_channel logging
     LISTSERV 

In   addition,  you   will  need   to  add   the  following   aliases  to
PMDF_ROOT:[TABLE]ALIASES:

        listserv:                     listserv@LISTSERV
        owner-listserv:               owner-listserv@LISTSERV

and for each of the mailing lists:

        listname:                     listname@LISTSERV
        owner-listname:               owner-listname@LISTSERV
        listname-request:             listname-request@LISTSERV
        listname-server:              listname-server@LISTSERV
        listname-search-request:      listname-search-request@LISTSERV
        listname-signoff-request:     listname-signoff-request@LISTSERV
        listname-subscribe-request:   listname-subscribe-request@LISTSERV
        listname-unsubscribe-request: listname-unsubscribe-request@LISTSERV

You will need  to add these eight  aliases for each new  mailing list you
create.

The LISTSERV_ROOT:[PMDF] directory will be  created if PMDF(R) support is
installed.  This  directory  should contain  the  following  PMDF-related
files:

        LINK_PMDF_CHANNEL.COM   - used to link a new version of
                                  PMDF_CHANNEL.EXE.  Needs to be done each
                                  time you install a new version of PMDF(R).
        LSV_MAILIN_RTN.OBJ      - object code for LISTSERV interface routines
        PMDF.OPT                - an options file specifying the PMDF(R)
                                  shareable image.
        PMDF_CHANNEL.C          - C source code for PMDF_CHANNEL.EXE.
        PMDF_CHANNEL.EXE        - LISTSERV channel program.
        PMDF_CHANNEL.OBJ        - object code for PMDF_CHANNEL.EXE

Note: PMDF_CHANNEL.EXE will  need to be relinked each time  you install a
new   version   of   PMDF(R).   The   following   command   will   relink
PMDF_CHANNEL.EXE:

     $ @LISTSERV_ROOT:[PMDF]LINK_PMDF_CHANNEL 

************************
* Starting up LISTSERV *
************************

The  LISTSERV  installation creates  SYS$STARTUP:LISTSERV_STARTUP.COM  to
start LISTSERV. It contains a hard  coded reference to the root directory
chosen during  the installation.  The other  startup files  determine the
root directory  by virtue of their  own location. Thus, if  you decide to
move   the   LISTSERV  root   directory,   you   will  need   to   modify
SYS$STARTUP:LISTSERV_STARTUP  to point  to  the new  root. The  following
startup files are located in the root directory:

        CREATE_LISTSERV.COM     - used to create the server process.
        GO.COM                  - executed by the server process to set up
                                  its environment.
        LISTSERV_CONFIGURE.COM  - the server configuration utility.
        LISTSERV_INSTALL.DAT    - lists the files to be installed at startup.
        LISTSERV__STARTUP.COM   - the real startup file.  It is executed by
                                  SYS$STARTUP:LISTSERV_STARTUP.COM.
        STOP_LISTSERV.COM       - send a STOP command to the server.

LISTSERV__STARTUP.COM  will  take  a   comma-separated  list  of  options
including LOGICALS, to define the  logical names; INSTALL, to install the
.EXEs;  and  START, to  start  the  server  process.  If no  options  are
specified, all three options are chosen.

GO.COM references  a couple  of files  in LISTSERV_FILES_DIR  (by default
LISTSERV_ROOT:[MAIN]): SYSTEM_CONFIG.DAT and SITE_CONFIG.DAT. These files
contain  process-table logical  names  that are  defined  for the  server
process. SYSTEM_CONFIG.DAT  contains the default  values. SITE_CONFIG.DAT
can  be  used   to  override  the  defaults.  You   should  confine  your
modifications to SITE_CONFIG.DAT. If SITE_CONFIG.DAT has not been created
at install  time, the installation  will create a  new one based  on some
questions asked. The installation will ask you to specify a value for the
following logical names:

        NODE            - the local node name. If you specify an Internet host
                          name, LISTSERV-TCP/IP will be enabled.  If you
                          specify a BITNET nodeid (without the .BITNET),
                          LISTSERV-NJE will be enabled.
        MYDOMAIN        - Lists the possible host names for this system.  If
                          this is a BITNET site, you should include the
                          nodeid and nodeid.BITNET forms.
        LOCAL           - Lists wildcarded host names that identify the
                          "local" mail.
        TZONE           - the Greenwich Mean Time offset for your location.
                          The value should take the form +hhmm or -hhmm.
                          For example, -0500 is the GMT offset for Eastern
                          Standard time.  Timezone abbreviations such as
                          EST, CET, JST, etc. will also work.
        CREATEPW        - the password required to create a list.
        STOREPW         - the password required for other privileged
                          commands.
        POSTMASTER      - lists the addresses of people who manage LISTSERV
                          on this system.  If a user appears in the list,
                          they are authorized to send privileged commands.
                          IF a user appears in the list, but not after a
                          "quiet:". they will be notified of server errors.
        STARTMSG        - lists the addresses of users to be notified when
                          the server starts.
        MYORG           - your "organization name."   This appears on the
                          "From:" line of messages from LISTSERV, so you
                          should try to keep it short to avoid a multi-line
                          "From:."

LISTSERV_CONFIGURE.COM  can  be  used  to update  the  values  stored  in
SITE_CONFIG.DAT. If you make modifications  while the LISTSERV process is
running, you  will need  to restart  it ($ LCMD  STOP REBOOT)  before the
changes will take effect.

To start LISTSERV at system startup, you should add the following command
to the system startup command procedure:

     $ @SYS$STARTUP:LISTSERV_STARTUP 

LISTSERV should be started after JNET(R) or your TCP/IP package depending
upon whether you are running in NJE  or TCP/IP mode. If have installed MX
along  with its  LISTSERV support,  you will  need to  add the  following
commands to the system startup command procedure:

     $ @SYS$STARTUP:LISTSERV_STARTUP LOGICALS
     $ @SYS$STARTUP:MX_STARTUP
     $ @SYS$STARTUP:LISTSERV_STARTUP 

This sequence  of commands  should replace  the "@SYS$STARTUP:MX_STARTUP"
that started MX.  Note: if you are  running LISTSERV in NJE  mode and the
server reports an error starting the  JNET(R) interface, make sure it has
the necessary privileges. If you had  to abort it with STOP/ID or Ctrl-Y,
you may have to issue the following command: 

     $ JCP REMOVE/HOOK LISTSERV 

************************
* LISTSERV executables *
************************

The LISTSERV installation is responsible for providing three executables:
LSV.EXE, LSV_MAILIN.EXE, and LCMD.EXE. LSV.EXE is the program that is run
by  the server  process.  LSV_MAILIN.EXE is  a  standalone incoming  mail
interface for LISTSERV. It allows you  to route mail to LISTSERV from DCL
level. By  default, LSV_MAILIN.EXE is  not installed with  privileges. If
you plan to use LSV_MAILIN.EXE, it  will either need to be installed with
or run from an account that has SYSLCK and SYSPRV.

LCMD.EXE is used  to send commands directly to the  local server (instead
using mail or  going going through the NJE interface).  Commands sent via
LCMD are executed ahead of commands  received via mail or NJE files; this
can  be  particularly useful  when  the  server is  backlogged.  LCMD.EXE
requires SYSPRV and  SYSLCK. However, if you wish to  allow general users
to use  LCMD, you  can install  it with  those privileges.  LCMD.EXE also
needs to be  able to create files within  LISTSERV_SPOOL_DIR. The default
LISTSERV_SPOOL_DIR,  LISTSERV_ROOT:[SPOOL]  is   created  with  a  SYSTEM
protection of RWE, allowing users with  SYSPRV to create files within it.
If  you relocate  LISTSERV_SPOOL_DIR, you  will need  to keep  SYSTEM:RWE
protection on the directory file.

LCMD must  be defined as  a DCL verb.  If you choose  not to add  LCMD to
DCLTABLES, you will need to add it to your process command table with the
following command: 

     $ SET COMMAND LISTSERV_ROOT:[000000]LCMD 

LISTSERV_ROOT:[000000]LCMD.CLD  is the  command definition  file for  the
LCMD command. Consult the SET  COMMAND documentation for more information
on DCL verbs and command tables.

In addition  to adding LCMD to  DCLTABLES, the installation will  add the
help  for LCMD  to  the help  library of  your  choice. The  installation
displays  the names  of  the  help libraries  accessed  by  the DCL  HELP
command:  SYS$HELP:HELPLIB.HLB,  HELP_LIBRARY, HELP_LIBRARY_1,  etc.  The
help for LCMD will be available from  DCL ($ HELP LCMD) if you choose one
of     these      libraries.     The     help     text      for     LCMD,
LISTSERV_ROOT:[000000]LCMD.HLP, is provided if you later decide to add or
relocate the LCMD help.

************************
* LISTSERV and JNET(R) *
************************

You will need to make some modifications to JANTIDY.COM, if you use it to
restart JNET(R) every night. JANTIDY.COM needs to be modified to stop and
restart the LISTSERV process. The command to stop the LISTSERV process: 

     $ @LISTSERV_ROOT:[000000]STOP_LISTSERV 

needs to be placed before the  "jcp shutdown". The command to restart the
LISTSERV process is: 

     $ @SYS$STARTUP:LISTSERV_STARTUP START 

It needs to be placed after the "@janstart warm".

**************************************
* IMPORTANT - License Activation Key *
**************************************

Before you  can start  up LISTSERV,  you will need  to install  a License
Activation  Key  (LAK) for  'LISTSERV-VMS-xxx'  (xxx  =  AXP, VAX,  or  a
wildcard  for architecture-independent  licenses).  LAKs  are similar  to
PAKs, but  are installed differently.  The reason we  do not use  PAKs is
that we support LISTSERV on IBM(R) mainframes and unix(R) and Windows(tm)
systems, where PAKs  are not available. In order to  offer the same range
of  services on  all systems,  we had  to develop  our own  "license key"
scheme.  Using PAKs  for VMS(tm)  and LAKs  for other  system would  have
required us to develop two parallel authorization schemes, and would also
complicate the task of issuing  license keys to customers. Since LISTSERV
is a server and  typically runs on a single cluster  member, there was no
technical  advantage to  the  use  of PAKs,  other  than  having all  the
licensing information in a single place.

Just like PAKs,  LAKs are not included  in the VMSINSTAL kit  and must be
installed separately. However, since the LAK manager is part of LISTSERV,
you must install  LISTSERV (LSV018) before you can install  the LAK. Once
LISTSERV is installed, run: 

     $@SYS$STARTUP:LISTSERV_STARTUP LOGICALS 

and follow  the instructions in  the License Registration Form  that came
with your  media. For evaluation  kits, the License Registration  Form is
the  file called  LICENSE.MERGE  in  the directory  where  you found  the
VAX.ZIP or AXP.ZIP file. That file is also included in the ZIP files.

**************************
* Registering the server *
**************************

NOTE: This section does not apply  to evaluation kits or to LISTSERV Lite
kits. Evaluation copies of LISTSERV should not be registered because they
are (presumably)  temporary servers  running test lists,  whose existence
should not be broadcast. LISTSERV Lite  copies run only in TABLELESS mode
and  therefore  cannot be  registered  in  the  same manner  as  LISTSERV
Classic, nor may they participate in the LISTSERV backbone.

Once  the server  is ready  for production  use (that  is, once  you have
installed a permanent License Activation  Key, and once you have arranged
for LISTSERV to be started from the system startup procedure), you should
register it with L-Soft by filling in the enclosed registration form, and
returning it to Support@LSOFT.COM. Registering the server is necessary to
broadcast  its existence  to the  other LISTSERV  servers. Once  you have
registered, your  server will  be sent periodic  updates about  the lists
hosted by other LISTSERV sites, among other things, and, similarly, other
LISTSERV sites  will receive information  about the public lists  you are
hosting. Here is  the registration form (the fields you  must fill in are
represented as XXXXXXXX, or a suggested value is provided):

------------------------------- Cut here --------------------------------
:node.XXXXXXXX           ! - Internet hostname if running in TCP/IP mode
                         ! - BITNET nodeid if running in NJE mode
:userid.LISTSERV         ! Username under which LISTSERV runs
:net.XXXXXXXX            ! BITNET for NJE mode, Internet for TCP/IP mode
:site.XXXXXXXX           ! University of XYZ, city, state, country
:country.XX              ! Two-letter ISO country code
:system.OpenVMS Vx.y     ! VMS version
:machine.XXXXXXXX        ! Hardware - AXP 3000-600, VAX 9000, etc
:contact.XXXXXXXX        ! Contact person, in the following format:
                         !   (Joe Manager) JOE@XYZ.EDU (+1 301 871.2727)
:type.VMS                ! Do not change this - must be "VMS"
:version.1.8d            ! Version you are currently running
:backbone.XXXXXXXX       ! YES or NO, depending on whether you want to
                         ! participate in the LISTSERV backbone; L-Soft
                         ! will advise you on this keyword.
------------------------------- Cut here --------------------------------

****************************************************
* Automatic Registration for LISTSERV Lite Servers *
****************************************************

LISTSERV Lite  servers are  registered automatically  when you  start the
software for the  first time. This auto-registration is  not optional for
Free  Edition servers,  but may  be  disabled for  non-Free Edition  Lite
servers by specifying STANDALONE runmode (see "RUNMODE=" in Appendix C of
the Site Manager's Operations Guide).

The auto-registration allows you to take part in the global List of Lists
and CataList services maintained by L-Soft. Registrations are verified on
a  regular basis  by a  central L-Soft  server, which  sends out  several
informational commands that return  non-privileged information about your
server (anyone can  issue these commands). Since  these registrations are
maintained by regular  communication with your server,  please note that,
should  you  decommission  the server,  registration  verifications  will
continue to be  mailed to your server for several  days until the central
server decides that  your server is actually gone, and  not simply unable
to receive  mail for some  reason. Please note  carefully that it  is not
possible for L-Soft  to stop these registration queries  manually even if
you  write  to  us and  tell  us  that  the  server has  been  shut  down
permanently. They will stop after several days without a response.

*****************
* List creation *
*****************

In order to create a new list, you must: 

1. Prepare a "list header", for instance using the sample provided below.
You can also get the header of an existing (L-Soft) LISTSERV list and use
it as sample. 

2. Fill in the PW=CCCCCCCC on the first line with the "CREATEPW" you
chose when configuring LISTSERV. The PW=XXXXXXX line at the end defines
the password you want to assign to your list. This is the password that
the list owner will have to supply with sending commands via mail, if you
select "Validate= Yes". Alternatively, you can select "Validate=
Yes,Confirm" to use the "OK" mechanism, which does not require any
password. 

3. Mail the resulting file to the LISTSERV address, from a username
defined as "postmaster" in the LISTSERV configuration. For instance:

        $ MAIL
        MAIL> send newlist.create
        To:     mx%"listserv@xyz.edu"
        Subj:
      
        MAIL>

If you have questions about  list creation, keywords, list management and
other high-level or system-independent LISTSERV topics, the best place to
ask them is the LSTOWN-L list, an open forum of LISTSERV list owners.

Please note that, for security  reasons, LISTSERV will not create archive
directories  automatically. You  must create  the directory  and set  the
protections before  storing the list.  LISTSERV will need RWED  access to
the directory; since LISTSERV runs with  SYSPRV, it is sufficient to have
S:RWED protection on the directory.

For  assistance  with problems  specific  to  evaluation kits,  join  the
LSTSRV-E list  or contact  Support@LSOFT.COM for  a prompt  reply. Please
don't  forget to  tell  us  which mail  system  (LSMTP,  PMDF(R) or  MX),
transport (JNET(R),  MultiNet(R), etc) and  which version of  VMS(tm) you
are running!

------------------------------- Cut here --------------------------------
PUT SAMPLE.LIST PW=CCCCCCCC
*
*  Title of sample LISTSERV list
*
*  Review= Public    Subscription= Open         Send= Public
*  Notify= Yes       Reply-to= List,Respect     Files= No
*  Stats=  Normal,Private                       Validate= No
*  Notebook= Yes,DISK2:[LISTS.PUBLIC],Monthly,Public
*
*  Owner=  someone@somewhere.EDU
*
* PW= XXXXXXXX
------------------------------- Cut here --------------------------------

Once  you have  constructed  a list  header  file, and  sent  it to  your
LISTSERV, you  need to instruct your  mail system to route  mail for that
new list to the LISTSERV interface.  Refer to the MX and PMDF(R) sections
of the present document for more information about this.

*******************
* Deleting a list *
*******************

While there  is no LISTSERV  command to delete  a list, the  procedure is
quite simple. Log  in to the listserv account (or  any other account with
administrative privileges in LISTSERV's directories), copy or archive any
files (list archives,  etc.) that you want  to keep to a  safe place, and
then use the VMS 'DELETE' command  to delete the list file. For instance,
if  you   are  deleting  a   list  called  'TEST.LIST',   simply  'DELETE
TEST.LIST;*' from  LISTSERV's 'MAIN'  directory. Optionally you  may also
remove the PMDF aliases,  but once the '.LIST' file is  gone, it has been
deleted as far as LISTSERV is concerned.

***************************************
* Note to customers migrating from VM *
***************************************

VM lists can be migrated to VMS with a much simpler procedure:

 A. Stop LISTSERV on VMS, and go to its [MAIN] directory.

 B. FTP a  copy of the xxxx.LIST file from the VM  system, in ASCII mode.
Note  that you  must grab  the  file as  it  appears on  the VM  server's
"A-disk". If  you send a  REVIEW command to the  VM LISTSERV, you  may be
sent a file called xxxx.LIST, but it is not suitable for migration: among
other things, it will not list subscribers with the "conceal" flag.

  C. If  the list  is  archived, edit  the  xxxx.LIST file  (which is  an
ordinary  text  file)  to  insert   a  suitable  directory  name  in  the
"Notebook=" keyword  (see example  below). Do not  modify the  lines with
subscriber names! The only lines you may  edit at this stage are the ones
starting with an asterisk.

 D. Start LISTSERV  on VMS. It will issue a  warning about incorrect list
format, and automatically convert it to the proper RMS attributes.

You  can  also FTP  the  archive  files  (xxxx.LOGyymm) directly  to  the
directory selected in point C.

*************************
* File server functions *
*************************

There are three file server systems currently in use or under development
for LISTSERV:

- The  VM  (mainframe)  version  of LISTSERV  continues  to  support  the
"traditional" file  server system. While  it is very powerful,  this file
server  system  dates back  to  1986  and  suffers  from a  few  annoying
limitations. In addition, it is written  in a non portable language. This
will be replaced eventually with  the "new" file server system, currently
under development.

- The  non-VM versions  of LISTSERV  1.8d  enhance further  the new  file
server  system introduced  in non-VM  1.8c,  which includes  most of  the
functionality of  the "traditional" file  system. Notably, GIVE  and file
"packages" are  now available.  Most end user  commands will  continue to
work as  before. However, there  is no  guarantee that the  internal data
files manipulated  by the  file server functions  will remain  as before.
Note that  SITE.CATALOG files from  versions 1.8a through 1.8c  are still
supported and will not need to be changed in order to work with 1.8d.

- The non-VM versions  of LISTSERV 1.8a and 1.8b  supported a "temporary"
file server system,  to provide an interim solution while  the new system
was being developed. This temporary system  only supports a subset of the
functions of the  traditional system. This system is  no longer supported
by  L-Soft as  it  has been  superseded  by the  new  non-VM file  server
referenced above.

In general, the three systems are compatible, with the understanding that
the temporary system does not  include all the possible options. However,
the mechanism  for registering  files (defining them  to the  file server
system) is different. 

Since the  first and  third systems  will eventually  be replaced  by the
second system, rather than providing  an exhaustive chapter detailing all
filelist aspects from the management side,  we have provided only a basic
overview  of the  two  systems currently  in the  field  with 1.8d,  with
pointers to where further information may be obtained.

The LISTSERV  maintainer stores "root-level"  file definitions in  a file
called SITE.CATALOG,  which should be  placed in the same  directory with
the  SYSTEM.CATALOG  file.  The   LISTSERV  maintainer  can  also  define
"sub-catalogs" which in turn can define further files. 

This installation guide will  discuss only "root-level" file definitions.
For information on "sub-catalogs" and  the file server in general, please
see chapter 8 of the Site Manager's Operations Manual.

LISTSERV version 1.8c  and later uses a file  archive registration system
similar to (but differing in important respects from) the old VM FILELIST
system. This  system is  available on  the VMS,  unix, and  Windows ports
only. VM sites will continue to  use the old FILELIST system indefinitely
as it still offers more functionality than the new system.

Files to be made generally available  to users (e.g., not specific to any
one list on  your server) should still be registered  in the site.catalog
file as before.

Prior to 1.8c, entries in site.catalog were written like this:

MY.FILE       MY.FILE.FILES:[XYZ]      ALL JOE@XYZ.COM               

In 1.8c a  new "native" format for these entries  was introduced, and the
new format is used  in all of the examples below.  The old format remains
supported  for compatibility.  However, note  that you  MUST use  the old
format if any of the directories in the path contains a period. 

Documented  restriction:  All  files  manipulated  by  LISTSERV  must  be
accessible through  LISTSERV's OS-independent  file access  methods. This
means that  files whose name  contains spaces or control  characters (or,
under unix, mixed  case characters) cannot be  accessed. Similarly, files
whose name does  not contain a period cannot be  manipulated by LISTSERV.
There is no limit  on the length of the file name,  only on its contents.
Note that these "system filenames" are  not visible to the end users, who
refer to the files by the names assigned in the catalog. 

To  register  a  new  file  to  the   server,  you  add  a  line  to  the
LISTSERV_ROOT:[MAIN]SITE.CATALOG file (create it if it did not exist). Do
not modify the SYSTEM.CATALOG file, as it  is part of LISTSERV and may be
replaced  when you  apply service.  Here is  what a  typical SITE.CATALOG
entry looks like:

MY.FILE         LISTSERV_ROOT:[FILES]MY.FILE    XXX YYY

The  first item,  MY.FILE, is  the name  by which  the file  is known  to
LISTSERV. That is, the users will use GET MY.FILE to order a copy of that
file.  The  name  should  only  contain one  period.  Only  the  first  8
characters of  the name and the  first 8 characters of  the extension are
shown by the INDEX command. This restriction will be removed with the new
file server system.

The second  item, for instance LISTSERV_ROOT:[FILES]MY.FILE,  is the name
LISTSERV will  use for the  actual disk file,  in native OS  format. Note
that the  directory must  be created  before you  register the  file. For
security  reasons, LISTSERV  will not  create the  directory (or  set the
protections) for you.  Note that LISTSERV will normally  need full access
to these files.

The third and  fourth items are "File Access Codes"  (FACs). The first is
for read accesses, and the second  for writing. The following file access
codes are available for non-VM servers:

ALL               universal access.
CTL               only the LISTSERV maintainers have access.
PRIVATE(xxx)      only members of the xxx list have access.
OWNER(xxx)        only the owners of the xxx list have access.
SERVICE(xxx)      only users in the service area of the xxx list have access.
NOTEBOOK(xxx)     same access as the archives of the xxx list.
user@host         the user in question is granted access.

Except for ALL  and CTL, which must  occur on their own,  you can specify
multiple  file  access  code  entries,  separated  by  a  comma  with  no
intervening space. For instance:

MY.FILE LISTSERV_ROOT:[FILES]MY.FILE JOE@XYZ.EDU,JACK@XYZ.EDU,PRIVATE(XYZ-L) CTL

defines a file that  Joe, Jack and the subscribers of  the XYZ-L list can
order via the  GET command, but that only the  LISTSERV administrator can
update.

IMPORTANT: LISTSERV does  not set file protection  attributes, ACLs, etc.
These attributes apply to LISTSERV commands (GET, PUT, INDEX) only; it is
your responsibility to  protect the actual VMS file by  setting the owner
UIC, protection and DEFAULT ACL on the directory in which it is created.

********************************************************************
* Installing the LISTSERV web archive and administration interface *
********************************************************************

1. Move the 'wa' executable from your ~listserv/ directory to the CGI
script directory for your web server. You can call it something else, but
a short name will help keep the HTML documents small! Under unix, make
the script run as suid listserv in order to allow it to access LISTSERV
archive files.

2. Create a subdirectory on your web server to contain the various files
LISTSERV will be creating. You should not use your main directory as
LISTSERV will create quite a few files! The suggested name is 'archives'.

3. Define the systemwide logical LISTSERV_WWW_ARCHIVE_PATH to point to
the directory you just created, and LISTSERV_WWW_ARCHIVE_URL with the URL
to the directory in question (preferably relative).

4. Modify LISTSERV's configuration to add two variables, as follows: 

   WWW_ARCHIVE_CGI is the relative URL that leads to the CGI script you
    have just installed. Typically this will be something like
    '/htbin/wa.exe'. This is a URL, not an OS path name. 

   WWW_ARCHIVE_DIR is the full path name to the directory you created in
    step 3. 

5. For each list that you want accessible through the web interface, you
must create a subdirectory in the directory you created in step 3, named
like the list. For instance, if you create 'archives/xyz-l', the list
XYZ-L will be accessible through the interface. Note that only lists with
public archives are ever made accessible, for security reasons. 

Reboot  LISTSERV.  It  should  create  a file  accessible  with  the  URL
http://localhost/archives/index.html, and  from there you should  be able
to access all the postings.

Complete information on installing the Web Archive Interface is contained
in chatper 5 of the Site Manager's Operations Manual.

*********************
* Failover facility *
*********************

LISTSERV  for VMS  now  includes "failover"  functionality. The  failover
facility  allows you  to build  a fully-redundant  LISTSERV configuration
based on an  OpenVMS cluster with shared mass storage  (CI, SCSI cluster,
etc.). Failover  can take place  among any number  of suitably-configured
VAX or  AXP nodes. Following  a failover, the service  will automatically
migrate back to the designated primary  when it is returned to operation.
A priority scheme  allows you to establish a hierarchy  of failover nodes
from most to least preferred (nodes with the same priority are treated as
peers).

The failover  facility requires a special  add-on license on top  of your
base  LISTSERV  license.  However,  only one  base  LISTSERV  license  is
required, regardless of the number of failover nodes. In other words, the
standby nodes  do not  consume a  license until they  take over  from the
primary, at which point the primary  has relinquished its use of the base
license.

For more  information on the  LISTSERV for VMS failover  facility, please
download our  white paper  "Implementing the LISTSERV  failover facility"
from ftp://ftp.lsoft.com/documents/WhitePaper-VMSfailover.txt .

****************************************
* Upgrading your LISTSERV installation *
****************************************

1. L-Soft recommends reading the release notes (available from
ftp://ftp.lsoft.com/documents) before proceeding with the upgrade. 

2. It is IMPERATIVE that you install a License Activation Key (LAK) for
version 1.8d before installing the new version of the software. Your 1.8d
license key will work with older versions of the product, but you will
not be able to start the new version unless your license key reads 1.8d
(you can verify that you have the proper license key by sending a SHOW
LICENSE command to LISTSERV and checking the "Version:" field). Please
contact your sales representative or write to SALES@LSOFT.COM if you did
not receive your new license key. 

*************************************************************************
* DO NOT PROCEED ANY FURTHER UNTIL YOU HAVE INSTALLED YOUR LICENSE KEY! * 
*************************************************************************

3. Connect to FTP.LSOFT.COM via anonymous FTP, CD LISTSERV, then go to
the subdirectory that corresponds to your operating system and download
the installation kit that matches your vendor/architecture, as if you
were planning to re-install LISTSERV from scratch. Customers running unix
should make sure to download both common.tar.Z and the system-specific
tar file. VM customers should download UPD18D HEX and HEXOUT EXEC in
ASCII mode (but not LISTSERV HEX). 

4. L-Soft recommends making a backup of your entire LISTSERV directory
tree before updating the code. 

5. Stop LISTSERV, then run VMSINSTAL on the new kit. The kit will
automatically update your previous installation. 

Contact L-Soft technical support if you have any question regarding the 
upgrade procedure. Please note that technical support is unable to assist
with licensing issues; you should contact the sales group in that case. 

*****************************
* Contacting L-Soft Support *
*****************************

At http://www.lsoft.com/lsv-faq.html we've attempted to document a few of
the most frequently-asked questions  pertaining to installing and running
a LISTSERV server.  Before writing to our support  department for problem
resolution, please take  a moment to read through the  online FAQ and see
if your problem is answered there.

L-Soft recognizes that the FAQ pages are not going to solve every problem
you may face. We are always willing to help diagnose and correct problems
you may be  having with your registered LISTSERV(R) server.  To that end,
please note the following when you write to L-Soft with a problem report:

1. Please make the subject line of your report indicative of the problem,
and in particular the product with which you are having a problem. A
subject like "Problem posting to moderated LISTSERV list" is much more
useful to us than "Help me please!"

2. Include any appropriate log entries. LISTSERV keeps logs of everything
it does when you are running it in the background (i.e., with 'go bg',
and without a log excerpt it is often impossible to determine what caused
a given error.

3. If you have a traceback for the error, please send it.

4. Always send a copy of your site configuration file (with the passwords
XXX'ed out).

5. Send along anything else that you think might be helpful in diagnosing
the problem.

If you are running an evaluation version of our software, please join the
evaluation  users'  list,  LSTSRV-E@PEACH.EASE.LSOFT.COM, and  send  your
trouble reports there.

If you are  running LISTSERV Lite, please join  the LISTSERV-LITE mailing
list, LISTSERV-LITE@PEACH.EASE.LSOFT.COM,  and send your  trouble reports
there.

If your  server is registered and  has paid-up maintenance, you  may send
problems to SUPPORT@LSOFT.COM for a quick reply.

********************************************
* Documentation and where to get more help *
********************************************

You should be  aware that there are several  documentation files included
with LISTSERV. They  are located in LISTSERV's MAIN  directory by default
and include the following:

 listserv.memo   A General Introduction to LISTSERV
 listpres.memo   A presentation of LISTSERV for the general user
 listownr.memo   List Owner's Manual
 listmast.memo   Site Manager's Operations Manual
 listkeyw.memo   A manual of the various list header keywords and what they do
 listall.refcard A quick reference card for LISTSERV commands

The List Owner's Manual  can also be viewed on the World  Wide Web at the
URL

http://www.lsoft.com/manuals/ownerindex.html

A Site  Manager's Operations Manual  for LISTSERV 1.8c is  available from
L-Soft at the URL

http://www.lsoft.com/manuals/siteindex.html

And finally, a General Users Guide  for LISTSERV is available from L-Soft
at the URL

http://www.lsoft.com/manuals/userindex.html

Also,  the  LISTSERV manuals  are  available  in various  word-processing
formats from the ftp site.

There are several mailing lists dedicated to the support of LISTSERV.

 LSTSRV-L@SEARN.SUNET.SE      for LISTSERV maintainers and interested list 
                              owners
 LSTOWN-L@SEARN.SUNET.SE      for LISTSERV list owners
 LSTSRV-E@SEARN.SUNET.SE      for LISTSERV evaluation kit users 

To subscribe  to any of  these lists, send mail  to LISTSERV@LISTSERV.NET
with the following command in the body of

the message:

SUBSCRIBE listname Your Name

Please send comments on this installation guide to manuals@lsoft.com. 

==============================================================================
LISTSERV is a registered trademark licensed to L-Soft international, Inc.
LSMTP is a trademark of L-Soft international, Inc.
EASE and CATALIST are service marks of L-Soft international, Inc.
L-SOFT is a trademark of L-Soft international.
MultiNet is a trademark of TGV, Inc.
JNET is a registered trademark of Wingra Technologies, Inc.
PMDF is a registered trademark of Innosoft International, Inc.
Unix is a registered trademark of X/Open Company, Limited.
IBM  is  a  registered   trademark  of  International  Business  Machines
Corporation.
Alpha  AXP, OpenVMS,  VAX and  VMS  are trademarks  of Digital  Equipment
Corporation.
All other  trademarks, both marked  and not  marked, are the  property of
their respective owners.