[LISTSERV logo] [Online documentation]

Installation guide for LISTSERV® 1.8c for Unix®

Copyright © L-Soft International, 1996, 1997

Last update: 29 Oct 1997


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

Contents:

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

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.

Installation Overview

If you're very familiar with software installations on your system and would prefer terse, matter of fact steps rather than complete instructions, skip to the section entitled "The Bare Facts About Installing LISTSERV" near the end of this document.

LISTSERV CLASSIC

LISTSERV Classic for UNIX(R) is distributed as two compressed "tar" archive files. The installation guide, which is the file you are currently reading, is also available independently of the archives. One of the tar files contains data files common to LISTSERV on all UNIX(R) platforms, and the other contains the compiled version of the LISTSERV server. In order to simplify the process of removing extraneous files created during the installation procedure, you can copy the tar files to a scratch directory, install LISTSERV, and then "rm -fr /tmp/scratch" (or whatever you name the staging area).

LISTSERV LITE

LISTSERV Lite for UNIX(R) is distributed as one compressed "tar" archive file. The installation guide, which is the file you are currently reading, is also available independently of the archives. The tar file contains data files common to LISTSERV on all UNIX(R) platforms, as well as the compiled version of the LISTSERV server. In order to simplify the process of removing extraneous files created during the installation procedure, you can copy the tar file to a scratch directory, install LISTSERV, and then "rm -fr /tmp/scratch" (or whatever you name the staging area).

LISTSERV for UNIX (both Classic and Lite) is shipped with both:

The installation of LISTSERV consists of the following steps:

All of these steps are described in greater detail in the sections below. They should be performed in the order they are presented since some steps rely on the results of earlier steps. Once you've finished the above steps, you will be able to start your LISTSERV server and verify that it's working. You'll then be ready to create mailing lists and start using your LISTSERV server.

For those sites running Sendmail

Note that many commercial unixes are shipped with Sendmail version 5. If your Sendmail is at a version less than version 8, note that you will probably experience long turnaround times on requests to LISTSERV that could run to several hours. This is because earlier Sendmail versions can handle only 1-2K deliveries per day. L-Soft strongly recommends that any Unix site running LISTSERV with Sendmail upgrade to at least Sendmail version 8.7.x.

Usernames needed by LISTSERV

LISTSERV requires exclusive access to the mail sent to one username. Unless you have a very good reason to do otherwise, the username "listserv" should be used for that purpose. Many people around the world are already familiar with LISTSERV, and will assume that mail sent to will reach the server. The LISTSERV account is just an ordinary user, it doesn't need privileges, doesn't require access to restricted directories, and it doesn't need to have any particular UID or GID.

Extracting installation materials from the "tar" files

BEFORE STARTING: Please note that the makefile should be run from a temporary directory rather than the target directory. Otherwise some 'mv' commands will produce unexpected results.

For LISTSERV Classic, the two archive files you receive will be called common.tar.Z and either AIX.tar.Z, or SunOS.tar.Z, or ULTRIX.tar.Z, etc... depending on the version of UNIX(R) you are using. The filename is taken from the string returned by the 'uname' command on each UNIX(R) platform. Please note that some FTP sites may change the name of the files slightly to adhere to system specific naming conventions.

For LISTSERV Lite you will download only the 'uname'.tar.Z file. Do not attempt to apply the common.tar.Z file to your LISTSERV Lite installation! You can safely ignore any further references in this file to the common.tar.Z file.

If you're used to dealing with compressed tar files already, then just extract the contents using whatever commands you prefer. If you'd like the sample commands listed below to work as shown, rename the files you received to common.tar.Z and `uname`.tar.Z before continuing. For example, if the system specific file you received is called aix.tar-z, you would enter the command mv aix.tar-z `uname`.tar.Z. Copy or move the two files to a scratch directory first. (The advantage of using a work directory for the installation is that you can easily clean up afterwards.) Once the files have been copied, "cd" to that directory and enter, uncompress *.tar.Z to restore them to their original state. Then enter, tar xf common.tar and tar xf `uname`.tar to unbundle the programs, data files, etc... needed to install LISTSERV. Afterwards you should find the following files have been created in your current directory,

lsv.o           Makefile         go           go.sys
go.user.sample  u-install.memo   lsv_amin.c   lcmd.c
lsv
and the ./home directory will contain the following files.

bitearn.nodes    listall.refcard  listmast.memo  peers.names
country.file     listfile.memo    listownr.memo  service.names
default.mailtpl  listjob.memo     listpres.memo  stdcmd.file
errfac.file      listkeyw.memo    listserv.memo  sysff.file
intpeers.names   listkwd.file     lsvhelp.file   system.catalog
linkswt2.file    listlpun.memo    lsvinfo.file
Sample commands for this step:

Deciding where LISTSERV will reside

If you plan to use the precompiled lsv binary, you can skip this section as it uses the defaults for these locations.

Before you can continue with the installation of LISTSERV, you need to choose where you want several things to be placed. The installation process needs the full path names of three directories. All of them are defined by macros in the Makefile (which was extracted from the common.tar archive in the preceding step).

The directory where the mail interface and command line interface programs should be installed is defined by the BINDIR macro. The Makefile is distributed with BINDIR set to /usr/local/bin by default. Whether you choose to use the default directory, or redefine it, the installation procedure assumes the directory already exists. If you choose a new directory, you will need to create it before running the final "make install". This directory is only referenced during the installation of the mail interface. Neither the mail interface program, the command line interface utility, nor the LISTSERV server process requires write access to this directory afterwards.

Incoming mail is written to the directory defined by the LSVSPOOL macro in the Makefile. The default value is /home/listserv/spool. Unlike the BINDIR directory, the LISTSERV spool directory is assumed to be a new directory. In fact, no other users or daemon processes should write to this directory since LISTSERV scans this directory for incoming mail. If the directory doesn't exist when the "make install" command is executed, it will be created, and the LISTSERV account will be made the owner.

The LISTSERV executable, as well as associated directories and data files will be installed in the directory pointed to by the LSVROOT macro in the Makefile. Any directory can be used, so long as LISTSERV has write access to it. When the final "make install" is run, the LSVSPOOL directory, and several subdirectories, will be created if necessary. The LISTSERV account will be made the owner of those directories. The Makefile is distributed with the LSVROOT macro is set to /home/listserv. If you choose the default setting, the directories /home/listserv, /home/listserv/home, and /home/listserv/tmp will be created as a result.

To use different directories, edit the Makefile and change the BINDIR, LSVSPOOL, and/or LSVROOT macros.

Sample commands for this step:

Building the interface utilities and LISTSERV server

The program that handles incoming mail is called lsv_amin and is distributed in source form. The file lsv_amin.c is a standalone program that can be modified to suit your local mail system as needed. It should work as distributed with unmodified Sendmail systems. If you are running ZMAILER instead of Sendmail, please contact L-Soft for installation instructions. If you are running PP instead of Sendmail, you can compile the standard mail interface with -DMAIL_PP. To compile lsv_amin, first check the CC and CFLAGS macro in the Makefile to make certain the compiler and options specified are appropriate for your system. Second, if you have enabled the syslog daemon on your system, note that the lsv_amin program logs informational and error level messages using the syslog facility. By default, lsv_amin logs those messages as part of the mail system. That is, LOG_MAIL is used on the openlog() call. If you would prefer to log the LISTSERV mail interface entries separate from the other mail software on your system, edit lsv_amin.c and change the line

#define LOG_FACILITY LOG_MAIL

replacing LOG_MAIL with LOG_LOCAL1, or whatever category is appropriate for your site. If you are using a system on which the openlog() routine only takes two parameters, older Ultrix system for example, just change LOG_MAIL to 0. Once you've checked the Makefile and (optionally) changed the syslog option in lsv_amin.c, enter "make mailer" to build the program.

The "lcmd" utility is also distributed in source form. Once you've compiled and installed "lcmd", users can use it to send commands to your LISTSERV server rather than having to use a mail program. Users familiar with the Bitnet version of LISTSERV will find "lcmd" works much like the VM "tell" and JNET "send" commands. The primary differences being that LISTSERV sends back mail in response to commands submitted with "lcmd", and only your local LISTSERV can be reached. In addition to providing a simple command line interface to LISTSERV, sending commands with "lcmd" obviates the need for password validation of protected commands. Since the origin of the command is determined by the username of the person running "lcmd", not by parsing mail headers, password checking can be skipped by LISTSERV. The lcmd.c program should compile without modification. Site specific information needed by "lcmd" will be provided by the Makefile when building the program. To compile the LISTSERV command interface enter, "make lcmd".

If you have decided to use the precompiled lsv binary shipped with the distribution, you can skip the rest of this section.

If you have decided to link the lsv.o file and make your own lsv binary, there should be no need to modify anything in the Makefile to perform this step. Just enter, "make server" to build the server program. The resulting binary will be named "lsv". Sample commands for this step:

Moving the programs and files to the proper directories

The command, "make install" will copy the "lsv", "lsv_amin", and "lcmd" programs to the appropriate directories, as specified by the BINDIR and LSVROOT macros in the Makefile. In addition several directories will be created and a number of data files copied to those directories. While there are scenarios in which you can complete this step from the LISTSERV account, in most cases you will need to become "root" to run the "make install" command.

Sample commands for this step:

Customizing LISTSERV for your system

LISTSERV needs to know a variety of things about your system, and also how to communicate with the people that will be maintaining the software. All of the settings that you are likely to want to change are defined in the "go.user" shell script, which is created in the LSVROOT directory when you enter "make install". There are a number of environment variables that you can set to reflect things like the Internet domain name of the machine that will be running LISTSERV, the e-mail address of the LISTSERV postmaster, etc... You'll need to edit the go.user file in the LSVROOT directory, and set each of the variables as appropriate. There are comments in the file explaining the purpose of each variable.

Sample commands for this step:

Telling your mail system about LISTSERV

Please note that the file you need to edit in this step, and the commands you need to issue will require root privileges. Also, while the procedure for manually modifying the sendmail aliases file is described below, you can also enter "make aliases" to have the installation program complete this step automatically. The automated procedure assumes that your sendmail stores aliases in the file /etc/aliases, that the "newaliases" command will rebuild the aliases database, and finally that "kill -HUP `cat /etc/sendmail.pid`" will cause Sendmail to read in the updated alias list.

LISTSERV accepts and responds to several e-mail addresses. Even before you setup mailing lists, mail sent to listserv and owner-listserv should be handed to LISTSERV. The link between LISTSERV and your mail system is the lsv_amin program. If you are running Sendmail, the best way to route incoming mail to lsv_amin is by adding entries to your "aliases" file. Refer to the manual pages for sendmail on your system if you are not sure where the alias file is stored. On many systems the file will be called /etc/aliases. Once you have located the file, add the following lines,

listserv: "|/BBB/lsv_amin /SSS listserv"
owner-listserv: "|/BBB/lsv_amin /SSS owner-listserv"

to the file, replacing /BBB with the directory where the lsv_amin program was installed (the BINDIR macro in the Makefile), and replacing /SSS with the LISTSERV spool directory (the LSVSPOOL macro from the Makefile). Other than that, the lines should look exactly like the examples above. The double quotes should be entered into the alias file.

For example, if you changed BINDIR to /usr/lbin, and kept the default LSVSPOOL directory, the new lines in /etc/aliases would look like the following.

listserv: "|/usr/lbin/lsv_amin /home/listserv/spool listserv"
owner-listserv: "|/usr/lbin/lsv_amin /home/listserv/spool owner-listserv"

After updating the alias file, you will need to issue two Sendmail commands. First enter "newaliases" to compile the alias file into the format the sendmail daemon expects. Then you need to direct the sendmail daemon currently running on your system to read the newly compiled list of aliases. Refer to the manual pages for sendmail if you are unsure of how to do so. The command, "kill -HUP `cat /etc/sendmail.pid`" will work on AIX and SunOS systems. If you are running a syslog daemon, sendmail will log the fact that it has loaded the new aliases file. You can check the syslog output after issuing the command to make sure your changes are in place.

Sample commands for this step:

IMPORTANT - License Activation Key

Please note that this step is handled automatically for evaluation kits. The necessary file, called "license.merge", is provided in the COMMON.TAR archive and the "make install" command will copy it to the proper directory.

Before you can start up LISTSERV, you will need to install a License Activation Key (LAK) for 'LISTSERV-xxx' (xxx = SUNOS, AIX, BSDI, etc...). In order to offer the same range of services to all LISTSERV sites, regardless of the operating system used, we had to develop our own "license key" scheme. Using system supplied license managers where available and L-Soft LAKs elsewhere would have required us to develop multiple authorization schemes, and would also complicate the task of issuing license keys to customers.

Since the LAK manager is part of LISTSERV, installing the LAK is done last, after all the programs have been built and moved to their proper directories. The process is quite simple, you just create a file in the $LSVROOT/home directory and start the LISTSERV server to compile the information. The instructions for doing so are described in the License Registration Form that came with your installation materials.

Starting LISTSERV and Verifying a Successful Installation

Once you've customized the "go.user" shell script, you're ready to start LISTSERV. To do so, change your current directory to LSVROOT (as defined in the Makefile) and enter "go". LISTSERV will print some startup messages, then since this is the first time your server has been run, LISTSERV will generate a number of files needed to route mail. You should see messages similar the ones below.

12 Jun 1996 22:16:47 LISTSERV-TCP/IP for unix version 1.8c starting...
12 Jun 1996 22:16:47 Copyright L-Soft international 1986-1997
12 Jun 1996 22:16:47 SIGNUP files are being compressed...
12 Jun 1996 22:16:47 -> No entry removed.
12 Jun 1996 22:16:48 The network tables are outdated and must be rebuilt.
* Network tables generation process started - be patient...
Currently processed 500 nodes.
Currently processed 1000 nodes.
etc...
And once the table generation steps have finished you will see,
* Step 6 complete - link weights file successfully compiled.
*
* Network tables generation completed successfully.
12 Jun 1996 22:16:54 Nearest backbone host is LISTSERV@PEACH.EASE.LSOFT.COM
12 Jun 1996 22:16:54 Nearest NJE host is LISTSERV@PSUVM
12 Jun 1996 22:16:54 Initialization complete.
which confirms that you've successfully installed the LISTSERV server. To issue LISTSERV commands, press Ctrl-C and you will be prompted to enter a command. You can verify that your customized version of "go.user" was used with the RELEASE command. It will display, among other things, the address(es) of the LISTSERV postmaster(s) you entered in "go.user". If not, then stop the server and make certain that LISTSERV owns the "go.user" file, and that execute permission is set for the file. To stop LISTSERV hit Ctrl-C then enter "stop".

Once you've verified that your LISTSERV server starts and accepts commands, you should check to make sure the mail interface is working properly. If you stopped your LISTSERV, then restart it. You can use "go bg" if you'd rather have the server run in the background. After restarting LISTSERV, login to a different username and send mail to the LISTSERV account on your machine. Include one or more LISTSERV commands in the body of the mail message. Since you have yet to define any mailing lists to your server, commands like RELEASE, INFO and THANKS would be good choices. The mail interface notifies the server immediately upon arrival of new mail. So unless your system is heavily used when you try sending the message, a response should arrive within a few moments. If you don't receive mail back from LISTSERV, check for syslog entries generated by the mail interface, lsv_amin. Also, check to see if there are any errors on the terminal/window where you're running LISTSERV. If you started the server with "go bg" check the file "listserv.log" for error messages.

Talking to other LISTSERV evaluation kit users

A discussion group for sites that have installed evaluation copies of LISTSERV has been created to facilitate communication between LISTSERV maintainers, list owners and L-Soft support staff. The list is called LSTSRV-E, and you can subscribe by sending mail to LISTSERV@LISTSERV.NET, with the command, "SUB LSTSRV-E Your Name" in the body of the mail message. If you have any questions, comments, helpful hints, etc., please post them to LSTSRV-E for distribution to other people participating in the evaluation. Don't forget to mention which version of UNIX(R) you are using when posting. The purpose of the list is to share your experience and problems with other users of evaluation kits. Because there are so many versions and brands of unix, the kits haven't been tested equally on all possible platforms. Knowing which kit you are using will streamline the process of finding an answer to your questions.

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 automatically when the system boots), 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, including domain name.
:userid.LISTSERV         ! Username under which LISTSERV runs
:net.Internet            ! Must be Internet, LISTSERV for UNIX cannot
                         ! cannot run in NJE (BITNET) mode
:site.XXXXXXXX           ! University of XYZ, city, state, country
:country.XX              ! Two-letter ISO country code
:system.XXXXXXXX         ! Which type of UNIX system, and the version
                         ! Examples: SUNOS 4.1, AIX 3.2.5, etc...
:machine.XXXXXXXX        ! Hardware - RS6000 320H, AXP 3000-600, etc...
:contact.XXXXXXXX        ! Contact person, in the following format:
                         ! (Joe Manager) JOE@XYZ.EDU (+1 301 871.2727)
:type.unix               ! Do not change this - must be "unix"
:version.1.8c            ! 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 --------------------------------

List creation

This topic is discussed in detail in the Site Manager's Operations Manual for LISTSERV, available from L-Soft's World Wide Web site.

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 listserv@xyz.edu < newlist.create
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 LISTSERV will not create archive directories automatically. You must issue the appropriate "mkdir" command yourself. And when creating such directories, remember that the file permissions must grant the LISTSERV account write access to the directory. Also, directories should be specified as full path names.

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 brand and version of unix you are running!

Following is a sample list header file that can be modified, then cut and pasted into a mail message to be sent to your LISTSERV server. For help with the various header keywords (not all are shown here), please refer to the LISTSERV List Owners Manual.

------------------------------- 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
* Validate= No
* Notebook= Yes,/some/directory,Monthly,Public
*
* Owner= someone@somewhere.EDU
*
* PW= XXXXXXXX
------------------------------- Cut here --------------------------------

(If you use this sample, be sure to change "/some/directory" in the Notebook= keyword specification to a directory that actually exists on your machine, and also change "someone@somewhere.com" in the Owner= keyword to point to a real list owner. While this sounds basic, it is one of the more common mistakes made by first-time installers.)

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 mail interface. That involves adding entries to your Sendmail aliases file, much like you did when installing the server itself. For each new list, you'll need to add five entries to the aliases file. The format of those lines is as follows,

NAME: "|/BBB/lsv_amin /SSS NAME"
owner-NAME: "|/BBB/lsv_amin /SSS owner-NAME"
NAME-request: "|/BBB/lsv_amin /SSS NAME-request"
NAME-search-request: "|/BBB/lsv_amin /SSS NAME-search-request"
NAME-server: "|/BBB/lsv_amin /SSS NAME-server"

where "NAME" is the name of the mailing list, "/BBB" in the directory where the mail interface was installed (BINDIR in the Makefile), and "/SSS" is the LISTSERV spool directory (LSVSPOOL in the Makefile).

For example, assuming the default values were chosen for BINDIR and LSVSPOOL, the aliases for a new list called "newt" would be,

newt: "|/usr/local/bin/lsv_amin /var/spool/listserv newt"
owner-newt: "|/usr/local/bin/lsv_amin /var/spool/listserv owner-newt"
newt-request: "|/usr/local/bin/lsv_amin /var/spool/listserv newt-request"
newt-search-request: "|/usr/local/bin/lsv_amin home/listserv/spool newt-search-request"
newt-server: "|/usr/local/bin/lsv_amin /var/spool/listserv newt-server"

(Note that /etc/aliases does not use line continuation characters and will not operate properly unless each alias is on a line by itself. For instance, the newt-search-request: alias above should be on a single physical line even though it is over 80 columns long.)

Once you've added the new aliases to the file, you need to issue the "newaliases" command and send your Sendmail daemon a hangup (HUP) signal before they will take effect.

As with the earlier step where adding mail aliases was necessary, the commands documented above can be automatically invoked by using the "make" command. If you system stores aliases in /etc/aliases, and the newaliases command can be used to compile that file, and if the command "kill -HUP `cat /etc/aliases`" will cause your Sendmail to reload the alias file, then the automated method should work. To add the mail aliases for a new list, and to direct your Sendmail to use those new aliases immediately, enter "make list name=XXX" where "XXX" is the name of the new list.

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 privileges in LISTSERV's directories, e.g., root), copy or archive any files (list archives, etc.) that you want to keep to a safe place, and then use the Unix 'rm' command to delete the list file. For instance, if you are deleting a list called 'test.list', simply 'rm test.list' from the LISTSERV 'home' directory (by the Makefile default, this directory is LSVROOT/home). Optionally you may also remove the Sendmail aliases from /etc/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 unix with a much simpler procedure:

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

Starting LISTSERV automatically

The "go" shell script can be called from an inittab entry if you would like LISTSERV to be started whenever your system is rebooted. And since the "lsv" program takes over the shell script's process, the "respawn" option can be used if you would like the init process to monitor and restart LISTSERV if it should stop for some reason. If you choose to treat LISTSERV like other daemon processes, it is advisable to redirect the standard output of the go script to a file. Otherwise, information needed to track and resolve problems will not be available for reference. You can either edit the "go" script, which is located in the LSVROOT directory, or start the server with the command "go bg". The "bg", or "background", option will redirect LISTSERV's informational and error messages to a file called "listserv.log" in the LSVROOT directory. By way of example, here is the inittab entry used on one of the L-Soft development machines.

  listserv:2:respawn:/u/listserv/server/go bg

Please note that this respawn method may not work if you don't have sh as the default shell for 'listserv'.

Please refer to the manual pages for init and inittab on your system for specific information on how such mechanisms work on your version of UNIX®.

File server functions

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

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, and particularly if you are migrating to the unix version from VM, you should be aware of the differences.

With the traditional system, you create files called "xxxx FILELIST", which contain definitions for all the files belonging to a particular archive. With the temporary system, you store these definitions in a file called "site.catalog", in the LISTSERV "home" directory (by the Makefile default, this directory is LSVROOT/home). You create files called xxxx.catalog and register them in site.catalog in order to provide access to them. Please be aware that there are major differences between the way files are registered on VM and workstation systems as many list owners use (or are used to) a VM server with different conventions.

To register a new file to the server, you add a line to the "site.catalog" file in the LSV$ROOT directory (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 /aaa/bbb/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, "/aaa/bbb/my.file", is the name LISTSERV will use for the actual UNIX file. 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: if you are upgrading from LISTSERV 1.8b to 1.8c, the preceding represents a change in the format of site.catalog entries. For compatibility, the old style entries are also acceptable.

Note that if you are not creating special subdirectories for file archives and they will reside in the LSVROOT/home directory, you can simplify the site.catalog entry by using "A" instead of the full path, e.g.:

MY.FILE my.file.A XXX YYY

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:

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 my.file./pub 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 protections to ensure that only the people listed are allowed to access the files. These attributes apply to LISTSERV commands (GET, PUT, INDEX) only; it is your responsibility to protect the actual UNIX file and parent directory by setting the file protections and/or ownership (UID and GID) to prevent unwanted access by local users. Please keep in mind that the LISTSERV username must be able to read the files it is to distribute to people, and it must have read/write access to files you want people to be able to update via PUT commands.

For more information on running the LISTSERV file archive server on your machine, including how to set up sub-catalogs, please consult chapter 8 of the Site Manager's Operations Manual for LISTSERV 1.8c, available from L-Soft's ftp and World Wide Web sites.

The bare facts about installing LISTSERV

If all went well, you're ready to add mailing lists to your server. Please refer to the "List creation" section of this guide for instructions on how to do so.

Installing the LISTSERV web archive interface (new for 1.8c)

  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. The interface will access the files using the relative path 'archives/'. Under unix this may be a problem as the current directory may not be predictable. You can create a file called /etc/lsv-wa.config to override this (the first line not starting with a hash sign is used as the path to the web directory).
  4. Modify LISTSERV's configuration to add two variables, as follows:
  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.

Common problems and their solutions

We've made an attempt here to document a few of the most frequently-asked questions pertaining to running a LISTSERV server. Before contacting L-Soft for problem resolution, please take a moment to read through this list and see if your problem is answered here.

(Please see http://www.lsoft.com/lsv-faq.html for the most current version of this FAQ.)

Documentation and where to get more help

You should be aware that there are several documentation files included with LISTSERV. They are located in the ~listserv/home 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 A List Owner's Manual for LISTSERV 1.8b
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

Additionally, the following files are available for downloading from L-Soft's anonymous ftp site, ftp.lsoft.com :

LISTSERV for the non-technical user
(superseded by the new General User's Guide)
=====================================================================

NSC93US.PS PostScript(tm) version formatted for 8-1/2" x 11" paper
NSC93A4.PS PostScript(tm) version formatted for A4 paper
NSC93.MEMO Plain text version
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.
Unix is a registered trademark of X/Open Company, Limited.
AIX is a registered trademark of International Business Machines Corporation.
Ultrix is a trademark of Digital Equipment Corporation.
Sun is a registered trademark of Sun Microsystems, Inc.
JNET is a registered trademark of Wingra Technologies, Inc.
All other trademarks, both marked and not marked, are the property of their respective owners.