![[L-Soft(TM) logo]](/images/logo-left.gif){kind=logo}
![[Online manuals]](/images/HDR-doc.gif)
|
|
|
Last update: 22 May 2002
>>> Do NOT receive any of the other files before reading this! <<<
This file is the installation guide for LISTSERV. You should read it
carefully before proceeding to install the server.
Preface
This manual is the installation guide for LISTSERV. It contains all the
information required to install the server, along with detailed
technical requirements.
Conventions
-----------
The following typographical conventions have been made in this docu-
ment to improve its readability:
| o Recent changes in the publication are indicated by a vertical bar
| in the left margin.
! o Intermediate changes between two releases of the document ("Pre-
! releases") are flagged with an exclamation point in the left
! margin. Features described in this fashion should be considered
! as not documented and not officially supported until the exclama-
! tion point is removed.
> o Temporary restrictions or circumventions are marked with a
> "greater than" sign in the left margin. This sign may also be used
> to signal obsolete features for which support will be dropped in
> the next release.
| Statement of Year 2000 Compliance for L-Soft's Products
| -------------------------------------------------------
|
| L-Soft's Year 2000 Statement is found at
| http://www.lsoft.com/y2k-faq.html .
PRELIMINARIES
_____________
This section contains the non-proprietary components list and technical
requirements specifications. It should be read carefully prior to
proceeding to the installation of the LISTSERV software package.
**************************
* Technical requirements *
**************************
Hardware requirements
---------------------
There is no particular hardware requirement, apart from those implied
by the software requirements hereunder.
Operating system requirements
-----------------------------
LISTSERV operates exclusively in VM/CMS environments. There exist,
however, a number of different "flavours" of VM/CMS, whose specifics
will be covered in this section. Note that the information and
recommendations provided hereunder have been extracted from comments
and problem reports sent by the 100 most important LISTSERV sites. This
information is provided to help you decide whether or not you can run
LISTSERV on your existing operating system, and if so, what are the
potential problems you should be aware of. It applies solely to the
LISTSERV software, and is not suitable to the evaluation of any other
product. It does not necessarily reflect the opinion of IBM, nor that
of the publisher.
CP requirements
There are three "families" of VM operating systems: VM/SP, VM/HPO and
XA/ESA. LISTSERV can operate under all three families, with different
requirements and/or restrictions.
VM/SP (CP)
LISTSERV can operate indifferently under VM/SP CP Release 4, 5 or 6,
and with the so-called "370 Feature" of VM/ESA. However, if VM/SP
Release 5 or above is used, an english message repository (either UCENG
or AMENG) is required. Additional facilities are provided when running
under CP Release 5 or above.
The release of CP has no notable performance nor reliability impact
under VM/SP (this is not necessarily true of the other "flavours" of
VM), and there is therefore no "recommended" level.
VM/SP HPO (CP)
LISTSERV presently supports VM/HPO CP Release 4.0, 4.2, 5.0, 5.1 and
6.0 (all five tested in production). However, if VM/SP HPO Release 5 or
above is installed, an english message repository (either UCENG or
AMENG) is required. Additional facilities are provided when running
under VM/HPO Release 5 or above.
Important note for HPO 5 sites: Performance and/or reliability prob-
lems have been experienced by a large number of customers when running
LISTSERV under VM/HPO Release 5, due to corresponding spooling prob-
lems introduced by HPO 5. In addition to a very large list of spool
APARs which cannot be reproduced here, APARs VM28372, VM29275 and
VM30661 must imperatively be applied in order for LISTSERV to function
properly under HPO 5.
VM/XA and VM/ESA (CP)
LISTSERV supports the CP component of all versions of VM/ESA, and VM/XA
SP Release 2. VM/XA SP Release 1 is not supported. All machine modes
(370/XA/ESA/XC) are supported, but 370 mode is recommended for optimal
performance due to the longer path lengths with XA/ESA/XC modes in a
number of key CMS system services.
CMS requirements
You will probably have more than one version of CMS available for use
on your system. This section should help you to select the one which
is best suited to LISTSERV, according to your local
migration/conversion policies.
| LISTSERV can operate properly under all versions of CMS from 4 to 12,
| and can operate properly under CMS 13 if you install IBM APAR VM61031
| (fix number UM28307).
Generally speaking, the higher the version of CMS, the more CPU time
and storage you will need. This is because the parts of CMS that
LISTSERV is using have been getting generally slower and bigger with
each release, with the exception of release 7 which is more efficient
than release 6. As a rule of thumb, you will get optimal performance by
using the same level of CMS for LISTSERV that your users are normally
IPL'ing. The most notable exceptions relate to CMS 6 and early levels
of CMS 5.5 - CMS 5 is then preferable even if LISTSERV is the only user
of that system.
Finally, it should be noted that the windowing functions of CMS
Release 5 are not supported -- LISTSERV can only operate with SET
FULLSCREEN OFF in effect.
Other software requirements
---------------------------
The following software products are required to operate the LISTSERV
software:
o For the NJE version (the one normally sent to BITNET sites), RSCS
version 3, version 2.3 or version 2.2 is required. LISTSERV may
operate with older versions but they are no longer supported.
o A "mailer", whose task is to deliver the mail messages generated by
LISTSERV. The recommended product is LMail, available from the same
author. The Crosswell/Princeton mailer is also supported (R2.07 or
higher). In a non-BITNET environment, the SMTP server that comes
with version 2 of IBM's TCP/IP product can also be used as a
makeshift solution, but a full-fledged mailer is required for full
functionality. See section "Configuring the MAILER server" for more
details on software requirements.
Network datafiles requirements
------------------------------
The following data files are required to operate LISTSERV properly on
BITNET/EARN:
o BITEARN NODES, the network Master Node File. It can be obtained
from any operational NETSERV or LISTSERV server.
o DOMAIN NAMES, the list of all official gateways to other domains.
It can be obtained from any NETSERV.
Sites which are not connected to BITNET/EARN will have to prepare
sample versions of these files as explained in section "Other custom-
izable data files".
******************************
* Non-proprietary components *
******************************
The LISTSERV "base" software package contains some components which
are not under the ownership of the LISTSERV copyright owner. These
components may be subjected to different conditions of use. In any
case, their authors have explicitly accepted to have them distributed
along with the software package you have received. Below is a short
description of each of these components, along with the address and
phone number of someone who can be contacted if more accurate informa-
tion is required.
PDUTIL
------
PDUTIL is no longer shipped with LISTSERV. It may still be present on
LISTSERV's disk in the case of old installations, but is no longer
needed. As far as LISTSERV itself is concerned, it can be removed if
found on any of LISTSERV's disks.
CARD
----
CARD is a CMS utility similar to the IBM standard DISK command, but
much more efficient. It appears in the LISTSERV shipment under the
name of CARD MODULE. It is used to implement the Card file transfer
format and is invoked from various "system" modules like LSVSENDF
EXEC. It may not be removed from the LISTSERV disk without having to
modify some of these modules.
The following copyright instructions have been copied verbatim from
the CARD ASSEMBLE file:
This source is in the PUBLIC DOMAIN. It may be freely redistributed,
however, the full source (this file and associated updates) must be
made available upon request by any you redistrubute executables to.
No promices of the usefulness, correct operation, fixes
(etc, etc, et c) are made.
Problem reports and requests for information should be sent to the
authors at the following address:
Systems Programing
Cornell Computer Services
Cornell University
315 Computing and Communications Center
Garden Ave.
Ithaca, N.Y. 14853
USA
INSTALLATION
____________
This section decribes the installation of the LISTSERV package. It
contains instructions about setting up the LISTSERV virtual machine and
downloading the software material from the installation tape or network
installation shipment.
******************
* Shipment files *
******************
Installation tape
-----------------
This section is relevant only to software recipients who have ordered
an installation tape. Recipients of a network installation package
should skip to the next section.
Your installation tape will contain the following set of files, in CMS
TAPE format, with one tape mark separating each set of files from the
next one:
o A set of installation instructions files:
LISTINST MEMO This is a computer readable copy of the
document you are reading now.
LISTCPRT MEMO This file is an exerpt from LISTINST MEMO
containing only the copyright
instructions.
LISTSERV DIRECT This is a sample directory entry for the
LISTSERV virtual machine.
o A set of basic installation files, containing all the program and
data files required to operate the software with a minimum config-
uration.
o An optional set of source files, to which a dummy file is substi-
tuted if you did not request source files when filling in your
order.
Network installation package
----------------------------
This section is relevant only to software recipients who have ordered
a network installation package. Recipients of an installation tape
should skip to the next section.
Your installation package will contain the following set of files:
LISTPRES MEMO This is a copy of the Revised LISTSERV:
BITNET-Oriented Presentation guide, document
number P01-009.
LISTINST MEMO This is the file you are reading now.
LISTCPRT MEMO This file is an exerpt from LISTINST MEMO
containing only the copyright instructions.
LISTSERV DIRECT This is a sample directory entry for the
LISTSERV virtual machine.
$LISTSRV NAMES This is a sample PEERS NAMES entry which you
must fill in and return to the author upon
completion of the installation process.
INITIAL SHIPMENT This is a set of installation-customizable
files which are sent only once to each
installation to avoid overlaying previously
configured files. It contains several files
batched in a single DISK DUMP reader file.
VERSVVVV N-OF-M These files contain all the program and data
files comprising the LISTSERV software. Each
of these files has been kept smaller than
3000 records for network efficiency reasons.
They contain several files batched in a
single CARD DUMP reader file, and can be
received by means of the CARD MODULE program
included in the INITIAL SHIPMENT file.
ASMVVVV N-OF-M These files contain optional source files for
the assembler language components of the
LISTSERV software. Each of these files has
been kept smaller than 3000 records for
network efficiency reasons. They contain
several files batched in a single CARD DUMP
reader file.
Installation overview
---------------------
The installation process can be divided into four steps:
o Creating the LISTSERV virtual machine.
o Downloading the shipment files.
o Customizing the configuration files.
o Verifying the installation.
The first two steps will be covered in this section. The third step
is described under the heading "Customization", whilst the last step
is discussed in "Starting the server to verify the installation".
*****************************************
* Creating the LISTSERV virtual machine *
*****************************************
The suggested configuration for the LISTSERV virtual machine is the
following:
+--------------------------------------------------------------------+
| |
| USER LISTSERV password 5M 16M BDG |
| ACCOUNT SYSTEM NETWORK |
| IPL CMS |
| CONSOLE 009 3215 |
| SPOOL 00C 2540 READER |
| SPOOL 00D 2540 PUNCH |
| SPOOL 00E 1403 A |
| LINK MAINT 190 190 RR |
| LINK MAINT 19E 19E RR |
| LINK MAILER 191 xxx RR |
| LINK BITNET 191 xxx RR |
| MDISK 191 dtype start1 cyl1 volid MR |
| MDISK 192 dtype T-DISK cyl2 |
| |
| Figure 1. Sample directory entry for the LISTSERV virtual machine |
+--------------------------------------------------------------------+
The various definitions of this virtual machine are discussed below:
USERID It is recommended that you used a userid of LISTSERV
for the LISTSERV virtual machine. However, LISTSERV
can operate normally under any userid as long as the
other LISTSERV servers are informed of this unexpected
userid. By default, all LISTSERV servers will assume
that a virtual machine with a userid of LISTSERV is a
LISTSERV server and is authorized to issue inter-server
control commands.
STORAGE The minimum recommended storage size for LISTSERV is
five megabytes, as a lot of EXEC files are EXECLOAD-ed
and an important amount of datafile information is
cached in storage for better performance.
PRIVILEGES LISTSERV requires privilege class D for distribution
list and spool monitoring functions (See the "OFFLI-
NETHR" variable in LOCAL SYSVARS.) to operate properly.
It is also recommended that MSGNOH privilege be granted
to it, either through a special installation-defined
privilege class or through the use of "standard" privi-
lege class B. This is the only reason why class B is
shown in the sample directory entry; LISTSERV does not
use any class B command other than MSGNOH.
If not endowed with MSGNOH capability, the server will
use the special CP TO command if it is available at
your installation, or will send the message via RSCS.
If all of this fails, a normal CP MSG command will be
used to make sure that the message is delivered.
A home-made privilege class can be substituted to this
as long as it includes the class D QUERY FILES,
TRANSFER and CHANGE commands, and, optionally, the
MSGNOH command.
IPL LISTSERV must IPL a CMS system located above its
virtual storage size.
LINKS Incomplete LINK directory statements have been included
for the two following disks:
o MAILER 191, which is supposed to contain the
required DOMAIN NAMES file.
o BITNET 191, which is supposed to contain the
required BITEARN NODES file.
None of these two userids have to be created if they do
not already exist. You should make sure, however, that
LISTSERV is granted R/O access to the three files
mentioned above. It is your responsibility to provide
the necessary ACCESS statements in the server's PROFILE
EXEC, or to install/create the files on the server's
191 minidisk. Non BITNET/EARN recipients should remove
these LINK statements as they will have to create
samples of these three files on the LISTSERV 191 mini-
disk anyway, as explained in section "Other
customizable data files".
MINIDISKS Two minidisks are required for LISTSERV:
o The 191 minidisk is used to store the LISTSERV code
and data files. The recommended size is approxi-
mately ten megabytes, allowing for a "normal"
amount of lists and entries in the signup file. The
source code should be placed on a separate minidisk
(which can be owned by a "maintainer" account).
o The 192 minidisk is a work disk which can be
defined either as a T-DISK or as a normal permanent
disk. In the latter case, it should be formatted
with the BLKSIZE 4k option. About two megabytes of
disk space should be allocated for the work disk.
You might want to define additional disks for your own
use if you plan to make an extensive use of the file
server functions of LISTSERV.
You should note that in any case, LISTSERV will not
automatically access any disk other than its 191 and
192 minidisks.
Once you have created the LISTSERV virtual machine, you must LINK to
its 191 minidisk in R/W mode and format it before proceeding with the
installation.
*************************
* Downloading the files *
*************************
Before starting to download the files you must have obtained R/W
access to the LISTSERV 191 minidisk and formatted it if required. It
must be accessed as your A-disk.
Downloading from installation tape
----------------------------------
You must first attach the tape drive to yourself at virtual address
181, before issuing the following commands:
TAPE REW (rewinds the tape)
TAPE FSF (skips the installation instructions files)
TAPE LOAD (loads the basic material)
The tape is then positioned on the beginning of the assembler source
files, which can then be loaded if desired. You might also wish to
load them on a separate disk. The same applies to the SCRIPT source
files which follow the assembler sources files.
Downloading from installation shipment
--------------------------------------
YOU MUST NOT USE RDRLIST TO RECEIVE THE FILES.
Instead, you must use the CP QUERY READER ALL * command to determine
which files are in your reader, and what are their spoolids. You must
then issue a CP ORDER READER spoolid command to place the INITIAL
SHIPMENT file on top of your reader, and then issue a DISK LOAD
command to receive its contents on the LISTSERV 191 minidisk.
Once the INITIAL SHIPMENT file has been loaded, you must proceed to
install all the VERSvvvv n-OF-m files, in any order, using (for each
file) a CP ORDER READER spoolid followed by a CARD LOAD command.
You can then install the ASMvvvv n-OF-m files on whatever disk you
might want, using the same procedure. The only file in DISK DUMP format
is INITIAL SHIPMENT.
CUSTOMIZATION
_____________
This section discusses the tailoring and customization of the LISTSERV
software. It explains how to modify the various user-tailorable exits
and control files to suit your installation's needs, and should be
reviewed before starting the program.
******************************
* User-tailorable EXEC files *
******************************
This section describes the EXEC files that must be tailored by the
installation.
PROFILE EXEC
------------
You must modify the default supplied PROFILE EXEC file to include the
following:
o LINK and/or ACCESS commands for all the LISTSERV disks except the
191 and 192 minidisks which are automatically accessed. Notably,
you must provide LISTSERV with R/O access to BITEARN NODES
and DOMAIN NAMES.
You can use any free minidisk address on a LINK command, except
5FF which is reserved for LISTSERV's use. Similarly, you can use
any free disk mode on an ACCESS command, except Z which is
reserved for LISTSERV's use. It is, however, recommended not to
access any disk under a filemode of B or C.
o You may add additional commands (e.g. PF-keys definitions) for
your convenience. You should note, however, that console spooling
commands should not be placed in PROFILE EXEC but in LSV$CCNS EXEC
(see below).
LSV$CCNS EXEC
-------------
This exec is a user-tailorable exit that is called by LISTSERV when-
ever it wants to change the status of the console spooling options.
You should review it and modify it to suit your needs. It is self-do-
cumented and the various options are therefore not detailed here.
LSV$INST EXEC
-------------
This exec is a user-tailorable exit that is called whenever an INSTALL
command with the AUTO=YES option has been received. You should review
it and modify it to fit your installation's requirements. It is
self-documented and the various options are therefore not detailed
here.
LSV$PW EXEC
-----------
This customizable exit is called whenever a PW ADD command (refer to
the "Revised LISTSERV: File Server Functions" - document number
U01-006 - for more details on the PW command) is received by LISTSERV.
It must decide whether the command is to be accepted, rejected, or
forwarded to the LISTSERV operation staff for their approval. It is
self-documenting and should be reviewed and modified to fit your
installation's policy.
Note that the LSV$PW is bypassed when the PW ADD commands emanates
from a LISTSERV maintainer ("postmaster") or from a member of the
LISTSERV Coordination Board. This ensures that these persons are
always able to obtain a LISTSERV password.
***************************************
* Tailoring LISTSERV System Variables *
***************************************
LISTSERV uses a number of system variables which control several
configurable aspects of the software. These variables are defined in
the various SYSVARS files on LISTSERV's 191 minidisk. The file
SYSVARS FILE contains a list of all the SYSVARS files which are to be
processed at initialization, in the order in which they will be exam-
ined.
LISTSERV SYSVARS contains declarations which are intrinsically
global to all LISTSERV implementations and should not be altered
by the installation.
BITEARN SYSVARS contains declarations which are global to all
BITNET/EARN installations. Most of these declarations are also
required for non BITNET/EARN sites, but might be assigned a
different value. In any case, these values may be overriden by
means of the LOCAL SYSVARS file (see below).
LOCAL SYSVARS contains variable definitions which are local to
each installation. It is this file that you will have to
customize.
BITEARN2 SYSVARS contains statements to check out the consistency
of the previous declarations and to try to avoid problems caused
by incorrect specifications in the previous SYSVARS files. It is
only relevant to BITEARN/EARN sites.
As each SYSVARS file is processed, new variables are assigned and
possibly overlay previously defined values. The LOCAL SYSVARS file is
processed after all the standard definition files, and can therefore
be used to override default settings. BITEARN2 SYSVARS subsequently
receives control and performs some verifications to ensure that the
values specified in LOCAL SYSVARS are consistent and will not cause
any problem at execution time.
Some of the optional LISTSERV sub-packages (e.g. the "LMON" RSCS line
monitor subsystem) have their own SYSVARS file which must be inserted
in SYSVARS FILE in the course of the sub-package installation. These
are documented in the corresponding sub-package installation guide.
The various SYSVARS files are self-documented and should be referred
to for more information.
Special considerations for non BITNET/EARN sites
------------------------------------------------
Non BITNET/EARN sites might need to modify some of the statements
contained in BITEARN SYSVARS and BITEARN2 SYSVARS. In particular, the
LMC and LCOORD variables should be modified. These modifications
should take place preferrably in the LOCAL SYSVARS files, which
receives control after BITEARN SYSVARS.
The LMC variable defines the RFC822 addresses of the LISTSERV Master
Coordinator, i.e. the person in charge of the management of LISTSERV
in BITNET/EARN. It is associated with the LMC File Access Code which
owns the various network-wide configuration files of LISTSERV. You
should set it to the userid@node of the person who will coordinate the
LISTSERV network in your institution. If you do not have a local
network, it should be set to be the same as the LISTSERV operations
staff, i.e. the declaration would be as follows:
LMC = postmaster
The LCOORD variable defines the RFC822 addresses of the members of the
LISTSERV Coordination Board, i.e. the persons in charge of the coordi-
nation of LISTSERV in BITNET/EARN. It corresponds to the list of
persons to be notified of problems which might affect the operation of
the LISTSERV network. These persons are also authorized to use the
FILEVERS command to check the installation status of the various
servers in the network. You should set it to the userid@node of the
persons who will monitor the LISTSERV network in your institution. If
you do not have a local network, it should be set to be the same as the
LISTSERV operations staff, i.e. the declaration would be as follows:
LCOORD = postmaster
Special considerations for local modifications
----------------------------------------------
New system variables can be defined in the LOCAL SYSVARS files for use
in locally developped commands. This does not require any modifica-
tion to the LISTSERV code, as the list of system variables is built
dynamically from the contents of the various SYSVARS files.
These variables can then be retrieved by means of a "GLOBALV SELECT
LISTSERV GET varname" command. However, care should be taken not to
use names that might receive an "official" meaning in subsequent
releases of the program. It has been decided that no "official"
system variable would start with an underscore ('_'). You should
therefore avoid defining new system variables which do not start with
an underscore.
To facilitate the definition of complex configuration parameters in
SYSVARS files associated with optional sub-packages, it has been
decided that any variable starting with a dollar sign ('$') would be
considered to be a scratch variable, local to the SYSVARS file in
which they have been defined. These scratch variables are not saved
to GLOBALV storage, and can only be used to build up other (permanent)
variables in the same SYSVARS file.
***********************************
* Configuring the MAILER software *
***********************************
This chapter contains configuration specifics for the "mailer" agent to
be used in conjunction with LISTSERV, and explains how to set the
NDMAIL variable in LOCAL SYSVARS, which tells LISTSERV whether to use
PUNCH or Netdata format when talking to the mailer. Regardless of its
setting, LISTSERV always accepts both formats as input.
LMail
-----
The LMail installation guide contains configuration instructions for
the use of LMail in conjunction with LISTSERV. Just search for the
string "LISTSERV" in the various MEMO files. With LMail you should set
the NDMAIL variable to 1 in LISTSERV's LOCAL SYSVARS file.
XMAILER
-------
The use of the Crosswell/Princeton mailer (XMAILER) is not recommended.
At any rate, only versions R2.07 and higher are supported. When using
XMAILER, the MAILER MTPLATE file must be modified to include the
LISTSERV virtual machine in the list of "trusted" origins. The
INCOMING: table would be modified as follows:
+--------------------------------------------------------------------+
| |
| INCOMING: |
| ; Node Userid Exit |
| ;------- -------- --------- |
| %incoming |
| BLUELAKE LISTSERV |
| *DEFAULT* *DEFAULT* RSCSVER ; standard RSCS tag checking |
| END INCOMING |
| |
| Figure 2. Modifying the MAILER MTPLATE file: This figure assumes |
| that the userid of the LISTSERV virtual machine is |
| "LISTSERV" and that your nodeid is "BLUELAKE". |
+--------------------------------------------------------------------+
You must then issue a MG MAILER command to rebuild the MAILER PROFILE
file and restart your mailer.
With XMAILER version R2.10 and higher, set NDMAIL to 1, otherwise to 0.
SMTP
----
The use of SMTP in conjunction with LISTSERV is discouraged if you have
a local NJE network. At any rate you are advised to install LMail,
which can communicate with both SMTP and other mailers of various types
(and of course LISTSERV) in order to provide optimal usability. With
SMTP, you set NDMAIL to 1.
*********************************
* Other customizable data files *
*********************************
This chapter gives a brief description of the remaining customizable
datafiles used by LISTSERV.
WAKEPARM FILE
-------------
LISTSERV is able to perform pre-defined tasks at scheduled dates or
times. These tasks are called events and are defined in a file called
WAKEPARM FILE. This file must have a logical record length of 80 and
fixed-length records, and must reside on the LISTSERV 191 minidisk. A
sample WAKEPARM FILE is shipped with the LISTSERV code:
+--------------------------------------------------------------------+
| |
| * |
| * This WAKEUP parms file is the new default for |
| * LISTSERV version 1.5j and above. |
| * |
| MON 06:00:00 06/15/87 EXEC LSVEXPIR |
| ALL 10:00:00 06/16/87 Call LSVCHK 'Database1' |
| ALL 12:00:00 06/16/87 EXEC LSVCLGBV LASTING |
| ALL 18:00:00 06/16/87 CMS EXECMAP |
| ALL 22:00:00 06/15/87 Call LSVXAFD 'Delayed AFD/FUI' |
| ALL 23:59:00 06/14/87 EXEC LSV$CCNS CLOSE |
| ALL 02:00:00 06/16/87 Call LSVXAFD 'Delayed AFD/FUI' |
| |
| Figure 5. Sample WAKEPARM FILE |
+--------------------------------------------------------------------+
Blanks lines and lines starting with an asterisk are ignored. All the
other lines define an event and its scheduled date and time, in the
following format:
1. Column 1: days when the event must be executed. This can take
any of the following forms:
ALL Indicates that the event must be executed every
day.
MON, TUE... Indicates that the event must be executed every
monday, tuesday, etc.
M-F Indicates that the event must be executed every
working day (i.e. from monday to friday).
S-S Indicates that the event must be executed every
weekend day (i.e. on saturdays and sundays).
WEEKDAY Is a synonym of M-F.
WEEKEND Is a synonym of S-S.
MM/DD/YY Is the exact date when the event is to be sched-
uled. Double equal signs ('==') can be used as
wildcard characters in the month, day or year spec-
ification. Thus, ==/10/== means that the event
must take place on the tenth day of every month,
while ==/==/== is functionally identical to ALL.
2. Column 10:
o Time at which the event must be executed, if it is a "fixed-
schedule" event (see below). This must be in hh:mm:ss format.
o Events can also be scheduled to be executed at regular inter-
vals of time, rather than at pre-defined time specifications.
In that case, "&hh:mm" must be entered in column 10 to define
the interval of time after which the event is to be re-exe-
cuted.
3. Column 19: date or time (for "interval" events) at which the
event was last executed. This field is maintained by LISTSERV and
should be left unchanged, with new entries being initialized to
00/00/00 for "fixed-schedule" events, and 00:00:00 for "interval"
events.
4. Column 28: description of the event. The first word indicates
the nature of the event:
CMD Indicates that the specified LISTSERV command is to be
executed under the authority of the LISTSERV virtual
machine, i.e. as if the command had been entered from
the LISTSERV console.
CMS Indicates that the command must be passed to CMS as per
the REXX Address CMS command.
COMMAND Is a synonym for CMD.
CP Indicates that the command must be passed to CP without
being translated to uppercase.
EXEC Indicates that the specified EXEC is to be invoked
without the argument list being translated to uppercase.
REXX Directs LISTSERV to process the command as per a REXX
Interpret command.
Each of these event descriptions may optionally be prefixed with a
QUIET keyword, indicating that the event should not be traced on
the console log (i.e. it suppressed the message "Executing WAKEUP
event:"). This is very useful for "interval" events which are to
be executed hundreds of time every day.
You might want to add new events to the file or change the date/time
of existing ones, at your convenience. However, it is recommended
that you did not altogether remove any of the standard event from the
file.
DOMAIN NAMES
-------------
This section is irrelevant to BITNET/EARN sites, which should use the
default DOMAIN NAMES file supplied by the BITNET coordination.
The DOMAIN NAMES file defines the various network domains accessible
from the local NJE network, along with the NJE addresses of the corre-
sponding gateways. It is used mainly by the DISTRIBUTE command (refer
to the "Revised LISTSERV: Application Programmer's guide", document
number A01-004, for a description of the DISTRIBUTE command) which
must be able to determine the nearest NJE node to any given domain.
+--------------------------------------------------------------------+
| |
| :nick..Atlantis :mailer.MAELSTRM@OCEAN |
| :nick..HADES.Olympus :mailer.FURNACE@HELL |
| :nick..Olympus :mailer.RAINBOW@EARTH |
| |
| Figure 6. Sample DOMAIN NAMES file |
+--------------------------------------------------------------------+
DOMAIN NAMES is a NAMES-format file of which LISTSERV recognizes and
uses only two tags:
:NICK This tag defines the name of the domain. Its value must
start with a period and can be either a top domain or a
sub-domain, with no limit on the number of intermediate
sub-domains. For example, both .ARPA and .host1.host2.ARPA
are valid domain names.
Note that it is perfectly valid to specify a different
gateway for a top domain and one of its sub-domains, as is
shown in Figure 6.
:MAILER This tag defines the userid@node of the gateway to the
domain. It must be directly accessible via the NJE network
to which LISTSERV is connected (or on the local machine).
XMAILER NAMES
-------------
XMAILER NAMES is no longer required by LISTSERV. This section has been
deleted.
BITEARN NODES
-------------
This section is irrelevant to BITNET/EARN sites, which should use the
default BITEARN NODES file supplied by the EARN coordination.
The BITEARN NODES file defines various parameters associated with each
node of the local NJE network. It is extensively used by LISTSERV,
which uses it to build several data files such as BITEARN LINKSUM2.
However, only a subset of the original tags from BITEARN NODES is used.
No attempt will be made at describing the other tags which are
irrelevant to non BITNET/EARN sites. The details of the format of the
BITEARN NODES file are described in a document called NEWTAGS DESCRIPT,
which is maintained by a third party and available upon request.
+--------------------------------------------------------------------+
| |
| :node.VERS9710 :nodedesc.Special version entry |
| :connect.19930301 :country.SE :lastup.ADD 19990131 |
| :ref.GRENDALE |
| |
| :node.BLUELAKE :links1.FOREST :ref.GRENDALE |
| :p_naiad.Naiad Lokiniram;NAIAD@BLUELAKE;36-15-33-33 |
| :country.US :fformat.PU :msgs.Y :connect.19930301 |
| :servers1.PISCES@BLUELAKE(MAIL,PU,M,BSMTP) :admin.p_naiad |
| |
| :node.FOREST :links1.GRENDALE BLUELAKE :ref.GRENDALE |
| :country.US :msgs.N :connect.19930301 |
| |
| :node.GRENDALE :links1.GRENTREE FOREST :connect.19930301 |
| :servers1.PIGEON@GRENDALE(MAIL,ND PU,M,BSMTP) |
| :p_wizard.Him who Knoweth;WIZARD@GRENDALE;43-72-67-98 |
| :country.US :fformat.ND :fclass.G :msgs.Y :admin.p_wizard |
| :member.The green dale :dir.p_wizard :ref.GRENDALE |
| |
| :node.GRENTREE :links1.GRENDALE :connect.19930301 |
| :p_ilopan.Dryad Ilopan;DRYAD@GRENTREE;36-15-69-00 |
| :country.US :fclass.T :msgs.Y :admin.p_ilopan :ref.GRENDALE |
| :servers1.PIGEON@GRENDALE(MAIL,ND PU,M,BSMTP) |
| |
| Figure 8. Sample BITEARN NODES file |
+--------------------------------------------------------------------+
IMPORTANT: with the exception of the first, or "version", entry, all
entries must be sorted in ascending order by the value of the ':node.'
tag.
VERSION ENTRY: the first entry in the file should be copied "as is".
The only field you should change is ':ref.', which should point to any
of the other nodes you define in the file (the value is immaterial as
long as the node in question is defined). You can also change the value
of the ':node.' field, as long as it starts with 'VERS' followed by a
2-digit year number and a 2-digit number from 00 to 99 (the length must
be exactly 8 bytes).
The format of BITEARN NODES is very similar to the IBM NAMES format,
with the :nick tag being replaced by :node. LISTSERV presently recog-
nizes only the following tags:
:NODE This tag defines the name of the node to which the
entry applies. It must be entered exclusively in upper
case characters.
:CONNECT This must contain a valid date, in the form yyyymmdd.
:LINKS1 Lists all the adjacent nodes. Any number of nodes may
be specified in this tag, separated from each other by
a single blank. More nodes can be entered under a
tagname of :links2, etc.
:ADMIN Defines a list of "system administrators". For each name
you specify in the :admin tag, you must provide a :P_xxx
tag defining the name and userid of that person.
:DIR Similar to :admin, but defines a "site director" rather
than a technical administrator. You can specify the same
value as for :admin - LISTSERV does not use this tag,
but its presence in the file is required.
:P_xxx Defines the name, userid@node and phone number of an
administrator, in the following format:
full name;userid@node;phone number
:COUNTRY Defines the country (ISO country code) in which the
node is physically located.
:FCLASS Defines the preferred file class for the node, i.e. the
default class in which files should be sent to users of
this node. This must be a single character in the A-Z
or 0-9 range. The default value is A.
:FFORMAT Defines the preferred file format for the node, i.e. the
default format in which files should be sent to users of
this node. The possible values are ND for Netdata and PU
for PUNCH. The default is ND (Netdata).
:SERVERS1 Defines the userid@node of the mailer serving the node,
if any. The format is a bit cryptic:
:servers1.userid@node(MAIL,format,M,BSMTP)
The 'userid@node' part must be on the local system or
reachable via NJE - not an Internet address. The format
should be 'ND PU' (without the quotes) for LMail,
FAL/SMTP, or XMAILER version R2.10 or higher. For older
versions of XMAILER, specify only 'PU'.
:MSGS Must be Y or N. Indicates whether the node is able to
receive interactive messages or not. You should use Y
for VM systems and VMS systems running JNET, but N may
be appropriate for MVS systems.
:MEMBER This tag is required in at least one of the entries. The
contents are a short free-form description of the site
in question. You can then use the nodeid containing the
:member tag to refer optional administrative definitions
via the :ref tag. In our example, GRENDALE is the
"member" node and tags such as :dir and :admin are
referred (inherited) by all the other nodes.
:REF This tag establishes a tree structure, referring the
current node to a higher-order node which it "belongs"
to. For instance, you could define one major node for
each physical plant and refer all the tags in this plant
to their major node. The higher-level nodes refer to
themselves. This tag is mandatory, even if you have a
simple, flat structure; in that case, just refer all the
nodes to themselves.
Referred tags: among the tags listed above, only the so-called "role
tags" (:admin, :dir and :p_xxxx) are inherited via the :ref mechanism.
The "technical tags" such as :fformat and :servers1 must be specified
in each entry.
OPERATING THE SERVER
____________________
This section describes the startup and shutdown procedures for LIST-
SERV. It is not intended to be a reference document (more detailed
information on this subject can be found in the Revised LISTSERV:
Maintenance Guide, document number S01-005), but should rather be
considered as a quick specific guide for post-installation verifica-
tion procedures.
**************************************************
* Starting the server to verify the installation *
**************************************************
Now that the software has been installed, you should start the server
to have it verify the consistency of the various program and data
files it has been provided with.
To do that, you must first release and detach the LISTSERV 191 mini-
disk if you had previously obtained R/W access to it. You should then
logon to the LISTSERV userid, and let the PROFILE EXEC run to its
completion. At this point, you should issue a QUERY DISK command to
check that both the 191 and 192 minidisks have been accessed in R/W
mode. If this is not the case, take the appropriate steps to correct
the problem.
First session (in test mode)
----------------------------
To start the server, you must execute the LSVPROF program. It is
normally invoked automatically from the PROFILE if LISTSERV is started
in disconnected mode (e.g. by means of an AUTOLOG command).
----------------------------------------------------------------------
LSVPROF
6 Jul 1993 17:56:32 LISTSERV version 1.7f starting...
6 Jul 1993 17:56:32 Copyright L-Soft international 1986-1993
6 Jul 1993 17:56:32 PASCAL code loaded at 3F9000 - size 503k
6 Jul 1993 17:56:32 Disk A(191) is 51% full.
6 Jul 1993 17:56:35 SIGNUP2 file is being compressed...
6 Jul 1993 17:56:35 -> No entry removed.
6 Jul 1993 17:56:36 Start: (WARM | COLD) | SHUTDOWN | View
cold p
6 Jul 1993 17:56:36 Initialization complete.
test
6 Jul 1993 17:56:45 From LISTSERV@SEARN: test
* Unknown command - "TEST". Try HELP.
stop
6 Jul 1993 17:56:51 From LISTSERV@SEARN: test
* STOP command accepted, returning to CMS.
Ready; T=1.87/2.33 17:56:52
Figure 9. Sample LISTSERV session
----------------------------------------------------------------------
At that point, LISTSERV may execute a migration procedure. A migration
procedure is a program that receives control whenever a new release of
the software is installed. It automatically performs several
post-installation steps to ensure that everything is in order. It will
normally display a number of information messages during this process,
and possibly some warning or error messages if a problem occured during
the "migration process".
If the migration process completed successfully, you will be prompted
for the type of startup that you want to take. You should answer COLD
POSTPONE (which can be abbreviated to COLD P) to this prompt. This will
direct LISTSERV to discard any warm data that might have been left from
a previous session, and to postpone the processing of reader files
until the next session.
NOTE: You might be asked whether you want to purge the contents of the
LISTSERV reader or not. In that case, you should probably answer NO and
make sure to transfer all important reader files to another account
before starting the server again, and to discard the remainder.
LISTSERV should then reply with a message saying "Initialization
complete" and wait for a command from the keyboard. You should try to
issue simple commands like HELP or LIST. When you have decided that the
server seems to operate properly, issue a STOP command to stop the
server and return to CMS.
Second session (in normal mode)
-------------------------------
You can now restart the server by typing LSVPROF again. This time it
should not run any kind of migration process -- if it does, it means
that something went wrong in the first run and that the migration
process did not complete successfully.
You should now answer WARM (or just enter a blank line) after being
prompted for the type of startup procedure to be executed. Note that
this prompt is issued only when LISTSERV is started from a physical
terminal -- a warm start is automatically performed when started in
disconnected mode.
LISTSERV should now be operating in normal mode. You can issue a few
more commands to check that it still functions properly, and then
disconnect it by entering a DISC command (you do not have to prefix it
with #CP as LISTSERV recognizes this command).
CONSIDERATIONS SPECIFIC TO BITNET/EARN SITES
____________________________________________
This section is specific to BITNET/EARN sites and contains the
definition of LISTSERV "backbone" sites.
*************************
* The LISTSERV backbone *
*************************
The LISTSERV backbone is a collection of servers which are operating
24 hours and maintained on a regular basis by their respective opera-
tion staffs, with assistance from the Listserv Coordination Board.
This backbone is used to support the DISTRIBUTE command (refer to the
"Revised LISTSERV: Application Programmer's guide", document number
A01-004, for a description of the DISTRIBUTE command) and to host
heavy-traffic network-wide peered lists.
BITNET/EARN servers can fall into one of two categories:
o Local server: A local server has by definition no obligation
towards the rest of the network. It can run any release of the
code, with or without local modifications. Its operation staff
can update it at irregular intervals, place it offline 14 hours a
day, or do just anything they might see fit to do. The server
will appear in PEERS NAMES but it will be flagged as being a local
server.
The only two restrictions placed about those servers are:
1. If its operation staff encounter a problem with the software
and the latest available release of the code has not yet been
installed on the server, no support will be provided by the
Listserv Coordination Board. The person who reported the
problem to the Listserv Coordination Board will merely receive
a note telling him that his problem will not be addressed
until he has upgraded to the latest available version of the
code.
2. Local servers are not allowed to create peer lists. Note that
the term "peer list" should be interpreted as meaning
"network-wide public peer list". A closed peer list local to
the various nodes of an institution does not fall into that
category.
A local server can create a network-wide list by means of the
Mail-Via= DISTRIBUTE feature. Local servers can submit DISTRIBUTE
jobs to the backbone, but will not receive any. If a peer sub-
backbone is required for the list (e.g. if large archive files are
to be made available), the local LISTSERV operations staff should
try to find hosts in the backbone or should join the backbone.
o Backbone server: A backbone server can do all of the above, can
create peer lists and is supposed to receive DISTRIBUTE jobs. The
restrictions placed on the backbone sites are the following:
1. A backbone server should always be at the latest available
level. This means that the operations staff should either
allow the Listserv Master Coordinator to update the server
remotely, or take whatever steps are necessary to update it in
a timely basis. The average delay should not exceed one week,
with the deadline being two weeks.
2. A backbone server cannot be placed offline on a regular basis.
It must operate 24 hours. It can of course be placed offline
manually under particular conditions, lists can be held by
their respective owners, etc.
3. A backbone server must be AUTOLOG-ged when the system is
IPL-ed, and ought to be automatically restarted at regular
intervals in case it logs off due to some hardware failure
(e.g. paging error). This applies only if such a restart
facility is already available at the site hosting the server.
In any case, local operators should be able to restart it if
they are also able to restart RSCS and other service machines.
That is, the host site should do its best to ensure that the
server is restarted on a regular basis in case it crashes.
4. A backbone server should have the latest version of BITEARN
NODES, or in the worst case, the version from the previous
month. This applies only if the NODUPD files are received in
due time of course.
Sites which are willing to become part of the LISTSERV backbone should
indicate it in the :backbone tag of the PEERS NAMES entry returned to
the Listserv Master Coordinator.
