![[LISTSERV logo]](../images/LISTSERV-generic.gif)
![[Online documentation]](../images/HDR-doc.gif)
|
|
|
L-Soft international, Inc.
QuickStart Guide for New List Owners
for
LISTSERV®, version 1.8d
May 1, 1998
Initial Release
r982602-001
The reference number of this document is 9802-UD-04.
Permission is granted to copy this document, at no charge and in its entirety, provided that the copies are not used for commercial advantage, that the source is cited and that the present copyright notice is included in all copies, so that the recipients of such copies are equally bound to abide by the present conditions. Prior written permission is required for any commercial use of this document, in whole or in part, and for any partial reproduction of the contents of this document exceeding 50 lines of up to 80 characters, or equivalent. The title page, table of contents and index, if any, are not considered to be part of the document for the purposes of this copyright notice, and can be freely removed if present.
The purpose of this copyright is to protect your right to make free copies of this manual for your friends and colleagues, to prevent publishers from using it for commercial advantage, and to prevent ill-meaning people from altering the meaning of the document by changing or removing a few paragraphs.
Copyright © 1998, L-Soft international, Inc.
1. Welcome to LISTSERV®!
2. Congratulations! You are a new List
Owner! Now what do you do?
2.1 The Command Address and List Address
2.2 First Steps in List Ownership
2.2.1 Setting Up a Personal Password
2.2.2 "Getting" Your List
2.2.3 "Putting" or Storing Your List Back to the Server
2.2.4 Adding Subscribers to Your List
2.2.5 Deleting Subscribers from Your List
2.2.6 Finding who are the List Members
3. Sample List Headers
4. Moderated Lists
5. Error Messages
5.1 Delivery Error Messages or "Bounces"
5.2 Rejected Posts
5.3 Rejected Commands
7. Additional Topics for EASE-HOME List Owners
7.1 The Ease-Home Support Forum Mailing List
7.2 The Ease-Home WWW List Management Interface
7.3 Ease-Home Frequently Asked Questions
8. Where to Find More Information
LISTSERV® is a system that allows you to create, manage and control electronic "mailing lists" on a corporate network or on the Internet. The person who manages a list is known as the "List Owner".
The goal of these pages is to introduce the beginning LISTSERV List Owner to the basic commands, configuration options, and Frequently Asked Questions (FAQ) that new List Owners face when they first begin managing a LISTSERV-based mailing list.
Since LISTSERV is a very robust, feature-rich system, all of the options and functionality cannot be discussed here. For detailed information on LISTSERV commands, the List Owner should refer to the LISTSERV Owner's Manual
The most important thing to keep in mind is that all commands to query, change, and configure your list are done mainly via e-mail messages, or via the newly introduced WWW interface for version 1.8d or later. This is true whether you are a List Owner sending in list configuration options or a List Subscriber setting personal options. If your list is running on LISTSERV Version 1.8d, you may be able to use an online WWW interface to run commands. For example, Ease-Home WWW List Management Interface.
The address to send commands, queries, etc., is known as the Command Address. This address is different than the List Address where messages are "posted" to the list. The most common mistake among List Subscribers is to send commands to the List Address and to try to post messages to the Command Address.
For example, assuming that your list is running on a server with the internet address of DOMAIN.COM, then the Command Address is
LISTSERV@DOMAIN.COM
And the List Address is
listname@DOMAIN.COM
assuming that your list name is listname.
Try this out. To determine the LISTSERV Version and Site Manager for your list send the command
SHOW VERSION
in the body of an e-mail to the LISTSERV Command Address for your site.
The first thing you must do is create a personal password as List Owner and GET your list. The terminology "GET your list" means that you retrieve the configuration file containing all the list control parameters so that you can customize your list to your specifications. Of course, you could keep the initial specifications that your list was installed with and it will run just fine. However, it is likely that the more you know about configuring your list, the more you will want to customize it to meet your specific needs.
To set up a password so that configuration options can be altered for the list, send this command to the Command Address:
PW ADD mypassword
where mypassword will consist of alphanumeric characters from the set: A-Z a-z 0-9 $#@_-?!|%. Passwords are not case sensitive.
When LISTSERV receives your password request, it will send you an e-mail message asking you to confirm your password for security purposes. When you receive this message, you should reply to it by inserting the word "OK" (without the quotes) in the body of the reply. No other words should be in the reply and you should check your "Send to:" field to make sure that the address is the LISTSERV Command Address. These instructions are also repeated in the message asking you to CONFIRM your password.
To see your initial specifications for your list, (hereafter called the "List Header") you will send in the command
GET listname (HEADER
to the LISTSERV Command Address. Replace the parameter listname with the name of your list. The parameter (HEADER, which can be abbreviated as (HEAD is required for you to retrieve only the configuration options and omit the e-mail addresses of List Subscribers. The "(" is required. It is recommended that you always use this (HEAD parameter to avoid complications when using the PUT command to save your List Header back to LISTSERV. You could inadvertently overwrite your entire list of subscribers, and thereby destroy your list, should you PUT a list header that included subscriber addresses.
The GET command automatically "locks" your list so that no changes can be made to the operating copy on the server until you store your list back to the server via a PUT command. Alternatively, should you decide no changes are needed, issue an UNLOCK listname command. A locked list prevents new subscribers from joining the list or existing subscribers from changing their delivery options. You don't want to leave the list in a "locked" state for days or weeks.
When you GET your List Header, the file will be sent with the command
PUT listname LIST PW=XXXXXXXX
already written as the first line. This enables you to simply insert your password (in place of the XXXXXXX) when you send the List Header back to the Command Address after you have made any desired changes. The text lines making up the List Header must follow directly after the PUT command line as part of your mail msg. Do not send the List Header as a mail attachment.
After the List Header is successfully stored on the server, you will receive a confirmation via e-mail. Any syntax errors will be identified and reported back to you.
Alternatively, for lists residing on servers with the LISTSERV 1.8d WWW List Management Interface (such as EASE-HOME) you may modify the List Header directly via the WWW interface in your browser.
For a complete and detailed explanation of all List Header keywords and examples of their use see the LISTSERV Owner's Manual Appendix B: List Keyword Alphabetical Reference
You may add users to your new list individually by sending the following command
[QUIET] ADD listname user@address Firstname Lastname
to the Command Address where listname is the name of your list and the subscriber's first and last names replace Firstname Lastname. If the full name is unavailable, you may use an *.
The [QUIET] modifier is an optional parameter and indicates that no notification or WELCOME file will be sent.
You may add multiple subscribers at a time by sending the "bulk-add" command
QUIET ADD listname DD=X IMPORT
//X DD *
user1@address Firstname Lastname
user2@address Firstname Lastname
etc
/*
to the Command Address.
The bulk method allows you to omit the full name if it is unavailable.
No notification will be sent to the new subscribers. You may wish to post to your list after adding everyone to let them know that the list is now ready.
Subscribers may add themselves. You may also tell your potential list members they can subscribe themselves by sending the command:
SUBSCRIBE listname Firstname Lastname
to the Command Address.
In LISTSERV 1.8d, potential subscribers may also send an email msg to the special "command-free" subscribe address:
listname-SUBSCRIBE-REQUEST@DOMAIN.COM
The content of the msg is ignored, the use of the special subscribe-address is sufficient.
Alternatively, for lists residing on servers with the LISTSERV 1.8d WWW List Management Interface (such as EASE-HOME) you may add new subscribers one-at-a-time or by uploading a "bulk-add" file containing a list of e-mail addresses and names into your browser.
To delete subscribers from your list send the command
[QUIET] DELETE listname user@address
to the Command Address. The DELETE command (which can be abbreviated DEL), must have the subscriber's address and must not have the full name (i.e., Firstname Lastname) as parameters.
The [QUIET] modifier is an optional parameter and indicates that no notification will be sent to the subscriber.
Subscribers may remove themselves. You may also tell your potential list members they can un-subscribe themselves by sending the command:
SIGNOFF listname
to the Command Address.
In LISTSERV 1.8d, subscribers may also send an email msg to the special "command-free" signoff address:
listname-SIGNOFF-REQUEST@DOMAIN.COM
The content of the msg is ignored, the use of the special signoff-address is sufficient.
Alternatively, for lists residing on servers with the LISTSERV 1.8d WWW List Management Interface (such as EASE-HOME) you may delete subscribers one-at-a-time or by uploading a "bulk-delete" file containing only their e-mail addresses into your browser.
If you wish to get a list of subscribers for your list send the command
REVIEW listname
to the Command Address. The REVIEW command may be abbreviated REV and has many options. For example, if you wish the list of subscribers without the List Header attached send
REV listname NOH
where NOH stands for NOHEADER. Or if you only wish a count of members, the command
REV listname S
where S stands for SHORT. Or send them together
REV listname S NOH.
If a subscriber has "concealed" their subscription from a REVIEW command, the List Owner can always get a list of all concealed subscribers via the QUERY command.
The QUERY command is very powerful and allows wildcards. For example, to get a list of all subscribers (and their subscriber options) send the command
QUERY listname FOR *@*
If you only want the "concealed" members send
QUERY listname WITH CONCEAL FOR *@*
In both cases the * means that any character can appear before and after the @ in the e-mail address.
For more information on adding and deleting subscribers see the LISTSERV Owner's Manual Chapter 4. For more information on managing subscriber options see this tutorial or LISTSERV Owner's Manual Chapter 5.
The flexibility of LISTSERV permits numerous variations in the types of mailing lists that can be defined. Below we have provided sample List Headers that you may wish to use and/or modify to meet your requirements. These examples will also allow you to become familiar with many List Header specification keywords and their parameters. A complete alphabetical listing of all List Header keywords may be found in the LISTSERV Owner's Manual Appendix B: List Keyword Alphabetical Reference.
Note: The following examples are based on the full-featured LISTSERV-Classic version. LISTSERV-Lite is mostly similar, but not all features are available in the Lite Version so not all of these examples will be completely correct for that version. See How is LISTSERV Lite different from LISTSERV Classic? for more details.
There are several ways in which a moderated list may be defined and these are explained in detail in the LISTSERV Owner's Manual Chapter 6.4.
One method is to define the List Header keywords:
* Send= Editor, Confirm
* Editor= editor1@address
which forwards all postings from non-editors to the list editor or moderator for approval. The list editor will then forward the message back to the list. However, unless your mail program supports special Resent-From: header lines, the mail From: address may be changed to appear to come From: the editor, not the original sender.
Using
* Send= Editor,Hold,Confirm
* Editor= editor1@address
will make LISTSERV hold the posted message until the editor approves the post with the "OK" mechanism. This method allows the message From: line to remain that of the original poster, and is recommended as the easiest for beginning List Owners.
Error messages fall into three major categories.
The good news is that the List Header keyword Auto-Delete= allows LISTSERV to intercept and handle most error messages that it receives when mail is rejected. Additionally, the Errors-to= keyword can direct error messages to a specific address rather than the owner's e-mail address. These two key options can greatly reduce the List Owner's workload.
The bad news is that not all e-mail systems are compliant with Internet standards. Therefore, LISTSERV is unable to intercept and handle all error messages. In these instances, the List Owner must take action. The most common action is for the List Owner to either DELETE the address or to set the subscriber to NOMAIL NOPOST. The latter method is kinder; for when the subscriber attempts to post to the list they will be directed to the List Owner for assistance.
(The NOPOST option is not available in LISTSERV-Lite.)
| Error Message | Recommended Intervention |
| No such user at host | This message could be transitory. Set the subscriber to NOMAIL NOPOST or DELete. |
| No such host | This message could be authoritative or transitory. Set the subscriber to NOMAIL NOPOST. |
| No MX or A records for host | This message could be authoritative or transitory. Set the subscriber to NOMAIL NOPOST. |
| Transient Failure: cannot deliver for n days | A host is experiencing periodic failures and the intermediate host or gateway will store the message and try to deliver it for n days. Usually, by the time you get this message the problem is resolved. Therefore, you can either "wait out" the problem or set NOMAIL NOPOST as above. |
| mailbox full | Some subscriber's providers have a limitation on mailbox space. Or the subscriber may have gone on vacation and forgotten to unsubscribe or set themselves to NOMAIL. Set the subscriber to NOMAIL NOPOST. |
| unknown mailer error x | A UNIX sendmail configuration error message. Could also indicate a full mailbox. Set the subscriber to NOMAIL NOPOST. |
| Bounced, but sent successfully | Misleading. Equivalent to "no known user." Set the subscriber to NOMAIL NOPOST |
There are many possible reasons that List Subscribers or List Owners may not be able to post to the list. Several of these are described below.
| Cause | Explanation |
| Subscriber is sending mail to the Command Address | Inadvertently, subscribers may send postings to the LISTSERV Command Address rather than the List Address. Since LISTSERV cannot recognize any command in the post, it will reject the "command" and send an error report to the subscriber. Hopefully, the subscriber will realize what they did and post correctly. |
| Subscriber is sending mail from an unsubscribed address | It is important to note that Private and Self-moderated lists only allow direct posting by subscribed members. Therefore, if a subscriber attempts to post from an unsubscribed address or an e-mail address even slightly different than their subscribed address, the post will bounce (for a Private list) or be sent to the moderator for review (for a Self-moderated list). |
| Subscriber has been deleted due to the Renewal and/or Auto-Delete configuration | Only subscribers may post to a Private or a Self-moderated list. |
| Subscriber is set to NOPOST | The subscriber option NOPOST has been set, and therefore, this user is not allowed to post to the list. (Does not apply to LISTSERV-Lite.) |
| List Storage Quota has been exceeded | The disk Quota for archiving and digests has been exceeded and therefore the list is in the HOLD state. The Quota must be increased or files deleted, and the FREE listname command sent for posting to be resumed. (This will apply to all members.) |
| LISTSERV internal loop checking routines have rejected a post | By default, LISTSERV's internal loop-checking routines look for anything in the body of a mail message that looks like a header line - specifically anything that looks like a "To:", "Sender:", or "Reply-To:" header line. |
| Bounced, but sent successfully | Misleading. Equivalent to "no known user." Set the subscriber to NOMAIL NOPOST |
There are many possible reasons that List Subscribers and List Owners may have commands rejected. Several of these are described below.
| Cause | Explanation |
| The command is being sent to the List Address rather than the Command Address. | LISTSERV tries to recognize possible commands in list mail. If commands are found, LISTSERV sends an error report to the sender. Hopefully, the subscriber will realize what they did and send the command correctly. |
| Command sent from an unsubscribed address. | Depending upon the security level of your list, many commands must be sent from the subscribed address. |
| Incorrect Syntax | Self-explanatory. |
| Command can only be performed by an authorized person. | Some list commands may only be issued by the List Owner. Furthermore, there are some protected commands that may only be issued by the LISTSERV Site Manager at your host. |
| Commands not acknowledged by LISTSERV. | You send a command and get back nothing at all from LISTSERV. Note that LISTSERV ALWAYS sends a command acknowledgement message for every command, reporting the success, results, or failure of the command. The problem is that some e-mail providers are not compliant with Internet standards and may reject LISTSERV command acknowledgement msgs (which use a Blank RFC821 From: <> return address) in a misguided attempt to prevent "spamming." The only solution is to try and convince the provider that LISTSERV mail is valid and the standards in fact require mailers to accept this kind of mail or to change providers. |
LISTSERV has two types of archives available. The first are archive notebooks where, if activated, all list postings are saved and may be accessed by List Owners and Subscribers (and perhaps by non-subscribers if the archives are public). The files in these archives are also known as notebook logs.
The second type of archive is called a file archive and basically operates as a file server. If file archives are activated (by creating a file catalog), owners may store files there that were not posted to the list.
To activate notebook logs for your list and thus, save all list postings, use the * Notebook=List Header keyword in the format:
* Notebook=Yes,Location,Interval,Private|Public
You will require assistance from your LISTSERV Site Manager to determine the value of the Location parameter.
Archive Notebooks are discussed in detail in Chapter 7 of the LISTSERV Owner's Manual. They may be searched via database functions, downloaded in their entirety or by individual list posting. Although the List Owner may edit and delete notebook logs, only the list and/or the LISTSERV Site Manager may create a notebook log.
Editing notebook logs is an advanced procedure and you should build your skills as a List Owner before attempting it. After you have gained confidence, examine this tutorialfor instructions.
Depending upon your host site, you may be able to make your archive notebooks available through the WWW. You will need assistance from your LISTSERV Site Manager to initiate this process. LISTSERV Version 1.8d and later allow password-protected WWW access to Private archive notebooks.
Database functions for both the VM and non-VM versions (1.8c and later) of LISTSERV are discussed in Chapter 7.3. For an excellent guide to database functions under the non-VM version of LISTSERV visit this site maintained by Jared Weinberger.Another excellent WWW source is the NIH Archive Search Tutorial. Although these sites were created for specific lists or hosts and are not supported by L-Soft, the information is useful and can be applied generally to all LISTSERV Version 1.8c and later lists.
To activate the file server capability for your list and thus File Archives you will need to create a listname.FILELIST file if your list is running on VM or a listname.CATALOG file if your list is running on Version 1.8c or later. You will require the assistance of the LISTSERV Site Manager to initially create these files. However, after that point, the List Owner will have the capability to add, edit, and delete File Archives.
File Archive files cannot be searched with database commands. They must be downloaded in their entirety. List members (or anyone if the archive is public) may download the files but cannot add files, edit or delete them.
Chapter 8 of the LISTSERV Owner's Manual discusses in detail the capabilities and maintenance of File Archives.
L-Soft's Ease-Home list hosting service is a full-featured version of LISTSERV-Classic. It is intended for non-commercial use for those clubs and hobbyists that want the benefits, features, reliability and performance of the traditional LISTSERV system at an affordable price. To maintain the low cost, mailing lists can be no larger than 1000 members and it is requested that the number of messages per day does not exceed 100.
Additionally, to achieve the biggest cost savings, instead of one-on-one customer support, all new List Owners are automatically subscribed to the Ease-Home Support Forum mailing list. Members on this list include L-Soft technical support, more experienced List Owners, and new List Owners. The purpose of the Ease-Home Support Forum is to act as a platform where more experienced List Owners and L-Soft technical support can easily assist less experienced List Owners regarding list configuration and management. The discussion includes setting list parameters, resolving error messages and sharing new techniques.
The Ease-Home Support Forum List has WWW archives where List Owners may search for common issues and solutions. Many New Owners have questions that others have asked before. The answers may easily be searched in the list archives.
If you are not already a member of the Ease-Home Support Forum List and would like to join send a blank e-mail to EASE-HOME-SUBSCRIBE-REQUEST@HOME.EASE.LSOFT.COM and you will be automatically subscribed.
The Ease-Home list hosting service includes a LISTSERV 1.8d WWW List Management Interface to manage Ease-Home lists. This interface provides an easy way to set subscriber options, modify the List Header and even customize default message templates and information messages such as the WELCOME and FAREWELL files. In effect, the interface allows Ease-Home List Owners a very convenient method to perform commands and configure features without using traditional LISTSERV e-mail commands.
The Ease-Home Support Forum has proven to be a valuable resource for both new and experienced List Owners. Over time, many Ease-Home List Owners have faced similar problems and shared their expertise. The following are some of the Frequently Asked Questions that have appeared on the list.
1. "Help! I just signed up and have no idea what to do! I need to convert my list from another type of mailing list system ASAP before my old list expires. Please tell me where to start!" [Answer]
2. "How can I get a label to appear in the "Subject:" line of all posts so subscribers can easily tell that the message is from my list?" [Answer]
3. "When I use the "Reply" feature of my mail program sometimes the message goes back to the list and other times it goes back to the person who posted the original message. Why is this and how can I set it so that it always goes back to the list (or to the subscriber, etc...)?" [Answer]
4. "When I send command messages to LISTSERV, it sometimes takes hours or even days before I get a response. Why is response so slow and how am I to manage my list when I can not even send and receive mail? I receive mail just fine from the rest of the world." [Answer]
5. "How can I make my list available in digest format?" [Answer]
6. "Help! I received the following error message when I posted to my list and I have no idea what it means. It seems that my list is "frozen" and nothing is processing." [Answer]
7. "When I issued the REVIEW listname command I noticed that some of my subscribers are set to CONCEAL. Since I do not want anonymous subscribers how can I prevent them from CONCEALing themselves?" [Answer]
These links provide further detail for List Owners.
Ease-Home Support Forum List Archives
Tutorial on Setting Subscriber Options
Tutorial on Editing list message Archives
Creating Custom Welcome and Farewell Files for Your List
The following sites are not supported by L-Soft; however, new List Owners may find them very helpful:
National Institutes of Health (NIH) LISTSERV Host Site
Jared Weinberger's LISTSERV Search Tutorial
We hope you found this tutorial helpful. It is presently in "beta" form and your feedback is very important. Please let us know if you found it helpful, what you liked, and what you think needs improvement. In addition, include any topics you think should be added.