![[L-Soft(TM) logo]](images/logo-left.gif){kind=logo}
![[Online manuals]](images/HDR-doc.gif)
|
|
|
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.