L-Soft international, Inc.
List Owner's Manual
for
LISTSERV®, version 14.5
24 February 2006
LISTSERV 14.5 Release
The reference number of this document is 0603-UD-02.
Information in this document is subject to change without notice. Companies, names and data used in examples herein are fictitious unless otherwise noted. L-Soft international, Inc. does not endorse or approve the use of any of the product names or trademarks appearing in this document.
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 ã 1996-2006, L-Soft international, Inc.
All Rights Reserved Worldwide.
L-SOFT, LISTSERV and LSMTP are a registered trademarks of L-Soft international, Inc.
LMail is a trademark of L-Soft international.
EASE and CataList are service marks of L-Soft international, Inc.
UNIX is a registered trademark of X/Open Company Limited.
AIX and IBM are registered trademarks of International Business Machines Corporation.
Alpha AXP, Ultrix, OpenVMS and VMS are trademarks of Digital Equipment Corporation.
OSF/1 is a registered trademark of Open Software Foundation, Inc.
Microsoft is a registered trademark and Windows, Windows NT and Windows 95 are trademarks of Microsoft Corporation.
HP is a registered trademark of Hewlett-Packard Company.
Sun is a registered trademark of Sun Microsystems, Inc.
IRIX is a trademark of Silicon Graphics, Inc.
PMDF is a registered trademark of Innosoft International.
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:
http://www.lsoft.com/manuals/index.html
L-Soft invites comment on its manuals. Please feel free to send your comments via e-mail to MANUALS@LSOFT.COM, and mention which manual you are commenting on. (However, please do not send support questions to this address.)
"Hot fix" revisions to this and other L-Soft manuals are posted as they are made to the master document, on the announcement-only mailing list:
LSOFT-DOC-UPDATES@PEACH.EASE.LSOFT.COM
A word about formatting: This manual was written in Microsoft Word 2000, and originally formatted to be printed on 8-1/2"x11" paper on a Hewlet-Packard LaserJet 1000 series printer. When printing the manual on a different type of printer, or converting to a different word-processing program, it is highly likely that the formatting and pagination will change and it will be necessary to update the tables of contents and figures as well as the index prior to printing. The author has taken great pains to ensure that the pagination and formatting works properly with the particular printer mentioned above, and cannot be held responsible for what is, in the end, a limitation of the software used to produce the manual.
Reference Number 0603-UD-02
Preface: LISTSERV Command Syntax and Other Conventions
Editorial Note – New Version Numbering
LISTSERV Command Syntax Conventions
1. About Mailing Lists and LISTSERV
2. Starting a Mailing List – The Basics
2.1. Avoid duplication of effort
2.2. What skills do I need to start and maintain a LISTSERV mailing list?
2.3. Creating a mailing list – Where can it be done, and Who can do it?
2.4. List Header Keywords and what they do
2.5. Sending commands to LISTSERV
2.6. Defining Personal Passwords
2.7. Retrieving the list configuration
2.7.1. Who can edit the list configuration?
2.7.2. Retrieving the list configuration by email
2.10. Storing the list on the host machine
2.12.1. First line of defense: The VALIDATE= keyword
2.12.2. Controlling subscription requests
2.12.3. Controlling the service area of your list
2.12.4. Controlling who may review the list of subscribers
2.12.5. Controlling who may access the notebook files
2.12.6. Controlling who may post mail to the list
2.12.7. The "OK" confirmation mechanism
2.12.8 Explicitly cancelling "OK" cookies (1.8e)
2.12.9. Restricting subscriber privileges
2.12.10. Restricting the number of postings per user to the list per day
2.13. How to set up lists for specific purposes
2.13.1. Public discussion lists
2.13.2. Private discussion lists
2.13.7. Private edited/moderated lists
2.13.10. Restricted subscription lists with automatically-generated questionnaire
2.13.12. "Super-lists" and "sub-lists"
2.14. List passwords are now obsolete
2.15. Allowing/Blocking MIME Attachments
2.17. DomainKeys Message Signing (14.5)
3. Advertising Your Public Mailing Lists
3.1. Lists of Lists maintained by LISTSERV
3.2. Adding HTML to a list header for the CataList
3.2.2. Inserting a pointer to another list
3.2.3. Restrictions on the placement of equal signs
3.3. Defining search categories in a list header for the CataList
3.3.1. Examples of category settings
3.4. The INFO <listname> command and how to implement it
3.6. The Internet Network Information Center (INTERNIC)
3.7. The Global List Exchange (GLX) and why you should mention it
3.8. How NOT to advertise a mailing list
4.1. How to add and delete subscribers to/from a list
4.1.1. Adding users whose address and real name exceed 80 characters
4.1.2. X.400 and X.500 addressing--Special Problems
4.1.3. Continuation card syntax
4.2. Finding users who do not appear in the list
4.3. Converting existing lists from other systems to LISTSERV
4.3.1. Converting mailing lists
4.3.2. Converting message archives
4.4. Adding subscribers to lists in bulk
4.5. Deleting subscribers from lists in bulk
4.6. Using the QUIET option with commands
4.7. Dealing with bounced mail
4.7.1. What is a bounce, and what can typically cause one?
4.7.2. The owner-listname address
4.7.3. What to do about several types of bounces
4.7.4. Redistribution and forwarding
4.7.5. "Sender:", "From:" or "Reply-To:" field in body causes bounce
4.8. Delivery error handling features
4.8.1. Auto-Delete considerations for holidays
4.9.2. Passive address probing
4.10. Subscription confirmation
4.12. Using the SERVE command when a user is "served out"
5. Setting Subscription Options For Subscribers
5.1. How to review current subscription options with QUERY
5.2. How to set personal subscription options for subscribers
5.3.6. Options for mail headers of incoming postings
5.3.7. Putting the list name into the Subject: field
5.4. Setting original default options with the Default-Options= keyword
6. Moderating and Editing Lists
6.1. List charters, welcome files, and administrative updates
6.2. The role of the list owner as moderator
6.3. The role of the list owner as editor
6.4. Setting up an edited list
6.5. Submitting subscriber contributions to an edited list
6.6. Message Approval with Send= Editor,Hold
6.8. The <listname> WELCOME and <listname> FAREWELL files
6.8.1. Creating and storing the listname WELCOME and FAREWELL files
6.8.2. Using the listname WELCOME file as a moderation tool
6.8.3. Using the listname FAREWELL file as a feedback tool
6.8.4. The alternative to using WELCOME and FAREWELL files
6.9. Social conventions (netiquette)
Recognize and Accept Cultural and Linguistic Differences
Private Mail Should Dictate Private Responses
Flaming is (Usually) Inappropriate
Unsolicited Advertising and Chain Letters
Other Disruptive or Abusive Behavior
6.10. Spamming: what it is, and what to do about it
6.11. Appropriate use policies: considerations
7.1. What is the list archive?
7.2. Setting up and managing archive notebooks
7.2.1 Indexing available archive notebooks
7.2.2. Deleting existing archive notebooks
7.3. Database Functions Overview
7.3.1. LISTSERV Command Job Language Interpreter
7.3.2. A basic database session (VM servers running 1.8b or earlier only)
7.3.3. A basic database session (All servers running 1.8c or later only)
7.4. Where to find more information on Database Functions
8.1. What is the file archive?
8.2. Starting a file archive for your list
8.3. Filelist maintenance (VM systems only)
8.3.2 Adding file descriptors to the filelist
8.3.3. File Access Codes (FAC) for user access
8.3.4 Deleting file descriptors from the filelist
8.4. The listname.CATALOG system on non-VM systems (1.8c and later)
8.4.1. Updating the sub-catalog
8.4.2. Indexing the sub-catalog
8.5. Storing files on the host machine
8.6. Deleting files from the host machine
8.7. Automatic File Distribution (AFD) and File Update Information (FUI)
8.9. Where to find more information on File Archives
9. Creating and Editing LISTSERV's Mail and Web Templates
9.1. What LISTSERV uses templates for
9.2. The default template files and how to get copies
9.3. Mail template format and embedded formatting commands
9.3.1. 8-bit characters in templates
9.4. Creating and editing a <listname>.MAILTPL file for a list
9.4.2. Other useful template forms
9.4.3. Tips for using templates
9.5. Storing the <listname>.MAILTPL file on the host machine
9.6. Other template files: DIGEST-H and INDEX-H
9.7. Templates and template forms for the WWW interface
9.7.1. Forms contained in DEFAULT MAILTPL
9.7.3. The default.wwwtpl file
9.7.4. The site.wwwtpl file (optional)
9.7.5. National language template files (idiom.mailtpl) (optional)
9.8. Using the DAYSEQ(n) function
9.8.2. Rotating FAQ via the PROBE1 template and "Renewal= xx-Daily"
9.8.3. Calculating the value for DAYSEQ()
9.9. Serving up custom web pages for your list
9.9.1. A practical example: ADMIN_POST
10.1. Helping subscribers figure out the answers
10.2. Loop-checking can cause occasional problems with quoted replies
10.3. User can't unsubscribe and/or change personal options
10.5. What to do if LISTSERV won’t store your list
10.6. If I can't find the answer, where do I turn?
11. Using the Web Adminstration Interface
11.1. Default LISTSERV Home Page
11.3. Setting a LISTSERV password
11.4. The List Management main page
11.5. Maintaining subcriptions via the web
11.5.1. Examine or delete a subscription
11.5.2. Add a new user to the list
11.6. Maintaining the list header via the web
11.7. Customizing how a list's pages look
11.8. Maintaining mail and WWW templates via the web
11.9. Bulk operations via the web
11.10. Sending interactive commands via the web
Appendix A: LISTSERV Command Reference for LISTSERV® version 14.4
A.1.1. List subscription commands (from most to least important)
A.1.2. Other list-related commands
A.1.4. Commands related to file server and web functions
A.1.5. Other (advanced) commands
A.2. List Owner and File Owner Commands
A.2.1. File management commands (for file owners only)
A.2.2. List management functions
Appendix B: List Keyword Reference for LISTSERV® 14.5
Appendix C: Sample Boilerplate Files
C.1. Subscription requests sent to the list
C.2. User is sending other commands to the list, or to the *-request address for the list
C.3. User isn't subscribed but complains that he's getting mail anyway
C.3. User unsubscribed successfully but is still getting list mail
C.6. You get a delivery error that doesn't specify which user account is causing the bounce
Appendix D: Related Documentation and Support
D.1. Official L-Soft Documentation
D.2. User-Created Documentation
D.2.1. LISTSERV List Owner Information Area on LISTSERV.BUFFALO.EDU
Table of Figures
Figure 2.1. Sample output of LISTS GLOBAL IBM
Figure 2.2. A sample list header file for a list called MYLIST.
Figure 2.3. The edited list header file ready to be sent back to the server.
Figure 2.4. Example: How to define list owners in the list header file.
Figure 2.5. The editor-header for a list set to Send= Editor,Hold
Figure 2.6. A typical command confirmation request.
Figure 6.2. Sample WELCOME file.
Figure 6.3. FAREWELL file used as a feedback tool.
Figure 7.1. Sample database job skeleton
Figure 7.3. Sample CJLI database search job for VM servers
Figure 7.4. Part of the LISTSERV response to the CJLI job in Figure 7.3.
Figure 7.5. CJLI job instructing LISTSERV to send specific messages to the requestor.
Figure 7.6. Sample SEARCH output from non-VM servers
Figure 8.1. Sample filelist retrieved with (CTL option.
Figure 8.2. Adding a file descriptor to the filelist
Figure 9.1. The default contents of the INFO template form of DEFAULT.MAILTPL.
Figure 9.2. Sample edited INFO template form.
Figure 9.3. Typical contents of a DIGEST-H or INDEX-H file.
Figure 10.1. Sample error message with included headers.
Figure 10.2. A slightly different sample error message with included headers.
Figure 10.3. A correctly-formatted message with included headers.
Figure A.1. Sample output of an INDEX listname command.
Table B.1. LISTSERV list-level commands and how they are affected by Validate=.
Preface: LISTSERV Command Syntax and Other Conventions
Editorial Note – New Version Numbering
With this release, L-Soft is aligning LISTSERV’s version numbering with the rest of the e-mail industry. There have been 50 released versions of LISTSERV since 1986 – 14 major upgrades and 36 minor releases. Version 1.8e in the “traditional” numbering system corresponds to 14.0, and the present update to 14.5.
Because the old nomenclature is more familiar to our users, in this version of the documentation we will continue to refer to versions of LISTSERV inferior to version 14.4 by the old versioning system.
LISTSERV Command Syntax Conventions
Generally, parameters used in this document can consist of 1 to 8 characters from the following set:
A-Z 0-9 $#@+-_:
Deviations from this include:
|
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). Must consist of at least two space-separated words, eg, "John Doe". |
|
listname |
name of an existing list |
|
node |
Either: the fully-qualified domain name (FQDN) of an Internet host; or the BITNET nodeid or Internet hostname of a BITNET machine which has taken care of supplying an ':internet' tag in its BITEARN NODES entry; |
|
host |
Generally the same as node, but normally refers specificallly to the fully-qualified domain name (FQDN) of an Internet host rather than to a BITNET nodeid. |
|
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 |
|
internet_address |
Similar to userid, but specifically refers to a complete RFC822 network address in userid@fqdn format. When we use this nomenclature a fully-qualified hostname is required. |
Other deviations from the standard set will be noted along with the affected commands.
Also please note the following conventions for representing variable or optional parameters:
|
italic type |
always indicates required parameter names that must be replaced by appropriate data when sending commands to LISTSERV |
|
< > |
Angle brackets may sometimes enclose required parameter names that must be replaced by appropriate data when sending commands to LISTSERV. Sometimes used for clarity when italic type is inappropriate |
|
[ ] |
Square brackets enclose optional parameters which, if used, must be replaced by appropriate data when sending commands to LISTSERV |
1. About Mailing Lists and LISTSERV
LISTSERV® is a system that allows you 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 BITNET academic network, LISTSERV has been continually improved and expanded to become the predominant system in use today. LISTSERV is now available for VM, OpenVMSTM, unix®, the Windows NT "family" (including Windows 2000), and Windows 95/98/ME.
Consider for a moment what the users of your electronic mail system actually use electronic mail for. Do they discuss problems and issues that face your organization, down to the departmental level? In an academic setting, do your faculty and students communicate via electronic mail? As with "real world" distribution lists, electronic mailing lists can make it possible for people to confer in a painless manner via the written word. The electronic mail software simply replaces the copying machine, with its associated costs, delays and frustrations. In fact, electronic mail lists are easier to use than most modern copiers, and a lot less likely to jam at just the worst possible moment.
Because electronic mail is delivered in a matter of seconds, or occasionally minutes, electronic mailing lists can do a lot more than supplement the traditional paper distribution lists. In some cases, an electronic mailing list can replace a conference call. Even when a conference call is more suitable, the electronic mailing list can prove a powerful tool for the distribution of papers, figures and other material needed in preparation for the conference call. And, when the call is over, it can be used to distribute a summary of the discussion and the decisions that were made. What before might have been an exchange of views between two or three people can now become an ongoing conference on the issue or problem at hand. Announcement lists and even refereed electronic journals can be made available to your audience, which can be as small as a few people or as large as the entire Internet community.
If you need a further overview, please see Appendix D, Related Documentation and Support, for information on how to get one.
2. Starting a Mailing List – The Basics
Note: This chapter (and much of the balance of this manual) assumes that you are administering your list by mail. LISTSERV 1.8d and following includes a web-based administration interface for lists which is described in Chapter 11 and which can handle most of the operations described in this chapter.
Lists that are coded "Validate= Yes,Confirm,NoPW" or "Validate= All,Confirm,NoPW" must imperatively be managed by mail, since the web administration interface is secured by passwords and these settings reject password validation, instead requiring validation by the "OK" method.
2.1. Avoid duplication of effort[1]
Before you start your list, it pays to do a careful search in several places to find out if you are duplicating an already-existing list, or if the name you are considering is already in use for a list on a differing subject.
The first place to check is the "CataList" service maintained by LISTSERV itself. This service lists all public lists running on LISTSERV servers worldwide. Point your Web browser of choice at the URL http://www.lsoft.com/CataList.html to access CataList.
If you don't have a web browser, you can alternately send the command
LISTS GLOBAL search_string
in the body of mail to LISTSERV@LISTSERV.NET (or to LISTSERV at any host site). You will receive a mail message in return containing a list of all lists known to LISTSERV where either the name of the list or the short list description contains your search string. For instance, LISTS GLOBAL IBM would result in the following being returned to you:
Excerpt from the LISTSERV lists known to LISTSERV@HOME.EASE.LSOFT.COM
---------------------------------------------------------------------
12 Dec 2001 13:35
(search string: IBM)
Copyright 2001 L-Soft international, Inc.
L-Soft international, Inc. owns the copyright to this compilation of
Internet mailing lists (the "Compilation") and hereby grants you the
right to copy the enclosed information for the sole purpose of
identifying, locating and subscribing to mailing lists of interest. Any
other usages of the Compilation, including, without limitation,
solicitation, tele-marketing, "spamming", "mail-bombing" and "spoofing"
are strictly prohibited.
***********************************************************************
* To subscribe, send mail to LISTSERV@LISTSERV.NET with the following *
* command in the text (not the subject) of your message: *
* *
* SUBSCRIBE listname *
* *
* Replace 'listname' with the name in the first column of the table. *
***********************************************************************
Network-wide ID Full address and list description
--------------- ---------------------------------
AIX-L AIX-L@NEW-LISTS.PRINCETON.EDU
IBM AIX Discussion List
Figure 2.1. Sample output of LISTS GLOBAL IBM
(Quite a few more lists were deleted for brevity)
You might want to make your search more specific, as this particular search locates every list that has IBM somewhere in its title. For instance, if you wanted to start a list on some aspect of the IBM 370, you might do better to search for IBM 370.
Alternative searches you can do include:
Check the NEW-LIST archive at
http://listserv.classroom.com/archives/new-list.html
where the NEW-LIST project (originally at North Dakota State University, later
hosted by the Internet Scout Project, and now hosted by Classroom Connect)
stores list announcements starting with June 2000[2].
The NEW-LIST archive contains information about LISTSERV lists as well as about
lists running on other types of servers.
· Check the Usenet newsgroups news.announce.newusers and news.lists , if they are available to you via your local news feed.
· Use one of the World Wide Web search engines such as Alta Vista or Google to search for matches to the name you want to use.
2.2. What skills do I need to start and maintain a LISTSERV mailing list?
You should already be familiar with your mailing system and text editor. Otherwise, there are no special skills required. It is the goal of this manual to give you what you need to know about LISTSERV user commands, privileged LISTSERV owner commands, and how to read and interpret RFC822 Internet-style mail headers. LISTSERV itself is designed to operate in an identical manner no matter which operating system it is running under. Thus the fact that LISTSERV is running under VM, VMS, some flavor of Unix, or Windows NT should not be a concern to the list owner, who may not even know which version of LISTSERV his lists are running on.
Additionally, we have made an attempt to give you a basic "list owner's course" in anticipation of some of the issues you may encounter in the course of moderating a list.
2.3. Creating a mailing list – Where can it be done, and Who can do it?
If you are looking for a site to host a list, consider the following:
· First, find out if your computing center maintains a LISTSERV host.
· If not, you might consider a commercial LISTSERV site. There are a number of such sites, including L-Soft's own EASESM service. You can get more information on EASESM by pointing a WWW browser at
http://www.lsoft.com/ease-head.html
Please note also that many sites (predominantly, but not necessarily limited to, those in .EDU domains) will not host commercial or potentially-controversial lists because of internal policies regarding appropriate use of their computing facilities. In such a case, your only option may be to seek a commercial LISTSERV site.
Physically creating the list is the task of the LISTSERV maintainer (sometimes referred to as the "LISTSERV postmaster") at a given LISTSERV host site.[3] Specific procedures for requesting a list startup vary from institution to institution. It is usually best to contact the computing center at the site for more information.
Because most list owners do not have the appropriate permissions to create lists, instructions on how to physically create lists are not included in this manual. If you are a LISTSERV maintainer, you can find these instructions in the Installation Guide that came with the software, or in the Site Manager’s Operations Manual for LISTSERV.
When choosing a name for a list, there are a few conventions and restrictions that you should keep in mind.
The "-L" convention isn't required, but it can help people to realize that the mail is coming from a mailing list rather than from a real person. The people we are referring to here are people who run Internet mail systems, who may see a great deal of mail coming from a single host and begin to wonder why. If it comes from a userid that ends in a "-L", they will be more likely to recognize it as list mail.
Reserved names
You may not create lists whose names match the following wildcards:
owner-*
*-request
*-search-request
*-server
*-signoff-request
*-subscribe-request
*-unsubscribe-request
For instance, lists cannot be made with names like "owner-loyalty", "linux-server", and "donation-request".
These "pseudo-mailboxes" have a special meaning to LISTSERV, which has internal rules that govern how mail sent to these addresses is handled. See chapter 17.3 of the Site Manager’s Operations Manual for LISTSERV for more information on what happens to mail sent to these special addresses.
Generally you want to avoid "special" characters such as the ones above the number keys on your keyboard. For example, don't use:
! which can be confused for "bang-path" addressing, e.g., UUCP
@ which is a reserved character
# which can cause problems with some mail software which uses it for addressing
$ which may have a special meaning to the unix shell
% another addressing character that could cause problems
& is sometimes reserved by non-unix systems (specifically on NT it has a special meaning to the shell). However, please note that use of this character in the name of a list or in a sendmail alias for a list will cause LISTSERV on unix to choke. Note that it is possible under unix to create a list with a "&" character in the name quite easily, and it is also possible to create a sendmail alias with a "&" character in the alias. That does not mean it will work.
* is, of course, the wildcard character.
() Parenthesis are generally reserved and can't be used in file names.
+ The plus character should be avoided because recent versions of sendmail deliver mail addressed to "user+whatever@somedomain" to "user@somedomain." Whether or not this is an intelligent thing to do on sendmail's part is left as an exercise for the user, but it can affect mail being sent to a list with a "+" character in the listname.
/ The slash character is reserved and can't be used in file names.
. Although on some systems it is physically possible to create lists with a dot character in the name, LISTSERV will not accept this nomenclature. The only place a dot can or should be used is before the word "LIST" in the PUT command; e.g., PUT MYLIST-L.LIST is equivalent to PUT MYLIST-L LIST.
" Double-quote characters are not allowed.
It is best if you avoid the use of special characters altogether and stick exclusively to the letters A-Z, numbers 0-9, and the underscore and hyphen characters when naming lists. Note that the "_" (underscore) character may cause problems with some non-compliant receiving systems. Also note that the space character (ASCII 0x20) is illegal in a list name, and L-Soft recommends that, although apostrophes (aka "single-quotes", ASCII 0x27) are valid in an RFC822 username, they not be used in list names since some mail programs may not accept them. (Prior to 1.8d, not all LISTSERV commands will work for lists whose names contain an apostrophe.)
If you have any question about the validity of a particular name, you can of course refer to RFC822 (http://nis.nsf.net/internet/documents/rfc/rfc822.txt) for the Internet standards for e-mail addressing.
Maximum length of the list name
The length of the list name (that is, the name of the list file and thus the "official" name of the list) is restricted as follows:
VM: 8 characters
Non-VM: unlimited (starting with 1.8c; but see below)
If you need a longer list name for a list running on a VM server, you should use the List-ID= keyword (see Appendix B).
PLEASE NOTE CAREFULLY that L-Soft recommends using names of 32 characters or less whenever possible as they provide for correct alignment of the results returned by certain commands. Very long (program generated) list names are likely to conflict with mail system limits and L-Soft recommends other solutions to the problem of dynamically generated lists. As a rule, list names in excess of 70 characters are likely to result in mail delivery problems.
While you can (within limits) name a LISTSERV mailing list just about anything you want, you will probably want to follow a couple of simple guidelines:
1. Keep the name simple.
2. Keep the name as short as possible without causing confusion.
No doubt you could name a list MY-LIST-FOR-MATH-STUDIES, but who wants to type that? Conversely, MLFMS-L wouldn't mean much to Joe Random User. Somewhere in the middle is a reasonable compromise, e.g., MATH-STUDIES (or even just MATH-S).
2.4. List Header Keywords and what they do
How a LISTSERV mailing list performs its tasks is defined by its header keywords. There are several different categories of keywords, each of which is discussed below in general terms. A complete alphabetical listing of list header keywords, including default settings and all options available, is provided in Appendix B.
Access Control Keywords. These keywords designate the level of "openness" for a list. They determine who can post to the list, who can review the list of subscribers, and whether or not the list is open to general subscription.
Distribution Keywords. This group has to do with how LISTSERV distributes postings to subscribers, including whether or not acknowledgments are sent back to posters, how many postings may go through the list daily, whether or not the list is available in digest form and whether it is available to USENET through a gateway. These keywords also determine whether or not list topics are enabled, and how LISTSERV will configure outgoing postings for replies.
Error Handling Keywords. Included under this group are the keywords controlling automatic deletion, loop-checking, and to whom error messages are sent for disposition when received by LISTSERV.
List Maintenance and Moderation Keywords. A fairly large group of keywords having to do with how the list is operated, including definitions for the list owner, list editor, and the list archive notebook; whether or not (and whom) to notify when users subscribe and sign off; how often subscriptions must be renewed, and so forth. These are perhaps the most basic keywords that can be set for a given list, and one of them ("Owner=") must be set for a list to operate.
Security Keywords. These keywords control who can "see" the list (that is, whether or not the list appears in the List of Lists for a given user, based on the user's host site), and the level of security necessary for changes to the list itself. The "Exit=" keyword is also contained in this group.
Subscription Keywords. These control whether or not the list is open to general subscriptions, whether or not a mailing path confirmation is required, and what user options are set by default upon subscription.
Other Keywords. These control other aspects of list management that are not generally changed from their defaults, and which do not fit readily into the categories listed above.
2.5. Sending commands to LISTSERV
In the following sections, you will see numerous references to "sending commands to LISTSERV". All LISTSERV commands are sent to the server either by email or (in LISTSERV 1.8d and following) via the web administration interface described in Chapter 11. For mailed commands, 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. Let’s say for the sake of argument that the list you want to subscribe to (or are currently subscribed to) is running on a server called LISTSERV.MYCORP.COM. In order to send a command to that server, you would create a new message and address it to LISTSERV@LISTSERV.MYCORP.COM , and place the command(s) in the body (not the subject) of the message.
Depending on how you have security set up for your lists, some or all commands may require that you validate them with a personal LISTSERV password.
2.6. Defining Personal Passwords
The passwords recognized by LISTSERV for various operations (assuming that the NOPW parameter is not used with the "Validate=" keyword) are of two distinct types:
· Personal Passwords. LISTSERV can store a personal password in its signup files corresponding to your userid. This password not only can be used for list maintenance operations, but also protects your FUI (file update information) and AFD (automatic file distribution) subscriptions (if available on your server) and must be used to store your archive files, if any, on the server.
· List Passwords. Beginning with 1.8c, list passwords are obsolete (we are mentioning them here only because users upgrading from earlier versions will be aware of their existence). You should define and use a personal password for all protected operations.
To add a personal password, send mail to LISTSERV with the command
PW ADD newpassword
in the body of the message. LISTSERV will request a confirmation via the "OK" mechanism (see above) before it adds the password.
If you want to remove your password altogether, send the command
PW RESET
This command will also require confirmation.
And finally, if you simply want to change your personal password, send the command
PW CHANGE newpassword [PW=oldpassword]
If you do not include the old password in the command (e.g., you’ve forgotten it), LISTSERV will request an "OK" confirmation. Otherwise, it will act on the command without need for further confirmation (unless, of course, the oldpassword provided is incorrect).
Personal passwords may also be defined via the web administration interface at login time.
2.7. Retrieving the list configuration
If you are a LISTSERV maintainer, never attempt to hand-edit a production list file in place and restart the server. The GET and PUT operations (or the web administration interface/TCPGUI functions) are the only supported methods. Particularly under unix and Windows, LISTSERV will not always accept the hand-edited list file because some editors will insert control characters or CR-LF combinations that LISTSERV cannot parse. Under VM or VMS, it is always possible that hand-editing the list will introduce some sequence that will cause an operational error. L-Soft suggests that this method be used sparingly, if at all, and does not support it.
2.7.1. Who can edit the list configuration?
In LISTSERV 14.3 and earlier, any email address specified explicitly as a list owner (in the Owner= list keyword setting) may retrieve, edit, and store the list configuration (also known as the "list header").
In LISTSERV 14.4 and following, the behavior remains the same as before, unless the Configuration-Owner= list keyword is set. If Configuration-Owner= is set, then only those list owners specified in both Owner= and Configuration-Owner= may retrieve, edit, and store the list configuration. All other owners (that is, those not specified in Configuration-Owner=) may perform other list maintenance duties, such as adding/deleting subscribers or modifying their subscription options.
Of course, in all versions, the LISTSERV maintainer may edit all list configurations on the server regardless of the setting of Owner= or Configuration-Owner=.
2.7.2. Retrieving the list configuration by email
Once your list has been created by the LISTSERV maintainer, you can have a copy of the list sent to you for editing purposes. Simply issue the command
GET listname (HEADER
to LISTSERV. This will cause the server to mail you a copy of the list header only (without the subscriber list).
Note that you can retrieve the entire list, subscribers and all, by omitting the (HEADER switch. However, L-Soft strongly discourages getting the entire list at any time. This is because you do not need the entire list file if all you want to do is to change list header keyword settings. Also, since LISTSERV has well-documented commands available to manage user subscriptions, you should never attempt to hand-edit a list file in order to add or delete subscribers. Therefore there should normally be no reason to issue the GET listname command without the (HEADER switch.
The GET command automatically locks the list so that no changes can be made to the operating copy on the server until you do one of two things:
· Issue the UNLOCK listname command (if you decide no changes are needed)
· Send the list back to the server with the PUT command.
Leaving the list locked also prevents new subscribers from signing up. It is therefore not advisable to leave the list locked for long periods of time. This necessitates remembering to issue the UNLOCK command if you decide not to make any changes.
It is possible to request that LISTSERV not lock the list when it is sent to you. This is accomplished by adding the (NOLOCK switch to the GET command. You can use (NOLOCK and (HEADER together as in the following example:
GET listname (HEADER NOLOCK
(Note that the "(" switch character is used only once.)
CAUTION: It is not advisable to use the (NOLOCK switch in at least two cases:
· Don't use the (NOLOCK switch if you are not the sole owner of the list. This prevents conflicting GETs and PUTs by different list owners. For instance, Owner(A) GETs the list without locking it. Owner(B) then also GETs the list. The owners make differing changes to the list header. Owner(B) PUTs his changes back first. Owner(A) then PUTs his changes back, erasing every change Owner(B) made. If Owner(A) had not used the (NOLOCK switch, Owner(B) would not have been able to GET a copy of the list until Owner(A) either unlocked the list or PUT his copy back. (Owner(B) could also unlock the list himself, but it would be advisable to ask Owner(A) if he was finished editing the list header before doing so.)
· Don't use the (NOLOCK switch if you get the entire list rather than just the header. You will erase all subscriptions for users who subscribed between the time you GET the list and PUT the list back. It is easier to deal with questions as to why they got the "listname has been locked since time by list-owner" message than to explain why they got a subscription confirmation and now aren't getting list mail.
Another caution (1.8c and earlier): If you GET the header with the (HEADER switch, do not add new subscribers "on the fly" to the bottom of the header. If you do, your subsequent PUT will replace the entire list online with what you have sent, canceling the subscriptions of every user on the list (except for the ones you added to the header). Note carefully that LISTSERV will parse a signature file as if it were new subscribers; you should therefore turn off your signature file whenever you PUT your list header.
Under 1.8d and following the above problem has been alleviated by the new PUTALL command and a modification to PUT. A PUT command containing new subscribers added "on the fly" will result in only the header of the list being updated and a warning being generated that says if you really wanted to PUT the entire list, subscribers and all, that you should use the PUTALL command.
LISTSERV maintainers should note one further caution: It is considered extremely inadvisable to "hand-edit" subscriber lists, as columns at the far right of each subscriber's entry contain list control codes corresponding to the subscriber's personal option settings. The only case in which it might be appropriate to "hand-edit" would be to delete a user entirely, and then only if all attempts to delete the user via the DELETE command fail. For instance, X.400 or X.500 addresses can cause DELETE to fail because of their use of the "/" character. You can use wildcards to delete these subscriptions. You can also enclose the address in double quotes:
DELETE XYZ-L "/ADMD=ABC/PRMD=DEF/...../@X400.SOMEHOST.COM"
Finally, note that depending on your list configuration, you may have to use a password or respond to a confirmation request in order to GET your list header. The syntax for using a password with the GET command is
GET listname (options PW=password
For instance,
GET MYLIST-L (HEADER NOLOCK PW=MYPASSWORD
See the sections below regarding list passwords, personal passwords, and the "OK" command confirmation feature.
Once the LISTSERV maintainer has notified you that the basic list has been created, you can send a GET command to the server to make any modifications necessary, as explained above. For instance,
GET MYLIST (HEADER PW=MYPASSWD
might cause LISTSERV to send you the following list header file:
PUT MYLIST.LIST PW=XXXXXXXX
* The Descriptive Title of My List
*
* Owner= NATHAN@LSOFT.COM (Nathan Brindle)
* Notebook= Yes,E:\LISTS\MYLIST-L,Monthly,Public
* Errors-To= Owner Send= Public
* Subscription= Open,Confirm Ack= Yes Confidential= No
* Validate= No Notify= No Reply-to= List,Respect
* Review= Public Default-Options= NoFiles,NoRepro
*
* This list installed on 96/11/02, running under L-Soft's LISTSERV
* for Windows NT.
*
* Comment lines...
*
Figure 2.2. A sample list header file for a list called MYLIST.
You can now physically edit this file in a couple of different ways, depending on what tools you have on your workstation:
· Cut and paste the header from your mail program into an ASCII text editor such as vi, emacs, or Notepad. Edit the various keyword values and set the password in the PUT command appropriately. Finally, cut and paste from your editor into a new mail message addressed to LISTSERV and send the message.
· Cut and paste from your mail program into the body of a new mail message addressed to LISTSERV and do your editing in the mail program.
· If you use the 'mail' or 'mailx' programs under unix, you can save the header into a text file (for instance, named myheader.txt) and mail it back to LISTSERV with the command line syntax
mail listserv@myhost.com < myheader.txt
In Figure 2.3, we've made some changes to the list header and it is ready to be included in a mail message and sent back to LISTSERV. Note that the PUT command has been modified to include your personal password (see 2.6 for instructions on how to obtain a personal password).
PUT MYLIST.LIST PW=MYPASSWD
* The Descriptive Title of My List
*
* Owner= NATHAN@LSOFT.COM (Nathan Brindle)
* Owner= Quiet:,nathan@linus.dc.lsoft.com,ncbnet@linus.dc.lsoft.com
* Notebook= Yes,A,Monthly,Public Auto-Delete= Yes,Full-Auto
* Errors-To= ncbnet@linus.dc.lsoft.com Subscription= Open,Confirm
* Ack= Yes Confidential= No Notify= No
* Validate= Yes,Confirm
* Reply-to= List,Respect Review= Public Send= Public
* Default-Options= NoFiles,NoRepro
*
* This list installed on 96/11/02, running under L-Soft's LISTSERV
* for Windows NT.
*
* Comment lines...
*
Figure 2.3. The edited list header file ready to be sent back to the server.
If LISTSERV responds to your PUT operation with error messages, bear in mind that the most common problems are:
1. You sent the header back from an account which is not defined as a list owner
2. You used the wrong password or didn't specify a password in the PUT command
3. Your mail program indents paragraphs by default, such that each header line does not start in column 1 and LISTSERV does not recognize your message as a list header
4. You sent the header file back as an attachment rather than as plain text in the body of the message.
5. Your mail client wrapped the lines of the header so that LISTSERV received header lines that did not begin with "*" and attempted to treat them as subscriber addresses. In this case you can probably solve the problem by increasing the right margin setting in your mail client so that messages at least 80 columns wide do not get wrapped.
List owners should be persons who will undertake the responsibility of managing the list in all of its aspects. A list owner may be a moderator; a list owner may be called upon to determine why a user can’t unsubscribe from the list, or to handle delivery errors, or to fix other problems that may arise.
The primary list owner (the first owner defined) has special responsibilities as well. This owner is considered the Editor and the primary Moderator for lists that have Send= Editor but do not have Editor= or Moderator= defined. This owner receives all error messages when Errors-To= is set to "Owner". In short, the primary list owner is generally the person who is ultimately responsible for the workings of the list.
Secondary list owners fall into two categories: Quiet and non-Quiet.
· Non-Quiet list owners receive mail sent to the listname-request address, and will receive error messages if Errors-To= Owners.
· Quiet list owners will never receive delivery errors or other administrative mail from LISTSERV.
Here is a sample list header excerpt for a list with all three types of list owners defined:
* Owner= NATHAN@EXAMPLE.COM (Nathan Brindle)
* Owner= nathan@linus.example.com
* Owner= Quiet:
* Owner= ncbnet@linus.example.com,cheng@linus.example.com
Figure 2.4. Example: How to define list owners in the list header file.
Note that all list owners defined after the * Owner= Quiet: line will be quiet list owners.
You can define multiple owners on a single line by separating them with a comma. Note that if you put "Quiet:" on a line with list owner userids, you must place a comma after "Quiet:", e.g.
* Owner= Quiet:,ncbnet@linus.example.com,cheng@linus.example.com
There must always be at least one non-quiet list owner. Otherwise LISTSERV sends all error messages and other administrative mail to the LISTSERV maintainer by default.
2.10. Storing the list on the host machine
When you are ready to store your list back on the host, include the list file in a mail message to LISTSERV. Ensure that the PW=XXXXXXXX command is in the first line of the mail body. Change XXXXXXXX to the personal password you have previously defined with the PW ADD command (see section 2.6). Then send the message.
If LISTSERV has trouble processing the edited list file, it will return a discrepancy report to you with each error noted. If the errors are categorized as "warnings only," LISTSERV will go ahead and store the list. However, if any one error is categorized as a serious error, the list will not be stored and the old version will be retained.
Caution: If you are using a mailer such as Pine or Microsoft Mail that allows "attachments" to mail, do not "attach" the list file to your mail message. It must be in plain text with the PUT line at the top. LISTSERV will not translate encoded attachments.
LISTSERV always backs up the current list file before it stores a new copy. Should you discover that you have made a mistake (for instance, you have deleted all users by storing a header and adding users "on the fly"), it is possible to retrieve the previous copy of the list by issuing a GET listname (OLD command to the host server. You must then add the PUT listname LIST PW=XXXXXXXX command to the top of the file and store it. (In LISTSERV 1.8d and later you should use the PUTALL command for this purpose since you will be storing the entire list, not just the header.)
LISTSERV’s security options are wide ranging, from almost no protection (easiest to administer your list, but also most open to hacker attacks) to total protection requiring validation of each and every command sent to LISTSERV for your list. It is also possible to limit access to various aspects of your list, such as who can subscribe, who can review the list of subscribers, and who can access the list archives. You can hide your list from the LIST command, either at the global level or from all requests, including those from users on LISTSERV’s local machine, or from a definable range in between.
2.12.1. First line of defense: The VALIDATE= keyword
The Validate= keyword controls the level of command validation desired for your list. The default, Validate= No, requires password validation only for storing the list on the server. This is often sufficient for general needs. However, when a list is set this way, LISTSERV only compares the RFC822 "Sender:"/"From:" headers against the Owner= keyword(s) in the list header to determine whether or not the person ostensibly sending the commands has authority to do so. Otherwise at this level LISTSERV does not validate commands it receives for the list, under the assumption that the mail it receives is genuinely coming from a list owner. This level of validation does not protect the list from commands issued by hackers who have forged mail in the name of the list owner. If you run a list on a controversial topic or just don't feel comfortable without at least some security, Validate= No is probably not for you.
The next level is Validate= Yes. At this level, LISTSERV requires a password for all of its "protected" commands. This password is the sender’s personal LISTSERV password as defined by the PW ADD command. The commands protected by this level are those that affect subscriptions or the operation of the list, e.g., DELETE or ADD. Users will also have to validate most commands that affect their subscriptions, but generally can do so using the "OK" mechanism rather than defining a personal password. Note that some user commands will be forwarded to the list owner for validation rather than accepting password validation from the user.
The next level is Validate= Yes,Confirm. At this level, LISTSERV will require validation with the "OK" mechanism (see below) by default, but will still accept passwords where appropriate. While the less-secure passwords are still accepted, this is considered a good compromise between list security and list owner and user convenience.
The next level is Validate= YES,Confirm,NoPW. At this level, LISTSERV will no longer accept passwords as validation for protected commands. The logic is that because of the way the "OK" mechanism is implemented, passwords are not as safe as "magic cookies". This is the recommended setting for lists that must be kept secure.
Two other levels are Validate= All,Confirm and Validate= All,Confirm,NoPW. These levels require "OK" validation for all commands that cause a change in state except for the PUT command. If NoPW is not specified, passwords are accepted where appropriate. With these levels, commands that do not cause a change in state (e.g., QUERY) do not require validation.
Note that LISTSERV requests coming from the local system via CP MSG or CP SMSG on VM systems or via LCMD on NT, VMS or Unix systems never require validation, as they cannot be forged.
Lists which are set to either Validate= Yes,Confirm,NoPW or Validate= All,Confirm,NoPW may not be managed via the web administration interface, which is password-driven.
See Appendix B for more information on the Validate= keyword.
2.12.2. Controlling subscription requests
You can control subscription requests by use of the Subscription= keyword. By default, this keyword is set to Subscription= By_Owner, meaning that all subscription requests will be forwarded to the list owner for disposition. You can also refuse all subscription requests by setting Subscription= Closed.
To code a list for open subscriptions without list owner intervention, you set Subscription= Open. If you would like to add protection against forged subscription requests or bad return mailing paths, code Subscription= Open,Confirm. The latter will cause a subscription confirmation request to be sent to the prospective subscriber, which he or she must respond to using the "OK" confirmation mechanism.
In order to restrict subscriptions to persons in a specific service area, see the next section.
2.12.3. Controlling the service area of your list
The Service= keyword is not available in LISTSERV Lite.
It may be desirable to restrict access to your list to people in a small area. For instance, you probably would not want a list for students in a class section at a university to be advertised or accessible by people all over the world. However, without setting certain keywords appropriately, such a list will be visible to a LIST GLOBAL command.
If you wish to simply hide your list from a LIST command, but still allow people to subscribe to it if they know it is there, use the keyword Confidential= Yes. Note that users subscribed to the list as well as the list owner(s) will be able to see the list if they issue a LIST command.
If you wish to hide your list from and refuse subscription requests from users outside the local area, you define two keywords:
* Service= bitnode1,bitnode2,some.host.edu
* Confidential= SERVICE
Service= can also be set to Service= Local, meaning it will use either LISTSERV’s global definition of which machines are Local, or the machines defined by the list keyword Local=. If you wish to set Service to Local, you should check with your LISTSERV maintainer to find out which nodes are considered local. If the global definition is not suitable, you can override it by defining the Local= keyword:
* Local= bitnode1,bitnode2,some.host.edu,another.host.com
* Service= Local
* Confidential= Service
If there are many subdomains within your primary domain, you may wish to use the wildcard when defining the Local= or Service=keywords. For instance:
* Service= HOST.COM,*.HOST.COM
defines the service area as "HOST.COM and all subdomains ending in .HOST.COM".
2.12.4. Controlling who may review the list of subscribers
For whatever reason, you may wish to restrict the ability to review the subscriber list either to subscribers or to list owners. This is done by setting the Review= keyword appropriately.
To restrict reviews of the list to subscribers only, set Review= Private. This is the default starting with LISTSERV 1.8c.
To restrict reviews of the list to list owners only, set Review= Owners.
To allow anyone, including non-subscribers, to review the list, set Review= Public. Prior to LISTSERV 1.8c this was the default; it is no longer recommended to use this value unless your LISTSERV server is operating on an intranet.
You can also restrict reviews to users within the list’s service area by setting Review= Service , and defining the Service= keyword appropriately (see the preceding section).
2.12.5. Controlling who may access the notebook files
Restricting access to the list’s notebook archive files is similar to controlling who may review the list. It is accomplished by setting the fourth parameter of the Notebook= keyword to an appropriate value. For instance,
* Notebook= Yes,A,Monthly,Public
defines a monthly notebook on LISTSERV’s A disk that is accessible by anyone. Change Public to Private if you wish only subscribers to be able to access the notebooks. The same access-levels are available for this keyword as for Review=. (See Appendix B for a discussion of access-levels.)
Note: The location (second) parameter of the Notebook= keyword may be changed only by the LISTSERV maintainer.
If enabled, notebook archives are private by default.
2.12.6. Controlling who may post mail to the list
The Send= list header keyword is the basic control for who may post mail to the list. If the list allows non-subscribers to post, set Send= Public.
For a list that does not allow non-subscribers to post, set Send= Private. (This is the default.)
If you want a further level of security for Send= Private, you may set Send= Private,Confirm , which requires each poster to confirm (via the "OK" mechanism) that the posting actually came from them. This can help in cases where a hacker might be trying to "spoof" mail from an otherwise legitimate subscriber. It is not recommended to set this in normal circumstances.
For a list where all posts should be forwarded to a moderator/editor, there are three settings:
· Send= Editor forwards all postings to the list editor (see the Editor= and Moderator= keywords). This setting allows the editor to make changes before forwarding the message back to the list. Note that your mail program must be capable of inserting "Resent-" header lines in your forwarded mail—if it is not capable of this, all such posts forwarded to the list will appear to be coming from the editor. Check with your system administrator if you are not sure whether or not your mail program inserts the "Resent-" headers.
· Send= Editor,Hold forwards a copy of the posting to the editor but differs from Send= Editor in that LISTSERV holds the posting for a period of time (usually 7 days) until the editor confirms the message with the "OK" mechanism (see below). Unconfirmed messages simply expire and are flushed by LISTSERV, so there is no need to formally disapprove a posting. This method of message confirmation is well-suited to lists where it is not often necessary to modify the text of a posting, and also is an excellent workaround if the editor’s mail program does not generate "Resent-" headers in forwarded mail.
Below is a sample of the editor-header for a list set to Send= Editor,Hold:
Date: Tue, 4 Aug 1998 10:47:21 -0500
From: "L-Soft list server at PEACH.EASE.LSOFT.COM (1.8d)"
<LISTSERV@PEACH.EASE.LSOFT.COM>
Subject: B5-L: approval required (9723A0DD)
To: Joe ListOwner <joe@PRUNE.EXAMPLE.COM>
This message was originally submitted by jack@UNIX.FOO.COM to the B5-L list at
PEACH.EASE.LSOFT.COM. You can approve it using the "OK" mechanism, ignore it,
or repost an edited copy. The message will expire automatically and you do not
need to do anything if you just want to discard it. Please refer to the list
owner's guide if you are not familiar with the "OK" mechanism; these
instructions are being kept purposefully short for your convenience in
processing large numbers of messages.
----------------- Original message (ID=9723A0DD) (13 lines) -------------------
Figure 2.5. The editor-header for a list set to Send= Editor,Hold
· Send= Editor,Hold,Confirm is identical to Send= Editor,Hold except that postings coming directly from an editor must be confirmed (with the "OK" mechanism) by the editor who sent the message. This is the recommended setting for any moderated list or announce-only list as it protects the list from hackers who might try to forge mail from a legitimate editor address.
A fourth method (called "self-moderation") exists for lists where subscribers should be allowed to post freely, but non-subscriber posts should always be sent to an editor for approval. To enable self-moderation, set
* Send= Editor
* Editor= userid@host,(listname)
Ensure that "listname" is in parenthesis. Note that self-moderation will catch all posts from non-subscribers—including posts from subscribers who are posting from a different address. For instance, if the subscriber originally signed up as joe@foo.com but is posting from joe@unix1.foo.com, LISTSERV will treat his mail as non-subscriber mail. Self-moderation may require some slight changes in individual user subscriptions in order for it to work seamlessly.
2.12.7. The "OK" confirmation mechanism
Depending on the setting of the Validate= list header keyword, certain LISTSERV commands have always required a password for execution. However, with a recognition that mail can be forged ("spoofed") by just about anyone on the Internet today, L-Soft introduced a "magic cookie" method of command validation that is considered much more secure than passwords.
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 owner’s user id, the command confirmation request will always be sent to the list owner’s 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.
A typical command confirmation request looks like this:
Date: Wed, 5 Aug 1998 09:50:06 -0400
From: "L-Soft list server at LISTSERV.EXAMPLE.COM (1.8d)"
<LISTSERV@LISTSERV.EXAMPLE.COM>
Subject: Command confirmation request (5C019D91)
To: joe_user@EXAMPLE.COM
Your command:
PW REP XXXXXXXX
requires confirmation. To confirm the execution of your command, simply
point your browser to the following URL:
http://listserv.example.com/scripts/wa.exe?OK=5C019D91
Alternatively, if you have no WWW access, you can reply to the present
message and type "ok" (without the quotes) as the text of your message.
Just the word "ok" - do not retype the command. This procedure will work
with any mail program that fully conforms to the Internet standards for
electronic mail. If you receive an error message, try sending a new
message to LISTSERV@LISTSERV.EXAMPLE.COM (without using the "reply"
function - this is very important) and type "ok 5C019D91" as the text of
your message.
Finally, your command will be cancelled automatically if LISTSERV does
not receive your confirmation within 48h. After that time, you must start
over and resend the command to get a new confirmation code. If you change
your mind and decide that you do NOT want to confirm the command, simply
discard the present message and let the request expire on its own.
Figure 2.6. A typical command confirmation request.
The general method of replying to a command confirmation request is as follows:
· Under 1.8d and following, the suggested method is to use the web browser confirmation method outlined in the confirmation request.
If you prefer, or if you are using 1.8c or 1.8b, you can use the old method of responding by mail:
· 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 this does not work, it is possible that the Subject: line was corrupted in transit and you may ne ed to try the following:
· 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.
It is also possible to confirm multiple command confirmation requests with a single message (for instance, if you have Send= Editor,Hold and have a number of requests to be responded to). This eliminates multiple "Message approved" mails from LISTSERV. However, make sure that you send the confirmations in a new mail message rather than replying to one of them.
Prior to LISTSERV 1.8e, when using "OK" cookies for moderation, note that confirmation requests for messages containing MIME attachments will show the "raw" attachment. This is because LISTSERV does not generate MIME headers for confirmation request messages. When the "OK" is sent, MIME attachments will be processed correctly.
Prior to LISTSERV 1.8d, the "OK" confirmations must come from the userid that originated the command, i.e., you cannot send a command from one account and then approve it from another.
From LISTSERV 1.8d the "OK" can be sent from any address, which helps when the address field of your mail gets changed somewhere along the line. For instance if you are logged into the web administration interface as joe@example.com and issue a command that requires mail confirmation, LISTSERV will send the request to joe@example.com (as expected). If your mail system expands joe@example.com to Joe_Doakes@mail.example.com, responding to the request under 1.8c would result in a failure because the cookie and the address in your From: line wouldn't correspond to what LISTSERV has on file. Under 1.8d and later the "OK" will succeed and Joe_Doakes@mail.example.com will get a message that says
> ok
Confirming:
> QUIET DELETE * jane@example.com
[reply sent to joe@EXAMPLE.COM]
while as a protection against "spoofed" commands the actual command response will be sent to joe@example.com like this:
jane@EXAMPLE.COM has been removed from the TEST list. No notification has
been sent.
Global deletion process complete, one entry removed.
Three further enhancements were added to the "OK" confirmation mechanism in 1.8d:
· An "OK" without an argument (confirmation number) flushes the job stream, so any text following an "OK" on a line by itself will not be seen by the LISTSERV command processor.
· Bracketed "OK" functionality. This feature allows you to send multiple commands for which LISTSERV will request only a single "OK" (where normally you would expect to have to "OK" each individual command). The syntax is as follows:
OK BEGIN
command1
command2
[more commands, one per line]
commandn
OK END
· A command confirmation ("OK") may now be sent by clicking on a web URL provided in the command confirmation request (mailed "OK"s are still perfectly acceptable, of course).
Documented restriction: In a "bracketed OK" the aggregate length of the data stream (ie, the total number of characters in the command lines falling between OK BEGIN and OK END) MUST be less than 32K characters. In practice you should use bracketed OKs for limited numbers of commands only, say no more than 10-12 at a time. In particular, if you have many ADD or DELETE commands to send, it is far more efficient (and strongly preferred) to use the bulk ADD and bulk DELETE syntaxes described in chapters 4.4 and 4.5, above.
2.12.8 Explicitly cancelling "OK" cookies (1.8e)
In LISTSERV 1.8e and following, it is possible to explicitly cancel an OK confirmation cookie if so desired. The command is simply
OK CANCEL xxxxxxxx
(for instance, "OK CANCEL 8F2E8F4B"), and if the cookie is valid, LISTSERV will respond "Confirmation code 8F2E8F4B cancelled." If the cookie is not valid (eg has expired, has already been cancelled, or is simply incorrect), LISTSERV will send its standard message telling you in part that "The confirmation code 8F2E8F4B does not correspond to any pending command."
2.12.9. Restricting subscriber privileges
Another security issue involves protecting the list from people who refuse to play by the rules. LISTSERV includes several different levels of privilege restriction for these users, some of which are available for use by list owners without the intervention of the LISTSERV maintainer.
1. The REVIEW personal option setting. By issuing a SET listname REVIEW FOR userid@host command to LISTSERV, you can moderate postings at the individual subscriber level. Postings from subscribers set to REVIEW are passed on to the Editor(s) or Moderator(s) of the list, or, if neither of these keywords are defined for your list, the postings are passed on to the primary list owner. At this point, the person who receives the postings can determine whether or not to approve them. Note that the subscriber always receives notification that his or her posting has been forwarded to a moderator for approval. This is to avoid the impression that the subscriber’s posting has been lost before reaching LISTSERV.
2. The NOPOST personal option setting. By issuing a SET listname NOPOST FOR userid@host command to LISTSERV, you can prevent a subscriber from posting to the list entirely. LISTSERV will reject postings from these subscribers and will not pass them on to a moderator. As with the REVIEW setting, note that the subscriber always receives notification that his or her posting has been rejected.
3. The FILTER= list header keyword. You can filter individual users from subscribing and/or posting to your list by adding them to the Filter= list header keyword. For instance, if you have a list called MACTALK-L and you want to discourage redistribution lists from using the same name as your list, you can add
* Filter= Also,MACTALK-L@*
See Appendix B for more information on the Filter= syntax.
2.12.10. Restricting the number of postings per user to the list per day
Beginning with 1.8c, you can control the maximum number of postings per day per subscriber on a list-by-list basis by setting the new (optional) second parameter of the "Daily-Threshold=" list header keyword. The default is to have no such daily limit per user.
If set, when the per-subscriber threshold is reached, the subscriber is told that his message cannot be processed because he has reached the limit for today, and that he should repost his message at a later time. The counter for this limit resets to zero at midnight for all lists.
This limit is waived for the list owner(s) and any list editors/moderators.
If you want to set this limit, note that an overall daily threshold must be set for the list in the first parameter of the keyword. If no "Daily-Threshold=" keyword is already present in your list header, the default is "Daily-Threshold= 50". Thus, to leave the default value in force and to add a daily limit of 5 postings per day per user, you would code:
* Daily-Threshold= 50,5
For more information see Appendix B.
2.13. How to set up lists for specific purposes
2.13.1. Public discussion lists
Public discussion lists have always been the "classic" type of LISTSERV mailing list. Such lists are available to discuss just about everything imaginable. In the last few years it has become desirable to secure mailing lists against random spamming and mailbombing, but no discussion of different types of lists would really be complete without talking about this kind of list.
Typically, a public discussion list is wide-open (although some things, like the ability to review the subscribership, may be restricted). Anyone can subscribe (with a confirmation to verify the mailing path), anyone can post, anyone can read the messages in the archives, and security is set fairly low. Very large lists (hundreds or even thousands of users with hundreds of postings every week) may likely be set up this way as it is a "low-maintenance" way to run a list (and most spams tend to be caught by LISTSERV's anti-spamming filters anyway). For instance you might have
* My public discussion list (MYLIST-L)
* Subscription= Open,Confirm
* Ack= Yes
* Confidential= No
* Validate= No
* Reply-to= List,Respect
* Review= Owners Send= Public Errors-To= Owner
* Owner= joe@example.com
* Notebook= Yes,E:\LISTS\MYLIST-L,Weekly,Public
For more security, you might want to code
* Validate= Yes,Confirm
and if you want to cut down on the amount of "me-too"ism on the list, you could set
* Reply-to= Sender,Respect
to force the default Reply-To: header to point back to the original poster instead of to the list. Note that the ",Respect" option means that if a user sends mail to the list that contains a "Reply-To:" header pointing back to the list (unlikely that this may be), LISTSERV will "respect" that header and use it. If you absolutely do not want this to be possible, you should code
* Reply-to= Sender,Ignore
instead.
There is one major caveat with regard to the use of the Reply-To= list header keyword. You should note carefully that not all subscriber-side mail clients either recognize or properly handle an RFC822 "Reply-To:" header. This may result in users posting replies to your list even though LISTSERV put the correct Reply-To: header on the mail. There is absolutely nothing that L-Soft can do to correct this problem since it exists on the subscriber's end in non-compliant mail software that L-Soft does not and cannot support.
2.13.2. Private discussion lists
Private discussion lists are similar to public discussion lists, but with varying restrictions on who may subscribe, who may post and who may view the archives. Such lists are relatively safe from random spamming since typically only a subscriber can post (but note that a spammer spoofing mail from a subscriber's address will probably be successful unless first caught by the anti-spamming filters). For instance:
* My private discussion list (PRIVATE-L)
* Subscription= By_Owner
* Ack= Yes
* Confidential= Service
* Validate= No
* Reply-to= List,Respect
* Review= Owners
* Send= Private
* Errors-To= Owner
* Owner= joe@example.com
* Notebook= Yes,E:\LISTS\PRIVATE-L,Weekly,Public
is a low-security private discussion list where subscriptions requests are passed on to the list owner(s) for review, only subscribers may post, and only subscribers may view the list archives. Here again, for more security you might want to set "Validate= Yes,Confirm", and of course you can have replies go to the original poster rather than to the list with "Reply-To= Sender,Respect" (with the same caveats as noted above in 2.13.1).
An edited list is one which requires a human editor to approve messages sent to the list. Some list software and most USENET newsgroups refer to this as "moderation", but to avoid confusion between two types of moderated LISTSERV lists, the present example will be referred to as an "edited" list.
Examples of edited lists range from refereed electronic journals to lists where the list owner simply wishes to exercise control over which postings are allowed to go to the list.
To set up a basic edited list, simply add
* Send= Editor
* Editor= someuser@somehost.com
to the basic list header. Note that the primary Editor= specification (that is, the first editor defined by an Editor= keyword for the list) must be a human person who will be able to act on postings sent to him or her for approval. You may not use an access-level specification (such as "Owner") when defining the primary editor for a list.
Please note that L-Soft recommends setting "Send= Editor,Confirm" so as to add a level of security against malicious users forging mail from an "Editor=" address to get around your moderation settings, or against badly-configured "vacation" programs that simply reflect the message back to the list in a manner that makes it appear that the mail is coming from the editor’s address. The "Confirm" option causes LISTSERV to request an "OK" confirmation from an editor when it receives mail claiming to be from that editor.
You can define multiple editors, but only the first editor will receive postings for approval. Anyone defined as an editor may post directly to the list without further intervention. Multiple editors can be defined on separate Editor= lines or can be grouped several on a line, e.g.,
* Editor= someuser@somehost.com,anotheruser@anotherhost.com
* Editor= yetanotheruser@his.host.com
To approve postings with the above configuration, the editor simply forwards (or "resends", or "bounces"--the terminology is unclear between various mail programs) the posting back to the list address after making any desired changes to the content. This should be done with a mail program that supports "Resent-" fields; if "Resent-" fields are not found by LISTSERV in the headers of the approved posting, the posting will appear as coming from the editor's address rather than from the original poster. If your mail program does not support "Resent-" fields, you should use the "Send= Editor,Hold" option and approve messages with the "OK" mechanism described below.
If you do not need to physically edit the content of your users' posts (for instance, to remove anything considered "off-topic" or to remove included mail headers and so forth), you can code
* Send= Editor,Hold
The "Hold" parameter causes LISTSERV to send you a copy of the posting along with a "command confirmation request". To approve the posting, you simply reply to the confirmation request with "ok".
For security purposes, you can code
* Send= Editor,Confirm
which will cause LISTSERV to request a command confirmation ("ok") from the editor sending the approved posting back to the list. This makes it impossible for an outside user to "spoof" mail from an Editor address.
Naturally, you can also code
* Send= Editor,Hold,Confirm
Finally, please note that the NOPOST subscriber option will take precedence over Editor=, if set for someone defined as an editor. This means that if you have "Default-Options= NOPOST" for your list and you add an editor as a subscriber, you will have to manually reset the editor to POST (with "SET listname POST FOR userid@host") before things will work properly. You will know that this is necessary if your editor can successfully approve postings but is then told that he or she cannot post to the list.
Note: The Moderator= keyword is disabled in LISTSERV Lite.
A moderated list is similar to an edited list, but for LISTSERV's purposes it refers to a list that uses the Moderator= list header keyword to "load-share" posting approvals among several editors. It is set up similarly to an edited list, as follows:
* Send= Editor,Confirm
* Editor= someuser@somehost.com
* Moderator= someuser@somehost.com,anotheruser@anotherhost.com
* Moderator= yetanotheruser@his.host.com
This list will "load-share" the approval process between the three moderators, who will each receive one-third of the postings for approval. Note that a primary editor should still be defined.
If it is desired to have one editor handle more than a single share of the approvals, you simply define the editor more than once in Moderator=. For instance,
* Send= Editor,Confirm
* Editor= someuser@somehost.com
* Moderator= someuser@somehost.com,anotheruser@anotherhost.com
* Moderator= someuser@somehost.com,yetanotheruser@his.host.com
would cause every other posting to be forwarded to someuser@somehost.com for approval.
Beginning with 1.8c, if the parameter "All" is coded at the beginning of the list of moderators, LISTSERV will send copies of all postings to all moderators, any of whom may approve the message. An example of this would be
* Moderator= All,kent@net.police.net,joe@bar.edu
Please note that something like
* Moderator= kent@net.police.net,All,joe@bar.edu,alex@reges.com
is not valid. "All" must appear at the beginning of the list of moderators.
Assuming "Send= Editor, Hold", once a message is approved by one of the moderators, any other moderator attempting to approve the same message will be told that the message cannot be found and has probably expired (since the cookie for that message will be gone).
If the message body is edited in any way before it is approved (i.e., by forwarding an edited copy back to the list), and more than one moderator is involved, duplicates are possible. Thus it is important that the moderators of any list set up this way pay close attention to whether or not the posting has already been approved by another moderator. Note carefully that this means if the "All" parameter is used in "Moderator=" with "Send= Editor" (that is, without the "Hold" parameter), again a separate synchronization method will have to be used to prevent duplicates, as two moderators are unlikely to make exactly the same edits to the message. Even if LISTSERV were able to identify the two submissions as being the same message, it would not know which to choose over the other.
"Semi-moderation" was developed some years ago after a great debate on whether or not an "urgent" message should be allowed to be posted to an edited list without having to go through the approval process. Although this option is still available, it can be misused by anyone who knows about it, and is therefore not generally recommended for use. However, should this feature be deemed necessary, it is activated by setting
* Send= Editor,Semi-Moderated
Then anyone needing to send an "urgent" message to the list simply types "Urgent:" in the subject line of their mail, followed by the subject of the message. Messages that do not have the "Urgent:" subject are forwarded to the list editor for approval as usual.
So-called "self-moderated" lists were invented in 1993 or 1994 when the current epidemic of spamming was beginning to get cranked up and before the "spam filter" was developed by L-Soft. With the spam filter in operation, self-moderation is not as much of an issue anymore, but some lists still run this way.
Self-moderation takes advantage of the ability to make an access-level a secondary list editor, and is implemented as follows:
* Send= Editor,Confirm
* Editor= someone@someplace.com,(listname)
(The "Hold" and "Confirm" parameters for "Send=" may naturally be used if required. L-Soft recommends that "Confirm" be used by default.)
Usually, one of the list owners is the primary editor (here "someone@someplace.com") and the specification of (listname) makes all of the subscribers of the listname list editors, and thus eligible to send messages directly to the list without editor intervention. Postings from non-subscribers (e.g., spammers) are deflected to the primary owner for his or her disposition.
There is one caveat to this kind of list. If a user subscribes to the list, and later his mail address changes (for instance, the hostname changes slightly but mail sent to the old address is automatically forwarded to the new address), any postings from him to the list from the new address will be forwarded to the editor because the new address is not subscribed to the list. Thus there is a certain amount of list-owner overhead on this kind of list in keeping track of users whose addresses have changed and modifying the subscriber list to reflect those changes.
2.13.7. Private edited/moderated lists
This type of edited or moderated list allows subscribed users to post with editor or moderator intervention, but rejects postings received from non-subscribers with a note to the poster stating that they are not allowed to post.
Using the same header you would create for an private discussion list (see 2.13.2, above), simply add the following line to the header:
* Default-Options= REVIEW
You should also add Editor= and (optionally) Moderator= keyword settings to the list. At least one editor must be defined to handle the message approval chores, otherwise the first listed list owner will receive the messages for approval.
Note the following carefully:
· For brand-new lists or existing lists which have no subscribers, all subscribers added to the list after this option is set will be set to REVIEW, and nothing further needs to be done.
·
For existing lists with existing subscribers, you will
need to set the existing subscribers to the REVIEW option manually, ie, with
the command
QUIET SET listname REVIEW FOR *@*
New subscribers who sign up or are added after you add the Default-0ptions= keyword setting will automatically be set to the REVIEW option.
Finally, note that the list editor will also be set to REVIEW if he is subscribed to the list under this scenario. This can be important if the list editor wants to approve even his own postings (for instance, to help avoid someone spoofing mail to the list from his address). If the list editor does not require this "suspenders and belt" level of security, he can simply set himself to NOREVIEW.
Since LISTSERV Lite does not support list-level mail templates, this functionality is effectively not available in LISTSERV Lite.
An "auto-responder" is a type of list that simply responds with a set message whenever it receives mail from someone. This kind of list can be useful for things like service messages or upgrade availability, or even to simply send back a standardized message to a user who has sent mail to a "support" address.
A simple auto-responder header might look like this:
* Auto-responder for service messages
* Owner= someone@someplace.com
* Send= Public Notebook= No Subscription= Closed
In other words, it can be very simple, since you probably don't want notebook archives for this kind of auto-responder, you don't want people to subscribe to the list as it isn't really a mailing list, and so forth. To make the auto-response message for this list, you'd then create a listname.MAILTPL file (see chapter 10 for details) that includes a POSTACK1 template, like the following:
>>> POSTACK1 Service Message for &MYNAMES
&MYNAMES will be down Sunday from 0200 EST until 0500 EST for backups and upgrades. For more information contact LSTMAINT@&MYHOST.
This particular template would inform the user that LISTSERV would be down (&MYNAMES translates to LISTSERV@NODE where NODE is the value of NODE= in the system configuration file) and to send questions to LSTMAINT@ the local host. In order to change the service message, it would be necessary only to change the POSTACK1 template.
An "announce-only" list would be used to distribute a newsletter or other timely information where responses to the list are neither expected nor desired. A typical announce-only list header might look like this:
* The FOO Product Announcment List
*
* Owner= foo@myhost.com
* Owner= Quiet:
* Owner= anotheruser@myhost.com,yetanotheruser@myhost.com
* Editor= foo@myhost.com
* Editor= anotheruser@myhost.com,yetanotheruser@myhost.com
* Notebook= No
* Errors-To= Owner
* Subscription= Open,Confirm
* Validate= No
* Review= Owners
* Send= Editor,Confirm
* Reply-To= foo@myhost.com,Ignore
* Sender= None
This list is set up so that generally any response to postings will go back to foo@myhost.com, which might be a special account set up specifically to handle such things, or a mail alias pointing to another account. The newsletter can be posted by foo, or anotheruser, or yetanotheruser, all of whom are editors, but the likelihood is that it would be posted from the foo userid so that the From: line would read "From: foo@myhost.com".
2.13.10. Restricted subscription lists with automatically-generated questionnaire
Since LISTSERV Lite does not support list-level mail templates, this functionality is effectively not available in LISTSERV Lite.
Sometimes it is desired to send out a little questionnaire before approving a subscription to a list with a very narrowly-defined topic or to lists created for members of specific organizations. By setting "Subscription= By_Owner", you can of course force all potential subscriptions to require list owner approval. In the "old days", if you wanted more information before you approved the subscription request, you had to manually send a questionnaire out to the user and wait for him or her to return it to you.
By setting "Subscription= By_Owner" and adding two simple template forms to your listname.MAILTPL (as explained in chapter 9), you can now have LISTSERV send your questionnaire out automatically, as soon as the subscription request is received.
The first template form you need to add to listname.MAILTPL is called SUB_OWNER, and in this case it would typically look like this:
>>> SUB_OWNER &LISTNAME: &WHOM requested to join
.TO &WHOM
A copy of the &LISTNAME membership questionnaire has been sent
to you. Please read it carefully and follow the instructions
to complete it and return it to the list owners.
The .TO &WHOM directive is required so that the message is sent to the subscriber rather than to the list owner. If you want the non-quiet list owners to receive a copy of this message (which is admittedly unlikely), you can simply add CC: &OWNERS to the end of the .TO line, e.g.,
.TO &WHOM CC: &OWNERS
Or, if you want to cc: a specific user such as joe@unix1.example.com, use
.TO &WHOM CC: joe@unix1.example.com
Note that you cannot format the SUB_OWNER template; it all comes out as one long paragraph without formatting no matter what you do, because it is a "linear" template. But you should modify it from the default to let people know that they will receive a questionnaire to be filled out and returned.
The second template form you need to add to listname.MAILTPL is called ADDREQ1 and it can be as simple or as detailed as you want. All of the available template formatting commands can be used in ADDREQ1. For instance:
>>> ADDREQ1 &LISTNAME Membership Survey
.RE OWNERS
.TO &WHOM
.CE &LISTNAME Membership Survey
NOTE: Please make sure when you send this back that it goes to
the address &LISTNAME-Request@&MYHOST. Thanks.
This is a standard questionnaire required for all prospective
subscribers to &LISTNAME. Blah blah blah...
In this case you want the message to go to the subscriber, with a Reply-To: header pointing back to the (non-quiet) list owners. The first line indicating the return address is added for those users with mail clients that don't recognize Reply-To: headers.
You can also put a pre-formatted ADD job into the questionnaire to simplify your job when the questionnaire comes back. For instance,
.fo off
----------------------------------------------------------------
For List Owner's Use Only -- Be sure to include with your Reply
----------------------------------------------------------------
// JOB
ADD &LISTNAME &WHOM &USERNAME
// EOJ
----------------------------------------------------------------
.fo on
For more detailed information on mail templates, see chapter 9.
This functionality is not available in LISTSERV Lite.
Please consult your LISTSERV maintainer before peering lists.
Occasionally the need to split a very large list may arise. This was more common when LISTSERV ran only on BITNET, whereas the TCP/IP version of LISTSERV is not limited by BITNET constraints. However, because of the fact that subscribers may be scattered all over the world, in rare cases it can make sense to split (or "peer") a list and share the mail load among two or more LISTSERV servers. Peering also makes it possible to have list archives located in more than one place; for example, a list might be peered between a European host and a North American host, making it possible for subscribers on each continent to retrieve archives from the nearer host.
Although there is no problem about peering to another L-Soft LISTSERV list, linking to a non-L-Soft mailing list manager is not supported and can and will cause serious problems (including mailing loops) for which L-Soft international, Inc. could not be held responsible.
After the link operation has been completed, it is recommended that you define "Peers=" keywords on lists you just linked. For lists running on LISTSERV for VM, this makes it possible to EXPLODE them for better network efficiency. (Because peering is not widely used today, it is unlikely that the EXPLODE command will be ported to other platforms.)
Note also that the peer lists MUST have the same list password (PW= list header keyword setting) or messages approved on one peer will not be accepted by the other peer and an error message will be generated, i.e.,
The approval request code received together with your posting for the MYLIST-L
list is incorrect. For a peered list, this may be a normal condition. The
approval protocol is not guaranteed to work among peer chains with pre-1.8b
servers, and will also fail if the peers have a different password. For a
non-peered list, the only likely explanation is a failure in the mail system or
a recent change in mail system version or configuration. At any rate, please
resubmit your message and go through the approval procedure a second time, and
contact the LISTSERV administrator if the problem persists.
------------------------ Rejected message (73 lines) --------------------------
This means that under LISTSERV 1.8c and later you must explicitly set the PW= list header keyword for each peer and not use the password LISTSERV generates automatically at list creation time. This is the only situation in which the PW= keyword must explicitly be set to a specific value.
Moving users from one (peer) server to another:
You should be aware of the fact that a MOVE operation is not just an ADD to the new server and a DELete to the current one. This would effectively transfer the person from the old server to the new one but his distribution options would be lost in the process. Besides, you should make sure that the user does not lose any mail in the process. The proper course of action to be taken when people are moved from one list to the other is the following:
1. Send mail to the list telling people that a new peer server is being linked to the list, and that some subscribers will be moved to it.
2a. If the prerequisites for using the MOVE command are met, you should use either individual MOVE commands (in the case that there are very few users to move) or a batch-MOVE command with associated DDname (see the LISTJOB MEMO guide for more information on commands-jobs) to move the users. You may want to use the QUIET option to suppress notification if there are a lot of users to move.
Warning: the MOVE command should not be used to move peer list servers. See the MOVE command description for more details.
If you cannot use the MOVE command, you should try one of the following two methods:
2b. For each user to be moved, issue the following commands in the following order:
Query listname FOR userid@host (old server), write down the options.
QUIET ADD listname userid@host full_name
QUIET SET listname options FOR userid@host
Wait until you get confirmation for the two previous commands
QUIET DELete listname userid@host (old server)
2c. If there are a lot of users to move, the following method is preferred:
GET listname (old server)
GET listname (new server)
If you are using VM XEDIT: Receive both files and use the XEDIT "PUT" and "GET" commands to move users from one list to the other. You must preserve the contents of columns 81-100 across the move.
If you are using another text editor: Make sure that the editor you are using does not "imbed" control codes such as line breaks, tabs or word-wrapping characters into the text when you edit it. Use the cut and paste controls to copy lines in their entirety. You must preserve the contents of columns 81-100 across the move. Imbedded control codes and/or word wrap will generate errors when the list is stored back on the server.
Store the two lists back on their respective servers.
Special commands for peered lists only
ADDHere listname userid@host <full_name> <PW=list_password>
The ADDHERE command is strictly identical to ADD, with the exception that the placement of the user is not checked against the list of peer servers, i.e. the specified user is added to the local list without any further verification. (By comparison, the ADD command causes LISTSERV to check automatically to see if there is no better-suited peer list for the specified user.)
EXPLODE listname <F=fformat> [VM only]
The EXPLODE command provides a means whereby a list can be automatically analyzed by LISTSERV to optimize the placement of its recipients over the various peer servers hosting the list. It requires a "Peers=" keyword to be defined in the list header (see Appendix B). Non-BITNET userids will be exploded according to the network address of the corresponding gateway (as per the SERVICE NAMES file), or ignored if the gateway could not be identified. LISTSERV will create a commands-job file containing the necessary MOVE command to transfer all the users which were found to be (possibly) mis-allocated to the peer server which is nearest to them. This file will then be sent to you so that you can review it before sending it back to the server for execution.
MOVE listname userid@host <TO> newhost <PW=list_password>
DD=ddname listid@newhost [VM only]
The MOVE command allows list owners to easily move users from one peer server to another. It will move the complete user entry from the source server to the destination one, including full name as it appears in the specified list and all list distribution options. The MOVE operation will be done in such a way that no mail can possibly be lost by the target while the MOVE operation is in progress (duplicate mail might be received for a short duration, however). Notification will be sent to the target user unless the QUIET option was used.
If the source and destination list names are identical, only the destination node ('newhost') needs be specified. Otherwise, the full network address ('listid@newhost') must be specified.
The MOVE command requires both source and destination lists to have the same password. Since each server will have to send a password to the other to validate the (special) ADD/DELETE commands it is sending to the other, it has potentially a way to trap the password specified by the server, thus thwarting any attempt at inventing a protocol to allow use of this command on lists which have a different password. Besides, no MOVE operation will be accepted on lists which do not have a password at all, because for technical reasons it would allow unauthorized users to easily add someone to a list (since there would be no password validation).
The MOVE command is the proper way to effect a move operation. You should not use any other command/set of commands unless you cannot use MOVE. THE MOVE COMMAND SHOULD NOT BE USED TO MOVE DISTRIBUTION LISTS!!! Since a MOVE is basically an ADD + DELETE, with the latter being done only AFTER the ADD is completed, moving a distribution list address with the MOVE command can cause a duplicate link to be defined for a short period of time. This could result in a transient mailing loop, which could become permanent if the size of the looping mailfiles is less than the size of the inter-servers "DELETE" command jobfile, and the RSCS priority of the latter has been altered.
2.13.12. "Super-lists" and "sub-lists"
This functionality is not available in LISTSERV Lite.
Please note that the LISTSERV maintainer must create the super-list.
In LISTSERV Classic 1.8c and following it is possible to define a "super-list" (as in opposite of sub-list), that is, a "container" list that includes all the subscribers in a predefined set of sub-lists. This can be done recursively to any depth. Only the LISTSERV maintainer can create a super-list, for security reasons. Concretely, the "Sub-lists=" keyword is protected from owner tampering in the same fashion as "Notebook=". The value is a comma separated list of all the sub-lists, which must all be on the same (local) machine. For instance:
* Sub-lists= MYLIST-L,MYOTHERLIST-L
The default value for this keyword is null, e.g., to have no sublists. Please note that the super-list and all of its sublists must reside on the same LISTSERV server.
The only difference between a normal list and a super-list is what happens when you post to it. With the super-list, the membership of all the sub-lists is added (recursively) and duplicates are suppressed. Other than that, the super-list is a normal list with its own archives, access control, etc. You can even subscribe to it, and this is actually an important aspect of the operation of super-lists. If you are subscribed to the super-list itself, the subscription options used to deliver super-messages to you are taken from your subscription to the super-list, just like with any other list. All combinations are allowed, and in particular NOMAIL is allowed, meaning you don't want to get messages posted to the super-list. When you are subscribed to multiple sub-lists, on the other hand, things work differently:
1. NOMAIL subscriptions are ignored. You will get the super-message if you have an active (not NOMAIL) subscription to at least one sub-list. The idea is that the super-message must be equivalent to posting to all the sub-lists, without the duplicates. Since all it takes to get a message posted to all the sub-lists is a single non-NOMAIL subscription, this is how the super-list works. The only way not to get the super-messages is to subscribe to the super-list directly and set yourself to NOMAIL.
2. The DIGEST and INDEX options are ignored and internally converted to MAIL. The first reason is that, since in most cases the user will be on multiple sub-lists (otherwise you don't need a super-list in the first place), the only safe method to set subscription options for super-messages is by subscribing to the super-list so that there is no ambiguity. The second reason is that, in most cases, super-lists will be used for out of band administrative messages rather than for large volume discussions, so it is actually preferable to have the message sent directly. The third reason is that the super-list and sub-lists may not necessarily offer the same options (DIGEST and INDEX). In particular it is expected that many super-lists will not have archives. If you want a DIGEST or INDEX for the super-messages, you must subscribe to the super-list directly.
3. In LISTSERV 1.8c and 1.8d, the REPRO option is NOT inherited by sub-lists. That is to say, even if the sub-list subscriber is set to REPRO on the sub-list AND the super-list is set up such that sub-list subscribers may post directly to it, he will NOT receive a copy of his own posting. REPRO is effective only for users who are directly subscribed to the super-list. This restriction has been removed in LISTSERV 1.8e.
Topics, if defined, are evaluated on a per-list basis. That is, for every sub-list (and for the super-list), LISTSERV determines whether the topic of the message is one that you want to see. If not, it acts as if you were not subscribed to this particular list. Roughly speaking, this works very well if all the sub-lists have the same set of topics (or a well-defined set of common topics), and doesn't work well at all if every list has its own set of topics.
Postings to a super-list are always archived in the super-list's notebooks (if enabled), and never in the notebooks of the sub-lists. This is because by its nature a posting to the super-list is not equivalent to cross-posting a message to all of the sub-lists. Rather, LISTSERV recurses into the sub-lists and generates an "on the fly" listing of all of the users on the super-list and the sub-lists (this is how it avoids duplicates, among other things) and then treats this "on the fly" listing as if it were the subscriber list of the super-list itself. You will note that a super-list posting is always identified as coming from the super-list, regardless of whether a given user is subscribed to the super-list or to one or more of the sub-lists.
Note carefully that a REVIEW command sent for the super-list will not recurse into the sub-lists pointed to by the super-list. If you have a super-list called SUPER and you send a REVIEW SUPER command, LISTSERV will respond with only the people who are subscribed directly to SUPER.
LISTSERV 1.8c and 1.8d: Also note that the REPRO option is honoured only when the user posting to the super-list is subscribed to the super-list with the REPRO option set. The REPRO option is not evaluated when LISTSERV recurses into the sub-lists. Thus if you have a super-list that is set up so that all of the subscribers of the sub-lists are able to post to it without actually being subscribed to the super-list, they will not receive copies of their own postings even if they are set to REPRO on the sub-lists.
LISTSERV 1.8e and following: The above restriction has been removed and REPRO works for users who are subscribed to the sub-lists.
Similarly, access to the super-list's notebook archives is not automatically recursive. If you want sub-list subscribers to be able to access the archives of the super-list (but don't want the sub-list subscribers to have to subscribe to the super-list), then you must configure the Notebook= keyword for the super-list so that it contains references to each of the sublists. For example, say we have a super-list called SUPER and two sub-lists called SUB-A and SUB-B. We want the subscribers of both SUB-A and SUB-B to be able to read the archives of SUPER (since postings to SUPER won't be archived in SUB-A or SUB-B), but we don't want people who aren't susbcribed to any of the three lists to be able to access the archives. So we set
* Notebook= Yes,C:\LISTS\SUPER,Monthly,Private,(SUB-A),(SUB-B)
and anyone subscribed to the SUPER list or to the SUB-A or SUB-B lists can access the SUPER archives.
If you have many sub-lists, you can specify multiple Notebook= lines, e.g.,
* Notebook= Yes,C:\LISTS\SUPER,Monthly,Private,(SUB-A),(SUB-B)
* Notebook= (SUB-C),(SUB-D),(SUB-E),(SUB-F)
LISTSERV will read these two (or more) Notebook= lines and concatenate the values.
Some sites may have a need for many lists that are essentially identical. For instance, a series of class section lists for a university department may have the same owner, allow the same class of users to subscribe, and so forth. LISTSERV makes it possible to maintain large collections of lists by "including" keywords from an external file.
For instance, consider a mathematics course with ten sections. Each section should have its own list (for instance, called M101-001, M101-002, and so forth), but the lists will otherwise be identical. The LISTSERV maintainer simply creates a text file (in this case called M101 KEYWORDS) containing the keyword definitions that will be shared by the lists, as follows:
PUT M101 KEYWORDS PW=createpw
* Owner= mathwhiz@someuni.edu (Professor J. Random User)
* Owner= Quiet:
* Owner= gradasst@someuni.edu (Joe Doakes, Graduate Assistant)
* Notebook= Yes,/home/listserv/archives/m101,Monthly,Private
* Auto-Delete= No
* Errors-To= gradasst@someuni.edu
* Subscription= Closed
* Notify= Yes Confidential= Yes Validate= Yes,Confirm,NoPW
* Reply-to= List,Ignore Review= Owners Send= Private
* Default-Options= Repro
Next, the LISTSERV maintainer stores this file in the usual way, by first making a filelist or catalog entry for it (as outlined in chapter 8) and then storing it with a PUT operation. Generally the GET and PUT FACs for this file should specify that the list owner(s) should be able to retrieve and store it. The file must be stored in LISTSERV’s A directory (the same directory that contains the *.LIST files).
Note that it is also possible to create this file directly in LISTSERV’s A directory with a text editor; if you do so, make sure that you do not include the PUT command shown above. You should still make the filelist or catalog entry for the file so that the list owners can retrieve and store it.
Next, the LISTSERV maintainer creates and stores a skeleton list header for each of the section lists. The first section list (M101-001) is illustrated below:
PUT M101-001 LIST PW=createpw
* Math 101 Section 001 Mailing List
* .IK M101
The .IK command tells LISTSERV that whenever it uses this list, it should read the keyword definitions from the file M101 KEYWORDS (note carefully that the syntax is ".IK M101", not ".IK M101 KEYWORDS"). Now, whenever the professor in charge of the class wants to make a change to all of the M101 lists (for instance, he has a new graduate assistant), he simply GETs the file M101 KEYWORDS, makes the changes, and PUTs the file back, instead of having to GET separate headers for each list and make the changes to all of them individually.
Note: On some servers the LISTSERV maintainer may have to stop and restart LISTSERV (or do a GET+PUT of all of the list headers involved) to make changes to the KEYWORDS file appear. This is because LISTSERV may have the KEYWORDS file and/or the list headers that use it cached at the time you modify it.
In order to see the complete list header, send a REVIEW listname command. The response to a GET will be only the skeleton header with the .IK command.
Special note: The sample KEYWORDS file above includes a Notebook= keyword. This will cause the notelogs for all of the lists that use this KEYWORDS file to be written in the same directory, per the example, /home/listserv/archives/m101 . This means that in that directory you would have notelogs for the M101-001 list, the M101-002 list, and so forth (depending of course on what lists use the example M101 KEYWORDS file). If this behavior is not desired, simply don't put a Notebook= keyword in the KEYWORDS file, and define it in the list header for the cloned list instead, either before or after the .IK directive.
For the web archive interface, note carefully that if you do use the same directory for all of the cloned lists' notelogs, the LISTSERV maintainer will still have to make separate web archive directories for each list under your WWW_ARCHIVE_DIR directory if you intend to serve the archives via the web interface. In other words, the web interface doesn't care where you keep a list's notelogs as long as it has a directory specified under WWW_ARCHIVE_DIR for it to write the list's web archive indexes into. So while all of your notelogs may go into /home/listserv/archives/m101 , regardless of the name of the cloned list, the LISTSERV maintainer still needs to make (for example) /usr/local/etc/httpd/htfiles/archives/m101-001 and so forth in order to serve the notelogs on the web.
2.14. List passwords are now obsolete
In LISTSERV 1.8c and later, when creating the list, a random password is assigned for security if the LISTSERV maintainer does not define one explicitly. In 1.8c and later it is no longer necessary to use the list password in all but one situation; it is simply another line of defense, and you can substitute a personal password in any command that formerly called for a list password. See section 2.9, above, to learn how to create a personal password.
The only situation in which a list password MUST be defined explicitly in a list header is in the case of peered lists, where the PW= list header keyword must be set to the same value on all peers.
2.15. Allowing/Blocking MIME Attachments
LISTSERV 1.8d kits starting in May 2000 contain a new MIME attachment-filtering feature which is configured by setting the new Attachments= list header keyword. The new keyword allows three distinct modes:
· Allow all MIME attachments, no filtering or blocking
· Reject MIME attachments with notice to the poster
· Filter MIME attachments out of messages transparently
In addition, you can configure specific MIME types to reject or filter while allowing other types through (for instance, you can block executable files but allow images or word processing files based on their MIME type).
For information on the various settings, please see the section on the Attachments= keyword in Appendix B of this manual.
This feature requires LISTSERV 1.8e or later. It is not available in LISTSERV Lite.
This feature is intended primarily to filter out-of-office messages and the like. It is not intended as a profanity filter. Attempts to configure it to filter profanity will most likely prove to be futile in the long run and are not recommended by L-Soft.
The CONTENT_FILTER mail template form, if present, contains filtering rules, one rule per line, empty lines ignored. Each rule has the following format:
[prefix:] pattern
The prefix, if present, can be a mail header tag (eg "Subject:"); "Header:" to check the whole header; or "Text:" to search the message text. The latter is the default if no prefix is supplied, it is provided in case the pattern contains a colon in the first word. If there are multiple mail header tags with the specified name (eg "Received:"), each such tag is searched and it is enough for one of them to match the pattern. If the requested tag is not present in the header, there is (surprise!) no match. A text search will search every line of the first text/plain part in the message. If there is no text/plain part, there is no match. Again, this is designed to filter read receipts, loops, chain letters, spam, you name it. There was no attempt on the developers' part to make this a profanity filter, and future versions will not be "enhanced" to make futile attempts at (for instance) decoding Word documents to look for obscene words.
Regular comparisons such as those described above are not case sensitive. Patterns are standard LISTSERV patterns, that is, the asterisk is the wildcard character. If there is no asterisk in the pattern, it is replaced with "*pattern*" much like the SCAN command.
The content filter also supports "exact match" comparisons, which are triggered by a double colon. For instance:
Subject::
There are two significant differences between exact and regular match:
a. You must supply your own wildcard characters in an exact match (if you want to use wildcards, that is). A regular match will insert leading and trailing wildcards if none are found. Thus, an exact match is the only way to make a comparison without wildcards.
b. You can make an exact match for the empty string. Empty regular matches are ignored since they map to a wildcard comparison for **, which would be always true. This also makes it possible to apply an exact match to a message that does not contain a specified header. For instance, if you want all messages to contain a (mythical) KABOOM: RFC822 header, with an exact match you can tell LISTSERV to perform one of the content-filtering actions if the the header is not present. This is not possible with a regular match.
Note however that you cannot differentiate a header with an empty KABOOM field from a header with no KABOOM field.
One of the most handy uses for the exact match syntax is to be able to write a rule to reject messages with blank subject lines. For instance:
Subject::
Action: REJECT Please resubmit your message with a non-blank subject.
Every rule can, optionally, be followed by an action rule. This has the following format:
Action: ALLOW
Action: REJECT reason
Action: DISCARD comment
Action: MODERATE
(The available actions are the same for both regular and exact comparisons.) For instance,
>>> CONTENT_FILTER
Subject: Out of office
Action: REJECT OOO messages are not allowed on this list.
Subject: Auto-Generated:
Action: REJECT
Text: Click here to be removed
Action: REJECT Buzz off, spammer.
Subject::
Action: REJECT Please resubmit with a non-blank subject.
Subject: copyright
Action: MODERATE
To: friend@public.com
Action: DISCARD This guy is a spammer
The default is "Action: REJECT" with no specified reason. REJECT means that the message is rejected. MODERATE means that the message is to be forwarded to the list editor to be manually approved or rejected. DISCARD means that the message is to be dropped on the floor without further processing; any text following DISCARD is echoed to the LISTSERV console (and is thus logged).
ALLOW means that the message is allowed and all remaining rules are ignored. This could be used in moderated lists to allow the list moderator to bypass certain filters, for instance:
>>> CONTENT_FILTER
Subject: Out of office
Action: REJECT OOO messages are not allowed on this list.
From: JOE@EXAMPLE.COM
Action: ALLOW
Text: Click here to be removed
Action: REJECT Buzz off, spammer.
In the example above, messages with Subject: lines containing "Out of office" are rejected. Messages containing the text "Click here to be removed" are also rejected UNLESS they come from joe@example.com .
The text of the rejection is fetched from the BAD_CONTENT mail template form, with the reason supplied as a variable called &COMMENT. The rejection message looks like this:
Date: Tue, 4 Dec 2001 22:03:42 -0500
From: "L-Soft list server at LISTSERV.EXAMPLE.COM (1.8e)"
<LISTSERV@LISTSERV.EXAMPLE.COM>
Subject: Rejected posting to TEST@LISTSERV.EXAMPLE.COM
To: Joe User <joe@EXAMPLE.COM>
Your posting to the TEST list has been rejected by the content filter. OOO
messages are not allowed on this list.
followed by the text of the posting including all mail headers. (In this case the body of the message contained the text "out of office" and the rule above was applied.)
A default site-wide CONTENT_FILTER template form may be defined in $SITE$.MAILTPL for use by lists whose owners do not prefer to provide their own custom versions in their listname.MAILTPL files.
2.17. DomainKeys Message Signing (14.5)
This feature is not available in LISTSERV Lite.
Starting with LISTSERV 14.5, DomainKeys message signing is available to sites running LISTSERV Classic or LISTSERV Classic HPO. If you do not know what version of LISTSERV you are running, or whether or not the DomainKeys signing feature is enabled on your server, please contact your site administrator before attempting to use the feature.
Assuming that it is available for your use, DomainKeys support for a list is enabled by default. This means that all list postings and administrative messages related to your list will be signed to assert that they actually originated from your LISTSERV server.
If for some reason you wish to disable DomainKeys message signing for your list, you can do so by adding
* Misc-Options: NO_DKIM_SIGNATURE
to your list header.
Note: Incoming DomainKeys or DKIM signatures in messages submitted to a mailing list will be removed unless "Misc-Options= KEEP_DKIM_SIGNATURE" is set in the list configuration. This is necessary because these signatures almost never match after the message has been processed. The worst thing that could possibly happen to your deliverability is a DomainKeys signature that does not match and causes the message to be flagged as suspicious.
The KEEP_DKIM_SIGNATURE option is experimental and not meant for general
use. As DomainKeys is specified today,
signatures DO NOT survive posting to mailing lists (LISTSERV or otherwise), so
LISTSERV removes them by default to avoid triggering alerts for subscribers on
systems that have implemented the client side of DomainKeys. The DKIM specification may be more robust in
this respect, but even DKIM signatures will probably not survive when posted
through a mailing list. Use the
KEEP_DKIM_SIGNATURE option at your own risk.
3. Advertising Your Public Mailing Lists
3.1. Lists of Lists maintained by LISTSERV
LISTSERV automatically produces a List of Lists that may be reviewed by users anywhere on the Internet in one of two ways:
· L-Soft's CataList service at http://www.lsoft.com/CataList.html
· The LISTS GLOBAL searchtext command. This list of lists is made up of one-line entries containing the short listname and the descriptive title of the list (up to about 60 characters in length). A sample of the List of Lists format was shown in Chapter 2.
Note that it is possible to code a descriptive title in your list header that is more than 40 columns long, but the List of Lists will include only the first 40 columns of that title. It is therefore important from this respect to be sure that the descriptive title of your list is succinct and to the point.
3.2. Adding HTML to a list header for the CataList
L-Soft's CataList service (http://www.lsoft.com/lists/CataList.html) allows users to search the global list of public LISTSERV lists via the World Wide Web. Adding an HTML description to a list is easy, and can do a lot to enhance the appearance of a list in the database. All you have to do is update your list header and add the text of your choice. Here is an example:
* The coffee lovers' list
*
* Review= Public Subscription= Open Send= Public
* Notify= Yes Reply-to= List,Respect
* Notebook= Yes,L,Monthly,Public
*
* Owner= claudia@espresso.xyz.it (Claudia Serafino)
*
* <HTML>
* COFFEE-LOVERS is an open list for, well, coffee lovers! Our
* motto is: <cite>"Instant – just say no!"</cite>
* That's pretty much our whole charter, although there are a
* few other <a href="http://www.coffee.org/charter.html">
* rules</a> that you may want to read before joining. For
* instance, we don't allow flame wars about decaf: if you like it,
* well, it's your body after all.
*
* <p>The list is maintained by
* <a href="http://www.coffee.org/claudia.html">Claudia
* Serafino</a> (that's me!) and you will find all sorts of
* useful info about coffee on my home page.
* </HTML>
*
In other words, you just insert your HTML text in the list header and bracket it with <HTML> and </HTML> tags (these tags tell the web interface where the HTML text begins and ends – they are not actually sent to the web browser). There are three simple rules that you must follow when inserting your HTML data:
1. The <HTML> and </HTML> tags must appear on a separate line, as shown in the example above. You cannot have anything else on that line and, in particular, you cannot mix keyword definitions with HTML data.
2. The HTML data you are providing is embedded into the document shown by the web interface when users query your list. Because you are given some space between two horizontal rules on an existing page, rather than a whole new page. you should not include tags that affect the whole document, like for instance <TITLE>.
3. While this procedure is compatible with all versions of LISTSERV, there are a few restrictions on the placement of equal signs within your HTML text with versions that do not have any specific support for the <HTML> and </HTML> markers. In practice, you can ignore this rule unless you get an error message while storing your list.
When reformatting your list header description for HTML, bear in mind that the text will not always be viewed using a web browser. It is best to keep the formatting as clear as possible and minimize the usage of HTML tags, since there are still many people without WWW access. For instance, do not hesitate to use white space between paragraphs for clarity.
Barring network outages, a list header update takes a maximum of 24h to be reflected in the distributed LISTS database. Database updates are usually scheduled to be broadcast at night, so the changes take place overnight. Once the LISTS database has been updated, it can take a maximum of 24h for the frozen copy of the database used by the web interface to be updated. In most cases, both the LISTS database and its frozen copy on the web server will be updated overnight. However, if the site hosting your lists is several time zones west of the site hosting the web server, and if that server only updates itself once a day, you may have to wait two days for your update to be reflected.
3.2.2. Inserting a pointer to another list
Sometimes it may be useful to link a number of related lists together so that the viewer can quickly examine all the lists without having to go back to the search screen and retyping the names you are providing. You can do this using the special HTML sequence:
<!--#listref listname@hostname-->
This sequence is internally translated to an <a> tag with a URL that will bring up information about the list you indicated. You must then provide a suitable caption and a closing </a> tag. Example:
Don't forget to take a look at
<!--#listref COFFEE-L@COFFEE.ORG-->
the coffee list!</a>
3.2.3. Restrictions on the placement of equal signs
While all versions of LISTSERV are supported, servers which have no specific support for the <HTML> and </HTML> tags will process your HTML data as an ordinary list header line and attempt to determine whether it contains a list header keyword or descriptive text. The exact algorithms vary from one version to another, but in general the parser looks for a single word followed by an equal sign. With HTML text, it is possible (if unlikely) to generate such patterns. Here is an example:
*
* Sample list with problem pattern
*
* <HTML>
* For more information on the list, just check <a
* href="http://www.xyz.edu/mypage.html">my home page.</a>
* </HTML>
*
In that case, you can just reorder the HTML data so that the equal sign does not appear in this position. Alternatively, if the equal sign was meant to be actually displayed as an equal sign (as opposed to being part of some HTML tag), you can use the HTML escape sequence = instead.
3.3. Defining search categories in a list header for the CataList
Note: The complete list of search categories may not yet be available when LISTSERV 1.8e is released. Note also that during the "pilot" phase of categories implementation, all categories will be "open", and you can define search categories for your list as long as the categories you define are in compliance with the rules for defining categories. When the "production" phase begins, only categories defined below as "open" will be open, and if a list is created or modified without a "Categories=" keyword, LISTSERV will issue a warning (but will go ahead and store the list without it).
Another feature of the CataList service discussed in the preceding chapter is the ability to search for lists based on topic categories. For instance, a user might be looking for lists that discuss various aspects of opera. The same user might want to search not just for lists that discuss opera in general, but great operatic tenors in particular.
In order to implement search categories for your list, you use the new "Categories=" list header keyword, in conjunction with the list of categories that can be found at the CataList site. The URL for the category list is http://www.lsoft.com/listcat.html.
If you do not have a web browser, you can issue the command
GET LISTCAT FILE
to LISTSERV@LISTSERV.NET or any LISTSERV server running version 1.8c or higher to have a list of categories mailed to you.
A typical category listing is in two parts. The first part is the category title itself (this is what you code in the "Categories=" keyword). The second part is an optional description of what the category covers. For instance:
Category:SubCategory:MinorCategory Description of this category
There are two types of categories that you need to be aware of.
Open Categories: These categories have a description indicating that they are open and can be added to. Taking our example of great operatic tenors above, you might see the following category listed:
Arts:Music:Opera:Singers Operatic Singers (Open)
You notice that there are further subcategories like
Arts:Music:Opera:Singers:Te_Kanawa_Kiri
Arts:Music:Opera:Singers:Caruso_Enrico
and so forth, but (gasp!) no category for your favorite tenor, Luciano Pavarotti! And your list is PAVAROTTI-L. Not to worry, however. Because the category of "Singers" is open, you can simply code:
* Categories= Arts:Music:Opera:Singers:Pavarotti_Luciano
and LISTSERV will accept the new subcategory "Pavarotti_Luciano".
Note that when you create a new category, it will not show up until the central categories list has been updated.
Note also that there are two "root level" open categories, Misc and Local. The Misc category is world-searchable. If, however, you code a Local category, it will only be searchable from the search engine running on the server hosting your list.
Closed Categories: These are categories that cannot be added to. In other words, if you see a category like:
Computers:Internet:Mailing_List_Managers:LISTSERV:Manuals:List_Owners_Manual List Owner's Manual for LISTSERV
whose description does not indicate that it is open, then you cannot add new categories after the last term. If you try to create a new subcategory under a closed category, you will receive an error message when you PUT your list header, and your updated header will not be stored.
3.3.1. Examples of category settings
Categories are defined by the new "Categories=" list header keyword. Each category string's subcategories are internally delimited with colon (":") characters. Each separate category string is separated from the others with commas. If your "Categories=" keyword setting gets too long to fit on one line, simply define multiple "Categories=" keywords. Note that spaces are not allowed in categories; therefore
* Categories= Arts:Music:Opera:Singers:Luciano Pavarotti
is not legal, but
* Categories= Arts:Music:Opera:Singers:Luciano_Pavarotti
is.
A simple category setting would be:
* Categories= Arts:Music:Opera:Singers
and if someone searched on that category, they would find our list. But we saw above that we can create a new category if we are running a list dedicated to Luciano Pavarotti. So instead, we might code
* Categories= Arts:Music:Opera:Singers:Pavarotti_Luciano
If, however, we're running a list for the Three Tenors, we might want to code:
* Categories= Arts:Music:Opera:Singers:Pavarotti_Luciano
* Categories= Arts:Music:Opera:Singers:Domingo_Placido
* Categories= Arts:Music:Opera:Singers:Carreras_Jose
Or even:
* Categories= Arts:Music:Opera:Singers:Three_Tenors
depending on our preference.
If you code a sub-category that does not exist in a "closed" upper-level category, LISTSERV will respond with an error message that will list the legal sub-categories that you can use.
3.4. The INFO <listname> command and how to implement it
This functionality is not available in LISTSERV Lite.
Chapter 9, Customizing LISTSERV's Default Mail Templates, includes details on how to include an informative paragraph in the information mail template file for your list. When a user sends the command INFO listname to your server, LISTSERV responds with either:
· The default response, which simply sends a copy of the list header to the user; or
· The customized paragraph included in the listname.MAILTPL file.
If listname.MAILTPL does not exist, the default response is sent. Also note that the user may send the INFO listname command to any L-Soft LISTSERV host (including the Global List Exchange discussed below), which will forward the request to the appropriate server.
The NEW-LIST project was started in 1989 to promote mailing lists via a mailing list. Originally hosted on NDSUVM and later on LISTSERV.NODAK.EDU at North Dakota State University, NEW-LIST was moved to the Internet Scout Project in July of 1998, and then in June, 2000 to Classroom Connect (www.classroom.com). The NEW-LIST administration asks only that your list be well-tested and ready for new subscriptions before you send your announcement to them. You also want to make sure that your announcement is as correct and comprehensive as possible, as news on the Internet spreads quickly and a mistake in a NEW-LIST announcement may cause problems for both you and other users months later.
For more information on the NEW-LIST project and what you need to use it, you should point a World Wide Web browser at the URL
http://listserv.classroom.com/archives/new-list.html
(As a matter of historical note, the NEW-LIST Project published a hard-copy version of their archive in 1992 with a newer edition in 1993 under the title Internet: Mailing Lists [ISBN 0-133-27941-3], edited by Edward T. L. Hardie and Vivian Neou.)
3.6. The Internet Network Information Center (INTERNIC)
Unlike many other lookup services on the Internet, the INTERNIC is not necessarily free. Its three distinct sections are run by General Atomics, Network Solutions, Inc. (NSI), and AT&T.
You can register your list with the INTERNIC, but be forewarned. A "basic" listing is free, while an "extended" listing is not. (On the other hand, anyone with net access can search the INTERNIC databases for free.)
For more information, point a WWW client at the INTERNIC web site at http://www.internic.net .
3.7. The Global List Exchange (GLX) and why you should mention it
The Global List Exchange, or GLX, is a central clearinghouse for LISTSERV subscriptions and List of List requests. For instance, If a user knows the name of a list but not the name of the host server, GLX simplifies the process by giving the user a single address where all subscription requests for lists running on L-Soft's LISTSERV can be sent.
By adding the GLX address in all advertisements for your list, you help other list owners as well as yourself by making it simple for users to subscribe to any list. Additionally, if for some reason a user is unable to contact your server directly, the GLX gives him an alternate subscription method.
The GLX address is LISTSERV@LISTSERV.NET.
3.8. How NOT to advertise a mailing list
It is generally considered a breach of netiquette to invade the privacy of other lists with a broadcast announcement that your list is up and running. The only time when this might be acceptable is when your list addresses a concern of people already subscribed to another list. If you feel it necessary to post an announcement on someone else's list, it is good manners to first send private mail to the owner of that list and ask his or her permission to do so. (The same policy applies to USENET newsgroups, though it may be more difficult to find out who the moderator is.)
It is certainly a breach of netiquette (and many networks' appropriate use policies) to blindly post multiple copies of your announcements to multiple lists. This kind of behavior is termed a "spam", something about which you may read more in Chapter 6, Moderating and Editing Lists. This kind of announcement is guaranteed to reap a good deal of bad will and may well result in the revocation of your network privileges.
4.1. How to add and delete subscribers to/from a list
A list owner may add and delete subscribers manually. The command syntax is:
ADD listname netaddress full_name
DELete listname netaddress
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. (See Appendix C for sample "boilerplate" instruction files that can be modified to suit local purposes.) 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: Joe User <JoeUser@example.com>
becomes an ADD command as follows:
ADD MYLIST-L Joe User <JoeUser@example.com>
4.1.1. Adding users whose address and real name exceed 80 characters
This problem happens particularly with the X.400 and X.500 addressing schemes, but can happen as well with any system which allows users to have a very long "local part" (i.e., the part to the left of the "@") in their userid, or with users on systems that just have very long names, such as some of the hosts in the .US domain generally have. For instance, you might try to send the following ADD to LISTSERV:
QUIET ADD MYLIST someone.with.a.real.long.userid.that.wraps@hishost.com
His Name
"His Name" wraps to the next line. If you send this to LISTSERV, LISTSERV treats the two lines as separate commands even though you did not hit RETURN after the user's address, and it responds:
> QUIET ADD MYLIST someone.with.a.real.long.userid.that.wraps@hishost.com
someone.with.a.real.long.userid.that.wraps@HISHOST.COM is not yet in the
signup file. Please specify the full name of that person, as in "ADD MYLIST
JOE@XYZ.EDU Joe H. Smith".
> His Name
Unknown command - "HIS". Try HELP.
To avoid this problem, set up your ADD command with a "continuation card" as follows:
// QUIET ADD MYLIST someone.with.a.real.long.userid.that.wraps@hishost.com ,
His Name
4.1.2. X.400 and X.500 addressing--Special Problems
X.400 and X.500 addressing schemes can cause problems for the list owner who is trying to add or delete one. These addressing schemes use the "/" character to separate address elements, but to LISTSERV, "/" is a special character and you would not be able to add or delete one of these addresses by simply cutting and pasting it into an ADD or DELETE command.
For instance, you might have an address like:
/G=Joe/S=Randomuser/OU=403402ABD/O=SOME.CORP/@LANGATE.SOME.HOST.COM
In order to either add or delete this address, there are two issues:
1. The address may wrap to the next line once you add the DELETE listname command, and LISTSERV will not accept it.
2. The address contains characters that LISTSERV will reject as illegal (the "/" character).
For adds, to get around both of these issues, you must use a LISTSERV JOB syntax as follows:
ADD MYLIST-L DD=X500 PW=MYPASSWORD
//X500 DD *
/G=Joe/S=Randomuser/OU=403402ABD/O=SOME.CORP/@LANGATE.SOME.HOST.COM
/*
Any other method will trigger an RFC822 parser error because of the "/" characters in the address. (Note that a user who is subscribing from an address like this will have no trouble; it is only when the list owner uses the ADD command that this difficulty surfaces.)
For deletions, to get around both of these issues, the wildcard character ("*") can be used. You may not need the entire address in order to delete it, so you might just use
DELETE MYLIST *G=JOE*S=RANDOMUSER*@LANGATE.SOME.HOST.COM
which solves both the line wrap problem and the illegal character problem at the same time.
You can also use double-quotes around the address if it contains illegal characters, and a "continuation card" (see 4.1.3) if the address is too long to fit on one line:
// DELETE MYLIST , "/G=Joe/S=Randomuser/OU=403402ABD/O=SOME.CORP/@LANGATE.SOME.HOST.COM"
4.1.3. Continuation card syntax
The basic syntax of a continuation card is
//<space><beginning of command><space><comma>
<continuation of command><space><comma>
<continuation of command>....
for example,
// QUIET ADD MYLIST someone.with.a.real.long.userid.that.wraps@hishost.com ,
His Name PW=mypassword
or, for instance, for a large GETPOST job,
// GETPOST MYLIST 10769-10770 10772 11079 11086 11095 11099-11100 11104 ,
11111 11115 11118 11121 11124 11131 11144 11147 11153 11158 11166 11168
Without going into a lot of detail, the "//<space>" at the beginning of the command causes LISTSERV to look for a comma at the end of the first line and, if if finds the comma, to add anything following the comma on the second line to the end of the first line. Be sure to put a space before the comma at the end of the first line, as LISTSERV will not add the space for you.
For more information, see the chapter on LISTSERV's Command Jobs Language Interface (CJLI) in the Developer's Guide to LISTSERV.
4.2. Finding users who do not appear in the list
Sometimes the list owner will get a message from a subscriber who says, in essence, "I keep trying to (unsubscribe/change to digest/etc.) and LISTSERV says I'm not subscribed. Can you help?" This requires some detective work.
There are a couple of strategies for figuring out what is wrong. List owners should first use the powerful SCAN command to search for a pattern anywhere in the subscriber list. The syntax is:
SCAN listname search-text
For instance, "SCAN TEST-L Nathan" might return:
> scan test-l Nathan
Nathan Brindle <nbrindle@INDYCMS.IUPUI.EDU>
Somebody Else <nathan@BAZ.NET>
Jonathan Smith <jsmith@FOO.BAR.COM>
SCAN: 3 matches.
Note that SCAN is not case-sensitive. "Nathan", "NATHAN", and "nathan" all return the same results.
Searches with SCAN should start out simple and become more complex as needed. For instance, if there are only three people in the list with the string "NATHAN" as part of their subscription record, it will be unlikely that you will need to make the search any more complex. If you are looking for "SMITH", however, it may be necessary to further qualify your search string, say to look for "JOE SMITH". Another reason it is important to begin with a simple search string is that your user may not be subscribed under the exact address the error is returning to you. For instance, say you don't have the user's id, but you have a host name. You can search for all occurrences of the host name, but note that the search:
SCAN TEST-L MAIL.FOO.BAR.COM
will not find the user jsmith@foo.bar.com. If you run the following search:
SCAN TEST-L BAR.COM
however, you will find Mr. Smith's subscription.
Another possibility is that the subscriber may be using more than one address to work with his subscription. For instance, say the user's complaint to you came from JOE@SUN6.SOMEUNI.EDU. Looking at the list, you find a subscription for JOE@SUN8.SOMEUNI.EDU. LISTSERV has no way to know that JOE@SUN6 is the same person as JOE@SUN8, even though Joe and you know they are. The solution to Joe's problem above is for you to delete his SUN8 subscription and add his SUN6 address. Then Joe needs to be sure that he uses SUN6 in the future, if not for reading mail, then at least for managing his own subscription.
Another strategy would be to submit a wildcard QUERY to the list. The drawback to this method is that it might require multiple tries to find the subscription, depending on the complexity of the wildcard query.
Note also that not only can this sort of problem arise from a subscriber using more than one workstation to read mail, but it can also arise when a particular site changes its domain configuration, forwards mail from the old addressing scheme to the new addressing scheme, and doesn't inform its users of the change. In these cases, users often don't realize there is a problem until they try to unsubscribe or change personal options, because the change has been transparent to them.
4.3. Converting existing lists from other systems to LISTSERV
4.3.1. Converting mailing lists
Currently there are no supported conversion programs that will take (for instance) a Majordomo or ListProc mailing list and convert it to LISTSERV format. However it should be possible to extract the address list from the non-LISTSERV list and use a bulk add operation (see chapter 4.4) to populate your new LISTSERV list.
4.3.2. Converting message archives
Note also that existing list archive notebooks will probably not be in LISTSERV format (a modified VM MAILBOOK format), but rather, in the standard unix mailbox format. Again there are no supported programs to convert such archives to the LISTSERV format, but the basic format is as follows:
Message separator
Body of Message
Message separator
Body of Message
The MAILBOOK message separator is a line of 73 "=" characters (ASCII &H3D). Each archive notebook file must start with a message separator as the first line, e.g.:
=========================================================================
Date: Tue, 3 Mar 1998 10:36:55 -0500
Sender: Test list <TEST@LISTSERV.EXAMPLE.COM>
From: Nathan Brindle <nathan@example.com>
Subject: Test
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
First test message
=========================================================================
Date: Tue, 3 Mar 1998 10:39:11 -0500
Sender: Test list <TEST@LISTSERV.EXAMPLE.COM>
From: Nathan Brindle <nathan@example.com>
Subject: Test2
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Second test message
and the notebooks must be named in a standard LISTSERV format, e.g., TEST.LOG9803A, so that LISTSERV will see them and include them in the output of the INDEX listname command.
Note that for unix mailbox-formatted archives you must remove the first line of each message, which begins with "From" followed by a space (this is the standard unix mailbox delimiter). Below is an excerpt from a unix mailbox for illustration purposes:
From owner-test@listserv.example.com Mon Dec 29 15:17:20 1997
Return-Path: <root@listserv.example.com>
Received: from localhost (root@localhost) by listserv.example.com (8.8.3/8.8.3) 0
Date: Mon, 29 Dec 1997 15:17:20 -0500 (EST)
From: root <root@listserv.example.com>
To: test@listserv.example.com
Subject: Test
Message-ID: <Pine.LNX.3.95.971229151703.711A-100000@listserv.example.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: RO
X-Status:
This is a sample message from Majordomo in unix mailbox format.
Root
From owner-test@listserv.example.com Mon Dec 29 15:23:51 1997
Return-Path: <root@listserv.example.com>
Received: from localhost (root@localhost) by listserv.example.com (8.8.3/8.8.3) 0
Date: Mon, 29 Dec 1997 15:23:51 -0500 (EST)
....
Each of the lines beginning with From owner-test@listserv.example.com is the delimiter separating one message from the next.
4.4. Adding subscribers to lists in bulk
If you are moving a list from a non-LISTSERV site, you can quickly and easily convert the existing subscriber list to the LISTSERV format by following these instructions:
1. Have the LISTSERV maintainer at your new site create the new list header and install it on the machine.
2. Create an add job as follows. The QUIET and IMPORT command words are optional; omit the square brackets if you use them. The "full name" field is optional as long as you use the IMPORT option; otherwise you must either specify "*" (for an anonymous subscription) or a full name consisting of at least two separate words.
[QUIET] ADD listname DD=ddname [IMPORT] PW=yourpassword
//ddname DD *
userid1@host1.com [*|full name]
userid2@host2.com [*|full name]
...more users, one per line...
useridn@hostn.com [*|full name]
/*
For example (what fun:),
ADD B5-L DD=MYDD IMPORT PW=BLAHBLAH
//MYDD DD *
SHERIDAN@BABYLON5.MIL John Sheridan
IVANOVA@BABYLON5.MIL Susan Ivanova
LONDO@CENTAURI.PRIME.GOV Londo Mollari
GKAR@KAARI.NARN.GOV Citizen G'Kar
/*
If you are importing from an existing non-LISTSERV list, you should remove any lines from the original list that do not actually identify subscriber addresses. If you are converting to LISTSERV from ListProc, note that LISTSERV will not convert ListProc user options to their LISTSERV equivalents; you must take a line like
user1@somehost.com POSTPONE NEWLIST NO user's name
and reduce it at least to
user1@somehost.com user's name
Otherwise, the ListProc options will become part of the full name field.
3. Send the job to LISTSERV.
The IMPORT option implies a QUIET ADD (in other words you do not need to specify QUIET if you use IMPORT) and otherwise vastly speeds up the ADD process by loosening syntax checking and omitting success messages. If you do not use the IMPORT option and do not specify QUIET, the users you bulk add will receive the normal SIGNUP message and/or WELCOME file as usual.
4.5. Deleting subscribers from lists in bulk
If you have a large number of users to delete at one time, you can use a bulk delete syntax that is similar to the bulk ADD documented above. However please note that there is no "IMPORT"-type option for this feature, and as usual for the DELETE command you specify only the user's address in the data DD.
There is, however, a BRIEF option that can be specified which is good when you don't want a long list of "userid@host has been deleted from list xxxx" messages, one for each user deleted. Use of the BRIEF option tells LISTSERV to return only a count of the users that were deleted.
Once again you construct a LISTSERV JOB framework as follows and then send it to LISTSERV:
[QUIET] DELete listname DD=ddname [BRIEF] PW=yourpassword
//ddname DD *
userid1@host1.com
userid2@host2.com
...
useridn@hostn.com
/*
You will probably want to use the QUIET modifier when doing a bulk delete, in order to suppress the notification message to the users being deleted.
4.6. Using the QUIET option with commands
Prepending the command word "QUIET" before any LISTSERV command that you issue on behalf of a subscriber causes LISTSERV to suppress any notification to the subscriber of the changes you have made. This is particularly helpful when deleting subscribers whose accounts have expired and when setting subscribers with full mailboxes to NOMAIL, as it will help avoid another error message from the host when the notification message bounces. It is also helpful when adding subscriptions to the list that should not receive any welcome mail, such as redistribution lists and USENET newsgroups.
Examples of the usage of QUIET include:
QUIET ADD EXCEL-L comp.spreadsheets.excel@netnews.somenode.edu
QUIET DELETE EXCEL-L Bouncemeister@somenode.edu
4.7. Dealing with bounced mail
4.7.1. What is a bounce, and what can typically cause one?
A bounce is simply an undeliverable e-mail message. The term "bounce" is used to describe it because normally the system that discovers the delivery error "bounces" a copy of the message back to you with some sort of delivery error message. Sometimes these messages are easy to decipher – "No such user at foo.bar.com" – but uncomfortably often they are not that easy. Certain systems, as noted above, kindly format error notifications in a format that LISTSERV can understand, and if your list is configured for auto-deletion, these bounces will be the least of your worries – in fact, they will not be worrisome at all.
4.7.2. The owner-listname address
If you receive bounces processed through LISTSERV you will note that they normally say something like the following at the top:
The enclosed message has been identified as a delivery error for the MYLIST-L
list because it was sent to 'owner-mylist-l@LISTSERV.EXAMPLE.COM'.
------------------------------ Message in error -------------------------------
What this message means is simply that LISTSERV has received mail sent to the owner-listname mailbox for your list. Mail sent to this special address is automatically forwarded by LISTSERV to the address(es) you have defined in the Errors-To= list header keyword. The little "error-header" shown above is prepended to the actual error message to let you know that this is an error for your list (rather than unceremoniously dumping it into your mailbox and making you wonder "why did I get this?", since some delivery errors aren't specific about what list or even what user they are for). So whenever you get mail saying it was found in the owner-listname mailbox, it means that it is an error that you need to deal with for the list referred to by listname.
If you find that you have users trying to contact you (as list owner) at the owner-listname address, you should tell them that the correct generic address for contacting the list owner(s) is listname-request, not owner-listname. Mail sent to the listname-request address will be sent to all non-quiet list owners and furthermore will be automatically responded to with the REQACK1 mail template form from your listname.MAILTPL file (or its default from DEFAULT.MAILTPL; see chapter 9) while mail to owner-listname will not be responded to at all unless you do so explicitly. The nice thing about having people use the listname-request address is that you can store your list's FAQ (if you have one) in the REQACK1 mail template form and probably not have to answer all of the questions you get as list owner--like "how do I subscribe?" and "how do I sign off?".
4.7.3. What to do about several types of bounces
Please note carefully that it is not the intent of (nor would it be reasonably possible for) this manual to document each and every kind of delivery error that you may ever see as a list owner. Unfortunately, and completely outside the control of anyone at L-Soft, new types of cryptic, difficult to understand, and totally misleading errors appear all the time. If you run across something not otherwise documented here, the best place to ask for help is the LSTOWN-L mailing list (see chapter 10.6).
That being said, here are a few of the typical mail errors you will have to deal with as a list owner. Newer, so-called "Notary" format error codes are documented in RFC1893, which can be found at the WWW URL
http://nis.nsf.net/internet/documents/rfc/rfc1893.txt
1. no such user at host , user unknown (or "notary" format error number 5.1.1)
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".
Microsoft Exchange servers send back the following message for an unknown user:
Joe@EXCHANGE.EXAMPLE.COM on Wed, 4 Mar 1998 13:31:50 -0600
The recipient name is not recognized
MSEXCH:IMS:Example Corp:EXAMPLE:EXCOMEXCH 0 (000C05A6)
Unknown Recipient
2. no such host, host unknown (or "notary" format error number 5.1.2)
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 userid@host") 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.
3. no MX or A records for host (or "notary" format error 5.4.4)
Similar to "no such host". This means that the Domain Name Service (DNS) can't find any routing information for host but has found at least one reference to it. This generally indicates a DNS configuration error and may or may not be transient.
4. Transient failure: cannot deliver for n days
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.
5. mailbox full, quota exceeded (or "notary" format error number 4.2.2)
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".
6. unknown mailer error x
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 <userid@node>... 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.
7. Bounced, but sent successfully
This error comes from cc:Mail systems and is extremely misleading. It claims that the mail bounced to one address, but was sent successfully to another.
While talking to smtp.ccabc.com:
>> DATA
<< 554 I/O error to mailbox
554 MILLERT@smtp.ccabc.com... Service unavailable
----- Recipients of this delivery -----
Bounced, cannot deliver:
MILLERT@smtp.ccabc.com
Sent successfully:
<MILLERT@ABC.COM>
What this means (assuming that the mail hasn't gone through a redistribution list or a mirror site) is that you have a user MILLERT@ABC.COM on your list, and the server accepted the mail for that address successfully. However, that address actually maps to a different internal address (in this case MILLERT@smtp.ccabc.com) and for whatever reason, the server can't forward the mail on. This is the equivalent of a "user unknown" error for MILLERT@ABC.COM.
8. Too many hops (or "notary" format error number 5.4.6)
Means that the message has transited through too many intermediate mail systems (1 transit = 1 hop). Most of the time this will be due to a temporary looping condition on the user's end (despite the "permanent" 5.4.6 error). For instance, the following Internet routing headers indicate a loop between three different mail machines (starting from the bottom and working back to the top):
Received: from un1.sample.com (root@un1.sample.com [200.9.212.3])
by un7.sample.com (8.8.7/8.8.7) with ESMTP id RAA22765
for <user@example.com.ar>; Wed, 4 Mar 1998 17:17:10 -0300
Received: from ul1.sample.com (root@ul1.sample.com [200.0.224.2])
by un1.sample.com (8.8.7/8.8.7) with ESMTP id RAA27352
for <user@example.com.ar>; Wed, 4 Mar 1998 17:16:00 -0300
Received: from un7.sample.com (un7.sample.com [200.9.212.4])
by ul1.sample.com (8.8.8/8.8.8) with ESMTP id RAA13496
for <user@example.com.ar>; Wed, 4 Mar 1998 17:15:40 -0300 (GMT-3)
Received: from un1.sample.com (root@un1.sample.com [200.9.212.3])
by un7.sample.com (8.8.7/8.8.7) with ESMTP id RAA22034
for <user@example.com.ar>; Wed, 4 Mar 1998 17:15:27 -0300
Received: from grape.EASE.LSOFT.COM (grape.ease.lsoft.com [206.241.12.34])
by un1.sample.com (8.8.7/8.8.7) with ESMTP id RAA25235
for <user@example.com.ar>; Wed, 4 Mar 1998 17:08:43 -0300
The problem here appears to be that the mailers at sample.com are MX (mail exchanger) sites for example.com.ar, but that they can't decide which one of them should hold onto the mail until it can be delivered to example.com.ar. So it looped through 7 iterations until the un7 machine finally decided that enough was enough (including the passage through LISTSERV it had taken 26 hops and un7 was set to accept a maximum of 25 hops) and generated an error.
You may occasionally see a "too many hops" message that isn't a loop. Usually the non-looping variant is due to the recipient being many hops away from the mail originator and the maximum hop count being set too low on the recipient's machine. Many older sendmail installations, for instance, will accept only 10-15 hops before they reject the message. With today's Internet a setting of 30-40 is probably much more reasonable.
A particularly annoying error you may have to deal with comes from Banyan networks and is of the form:
LLONG@StarShip@Dora: Mailbox full
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 <LLONG%StarShip%Dora@BOONDOCK.TERTIUS.COM>
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.
4.7.4. Redistribution and forwarding
Perhaps the worst type of bounce is one that comes from a user who is "hiding" behind an account that redistributes mail (a "redistribution list"), or a user whose Internet address has changed slightly but who is still subscribed to your list under his original address.
Redistribution lists typically (but not always) take some form of your list's name (such as "xxxxx-L-REDIST@foo.bar.com"), and thus their subscriptions tend to be easy to find. What is difficult is that you have no way of knowing which users (or how many users) are hidden behind this interface, nor any way of knowing what their userids are.
Forwarded accounts generally fall into one of two categories – those where the user has forwarded his own mail from one account to another rather than changing his subscription, and those where the user's system name has changed and the old address is still valid but is forwarding mail to the new address without the user being aware of it.
Let's say that suddenly you are bombarded with delivery errors for someuser@baz.net. Your immediate reaction is to set this person to NOMAIL or (in some cases) to delete him/her altogether. You therefore send set xxxxx-L nomail for someuser@baz.net to LISTSERV. LISTSERV responds: "No subscription for someuser@baz.net in list XXXXX-L."
In a best-case scenario, you can query the list for *@*.baz.net and find either a user like someuser@glork.baz.net (the address has changed and the local sysadmins didn't inform the user) or a redistribution-list account like xxxxx-L@baz.net. These are easily-fixed redistribution bounces. In the first case, you delete the user and let him or her resubscribe. In the second case, you can try sending a message to owner-xxxxx-l@baz.net with a cc: to postmaster@baz.net and inform them of the problem. If it persists, you could send a further message informing them that you are suspending the redistribution list's subscription until such time as they tell you the problem on their end is fixed, and simply set xxxxx-l@baz.net to NOMAIL.
The worst-case scenario is as follows: baz.net may be bouncing the mail to you, but there may not be a single subscription for baz.net in your list. Here's where you have to do some careful sleuthing. First, run a wildcard query such as QUERY xxxxx-l FOR *@*baz* or QUERY xxxxx-l FOR *baz*@*. The former will find users at baz.com, for instance, where baz.net is a synonym for baz.com. The latter query may seem somewhat strange, but it's possible that the mail is being routed through a gateway and the actual subscription is for xxxxx-l%baz.net@cunyvm.cuny.edu or something of that sort.
4.7.5. "Sender:", "From:" or "Reply-To:" field in body causes bounce
Sometimes you will receive bounces from LISTSERV with a error header like this:
The enclosed message, found in the VISBAS-L mailbox and shown under the spool
ID 19630445 in the system log, has been identified as a possible delivery error
notice for the following reason: "Sender:", "From:" or "Reply-To:" field
pointing to the list has been found in mail body.
Sometimes this is a legitmate bounce from a mail system that isn't compliant with Internet standards for mail, and the reason the "Sender:", "From:", and/or "Reply-To:" headers are significant is because if this mail were to be allowed through to the list it could very possibly start a loop with the non-compliant mail server. Normally this is a good thing; however, an unfortunate side-effect of the loop-checking code that catches this kind of bounce means that LISTSERV may treat replies to list mail from some mail clients as if they are delivery errors. LISTSERV has no way to know the difference between a bounce and a legitimate message that just happens to have unquoted included headers so it takes the conservative route and bounces it to the list owner as a "possible" delivery error. This way the list owner can (if he or she wants to) return the message to the user in question and ask them to either quote out or delete the headers from their replies.
In any case this is specifically known to be a problem with Pegasus Mail and some incarnations of the Microsoft Exchange Client, but there are probably other mail programs that do the same thing. The problem arises when the user's mail client includes the "Sender:", "From:", or "Reply-To:" fields that point back to the list itself (for instance, the above error was for VISBAS-L@PEACH.EASE.LSOFT.COM) in the quoted material and doesn't quote them correctly--that is to say, without a quoting character, or with a space between the quoting character and the included text. For instance, a reply from Pegasus with quoted material would include the following lines:
User's reply, blah blah blah
> Date: Tue, 31 Dec 1996 17:00:00 -0700
> Reply-to: Visual Basic List <VISBAS-L@PEACH.EASE.LSOFT.COM>
> From: Joe User <JOE@UNIX.FOO.COM>
> Subject: Re: 97 Style ToolBars
> To: VISBAS-L@PEACH.EASE.LSOFT.COM
The quoted lines below the user's reply would trigger LISTSERV's loop detection functions because there is a space between the ">" character and the "Reply-To:" and the "From:" headers.
The correct, netiquette-approved method of quoting these headers is to delete them entirely from the body of your message. Quoting is generally done for reasons of context and message headers are not needed for context. (Pegasus actually lets you toggle this on and off via the "Advanced options for replies" dialog. Other clients don't seem to have this function.) Note that Eudora quotes messages with no space between the ">" character and the quoted text, so this is not an issue with Eudora.
If necessary, subscribers using Pegasus can change the quoting character (at least they can in the current version of Pegasus) by editing their copy of PMAIL.INI and changing the value in
[General]
...
Commenting string = >
Normally this variable contains "> ", that is, ">" followed by a space character. If you remove the space, Pegasus quotes "properly" and this is no longer a problem. Other mail clients may or may not have similar configuration settings.
(See also 10.2, below).
LMail is an L-Soft mailer product for VM mainframes. When it receives error mail from remote hosts it translates the error into a standard format recognized by LISTSERV so that LISTSERV can take action as necessary. From time to time you may see such errors in your mailbox; they look like this:
-------------------------------------------------------------------------
Date: Fri, 8 Jan 2000 20:04:50 +0100
Reply-To: Postmaster@SEARN.SUNET.SE
From: RFC822 mailer (LMail release 1.2d/1.8d) <MAILER@SEARN.EXAMPLE.SE>
Subject: Undelivered mail
To: ERIC@SEARN.EXAMPLE.SE
cc: Postmaster@SEARN.SUNET.SE
X-Report-Type: Nondelivery; boundary="> Error description:"
An error was detected while processing the enclosed message. A list of
the affected recipients follows. This list is in a special format that
allows software like LISTSERV to automatically take action on incorrect
addresses; you can safely ignore the numeric codes.
--> Error description:
Error-For: JACK@SEARN.SUNET.SE
Alias: JACK@SEARN.BITNET
Error-Code: 3
Error-Text: No such local user.
Error-For: JOE@SEARN.SUNET.SE
Alias: JOE@SEARN.BITNET
Error-Code: 3
Error-Text: No such local user.
Error-End: Two errors reported.
------------------------- Rejected message (5 lines) --------------------------
Date: Fri, 8 Jan 1993 20:04:47 +0100
From: Eric Thomas <ERIC@SEARN.BITNET>
To: JACK@SEARN.BITNET, JOE@SEARN.BITNET
Testing.
The LMail codes stand for the following:
0 is used for all the weird errors that can't easily be classified, and LISTSERV takes no action on these codes by definition. This includes errors such as "invalid device name" or "device full" which have meaning only for the postmaster of the host that bounced the message.
1 means "don't know that/don't know how to get there" (as opposed to "can't get there right now"), which is used when the host can't be found (eg, "host unknown").
2 means "configuration error". This means that LMail has detected an error in its routing tables which prevents it from delivering the mail. It does not necessarily mean that the address is bad.
3 is "no such local user".
4 is "not allowed to mail to this user".
The difference between 3 and 4 is that a 3 indicates there is no way to successfully send mail to the user, whereas 4 indicates the user cannot receive mail from the address your message came from. LMail uses code 4 when a local LMail user directs it to reject all mail coming from mailing lists, but to let private mail through. Typically you will not see very many 4 codes.
5 means "mailbox full", "quota exceeded", and so on.
LISTSERV itself takes action on error codes 1, 3 and 4, and forwards anything else to the list owner.
4.8. Delivery error handling features
LISTSERV supports several levels of automatic deletion based on error messages passed back to it in LMail format 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 Classic 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() parameters 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. Note carefully that LISTSERV will not generate a daily error monitoring report when Delay(0) is used.
The default value is "Auto-Delete= Yes,Semi-Auto,Delay(4),Max(100)" for lists coded "Validate= No" and "Auto-Delete= No" for all other lists.
Under LISTSERV Lite, Auto-Delete= is available but deletes on the first bounce (e.g., "Delay(0),Max(1)") regardless of the Delay() and Max() settings.
Implementation of the "Auto-Delete=" keyword is discussed in detail in Appendix B, List Keyword Alphabetical Reference, under "Error Handling Keywords."
4.8.1. Auto-Delete considerations for holidays
Making a big increase to the DELAY threshold to provide more leniency during a holiday may not be a good idea. While it will indeed disable the monitor for the duration of the holiday, switching back to the normal threshold when you return will cause the monitor to delete all the users that had been bouncing during the holidays. In general, you should avoid making temporary changes to the DELAY threshold, because it takes the monitor a while to adapt to the new settings.
The best way to relax the rules during a long holiday is to leave the DELAY threshold unchanged but switch the monitor to passive mode ("Auto-Delete= Yes,Manual"). Noone will be deleted over the holidays, but the monitor's cycle will not be perturbed. When you return, you should wait about a week before switching back to automatic mode. This is because, after a long holiday such as Christmas, it usually takes about 2 working days for system administrators to solve all problems. In some cases, the problems will have caused bounces to remain undelivered. So, by fixing the problems, the system administrators may actually send a flood of new bounces corresponding to problems that have now been solved. Unfortunately, since the monitor only receives NON-delivery reports, it has no way to know that these problems have in fact been solved. As a rule of thumb, you will note that your daily delivery error reports are much longer than usual over the vacation. When you return, you should wait until they are back to their normal size before switching back to automatic mode.
This functionality is not available in LISTSERV Lite.
There are two levels of automatic address probing available in LISTSERV.
This functionality is not available in LISTSERV Lite.
Active address probing was introduced in LISTSERV 1.8c, for two reasons: first, to enhance subscription renewal functionality so that no "CONFIRM listname" response was required from subscribers in order to stay subscribed, and second, to enhance the ability of the auto-deletion feature to handle bounces that can't be parsed into something LISTSERV can recognize.
"Renewal= ...,Probe" activates this enhanced bounce processing feature, whereby subscribers are probed at subscription renewal time using the PROBE1 mail template. The "Probe" option makes subscription renewal passive rather than reactive; no "CONFIRM listname" response is needed from the user. In fact, the desired response from the user is to discard the message and do nothing, making the process very simple. LISTSERV also probes addresses that return mail delivery errors, and probe messages have a special signature in the return address that allows LISTSERV to uniquely identify any bouncing address, without having to understand the bounce itself.
If the probe bounces, LISTSERV first sends the PROBE2 template with a copy of the bounce, to show the user (if the account actually works in spite of the bounce) what garbage his mail system is sending people. LISTSERV then schedules a new probe for the next day, or deletes the user immediately, depending on the auto-delete policy. Every failure triggers a new daily probe until the user gets deleted or the problem gets fixed. The user can also save his subscription manually by sending a CONFIRM listname command (this is explained in PROBE2). This doesn't solve the underlying problem, so eventually the user should get tired of confirming in an emergency and notify his system administrators that the system is generating bounces saying (for instance) "Your message was registered at the MORONICUS mail gateway. Press F1 for more information" that cause the problem in the first place.
When used together with "Auto-Delete= ...,Full-Auto", the probe option deletes all delivery errors from bounced probes, even if LISTSERV can't understand the error. This means the list owner never ever has to see a single bounce from a probed address! Hurray! :-) The list, however, is kept clean because bad addresses are always detected. In fact, the biggest risk is that the users of the MORONICUS mail gateway will be deleted even though they do get their mail.
This being said, note carefully that all errors bounced by non-compliant mail hosts to the wrong address, and non-probe errors that are sent to the owner-listname address but are not in a format that LISTSERV can parse, will still show up in your error mailbox. If the bounce goes to the wrong address, LISTSERV never sees it and cannot probe it. If the error goes to the correct address (owner-listname) but isn't specific enough for LISTSERV to understand, while LISTSERV will be able to see it, it still won't be able to probe it. Finally, in some cases where the error is so vague (or constructed in a complicated manner that defies LISTSERV's attempts to parse it) the error may be passed to the LISTSERV postmaster, instead of to the list owner, for disposition, even if it was correctly returned to the owner-listname address.
Yet even with these restrictions, the author saw an error queue of 1300 errors/day shrink to under 50 errors/day by applying the ",Probe" parameter to seven high-volume lists, which in his opinion was much more acceptable.
4.9.2. Passive address probing
This functionality is not available in LISTSERV Lite.
Passive address probing is available beginning with LISTSERV 1.8d. In effect passive probing is very similar to active probing, but it is not tied to subscription renewal. Passive probing is enabled by default for small lists (e.g., <1K subscribers) but not for large ones due to the fact that passive probing does cost additional resources and large lists are often used for one-shot mailings where it is simply not effective to use those resources to probe addresses that will not be used a second time.
Passive probing operates by turning a certain percentage of your regular list messages into transparent probes that look like a normal message but also double as a probe, rather than sending out the explicit PROBE1 template as in active probing. You enable (or tune) passive probing by adding a ",Probe(xx)" parameter to the Auto-Delete= keyword setting. For instance,
Auto-Delete= Yes,Full-Auto,Probe(30)
where "30" is the number of days to wait between probes for any given user (the default is Probe(30). Subscribers with working mail systems will not see any difference, subscribers with flaky mail systems will occasionally receive a message showing that their mail bounced and saying that they should report the problem to their ISP, and of course plain bad addresses will go away.
In order to disable passive probing you set the probe parameter to 0, i.e.,
Auto-Delete= Yes,Full-Auto,Probe(0)
If you have users who for whatever reason should not be probed, you can deactivate passive probing (and any other renewal you have set for the list) with the SET userid@host NORENEW command.
4.10. Subscription confirmation
For lists coded "Subscription= Open", you can require confirmation on all new subscription requests, thus ensuring that LISTSERV has a clear mailing path back to the subscriber. In the past, a user could send a subscription for an open subscription list to LISTSERV, which upon acceptance would immediately start sending the user list mail. If the user was located behind a "broken" or one-way gateway, this produced immediate bounced mail until the list owner noticed and deleted the subscription. Note that requiring confirmation at the time of subscription does not guarantee that the clear mailing path will continue to exist permanently.
"Subscription= Open,Confirm" causes LISTSERV to send a Command Confirmation Request to the potential subscriber before actually adding the user to the list. The subscriber is requested to reply to the request by sending a validation "cookie" back to LISTSERV (this "cookie" being the hexidecimal number pulled from the subject line).
The Command Confirmation Request, while straightforward, has the potential to cause confusion if users do not read carefully the instructions that make up the request. LISTSERV expects confirmation codes to be sent in a specific way because some mail gateways add lines to the header of the message that LISTSERV doesn't understand. If a user forwards the request back to LISTSERV, or creates a new mail message to send the 'cookie' back, it usually will not work correctly. The sequence should thus be as follows:
1. SEND the subscription request to LISTSERV.
2. REPLY to the confirmation request ('ok')
3. SEND the confirmation code (if necessary) ('ok 23CBD8', for example)
4. Send mail to the list owner (not the list) if the subscription request fails after step 3.
Note that if a list owner adds a user manually, the confirmation process is bypassed.
You can code subscription renewal into your lists. This is one method to keep lists "pruned down" and avoid having large lists that are actually distributing mail to only a fraction of the users. For instance, you may have a number of subscriptions set to NOMAIL for one reason or another. NOMAIL user(a) may have forgotten that he has a subscription; user(b) may have set NOMAIL instead of unsubscribing; user(c) may no longer exist because she graduated or no longer works for the service provider; you may have set user(d) to NOMAIL because of recurrent mail delivery errors. Requiring a periodic confirmation of subscriptions is therefore a reasonable course of action for large, non-private lists.
Subscription renewal is disabled by default. If you do not want subscription renewal, or if you wish to turn it off, simply do not include a "Renewal=" keyword in your list header.
To add subscription renewal, you add the following keyword to the header of your list:
* Renewal= interval
or
* Renewal= interval,Delay(number)
or
* Renewal= interval,Delay(number),Probe
where interval is a period of time such as Weekly, Yearly, 6-monthly, or something similar, and Delay(number) is an integer corresponding to how many days LISTSERV will wait for the renewal confirmation to arrive. (See "Renewal=" in Appendix B for more information on renewal and delay periods; see chapter 4.8.2., above, for more information on the "Probe" parameter.) Note that you can have multiple interval parameters; again, see the entry for "Renewal=" in Appendix B for details.
The confirmation request mailing asks the subscriber to send the command CONFIRM listname back to LISTSERV. If the subscriber does not do so within a certain length of time, LISTSERV automatically deletes the subscription. The default delay time is 7 days. If you wish to use the default delay time, it is not necessary to code ",Delay(7)" into your Renewal parameters.
Note: You may wish to increase the delay time to accommodate users whose subscriptions expire over holidays (such as the Christmas/New Year's week) in order to avoid accidental deletions. Also, be aware that confused subscribers can and will send the CONFIRM command back to the list, rather than to LISTSERV. LISTSERV's default filter will catch these commands and forward them to the userid(s) defined by the "Errors-To=" keyword.
It is possible to waive subscription renewal for certain users (such as list owners, editors, redistribution lists, etc.). In order to do this, simply issue the command
[QUIET] SET listname NORENEW FOR net-address
to LISTSERV. It is most advisable to do this in the case of redistribution lists, as they broadcast the renewal notice to their users, who a) cannot renew the subscription and b) become very confused when they see the notice, often sending "what does this mean?" mail to the list.
You can also issue the CONFIRM command for a subscriber:
[QUIET] CONFIRM listname FOR net-address
Note that "active" users of the list (that is, people who post regularly to the list) will never be required to renew their subscriptions, nor (if subscription "probing" is enabled) will they ever be sent the passive subscription probe. LISTSERV presumes that such users have valid addresses and does not require a renewal confirmation from them.
4.12. Using the SERVE command when a user is "served out"
If a user sends more than 50 consecutive invalid commands to LISTSERV, LISTSERV automatically serves that user off so that further commands from that user will be ignored. Should a user become served off in this fashion, it is possible for the list owner or any other user to issue a SERVE net-address command to restore that user's access. As with all other LISTSERV commands, the SERVE command is sent to LISTSERV.
Please note that the number of invalid commands allowed before the user is served off was increased from 20 in 1.8b to 50 in 1.8c and later.
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.
5. Setting Subscription Options For Subscribers
5.1. How to review current subscription options with QUERY
The syntax is similar to the subscriber's method of reviewing his options, except that the list owner must specify for whom the options are being checked.
Query listname FOR userid@host
Note that it is possible to use wildcards in the subscriber address. For instance,
Q LSTOWN-L FOR J*@UBVM*
will return option listings for subscribers such as JIMJ@UBVM, JOHN@UBVMS.CC.BUFFALO.EDU, etc. This can be handy if you are searching the list for someone whose subscription address differs from the address you are given in an error report (see the examples, above, in "Dealing with bounced mail").
Using the WITH qualifier, you can also query a list for users who have a specific option set. For instance, you might want to know which users are set to NOMAIL. Send the command
Q listname WITH NOMAIL FOR *@*
and LISTSERV will return a list of those users. It is also possible to query a list for multiple options:
Q listname with DIGEST CONCEAL FOR *@*
will return a list of those subscribers who have set their subscription to DIGEST and also to CONCEAL.
Version 1.8c adds the ability to query users by the list topics they are subscribed to. For instance:
Q listname WITH TOPICS: ADMIN FORUM FOR *@*
shows all members subscribed to both the ADMIN and FORUM topics.
Q listname WITH TOPICS: -ADMIN FOR *@*
shows all members who are not subscribed to the ADMIN topic.
Q listname WITH TOPICS: ADMIN -TEST FOR *@*
shows all members who are subscribed to the ADMIN topic but not to the TEST topic.
5.2. How to set personal subscription options for subscribers
Again, the syntax is similar to the subscriber's method.
SET listname option FOR userid@host
or
QUIET SET listname option FOR userid@host
Setting this option to Mail indicates that the subscriber will receive mail from the list. NOMail is the complementary command that stops mail but leaves the user subscribed to the list. (NOMail is often a good compromise for users who are leaving the office for vacation or on extended business trips, and who don't want a full mailbox on their return.) The format of the messages received is controlled by the DIGEST/INDEX/NODIGEST/NOINDEX options (see below).
Causes the subscriber to receive one posting per digest cycle (typically daily) rather than individual messages as they are processed by LISTSERV.
In version 1.8b and later, the MAIL/NOMAIL option was isolated from DIGEST/INDEX. The MAIL/NOMAIL option controls whether messages should be delivered, and the DIGEST/INDEX/NODIGEST/NOINDEX option controls the format in which messages should be delivered. Thus, switching to NOMAIL and back to MAIL now preserves the digest/index/normal delivery setting. To provide as much compatibility with the old syntax as possible, the four options operate as follows:
· DIGEST: enable digest delivery mode (which negates INDEX), enable mail delivery. No change from version 1.8a.
· INDEX: enable index delivery mode (which negates DIGEST), enable mail delivery. No change from version 1.8a.
· NOMAIL: disable mail delivery. No change from version 1.8a.
· MAIL: restore mail delivery, without altering the digest/index/normal delivery setting (new behavior). For compatibility with 1.8a, if mail delivery was already active, the MAIL option negates INDEX/DIGEST. Thus, a user going from NOMAIL to MAIL will keep his previous delivery options, whereas a user going from DIGEST or INDEX to MAIL will in fact deactivate index/digest mode.
To revert from digest/index subscription mode to normal delivery, you can use either the MAIL option as before, or the NODIGEST/NOINDEX option. The NODIGEST and NOINDEX options were actually present in versions 1.7f and 1.8a, as synonyms for the MAIL option. In other words, you can update your instructions to indicate that the DIGEST/INDEX options are negated by the NODIGEST/NOINDEX options, even if you are still running an older version of the software.
Note that for backward compatibility, the command SET listname MAIL sent by a user who is set to DIGEST but not also set to NOMAIL will cause the user to be set to NODIGEST (the behaviour is identical for users set to INDEX but not to NOMAIL). SET listname MAIL sent by users set to DIGEST/NOMAIL or INDEX/NOMAIL will simply remove the NOMAIL setting and leave the user set to DIGEST or INDEX as the case may be.
Note that in extreme cases, subscribers using the DIGEST option may receive more than one digest per cycle if the digest limit is reached before the end of the cycle.
Toggles MIME functions on and off. Currently this is only useful if the user has a mail client that supports MIME digests. Note that users who send their SUBSCRIBE command using a MIME-compliant agent will have this option set automatically unless "Default-Options= NOMIME" is specified for the list.
In future versions, this toggle may control other MIME functions.
5.3.4. INDex/NOINDex
Causes the subscriber to receive one posting per digest cycle containing only an index of subject topics for all messages during that cycle. See the section on DIGEST (above) for further information.
These three command words control the level of acknowledgment the subscriber receives when posting to the list. ACK causes LISTSERV to send a short confirmation message to the subscriber when the post has been received and distributed. NOACK disables the confirmation feature for the subscriber (although BITNET subscribers will receive a short interactive message on their terminal). For BITNET subscribers, MSGack provides the same information as ACK via interactive messages.
5.3.6. Options for mail headers of incoming postings
By specifying one of the following command words, the subscriber can control the amount of mail header information prepended to list mail. The syntax is SET listname headertype, where headertype is one of the following:
|
FULLhdr |
"Full" mail headers (default) (formerly FULLBSMTP) |
|
SHORThdr |
Short headers (formerly SHORTBSMTP) |
|
IETFhdr |
Internet-style headers |
|
DUALhdr |
Dual headers, useful with PC or Mac mail programs |
|
FULL822 |
"Full" RFC822 mail headers |
|
SHORT822 |
Short RFC822 mail headers |
|
SUBJecthdr |
"Full" RFC822 mail headers (like the default), except that LISTSERV adds the list's default subject tag to the subject line of mail coming from the list. To turn this off, simply set another mail header option. |
Note: do not use FULL822 or SHORT822 unless debugging specific problems or unless directed by L-Soft. Use of these options can seriously slow performance as they force LISTSERV to generate a separate "envelope" for each user so set. FULL822 and SHORT822 are obsolete but remain available for compatibility with certain older BITNET mailers still in use.
Quite a few non-technical users are relying on non-RFC822 user interfaces for reading their mail. Quite often these user interfaces are user-friendly, quality implementations of a proprietary mail protocol which the users are proficient with, but which happens not to lend itself to bidirectional mapping to RFC822. The users may have a good reason for using this particular program, and they complain that it is not always clear what list the postings come from, or who posted them. Other users have very primitive mail programs which do not preserve the original RFC822 header and may not even have a "message subject" concept. The user knows which list the message came from, but not who posted it, making private replies impossible.
The DUALHDR (minimum abbreviation: DUAL) header option is provided to help solve this problem. Dual headers are regular short (SHORThdr) headers followed by a second header inside the message body. This second header shows what list the message is coming from ('Sender:'), the name and address of the person who posted it ('Poster:'), the poster's organization, if present, and the message subject. The date is not shown because even the most primitive mail programs appear to supply a usable message date.
The SUBJECTHDR (minimum abbreviation: SUBJ) header option is provided for users who want to see a "tag" in the subject line of their incoming list mail that indicates where the mail is coming from (e.g., to activate a filter in their mail program to drop the message into a specified notebook). Note that if you have SHORT headers (or any other header option) set, setting your option to SUBJecthdr will automatically change you to FULLHdr, as subject tags require full headers. Also, subject tags are not generated for messages sent without a RFC822 "Subject:" header.
Generally, users will be well-served by the FULL header option, which is the default.
Documented Restriction: The use of the SHORTHDR or DUALHDR options will break messages that depend on MIME encoding, because these options strip the RFC822 headers that identify the message as a MIME message. SHORTHDR and DUALHDR were designed for the non-MIME mail clients which prevailed in LISTSERV's early history. As most mail clients today support MIME, the use of these options is now deprecated.
5.3.7. Putting the list name into the Subject: field
To do this, use the SUBJecthdr personal option as explained in the previous section. To set this option by default for new subscribers, include it in the Default-Options= keyword setting for your list (see 5.4, below). To set it for existing subscribers, use the SET command.
Occasionally, a subscriber may not want his presence to be known to someone else making a casual REView of the list. Subscribers may choose to "hide" their subscription from the REView command by using the CONCEAL command. Conversely, a subscriber may choose to remove this restriction by issuing the NOCONCEAL command. Note that the list owner can always obtain a list of all subscribers, both concealed and unconcealed, by issuing the GET listname (NOLock) command, or by issuing a QUERY listname WITH CONCEAL FOR *@* command.
This option controls whether or not the subscriber will get a copy of his or her own posts back from the list after they are processed. Generally, if a subscriber's mail program is configured to file copies of the subscriber's outgoing mail, or if the subscriber has one of the acknowledgment options (ACK/MSGack) enabled, this option should be set to NOREPro. If, on the other hand, the subscriber is set to NOACK and doesn't keep a copy of outgoing mail, this option should probably be set to REPro.
Topics are not available in LISTSERV Lite.
If list topics are enabled, this option allows the subscriber to specify which topics he or she will receive. The syntax of a SET TOPICS statement is significantly different from that of the other options. See Chapter 6, Section 7, for more information on this syntax.
This option may be set only by list owners or the LISTSERV maintainer. It is not available in LISTSERV Lite.
A subscriber set to NOPOST may not post to the list. NOPOST gives the individual list owner the ability to serve out abusive or obnoxious posters without having to add such users to the list's "Filter=" setting. Subscribers set to NOPOST will still receive list mail – they just won't be able to post mail to the list.
The list owner or LISTSERV maintainer may issue the
SET listname POST FOR userid@host
command to reverse a previously-set NOPOST.
Note for peered lists: NOPOST must be set globally or a user can bypass the setting by simply posting to another peer. Thus you must add the user manually to the other peers and then set the user to NOMAIL as well as NOPOST on the peers.
Setting NOPOST for a user cancels any previous EDITOR or REVIEW setting for that user.
Note that list editors who are set to NOPOST will be able to approve messages but will then be told they cannot post to the list. The NOPOST subscriber option does override any Editor= or Moderator= definition in the list header, so be sure that your editors and moderators are set to POST.
This option may be set only by list owners or the LISTSERV maintainer, and is effective only on moderated lists. It is not available in LISTSERV Lite.
A subscriber set to EDITOR on an edited/moderated list may post directly to the list without a moderator's intervention. It is virtually identical to adding the subscriber's address to the "Editor=" keyword, but easier to manage. The only difference between the EDITOR option and the "Editor=" keyword, other than not being visible in the list header, is that the "Editor=" keyword also defines a (seldom used) access level class which can then be used in keywords such as "Review=". Thus, one could have a list with "Review= Editor", indicating that only the users listed in the "Editor=" keyword are allowed to review the list. The EDITOR option does not confer this privilege. Note that the EDITOR option is only meaningful on moderated lists.
The list owner or LISTSERV maintainer may issue the
SET listname NOEDITOR FOR userid@host
command to reverse a previously-set EDITOR.
Setting EDITOR for a user cancels any previous NOPOST or REVIEW setting for that user.
This option may be set only by list owners or the LISTSERV maintainer. It is not available in LISTSERV Lite.
When a subscriber is set to REVIEW, all postings from that subscriber are forwarded to the list editor or list owner for approval. Approval for these postings is always via the OK mechanism – there is no need to forward the posting to the list, simply reply to the approval confirmation with "OK".
Note that if a list is unmoderated, it is still possible to direct REVIEW postings to a specific person by adding an "Editor=" or "Moderator=" keyword to the list header.
The list owner or LISTSERV maintainer may issue the
SET listname NOREVIEW FOR userid@host
command to reverse a previously-set REVIEW.
Setting REVIEW for a user cancels any previous NOPOST or EDITOR setting for that user.
This option may be set only by list owners or the LISTSERV maintainer.
Enables or disables subscription renewal confirmation on an individual subscriber basis. Setting a subscription to NORENEW is particularly useful for exempting list owners, redistribution lists, and other subscriptions which should not or must not receive the confirmation request message from the renewal process.
The list owner or LISTSERV maintainer may issue the
SET listname RENEW FOR userid@host
command to reverse a previously-set NORENEW.
5.4. Setting original default options with the Default-Options= keyword
The list owner may specify original defaults for many subscriber options by using the "Default-Options=" keyword. This keyword takes regular SET options as its parameters. Examples include:
* Default-Options= DIGEST,NOREPRO,NOACK
* Default-Options= REPRO,NONE
You may have more than one "Default-Options=" line in your header, as needed.
Note that any default topics are set with the "Default-Topics=" keyword. See Appendix B for details on this keyword.
Also note carefully that your existing subscribers are not affected by any change to the Default-Options= keyword. This keyword sets initial options only for people who subscribe after it is defined. If you want to update your existing subscribers to the Default-Options settings, you must use the SET command with a wildcard (i.e., FOR *@*) to do so.
6. Moderating and Editing Lists
Please note that much of this chapter is subjective, based on personal experiences during several years of list ownership, and may not necessarily match your own philosophy of "the way things ought to be." The following sections are offered as one way to run a list, and the author does not mean to assert that the one way offered – his way – is the only way. As we seem to say so often, "your mileage may vary."
6.1. List charters, welcome files, and administrative updates
One of the most important things you can do as a list owner is make it clear from the outset what policies are in place and will be enforced if it becomes necessary. Due to a potential for controversy, for instance, some lists may require a formal "list charter" by which all subscribers must agree to abide before they are allowed to subscribe. Other lists may be able to get by with a simple welcome file (see below) that spells out basic netiquette, polices on "flaming" and commercial posts, and anything else that seems appropriate (such as how to get in touch with the list owner in an emergency, where the list archives are located, etc.).
It is particularly important on open subscription lists that you make a concerted effort to remind your subscribers on a regular basis of the policies you have set for your list, as well as any other information they need in order to make best use of your list. If you have a great deal of subscriber turnover, it may be necessary to do this every few weeks. You may decide to put together a quarterly or semi-yearly post for more stable lists. Ensure that the subject line is indicative of what the administrative posting is so that there is no question as to whether or not you posted it (even if subscribers don't read it). (Note that with LISTSERV 1.8c or later you can use the PROBE1 mail template form and automatic address probing to do this automatically.)
6.2. The role of the list owner as moderator
By default, the list owner becomes a moderator of sorts, even if the list in question is neither edited nor officially moderated. This means that, as a list owner, you must be prepared to maintain order if it becomes necessary. At the same time, you must moderate yourself so that you do not alienate users and cause your list and/or host institution to suffer as a result. Thankfully, mailing lists have generally enjoyed relative peace and quiet over the years in comparison to newsgroups, but mailing lists have unique problems of their own.
Lists dedicated to controversial subjects are more likely to become arenas for "flame wars" between subscribers with hard-held and differing opinions than those dedicated to the discussion of popular software packages, but this does not mean that the latter are immune any more than it means that the former are constantly plagued by flames. The example set by you as list owner and as a participating subscriber to the list is perhaps the most important factor in whether or not your list becomes a site known for strife and controversy. In other words, if you appear not to care about whether or not discussion is on topic and/or civilized, no one else will, either. Yet if you become a policeman – the other end of the spectrum – no one will want to subscribe or participate for fear of your wrath. Either way, your list is unlikely to last very long.
The middle ground is, as in most things, the place to be when administering a list. Some call this "firm but fair," letting things go pretty much as they will but stepping in with a wry or gently chiding remark from time to time when exchanges get heated. And they will! Software discussion lists are particularly bad about this when new subscribers ask "frequently-asked questions" (FAQs) and veteran subscribers respond in exasperated fashion with "RTFM!" (Read The Fine Manual) and similar nasty retorts. Good list owner practice at this point is likely to be a good-natured reminder from you that flames belong in private mail, pointing out that new subscribers have no way of knowing that the particular questions they ask have been asked (and answered!) n random times before, and possibly adding a link to the list's archives (if they are available on the web) or instruction on how to use the SEARCH command to look for answers before asking.
Finally, if your mailing list has an international audience, you must be careful to account for language problems and cultural differences. You will need to decide which languages are allowed or not allowed on the list; this should be mentioned shortly in the list abstract or welcome message. Unless the list is specific to one country or is explicitly for discussion in a specific language, the official language will probably be English. As your list grows, some subscribers may object to this decision, arguing that people who have trouble expressing themselves in English should be allowed to use their own language, with the understanding that many people will be unable to understand what they are saying. As the list owner, it will be your call. Usually, the best compromise is to start a separate list for discussions in the new language. However, you must be careful in wording your decision. In multi-lingual cultures, it is usually considered a courtesy to use the other person’s language. It is certainly considered rude for people to demand that everyone else should speak their language. Thus, if your native language is English, you will be in a delicate position. To avoid a flame war, you will want to make sure that your decision does not come out as a unilateral demand. Politely suggesting a separate list, and tolerating an occasional non-English posting when the poster genuinely cannot speak English, is often the best course of action.
Another possible source of flame wars is unintended rudeness. It is easy to forget that non native speakers are making an effort every time they post something to the list. People will make mistakes, sometimes appearing rude when they did not mean to, simply because they used the wrong word. Another cause of apparent rudeness is cultural difference. Things which are perfectly normal in one culture can be insulting in another. For instance, ad hominem attacks are perfectly acceptable in some countries. Conversely, referring to other people by their first name ("As Peter said in his last message, ...") can be downright insulting in some cultures, where anything short of the full title is at best condescending. But, of course, in other countries the use of the full title is considered sarcastic... There is no middle ground here, because there are too many conflicting cultures and too many languages. The only way to successful cross-cultural communication is through the tolerance of other people’s cultural habits, in return for their tolerance of yours.
6.3. The role of the list owner as editor
Edited lists are generally used for the purpose of "full moderation" or for refereed electronic journals or the like, for which random postings from subscribers and/or non-subscribers may not be welcome for general distribution. This places the list owner and any editors in the position of being full-time monitors of what is and is not allowed to go through to the list.
A word of warning to potential list editors: Rules on the Internet are not set in stone. Some people will insist on their right to post without what they will term "censorship" by the list editor. Some will become upset to the point of threatening to report you to your local computing center administrators for abridging their freedom of speech, or (in the U.S.) even threatening to sue your institution and you personally for an abridgment of their First Amendment rights. It is therefore vitally important to you that you keep a "paper trail" of such complaints in the event that threats become reality and you are asked about them. This common practice in the business world should be common practice in list ownership as well.
Freedom of speech and copyright issues on the Internet have not yet been tested in the courts as of this writing. These are both areas in which list editors and list owners in general must tread carefully. Always document any problems you may have in these areas.
6.4. Setting up an edited list
Please note that the "Moderator=" keyword and moderation "load-sharing" are not available in LISTSERV Lite.
Note that L-Soft currently recommends that edited lists be coded with the ",Confirm" parameter to the "Send=" keyword, in other words:
* Send= Editor,Confirm
or
* Send= Editor,Hold,Confirm
This will help prevent malicious users from forging mail from an editor address in order to get around your moderation settings, by telling LISTSERV to require an "OK" confirmation whenever it receives a posting from an editor address. The "OK" request goes to the editor address, so the forger is stymied.
Note also that some vacation programs and broken mailers have recently been "reflecting" mail back to lists in such a way that the mail appears to be coming from the editor’s address (and the mail therefore gets through). Setting the ",Confirm" option will stop this phenomenon as well.
When confirmation is required for Editor postings, please note that the confirmation request always goes to the Editor who posted, even if you have moderation "load-sharing" configured as noted below. Moderation "load-sharing" applies to postings from general users only.
Should you decide that an edited list is the way to go for your particular situation, you need only add the following lines to your list header file:
* Send= Editor
* Editor= userid@some.host.edu
where "userid@some.host.edu" should be replaced with the network address of the person who will be handling submissions to your list.
There can be multiple editors as well (and multiple Editor= lines, if desirable), and they do not have to be list owners:
* Send= Editor
* Editor= alex@reges.org,joe@foo.bar.edu
* Editor= tony@tiger.com
Normally, LISTSERV forwards submissions only to the first editor defined by the "Editor=" keyword. In the case above, all submissions would go to the primary list owner.
NOTE CAREFULLY that the first editor CANNOT be an access-level; e.g., you cannot use the notation "Editor= Owner" to define the first editor. LISTSERV requires that the primary editor of a list must be the e-mail address of a real person.
Note also that this does not apply to second and subsequent editors. For instance, in order to allow subscribers to post directly but have non-subscriber posts sent to an editor for approval, you can code something like:
* Send= Editor
* Editor= alex@reges.org,(MYLIST-L)
On a high-volume list, LISTSERV allows you to share the editing load via the "Moderator=" keyword. By default, this keyword is set to the same value as the first editor defined by "Editor=". When you define more network addresses with the "Moderator=" keyword, LISTSERV sends submissions to each moderator in sequence. The difference between the "Editor=" and "Moderator=" keywords lies in the fact that while any editor can post directly to the list, only moderators receive the forwarded submissions from non-editors.
Here is an example of a list with both Editor= and Moderator= keywords defined:
* Send= Editor
* Editor= joe@foo.bar.edu,tony@tiger.com,kent@net.police.net
* Moderator= kent@net.police.net,joe@foo.bar.edu
This list will "load-share" the editing duties between Kent and Joe. Tony is able to post directly to the list, but will not receive forwarded subscriber posts for editing.
Note that whereas an Editor is not required to be a Moderator, a Moderator should always be listed as an Editor. LISTSERV currently compares the contents of the "Editor=" and "Moderator=" keywords and consolidates the two sets of parameters if necessary, but coding lists this way is not considered good practice and the "compare/consolidate" feature may be removed in a future upgrade.
Beginning with 1.8c, if the parameter "All" is coded before any moderator addresses, LISTSERV will send copies of all postings to all moderators, any of whom may approve the message. An example of this would be
* Moderator= All,kent@net.police.net,joe@foo.bar.edu
Assuming "Send= Editor, Hold", once a message is approved by one of the moderators, any other moderator attempting to approve the same message will be told that an identical message has already been posted to the list.
If "Send= Editor" (e.g., without "Hold"), please note that if a note is appended or prepended to the edited post, or if the body of the post itself is edited (that is to say, if the body of the approved message is changed), duplicates are possible. Thus it is important that the moderators of any list set up this way pay close attention to whether or not the posting has already been approved by another moderator.
6.5. Submitting subscriber contributions to an edited list
By default, LISTSERV forwards subscriber contributions to the Moderator/Editor with the following paragraph prepended to the message body:
This message was originally submitted by JOE@FOO.BAR.COM to the ACCESS-L
list at PEACH.EASE.LSOFT.COM. If you simply forward it back to the list, using
a mail command that generates "Resent-" fields (ask your local user support or
consult the documentation of your mail program if in doubt), it will be
distributed and the explanations you are now reading will be removed automatically. If on the other hand you edit the contributions you receive into
a digest, you will have to remove this paragraph manually. Finally, you should
be able to contact the author of this message by using the normal "reply"
function of your mail program.
------------------ Message requiring your approval (25 lines) ----------------- [message body]
If you leave this paragraph prepended to the message, LISTSERV will strip it off when it processes the message and to all intents and purposes the message will appear to have come directly from the original sender. Warning: If your mail program or client does not generate "Resent-" fields, the forwarded postings will appear to be coming from you rather than from the original sender. See Section 6.6 for an alternative if your mail program does not generate these fields.
(If you leave the editor-header paragraph on the message, make sure that your mail client or mail server does not insert quoting characters (e.g., ">") at the beginning of all of the lines in the message when you use the forwarding function of your mail program. If this happens then the editor-header will not be stripped from the message.)
When you are ready to edit and/or submit the contribution to the list, simply use the "Forward" function of your mail client. You can make any changes you feel are appropriate to the message body, but be sure to read sections 6.2 and 6.3 above before deciding to do so.
6.6. Message Approval with Send= Editor,Hold
LISTSERV includes an optional mechanism allowing you to simply "ok" messages which are then posted with all the correct headers. This option is targeted mainly at list moderators who just approve/reject messages, as opposed to people who actually edit the content of messages. The option is also a good choice if you have a mail client that does not insert "Resent-" header lines into forwarded mail.
To activate this feature, code your list "Send= Editor,Hold" and be sure that you have defined at least one editor who will be in charge of approving the messages. A copy of the message on "hold" is sent to the editor with minimal instructions (in order to avoid adding a long message before the text needing approval each time).
To approve a message forwarded to you with "Send= Editor,Hold", simply reply to the approval request and type "OK" as the body of your reply. LISTSERV will normally pick up the confirmation request number from the subject line. If there is a problem, LISTSERV may ask you to resend the approval confirmation along with the number. For instance,
OK 6A943D3C
If the message has been in the spool longer than the time-out period (LISTSERV holds these jobs for a minimum of 7 days), you will receive notification that the confirmation number does not match any queued job. If you need to increase the time-out period, you can set a value for the "Confirm-Delay=" list header keyword that is greater than 168h, but please read the section on "Confirm-Delay=" in Appendix B before doing so.
If you do not want the message to be forwarded on to the list, you need not do anything. The message will expire automatically at the end of the time-out period and will be deleted from the queue.
List topics are not available in LISTSERV Lite.
List topics provide powerful "sub-list" capabilities to a list. When properly set up and used, topics give subscribers the ability to receive list postings in a selective manner, based on the beginning of the "Subject:" line of the mail header. It is important to note the following points about topics:
· Topics are best employed on moderated lists. This makes it possible to review the "Subject:" header line to make sure that it conforms to one or more of the topics defined for the list before you forward the post to the list. Not only does this help catch simple errors (such as misspellings of the topic), but it also allows the moderator to add a topic into the subject line if one is not already there.
· If you employ topics on unmoderated lists, your subscribers must be well-educated in their use. Otherwise, there is no point in using them. Messages that do not conform to a specified topic are lumped into the reserved topic "Other" and are distributed only to subscribers who have explicitly defined "Other" as a topic they wish to receive. Therefore some subscribers will receive the message and some won't, and it is problematic as to whether the message will actually reach the entire audience for which it is intended.
· It is important to note that topics are active only when the subscriber's subscription is set to MAIL. All messages posted to the list, regardless of topic, are included in the digest and/or index for the list (if available) because the same digest/index is prepared and sent to all the digest/index subscribers. Similarly, all messages posted to the list are archived in the list's notebook logs (if available), making it possible for subscribers to retrieve postings in topics they are not set to receive normally.
The basic keyword syntax for defining list topics in the list header file is:
* Topics= topic1,topic2,...topic21
And the basic syntax used to set topics for users once they have been defined is:
SET listname TOPICS: xxx yyy zzz for userid@host
where xxx, yyy, and zzz can be:
· A list of all the topics the subscriber wishes to receive. In that case these topics replace any other topics the subscriber may have subscribed to before. For instance, after 'SET XYZ-L TOPICS: NEWS BENCH', the subscriber will receive news and benchmarks, and nothing else.
· Updates to the list of topics the subscriber currently receives. A plus sign indicates a topic that should be added, a minus sign requests the removal of a topic. For instance, "SET XYZ-L TOPICS: +NEWS -BENCH" adds news and removes benchmarks. If a topic name is given without a + or - sign, + is assumed: "SET XYZ-L TOPICS: +NEWS BENCH" adds news and benchmarks. The first topic name must have the plus sign to show that this is an addition, and not a replacement.
· A combination of the above, mostly useful to enable all but a few topics: "SET XYZ-L TOPICS: ALL -MEETINGS".
The colon after the keyword TOPICS: is optional, and TOPICS= is also accepted. The subscriber should not forget to include the special OTHER topic if you want to receive general discussions which were not labeled properly. On the other hand, if the subscriber only wants to receive properly labeled messages it should not be included. ALL does include OTHER.
With the "Default-Topics=" keyword, you can also set default topics for users that will be effective as soon as they subscribe to the list. For instance,
* Default-Topics= NEWS,BENCH,OTHER
would set the new user to receive topics NEWS, BENCHmarks, and any messages that are incorrectly labeled.
In LISTSERV 1.8d and following, you may get a listing of topics with the number of subscribers who have them set by issuing the command
REVIEW listname Short TOPics
(if you do not specify Short then the topic listing follows the list of subscribers in the review output). The following is a sample output (assuming you actually have topics enabled; if topics are not enabled then the TOPics option is ignored):
* Topic Subscribers
* ----- -----------
* Apps 1,411
* Backup 1,330
* Beta 951
* Bugs 1,416
* Comm 1,395
* Desktop 1,407
* Hardware 1,401
* Install 1,373
* Internet 1,002
* Network 1,399
* Wish 1,336
*
* "Other" topic 1,294
* Digest/index subscribers 1,384
See Appendix B under the Topics= keyword for more information on setting up and using list topics.
6.8. The <listname> WELCOME and <listname> FAREWELL files
When a user subscribes and signs off of a list, LISTSERV looks for list owner-supplied files called listname.WELCOME and listname.FAREWELL, respectively. If found, it sends the user a copy of the appropriate file in addition to its own administrative message. The WELCOME and FAREWELL files allow the list owner to send a more personal message to the user that can help set the tone for how the list is used. The WELCOME file may contain information about the list charter and netiquette rules, or be simply a message welcoming the user to the list. The FAREWELL file can be used to gather feedback about how the list is serving users.
6.8.1. Creating and storing the listname WELCOME and FAREWELL files
The procedure differs slightly on VM systems, but the following will work for unix, VMS and Windows systems:
1. Create the file. If you place a "Subject:" line at the top of the document, i.e., as the first line, LISTSERV will pick that line up and use it as the RFC822 "Subject:" header line. Otherwise, LISTSERV places a generic subject line in the mail message.
2. If the file contains special characters (i.e., non-7-bit ASCII characters) and you want to specify a character set for LISTSERV to include in the headers of the messsage, place a line such as:
Character-Set: ISO-8859-7
at the top of the message (or directly following the "Subject:" line if one is configured). The value "ISO-8859-7" is used here as an example only and should be replaced with the appropriate character set descriptor. If the file does not contain any non-7-bit ASCII characters, this line will be ignored.
3. Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the welcome file. If you have done this but can't remember the password, send LISTSERV a PW RESET command. You will then be able to add a new password with the PW ADD command.
4. Send the file to LISTSERV with a PUT listname WELCOME PW=XXXXXXXX command at the top of the file, just as if you were putting the list itself. Replace XXXXXXXX with your personal password.
The variation for VM systems is that the LISTSERV maintainer will have to create a fileid for the file before you can PUT it on the server. Contact the LISTSERV maintainer before trying to store your WELCOME and/or FAREWELL files.
Here is the format of a very simple WELCOME file. (Note that the FAREWELL file is created and stored in an identical manner.)
PUT SONGTALK WELCOME PW=XXXXXXXX
Subject: Welcome to Songtalk!
Welcome to Songtalk, the list for Songwriters talking about their work.
Your list owner is Susan Lowell (susan@example.com).
Figure 6.2. Sample WELCOME file.
6.8.2. Using the listname WELCOME file as a moderation tool
The WELCOME file should contain information geared toward orienting the new subscriber to several areas. The outline of a suggested WELCOME file follows:
1. The revision date for the WELCOME file.
2. A heading including the short and long names of the list, along with the name and network address of the primary list owner (or the list owner who handles subscription issues/problems).
3. Any warnings about the list that you want people to see immediately. These might include
a notice regarding the volume of mail subscribers can expect from the list
any newsgroups that echo the list
ftp sites for the list
where to send LISTSERV commands
where to find more in-depth information about the list (if you do a quarterly administrative posting or have a FAQ, where can it be found?)
4. A short abstract of what the list is all about. This might be a duplicate of the description you send to NEW-LIST.
5. The author includes the following paragraph at this point:
Users new to the use of L-Soft's LISTSERV are encouraged to read the online files LISTSERV REFCARD and LISTSERV GENINTRO, which can be obtained by sending the following commands in the body of a mail message to LISTSERV@LISTSERV.NET:
INFO REFCARD
INFO GENINTRO
6. Any guidelines for use of the list, including the list charter if you have one.
7. Information about the notebook archives and how to retrieve them.
8. Other list-specific information that might be important to new users.
Naturally, list owners should write WELCOME files based on their own experience of what is needed. A WELCOME file should not be static – review it once in a while to ensure that it continues to meet the needs of new subscribers.
6.8.3. Using the listname FAREWELL file as a feedback tool
The following FAREWELL file used to be used on the ACCESS-L list on PEACH.EASE.LSOFT.COM, and was intended as a tool to get feedback from users. When it was in use