L-Soft international, Inc.
List Owner's Quick Start
for
LISTSERV®, version 1.8c
October 24, 1996
Revision 1
The reference number of this document is 9610-UD-04.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of L-Soft international, Inc.

Copyright © 1996, L-Soft international, Inc.
All Rights Reserved Worldwide.

LISTSERV is a registered trademark licensed to L-Soft international, Inc.
L-SOFT and LMail are trademarks of L-Soft international.
LSMTP is a trademark of L-Soft international, Inc.
EASE and CataList are service marks of L-Soft international, Inc.
Microsoft is a registered trademark and Windows, Windows NT and Windows 95 are trademarks of Microsoft Corporation.
Pentium and Pentium Pro are registered trademarks of Intel Corporation.
All other trademarks, both marked and not marked, are the property of their respective owners.

All of L-Soft's manuals for LISTSERV are available in ascii-text format via LISTSERV and in popular word-processing formats via ftp.lsoft.com. They are also available on the World Wide Web at the following URL:

L-Soft invites comment on its manuals. Please feel free to send your comments via e-mail to MANUALS@LSOFT.COM and indicate which manual you are commenting on.

Reference Number 9610-UD-04

Table of Contents

1.1. Typographical conventions used in this manual

1.2. What letters, numerals and characters are legal in parameters passed to LISTSERV

2.1. Anatomy of a mailing list

2.2. Sending commands to LISTSERV vs. sending mail to your list

2.3. How to retrieve ("GET") the list header

2.4. Modifying the values in the list header

2.5. Passwords: why they're important, and how to work with them

2.5.1. "Personal" passwords

2.6. How to store ("PUT") the list header

2.7. Command confirmation requests: the "OK" mechanism

2.8. Setting up different kinds of lists

2.8.1. A basic discussion list

2.8.2. A basic discussion list with digest enabled and no notebook archives

2.8.3. A basic moderated discussion list

2.9. Adding and deleting subscribers

2.10. Handling mail delivery errors

2.10.1. Common mail delivery errors and what they mean

2.10.2. The "auto-delete" feature

2.11. What to do when a user is "served out"

2.12. What to do if a LISTSERV error "holds" your list

2.13. Reviewing the list of subscribers

2.14. Managing Notebook archives

2.14.1 Indexing available archive notebooks

2.14.2. Deleting existing archive notebooks

2.14.3. The LISTSERV WWW archive interface

2.15. Digests and indexes

3.1. The list owner's manual

3.2. LISTSERV-related mailing lists

1. Welcome to LISTSERV!

LISTSERV is a system that allows people to create, manage and control electronic "mailing lists" on a corporate network or on the Internet. Since its inception in 1986 for IBM mainframes on the BITNETBITNET academic network, LISTSERV has been continually improved and expanded to become the predominant system in use today. LISTSERV is now available for VM, VMS™, many "flavors" of unix®, Windows NT™ and Windows 95™.

1.1. Typographical conventions used in this manual

We've tried to keep things as simple as possible to avoid possible confusion. When you see the following kinds of text, here's what you're looking at:

Normal text like this is simply descriptive text, and is used throughout as the "body text" of the document.

Monospaced bold text is used to show commands that you send to LISTSERV and the responses sent back to you by LISTSERV.

Monospaced bold italic text indicates a part of the LISTSERV command that you have to substitute a value for. In other words, if we print something like

we mean for you to replace listname with an appropriate value, which in this case would be the name of your list.

1.2. What letters, numerals and characters are legal in parameters passed to LISTSERV

You can use the following letters, numerals, and characters in the parameters of most LISTSERV commands:

Sometimes, however, LISTSERV expects specific kinds of data for its commands. Where this is required, we've used special "replaceable parameter" names like the following. When you see a command that requires one of these "replaceable parameters", you must choose from one of the options listed or provide the specific data requested:

fformat	Netdata, Card, Disk, Punch, LPunch, UUencode, XXencode, VMSdump, MIME/text, MIME/Appl, Mail
full_name	first_name [middle_initial] surname (not your e-mail address)
internet-address (or net-address)	synonymous with "userid" (see below) except that the 'hostname' part is always required; e.g., this parameter must always be in the form "someone@somehost.com".
listname	the name of an existing list
node	the fully-qualified domain name (FQDN) of an Internet host, e.g.: YOURHOST.YOURDOMAIN.COM
pw	a password containing characters from the set: A-Z 0-9 $#@_-?!|%
userid	Any valid RFC822 network address not longer than 80 characters; if omitted, the 'hostname' part defaults to that of the command originator

Other deviations from the standard set will be noted along with the affected commands.

2. Basic LISTSERV

This chapter begins with the beginning: not just the first things you will have to do as a list owner, but things that all list owners have to do eventually. For complete list owner documentation, see the List Owner's Manual for LISTSERV, available from L-Soft's WWW and FTP sites. The URL for the list owner's manual is

The manual can be viewed online or downloaded in various wordprocessing formats.

2.1. Anatomy of a mailing list

A mailing list under LISTSERV is basically just a file with configuration information at the top (the "list header"), followed by lines for subscriber addresses and personal option settings for those subscribers. If you were to get the entire list from the server, it might look something like this:

* My Distribution List
*
* Owner= JOE@BIGCORP.COM (Joe Doakes)
* Notebook= Yes,E:\FTP\LISTS\MYLIST-L,Monthly,Public
* Auto-Delete= Yes,Full-Auto
* Errors-To= Owner
* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No           Notify= No
* Files= No                Mail-Via= Distribute       Validate= No
* Reply-to= List,Respect   Review= Owner              Send= Private
* Stats= Normal,Private    X-Tags= Yes
* Default-Options= NoFiles,NoRepro
*
* This list installed on 95/10/02, running under L-Soft's LISTSERV-TCP/IP
* for Windows NT.
*
JOE@BIGCORP.COM Joe Doakes
2AAARAA5SAAA
FRAMIREZ@SOMEPLACE.NET Fred Ramirez
2AAARAA5PAAA
SUSAN@MYSCHOOL.EDU Susan Doe
2AAARAA4AAAA

(We don't recommend requesting the whole list, by the way--only the list header. This will be explained in a moment.)

The "list header" is that part of the list file where each line begins with the asterisk character ("*"). This is where all of the configuration keywords are found.

The subscriber list follows the list header. Note that a full subscriber record consists of an email address followed by a "real name" field, followed by a string of characters that tells LISTSERV what the personal options for each subscriber are.

Actually, the subscriber options are part of the same line as the email address and "real name" field. LISTSERV keeps this information in 100-byte "records", where the first 80 bytes are the email address and "real name" field and the last 20 bytes are for storing the user's personal options. Most mail clients wrap lines after 80 characters, so if you were to get the entire list, it would look like the example above. You can't store the list that way, so you should never retrieve the entire list when all you want to do is modify the header configuration. We'll talk later about how to "review" the list's subscribers rather than retrieving the entire list just to see who's subscribed.

There is a specific method to get only the header of the list sent to you for modification and this method should always be used.

2.2. Sending commands to LISTSERV vs. sending mail to your list

All LISTSERV commands are sent to the server by email. This means that you must create a new mail message using whatever command this requires for your mail client (click on "New message" or its equivalent for most mail clients) addressed to the LISTSERV address. Lets say for the sake of argument that your list is running on a server called LISTSERV.MYCORP.COM. So you would create a new message and address it to LISTSERV@LISTSERV.MYCORP.COM if you wanted to send a command to the server.

Don't confuse sending mail to your list with sending mail to LISTSERV. If you have a list called "MYLIST", for instance, you don't want to send LISTSERV commands to MYLIST@LISTSERV.MYCORP.COM because if you do, one of two things will happen:

• If LISTSERV recognizes a LISTSERV command word in the first line of a posting to a list, it rejects the posting and sends it back to the sender.
• If for some reason LISTSERV does not catch a LISTSERV command in the first line of the posting, your command will simply be distributed to the membership of your list and will not be acted upon.

LISTSERV commands go in the body (or message area) of your mail message, rather than in the subject. LISTSERV ignores the subject line for mail in all but only a few specific cases, so if you send mail to LISTSERV with the command in the subject line and nothing in the body, nothing will happen.

When we speak of "sending a command to LISTSERV" in the following sections, then, we are referring to creating a new email message addressed to LISTSERV@LISTSERV.MYCORP.COM and placing the command in the body (not the subject) of the message.

2.3. How to retrieve ("GET") the list header

To retrieve the list header, you send the following command to LISTSERV:

Or, you can use the minimum abbreviation:

"GET listname" is the basic command. It tells LISTSERV to send you a copy of the mailing list "listname".

Because we do not want the entire mailing list, only the header, we modify the basic "GET" command with the modifier "HEADER" (or "HEAD"). Note that the modifier must be preceded with a left parenthesis character ("(") for it to work correctly. Therefore, if your list is called "MYLIST", the command to get the header of MYLIST would be:

When you send this command, LISTSERV will send you just the lines of the list file that begin with asterisks ("*"). You can now edit the header and send it back.

Note: When you send this command and LISTSERV sends the header to you, LISTSERV will also "lock" the list so that no other privileged user (e.g., a secondary list owner or the LISTSERV site manager) can retrieve or store the list without first unlocking it. This is to help avoid owner (A) making a change in the header while owner (B) is also planning to make changes. If you decide after sending your GET command that you do not want to modify the list after all, you should send the command

to LISTSERV. If you do not either store the modified list back on the server (which also unlocks the list) or unlock the list explicitly with the UNLOCK command, subscribers will not be able to change their options or unsubscribe, and non-subscribers will not be able to subscribe. So it is important to make sure that you either store the list or issue an UNLOCK command whenever you GET the list header.

If you are the only list owner and don't see a need to lock the list while you are modifying the header, you can send:

which tells LISTSERV to send you the header but not to lock the list. However, please note that we do not recommend using the NOLOCK keyword unless you are an experienced LISTSERV list owner, as locking the header can help keep you from making major mistakes on a PUT operation. (See the chapter below on storing the list header for more detail.)

2.4. Modifying the values in the list header

The list header will come back to you looking like this:

* My Distribution List
*
* Owner= JOE@BIGCORP.COM (Joe Doakes)
* Notebook= Yes,E:\FTP\LISTS\MYLIST-L,Monthly,Public
* Auto-Delete= Yes,Full-Auto
* Errors-To= Owner
* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No           Notify= No
* Files= No                Mail-Via= Distribute       Validate= No
* Reply-to= List,Respect   Review= Owner              Send= Private
* Stats= Normal,Private    X-Tags= Yes
* Default-Options= NoFiles,NoRepro
*
* This list installed on 95/10/02, running under L-Soft's LISTSERV-TCP/IP
* for Windows NT.
*

If you made a mistake and did not specify the (HEADER modifier in your GET command, meaning that your entire list (including the subscriber addresses) was sent to you, our best advice is to discard the header and send your GET command over again, this time with the (HEADER modifier. This will save a lot of potential trouble for you later.

Without going into a lot of detail about what each of the header keywords means, here's a general breakdown of what you are looking at:

PUT MYLIST-L LIST PW=XXXXXXXX

The first line of the header is not actually part of the header at all. It is the command to LISTSERV to store the list header back on the server. When you send the header back to LISTSERV, you have to replace the line of "X"'s with either the password for your list or with a "personal password" that you define with another command. (More about passwords in the next section of this guide.) In any case, this line must be present and must not begin with an asterisk ("*").

* My Distribution List

The very first line of the list header proper (in other words, the first line beginning with an asterisk) is used by LISTSERV for the so-called "short description" of the list. This "short description" becomes part of how the list announces itself to the world, both in the global list of lists and in the "From:" and "Sender:" lines of mail coming from your list.

This first line may not contain any list header keywords. It must contain either the short description or must be blank except for the leading asterisk. If the first line of the list header contains only the asterisk, LISTSERV will insert "(No title defined)" where appropriate, so it is always best to have some kind of short description in the first line.

* After the first line, "blank" header lines containing just the asterisk are simply used to provide "white space". You do not need to leave any white space if you do not feel it is necessary.

* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No           Notify= No

List header keywords can be formatted one keyword to a line or several keywords to a line, as shown. LISTSERV considers any word followed by an equal sign ("=") to be a keyword. This means that you can have "comment" lines without having to use any special formatting, as in the following excerpt:

* This list installed on 95/10/02, running under L-Soft's LISTSERV-TCP/IP
* for Windows NT.

These are just comment lines that may or may not indicate something important to the list owner.

An important point to consider is that you may not have any blank lines in the header (other than the "blank" lines we've talked about above that actually begin with an asterisk). LISTSERV stops processing the list header when it reaches the first line that does not begin with an asterisk. At this point it begins processing lines as subscriber addresses. Thus, if you had a list header with a blank line as follows:

* My Distribution List

* Owner= JOE@BIGCORP.COM (Joe Doakes)
* Notebook= Yes,E:\FTP\LISTS\MYLIST-L,Monthly,Public
* Auto-Delete= Yes,Full-Auto

* My Distribution List

and treat the rest of your header as if it were a list of subscribers. This has the potential to cause a great deal of trouble, but normally if you are just storing a header with a blank line you will only receive an error message to the effect that a number of lines have "invalid RFC822 addresses" and that the header was not stored.

2.5. Passwords: why they're important, and how to work with them

There are two different kinds of passwords used by LISTSERV: a list password (which is obsolete, and not discussed below) and a personal password. We mention list passwords only for the benefit of list owners who may have owned LISTSERV lists running under previous versions.

2.5.1. "Personal" passwords

"Personal" passwords are stored by LISTSERV itself, and are the way to authenticate your identity when LISTSERV requests a password. Your "personal" password:

• Is used to authenticate that the command you sent actually came from you, on certain lists with appropriate settings;
• Is used to delete old notebook archive files if you don't want them hanging around on the server and taking up space (more about this later)
• Is used to store files on the LISTSERV's file server (more about this later)
• Is used to validate list GETs and PUTs

(replace "mypassword" with the password of your choice.)

LISTSERV will respond with a "command confirmation request". This is to ensure that the password command actually came from you and was not "spoofed" by someone else forging your address in the "From:" line of mail. "Command confirmation requests" and how to respond to them are described later in this chapter.

To remove your password, you would send the command:

You can leave the "PW=mypassword" part off and authenticate the command with a command confirmation request if you prefer. This is handy if you've forgotten your personal password and want to remove it so you can add a new one.

To change your password, send the command:

Note again that if the "PW=oldpassword" part is removed, you will be asked to authenticate the command with a command confirmation request.

2.6. How to store ("PUT") the list header

Going back to our example header, and assuming that we have made the changes we wanted to make, we now create a new email message addressed to LISTSERV and cut and paste the modified header--including the PUT command at the top--into the body of the new message. We change the PW= section of the PUT command so that it contains either our personal password, as discussed above. So if our personal password is MUADDIB, we have the following:

PUT MYLIST-L LIST PW=MUADDIB
* My Distribution List
*
* Owner= JOE@BIGCORP.COM (Joe Doakes)
* Notebook= Yes,E:\FTP\LISTS\MYLIST-L,Monthly,Public
* Auto-Delete= Yes,Full-Auto
* Errors-To= Owner
* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No           Notify= No
* Files= No                Mail-Via= Distribute       Validate= No
* Reply-to= List,Respect   Review= Owner              Send= Private
* Stats= Normal,Private    X-Tags= Yes
* Default-Options= NoFiles,NoRepro
*
* This list installed on 95/10/02, running under L-Soft's LISTSERV-TCP/IP
* for Windows NT.
*

It is VERY IMPORTANT that you do NOT attempt to add subscribers "on the fly" by adding them to the bottom of a list header PUT operation. If you do this, and the list is not locked (e.g., you've done a GET with the NOLOCK option or have unlocked the list manually prior to your PUT), LISTSERV will replace all of your existing subscribers with the new subscribers you've added at the bottom of your list header.

-------------------------------------------------------------------------
Date: Mon, 15 Jul 1996 09:39:20 -0500
From: "L-Soft list server at LISTSERV.MYCORP.COM (1.8c)"
 
To: Joe Doakes 
Subject: Command: PUT MYLIST-L LIST

The header of the MYLIST-L list has been successfully replaced.
-------------------------------------------------------------------------

If there is a problem with the list header, LISTSERV will warn you and may or may not store the header depending on how serious the error is. For instance, if you happen to use old documentation for LISTSERV, you may see obsolete syntax that worked fine for older versions but no longer is officially supported. If we were to PUT the list header with the keyword setting "Validate= Store Only" instead of "Validate= No", for instance, LISTSERV would respond:

-------------------------------------------------------------------------
Date: Mon, 15 Jul 1996 11:17:34 -0500
From: "L-Soft list server at LISTSERV.MYCORP.COM (1.8c)"
 
To: Joe Doakes 
Subject: Command: PUT MYLIST-L LIST

The following problems have been detected in the list header:

* Validate= STORE
Warning:  this  syntax  is  obsolete. In  order  to  avoid  compatibility
problems  in  the  future,  you   should  replace  this  definition  with
"Validate= No".

Please refer to the list keyword documentation (available via the "INFO
KEYWORDS" command) for more information about keyword syntax.

Since only warnings have been issued, the list will be stored anyway.

The header of the MYLIST-L list has been successfully stored.
-------------------------------------------------------------------------

If there is a "hard" error, in other words, one which will significantly affect LISTSERV's operation, LISTSERV will not store the list. This also applies to any attempt by the list owner to change certain settings such as the location parameter of the Notebook= and Digest= keywords. For instance, if we were to attempt to change the location parameter of the MYLIST-L list to something like E:\FTP\LISTS\MYLIST, or to turn the notebook archiving off by changing YES to NO, LISTSERV would respond:

-------------------------------------------------------------------------
Date: Mon, 15 Jul 1996 11:43:05 -0500
From: "L-Soft list server at LISTSERV.MYCORP.COM (1.8c)"
 
To: Joe Doakes 
Subject: Command: PUT MYLIST-L LIST

The following problems have been detected in the list header: 

* Notebook= ... 
Error: The first two parameters of the "Notebook=" keyword may only be 
updated by the LISTSERV administrator. 

Please refer to the list keyword documentation (available via the "INFO 
KEYWORDS" command) for more information about keyword syntax. 

PUT operation rejected, old list remains unchanged.<<< 
-------------------------------------------------------------------------

If you've disregarded the warning above and tried to add subscribers "on the fly", but the list is locked, you're in luck: LISTSERV won't overwrite your existing subscribers. Instead, it will store the header only and issue the following warning:

-------------------------------------------------------------------------
Date: Mon, 15 Jul 1996 11:53:05 -0500
From: "L-Soft list server at LISTSERV.MYCORP.COM (1.8c)"
 
To: Joe Doakes 
Subject: Command: PUT MYLIST-L LIST

WARNING: New recipients were present in the replacement list you sent. The
MYLIST-L list was last locked with a "GET HEADER" command, which does not
permit changes to list recipients. Only the list header will be updated.

The header of the MYLIST-L list has been successfully replaced.
-------------------------------------------------------------------------

If you didn't lock the list when you got the header, though, this message will not be issued and your existing subscriber list will be overwritten. The bottom line: Even if you are an experienced LISTSERV list owner, you should never use the NOLOCK option when you GET your list header unless you know exactly what you are doing and are alert to the possibility of making an error that may be very difficult to recover from.

2.7. Command confirmation requests: the "OK" mechanism

In essence, the magic cookie method requires that the sender of the command must confirm his command via a reply containing only the text OK. (This is actually simplistic; see below.) If mail is spoofed from the list owners user id, the command confirmation request will always be sent to the list owners user id, thus preventing the spoofer from confirming the command. Moreover, the cookie itself (a six-digit hexidecimal number) is registered to the From: user id of the original command.

The general method of replying to a command confirmation request is as follows:

• REPLY to the command confirmation request with the text ok in the body of the reply. (Non-case-sensitive) LISTSERV reads the cookie from the subject line and if it corresponds to a held job, the job is released and processed. If your mail program "quotes" the text of the command confirmation request in your reply, you should probably remove the quoted text so that the message body only contains "ok".

• SEND a new message to LISTSERV with the text ok xxxxxx (where xxxxxx is the command confirmation number from the original confirmation request) in the body of the reply. For instance, "ok 0A78B6".

Also note that the confirmations must come from the user id that originated the command. You cannot send a command from one account and then approve it from another. For instance, if you use two different methods to read your mail (like Pine from your shell account and Eudora from your SLIP connection) and the two different mail programs have your return address configured differently, you will experience a problem if you send the original command from one mail program and try to "ok" it from the other.

2.8. Setting up different kinds of lists

We'll now discuss simple distribution lists and how to set them up for specific purposes.

2.8.1. A basic discussion list

A basic discussion list can have a very simple header. Let's call our example list MYLIST-L. We'll assume that MYLIST-L is open for anyone to subscribe (but that to avoid subscription spoofing and/or bad return addresses, that subscription confirmation is turned on), that anyone can post to the list whether or not they are subscribed, notebook archives and digests are enabled, and that security is set at a basic (but still effective) level.

* My basic discussion list
* 
* Owner= myself@myhost.com
* Errors-To= Owners
* Notebook= Yes,E:\FTP\LISTS\MYLIST-L
* Send= Public
* Subscription= Open,Confirm
*

And that's all there is to it. (Daily digests are enabled by default when Notebook= Yes, so you dont need to explicitly code a Digest= keyword in this case.)

2.8.2. A basic discussion list with digest enabled and no notebook archives

Here we want to do the same thing as above, except that to save money and the time it takes to maintain notebook archives, we've decided not to archive the list. However, we still want daily digests enabled for people who want to receive the list that way.

* My basic non-archived discussion list
* 
* Owner= myself@myhost.com
* Errors-To= Owners
* Notebook= No
* Digest= Yes,A,Daily
* Send= Public
* Subscription= Open,Confirm
*

2.8.3. A basic moderated discussion list

For lists where you want to "moderate" the discussion (in other words, approve every posting that goes to the list), you'll need to define one more keyword and slightly change the parameters for "Send=".

* My basic moderated discussion list
* 
* Owner= myself@myhost.com
* Errors-To= Owners
* Editor= myself@myhost.com
* Notebook= No
* Digest= Yes,A,Daily
* Send= Editor,Hold
* Subscription= Open,Confirm
*

Note that using the ",Hold" option with "Send= Editor" means that all you have to do is respond "OK" to the messages being sent to you for your approval. If you actually need to edit the message text, you should see Chapter 6 of the List Owner's Manual for LISTSERV.

2.9. Adding and deleting subscribers

A list owner may add and delete subscribers manually. The command syntax is:

In a perfect world, subscribers would understand intuitively how to subscribe and unsubscribe from mailing lists. Unfortunately, this is not always the case. Depending on an individual's style of list management, a list owner may choose to add or delete subscribers to the list manually, or send the potential subscriber instructions on how it is done. And for lists coded Subscription= By Owner or Subscription= Closed, it is of course necessary to use the ADD command to subscribe a user.

If the list is set to confirm mailing paths for new subscriptions (Subscription= Open,Confirm), it is probably wisest to use the latter option, since if a subscriber is added manually to a list, the confirmation process is bypassed.

Note that full_name should contain at least two discrete words, but it is also possible to add users without knowing the value for full_name. Simply use an asterisk ("*") character. Note that if the user is already subscribed to another list on the same host, LISTSERV will pick up the value for full_name from its signup files. Examples are:

RIGHT: ADD GOV-L vice-president@whitehouse.gov Al Gore

RIGHT: ADD GOV-L vice-president@whitehouse.gov *

WRONG: ADD GOV-L vice-president@whitehouse.gov Al

WRONG: ADD GOV-L vice-president@whitehouse.gov Al-Gore

When adding users, ADD will also accept a full RFC822 address that you can cut and paste from the "From:" line of a message. Be sure that you remove the "From:" part of the line. For example, the "From:" line

From: Al Gore <vice-president@whitehouse.gov>

becomes an ADD command as follows:

For more details see the List Owners Manual.

2.10. Handling mail delivery errors

2.10.1. Common mail delivery errors and what they mean

Here are a few of the typical mail errors you will have to deal with as a list owner:

1. no such user at host

Most of the time, this is authoritative and indicates that the user's access has been curtailed for some reason (graduation, no longer employed, etc.). A quiet delete (syntax: "QUIET DELETE listname userid@host") is in order unless you have reason to believe that the message is not authoritative. Variations on this message include "Recipient unknown" and "Ambiguous address: userid". The latter doesn't really mean the user doesn't exist, but it's almost as bad, and many list owners choose to classify it as "no such user".

This is sometimes authoritative and sometimes not. If a host goes down or a gateway fails, often this message is returned by an intermediate host or gateway. If the user is bouncing a great deal of mail from a high-volume list, it is probably best to set the user to NOMAIL (syntax: "SET listname NOMAIL FOR @") rather than to summarily delete him. This way, the error messages stop, the user is sent an automatic message telling him his personal options have been changed by the list owner, and the user doesn't have to go through the subscription process again if the problem has been solved in the interim.

The problem is that some hosts go down on a regular basis and this error makes it impossible to tell if the host in question is gone forever or gone until the local sysadmin reboots his machine. After a while, you will begin to recognize the transient hosts and may elect to ignore them. If you choose to set the user to NOMAIL, you should send a message to the user just in case the system has come back up, and you should keep some sort of record of the users you've set this way so you can follow up later with another message.

Similar to "no such host". Comes from a different lookup system, and generally means the same thing.

A host is experiencing periodic failures, and the gateway or intermediate host has not been able to deliver the message for n days. Usually the host will attempt redelivery. Usually there is nothing wrong with the user address, so it is a list owner decision as to whether it is worth waiting out the transient failure or going ahead and setting the user to NOMAIL. Unfortunately, by the time you get this message, the failure is n days in the past, the "transient failure" is very probably over, and you are likely to receive further error messages for n more days until the intermediate host's queue is exhausted.

Self explanatory. This usually happens on systems with tiny user mailbox space, but it can happen on any system if a user subscribes to too many lists or goes on an extended vacation without setting lists to NOMAIL. The best solution is to set the user to NOMAIL yourself. Variations on this message include VMS's "file extend failed writing to [disk.user]MAIL.MAI".

This is a favorite Unix sendmail configuration bounce. NOMAIL or DELETE, according to your preference. Since it is a configuration problem, it is usually transient. One system sent the following under an "unknown mailer error 1" heading:

binmail: /usr/spool/mail/userid: too big to accept new messages. 
 It's size is 205735 bytes which is 935 bytes over quota. 
mail: cannot open dead.letter 
554 ... unknown mailer error 1 

This is apparently a "mailbox full" error, as "userid's" mail spool is "over quota". It is also possible that it means your message would put the user over quota by 935 bytes. Either way, there isn't enough space in the user's mailbox to store your message (in this case, it was a daily digest). Note that "unknown mailer error x" does not always mean the user's mailbox is full what it always means is that sendmail cannot identify the cause of the error.

Obviously this is not a properly-configured address (at least, not as far as LISTSERV is concerned), and if you SCAN or QUERY the list for it, you will get a negative response. If, however, you SCAN the list for LLONG, you may find a user such as:

> scan test-l LLONG
Bill Smith 
SCAN: 1 match.

This user can now be set to NOMAIL and the errors will stop after the Banyan host has emptied its queue. If you do not find the user on the first SCAN, try using another part of the address as your search text. Note that a user may have his mail forwarded from the account that is actually subscribed to an account on another machine where he reads his mail. If the second machine is bouncing the mail, it may not be immediately apparent from the bounce messages that the mail is actually being forwarded. It is important to check for variants of the userid in the bounce message as it may be related to the userid that is actually subscribed to the list.

Note that there are many forms of error messages. Many mail systems do not conform to Internet "standards" (some of them even return non-English error messages!) and LISTSERV's auto-deletion feature will not always catch their bounces. If you receive a bounce that you simply cant understand, you can forward it to the LSTOWN-L mailing list for help deciphering it.

2.10.2. The "auto-delete" feature

LISTSERV supports several levels of automatic deletion based on error messages passed back to it in a recognizable by certain remote systems. While auto-delete will not solve all of your bouncing mail problems, it has the potential to take care of most "permanent" errors (including "no such user" and "no such host"). However, note that auto-delete ignores "temporary" errors such as "host unreachable for 3 days", "system error", "disk quota exceeded", and so forth, such that users whose accounts generate "temporary" errors are not summarily deleted from the list.

By default, lists running under LISTSERV 1.8b and higher generate a report which lets the list owner know what userids are causing problems, rather than deleting users at the first error LISTSERV understands. If the Delay() and Max() parametersparameters are set to non-zero values for a list coded "Auto-Delete= Yes", LISTSERV will not take immediate action on mail delivery errors. You will receive an "auto-deletion monitoring report" daily to show you which subscribers are bouncing mail, what the error is, when it started, when the last error arrived, and how many errors have been received for the subscriber in total. By default, LISTSERV will wait 4 days (or for a maximum of 100 error messages per individual user) before deleting a subscriber.

If you code Delay(0), LISTSERV will not wait to take action, but will delete the subscriber at the first error LISTSERV understands.

By default, lists with "Validate= All" are set "Auto-Delete= No", while all other lists are set "Auto-Delete= Yes,Semi-Auto,Delay(4),Max(100)".

Implementation of the "Auto-Delete=" keyword is discussed in detail in the full List Owner's Manual, Appendix B, List Keyword Alphabetical Reference, under "Error Handling Keywords."

2.11. What to do when a user is "served out"

If a user sends more than 21 consecutive invalid commands to LISTSERV, LISTSERV automatically "serves" that user out so that further commands from that user will be ignored. This is done because LISTSERV has no way to know that the invalid commands aren't actually a mailing loop--so instead of accepting the invalid commands forever, LISTSERV stops responding to them after it sees 21 of them. LISTSERV will actually stop reading an individual message after it counts 20 invalid commands inside that message, so if an individual user is sending list mail to the LISTSERV address (for instance), he won't get served out if he sends one such message to LISTSERV; it takes at least two in a row from the same user.

Should a user become served off in this fashion, it is possible for the list owner or any other user to issue a SERVE internet-address command to restore that user's access. (The user who is served out, of course, cannot do this for himself.) As with all other LISTSERV commands, the SERVE command is sent to LISTSERV and not to the list.

While served off, the user will be unable to set personal options and will be unable to subscribe or unsubscribe to lists on that server. Note that a user will likely be served off of one particular LISTSERV site but not others, and also that the user may not even realize that he has been served off (in spite of the fact that LISTSERV sends notification to the user to that effect).

Note that the SERVE command will not restore service to users who have been manually served off by the LISTSERV maintainer.

2.12. What to do if a LISTSERV error "holds" your list

From time to time, an error condition may be experienced by LISTSERV that causes it to "hold" or "freeze" your list. Mail for your list will simply be held in LISTSERV's job queue until the list is freed (in other words, you should not lose any mail because of these situations). This condition can generally be solved by sending LISTSERV the command:

While this will usually work, there are certain error conditions under which just freeing the list will not solve the problem. Three of these are detailed below:

Major entity not found

This error means that for some reason the directory for your list pointed to by the "Notebook=" and/or "Digest=" keywords does not exist. Forward a copy to your LISTSERV maintainer. (Generally the LISTSERV maintainers get copies of these errors, but it doesn't hurt to notify them anyway.) Technically you should never see this error, but it has been know to happen.

File is locked by another process

This error will generally only happen for lists that have notebook archives available for anonymous FTP from the server, and results from LISTSERV attempting to process mail for your list while someone is downloading the current notebook. The FTP server locks the file and LISTSERV can't open it to add the next posting to it. As soon as the FTP user finishes his download, the FTP server will unlock the file and LISTSERV will be able to write to it again. Just send the "FREE listname" command and LISTSERV will reprocess the message that caused the problem and any other messages that have arrived for the list in the meantime.

If this error persists, forward one to your LISTSERV maintainer.

This message means that your list has processed the maximum number of messages that it is allowed to process for one day. In order to start the list processing messages again, you have to send the command
FREE listname

to LISTSERV. The default number of messages per day is 50. If you want to increase the number of messages processed before an automatic hold is placed on your list, you need to change the value of the "Daily-Threshold=" list header keyword for your list.

2.13. Reviewing the list of subscribers

Any time you want to review the list of your subscribers, simply send LISTSERV the command

There are several options to the REView command, but the basic command sends back the list header and the list of subscribers. Note that the REView command sends back a copy of the list that is not suitable for editing and storing back on the server.

If you want to keep certain classes of users from reviewing your list of subscribers, you can set the list header keyword "Review=" appropriately. For instance:

* Review= Private

allows only subscribers to review the list, and

* Review= Owners

allows only list owners to review the list. Classes of users who are not allowed to review the subscriber list get back a copy of the list header only, with a message that they are not allowed to review the subscriber list.

2.14. Managing Notebook archives

If your list is coded "Notebook= No", your list isn't set up to keep notebook archives (in other words, files containing the mail posted to your list; you will also hear these called "list archives" or even notelogs). You should consult your LISTSERV maintainer before changing the keyword to create list archive notebooks. For security reasons, the LISTSERV maintainer will have to set the keyword for you. Notebook archives take up disk space and (depending on your host sites policies) may necessitate an additional fee or other consideration.

2.14.1 Indexing available archive notebooks

To find out what archive notebooks are available for your list, simply send the command

to LISTSERV.

2.14.2. Deleting existing archive notebooks

To delete an existing archive notebook, simply execute a PUT operation for the notebook in question without sending any other text along with the PUT command line. For instance:

without any other additional text would delete MYLIST LOG9607 from the server. Note that extra carriage return and/or line feed characters following the PUT command are considered text to be stored on the server, and you will end up with a very short file consisting of cr/lf combinations corresponding to the number of times you hit RETURN after the PUT command. The best way to avoid this is to type the PUT command without a following RETURN and send the mail.

2.14.3. The LISTSERV WWW archive interface

If your list is set up with public notebooks (i.e., Notebook= Yes,...Public), and assuming that your host site has the LISTSERV WWW archive interface installed, you may elect to have your notebooks viewable and searchable via the World Wide Web. If the list was originally created with public notebooks, this feature may already be enabled; the URL for your list would be something like

For instance, the MYLIST-L list weve been using for examples above would have the URL

If your list has public notebooks but isn't available on the Web, just drop a line to your LISTSERV maintainers to have them enable this feature for you.

2.15. Digests and indexes

There are three ways to have LISTSERV deliver mail to subscribers. First of all is the default: messages are sent individually, as they are received and processed by LISTSERV.

A second way LISTSERV delivers mail is called "digest mode" or simply "digests". A digest is a compilation of all postings to the list in one large message, typically sent at midnight at the end of the digest period (which is typically daily). Digests are good for people who don't want to clutter up their mailbox with lots of single postings, and who want to read the day's postings in one sitting. To turn on digest mode, a subscriber sends LISTSERV the command

The final way LISTSERV will deliver mail is in "index mode". An index is simply a list of all the topics sent to the list during the same period used for the digest, along with information about who sent each message and how long each message is. The subscriber can retrieve the individual messages that he or she wants by using the GETPOST command along with the index numbers of the postings (instructions are sent along with the index). To turn on index mode, a subscriber sends LISTSERV the command

If a subscriber wants to turn off either index mode or digest mode, they send LISTSERV the command

to turn off digest mode and return to individual postings, or

to turn off index mode and return to individual postings. If a subscriber wants to switch from INDEX to DIGEST or vice-versa, they simply send the appropriate SET command for the mode they want.

Daily digests that are sent at midnight are enabled by default when you have "Notebook= Yes...". They are disabled by default when "Notebook= No". If you want to have digests but not archive notebooks, the list header keyword "Digest=" must be set explicitly. As with the "Notebook=" keyword, the first two parameters of the "Digest=" keyword may be set only by the LISTSERV maintainer, so if you do not have archive notebooks enabled but want to enable digests, you will have to contact the LISTSERV maintainer. Other parameters of the "Digest=" keyword, as with the "Notebook=" keyword, may be modified by the list owner.

Indexes are only available if you have notebook archives enabled. This is because the indexes depend on the availability of existing notebook archives for the GETPOST command. So indexes are automatically enabled if you have "Notebook= Yes..." and disabled if "Notebook= No".

3. Where to go from here

3.1. The list owner's manual

L-Soft has made available a comprehensive 145-page List Owner's Manual for LISTSERV both for reading online via your web browser and for download in various word processing formats. This manual contains information on just about everything you need to know about being a list owner. You can find it at the URL

3.2. LISTSERV-related mailing lists

Two LISTSERV lists exist for list owner and LISTSERV maintainerLISTSERV maintainer questions.

LSTSRV-L is the LISTSERV give-and-take forum. Its primary mission is to provide assistance to LISTSERV maintainerLISTSERV maintainers, but it can also be of interest to list owners who desire a more in-depth knowledge of the workings of the system. To subscribe to LSTSRV-L, send your subscription request to LISTSERV@LISTSERV.NET.

LSTOWN-L is the LISTSERV list owners' discussion list, where list owners can get assistance on list maintenance and other aspects of list ownership. To subscribe to LSTOWN-L, send your subscription request to LISTSERV@LISTSERV.NET.

Revisions