L-Soft international, Inc.
Site Manager's Operations Manual
for
LISTSERV®, version 1.8c
December 12, 1996
Initial Release
r970128-001
The reference number of this document is 9612-UD-03.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of L-Soft international, Inc. For information on mirroring copies of this manual on your local system, please write to manuals@lsoft.com.

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

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:

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.

Reference Number 9612-UD-03

Table of Contents

Preface: LISTSERV Command Syntax Conventions

1. Who should read this book

2. Differences Between Architectures and Implementations


2.1. Differences between architectures
2.2. Differences between LISTSERV and LISTSERV Lite

3. Principles of Operation

4. How your organization can use LISTSERV® to its benefit


4.1. A practical example: Mike's Bikes

5. Configuring your LISTSERV® site

5.1. Site configuration files
5.2. What can be configured?
5.3. Files used by LISTSERV
5.4. Installing and configuring LISTSERV's WWW Archive Interface

5.4.1. Installing a web server
5.4.2. Installing the web archive interface script
5.4.3. Creating a subdirectory for the archive interface
5.4.4. Configure LISTSERV to activate the web archive interface
5.4.5. Customizing the web pages LISTSERV creates
5.4.6. Enabling individual lists

5.5. The "spam" detector

5.5.1. Spam quarantine
5.5.2. "Anonymous" spam alerts

6. LISTSERV Commands

6.1. General Commands

6.1.1. List subscription commands (from most to least important)
6.1.2. Other list-related commands
6.1.3. Informational commands
6.1.4. Commands related to file server functions
6.1.5. Other (advanced) commands

6.2. List Owner and File Owner Commands

6.2.1. File management commands (for file owners only)
6.2.2. List management functions

6.3. LISTSERV Maintainer Commands

7. Creating Lists

7.1. Basic list creation
7.2. Architecture-Specific Steps for List Creation

7.2.1. Unix: Creating required Sendmail aliases
7.2.2. VMS: Creating required PMDF aliases

7.3. A sample checklist for creating lists
7.4. Naming Conventions
7.5. List Header Keywords and what they do
7.6. Retrieving and editing the list -- some considerations
7.7. Adding a list password (obsolete in 1.8c)
7.8. Storing the list on the host machine
7.9. Fixing mistakes
7.10. A sample list header file
7.11. Deleting a list
7.12. How to set up lists for specific purposes

7.12.1. Edited lists
7.12.2. Moderated lists
7.12.3. Semi-moderated lists
7.12.4. Self-moderated lists
7.12.5. Auto-responders
7.12.6. Announce-only lists
7.12.7. Peered lists
7.12.8. "Super-lists" and "sub-lists"
7.12.9. "Cloning" lists

7.13. Migrating lists from one site to another

7.13.1. Migrating lists from one LISTSERV site to another LISTSERV site
7.13.2. Migrating lists from non-LISTSERV sites
7.13.3. Migrating lists from Sendmail alias files, databases, etc.

7.14. Adding HTML to a list header for the CataList

7.14.1. Update latency
7.14.2. Inserting a pointer to another list
7.14.3. Restrictions on the placement of equal signs

8. File and Notebook Archives

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.1. Creating a filelist
8.3.2. Adding FAC codes
8.3.3. Retrieving the filelist
8.3.4. Adding file descriptors to the filelist
8.3.5. File Access Codes (FAC) for user access
8.3.6. Deleting file descriptors from the filelist
8.3.7. Storing the filelist

8.4. The listname.CATALOG system on non-VM systems (new for 1.8c)

8.4.1. Adding files to the default SITE.CATALOG
8.4.2. Delegating file management authority
8.4.3. Creating a sub-catalog
8.4.4. Updating the sub-catalog
8.4.5. 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.8. File "Packages"
8.9. Where to find more information on File Archives
8.10. Notebook Archives

8.10.1. Setting up notebook archives for a list
8.10.2. Migrating old notebook archives to a new site
8.10.3. Deleting old notebook archives
8.10.4. Indexing existing notebook archives

9. Interpreting and Managing LISTSERV's log files

9.1. Logs kept by LISTSERV
9.2. Managing the logs
9.3. Interpreting the LISTSERV log

9.3.1. Expiring cookies
9.3.2. Releasing and reallocating a disk slot
9.3.3. Reindexing a list
9.3.4. Distributing a digest
9.3.5. Daily error monitoring reports
9.3.6. Processing mail for local lists
9.3.7. Administrative mail (X-ADMMAIL)
9.3.8. DISTRIBUTE jobs from remote hosts
9.3.9. Requesting "OK" confirmation for commands
9.3.10. Supervisory updates (SUPD jobs)
9.3.11. Global list of lists updates (LUPD jobs)
9.3.12. Valid "OK" confirmation received
9.3.13. Invalid "OK" confirmation received
9.3.14. User is already subscribed to a given list
9.3.15. User has included non-command text (e.g., a .sig file) in his mail to LISTSERV
9.3.16. Response to list owner or LISTSERV maintainer commands
9.3.17. Response to a user who tries to post to a held list (or one for which PRIMETIME is in effect)
9.3.18. Command forwarded via GLX from another host
9.3.19. Netwide DELETE (X-DEL jobs)
9.3.20. FIOC cache notifications

9.4. Interpreting the SMTP logs (Windows servers only)
9.5. Interpreting the SMTPS logs (Windows and VMS servers only)

10. Creating and Editing LISTSERV's Mail Templates

10.1. What LISTSERV uses mail templates for
10.2. The DEFAULT.MAILTPL file and how to get a copy
10.3. The $SITE$.MAILTPL file
10.4. Mail template format and embedded formatting commands
10.5. Creating and editing a .MAILTPL file for a list

10.5.1. The INFO template form
10.5.2. Other available template forms
10.5.3. Tips for using templates

10.6. Storing the .MAILTPL file on the host machine
10.7. Other template files: DIGEST-H and INDEX-H
10.8. Template files for the WWW archive feature
10.9. Using the DAYSEQ(n) function

10.9.1. Rotating bottom banner
10.9.2. Rotating FAQ via the PROBE1 template and "Renewal= xx-Daily"

11. The DISTRIBUTE Feature

11.1. Introduction
11.2. What is Relayed File Distribution?
11.3. A description of Relayed File Distribution Requests
11.4. Sample mail RFDR job

12. List Exits

12.1. What is a "list exit"?
12.2. List Exit Points

12.2.1. ADD/SUBSCRIBE exit points
12.2.2. DELETE/SIGNOFF entry points
12.2.3. SET exit points
12.2.4. General remarks

12.3. Local command definition (non-VM)

13. Distribution Features and Functions

13.1. Controlling the default level of acknowledgement to user postings
13.2. Controlling the maximum number of postings per day

13.2.1. Controlling total postings to the list per day
13.2.2. Controlling the number of postings per day from individual users

13.3. Controlling "prime" time
13.4. "Holding" and "freeing" a list

13.4.1. Automatic list holds
13.4.2. Manual list holds

13.5. Controlling the list digest feature
13.6. Setting up list topics

14. Error Handling Features and Functions

14.1. Defining error handling addresses
14.2. The auto-deletion feature
14.3. LISTSERV's loop detection feature

14.3.1. The anti-spamming filter

15. List Maintenance and Moderation Features and Functions

15.1. Setting up edited/moderated mailing lists
15.2. Restricting the size of messages posted to the list
15.3. Restricting the number of posts per user per day
15.4. Moving a list to a new location: the New-List= keyword

16. Security Features and Functions

16.1. First line of defense: The VALIDATE= keyword
16.2. Controlling subscription requests
16.3. Controlling the service area of the list
16.4. Controlling who may review the list of subscribers
16.5. Controlling who may access the notebook files
16.6. Controlling who may post mail to the list
16.7. The "OK" confirmation mechanism
16.8. Denying Service to Problem Users

16.8.1. The "Filter=" list header keyword
16.8.2. The "FILTER_ALSO" configuration file variable
16.8.3. The "SERVE" command

17. Subscription Features and Functions

17.1. Setting up subscription confirmation
17.2. Defining default options for subscribers at subscription time
17.3. Setting up subscription renewal

18. Other Features and Functions

18.1. Setting up national language mail templates
18.2. Translating control characters included in list mail
18.3. Communicating with list owners

18.3.1. The listname-REQUEST alias
18.3.2. The ALL-REQUEST alias
18.3.3. Configuration required for unix servers and VMS servers running PMDF

19. Special Functionality for ISP's

19.1. Directory quotas for individual lists

19.1.1. The QUOTA.FILE
19.1.2. Displaying quota information
19.1.3. Reloading quota information after making changes

19.2. Limiting the number of subscribers to a list

20. When things go wrong

21. Contacting L-Soft


21.1. Support
21.2. Sales
21.3. Manuals

Appendix A: System Reference Library for LISTSERV® version 1.8c
Appendix B: List Keyword Alphabetical Reference for LISTSERV® Version 1.8c
Appendix C: Site Configuration Keyword Reference
Appendix D: LISTSERV "Commands-Job" Feature and CJLI Interpreter
Appendix E: LISTSERV Database Functions
Appendix F: Sample Boilerplate Files
Appendix G: Related Documentation and Support
Appendix H: Acknowledgements

Table 5.1. LISTSERV site configuration variables

Figure 6.1. Sample output of an INDEX listname command.
Figure 7.1. A sample list header
Figure 7.2. A sample list header file for a list called MYLIST.
Figure 7.3. The edited list header file ready to be sent back to the server.
Figure 8.1. Sample filelist retrieved with (CTL option.
Figure 8.2. Adding a file descriptor to the filelist
Figure 8.3. This output will appear either if an attempt is made to change "Notebook=No" to "Notebook= Yes", or if an attempt is made to change the location where notebook archives are stored on the server, without using the list creation password to validate the PUT operation.
Figure 9.1. Sample CLEANLOG.REXX script for managing LISTSERV's log files.
Figure 9.2. Typical SMTP log for the SMTPL.EXE "listener"
Figure 9.3. Typical SMTPS log for the SMTPW.EXE SMTP "workers"
Figure 10.1. The default contents of the INFO template form of DEFAULT.MAILTPL.
Figure 10.2. Sample edited INFO template form.
Figure 10.3. Typical contents of a DIGEST-H or INDEX-H file.
Figure 10.4. Sample DIGEST output for a list with a DIGEST-H file.
Figure 14.1. A daily error monitoring report.
Figure 16.1 The editor-header for a list set to Send= Editor,Hold
Figure E.1. Sample database job skeleton
Figure E.2. Sample DATABASE OUTPUT
Figure E.3. Sample DATABASE LIST command output
Figure E.4. Sample SEARCH commands using complex document search arguments
Figure E.5. Sample SEARCH commands using date search arguments
Figure E.6. Sample SEARCH commands with continuation lines
Figure E.7. Sample use of "factorization"
Figure E.8. Sample SEARCH commands with keyword search clauses
Figure E.9. Sample SEARCH commands involving several databases
Figure E.10. Sample SEARCH commands involving phonetic match.
Figure E.11. Sample IN clauses
Figure E.12. Sample date clauses
Figure E.13. Comparison operators for WHERE clauses
Figure E.14. Logical (boolean) operators
Figure E.15. Sample WHERE clauses
Figure E.16. Sample document-search clauses
Figure E.18. Sample INDEX for a (fancy) Opera database
Figure E.19. Search/Index upon which the sample PRINT commands are based
Figure E.20. Sample PRINT of a document portion
Figure E.21. Sample PRINT of both document keywords and portions
Figure E.22. Syntax of the PRINT command
Figure E.24. Syntax of the FORMAT command
Figure E.25. Justification keywords for use with the FORMAT command
Figure E.26. Reserved keywords for use with the FORMAT command
Figure E.27. Sample FORMAT command
Figure E.28. Default format provided for "Notebook" databases
Figure E.29. Sample LIST command
Figure E.30. Example of valid and invalid use of the OUTLIM keyword
Figure E.31. Example of the use of the OUTLIM keyword

Site Manager's Operations Manual
for
LISTSERV®, version 1.8c
December 12, 1996
Initial Release
r970128-001

Preface: LISTSERV Command Syntax Conventions

Generally, parameters used in this document can consist of 1 to 8 characters from the following set:

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)
listname	name of an existing list
node	BITNET nodeid or Internet hostname of a BITNET machine which has taken care of supplying an ':internet' tag in its BITEARN NODES entry; or the fully-qualified domain name (FQDN) of an Internet host.
host	Generally the same as node, but often refers particularly to the fully-qualified domain name (FQDN) of an Internet host.
pw	a password containing characters from the set: A-Z 0-9 $#@_-?!|%
userid	Any valid RFC822 network address not longer than 80 characters; if omitted, the 'hostname' part defaults to that of the command originator

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

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. Who should read this book

This manual makes the following assumptions:

• You are a system administrator of a VM, VMS, unix, Windows NT or Windows 95 system (or in any case, a person with root-level administrative privileges) whose assignment it is to be the LISTSERV maintainer;
• You have already installed L-Soft's LISTSERV 1.8c on your system in accordance with the installation instructions that come with the package, and have it running;
• You have sufficient knowledge (or know where to find it) of your system mailer to fine-tune it without needing instructions from this manual.

In other words, we expect you already to be knowledgeable about the system on which you plan to install and run LISTSERV.

L-Soft international's LISTSERV software is designed to run on various platforms that have widely-differing configurations. Therefore it is not within the scope of this manual to describe in detail (for instance) how you can tune sendmail 8.7.3 under Linux for optimum performance with LISTSERV. However, general tips that could work on all systems will be offered within these pages.

Overall you will find that LISTSERV works much the same way on a unix workstation or a VMS minicomputer or an Intel Pentium machine running Windows NT as it has for years on VM mainframes. Where LISTSERV procedures do differ between platforms, we will detail those differences in order to minimize confusion.

2. Differences Between Architectures and Implementations

This chapter outlines differences between how LISTSERV is implemented on VM and non-VM machines, and the differences between LISTSERV and LISTSERV Lite.

2.1. Differences between architectures

In version 1.8c, LISTSERV running under VM differs in some regards from its counterparts on the other architectures. Here is a short list of these differences:

• Non-VM: Only a subset of the file server functions are available
• Non-VM: Certain rarely-used commands (e.g., SHOW STATS) are not available
• Non-VM: FUI (File Update Information) and AFD (Automatic File Distribution) are not available

However, note that 1.8c running on non-VM systems actually has about 98% of the functionality of the VM version, and nearly 100% of the functionality that people actually use day-to-day.

The File Server

There are actually two different file server systems in operation across the LISTSERV network. One is the original version running on VM, which includes the ability to create "filelists" (indexes) which point in turn to more files which can be stored on the server, and the AFD and FUI functions mentioned above. This file server system, while still quite powerful and easy to use, is unfortunately written in a non-portable language, making a complete rewrite from the beginning a necessity. There has been no change in the VM file server from 1.8b to 1.8c.

The second file server system currently in operation runs on the VMS, unix, and Windows ports of LISTSERV. This is in essence still a subset of the old system in which the LISTSERV maintainer creates entries in a SITE.CATALOG file for each file that will be made available to users. With the release of 1.8c, it is now possible for the LISTSERV maintainer to create sub-catalogs, which can be maintained by list owners or other responsible people. For more information, please see chapter 8 of this manual.

L-Soft is still developing LISTSERV's file server, which will eventually include a super-set of the original VM file server command set. Complete details are not available as of this writing, but pains are being taken to ensure that the most common commands will not change along the development path. This will help to keep a great deal of existing documentation that has been passed along the Internet from becoming obsolete overnight. The fully-developed file server will also include AFD (Automatic File Distribution) and FUI (File Update Information) in addition to other new functionality.

The WWW List Archive Search Interface

Due to the fact that named pipes are not implemented in Windows 95, this feature is not available in LISTSERV for Windows 95. The rest of the WWW List Archive interface is, however, available, and regular archive database searches can be executed via E-mail.

2.2. Differences between LISTSERV and LISTSERV Lite

LISTSERV Lite is LISTSERV running with a special license activation key (LAK) which is both free and perpetual, but is limited in its scope. With LISTSERV Lite, you can run up to 10 mailing lists as long as you do not derive a profit from this activity. Note also that LISTSERV Lite does not have all of the functionality of a full version--a list of the keywords and functions disabled in LISTSERV Lite follows this paragraph. For more information on the exact terms and conditions under which you may run LISTSERV Lite, please see L-Soft's World Wide Web site or contact L-Soft's sales department.

LISTSERV Classic Keywords disabled in LISTSERV Lite

Confirm-Delay	Default-Topics	Editor-Header	Exit
Files	Indent	Internet-Via	Language
List-Address	List-ID	Local	Long-Lines
Loopcheck	Mail-Via	Moderator	New-List
Newsgroups	NJE-Via	Peers	Prime
Renewal	Sender	Service	Sizelim
Stats	Sub-Lists	Topics	Translate
X-Tags

Note: the fact that the keyword is disabled only means that the default value cannot be changed. For instance, loop checking is still present, you just cannot control the details of its operation. On the other hand, if the default value is that the function in question is disabled (as is the case with "Peers="), then the function is actually gone. See Appendix B for more information on keyword defaults.

Comparison chart: LISTSERV Lite vs. LISTSERV Classic

Feature	LISTSERV Classic	LISTSERV Lite
Moderated lists	Yes	Yes
Moderation sharing	Yes	No
DISTRIBUTE	Yes	No
Peered lists	Yes	No
Topics (up to 11 different topics per list)	Yes	No
Validate keyword (provides security)	Yes	Yes
Filter keyword (screens mail)	Yes	Yes
Spam detector	Yes	Yes
Spam filter	Yes	No
Customization of mail templates	List based	Site based
Auto-delete	Yes, full featured	Yes, not full featured
Probe (never see a bounce again!)	Yes(*)	No
List exits	Yes	No
Networked mode	Yes	No
Subscription options:	RENEW: Yes	No
	EDITOR: Yes	No
	REVIEW: Yes	No
	NOPOST: Yes	No
All other LISTSERV subscription options:	Yes	Yes
File server functions	Yes, hierarchical	Yes, non-hierarchical
Database functions	Yes	No
WWW archive interface	Yes, with database interface	Yes, but no database functions

(*) The probe feature does not work with all MTAs (mail servers), or may only work with recent enough versions.

3. Principles of Operation

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, VMS™, unix® and Windows NT™, and has been released as shareware for Windows 95™.

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.

LISTSERV accomplishes its design goals very efficiently and very quickly. This is due primarily to its use of the proprietary DISTRIBUTE algorithm (described in RFC1429, and in Chapter 11, below) and to the large (and growing) network of LISTSERV servers.

The LISTSERV network of servers helps to enhance LISTSERV's performance by providing a "backbone" through which large quantities of mail can be quickly distributed. The backbone also allows LISTSERV servers to "talk" to each other and exchange information. Among other things, this exchange of information between servers allows your own local server to participate in the global List of Lists service and L-Soft's CataList service on the World Wide Web (just point a web browser at http://www.lsoft.com/lists/listref.html to use the CataList service).

LISTSERV's nature as a distributed network of interconnected servers also makes it possible to identify and eliminate unsolicited advertisements sent to multiple lists (known colloquially as "spams") before they do much harm. While it is virtually impossible for a small isolated server to detect a spam (unless the sender listed the thousands of lists he was targeting in the "To:" field), for the simple reason that it will only ever receive a few copies for its own public lists, the LISTSERV network as a whole receives thousands of copies of the spam. By comparing notes with each other, the servers can quickly determine that a spam is occurring and raise a network-wide "spamming alert", stopping the message before it does much damage at all. Since the introduction of LISTSERV's anti-spam technology in version 1.8b, the growing number of sites that are participating in the anti-spamming warnings have virtually stopped the distribution of such messages in their tracks. L-Soft's developers are constantly upgrading and refining the anti-spam algorithms, to the effect that LISTSERV version 1.8c has an even better anti-spam filter than before.

LISTSERV also makes it possible for you to offer the same mailing list in three different formats, all running from the same list:

• Individual mail messages sent out as they are processed
• Digest mode, where a compendium of messages processed by the list is sent at specified intervals
• Indexed mode, where an index consisting of the message number, sender, and the subject line of each message is sent each day, along with instructions on how to retrieve postings from the server

LISTSERV 1.8c also introduces database search capability to the non-VM servers (VM servers have had this capability for years). A new reverse indexing feature is available for servers running lists with large archives. Users can use a simple search syntax to comb list archives for specific terms of interest. And L-Soft has also written a World Wide Web archive interface (not currently available on VM for technical reasons unrelated to LISTSERV itself) with which the notebook archives for all public lists can be viewed and searched from a web browser. The new WWW interface differs from (and has advantages over) "hypermail" style web archiving in that new postings are shown as soon as they are received; postings can be organized in a manner that best suits the reader; there is no duplication of effort, as the LISTSERV WWW interface works from the list's notebook archives rather than creating a separate HTML file for each posting; and the list owner can customize the main page for their list by simply modifying their mail template file.

In addition to the anti-spamming filter, LISTSERV 1.8c introduces an anti-spoofing filter, to keep mischevious (and often malicious) users from subscribing other users to mailing lists in order to "mailbomb" them.

Many other enhancements have been introduced in 1.8c. Please see the release notes for complete details at http://www.lsoft.com/manuals/index.html .

4. How your organization can use LISTSERV® to its benefit

Universities that have used LISTSERV for many years can attest to the value of LISTSERV as both an educational and administrative tool. Lately, more and more commercial enterprises have come to realize that LISTSERV can work for them, too.

4.1. A practical example: Mike's Bikes

How can LISTSERV improve your business? Although hundreds of businesses have used LISTSERV for years, we are ever impressed by the number of creative and new ways that businesses use LISTSERV. Let's follow the fictitious "Mike's Bikes" bicycle company, and see how using LISTSERV increases sales and product visibility, reduces costs and makes a business more efficient.

Public Relations Lists

When Mike first got LISTSERV, his main goal was to increase name recognition for Mike's Bikes, so he set up a few mailing lists that bicycle enthusiasts would want to subscribe to: the Bicycle Travel list, the Bicycle Maintenance list, and the Bicycle Safety list. News of the lists was sent to various bicycle and sports magazines, and before long hundreds of subscribers were exchanging their views and experiences on the three lists. Thousands of letters were distributed by LISTSERV every week, and, best of all, by using LISTSERV's Banner feature, each letter carried the message:

Mike also set up a newsletter list for his clients who preferred to receive the Mike's Bikes monthly newsletter, "In Gear" via email. Mike knew that every newsletter he could send out via the list saved him in printing and postage costs, and made the newsletter more convenient for his customers to save and store. Visitors to the Mike's Bikes home page could get on the "In Gear" subscriber list right from the web site. By using LISTSERV, Mike had developed the cutting-edge image he wanted for his company.

Announcement and Product Support Lists

Mike started selling so many bicycles that his customer service telephone line was busy constantly. People wanted catalogs; they wanted information on how to attach the new "Nite-Lite Reflectors" that Mike had mentioned on the Bicycle Safety list (sales were great, but the manufacturer's instructions were lacking); they wanted to know when the next sale was (those reflectors were pricey). The phone bill for all of those 800 number calls was getting out of hand!

Mike responded by setting up a Product Announcement List, a New Catalog list, and a Product Support list. Mike made both the Product Announcement list and the New Catalog list "announce only" lists: information could be distributed to these lists only by Mike and his sales team.

The Product Announcement list was for customers who wanted to know immediately about new products and services from Mike's Bikes. People who visited the Mike's Bikes home page on the World Wide Web could ask to be added to the list from the web site. When Mike announced a sale, his customers got the word in minutes, and consequently placed their orders sooner.

The New Catalog list was set up for customers who wanted to have Mike's Bikes catalogs sent to them as soon as they were published. Because the catalogs came by email, customers received them within minutes. In addition, customers could save the catalogs instantly on their computers, and didn't have to be concerned about storing or losing a paper copy. Mike was happy because it reduced the number of his paper catalogs, which meant reduced printing and postage costs for the business. Mike's customers were happier because they could search for specific items with their word processor and find them instantly. The reputation Mike's Bikes got for being an environmentally friendly company didn't hurt, either.

Mike also announced to his Catalog list that a deluxe, full color version of the new catalog, including graphics and hypertext, was now on the Mike's Bikes home page on the World Wide Web, and that anyone who wanted the deluxe version of the catalog on their own PC could retrieve specific chapters by using LISTSERV's file retrieval function.

The Product Support list was set up as a moderated "discussion" list. It worked somewhat like a "Letters to the Editor" page in a magazine: any subscriber could submit mail to the list, but Mike filtered the mail, posting only the letters which best articulated a problem, then answering the letters. Sometimes he sent a copy of the letter to the Bicycle Maintenance list, or included it in the "Letters" section of "In Gear". This way, Mike was able to be proactive about addressing issues he knew would be important to his customers.

File Serving

Mike also wrote his own installation instructions for that problem reflector. He made the file available to anyone who needed it using LISTSERV's file server function, as he had done for his deluxe version of the Mike's Bikes catalog. He posted the simple directions on how to get the file to the Bicycle Maintenance list, the Bicycle Safety list, the Announcement list, and the Product Support list. He also mentioned it in the "In Gear" newsletter and on the web site. When word of this got to a major bicycle magazine, instructions for getting the file and visiting the Mike's Bikes homepage were mentioned in the next issue. Mike's use of LISTSERV in handling the reflector dilemma turned apotential problem into an opportunity to attract new customers and improve public relations.

Internal Lists

Mike's Bikes eventually opened manufacturing plants, branch offices and retail stores all over the world. In order to keep his company connected, Mike set up internal mailing lists. Although these lists sent mail through the Internet, they were concealed lists that only people within the company were aware of. Mike could also set up lists on his Wide Area Network. LISTSERV even worked through his firewall.

Mike set up lists for the sales and marketing divisions, branch managers, the import/export teams, and the regional vice-presidents. The US West Coast division had its own list, as did the South America and Tokyo/Far East divisions. There was even a general staff list that included everyone in the world who was employed by Mike's Bikes.

Product Development Lists

Mike's dream was to develop a "carcycle"--a car/bicycle hybrid which would keep 2-4 peddling passengers protected from rain and cold. A market study had shown that people in Japan and the Netherlands were particularly interested in the carcycle, and Mike was confident that once he built a stronghold in these markets, interest would spread worldwide.

The project had been stalled, however, because the development teams in Chicago, Amsterdam, New Delhi, Singapore and Aqaba had such a hard time coordinating international conference calls and scheduling local meetings. Mike started a "carcycle" list for the team. Each time one of them had an idea for the carcycle, they would send it to the list, knowing that LISTSERV would automatically copy and send the information to the others on the team within minutes. The team became a virtual community, without having to schedule conference calls or meetings, and without geographical restrictions.

File Serving Functions

The plans for the carcycle were in a series of computer files. Everyone on the carcycle list had "read" access to the files and could retrieve them. The head engineers also had "write access" to the files which corresponded to their part of the project, meaning they could make changes to those files. Whenever someone updated a file, they sent a message to the list, so everyone on the carcycle development team would be informed of the change and could get the latest version of the file. Because of the international nature of the teams, development was going on 'round the clock, which sped up the development process considerably. The team was able to concentrate on developing the carcycle instead of faxing photocopies of plans and scheduling meetings.

Although Mike's Bikes is a fictional company, these examples are taken from actual LISTSERV use. LISTSERV helps medical research teams coordinate their work worldwide; software developers use it to develop, beta test and support their products. Promotional and Public Service lists give companies elevated profile and "reach" they strive so hard to maintain. Lobbying lists allow organizations to email form letters to their members, who in turn forward the letters to members of Congress.

Copyright © 1995 by L-Soft international, Inc. Comments and questions may be sent to marketing@lsoft.com.

5. Configuring your LISTSERV® site

For the purposes of this chapter, therefore, it is assumed that you have already installed LISTSERV on your host computer and have been able to start it in successfully in interactive mode. If you have not reached this point, this chapter will be of little use to you.

5.1. Site configuration files

Platform	Site configuration file
VM	LOCAL SYSVARS
VMS	SITE_CONFIG.DAT
Unix (all)	go.user
Windows NT	SITE.CFG
Windows 95	SITE.CFG

These are the only configuration files that should be changed on any LISTSERV installation. Software upgrades may overwrite any other configuration files located in LISTSERV's home directory. They will never overwrite the files listed above. The intent is to help preserve your system settings from one version to the next so that you do not experience the inconvenience of having to reconfigure LISTSERV after an upgrade.

L-Soft international, Inc., is not responsible for system downtime or misoperation occassioned by the loss of any changes that you make to configuration files other than the ones listed above.

5.2. What can be configured?

Table 5.1. LISTSERV site configuration variables

Variable	Short Description	VM	VMS	Unix	Win
BITNET_ROUTE	defines the hostname of a machine that knows how to route mail to BITNET addresses	yes	yes	yes	yes
CHECKMDISK	List of library minidisks to be checked at startup	yes	no	no	no
CMSNAME	the name of the CMS system to be used on IPL commands	yes	no	no	no
CREATEPW	the password required to create new lists	yes	yes	yes	yes
DATABASE	Indicates whether the database functions are enabled or not	yes	no	no	no
DBRINDEX	Determines whether or not the new LISTSERV database functions use reverse indexing	yes	yes	yes	yes
DEFAULT_SPLIT	Provides a default value for the "SPLIT=" command line keyword	yes	yes	yes	yes
DELAY	the delay between two reader-scan operations	yes	no	no	no
DIAGD4	Indicates whether LISTSERV should use diagnose X'D4' to mimic the RSCS origin on files it DISTRIBUTEs	yes	no	no	no
FILEDISK	the filemode of the DEFAULT disk to be used for storing files via a PUT command	yes	yes	yes	yes
FILEMAXL	the maximum number of lines for any incoming non-mail file to be accepted	yes	no	no	no
FILTER_ALSO	defines users or classes of users who should not be allowed to post to any list on the server.	yes	yes	yes	yes
FIOC_TARGET	Defines (in kilobytes) the "target size" for LISTSERV's file cache.	yes	yes	yes	yes
FIOC_TRIM	Defines (in kilobytes) the threshold at which point LISTSERV should start aggressively trimming the cache.	yes	yes	yes	yes
FIOC_WARNING	Defines (in kilobytes) the cache size at which LISTSERV should write a warning to the console log.	yes	yes	yes	yes
GETQWAIVE	Internet addresses of persons to be granted an "infinite" GET quota	yes	no	no	no
IGNORE	a list of userid@nodes whose messages and files are to be ignored	yes	no	no	no
INDEX_VIA_GETPOST	On VM, determines whether INDEX subscriptions use GETPOST or database jobs by default.	yes	no	no	no
INSTPW	the optional local "installation password" associated with the INSTALL command	yes	no	no	no
LICENSE_WARNING	Toggles license warnings on and off. WARNING: See Appendix C before changing this value.	yes	yes	yes	yes
LIST_ADDRESS	Default value for the "List-Address=" keyword	yes	yes	yes	yes
LIST_EXITS	Filenames of EXEC files that can be defined as exits by an "Exit=" list header keyword	yes	yes	yes	yes
LMCPUT	a boolean variable indicating how PUT commands for datafiles associated with the LMC FAC are handled	yes	no	no	no
LOCAL	a list of nodes to be associated with the hardcoded LCL FAC. Also used as the default for the "Local=" list keyword	yes	yes	yes	yes
MAILER	Internet address of the local mailer	yes	no	no	no
MAILMAXL	the maximum number of lines for an incoming MAIL file to be accepted	yes	yes	yes	yes
MAXBSMTP	Maximum number of 'RCPT TO:' lines per BSMTP file sent to the mailer	yes	yes	yes	yes
MAXDISTN	Maximum number of recipients in forwarded DISTRIBUTE jobs	yes	yes	yes	yes
MAXGET	Maximum number of GET requests a user can make per day	yes	no	no	no
MAXGETK	Maximum number of kilobytes of data a user may obtain a day via GET requests.	yes	no	no	no
MDISK.cuu	Information about library minidisks	yes	no	no	no
MSGD	Userid of the virtual machine running a RFC1312/MSP server, if "Internet TELL" support is desired	yes	no	no	no
MYDOMAIN	the list of domain names which are equivalent to NODE--e.g., MX addresses, CNAMEs, etc.	yes	yes	yes	yes
MYORG	Short organization name that appears in the RFC-822 "Sender:" line.	yes	yes	yes	yes
NDMAIL	Whether to send mail to the local MAILER in Netdata format	yes	no	no	no
NODE	Internet address of this LISTSERV host	yes	yes	yes	yes
NO_NJE_JOBS	directs a VMS™ server running in NJE mode to send all outgoing server-to-server requests via the Internet	no	yes	no	no
OFFLINETHR	Defines the system and RSCS spool thresholds for automatic offline/online control	yes	yes	no	no
POSTMASTER	a list of userid@nodes, of which the first one is the "main" postmaster (to receive transferred files).	yes	yes	yes	yes
PRIMETIME	Defines the "prime time" for your node	yes	yes	yes	yes
QUALIFY_DOMAIN	Defines domain to be appended to all non-qualified addresses	no	yes	yes	yes
RESMODES	defines a list of filemodes which are to be considered as "reserved" and never available for dynamic ACCESS	yes	no	no	no
RSCS	a list of local userids which must be treated as RSCS virtual machines	yes	yes	no	no
SMTP_FORWARD	the Internet hostname of the server to which all outgoing SMTP mail should be forwarded for delivery	yes	yes	yes	yes
SMTP_FORWARD_n	Defines n number of "SMTP workers" used to split up the SMTP forwarding load	no	yes	no	yes
SMTP_RESET_EVERY	Directs LISTSERV to reset open SMTP connections every n minutes	no	yes	yes	yes
SORT_RECIPIENTS	Determines whether or not to sort recipients in the RFC821 mail envelope	yes	yes	yes	yes
SPAM_DELAY	Sets the server-wide value (in minutes) for the anti-spam quarantine period	yes	yes	yes	yes
SSI	Flag telling LISTSERV that it runs in a SSI system	yes	no	no	no
STARTMSG	Recipients of start and stop messages	yes	yes	yes	yes
STOREPW	the password to be used by postmasters when executing CP/CMS commands and when storing files in the server by means of the PUTC command	yes	yes*	yes*	yes*
TRAPIN	List of userid@node templates from whom LISTSERV should never accept mail	yes	yes	yes	yes
TRAPOUT	List of userid@node templates to whom LISTSERV should never send mail	yes	yes	yes	yes
VM30091	indicates whether or not the VM30091 message suppression functions are available	yes	no	no	no
WEB_BROWSER_CONFIRM	indicates whether or not LISTSERV should require "OK" confirmation for commands sent from WWW browsers.	yes	yes	yes	yes
WWW_ARCHIVE_CGI	the relative URL that leads to the WWW archive CGI script. (This is a URL, not an OS path name.)	no	yes	yes	yes
WWW_ARCHIVE_DIR	the full OS path name to the WWW archive directory	no	yes	yes	yes
XFERTO	Userid of the virtual machine to which files found in the lists readers should be transferred	yes	no	no	no

Notes:

* For non-VM systems, STOREPW is a secondary password that is functionally identical to CREATEPW. You should use the same value for both passwords, i.e., set STOREPW=%CREATEPW% (for Windows NT and 95), etc.

5.3. Files used by LISTSERV

BITNET Network Table files

These files are not required when running LISTSERV with RUNMODE=TABLELESS, and are not shipped with evaluation copies for Windows 95 or with LISTSERV Lite. Network table files include:

bitearn.nodes	bitearn.dbindex	bitearn.distsum2	bitearn.linkdef2
bitearn.linksum2	bitearn.nodesum3

With the exception of BITEARN.NODES, all files are generated whenever BITEARN.NODES is updated or when an explicit NODESGEN command is issued. For pre-1.8c servers, BITEARN.NODES must be downloaded monthly from

or from the European mirror at

Beginning with 1.8c, BITEARN NODES on registered networked servers will be updated using the same mechanism as PEERS NAMES and other LISTSERV tables. Note that this requires that your mail server support incoming files of at least 1.5M. VM sites have not been included as they typically maintain this file using the UPNODES procedure and store it on a public disk, applying change control procedures in the process.

Internet and Peer Networking Table files

intlinks.file	intpeers.names	linkswt2.file	peers.dbindex
peers.dbnames	peers.distsum2	peers.names	peers.namesum
service.names

These files are used by LISTSERV to define its "backbone" and other peer servers, as well as to help determine the best routes for mail sent via the DISTRIBUTE algorithm. They are updated periodically by mail from other servers. The update process is automatic and does not require LISTSERV maintainer intervention unless a problem is noted.

LISTSERV's external data files

LISTSERV uses these files for a number of purposes. The fact that they are external to the executables makes it easy to update them when needed. These files include:

country.file	default.mailtpl	errfac.file	listkwd.file
lsvhelp.file	lsvinfo.file	permvars.file	signup.filex
stdcmd.file	sysff.file	site.catalog	system.catalog

PERMVARS.FILE is LISTSERV's main "permanent variables" file; among other things, this is where LISTSERV registers spammers and users that have been served off. The SIGNUP.FILEx files (initially there are 9, e.g., SIGNUP.FILE1, SIGNUP.FILE2, etc.) are used to register users and their real name fields.

SYSTEM.CATALOG is used by LISTSERV to register system files; it should not be modified, as it is always shipped with new versions and will thus overwrite itself. Instead, SITE.CATALOG should be used to register files and list file archive catalogs (listname.CATALOG) for users to retrieve. (SITE.CATALOG is not shipped with LISTSERV; please see the chapter on Notebook and File Archives for details.)

DEFAULT.MAILTPL is the file from which LISTSERV gets its default mail templates for responses to user input. See the chapter on Creating and Editing LISTSERV's Default Mail Templates for details.

User reference material

The following files are LISTSERV's online documentation.

listfile.memo	listkeyw.memo	listmast.memo	listpres.memo
listjob.memo	listlpun.memo	listownr.memo	listserv.memo
listall.refcard

LISTALL.REFCARD is broken into three parts internally. Part 1 is the response to the INFO REFCARD command; Parts 1 and 2 are the response to INFO OWNERs command; and the whole document is sent in response to a GET LISTMAST MEMO command.

Other files that will appear during use

While in use, LISTSERV creates various files for itself. In the MAIN or HOME directory, these are typically:

.AUTODEL files	Maintain data for LISTSERV's autodeletion functions; one for each list that has Auto-Delete enabled. If no auto-deletion reports are pending, this file will not exist.
.DIGEST files	These files are the (volatile) digest files for each list that has digests enabled. They are deleted and restarted when the digest is cut. Note that if the location parameter of the Digest= keyword is not set to something that points to the MAIN or HOME directory, .DIGEST files will not appear in the MAIN or HOME directory, but rather in the directory specified.
.LIST files	Mailing list files, including the header and subscriber information. Do not attempt to edit these files with a text editor; use the GET and PUT commands instead.
.OKxxxxxx files	Usually found for edited lists, but can also appear for non-edited lists if users are set to REVIEW. These are mail messages that are awaiting "OK" confirmation. If they are not confirmed, they are automatically deleted after about a week.
.OLDLIST files	These files contain the last saved version of the list file. If you PUT a header and find that you've made a fatal mistake (like adding users "on the fly" and deleting everyone else on the list, or editing the list file by hand and corrupting the record structure) you can send the command GET listname (OLD to have the listname.OLDLIST file sent to you.
.SUBJECT files	Maintain the list of subjects for the digest. Again, if digests are not enabled for a specific list, this file does not exist for that list. Also, the same note for the location of these files as for .DIGEST files applies. .SUBJECT files are deleted and restarted when the digest is cut.

In the SPOOL directory, the following file types will be found:

.ERROR	LISTSERV generates an .ERROR file in the spool for each error that it processes. These can be viewed with the jobview utility and are important for tracing certain errors back.
.JOB	Files that have been received by LISTSERV and are queued for processing. These files are in Base64 format and can be viewed with the jobview utility.
.JOBH	Held .JOB files. Such files are either being processed by LISTSERV (and are thus locked) or have generated an error message. These can also be viewed with the jobview utility.
.MAIL	Files that have been processed through LISTSERV and are queued for delivery to the outgoing SMTP mail agent.
.MAIL-ERR	Files that have been processed through LISTSERV and for which delivery has been attempted, but for which a "permanent" SMTP error has resulted. If you have reason to believe that the error was not actually "permanent", simply rename the file with the .MAIL extension and LISTSERV will pick it up for another try.

JOBH files containing the string $NOJOB$ in the filename are typically waiting to be processed because the list they are going to has an explicit Prime= variable set and the non-prime time has not yet arrived.

5.4. Installing and configuring LISTSERV's WWW Archive Interface

Version 1.8c introduces a WWW archive interface that allows users to browse and search list archives (the LISTSERV maintainer controls which lists are or are not visible through this interface). Postings can be organized by date, by topic or by author, and a search function with online help is provided. LISTSERV's WWW interface has the following advantages over "hypermail" style web archiving:

• The information on the web is always up to date. New postings are shown as soon as they are received.
• The postings can be organized in the manner that best suits the reader: by date, by author, by topic, with or without table of contents, with or without showing the author, etc.
• Only one copy of the information is kept, and in particular there is no need to create an individual HTML file for each posting. This design allows the interface to scale up gracefully to lists with hundreds of thousands of archived postings, which would otherwise require hundreds of thousands of individual HTML files, wasting disk space (each file takes up at least one disk block) and stressing the file system past reasonable limits.
• The search forms can be used to create search requests matching all postings in the last X days. The resulting URL can then be bookmarked and reloaded on a regular basis.
• List owners can customize the main page for their lists without any intervention by the LISTSERV maintainer, by updating one of the mail templates for their list. The LISTSERV maintainer can customize common pages and header/trailer HTML statements by updating system mail templates.

To take advantage of this new interface, you must first ensure that the "Notebook=" options for your list are compatible with the WWW interface. In most cases, you will not have to do anything, but certain options are incompatible with the use of the WWW interface and may need to be changed:

• The archive frequency must be WEEKLY, MONTHLY or YEARLY. SEPARATE and SINGLE notebooks are not supported. L-Soft generally recommends converting lists with SINGLE notebooks to YEARLY unless there is a compelling reason to have all the messages in exactly one file.
• For optimal performance, the archive frequency may need to be adjusted to produce an "adequate" number of topics and messages in each archival period. The definition of "adequate" depends on your users, the kind of equipment they have, and how they connect to the Internet. As a rule, home users will prefer a larger number of smaller archives whereas office users with large screens and T1 or better connectivity will tolerate a larger table of contents.
• The archives must be public as there is no userid/password control in the web archive interface.
• On most systems, the directory in which your list archives are kept must be specified in absolute rather than symbolic form, or the WWW interface may not be able to access it. Symbolic form is when the directory name is a single letter, for instance "Notebook= Yes,L,Monthly,Public" ("L" is the directory specification). In most cases, your list header will read "Notebook=Yes,E:\LISTS\XYZ-L,Monthly,Public" and you will not have to worry about this.

You must then ask the LISTSERV maintainer to enable your list for the WWW interface. This may require the installation of a web server and of the WWW interface code itself. You can then modify the WWW_INDEX mail template to customize the main archive page for your list. See the chapter 10 of this manual for more information on customizing mail templates.

5.4.1. Installing a web server

If you do not already have a World Wide Web server installed and operating on your LISTSERV machine, you will need to obtain and install one. There are quite a few free web servers available for downloading on the Internet for most systems; you may want to start your search for server software at the W3 Consortium's web site at http://www.w3.org. Naturally, commercial web servers are also supported.

Please note that L-Soft cannot help you with the installation or configuration of your web server.

5.4.2. Installing the web archive interface script

The CGI script for the web archive interface must be installed in the directory where your web server normally keeps CGI scripts and from which they are authorized to run. If in doubt, please read the manuals that came with your web server and/or contact the web server manufacturer's support group; L-Soft cannot help you with this. LISTSERV cannot install the script for you because installation depends on which server you use, which operating system you are running, how the server has been configured, etc.

System specific instructions:

• NT: simply copy WA.EXE to the appropriate directory. For Microsoft's Internet Information Server (IIS), this is normally C:\INETSRV\SCRIPTS (not C:\INETSRV\WWWROOT\SCRIPTS).
• unix: copy 'wa' to the appropriate directory, change its owner to 'listserv' and set the suid bit. This authorizes the interface to read archive files.
• VMS: you will have to link WA.OBJ with the CGI library provided with your web server, then copy it to the appropriate directory. Make sure to arrange for the program to have read access to the archive files for the lists you want to serve on the web. This may vary from one web server to another.

While the script can be renamed, a short name will help keep the HTML documents small and speed up the site.

5.4.3. Creating a subdirectory for the archive interface

Create a subdirectory on your web server to contain the various files LISTSERV will be creating. You should not use your main HTML documents directory as LISTSERV will create quite a few files! The suggested name is 'archives'. For IIS, this would be the directory C:\INETSRV\WWWROOT\ARCHIVES. For a unix server running Apache it might be /usr/local/etc/httpd/htdocs/archives .

System specific steps:

• VMS: define the systemwide logical LISTSERV_WWW_ARCHIVE_PATH to point to the directory you just created, and LISTSERV_WWW_ARCHIVE_URL with the URL to the directory in question (preferably relative).
• unix: create a world-readable file called /etc/lsv-wa.config with the following two statements:

  PATH xxx
  URL yyy

  Where 'xxx' is the absolute path to the directory you've just created and 'yyy' is the URL to this directory (preferably relative). For instance:

  PATH /usr/local/etc/httpd/htdocs/archives
  URL /archives

• NT: if necessary (and it shouldn't be), you can update the registry key HKEY_LOCAL_MACHINE\SOFTWARE\L-Soft\LISTSERV\WWW_ARCHIVE_URL to override the default URL to the directory you have just created. Again, this is not normally necessary and is only provided for weird web servers, etc. Don't do it unless it didn't work without it.
• NT: Note that some NT Web servers use 'default.htm' rather than 'index.html' as the default file opened when a URL path doesn't end with a file name (e.g., if you were to call the URL http://listserv.yourhost.net/archives/ rather than http://listserv.yourhost.net/archives/index.html). If your server looks for 'default.htm' instead of 'index.html' by default, you will want to address this in some way, perhaps by creating a 'default.htm' file in the /archives directory that has a link pointing to 'index.html'.

5.4.4. Configure LISTSERV to activate the web archive interface

This is done by modifying LISTSERV's configuration to add two variables:

• WWW_ARCHIVE_CGI is the relative URL that leads to the CGI script you have just installed. Typically this will be something like '/cgi-bin/wa' or '/scripts/wa.exe'. This is a URL, not an OS path name.
• WWW_ARCHIVE_DIR is the full path name to the directory you created in the previous step (C:\INETSRV\WWWROOT\ARCHIVES or whatever).

Under unix, don't forget to export!

LISTSERV will then create and maintain a file called http://localhost/archives/index.html from which you can access all the postings. (This is made from the template WWW_ARCHIVE_INDEX--see below.)

5.4.5. Customizing the web pages LISTSERV creates

The LISTSERV maintainer can create a file called www_archive.mailtpl in the main LISTSERV directory to override the web archive templates in default.mailtpl. (See chapter 10 for more information on LISTSERV's mail templates.) There are 3 templates you typically might want to override:

• $WWW_ARCHIVE_HEADER: this is added at the top of every HTML file generated by the interface. This can be used to set the background color and insert a logo. Usage should be kept to a minimum since it appears on every page and gets in the way of the information people want to see.
• $WWW_ARCHIVE_TRAILER: same but added at the bottom of every HTML files. Can contain legal disclaimers, copyright information, and useful links.
• WWW_ARCHIVE_INDEX: this is the main page for the web archive interface. The default works fine but is a bit bland.

The list owner can also control the main page for his own lists by creating the usual listname.MAILTPL file with a WWW_INDEX template.

5.4.6. Enabling individual lists

Once the interface is installed, LISTSERV will automatically make any mailing list with public archives available through it, provided that a subdirectory has been created for them in the 'archives' subdirectory created above, and provided that LISTSERV has read/write access to the subdirectory.

Note that public notebooks for any list coded "Confidential= Yes" will appear via the interface if a subdirectory under 'archives' is created for that list. If you do not want the confidential list's public notebooks available via the WWW interface, do not make a subdirectory for it under 'archives'.

In general this should not cause a problem, since most confidential lists will also have private notebooks, but naturally this is not always the case.

Also note that under unix, if the 'wa' script does not have the suid bit set, the interface will appear to work normally until you try to read a message. If the suid bit is not set, you will receive a message to the effect that the archives are not available and to try again in 30 seconds.

As an example, let's assume that you have a list called XYZ-L that you want to make available through the Web interface.

First, under the 'archives' directory you created above, you must create a directory with the same name as your list. Thus, in order to make the XYZ-L list accessible through the interface, you must create the directory 'archives/xyz-l'

Next, you would edit the XYZ-L header so that XYZ-L has these characteristics:

* Notebook= Yes,where,interval,Public

Finally, you would PUT the XYZ-L header onto the server. When you PUT the header, LISTSERV will create the XYZ-L.HTML file in the 'archives' directory and build indexes for the list in the 'archives/xyz-l' directory.

Note: If you do not execute a list PUT operation after creating the directory for the list under 'archives' (for instance, if the list already had public archives and it was not necessary to edit the header), LISTSERV will wait until midnight to create the web archive files for the list rather than creating them immediately. (Naturally, stopping and restarting LISTSERV will also force a rebuild of all of the web interface files but is not recommended as the normal way to accomplish this.)

At this point you will be able to access XYZ-L's archives from the URL http://www.yourhost.com/archives/xyz-l.html.

5.5. The "spam" detector

The spam detector has been improved in version 1.8c, as follows:

• The spam detector is now able to catch the first few copies of a new spam (in most cases). Previously, dozens of copies (out of the thousands sent by the spammer) would be let through before enough data was collected to identify the posting as a spam.
• The number of spam alert messages sent to the LISTSERV maintainer has been reduced to one per offender.
• The spam database is trimmed more aggressively, saving storage and processing time for sites with lots of mailing lists.
• The algorithms have been generally refined and improved, making the spam detector react more promptly and more accurately. New detection techniques have been introduced.

There are two major changes that list owners need to be aware of: spam quarantine and "anonymous" spam alerts.

5.5.1. Spam quarantine

One of the most arduous problems the spam detector has to face is the accurate detection of the first few copies of the spam. When the first copy reaches the first LISTSERV server worldwide, it is just a posting like any other. It will take repeated occurrences of this same posting for LISTSERV to realize that it is in fact a spam. However, it is desirable to block this very first copy as well, and this can only be accomplished by introducing a delay in the processing of "suspicious" messages. This "quarantine" gives the spam detector some time to gather the necessary evidence to determine if the message is a spam or not. The default value is 10 minutes, and can be changed by adding:

* Loopcheck= Spam-Delay(xxx)

in the list header (the value is in minutes). The LISTSERV maintainer can also change the system default by adding a SPAM_DELAY variable to the LISTSERV configuration with the desired value (also in minutes). A value of zero disables this new feature.

The default value of 10 minutes is adequate in most cases; it can be lowered on fast, large, active servers and may need to be increased on servers with chronical backlogs. Currently, LISTSERV determines whether a message is suspicious or not based on the sender's posting history. This however may be changed in future versions to further improve the efficiency of the spam detector.

5.5.2. "Anonymous" spam alerts

On occasion, you may receive a spam alert from LISTSERV where the offender's e-mail address is replaced with the word "anonymous". These alerts are generated by new detection algorithms where, for various reasons, it may sometimes be desirable to hide the identity of the potential offender, usually because there is a fair chance that the posting is in fact legitimate for the particular lists to which it was posted (for instance because these lists were configured to tolerate a high degree of cross-posting). In this case, information about the text of the message may be released and ultimately lead to a spamming alert that will block further copies of this same message, while the identity of the poster remains hidden.

6. LISTSERV Commands

(For a quick reference card of LISTSERV commands, see Appendix A of this document.)

This chapter is divided into three parts, corresponding to those commands available for use by the general user, list owners and file owners, and the LISTSERV maintainer. Non-privileged users can send commands by mail or by interactive commands. (Note that interactive commands can only be sent if a two-way NJE or MSGD connection exists.) Privileged users can send commands by mail, interactive commands (subject to the same restriction previously noted) or via the console (VM) or the LCMD utility (non-VM).

Unless otherwise noted, commands are listed in alphabetical order, with the minimum acceptable abbreviation in capital letters. Angle brackets are used to indicate optional parameters. All commands which return a file accept an optional 'F=fformat' keyword (without the quotes) that lets you select the format in which you want the file sent; the default format is normally appropriate in all cases. Some esoteric, historical or seldom-used commands and options have been omitted.

Note that some commands are not available on all platforms; these commands are marked appropriately.

Continuation cards (see Appendix D regarding LISTSERV's Jobs Command Language) can be used to split long commands (for instance, ADD commands for users with long X.500 addresses) into two or more 80-character cards. In that case you must insert a "// " string before the command text and a comma at the end of each line of the command so that CJLI considers it as a control card and performs the required concatenation. For instance,

// QUIET ADD MYLIST someone.with.a.real.long.userid.that.wraps@hishost.com ,
His Name

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.

6.1. General Commands

6.1.1. List subscription commands (from most to least important)

SUBscribe listname[full_name | ANONYMOUS]

The SUBscribe command is LISTSERV's basic command, issued by users to join mailing lists. This command can also be used to change one's "full_name" field in LISTSERV's SIGNUP database (simply reissue the command with the changed name). Note that the full_name is not required if the user has previously signed up to lists on the same LISTSERV server, or if the user has previously registered in LISTSERV's SIGNUP database by using the REGISTER (q.q.v.) command.

In 1.8c, the SUBSCRIBE command has been enhanced to support the following syntax:

SUBSCRIBE listname ANONYMOUS

This indicates that the user wishes to join the list anonymously, that is, without specifying a name. The CONCEAL subscription option is automatically set, granting the subscriber the maximal level of protection available.

SIGNOFF listname| * | * (NETWIDE

The SIGNOFF command allows the user to cancel his or her subscription to lists. SIGNOFF requires a qualifying parameter, as follows:

listname	Sign off of the specified list
*	Sign off of all lists on that server
* (NETWIDE	Sign off of all lists in the LISTSERV network

The "* (NETWIDE" parameter causes the LISTSERV server to forward a copy of the signoff request to all other registered LISTSERV servers. This is a good option for a user who is changing service providers or otherwise losing a specific address that will not be forwarded. Please note that this parameter will not remove the user from non-LISTSERV lists or from LISTSERV lists running on non-registered sites.

SET listname option1 [option2...]

Allows the user to change his or her subscription options without administrative intervention. The options available to be changed are as follows:

ACK	A mail message acknowledging the receipt and distribution of the user's posting is sent back to the user.
NOACK	No posting acknowledgement is sent. In general, this setting should only be used if the user has also set himself to REPRO, as it is desirable in most cases that some indication of whether or not the posting was received by LISTSERV be sent.
MSGack	An interactive message is sent to acknowledge receipt and distribution. Note that this works only if both the machine running LISTSERV and the user's machine have NJE connectivity (e.g., BITNET). If NJE connectivity is not available on both ends, this option is effectively the same as NOACK.
CONCEAL	Allows the user to be concealed from the REVIEW command. Note that the list owner or LISTSERV maintainer can always get the complete list of subscribers, regardless of this setting.
NOCONCEAL	"Unhides" the user
Files/NOFiles	These options toggle the receipt of non-mail files from the list. Note that this is NJE-specific, and thus obsolete for systems without NJE connectivity, but retained for compatibility.
Mail/NOMail	These options toggle the receipt of mail from the list. Users who will be away from their mail for an extended period of time may prefer to simply turn the mail off rather than to unsubscribe, particularly if subscription to the list is restricted in some way.
DIGests/INDex/NODIGests/NOINDex	These options change the format in which list mail is received by the subscriber. DIGEST turns on digest mode, in which the subscriber receives a digest of postings at set times dependent on how the Digest= keyword of the list is set. INDEX turns on index mode, in which the subscriber receives a daily listing of subjects posted to the list, from which he or she may order postings of interest. NODIGEST and NOINDEX toggle the mode back to individual postings sent as received by LISTSERV. Note that these options are interrelated; setting one will negate another.
REPro/NOREPro	Causes LISTSERV to send you a copy of your own postings as they are distributed. Some users may prefer this behavior to the ACK option (see above).
MIME/NOMIME	Toggles MIME options on and off. Currently only digests are available in MIME format. If DIGEST mode is set, the user will receive a MIME digest instead of the regular plain-text digest. Note that you must have a mail client that supports MIME digests (Pegasus is one that does) or this setting will do you little good. This option is automatically set at subscribe time for users who send their subscription command using a MIME-compliant agent, unless "Default-Options= NOMIME" is specified for the list.
TOPICS: ALL | [+/-]topicname	For lists with topics enabled (see the Topics= list header keyword), subscribe or unsubscribe to topics. For instance, if a list has topics SUPPORT and CHAT, a user could subscribe to CHAT by sending SET TOPICS +CHAT . Or the user could unsubscribe to SUPPORT by sending SET TOPICS -SUPPORT . Finally, the user can subscribe to all available topics by sending SET TOPICS ALL .

Options for mail headers of incoming postings (choose one):

FULLhdr	"Full" mail headers, (default) containing all of the routing information.
IETFhdr	Internet-style headers.
SHORThdr	Short headers (no routing information).
DUALhdr	Dual headers, useful with PC or Mac mail programs which do not preserve the RFC822 return email address.
FULL822	Essentially the same as "full" mail headers, but with the important difference that the recipient's email address is specified in the "To:" line rather than the address of the list. "FULL822" headers should be used with extreme caution, as they cause LISTSERV to create a separate mail envelope with a single RFC822 RCPT TO: for each address so set. This behavior can significantly affect the performance of both LISTSERV and of your external mail system.
SHORT822	Essentially the same as "short" mail headers, with the same caveats as noted for FULL822.
SUBJecthdr	"Full" mail headers (like the default) except that setting this option tells LISTSERV to add the list's default subject tag to the subject line of mail coming from the list. (See the listing in Appendix B for "Subject-Tag=" for more information.) Note that if the user is set to SHORThdr (or any other header option other than FULLhdr), LISTSERV will automatically switch the user to FULLhdr, as subject tags require full headers. Note also that subject tags are not generated for messages sent without an RFC822 "Subject:" header. To turn the subject tagging off, the user simply sends a new SET command with any of the other header options (e.g., SET listname FULLhdr) and the SUBJecthdr option is reset.

Note that FULL822 and SHORT822 headers should only be used if a specific problem indicates that they might solve the problem. One possible use would be to determine which subscriber from a specific site is causing the site to throw back delivery errors if that site does not specify which RCPT TO: is generating the error. These headers should never be used by default.

CONFIRM listname1 [listname2 ]...]]

The CONFIRM command should be issued when LISTSERV requests it. A request for CONFIRM should not be confused with a "command confirmation request" which requires an "OK" response. The CONFIRM command is used in two cases:
• When the list in question requires periodic subscription renewals (controlled by the Renewal= keyword). In this case, the amount of time between the request for confirmation and termination of the subscription is controlled by the Delay() parameter of the Renewal= keyword; the default is seven days.
• When LISTSERV "probes" an account during its automatic address probing function. The response time is controlled by the settings of the Auto-Delete= keyword for the list in question.

6.1.2. Other list-related commands

INDex [listname]

The INDEX command sent to LISTSERV without further qualification sends back the contents of the "root" level archive filelist on VM systems (LISTSERV FILELIST) or archive catalog on non-VM systems (SITE.CATALOG plus the contents of SYSTEM.CATALOG).

If the INDEX command is sent with the name of a list (e.g., INDEX MYLIST) or the name of a special filelist or catalog file (e.g., INDEX TOOLS , if TOOLS FILELIST on VM or TOOLS.CATALOG on non-VM exists), LISTSERV sends back the contents of the specified filelist or catalog. Several possibilities exist:

• For mailing lists without an associated filelist or catalog, LISTSERV creates an index "on the fly" containing entries for the accumulated notebook archives for that list. If notebook archives are not enabled for the list, LISTSERV will respond, "This server does not have any file by the name 'listname.filelist'."
• For mailing lists with an associated filelist or catalog, LISTSERV will append the "on the fly" index of notebook archives to the entries in the associated filelist or catalog. For instance, for a list called MYLIST with associated catalog MYLIST.CATALOG, INDEX MYLIST might return:

---

*
* MYLIST FILELIST from LISTSERV@LISTSERV.MYCORP.COM
*
* :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
*
*  The GET/PUT authorization codes shown with each file entry describe
*  who is authorized to GET or PUT the file:
*
*     ALL = Everybody
*     CTL = LISTSERV administrators
*     OWN = List owners
*     PRV = Private, ie list members
*     LMC = LISTSERV master coordinator
*     N/A = Not applicable - file is internally maintained by LISTSERV
*     MSC = Miscellaneous - contact administrator for more information
*
* :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
*
*
* Information files for MYLIST
*                                      rec             last - change     
* filename      filetype       GET PUT -fm lrecl nrecs date     time     
* --------      --------       --- --- --- ----- ----- -------- -------- 
  MYLIST        FAQ            ALL MSC V      66   241 96/04/23 21:42:21 
  MYLIST        WELCOME        ALL MSC V      69    72 96/06/08 18:27:46 
  MYLIST        FAREWELL       ALL MSC V      68    51 96/06/08 18:27:47 
                                                                         
*
* Archive files for the MYLIST list at LISTSERV.MYCORP.COM
* (monthly logs)                                                         
*                                      rec             last - change     
* filename      filetype       GET PUT -fm lrecl nrecs date     time    
* --------      --------       --- --- --- ----- ----- -------- --------
  MYLIST        LOG9603        LOG OWN V      78   412 96/05/14 18:52:07
  MYLIST        LOG9605        LOG OWN V     825  6859 96/05/31 23:01:28
  MYLIST        LOG9606        LOG OWN V     632  8595 96/06/14 12:52:40

---

Figure 6.1. Sample output of an INDEX listname command.
• Lastly, for catalogs or filelists without an associated list, the INDEX command returns only the entries in the catalog or filelist, since there are no associated list archives to be indexed.

Lists [option]

Access the global list of lists maintained by LISTSERV. If no options are specified, then LISTSERV returns only local lists, one line per list. The available options are:

Detailed	All local lists, complete with full header information.
Global xyz	Only those whose name or title contains 'xyz'
SUMmary [host]	Membership summary for all lists on specified host, or the host to which the command is sent if no host is specified
SUMmary ALL	Membership summary for all hosts (long output, send request via mail!)
SUMmary TOTAL	Membership totals only

"Lists Global" without a search string, which returns the entire list of lists, may no longer be issued by general users. If you are asked about this, you should advise users to use the "Lists Global /xyz" format to search the list of lists, or use L-Soft's CataList service at http://www.lsoft.com/lists/listref.html.

Query listname

Query your subscription options for a particular list (use the SET command to change them). Using the "*" wildcard in place of the name of a single list queries subscription options on all lists on the server.

REGister full_name | OFF

Register's the user's full name field in LISTSERV's SIGNUP files, or changes the current value of that field. When a user's name is registered, he or she can omit the full name field from subsequent SUBscribe requests to that server. Sending "REGISTER OFF" to LISTSERV deletes the user's entry from the SIGNUP file.

REView listname <(options>

Get information about a list, assuming the list header keyword "Review=" is set appropriately. The options are:

BY sort_field	Sort list in a certain order: Country by country of origin (ISO country codes) Name by user name (last, then first) NODEid by hostname/nodeid Userid by userid BY (sort_field1 sort_field2) You can specify more than one sort field if enclosed in parentheses. For instance: BY (NODE NAME)
Countries	Synonym of BY COUNTRY
LOCal	Don't forward request to peers. This is only useful if the list is peered; normally it should not be necessary to issue this option.
Msg	Send reply via interactive messages (BITNET users only)
NOHeader	Don't send list header, just send the subscriber list
Short	Don't list subscribers, just send the header and the membership summary for the list.

Note that you can get a quick read of the number of subscribers on the list by sending the command REVIEW listname SHORT NOHEADER.

SCAN listname text

Scan a list's membership for a name or address. Helpful if a user attempts to send a SET command or an UNSUB command and is informed that their address is not subscribed to the list. At the non-privileged level, this command will show all non-concealed entries that match the search text, assuming that the list is set to "Review= Public".

Stats listname <(options>

Get statistics about a list. NOT AVAILABLE ON NON-VM SERVERS. This command is VM-specific, and was originally intended to return BITNET data. The single option is:

LOCal

Don't forward to peers

6.1.3. Informational commands

Help

Obtain a list of commonly-used LISTSERV commands. Also explains how to get the comprehensive reference card and tells who the (non-hidden) server manager(s) are.

Info <topic>|<listname>

Order a LISTSERV manual, or get a list of available ones (if no topic was specified); or get information about a list. For Info listname, the text in the INFO template of listname.TEMPLATE is used, or the INFO template of DEFAULT.MAILTPL if listname.TEMPLATE does not exist or does not contain an INFO template.

Query File fn ft <filelist> <(options>

(Available only on VM) Get date/time of last update of a file, and GET/PUT file access code. The single option is:

Flags

Get additional technical data (useful when reporting problems to experts)

RELEASE

Find out who maintains the server and the version of the software and network data files.

SHOW <function>

Display information as follows:

ALIAS node1 <node2 <...>>	BITNET nodeid to Internet hostname mapping
DISTribute	Statistics about DISTRIBUTE
HARDWare or HW	Hardware information; what kind of machine is LISTSERV running on?
LICense	License/capacity information and software build date
LINKs node1 <node2 <...>>	Network links at the BITNET node(s) in question
NADs node1 <node2 <...>>	Addresses LISTSERV recognizes as node administrators for the specified site(s)
NODEntry node1 <node2 <...>>	BITEARN NODES entry for the specified node(s)
NODEntry node1 /abc*/xyz	Just the ':xyz.' tag and all tags whose name starts with 'abc'
POINTs <ALL | list1 list2...>	Graduated license point information. This information can help you plan orderly expansion of your site if you are running with a graduated license.
STATs	Usage statistics for the server (this is the default option)
VERSion	Same output as RELEASE command

If no function is specified, the output is per SHOW STATS.

The following options are available for VM servers only:


BITEARN	Statistics about the BITEARN NODES file
DPATHs host1 <host2 <...>>	DISTRIBUTE path from that server to specified host(s)
DPATHs *	Full DISTRIBUTE path tree
FIXes	List of fixes installed on the server (non-VM see SHOW LICENSE)
NETwork	Statistics about the NJE network
PATHs snode node1 <node2 <...>>	BITNET path between 'snode' and the specified node(s)

6.1.4. Commands related to file server functions

GET fn ft <filelist> <(options> <F=fformat>

Order the specified file or package from LISTSERV. The single option is VM-specific and is:

PROLOGtext xxxx

Specify a 'prolog text' to be inserted on top of the file

To control the format in which LISTSERV returns the file(s) to you, you can specify the F=fformat parameter. Supported formats are Netdata, Card, Disk, Punch, LPunch, UUencode, XXencode, VMSdump, MIME/text, MIME/Appl, Mail

INDex <filelist>

Same as GET xxxx FILELIST. If no filelist is specified, the default is LISTSERV FILELIST.

PW function

Define/change a "personal password" for protecting AFD/FUI subcriptions, authenticating PUT commands, and so on.

ADD firstpw	Define a password for the first time, or after a PW RESET. Requires confirmation via the "OK" confirmation method.
CHange newpw <PW=oldpw>	Change your existing password. If you do not include your old password for authentication, LISTSERV will require confirmation via the "OK" confirmation method.
RESET	Reset (delete) your password. This function always requires confirmation via the "OK" confirmation method.

SENDme

Same as GET

The following commands are available on VM servers only:

AFD

Automatic File Distribution. The functions are as follows:

ADD fn ft <filelist <prolog>>	Add file or generic entry to your AFD list
DELete fn ft <filelist>	Delete file(s) from your AFD list (wildcards are supported)
List	Displays your AFD list

For node administrators:

FOR user ADD/DEL/LIST etc

Perform requested function on behalf of a user you have control over (wildcards are supported for DEL and LIST)

FUI

File Update Information: same syntax as AFD, except that FUI ADD accepts no 'prolog text'

GIVE fn ft <filelist> <TO> userid

Sends a file stored in a LISTSERV file archive to someone else. For instance, you may want to send LISTSERV REFCARD to a new user. Rather than retrieving LISTSERV REFCARD and then forwarding it to the user, you simply issue the command
GIVE LISTSERV REFCARD joenewuser@hishost.com

6.1.5. Other (advanced) commands

DISTribute <type> <source> <dest> <options>

Distribute a file or a mail message to a list of users (see Chapter 11 for more details on the syntax). The various parameters are, briefly:

Type:

MAIL	Data is a mail message, and recipients are defined by '<dest>'
FILE	Data is not mail, recipients are defined by '<dest>'
RFC822	Data is mail and recipients are defined by the RFC822 'To:'/'cc:' fields

Source:

DD=ddname

Name of DD holding the data to distribute (default: 'DD=DATA')

Dest:

<TO> user1 <user2 <...>>	List of recipients
<TO> DD=ddname	Use a DD called ddname for the destination addresses, one recipient per line

Options for the general user:

ACK=NOne/MAIL/MSG	Acknowledgement level (default: ACK=NONE)
CANON=YES	'TO' list in 'canonical' form (uid1 host1 uid2 host2...)
DEBUG=YES	Do not actually perform the distribution; returns debug path information
INFORM=MAIL	Send file delivery message to recipients via mail
TRACE=YES	Same as DEBUG=YES, but file is actually distributed

Options requiring privileges:

FROM=user	File originator
FROM=DD=ddname	One line: 'address name'

FOR user command

Execute a command on behalf of another user (for LISTSERV maintainers). Note that generally this command should not be used for normal production purposes.

GETPost listname post_number <post_number...>

(New for 1.8c)

GETPost is used after receiving the output of a SEARch command to retrieve the postings you want from the SEARch output. For instance, if you want postings numbered 1730, 1731, 1732, and 1840 from the MYLIST list, send the command

GETPost MYLIST 1730-1732 1840

GETPost is analogous to the VM database command PRINT.

Search

(New for 1.8c)

For lists running on VM servers, see also below at DATABASE.

The Search command syntax is similar to that of the SEARCH/SELECT commands in the "old" database functions. A very basic Search command for list MYLIST would look like this:

Search search_string IN MYLIST

You can also restrict your search by date, sender, or other criteria, e.g.,

Search search_string IN MYLIST SINCE 96/01/01
Search search_string IN MYLIST WHERE SENDER CONTAINS ERIC

etc. See section 3 of Appendix E for more information on the specific syntax. Note that the new Search command does not require a CJLI job framework to operate; simply send the Search command in the body of an email message to the appropriate server. LISTSERV will respond with an index of the postings matching your criteria and instructions on how to use the GETPost command to retrieve the posts you want.

SERVE user

Restore service to a user whose access to LISTSERV has been disabled. This generally occurs when a user has sent 51 incorrect commands (raised from 21 in 1.8b) in a row to LISTSERV, which LISTSERV interprets as a possible mail loop. (Note also that certain mail packages that send "Read:/Not Read:" notifications back to LISTSERV will trigger this scenario after 51 iterations. The best solution would be for the user to disable receipt notifications.) The user in question cannot restore his or her own service; this command must be issued from another userid. Note that if the user has been manually served out by privileged user (a LISTSERV maintainer), the SERVE command must be issued by a similarly-privileged user (who must also be a LISTSERV maintainer, although naturally the same user who issued the SERVE OFF command can issue the SERVE command).

THANKs

You can send this command to check to see if the server is alive. If it is, the server politely responds, "You're welcome!".

The following commands are available only on VM servers:

DATAbase function

Access LISTSERV database(s). The functions are explained in detail in Appendix E, but the basic syntax is:

Search DD=ddname <ECHO=NO>	Perform database search (see Appendix E for more information on this)
List	Get a list of databases available from that server
REFRESH dbname	Refresh database index, if suitably privileged

Dbase

Same as DATABASE

6.2. List Owner and File Owner Commands

6.2.1. File management commands (for file owners only)

PUT fn ft <filelist <NODIST>>

Update a file you own. Options are:

<PW=password>

Supply your password for command authentication

The following options are VM-specific and will not work on the non-VM servers.

The "NODIST" option prevents AFD and FUI distributions when the file is updated. Other available VM only options include:

<CKDATE=NO>	Accept request even if the current version of the file is more recent than the version you sent
<DATE=yymmddhhmmss>	Set file date/time
<RECFM=F <LRECL=nnn>>	Select fixed-format file (not to be used for text files).
<REPLY-TO=user>	Send reply to another user
<REPLY-TO=NONE>	Don't send any reply
<REPLY-VIA=MSG>	Request reply via interactive messages, not mail (Requires NJE connectivity)
<"parameters">	Special parameters passed to FAVE routine, if any

Standard parameters supported for all files:

TITLE=file title

Change file "title" in filelist entry

The following commands are available on VM servers only:

AFD/FUI

Automatic File Distribution privileged commands. In addition to the AFD/FUI functions listed above, a file owner may use the following function:

GET fn ft <filelist>

Get a list of people subscribed to a file you own

GET fn FILELIST <(options>

Special options for filelists:

CTL	Return filelist in a format suitable for editing and storing back
NOLock	Don't lock filelist (use in conjunction with CTL)

REFRESH filelist< (options>

Refresh a filelist you own. The single option is:

NOFLAG

Don't flag files which have changed since last time as updated (for AFD/FUI)

UNLOCK fnFILELIST

Unlock filelist after a GET with the CTL option if you decide not to update it after all

6.2.2. List management functions

Commands that support the QUIET keyword are marked (*)

ADD(*) listname user <full_name>

Add a user to one of your lists, or update his name field. Note that you can substitute an asterisk ("*") for full_name and LISTSERV will substitute "<No name available>" in the list.

listname DD=ddname

Add multiple users, one address/name pair per line

ADDHere(*)

Same as ADD, but never forwards the request to a possibly closer peer

DELete(*) listname user <(options>

Remove a user from one of your lists, or from all local lists if listname is '*'

Global	Forward request to all peers
LOCal	Don't try to forward request to closest peer if not found locally
TEST	Do not actually perform any deletion (useful to test wildcard patterns)

FREE listname <(options>

Release a held list. The single option is:

Global

Forward request to all peers

GET listname <(options>

Get a copy of a list in a form suitable for editing and storing the list and lock it so that other list owners can't modify it until you store it back (or until you or they issue an UNLOCK command). The options are:

Global	Forward request to all peers
HEADer	Send just the header; on the way back, only the header will be updated. This is the recommended way to modify your list header.
NOLock	Do not lock the list
OLD	Recover the "old" copy of the list (before the last PUT)

HOLD listname <(options>

Hold a list, preventing new postings from being processed until a FREE command is sent. The single option is:

Global

Forward request to all peers

MOVE(*) listname user <TO> node

Move a subscriber to another peer. Do NOT use this command to move users from one list host site to another during migration. It is strictly for moving subscribers from one peer to another peer.

listname DD=ddname

Move several subscribers to various peers

PUT listname LIST

Update a list from the file returned by a GET command. This is the standard "PUT command" or "list PUT" referred to throughout this document.

Query listname <WITH options> FOR user

Query the subscription options of another user (wildcards are supported).

* <WITH options> FOR user

Searches all the lists you own for the specified user(s) with the specified option(s).

SET(*) listname options <FOR user>

Alter the subscription options for other users (wildcards are supported when setting options for another user or set of users).

Additional options for list owners:

NORENEW/RENEW	Waive subscription confirmation for this user
NOPOST/POST	Prevent user from posting to list
EDITor/NOEDITor	User may post without going through moderator
REView/NOREView	Postings from user go to list owner or moderator even if user is otherwise allowed to post

UNLOCK listname

Unlock a list after a GET, if you decide not to update it after all, or unlock a list if it has been locked by another list owner or by the LISTSERV maintainer. Note that if you are not the person who originally locked the list, it is considered good practice to ask the person who originally locked the list whether or not they are done with the list before you unlock it.

The following commands are available only on VM servers:

EXPLODE listname <(options>

Examine list and suggest better placement of recipients, returning a ready-to-submit MOVE job.

BESTpeers n	Suggest the N best possible peers to add
Detailed	More detailed analysis
FOR node	Perform analysis as though local node were 'node'
PREFer node	Preferred peer in case of tie (equidistant peers)
SERVice	Check to see that service areas are respected
With(node1 <node2 <...>>>)	Perform analysis as though specified nodes ran a peer
WITHOut(node1 <node2 <...>>>)	Opposite effect

Stats listname (RESET

Resets statistics for the list.

6.3. LISTSERV Maintainer Commands

All LISTSERV maintainer commands require a password for validation when issued by email. Commands issued by TELL or SEND from the local host or via the LCMD utility do not require password validation.

Lists Global All

All known lists, one line per list, sent as a (large!) file. Only LISTSERV maintainers may request this list, as it has become a favorite pastime of Internet mailbombers to issue LIST GLOBAL commands on behalf of users whose mailboxes they wish to bomb. You should direct users who request "the whole list of lists" to L-Soft's CataList service at the WWW URL http://www.lsoft.com/lists/listref.html.

NODESGEN <WTONLY>

Regenerate all LISTSERV network tables, or just compile the links weight file (debugging command). This happens automatically when LISTSERV is rebooted if a new BITEARN NODES file is found. Otherwise you should issue a NODESGEN whenever you update BITEARN NODES.

PUT listname LIST

Create a new list. Requires the CREATEPW for validation when issued from a remote node.

PWC function

Password file management:

ADD user newpw	Define a password for the specified user
DELete user	Delete password for that user
Query user	Query the password of the specified user

REGister name|OFF FOR user

Set or delete a user's SIGNUP FILE entry

SERVE user OFF

Permanently suspend access from an abusive user or gateway (restore with 'SERVE user')

SHUTDOWN

Stop the server. For VM servers, see the VM-specific entry for SHUTDOWN, below.

STOP

Same as SHUTDOWN

The following commands are available only on VM servers:

CMS command_text

Issue a CMS command and get the last 20 lines of response sent back to you, the rest being available from the console log

CP command_text

Issue a CP command and get up to 8k of response data sent to you (the rest is lost)

DATAbase function

Control operation of databases:

DISAble	Disable interactive database access, without shutting down existing sessions
ENAble	Re-enable interactive access
SHUTDOWN	Shut down all interactive database sessions, and disable interactive access

INSTALL function

Software update procedure (LISTSERV-NJE only):

CLEANUP shipment	Remove an installed shipment from the log
CLEANUP BEFORE dd mmm yy	Remove all shipments installed before that date
PASSWORD shipment PW=instpw	Confirm installation of a shipment, when requested by LISTSERV
RELOAD shipment	Attempt to reload a shipment which failed due to a disk full condition
STATus	Get a list of installed "shipments"

OFFLINE

Suspend processing of reader files and disable the GET command

ONLINE

Cancel OFFLINE condition

PUTC fn ft <fm|cuu|dirid> <RECFM=F LRECL=nnn>

Update a CMS file on one of LISTSERV's R/W minidisks; note that this is similar to SENDFILE + RECEIVE or LINK + COPYFILE and should NOT be used to update file-server files

SENDFile fn ft <fm|cuu|dirid>

Request the server to send you a file from one of its disks

SF

Same as SENDFILE

SHOW <function>

In addition to the standard SHOW functions available on other servers, VM servers support the following functions:

BENCHmarks	CPU/disk/paging benchmarks
EXECLoad	Statistics about EXECLOADed REXX files
LSVFILER	Statistics about LSVFILER file cache
PREXX	Statistics about PREXX functions usage
STORage	Information about available disk space and virtual storage

SHUTDOWN <REBOOT|REIPL>

Stop or reboot the server (the two options are synonyms)

Note: some debugging commands and options have been omitted.

7. Creating Lists

You can create and maintain lists from any userid listed in the POSTMASTER keyword of LISTSERV's site configuration file. Note that a LISTSERV maintainer has the authority to GET and PUT any list, filelist, catalog, or archive file on the server (although for any list not set to "Send= Public", the LISTSERV maintainer must be subscribed to the list in order to post to it, and must additionally be a list Editor if the list is set to "Send= Editor...").

7.1. Basic list creation

At its simplest, creating a list is a matter of setting certain keywords to desired values in a file (called the "list header file") and storing the file in a place where LISTSERV can find it. The format of a typical list header file is relatively free-form, with only a couple of rules:

1. All header lines must begin with the character "*" (ASCII 042)
2. All words ending with the character "=" (ASCII 061) are evaluated as keywords
3. The first line of the header file is evaluated as the descriptive name of the mailing list, and will be displayed as such by the LIST command.

Additionally, for PUT operations, you must add a line of the format

PUT listname.LIST PW=password

to the top of the file before mailing it. This PUT line does not begin with an asterisk. (Note that the filename for the list can be either in the format listname LIST or listname.list . The "." character is not necessary, but the word LIST is always necessary.)

Here is a sample of a basic list header with its PUT command at the top:

PUT SAMPLE LIST PW=CCCCCCCC
*
* Title of sample LISTSERV list
*
* Review= Public      Subscription= Open           Send= Public
* Notify= Yes         Reply-to= List,Respect       Files= No
* Stats= Normal,Private   Validate= No
* Notebook= Yes,A,Monthly,Public
*
* Owner= someone@somewhere.com
*
* PW= XXXXXXXX

There are two basic methods to store a list on the server.

1. Read or paste (do not "attach") the list header file (with the PUT command at the top) into a mail message addressed to LISTSERV. If creating the list for the first time, password must be the CREATEPW defined in the site configuration file. If modifying an existing list, password can be either:
   • The list password (defined with the PW= list header keyword); or
   • Your personal LISTSERV password (defined with the PW ADD command).

   This is the preferred method for creating and editing list headers. LISTSERV will respond with a report that either the list has been successfully created or that various problems (fatal and/or non-fatal) have been detected. If only non-fatal problems are detected, the list will be stored anyway (non-fatal problems include no list password having been defined). Any fatal problem detected will abort the storage operation.
   

2. Copy the list header file into LISTSERV's main directory and restart LISTSERV. LISTSERV will log a message to the effect that the list is not formatted properly and will then reformat the list. This assumes that the list header has been constructed properly and that there are no errors in the file that will cause LISTSERV to crash or to reject the list file. This method is useful only for creating lists; never attempt to edit a production list file in place and restart the server. The GET and PUT operations are the only supported methods for editing list files. Particularly under unix and Windows, LISTSERV will not always accept the 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. Method 1 is always preferable to Method 2.

BITNET users may also use the LSVPUT utility to store lists on BITNET-connected servers. However, LSVPUT is not documented here as the number of sites with BITNET connectivity is dropping rapidly and fewer and fewer users will be using LSVPUT.

7.2. Architecture-Specific Steps for List Creation

7.2.1. Unix: Creating required Sendmail aliases

This section is for use only by Unix sites running Sendmail.

Once you have constructed a list header file, and sent it to your Unix LISTSERV server, you need to instruct your mail system to route mail for that new list to the LISTSERV mail interface. That involves adding entries to your aliases file, much as you did when installing the server itself. For each new list, you'll need to add five entries to the aliases file. The format of those lines is as follows,

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

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

• An explicit directory definition, e.g., /var/spool/listserv ; or
• The switch -t , which is equivalent to the value in LSVSPOOL. (Note that the "make list" command makes aliases using -t.)

For example, assuming the default values were chosen for BINDIR and LSVSPOOL, the aliases for a new list called "mylist" (using the -t option) would be,

mylist: "|/usr/local/bin/lsv_amin -t mylist"
owner-mylist: "|/usr/local/bin/lsv_amin -t owner-mylist"
mylist-request: "|/usr/local/bin/lsv_amin -t mylist-request"
mylist-search-request: "|/usr/local/bin/lsv_amin -t mylist-search-request"
mylist-server: "|/usr/local/bin/lsv_amin -t mylist-server"

If you should decide to use the explicit definition for the LSVSPOOL parameter, the aliases would look like this instead:

mylist: "|/usr/local/bin/lsv_amin /var/spool/listserv mylist"

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

7.2.2. VMS: Creating required PMDF aliases

This section is for use only by VMS sites running Innosoft International, Inc.'s PMDF® product, version 4.2 or later.

listname:	listname@LISTSERV
owner-listname:	owner-listname@LISTSERV
listname-request:	listname-request@LISTSERV
listname-search-request:	listname-search-request@LISTSERV
listname-server:	listname-server@LISTSERV

7.3. A sample checklist for creating lists

1. Check to see that the list name is legal and not duplicated elsewhere
2. If Notebook= Yes, then make the appropriate directory
3. If Notebook= No but Digest= Yes, then make the appropriate directory
4. Optionally, add the list to the quota file (ISP scope licenses only; see chapter 19 for details)
5. VM: Optionally, make a listname.FILELIST for this list (see chapter 8 for details)
   Non-VM: Optionally, make an entry in SITE.CATALOG for a sub-catalog belonging to this list (see chapter 8 for details)
6. Create and store the list header with the list owner and you as the only subscribers
7. Architecture-specific steps:
   • Unix, running Sendmail: Create the required Sendmail aliases for the list, either by hand or by using 'make list name=listname' . Note that this is a required step for unix servers; if you don't make the Sendmail aliases, the list won't work. See section 7.7.1 for details.
   • VMS, running PMDF®: Create the required PMDF aliases for the list in PMDF_ROOT:[TABLE]ALIASES. Note that this is a required step for VMS servers running PMDF; if you don't make the aliases, the list won't work. See section 7.7.2 for details.
8. Send a boilerplate "your list has been created" message to the list as the final test that the list works--if it doesn't, go back and find out why, then return here. See Appendix F for a sample boilerplate message for this step.
9. Delete yourself from the list (assuming you don't want to be subscribed)

At this point the list should be ready for use.

7.4. Naming Conventions

When naming a list, there are a few conventions and restrictions that you should keep in mind.

The "-L" convention

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 characters

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
%	another addressing character that could cause problems
&	is sometimes reserved by non-unix systems. 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 slash character is reserved and can't be used in file names.

It is best if you avoid the use of special characters altogether and stick exclusively to the letters A-Z and numbers 0-9 when naming lists. The "-" character is also legal, but note that the "_" (underscore) character may cause problems with some non-compliant receiving systems. Also note that the space character (ASCII 32) is illegal in a list name.

If you have any question about the validity of a particular name, you can of course refer to RFC822 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)

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.

Make it easy on your users

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).

7.5. 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. We will discuss these keywords in detail in subsequent chapters, and 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 who) 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), whether or not the list is protected by a password, 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.

7.6. Retrieving and editing the list - some considerations

If you want to change header keyword settings only, it is probably advisable to issue the GET command with 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.

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:

(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: 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).

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:

7.7. Adding a list password (obsolete in 1.8c)

This section is retained for compatibility with those sites still running 1.8b or earlier.

When creating the list, the LISTSERV maintainer should assign a password for the list. However, note that in 1.8c if the LISTSERV maintainer does not assign a password at the time of the list's creation, LISTSERV will generate a random password for the list. This random password can be changed later, but until and unless it is changed, administrators must provide their personal LISTSERV password (created with the "PW ADD password" command) when updating the list.

* PW=MYPASSWD

Replace "MYPASSWD" with the word chosen. Note that there should not be a space between "PW=" and the password. The list password is never changed unless specified explicitly in the list header when it is stored on the server. For additional security, the list password will not appear in the list header on subsequent GETs; to all intents and purposes it is invisible once it is assigned.

L-Soft's position on list passwords is that they have become obsolete with version 1.8c, and that personal passwords should be used instead to validate commands (such as the PUT command).

7.8. Storing the list on the host machine

(If you are creating a list, see 7.1. These instructions are for storing a list once it already exists on the server, for instance, if changes have been made to the list header after a GET operation.)

When you are ready to store your list 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. 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. (For instance, creating a list with no list password defined in the header will generate a "soft" error, and the list will be stored. On the other hand, setting a list to "Send= Editor" and not defining an editor with "Editor=" is considered a "hard" error, and you will have to fix the error before LISTSERV will accept the list for storage.)

Caution: If you are using a mailer such as Eudora, Pegasus, 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.

Also, be sure to turn off your signature file (if you use one) before sending a PUT command to LISTSERV. If you don't, LISTSERV will attempt to parse the data in your signature file as RFC822 addresses to be added to the list, and you will receive an error to the effect that the file includes invalid RFC822 addresses and it has therefore not been stored.

7.9. Fixing mistakes

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.

It is also possible for the LISTSERV maintainer to restore the list by deleting or moving the listname.LIST file from LISTSERV's A directory and renaming the listname.OLDLIST file to listname.LIST. Naturally this method requires that the LISTSERV maintainer in question have appropriate access to LISTSERV's files and directories or be able to log in as the 'listserv' user.

7.10. A sample list header file

A basic list header file for a list to be created might look like this (CREATEPW is replaced with the appropriate password):

PUT MYLIST.LIST PW=CREATEPW
* The Descriptive Title of My List
*
* Owner= NATHAN@LSOFT.COM (Nathan Brindle)
* Notebook= Yes,A,Monthly,Public
* Errors-To= Owner
* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No              
* Files= No                Validate= No
* Reply-to= List,Respect   Review= Public
* Send= Public
* Default-Options= NoFiles,NoRepro*                                                                                                  
* This list installed on 96/06/02, running under L-Soft's LISTSERV-TCP/IP 
* version 1.8c for Windows NT.
*
* Comment lines...*

A list owner might take the created list and modify it as shown below. Note that the PUT command has been modified to include the password assigned by the LISTSERV maintainer, and note also the PW= keyword in the body of the list header which will define a new password.

PUT MYLIST.LIST PW=MYPASSWD
* The Descriptive Title of My List
*
* Owner= NATHAN@LSOFT.COM (Nathan Brindle)
* Owner= Quiet:
* Owner= nathan@linus.dc.lsoft.com
* Owner= ncbnet@linus.dc.lsoft.com
* Notebook= Yes,A,Monthly,Public
* AutoDelete= Yes,Full-Auto
* Errors-To= ncbnet@linus.dc.lsoft.com
* Subscription= Open,Confirm
* Ack= Yes                 Confidential= No              Notify= No
* Files= No                Mail-Via= Distribute          Validate= No
* Reply-to= List,Respect   Review= Public                Send= Public
* Stats= Normal,Private    X-Tags= Yes
* Default-Options= NoFiles,NoRepro
* PW=NEWPASSWD
*                                                                                                  
* This list installed on 96/06/02, running under L-Soft's LISTSERV-TCP/IP 
* version 1.8c for Windows NT.
*
* Comment lines...
*

7.11. Deleting a list

For security reasons, LISTSERV does not have an explicit command for deleting lists. The LISTSERV administrator simply deletes the list file from the system command prompt with the appropriate file system command (CMS ERASE for VM, DEL for VMS, ERASE for Windows, rm for Unix). A suggested procedure for deleting an established list (one with archives and so forth) follows:

1. Back up any files you wish to keep, such as notebook archives
2. For a digested list, you may want to send a QUIET SET listname NODIGEST FOR *@* command. This will cause LISTSERV to send out its accumulated digest to those who were set to DIGEST mode. If the list hasn't been active or if it's not digestified, you don't need to take this step.
3. Delete the listname.LIST file with the appropriate file system command.

7.12. How to set up lists for specific purposes

7.12.1. Edited lists

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 referreed 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 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

7.12.2. Moderated lists

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 an identical message has already been posted to the list.

If "Send= Editor" (e.g., without "Hold"), please note that if a notation 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. 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.

The "Hold" and "Confirm" options for "Send=" can also be used with these examples, if desired. L-Soft recommends that "Confirm" be used by default.

7.12.3. Semi-moderated lists

"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.

7.12.4. Self-moderated lists

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.

7.12.5. Auto-responders

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.

7.12.6. Announce-only lists

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
* Owner= yetanotheruser@myhost.com
* Editor= foo@myhost.com
* Editor= anotheruser@myhost.com
* Editor= 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".

7.12.7. Peered 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.)

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.

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]

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.

7.12.8. "Super-lists" and "sub-lists"

In LISTSERV 1.8c 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.

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.

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.

7.12.9. "Cloning" lists

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

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

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.

7.13. Migrating lists from one site to another

In migrating lists to LISTSERV, there are three typical possibilities:

1. You are migrating lists from an existing LISTSERV site (e.g., moving from VM to unix)
2. You are migrating lists from a non-LISTSERV site to LISTSERV
3. You are creating a LISTSERV list from a Sendmail alias or other database of e-mail addresses

7.13.1. Migrating lists from one LISTSERV site to another LISTSERV site

Naturally, this is the simplest migration, but it still requires a few important steps. The preferred method (and the one that generally works the best) is to GET the list from the old server, make any changes necessary to the header (e.g., location of Notebook archives) and PUT the resulting list file on the new server. This method (assuming no corruption or reformatting of the list file by intervening mail systems) is preferred because it involves LISTSERV's internal syntax checking and other error-handling functions, LISTSERV knows exactly where to put the files, and the migration isn't restricted by possible architecture-specific problems.

The drawback to the preferred method is that you have to migrate one list at a time, which may not be acceptable if you need to migrate many lists in a short period of time. In general, you can simply FTP your list files from the old server to the new server, but note the following:

• You can migrate only from VM to non-VM, or from non-VM to non-VM. You cannot migrate using the FTP method from non-VM back to VM (unless you are prepared to reconstruct your list files and so forth from scratch). Naturally a GET and PUT will work if you need to move from non-VM to VM.
• If migrating from VM to non-VM: Be sure to FTP the list files, archives, and so forth in ASCII mode. If you use binary mode, the files will be unreadable on your new system.
• If migrating from non-VM to non-VM, please note that if moving the files by FTP does not work, you will have to migrate the list using the preferred method outlined above. You could also create a new list header on the new server and add the users with an ADD IMPORT job as detailed in the next section.
• Once you have FTP'd the files to the new server, decide where you want things to go. The list file itself should go into LISTSERV's A directory (typically ~listserv/home on unix systems, LISTSERV\MAIN on Windows systems, and [LISTSERV.MAIN] on VMS systems). You may want to make a separate directory on your new server for archives, then subdirectories of that directory for each list. If so, make the appropriate directories and move the archive files there. (This is particularly important if you intend to use the ISP options such as the file quota subsystem.) If you are copying non-notebook archives, you should read the chapter on Notebook and File Archives, below, in order to set up a filelist or catalog file for these files.
• Next, you should restart LISTSERV. This is particularly important when moving lists from VM to other platforms, as LISTSERV will need to reformat the file into the binary format used on non-VM machines. If this is successful, you will see two messages in the console log:

  6 May 1996 12:50:14 Invalid record format for list XXXXX-L.
  6 May 1996 12:50:14 -> List reformatted successfully.

  If this is not successful, you will need to open the list file in a text editor and look for anything that might have caused a problem. Note that list header lines have a limit of 100 characters in length.

• Before releasing the list to the general public, be sure to GET the list header and make any changes that need to be made. Typically, changes will need to be made to the location parameters of the Notebook= and/or Digest= keywords, particularly if you are moving from one platform to another.

Note that the first digest sent from the new site will say "First ever".

7.13.2. Migrating lists from non-LISTSERV sites

Non-LISTSERV list files (notably from Majordomo and ListProc, but from other MLM software as well) are not directly compatible with LISTSERV. While it is probably possible to write a script or batch file for the purpose of converting one format to the other, it is outside the scope of this manual to describe this process.

Majordomo users will note that LISTSERV does not require two separate lists for those who want individual messages and those who want digested summaries. LISTSERV handles digesting internally for those who have set the personal option DIGEST for the list. Thus those sites migrating to LISTSERV from Majordomo will probably want to merge the digested and non-digested subscribers into one single list and let all subscribers know that they can set themselves to DIGEST mode with the SET listname DIGEST command. (It would also be possible to send commands to LISTSERV to set all of the old digest subscribers to DIGEST before releasing the list to the public.)

In general, the method recommended by L-Soft for migrating a non-LISTSERV list into LISTSERV format is the following:

• Create a list header for your list as noted above and store it on the LISTSERV server. If you plan to set "Validate=" to any value but "No", set it to "No" until the following steps are completed.
• Create a LISTSERV command language job as follows:

  QUIET ADD listname DD=X IMPORT
  //X DD *
  internet-address1
  internet-address2
  /*

  where "listname" is the name of the new list, and "internet-address1", "internet-address2" and other users are the internet addresses from the original list that you want to add to the new list. Optionally, you can add the user's "real name" field, e.g.,

  QUIET ADD listname DD=X IMPORT
  //X DD *
  internet-address1 full_name
  internet-address2 full_name
  /*

  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.

• Send the command language job to LISTSERV.
• You will receive in return a confirmation that the job executed and whether or not it was successful, e.g.:

  > QUIET ADD XXXXX-L DD=X IMPORT
  ADD: no error, 2 recipients added, no entry changed, none forwarded.

List archive notebooks from non-LISTSERV sites can be copied into a file archive area for the list and registered in the listname.FILELIST (VM) or listname.CATALOG (non-VM), but it is not recommended that non-LISTSERV notebooks be renamed with LISTSERV naming conventions, as this may cause problems with LISTSERV's database functions. For instance, if you have ListProc or Majordomo notebook archives that were kept monthly, L-Soft does not recommend renaming them with the listname.logyymm format.

7.13.3. Migrating lists from Sendmail alias files, databases, etc.

In general, you will follow the same procedure outlined in 7.13.2 to migrate from these types of lists. You may wish to write an executable script of some sort to pull the addresses and names (if you have them) from your database and surround them with the appropriate CJLI commands, particularly if your database is made from a web site and you need to run a periodic job to add users to your lists.

7.14. Adding HTML to a list header for the CataList

L-Soft's CataList service allows users to search the global list of 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 the list owner or LISTSERV maintainer has to do is update the 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.

7.14.1. Update latency

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.

7.14.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:

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>

7.14.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 &#61; instead.

8. File and Notebook Archives

There are three file server systems currently in use by LISTSERV:

• The VM (mainframe) version of LISTSERV continues to support the "traditional" file server system. While it is very powerful, this file server system dates back to 1986 and suffers from a few annoying limitations. In addition, it is written in a non portable language. This will be replaced with the "new" file server system, currently under development.
• The non-VM versions of LISTSERV 1.8c introduce a new file server system which includes most of the functionality of the "traditional" file system. Most end user commands will continue to work as before. However, there is no guarantee that the internal data files manipulated by the file server functions will remain as before. Note that SITE.CATALOG files from versions 1.8a and 1.8b are still supported and will not need to be changed in order to work with 1.8c.
• The workstation and PC versions of LISTSERV 1.8a and 1.8b support a "temporary" file server system, to provide an interim solution while the new system is being developed. This temporary system only supports a subset of the functions of the traditional system. This system is no longer supported by L-Soft as it has been superseded by the new non-VM file server referenced above.

Since the first two systems will eventually be replaced by the third system, rather than providing an exhaustive chapter detailing all filelist aspects from the management side, we have provided only a basic overview of the two systems currently in the field with 1.8c, with pointers to where further information may be obtained.

8.1. What is the file archive?

The file archive consists of all files other than notebook logs that have been stored on the LISTSERV host for your list. Users can find out what files are available for a specific list by sending the command INDex listname to the appropriate LISTSERV host.

8.2. Starting a file archive for your list

On VM Systems ONLY

With the traditional system (running on the VM servers), the LISTSERV maintainer creates files called "xxxx FILELIST", which contain definitions for all the files belonging to a particular archive. These FILELIST files must be created by the LISTSERV maintainer at the site before they can be edited by the list owner.

On Workstation and PC Systems

The LISTSERV maintainer stores "root-level" file definitions in a file called SITE.CATALOG, which should be placed in the same directory with the SYSTEM.CATALOG file. Beginning with 1.8c, the LISTSERV maintainer can also define "sub-catalogs" which in turn can define further files. You should be aware of the differences between VM and workstation file server functions as many people are using and will continue to use the VM file server with different conventions, and may give you incorrect advice. Non-VM sites should skip section 8.3, and use the information below in section 8.4 to maintain their file archives.

8.3. Filelist maintenance (VM systems only)

8.3.1. Creating a filelist

[THIS SECTION HAS NOT YET BEEN WRITTEN. In the interim, please see FSV GUIDE for details.]

8.3.2. Adding FAC codes

[THIS SECTION HAS NOT YET BEEN WRITTEN. In the interim, please see FSV GUIDE for details.]

8.3.3. Retrieving the filelist

To retrieve your filelist in an editable format, send the command

GET listname FILELIST PW=XXXXXXXX (CTL

to the LISTSERV host where the filelist is stored. The (CTL switch causes LISTSERV to lock the filelist until you store it again or explicitly unlock it with an UNLOCK listname FILELIST command. (If you don't want to lock the filelist, use (CTL NOLOCK instead.) If your mail account is not located on the same host as LISTSERV, you will need to provide your personal password (same as your password for getting and putting your lists).

A filelist retrieved with the (CTL option does not look like the filelist you get with an INDEX command. A sample (CTL option filelist appears below:

*  Files associated with MYLIST and available to subscribers:
*                             rec               last - change
* filename filetype   GET PUT -fm lrecl nrecs   date     time   Remarks
* -------- --------   --- --- --- ----- ----- -------- -------- --------
  MYLIST   POLICY     ALL OWN V      79    45 94/03/16 12:04:23 Mission Statement
  MYLIST   BOOKLIST   ALL OWN V      79   177 94/04/19 16:24:57 Books of interest
  MYLIST   QUARTER    ALL OWN V      73   113 95/03/11 08:57:04 Quarterly posting

*  Listowner's files (not public)
  MYLIST   FAREWELL   OWN OWN V      78     9 95/03/11 08:53:41 Goodbye memo
  MYLIST   WELCOME    OWN OWN V      73   105 95/03/11 09:14:38 Hello memo

Figure 8.1. Sample filelist retrieved with (CTL option.

Note that the filelist does not include the comment lines you would normally see at the top of an INDEX filelist; nor does it include any notebook archives. LISTSERV creates these lines dynamically at the time the INDEX command is received from a user. If the filelist you have retrieved has any of this kind of material in it, either a) you have not retrieved the filelist correctly, or b) you or someone else has stored the filelist previously with this material included. If you did a GET with (CTL, you should be able to remove these extraneous lines by simply deleting them.

If you do an INDEX of your archive and it has (for instance) two sets of comment lines or duplicate notebook archive listings, then you should GET the filelist with (CTL and edit out the offending lines. While the extra lines will not affect the operation of the file server, they are a source of potential confusion for your users.

8.3.4. Adding file descriptors to the filelist

"Adding a file to a filelist" is not exactly accurate terminology, although it is a widely-used phrase. Adding files to file archives is a two-step process: First, add a file descriptor to the appropriate filelist and store the filelist on the server. Second, store the file itself on the server.

To add a file descriptor, start a line with a space and then type in your file's name, access codes, five dots (periods) and a short description, each separated by a space. For example:

MYLIST FAQ ALL OWN . . . . . Frequently-Asked Questions for MYLIST

Note that the line must begin with a space. Also, you must place five dots separated by spaces between the PUT file access code (here it is OWN) and the short description. These dots are place holders for the record format (recfm), longest record length (lrecl), number of records (nrecs), and the date and time of the last update. If these dots are not present, LISTSERV will return an error message when you try to store the filelist.

You will note that the line you have just added does not look like the other lines in the filelist. Ignore the "pretty" formatting. LISTSERV will reformat the information for you. After adding the line, your filelist should look like this:

*  Files associated with MYLIST and available to subscribers:
*                             rec               last - change
* filename filetype   GET PUT -fm lrecl nrecs   date     time   Remarks
* -------- --------   --- --- --- ----- ----- -------- -------- --------
  MYLIST   POLICY     ALL OWN V      79    45 94/03/16 12:04:23 Mission Statement
  MYLIST   BOOKLIST   ALL OWN V      79   177 94/04/19 16:24:57 Books of interest
  MYLIST   QUARTER    ALL OWN V      73   113 95/03/11 08:57:04 Quarterly posting
 MYLIST FAQ ALL OWN . . . . . Frequently-Asked Questions for MYLIST

*  Listowner's files (not public)
  MYLIST   FAREWELL   OWN OWN V      78     9 95/03/11 08:53:41 Goodbye memo
  MYLIST   WELCOME    OWN OWN V      73   105 95/03/11 09:14:38 Hello memo

Figure 8.2. Adding a file descriptor to the filelist

Note that you can add comment lines to the filelist by placing an asterisk in the left-most column instead of a space. Comment lines can act as indexes, descriptions, or pointers to other resources.

Once you are finished adding file descriptors, save the filelist to disk.

8.3.5. File Access Codes (FAC) for user access

FACs define which users have access to files in the file archive. The FAC for GET indicates who may retrieve the files, and the FAC for PUT indicates who may store the files on the server. (Note that some special FACs exist for "superusers" such as the LISTSERV maintainer(s) and the LISTSERV Master Coordinator, who may GET and PUT any file regardless of its GET/PUT permissions.)

The basic FAC codes that are always available for VM servers are:

ALL universal access.

PRV only members of the associated mailing list have access.

OWN only the owners of the associated mailing list have access.

(The FAC codes PRV and OWN work only on the VM filelist system. They do not work on the non-VM catalog system. See section 8.4 if you are configuring the non-VM systems.)

(Note that this assumes the name of the filelist is identical to the name of the associated mailing list - for instance, MYLIST@FOO.BAR.EDU would have a MYLIST LIST file and a MYLIST FILELIST file. Ask your LISTSERV maintainer for assistance if this is not the case or if you need special FACs added for special user access to files.)

8.3.6. Deleting file descriptors from the filelist

Before you delete file descriptors from the filelist, you should delete the files themselves from LISTSERV's archive disk. See section 8.6, below, for instructions.

If this step is not followed, LISTSERV may not be able to find the file you want to delete after you edit the filelist and store it.

8.3.7. Storing the filelist

1. Create a mail message to LISTSERV at the appropriate host. (Sending a filelist to LISTSERV@LISTSERV.NET will not work. The filelist must be sent to the host it resides on.)

2. Include the filelist file as plain text in the body of the mail message. Do not attach it with MIME or another encoding scheme, as LISTSERV does not translate encoded messages.

3. Make sure that your mail client does not automatically add a signature file to the bottom of your mail. If it does, your signature file will be treated as part of the filelist and will be stored along with it.

4. At the top of the filelist, add a single line as follows:

   PUT filename FILELIST PW=XXXXXXXX

   where XXXXXXXX is your personal password for LISTSERV on that host. Note that this is similar to the PUT command used when storing the list file.

5. Send the filelist to LISTSERV.

8.4. The listname.CATALOG system on non-VM systems (new for 1.8c)

LISTSERV version 1.8c introduces a new file archive registration system similar to (but differing in important respects from) the old VM FILELIST system. This new system is available on the VMS, unix, and Windows ports only. VM sites will continue to use the old FILELIST system indefinitely as it still offers more functionality than the new system.

Files to be made generally available to users (e.g., not specific to any one list on your server) should still be registered in the site.catalog file as before.

The new file archive system makes it possible to specify filenames in native OS format in the catalogs. Thus, you can now write:

MY.FILE        /home/lists/xyz/my.file     ALL JOE@XYZ.COM

instead of:

MY.FILE        my.file./home/lists/xyz     ALL JOE@XYZ.COM

All examples will be given in the new native format. The old format remains supported for compatibility. However, note that you MUST use the old format if any of the directories in the path contains a period.

The new syntax does not remove the restriction that all files manipulated by LISTSERV must be accessible through LISTSERV's OS-independent file access methods. This means that files whose name contains spaces or control characters (or, under unix, mixed case characters) cannot be accessed. Similarly, files whose name does not contain a period cannot be manipulated by LISTSERV. There is no limit on the length of the file name, only on its contents. Note that these "system filenames" are not visible to the end users, who refer to the file in the above example as MY.FILE (or my.file - LISTSERV is not case sensitive).

8.4.1. Adding files to the default SITE.CATALOG

This is the most basic way to add files to LISTSERV's file archive system so they can be made available to users via the GET command.

To register a new file to the server on workstation systems, the LISTSERV maintainer adds a line to the SITE.CATALOG file. Here is what a typical SITE.CATALOG entry looks like under Windows NT:

MY.FILE C:\FILES\XYZ\MY.FILE XXX YYY

And the same entry under Unix would look like this:

MY.FILE /files/xyz/my.file XXX YYY

(Note that under Unix, LISTSERV does not observe case-sensitivity internally. Therefore you cannot define two different files with the same non-case-sensitive filename. In other words, LISTSERV will not differentiate between MY.FILE and my.file, or even My.File. But note carefully that the physical files you store must be named in lower-case; in other words, the output of an 'ls' command must show my.file, not MY.FILE or My.File. LISTSERV will handle this issue automatically when you PUT the files, but be forewarned if you store the files on the server via ftp or the Unix file system.)

Finally, here is a VMS example:

MY.FILE [XYZ:FILES].MY.FILE XXX YYY

The first item, MY.FILE, is the name by which the file is known to LISTSERV. That is, the users will use GET MY.FILE to order a copy of that file. The name should only contain one period. Only the first 8 characters of the name and the first 8 characters of the extension are shown by the INDEX command. This restriction will be removed with the new file server system.

The second item, for instance C:\FILES\XYZ\MY.FILE, is the name LISTSERV will use for the actual disk file, in native OS format. Note that the directory must be created before you register the file. For security reasons, LISTSERV will not create the directory (or set the protections) for you. Note that LISTSERV will normally need full access to these files.

The third and fourth items are "File Access Codes" (FACs). The first is for read accesses, and the second for writing. The following file access codes are available for non-VM servers (for VM FAC codes, see 8.3.5, above):

ALL universal access.

PRIVATE(xxx) only members of the xxx list have access.

OWNER(xxx) only the owners of the xxx list have access.

SERVICE(xxx) only users in the service area of the xxx list have access.

NOTEBOOK(xxx) same access as the archives of the xxx list.

user@host the user in question is granted access.

Except for ALL, which must occur on its own, multiple file access code entries can be specified, separated by a comma with no intervening space. For instance:

MY.FILE C:\FILES\XYZ\MY.FILE JOE@XYZ.EDU,JACK@XYZ.EDU,PRIVATE(XYZ-L) CTL

defines a file that Joe, Jack and the subscribers of the XYZ-L list can order via the GET command, but that only the LISTSERV administrator can update.

8.4.2. Delegating file management authority

The sub-catalog enhancement allows the LISTSERV administrator to delegate file management authority in a controlled and secure manner. Multiple list owners can be given the authority to maintain their own sub-catalog in a predefined directory. With the LISTSERV-ISP add on (under development), a quota can be imposed on the directory in question.

The procedure works as follows:

1. The LISTSERV administrator creates the sub-catalog and identifies the directory where the files will be stored, and the person(s) who will be in charge of managing it ("catalog owners").
2. The catalog owners use the GET and PUT commands to update their catalog and register new files in their directory. Each file has the usual GET and PUT file access codes, allowing the catalog owners to further delegate the management of individual files to third parties ("file owners").
3. The file owners manage the files in question using the GET and PUT commands. Authorized users can retrieve the files using the GET command.

Note that this functionality is available in the VM version, using a different syntax. See Chapter 8.3, above, for information on managing the VM file archive system.

If you are migrating from VM to one of the non-VM versions of LISTSERV, please note that it is not necessary to create a subcatalog file for WELCOME, FAREWELL and MAILTPL files. If a subcatalog for these files is not created, they do not appear in the output of an INDEX command. However, there are two ways to force them to appear:

1. As the result of an INDEX command without qualifier: simply define the file in SITE.CATALOG.
2. As the result of an INDEX listname command: simply define the file in the listname.CATALOG.

8.4.3. Creating a sub-catalog

To create a sub-catalog, the LISTSERV administrator edits the file called SITE.CATALOG (or site.catalog under unix) in LISTSERV's main directory (the directory where SYSTEM.CATALOG/system.catalog is located). A sub-catalog is defined as follows:

MY.CATALOG     /home/lists/xyz/my.catalog  ALL JOE@XYZ.COM

(1)            (2)            (3)          (4) (5)                       

(1) The name must end in '.CATALOG', but otherwise it can be anything. In particular, there does not need to be a list by that name.

(2) The directory specification indicated for the catalog file (e.g., /home/lists/xyz) is where ALL the files defined in the sub-catalog will be stored. DO NOT USE LISTSERV'S MAIN DIRECTORY FOR THIS PURPOSE! The catalog owner will be given FULL ACCESS to all the files in this directory, so make sure to create a new, empty directory. If the sub-catalog is being set up for a list owner, it may be a good idea to put the list archives and the sub-catalog in the same directory.

(3) A file name must be provided for the sub-catalog file itself. This name, however, does not need to match (1).

(4) This file access code controls the authority to INDEX the sub-catalog. This will also be the default GET access code for all the files registered in the sub-catalog.

(5) This file access code defines the catalog owner(s) and default file owner(s) for all the files in the sub-catalog.

Note that there is no need to reboot LISTSERV after updating the SITE.CATALOG file. Also, bear in mind that you are responsible for the OS-level security of the directory you create for the catalog. The file access codes in SITE.CATALOG only affect operations that go through LISTSERV; it is your responsibility to make sure that other users of the computer are given the appropriate access level to any directory you create for LISTSERV's purposes.

8.4.4. Updating the sub-catalog

Once the sub-catalog is created, the catalog owner(s) can register new files using the following procedure (in this example, it will be assumed that the sub-catalog is called MY.CATALOG):

1. Send a GET MY.CATALOG command to LISTSERV (or, if the catalog is brand new, start from an empty file).
2. Register new file(s) in the catalog (see below).
3. Use the PUT MY.CATALOG PW=XXXXX command to store the updated catalog.

Alternatively, if the catalog owner has an account on the LISTSERV host system and write access to the directory associated with the sub-catalog, the file can be edited directly. Note however that, in that case, the LISTSERV-ISP quota system will be inoperative as it has no control over disk accesses which do not go through LISTSERV itself.

The format of sub-catalogs is similar to that of SITE.CATALOG:

MY.FILE        my.file                     ALL JOE@XYZ.COM

(1)            (2)                         (3) (4)                      

Notes:

(1) This defines the name of the file as seen by LISTSERV users. That is, the command to retrieve the file will be GET MY.FILE.

(2) This defines the name of the actual disk file where the contents of MY.FILE will be stored. Normally, you should specify the same as (1), or just an equal sign (LISTSERV will then substitute the name you provided for (1)). However, in some cases you may want to make a particular file available under multiple names. This can be done by registering multiple files (ie multiple values for (1)), and using the same (2) value every time.

(3) This file access code determines who can order the file through a GET command. See section 8.4.1, above, for more information on FAC codes.

(4) This file access code determines who can update the file with the PUT command. See section 8.4.1, above, for more information on FAC codes.

Note: (2) defaults to the value of (1), and (3) and (4) default to the GET and PUT access codes of the sub-catalog itself, respectively. So, in most cases a sub-catalog entry will be as simple as:

MY.FILE

Additionally, comment lines (starting with an asterisk) or blank lines can be interspersed with file definitions. These comments will be echoed when the sub-catalog is indexed (see below), in sequence with the file definitions. For instance, your catalog could read:

*
* Files for the XYZ sub-project
*
XYZ.AGENDA
XYZ.BUDGET
XYZ.PROPOSAL-1
XYZ.PROPOSAL-2

8.4.5. Indexing the sub-catalog

If MY.CATALOG is defined as:

MY.CATALOG     /home/lists/xyz/my.catalog  xxx JOE@XYZ.COM

then any user who matches the 'xxx' file access code is authorized to issue an INDEX MY command to get a formatted version of the catalog. For compatibility with older versions of LISTSERV, GET MY.FILELIST will produce the same results. If there is a mailing list called MY, a list of the archive files will be appended automatically.

8.5. Storing files on the host machine

To store a file on any LISTSERV host, first ensure that it has been registered with an entry in a filelist or the site catalog. Then mail the file to LISTSERV with a single line at the top of the document:

1. Edit your file and save it. Add a single line at the top of the file as follows:

   PUT filename.extension PW=XXXXXXXX

   (This line will not appear to people who GET the file from LISTSERV.) Replace XXXXXXXX with your personal password.

2. Be sure that the file has been registered with an entry in a filelist or the site catalog.
3. Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the new or edited file. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command.
4. Send the mail message to LISTSERV.

8.6. Deleting files from the host machine

To delete a registered file on any LISTSERV host:

1. Create a new mail message addressed to LISTSERV. Add a single line at the top of the message as follows:

   PUT filename.extension PW=XXXXXXXX (DELETE

   Replace XXXXXXXX with your personal password.

2. Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the delete job. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command.
3. Send the mail message to LISTSERV.
4. LISTSERV will tell you that the file has been successfully deleted.
5. For VM Systems ONLY: GET the listname FILELIST for your list and delete the line for the file you've just deleted. PUT the listname FILELIST back on the server.
6. For Workstation and PC Systems ONLY: GET the catalog file in which the deleted file is registered and delete the line for the file. PUT the catalog file back on the server.

   8.7. Automatic File Distribution (AFD) and File Update Information (FUI)

   AFD and FUI have not yet been ported to the workstation and PC environments. However, this feature is supported on VM and will be supported in the near future on the other platforms.

   ---

   If you are running LISTSERV under unix, Windows, or VMS, please skip the rest of this section as it does not pertain in any way to your implementation of LISTSERV.

   ---

   These two features are similar in their command syntax, but do different things. AFD provides a method whereby users may subscribe to specific files, which will be sent to them any time the files are updated. For instance, if you have a FAQ file that is updated monthly, a user could send an AFD subscription to that FAQ file and LISTSERV would send it to the user every time you updated and stored the FAQ.

   FUI, on the other hand, is a method whereby a user subscribes to a file but receives only a notification that the file has been updated. The user can then GET the file at his own discretion.

   AFD and FUI can be password-protected to protect users from network hackers who might forge mail from the user subscribing him to large or frequently-updated files. If a password is not provided in an AFD or FUI ADD command, LISTSERV warns the user that it would be a good idea to password protect the subscription.

   8.8. File "Packages"

   This feature has not yet been ported to the workstation and PC environments. However, this feature is supported on VM and will be supported in the near future on the other platforms.

   ---

   If you are running LISTSERV under unix, Windows, or VMS, please skip the rest of this section as it does not pertain in any way to your implementation of LISTSERV.

   ---

   You can define a group of files as a "package" that can be retrieved by users with a single GET command. First, ensure that all the files in the package are defined in the appropriate filelist and stored on the server as detailed above.

   Next, create a file descriptor in the filelist for a file called filename$PACKAGE , where filename is the name you have chosen for the group of files. Be sure that the filetype is $PACKAGE, with a $ sign, and store your filelist.

   Now create a file called filename $PACKAGE that looks like this:

   * MYLIST $PACKAGE
   * Packing list for MYLIST PACKAGE
   * 
   * You can make other comments here, such as 
   * the contact email address.
   *
   * filename filetype filelist
   *=======================
   MYLIST   $PACKAGE MYLIST
   INTEREST FILE     MYLIST
   NETIQUET FILE     MYLIST
   ANOTHER  FILE     MYLIST

   Note that anything that is not the name of a file in the package must be commented out with an asterisk in the leftmost column of the line. It is possible to create a package file without any comment lines at all, but this is not preferable in practice. Often users will get the package file itself just to see what is in it. You should include a reference to the package file itself so that the user will get a copy of the "packing list" to check against the files he receives from LISTSERV.

   The final step is to send the package file to LISTSERV like any other file.

   Now users can do one of two things:

   1. They may get the entire package of files sent to them by sending LISTSERV the command GET filename PACKAGE (without the $ sign); or
   2. They may request that LISTSERV send only the package file itself by sending LISTSERV the command GET filename $PACKAGE (with the $ sign).

   Packages may be subscribed to with the AFD and FUI commands.

   8.9. Where to find more information on File Archives

   Other guides that refer to File Archive setup and maintenance are referenced in Appendix E, Related Documentation and Support.

   8.10. Notebook Archives

   Notebook archives are files in which postings to the list are stored (assuming that notebooks are enabled for the particular list). In general, they are managed automatically by LISTSERV, with certain functions left to the list owner(s). For instance, there is no need to register notebook archives in the listname.FILELIST or listname.CATALOG; this is taken care of automatically.

   8.10.1. Setting up notebook archives for a list

   Setting up notebook archives requires only a few steps:

   1. Make sure that you have disk space for the notebook archives and that the directory in which they will reside has been created with appropriate security privileges. LISTSERV needs read and write access to any directory it uses for notebooks. Note that, for security reasons, LISTSERV will not create the directory if it does not exist.
   2. Add the Notebook= keyword to the list header with appropriate settings
   3. Store the list header back on the server.

   For instance, let's assume you have a list called MYLIST running on a unix server and you wish to store its archives in a directory called /usr/listserv/home/mylist-archive. Notebooks are to be kept on a monthly basis and are to be available to anyone. Your Notebook= keyword would look like this:

   * Notebook= Yes,/usr/listserv/home/mylist-archive,Monthly,Public

   Note that only the LISTSERV maintainer may change the location of Notebook archives (or change Notebook= No to Notebook= Yes), and that the list creation password (CREATEPW in the site configuration file) must be used when changing these values. Attempting to PUT the list header with any other password after changing these values will result in the following message being sent in response:
   

   ---

   The following problems have been detected in the list header:
   
   * Notebook= ...
   Error: Please use the list creation password ("createpw") when updating one
   of the keywords that are under the exclusive control of the LISTSERV 
   administrator.
   
   Please refer to the list keyword documentation (available via the "INFO 
   KEYWORDS" command) for more information about keyword syntax.
   
   PUT operation rejected, old list remains unchanged.

   ---

   Figure 8.3. This output will appear either if an attempt is made to change "Notebook= No" to "Notebook= Yes", or if an attempt is made to change the location where notebook archives are stored on the server, without using the list creation password to validate the PUT operation.

   Similar restrictions also apply to the Digest= keyword. See Appendix B for details.

   8.10.2. Migrating old notebook archives to a new site

   If migrating old notebook archives from one LISTSERV site to another, you can simply ftp (in TEXT mode) the notebooks from the old host to the new host, put them in the directory reference in the Notebook= keyword settings, and LISTSERV will immediately recognize their presence. You can also migrate the notebooks with GET and PUT.

   If migrating old notebook archives to LISTSERV from a non-LISTSERV site, please see the section above (7.12.2) on migrating lists from non-LISTSERV sites.

   8.10.3. Deleting old notebook archives

   The LISTSERV maintainer may delete old notebook archives that are no longer needed in one of two ways:

   • Use standard file system commands from the console prompt to delete the files. On VM, use CMS ERASE; on Unix, RM; on VMS, DEL; on Windows systems, DEL or ERASE.
   • Send a PUT command by itself (in essence, you are storing a zero-length file) via mail to LISTSERV. For instance:

     PUT MYFILE.TEXT PW=XXXXXXXX

     by itself would delete the file MYFILE.TEXT.

   8.10.4. Indexing existing notebook archives

   LISTSERV creates the notebook archive index "on the fly" as required. If there is an existing listname.FILELIST or listname.CATALOG, it appends the index of notebook archives to the end of the index of other files. Otherwise, the index of notebooks is generated and sent by itself. The user simply issues the command INDEX listname to receive the index of available files and notebooks.

   9. Interpreting and Managing LISTSERV's log files

   9.1. Logs kept by LISTSERV

   LISTSERV keeps logs of all of its activity. On VM systems, this information is kept in the LISTSERV console log. On unix systems, it is kept in ~listserv/listserv.log by default. Note that unix systems create the log by redirection of standard output to a file; see the 'go' script if you are interested in this process.

   On VMS and Windows systems, there may be several different logs depending on the configuration of the system. For instance, in addition to the LISTSERV log itself, there will be logs for the SMTP workers if this feature is enabled. On Windows systems, there will also be a log for the SMTP "listener" if it is in service. (Windows systems running L-Soft's LSMTP product will not use the SMTP "listener" service, and thus will not keep logs for it.)

   9.2. Managing the logs

   Making daily logs

   While LISTSERV for VM (via WAKEPARM FILE) and Windows "turns" the log at midnight each day, automatically creating daily logs, LISTSERV for unix and VMS does not.

   LISTSERV for unix creates a single file in the $LSVROOT directory called listserv.log. As this file can get quite long, it will probably be most productive to create a shell script called by a cron job to stop LISTSERV, rename the existing listserv.log and move it to another location (e.g., $LSVROOT/oldlogs), and then restart LISTSERV. L-Soft does not provide shell scripts for this purpose.

   The procedure for LISTSERV for VMS is similar to that for unix; the LISTSERV maintainer will have to write a script to turn logs automatically. Again, L-Soft does not provide these scripts.

   "Cleaning" your log files periodically

   On all systems, you will probably want to clean out your old logs on a regular basis. To do this, you will want to write a script that executes automatically (e.g., via WAKEPARM on VM, as a cron job on unix, or as an AT job on Windows). A sample REXXette for use with Windows NT or 95 that keeps the last 5 days' worth of compressed logs and deletes anything older than that follows:

   ---

   /**/ 
    logdir = 'E:\LISTSERV\LOG'
    tempfile = logdir'\CLEANLOG.TMP'
    keep = 5
   
   /* First zip all the logs, except today's */
   'DIR/B' logdir'\*.LOG >' tempfile
    If rc ^== 0 Then Exit
    today = Date('S')
    Do forever
       line = Translate(Linein(tempfile))
       If line == '' Then Leave
       Parse var line '-'date'.'
       If date = today Then Iterate
       Parse var line fn'.'
       Say 'ZIPping' line'...'
      'ZIP -j -m -q' logdir'\'fn logdir'\'line
    End
    Call Lineout tempfile
   
   /* Now delete ZIP files older than 'keep' days */
   'DIR/B/O-N' logdir'\*.ZIP >' tempfile
    If rc ^== 0 Then Exit
    n. = 0
    Do forever
       line = Translate(Linein(tempfile))
       If line == '' Then Leave
       Parse upper var line pfx'-'date'.'
       n.pfx = n.pfx + 1
       If n.pfx <= keep Then Iterate
       Say 'Deleting' line'...'
      'DEL' logdir'\'line
    End
    Call Lineout tempfile
   'DEL' tempfile
   

   ---

   Figure 9.1. Sample CLEANLOG.REXX script for managing LISTSERV's log files. This particular script runs under Regina REXX on Windows NT or 95.

   Please note that while it is of course possible to simply delete the log file on a daily basis, for the purpose of debugging potential problems this is not recommended.

   9.3. Interpreting the LISTSERV log

   This file, LISTSERV's main logging file, has different names under different ports of the product.

   VM: LISTSERV logs events to the LISTSERV user's console log.

   VMS: LISTSERV_ROOT:[LOG]LSV.LOG

   Unix: ~$LSVROOT/listserv.log

   Windows: LISTSERV\LOG\LISTSERV-yyyymmdd.LOG

   Under VM, the console log can be "turned" by placing the appropriate command in the WAKEPARM file. Under VMS and Windows, LISTSERV automatically "turns" the log at midnight. For VMS, the logs are numberered using the VMS revision tracking system, e,g, LSV.LOG;1, LSV.LOG;2, etc. For Windows, "yyymmdd" is the year, month and day of the log, e.g., LISTSERV-19961111.LOG is the log for 11 November 1996. Unix logs are simply the output of the program written to standard output and shell scripts (not provided by L-Soft) can be written to "turn" the logs daily via cron.

   9.3.1. Expiring cookies

   25 May 1996 00:00:00 Expiring cookie from rdeon@ICOM.CA:
    > SIGNOFF TECHLINK
   25 May 1996 00:00:00 Sent information mail to rdeon@ICOM.CA
   25 May 1996 00:00:00 Expiring cookie from smbourne@LIGHTSIDE.COM:
    > SUBSCRIBE WINNT-L Scott Bourne
   25 May 1996 00:00:00 Sent information mail to smbourne@LIGHTSIDE.COM

   These entries refer to expiring "OK" confirmation cookies.

   9.3.2. Releasing and reallocating a disk slot

   25 May 1996 00:00:00 Virtual disk slot E(E:\LISTSERV\ARCHIVES\NISTEP-L) released
   .
   25 May 1996 00:00:00 Directory E:\EASE\PEACH\LISTS\IATN accessed as virtual disk
    slot E.

   LISTSERV uses "disk slots" in rotation to minimize the overhead involved in opening a file, performing an operation, closing the file, and then possibly having to reopen the file immediately to perform another operation. A given "disk slot" stays open until it is needed for another file.

   9.3.3. Reindexing a list

   25 May 1996 00:00:01 Reindexing IATN LOG9605D...

   LISTSERV rebuilds the index for the current notebook archive file of a given list immediately prior to sending the DIGEST and INDEX versions of the list.

   9.3.4. Distributing a digest

   Here is a typical log sequence for the distribution of a daily digest:

   25 May 1996 00:00:35 Virtual disk slot E(E:\LISTSERV\ARCHIVES\HONYAKU) released.
   25 May 1996 00:00:35 Directory E:\LISTSERV\ARCHIVES\SPAM-L accessed as virtual d
   isk slot E.
   25 May 1996 00:00:37 Reindexing SPAM-L LOG9605...
   25 May 1996 00:00:37 SPAM-L digest is being distributed...
   25 May 1996 00:00:37 Distributing mail ("SPAM-L") from owner-SPAM-L@PEACH.EASE.L
   SOFT.COM...
   25 May 1996 00:00:38 Mail forwarded to H-NET.MSU.EDU     for   2 recipients.
   25 May 1996 00:00:38 Mail forwarded to UAFSYSB.UARK.EDU  for   2 recipients.
   25 May 1996 00:00:38 Mail forwarded to LISTMAIL.SUNET.SE for   2 recipients.

   The preceding 3 jobs were forwarded to LISTSERV servers on the DISTRIBUTE backbone. The following mail is posted to 45 users who are not served by the DISTRIBUTE backbone in a single BSMTP "envelope".

   25 May 1996 00:00:38 Mail posted via SMTP to jim@AMERICAN.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to Jeantheau@AOL.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to PDrazen@AOL.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to GROSS@BCVMS.BC.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to GREER@BMACADM.BITNET.
   25 May 1996 00:00:38 Mail posted via SMTP to JAMES@CLEMSON.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to 75776.1734@COMPUSERVE.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to rkosovsk@EMAIL.GC.CUNY.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to beruber@ERE.UMONTREAL.CA.
   25 May 1996 00:00:38 Mail posted via SMTP to monica@ETERNA.COM.AU.
   25 May 1996 00:00:38 Mail posted via SMTP to laszlo@GOL.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to pletendr@GPU.SRV.UALBERTA.CA.
   25 May 1996 00:00:38 Mail posted via SMTP to kimotol@HAWAII.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to os2wiz@IBM.NET.
   25 May 1996 00:00:38 Mail posted via SMTP to endacott@IDIR.NET.
   25 May 1996 00:00:38 Mail posted via SMTP to xxxxxxx@INET.UNI-C.DK.
   25 May 1996 00:00:38 Mail posted via SMTP to JAY@KSUVM.KSU.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to rrne@LOC.GOV.
   25 May 1996 00:00:38 Mail posted via SMTP to keith@LOONY-TOONS.TAMU.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to MMUNRO@LTRR.ARIZONA.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to listmgr@MAILBOX.SYR.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to lackritz@MO.NET.
   25 May 1996 00:00:38 Mail posted via SMTP to CCHB@MUSICA.MCGILL.CA.
   25 May 1996 00:00:38 Mail posted via SMTP to metacom@NANDO.NET.
   25 May 1996 00:00:38 Mail posted via SMTP to sylviac@NETCOM.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to epstein@NYIQ.NET.
   25 May 1996 00:00:38 Mail posted via SMTP to laura@PAMELA.INT.MED.UNIPI.IT.
   25 May 1996 00:00:38 Mail posted via SMTP to stoxen@PIONEER.STATE.ND.US.
   25 May 1996 00:00:38 Mail posted via SMTP to eagree@PSC.LSA.UMICH.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to PMW1@PSUVM.PSU.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to TDTRUE@PUCC.PRINCETON.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to willis@SCS.UNR.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to greggd@SILVERPLATTER.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to KARYPM@SJUVM.STJOHNS.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to TERRY@SPCVXA.SPC.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to barry@TELERAMA.LM.COM.
   25 May 1996 00:00:38 Mail posted via SMTP to JFORD@UA1VM.UA.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to USTS004@UABDPO.DPO.UAB.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to LISTSMNT@UCONNVM.UCONN.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to CDYOUNG@UTARLVM1.UTA.EDU.
   25 May 1996 00:00:38 Mail posted via SMTP to KLASSEN@UVVM.UVIC.CA.
   25 May 1996 00:00:38 Mail posted via SMTP to U8803KT@VM1.HQADMIN.DOE.GOV.
   25 May 1996 00:00:38 Mail posted via SMTP to MARIE@VM1.MCGILL.CA.
   25 May 1996 00:00:38 Mail posted via SMTP to TURGUT@VM3090.EGE.EDU.TR.
   25 May 1996 00:00:38 Mail posted via SMTP to rubinm@WATSON.IBM.COM.

   LISTSERV always summarizes and tells you what it's done:

   25 May 1996 00:00:38 Done - 3 jobs (6 rcpts), 1 outbound file (45 rcpts).

   9.3.5. Daily error monitoring reports

   25 May 1996 00:00:43 Generating daily nondelivery monitoring reports...

   Here LISTSERV deletes a subscriber who has gone over the Auto-Delete= limits:

   25 May 1996 00:00:44 -> Deleted jechaves@CARIARI.UCR.AC.CR from ACCESS-L.

   LISTSERV now sends out the daily error monitoring reports to the appropriate people (defined in "Errors-To=" for each list).

   25 May 1996 00:00:44 Sent information mail to jechaves@CARIARI.UCR.AC.CR
   25 May 1996 00:00:45 Sent information mail to ACCERR@LINUS.DC.LSOFT.COM
   25 May 1996 00:00:46 Sent information mail to AFWEB@AF.PENTAGON.MIL
   25 May 1996 00:00:46 Sent information mail to CLIFF@ESA.MHS.COMPUSERVE.COM

   As LISTSERV continues to run and process errors for the various lists, it will update the listname.AUTODEL file whenever it receives an error that it understands:

   25 May 1996 00:05:43 Automatic nondelivery report processing for WIN95-L:
   25 May 1996 00:05:43 -> All errors temporary, no action taken.
   25 May 1996 00:07:34 Automatic nondelivery report processing for EXCEL-G:
   25 May 1996 00:07:34 -> 1 monitoring entry updated.

   9.3.6. Processing mail for local lists

   25 May 1996 00:39:23 Processing file 8209289 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:39:25 Processing mail from pbrass@PRIMENET.COM for ACCESS-L
   25 May 1996 00:39:25 Virtual disk slot E(E:\EASE\PEACH\FTP\EXCEL-L) released.
   25 May 1996 00:39:25 Directory E:\EASE\PEACH\FTP\ACCESS-L accessed as virtual di
   sk slot E.
   25 May 1996 00:39:26 Distributing mail ("ACCESS-L") from owner-access-l@PEACH.EA
   SE.LSOFT.COM...
   25 May 1996 00:39:26 Mail posted via SMTP to DOW1COM%bu.bbc@NR-COMMS.RADIO.BBC.C
   O.UK.
   25 May 1996 00:39:26 Mail posted via SMTP to MARYANNG@OHS.ORG.
   25 May 1996 00:39:26 Mail posted via SMTP to wroth@POBOX.COM.
   25 May 1996 00:39:26 Done - 1 outbound file (3 rcpts).
   25 May 1996 00:39:26 Distributing mail ("ACCESS-L") from owner-access-l@PEACH.EA
   SE.LSOFT.COM...
   25 May 1996 00:39:26 Mail forwarded to LISTSERV@HEARN    for   4 recipients.
   25 May 1996 00:39:27 Mail forwarded to LISTMAIL.SUNET.SE for  11 recipients.
   25 May 1996 00:39:27 Mail forwarded to LISTSERV@ICINECA  for   4 recipients.
   25 May 1996 00:39:27 Mail forwarded to LISTSERV.GMD.DE   for   3 recipients.
   25 May 1996 00:39:27 Mail forwarded to LISTSERV@AEARN    for   2 recipients.
   25 May 1996 00:39:27 Processed     192 recipients...
   25 May 1996 00:39:27 Done - 5 jobs (24 rcpts), 1 outbound file (192 rcpts).
   25 May 1996 00:39:27 Distributing mail ("ACCESS-L") from owner-access-l@PEACH.EA
   SE.LSOFT.COM...
   25 May 1996 00:39:27 Mail posted via SMTP to russo@ADC.COM.
   25 May 1996 00:39:27 Mail posted via SMTP to PeterDe@MSMEL.PRAXA.COM.AU.
   25 May 1996 00:39:27 Mail posted via SMTP to mahoney@SPRYNET.COM.
   25 May 1996 00:39:27 Done - 1 outbound file (3 rcpts).
   25 May 1996 00:39:27 Message DISTRIBUTEd to 222 recipients.
   25 May 1996 00:39:28 Sent information mail to pbrass@PRIMENET.COM

   9.3.7. Administrative mail (X-ADMMAIL)

   This particular type of mail, sent to the OWNER-listname address, is a delivery error being returned to the RFC 821 MAIL FROM: address.

   25 May 1996 00:01:16 From MAILER@PEACH.EASE.LSOFT.COM: X-ADMMAIL OWNER-AFNS
   25 May 1996 00:01:16 Processing file 8206153 from MAILER@PEACH.EASE.LSOFT.COM

   9.3.8. DISTRIBUTE jobs from remote hosts

   Just as our LISTSERV sends out DISTRIBUTE jobs to the backbone, it also receives them for distribution from remote backbone hosts.

   25 May 1996 00:01:16 Processing file 8206155 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:01:16 From LISTSERV@PSUVM.PSU.EDU: X-B64 ID=PAN-L.MAILDIST CLASS=
   A
   25 May 1996 00:01:16 Rescheduled as: 8206156
   25 May 1996 00:01:16 Processing file 8206156 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:01:16 From LISTSERV@PSUVM: DIST2 MAIL I=Y FROM=owner-pan-l@BINGVM
   B.CC.BINGHAMTON.EDU FORW(CRC) HOST(626 626 (...) 
   25 May 1996 00:01:17 Distributing mail ("PAN-L") from owner-pan-l@BINGVMB.CC.BIN
   GHAMTON.EDU...
   25 May 1996 00:01:17 Mail posted via SMTP to rbradley@ACS.RYERSON.CA.
   25 May 1996 00:01:17 Mail posted via SMTP to mlt40@AMAIL.AMDAHL.COM.
   25 May 1996 00:01:17 Mail posted via SMTP to Anyushka@AOL.COM.

   and so forth.

   9.3.9. Requesting "OK" confirmation for commands

   25 May 1996 00:01:17 Processing file 8206160 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:01:17 From jhoward@AUSCONSULT.COM.AU: UNSUB EXCEL-L
   25 May 1996 00:01:17 Requesting confirmation, cookie=3EB4F2
   25 May 1996 00:01:17 Sent information mail to jhoward@AUSCONSULT.COM.AU
   

   9.3.10. Supervisory updates (SUPD jobs)

   25 May 1996 00:04:54 Processing file 8206401 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:54 From LISTSERV@INTERNET.COM: X-B64 ID=X-SUPD.JOB ASCII CLASS
   =J
   25 May 1996 00:04:54 Rescheduled as: 8206402
   25 May 1996 00:04:54 Processing file 8206402 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:54 From LISTSERV@INTERNET.COM: DIST2 I=Y FROM=LISTSERV@INTERNE
   T.COM FORW(CRC) HOST(626 626 626 626 626 691 686  (...)
   25 May 1996 00:04:54 Distributing file "X-SUPD JOB" from LISTSERV@INTERNET.COM..
   .
   25 May 1996 00:04:54 File forwarded to LIME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:54 File forwarded to WIN95.DC.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:54 File forwarded to SPIDER.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:54 File forwarded to HOME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:54 File forwarded to LISTSERV.GEORGETOWN.EDU for   1 recipient
   .
   25 May 1996 00:04:54 File forwarded to CC1.KULEUVEN.AC.BE for   1 recipient.
   25 May 1996 00:04:54 File forwarded to LISTSERV.USHMM.ORG for   1 recipient.
   25 May 1996 00:04:54 File forwarded to LISTSERV.CLARK.NET for   1 recipient.
   25 May 1996 00:04:54 File "X-SUPD JOB" distributed to LISTSERV@PEACH.EASE.LSOFT.
   COM.
   25 May 1996 00:04:54 Done - 8 jobs (8 rcpts), 1 outbound file (1 rcpt).
   25 May 1996 00:04:54 Processing file 8206411 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:54 From LISTSERV@INTERNET.COM: X-SUPD FWD=NO DATE=1996052500:0
   0:04 DATA=5 56 PHOTOPRO 465 PHOTOTECH 268 PHOTOAS (...)

   9.3.11. Global list of lists updates (LUPD jobs)

   LISTSERV receives the file from another LISTSERV host and distributes it down the line:

   25 May 1996 00:04:08 Processing file 8206361 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:08 From LISTSERV@LISTSERV.UIC.EDU: X-B64 ID=X-LUPD.JOB ASCII C
   LASS=J
   25 May 1996 00:04:08 Rescheduled as: 8206362
   25 May 1996 00:04:08 Processing file 8206362 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:08 From LISTSERV@LISTSERV.UIC.EDU: DIST2 I=Y FROM=LISTSERV@LIS
   TSERV.UIC.EDU FORW(CRC) HOST(626 626 626 626 626 691  (...)
   25 May 1996 00:04:08 Distributing file "X-LUPD JOB" from LISTSERV@LISTSERV.UIC.E
   DU...
   25 May 1996 00:04:08 File forwarded to LIME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:08 File forwarded to WIN95.DC.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:08 File forwarded to SPIDER.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:08 File forwarded to HOME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 00:04:08 File forwarded to LISTSERV.GEORGETOWN.EDU for   1 recipient
   .
   25 May 1996 00:04:08 File forwarded to CC1.KULEUVEN.AC.BE for   1 recipient.
   25 May 1996 00:04:08 File forwarded to LISTSERV.USHMM.ORG for   1 recipient.
   25 May 1996 00:04:08 File forwarded to LISTSERV.CLARK.NET for   1 recipient.

   LISTSERV also sends itself a copy:

   25 May 1996 00:04:08 File "X-LUPD JOB" distributed to LISTSERV@PEACH.EASE.LSOFT.
   COM.
   25 May 1996 00:04:08 Done - 8 jobs (8 rcpts), 1 outbound file (1 rcpt).
   25 May 1996 00:04:08 Processing file 8206371 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:08 From LISTSERV@LISTSERV.UIC.EDU: X-LUPD FWD=NO DATE=19960524
   23:00:02 HDR=YES

   The following entry tells LISTSERV to replace the information it has for NEWIO-L in its global list of lists:

   > REP NEWIO-L NEWIO-L /Info about replacing ILLINET Online hardware and software
   /2616677089 > CKS 3881006631
   25 May 1996 00:04:10 GLOBLIST FILE has been successfully updated.

   Note that entries for deleted lists also are updated (deleted from GLOBLIST FILE):

   25 May 1996 00:24:11 Processing file 8207550 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:24:11 From LISTSERV@VM1.NODAK.EDU: X-LUPD FWD=NO DATE=1996052423:
   00:04 HDR=YES
   > DEL WLREHAB
   > DEL WDAMAGE
   > DEL POWER-L
   > DEL QUEST
   > DEL RS1-L
   > DEL SANGEET
   > DEL SPRINT-L
   > DEL STAFFGOV
   > DEL TAG-L
   > DEL TELUGU
   > DEL THEORY-A
   > DEL THEORY-B
   > DEL THEORY-C
   > DEL THEORYNT
   > DEL TOW
   > DEL TWSGIS-L
   > DEL UND-SEMI
   > CKS 3794276653
   25 May 1996 00:24:13 GLOBLIST FILE has been successfully updated.

   Note that if the "CKS" checksum does not check out, the job is discarded without being processed.

   9.3.12. Valid "OK" confirmation received

   Here is a set of typical log entries for the receipt of a valid "OK" confirmation. Notice that LISTSERV accepts the OK and then issues itself the command that required confirmation. Other than the "OK", this behavior (at least in the log) is identical to how LISTSERV handles commands that do not require confirmation.

   25 May 1996 00:04:58 Processing file 8206418 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:04:58 From tom.smith@SOL.KISS.DE: OK
   25 May 1996 00:04:58 From tom.smith@SOL.KISS.DE: SIGNOFF AFWEEKLY
   25 May 1996 00:04:58 To tom.smith@SOL.KISS.DE: You have been removed from the
   AFWEEKLY list.
   25 May 1996 00:04:58 Sending FAREWELL message to tom.smith@SOL.KISS.DE
   25 May 1996 00:04:58 Sent information mail to tom.smith@SOL.KISS.DE
   25 May 1996 00:04:58 Sent information mail to:
                        >BOWMANT@AFSYNC.HQ.AF.MIL HEDGESE@AFSYNC.HQ.AF.MIL
                        >SYSOP@AFNEWS.PA.AF.MIL WAYMAN@MASTER.PA.AF.MIL
   25 May 1996 00:04:58 Sent information mail to tom.smith@SOL.KISS.DE

   Note that the "OK" may contain the return cookie:

   25 May 1996 00:08:50 Processing file 8206772 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:08:50 From e.kirchner@GENIE.COM: OK 71365E
   25 May 1996 00:08:50 From e.kirchner@GENIE.COM: SUBSCRIBE AFNS Major Eric Kirchn
   er
   25 May 1996 00:08:51 To e.kirchner@GENIE.COM: You have been added to the AFNS
   list.
   25 May 1996 00:08:51 Sent information mail to e.kirchner@GENIE.COM
   25 May 1996 00:08:51 Sending WELCOME message to e.kirchner@GENIE.COM
   25 May 1996 00:08:51 Sent information mail to e.kirchner@GENIE.COM
   25 May 1996 00:08:51 Sent information mail to:
                        >BOWMANT@AFSYNC.HQ.AF.MIL HEDGESE@AFSYNC.HQ.AF.MIL
                        >SYSOP@AFNEWS.PA.AF.MIL WAYMAN@MASTER.PA.AF.MIL
   25 May 1996 00:08:51 Sent information mail to e.kirchner@GENIE.COM

   9.3.13. Invalid "OK" confirmation received

   "OK" confirmation codes relate to specific userids. For instance, if you try to execute a command as "someuser@someplace.com" and reply to the "OK" from "someuser@unix1.someplace.com", LISTSERV will not perform so-called "fuzzy matching" or do a DNS lookup to determine whether or not "unix1.someplace.com" maps to "someplace.com". Therefore, since the code and the userid don't match, LISTSERV will respond that the confirmation code does not match any pending job.

   This message is also sent if the "OK" comes after the "cookie" expires, since of course there is no longer any pending job matching it.

   25 May 1996 01:16:28 Processing file 8211043 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 01:16:29 From VB_Guy@MSN.COM: ok
   25 May 1996 01:16:29 To   VB_Guy@MSN.COM: The confirmation code you gave (78B484)  does
   not correspond to any pending (...)

   9.3.14. User is already subscribed to a given list

   Note that the user may be trying to change his "real name" field in the list. In any case, if the "real name" field matches the one in the SUBSCRIBE command, the following is logged:

   25 May 1996 00:11:42 Processing file 8206935 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:11:42 From therrera@NS.NET: SUBSCRIBE IN-TOUCH Thomas Herrera
   25 May 1996 00:11:42 To   therrera@NS.NET: You are already subscribed to the IN-TOUCH list as "Thomas
   Herrera".
   25 May 1996 00:11:42 Sent information mail to therrera@NS.NET

   If the "real name" field is different, the following is logged:

   25 May 1996 00:16:18 Processing file 8207278 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:16:18 From rolando@EROLS.COM: SUBSCRIBE IN-TOUCH Rolando Sanz
   25 May 1996 00:16:18 To   rolando@EROLS.COM: The name associated with your rolan
   do@EROLS.COM subscription has been (...)
   25 May 1996 00:16:18 Sent information mail to rolando@EROLS.COM

   9.3.15. User has included non-command text (e.g., a .sig file) in his mail to LISTSERV

   25 May 1996 00:32:07 Processing file 8207703 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:32:07 From MAILER@PEACH.EASE.LSOFT.COM: X-ADMMAIL OWNER-EXCEL-L M
   ailer-Daemon@inf.com
   25 May 1996 00:32:15 Processing file 8207705 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:32:15 From scotty68@IX.NETCOM.COM: ok
   25 May 1996 00:32:15 From scotty68@IX.NETCOM.COM: sub WINNT-L Tracy D. Scott
   25 May 1996 00:32:15 To   scotty68@IX.NETCOM.COM: You have been added to the WIN
   NT-L list.
   25 May 1996 00:32:15 Sent information mail to scotty68@IX.NETCOM.COM
   25 May 1996 00:32:15 From scotty68@IX.NETCOM.COM: Tracy Scott
   25 May 1996 00:32:15 To   scotty68@IX.NETCOM.COM: Unknown command - "TRACY".
   Try HELP.
   25 May 1996 00:32:15 From scotty68@IX.NETCOM.COM: scotty68@ix.netcom.com
   25 May 1996 00:32:15 To   scotty68@IX.NETCOM.COM: Unknown command - "SCOTTY68@IX
   .NETCOM.COM". Try HELP.
   25 May 1996 00:32:15 From scotty68@IX.NETCOM.COM: http://www.netcom.com/~scotty6
   8/
   25 May 1996 00:32:15 To   scotty68@IX.NETCOM.COM: Unknown command - "HTTP:".
   Try HELP.
   25 May 1996 00:32:15 Sent information mail to scotty68@IX.NETCOM.COM

   9.3.16. Response to list owner or LISTSERV maintainer commands

   25 May 1996 00:36:08 From bwblack@WEBCOM.COM: quiet delete iatn tusita@po.pacifi
   c.net.sq pw=xxxxx
   25 May 1996 00:36:08 To   bwblack@WEBCOM.COM: tusita@PO.PACIFIC.NET.SQ is not su
   bscribed to the IATN list.
   25 May 1996 00:36:08 Sent information mail to bwblack@WEBCOM.COM

   9.3.17. Response to a user who tries to post to a held list (or one for which PRIMETIME is in effect)

   25 May 1996 00:36:42 Processing file 8208564 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:36:43 To   jblock@IQUEST.NET: The distribution of your message da
   ted  Fri, 24 May 1996 23:32:59 -0500 with (...)
   25 May 1996 00:36:43 Sent information mail to jblock@IQUEST.NET

   9.3.18. Command forwarded via GLX from another host

   25 May 1996 00:48:56 Processing file 8210093 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 00:48:57 From LISTSERV@SEARN.SUNET.SE: X-B64 ID=X-FOR.JOB CLASS=M
   25 May 1996 00:48:57 Rescheduled as: 8210094
   25 May 1996 00:48:57 Processing file 8210094 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 00:48:57 From LISTSERV@SEARN: X-FOR FWDED=2 polydoro@CS.SFU.CA SUBSC
   RIBE WINNT-L Paraskevas Polydorou
   25 May 1996 00:48:57 Requesting confirmation, cookie=4E79B8
   25 May 1996 00:48:57 Sent information mail to polydoro@CS.SFU.CA
   25 May 1996 00:48:57 Sent information mail to polydoro@CS.SFU.CA

   9.3.19. Netwide DELETE (X-DEL jobs)

   25 May 1996 01:13:25 Processing file 8210957 from MAILER@PEACH.EASE.LSOFT.COM
   25 May 1996 01:13:25 From LISTSERV@PSUVM.PSU.EDU: X-B64 ID=X-DEL.JOB CLASS=A
   25 May 1996 01:13:25 Rescheduled as: 8210958
   25 May 1996 01:13:25 Processing file 8210958 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 01:13:25 From LISTSERV@PSUVM: DIST2 I=Y FROM=LISTSERV@VM1.NODAK.EDU
   FORW(CRC) HOST(626 626 626 626 626 626 691 (...)
   25 May 1996 01:13:25 Distributing file "X-DEL JOB" from LISTSERV@VM1.NODAK.EDU..
   .
   25 May 1996 01:13:25 File forwarded to HOME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 01:13:25 File forwarded to SPIDER.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 01:13:25 File forwarded to WIN95.DC.LSOFT.COM for   1 recipient.
   25 May 1996 01:13:25 File forwarded to INDIAN.DC.LSOFT.COM for   1 recipient.
   25 May 1996 01:13:25 File forwarded to LIME.EASE.LSOFT.COM for   1 recipient.
   25 May 1996 01:13:25 File forwarded to LISTSERV.GEORGETOWN.EDU for   1 recipient
   .
   25 May 1996 01:13:25 File forwarded to CC1.KULEUVEN.AC.BE for   1 recipient.
   25 May 1996 01:13:26 File forwarded to LISTSERV.USHMM.ORG for   1 recipient.
   25 May 1996 01:13:26 File forwarded to LISTSERV.CLARK.NET for   1 recipient.
   25 May 1996 01:13:26 File "X-DEL JOB" distributed to LISTSERV@PEACH.EASE.LSOFT.C
   OM.
   25 May 1996 01:13:26 Done - 9 jobs (9 rcpts), 1 outbound file (1 rcpt).
   25 May 1996 01:13:26 Processing file 8210968 from LISTSERV@PEACH.EASE.LSOFT.COM
   25 May 1996 01:13:26 From LISTSERV@VM1.NODAK.EDU: X-FOR NF05@SDSUMUS.SDSTATE.EDU
    SIGNOFF * FWDED=2 (NETWIDE 

   9.3.20. FIOC cache notifications

   LISTSERV caches files that it uses for efficiency. Occasionally, you may see a warning that the FIO cache has reached a preset limit (FIOC_WARNING in the site configuration file). See the FIOC_CACHE, FIOC_TRIM, and FIOC_WARNING site configuration variables in Appendix C for more information. If you get a lot of these warnings, you may want to consider adjusting the cache values.

   25 May 1996 01:24:06 Virtual disk slot E(E:\EASE\PEACH\FTP\VBDATA-L) released.
   25 May 1996 01:24:06 Directory
   E:\LISTSERV\ARCHIVES\SPAM-L accessed as virtual disk slot E.
   
   *** FIO file cache now totals 20659k. A list of cached files follows. ***
   
   File size  Usage  Flags  File name
   ---------  -----  -----  ---------
       5071k      1   U     E:\LISTSERV\ARCHIVES\SPAM-L\SPAM-L.LOG9605
          2k      1         E:\listserv\TMP\LISTSERV.CMSUT1
        242k      1         E:\listserv\main\PERMVARS.FILE
          4k      1         E:\listserv\main\VBDATA-L.DIGEST
        378k      1         E:\EASE\PEACH\FTP\VBDATA-L\VBDATA-L.LOG9605D
        121k      1         E:\listserv\main\POSTNOTE.LIST
        282k      1         E:\listserv\main\FUTURESUPERSTOCK.LIST
        115k      1         E:\listserv\main\AUTOTECHNET.LIST
          6k      1         E:\LISTSERV\ARCHIVES\HONYAKU\HONYAKU.DIGEST
          1k      3         E:\listserv\main\DIGESTS.FILE
         11k      3         E:\listserv\TMP\TEMP.FILELIST

   (Many more lines were deleted)

   9.4. Interpreting the SMTP logs (Windows servers only)

   These logs are for the SMTPL.EXE "listener" service, and are called SMTP-yyyymmdd.LOG. They are found in the /LISTSERV/LOG directory with the other LISTSERV system logs. A typical "listener" log looks like this:

   ---

   24 May 1996 14:13:31 LISTSERV SMTP listener, version 1.0a
   24 May 1996 14:13:31 Copyright L-Soft international, 1994-95
   24 May 1996 14:13:31 Initialization complete.
   24 May 1996 14:15:59 New connection (1) from 128.118.56.2
   24 May 1996 14:18:50 New connection (2) from 199.3.65.5
   24 May 1996 14:18:59 >>>(1) Connection closed by remote host.
   24 May 1996 14:19:05 Closing connection (2) from 199.3.65.5.
   24 May 1996 14:19:08 New connection (3) from 205.186.43.7
   24 May 1996 14:20:08 Closing connection (3) from 205.186.43.7.

   ---

   Figure 9.2 Typical SMTP log for the SMTPL.EXE "listener"

   This log simply keeps track of incoming SMTP connections to your server. It adds an entry for each new connection as it opens and closes. Additionally, if a connection is closed abnormally (e.g., by the remote host before any data is sent), the condition is logged. The SMTP log is generally useful only for debugging the SMTP listener, although it may also be of use in debugging problems with specific remote hosts.

   Note that if you are running L-Soft's LSMTP™ product and do not have the SMTPL.EXE "listener" running, these logs will not be generated.

   9.5. Interpreting the SMTPS logs (Windows and VMS servers only)

   If you have SMTP "workers" activated on a Windows or VMS server, each "worker" creates a separate log for itself. These logs are found in:

   VMS: LISTSERV_ROOT:[LOG]SMTPSn-yyyymmdd.LOG

   Windows: LISTSERV\LOG\SMTPSn-yyyymmdd.LOG

   (LISTSERV automatically "turns" the SMTPS logs at midnight. "yyymmdd" is the year, month and day of the log, e.g., LISTSERV-19961111.LOG is the log for 11 November 1996. "n" refers to the worker that is generating the log. Each worker generates a log, so if you have 10 workers running, you will have logs for SMTPS1 through SMTPS10.)

   A typical SMTP "worker" log looks like this:

   ---

   03 Jun 1996 13:49:21 *** LSMTP extensions activated ***      
   
   03 Jun 1996 13:49:03 500 error reading data line
   
   03 Jun 1996 13:49:04 Renaming 8891738.MAIL to 8891738.MAIL-ERR1.
   
   03 Jun 1996 14:06:54 Error opening '8894361.MAIL': Permission denied
   03 Jun 1996 14:09:55 Error opening '8894695.MAIL': Permission denied
   03 Jun 1996 14:40:45 Error opening '8897761.MAIL': Permission denied

   ---

   Figure 9.3 Typical SMTPS log for the SMTPW.EXE SMTP "workers"

   The SMTP worker logs keep track of events that occur while the SMTP workers are delivering mail to the external mail host(s) defined in the SMTP_FORWARD_n variables in the site configuration file. In general, the events logged will be errors of one kind or another. For instance, the first error in the example above indicates an SMTP error, and the second indicates that a file that caused an error has been renamed so that it can be examined for debugging.

   The last three errors are normal and can generally be ignored. They refer to the fact that two workers have noticed a .MAIL file that exists in the queue, and that one of them grabbed it before the other one did. The first worker locks the file and the second worker is denied permission to open it. Sometimes the first worker may process the mail so quickly that the error will read "File not found" rather than "Permission denied"; either way, this should not be considered alarming unless mail is actually not being delivered.

   The first line in the example simply indicates that special extensions for use with LSMTP have been activated. This message will appear only if you are licensed for LISTSERV-HPO.

   10. Creating and Editing LISTSERV's Mail Templates

   10.1. What LISTSERV uses mail templates for

   Mail templates are used to generate some of the mail LISTSERV sends to users in response to commands it receives. Among these are the "You are now subscribed . . ." message, the message sent to users when LISTSERV cannot find a subscription for them in a specified list, and others. Note that certain administrative mail (for instance, the response to the STATS and RELEASE commands) is hard-coded into LISTSERV and cannot be changed.

   Mail templates are files that contain one or more mail template forms.

   10.2. The DEFAULT.MAILTPL file and how to get a copy

   LISTSERV stores the default mail template information in a file called DEFAULT.MAILTPL, which can be requested by list owners from LISTSERV with the GET command, just like any other file. The LISTSERV maintainer will find this file in LISTSERV's "A" directory (usually ~listserv/home on unix, LISTSERV\MAIN on Windows systems, and [LISTSERV.MAIN] under VMS).

   Note that it is considered unwise to modify the contents of DEFAULT.MAILTPL itself, as this file will be overwritten by upgrades.

   10.3. The $SITE$.MAILTPL file

   In some cases, it may be necessary for the LISTSERV maintainer to ensure that all subscribers receive certain information or warnings (typically legal notices required by government regulations) when they leave or join a list. The list owner should not be able to disable these warnings, accidentally or otherwise. The $SITE$.MAILTPL file provides this functionality.

   If a $SITE$.MAILTPL file is present in LISTSERV's main directory (the one with DEFAULT.MAILTPL), LISTSERV will look it up every time it needs to deliver an administrative message. If the message is not found in the site template, LISTSERV will process the request normally, looking up the list template file, then the language template file and finally the system template file. If the message is listed in the site template, LISTSERV will deliver both the copy in the site template and the copy in the list/language/system template.

   Note that L-Soft does not ship a $SITE$.MAILTPL file in the LISTSERV distributions. If needed, you must create this template file yourself. $SITE$.MAILTPL will not be overwritten during an upgrade.

   Also note that LISTSERV will not pick up an "imbedded" template from $SITE$.MAILTPL. If you wish to include an "imbedded" template (e.g., $SIGNUP) in $SITE$.MAILTPL, you must also include the template(s) that calls it with the .im command. For instance, if you include $SIGNUP in $SITE$.MAILTPL, by default you would need to include the SIGNUP1 and ADD1 templates in $SITE$.MAILTPL as well if you expected $SIGNUP to be sent from $SITE$.MAILTPL.

   10.4. Mail template format and embedded formatting commands

   Each individual template form starts with a form name and subject line, such as:

   >>> EXAMPLE1 This is the subject line

   Please note carefully the following instructions for the form name and subject line:

   • The template starts with the line containing the form name and subject, and ends with the next line starting with '>>>', or at the end of the file.
   • The subject line may contain substitutions (such as "&LISTNAME: &WHOM requested to join").
   • Ensure that there is a blank space between `>>>` and the name of the form, or LISTSERV will not recognize the form.
   • Also note that the names of the templates must be typed in UPPER CASE.

   A template form contains text and, optionally, formatting/editing commands, which start with a period in column 1. All other lines are treated as normal text: sequences starting with an & sign are substituted, then lines are joined together to form a paragraph, which is finally formatted like with any non-WYSIWYG text processor. You can suspend formatting with .FO OFF and resume it with .FO ON; when formatting is suspended, LISTSERV no longer joins lines to form a paragraph, but simply writes one line of text to the message for each line read from the template form. This makes it possible to include tables or a text-mode logo, but can create seriously imbalanced text if substitutions are used. For instance, a typical &WHOM substitution can range from a dozen characters to 60 or more, even though it only takes up 5 characters on your screen when you enter it.

   The following substitutions are always available:

   
   &DATE               Long-style date (29 Jul 1993)
   &TIME               hh:mm:ss
   &WEEKDAY            Three-letter day of the week, in English
   &MYNAMES            The substitution you will use most of the time when you
                       need to refer to LISTSERV. For Internet-only or BITNET-
                       only servers, this will display LISTSERV's only e-mail 
                       address. For servers with both Internet and BITNET 
                       connectivity, it will say "LISTSERV@hostname (or
                       LISTSERV@nodeid.BITNET)".
   &MYSELF             LISTSERV's address, in the form LISTSERV@XYZ.EDU or, if 
                       no Internet hostname is available, LISTSERV@XYZVM1.BITNET.
   &MYNODE             LISTSERV's BITNET nodeid, without the '.BITNET', or
                       its Internet hostname if no NJE address is available.
   &MYHOST             LISTSERV's Internet hostname or, if none is available, its
                       NJE address (with '.BITNET').
   &MBX(addr)          Looks up the specified address in LISTSERV's signup file
                       and displays "name <addr>" if a name is available,
                       or just the original address otherwise. This is typically
                       used to give the name of the command originator or target,
                       along with his e-mail address: &MBX(&WHOM) or 
                       &MBX(&INVOKER).
   &RELEASE            LISTSERV's release number (e.g., "1.8b").
   &OSTYPE             The operating system under which LISTSERV is running, e.g.,
                       VM/VMS/unix/Windows.
   &OSNAME             The full operating system name including the version number,
                       e.g., "VM/ESA 1.2.3", "Windows NT 3.51", "Linux 1.1.88", 
                       "SunOS 5.4", etc.
   &HARDWARE           The type of machine LISTSERV is running on, e.g., "Pentium
                       (32M)".

   The following substitutions are also available for templates related to mailing lists:

   
   &LISTNAME           The name of the list per the "List-Address=" keyword or
                       its default value.
   &TITLE              Title of the list, or empty string.
   &KWD(kwd)           Value of the specified keyword for the list. You do not
                       need to specify the name of the list - it is implicit. You 
                       need not put quotes around the keyword names either, although
                       quotes will be accepted if present.
                       Optionally, you can specify a second numeric argument to 
                       extract just one of the terms of a list header keyword; for 
                       instance, if the list header contains "Notebook= Yes,L1,
                       Monthly, Private", &KWD(NOTEBOOK,4) has the value
                       "Private". A third argument, also optional, specifies the 
                       default value for the keyword in case it was not initialized. 
                       It is meant to be used for conditional formatting in the 
                       default templates and list owners should not worry about it.
   &LITE               (New for 1.8c) Has the value 1 when running the new LISTSERV 
                       Lite product, and 0 otherwise. This variable can be used to
                       write generic templates that account for the differences 
                       between the two products.
   &ISODATE            (New for 1.8c) Returns today's date in ISO format, i.e.,
                       yyyy-mm-dd.
   &DAYSEQ(n)          (New  for 1.8c)  Used to create FAQ template forms with rotating
                       topics. May also be used to create bottom banners with rotating
                       text (e.g., for lists with multiple commercial sponsors who 
                       get "ad space" in the banner on a rotating basis).

   In addition, many template forms have their own specific substitutions, meaningful only in their specific context. For instance, a message informing a user that he was added to a mailing list may have an &INVOKER substitution for the address of the person who issued the ADD command. This is not meaningful for a template form informing a user that he must confirm his subscription to a list within 10 days, so it is not generally available. If you attempt to use a substitution which is not available, the template processor writes an error message to the mail message it is generating, but sends it anyway, in the hope that the recipient will be able to figure out the meaning of the message in spite of the error. If you need to include a sentence with an ampersand character, you will have to double it to bypass the substitution process, as in "XYZ &&co."

   Starting with 1.8c, the mail template processor supports HTML-like variable closure, in addition to the traditional LISTSERV closure (both methods are supported concurrently; there is no need to select one over the other). For example:

   Traditional:	For more information, please send mail to &EMAIL or call &PHONE.
   HTML:	For more information, please send mail to &EMAIL; or call ☎.

   Previously, HTML writers who used HTML closure conventions would not get the expected results. This change makes it easier for webmasters to get the desired results the first time.

   Any line starting with a period in column 1 is processed as a formatting command. Note that neither substitutions nor formatting commands are case sensitive. Here is a list of the formatting commands list owners may need to use:

   .*	Comment: anything on this line is simply ignored. This is useful for recording changes to template files when there are multiple owners. Just add a comment line with the date and your initials every time you make a change, for the benefit of the other owners.
   .FO OFF	Turns off formatting: one template line = one line in the final message. You can resume formatting with .FO ON.
   .CE text	Centers the text you specify (just the text you typed on the same line as the .CE command). This can be useful to highlight the syntax of a command.
   .RE OWNERS	Adds a 'Reply-To:' field pointing to the list owners in the header of the generated message. Use this command when you think users are likely to want to reply with a question. You can also use .RE POSTMASTER to direct replies to the LISTSERV administrator, if this is more appropriate.
   .CC OFF	Removes all "cc:" message recipients, if any. You can also add message recipients by specifying a series of e-mail addresses after the .CC statement, as in .CC JOE@XYZ.EDU. PC mail users should note that in this context "cc:" is a RFC822 term that stands for "carbon copy". RFC822 messages may have "cc:" recipients in addition to their "primary" recipients. There is no real technical difference between the two, the "cc:" indicator just denotes a message that is being sent for your information. Some administrative messages sent to list owners are copied to the user for their information, and vice-versa; this behavior can be disabled by adding a .CC OFF statement to the template.
   .TO	Replaces the default recipients of a message with the value specified. For instance, if you use the ADDREQ1 template form to send new subscribers a questionnaire, application form or similar material, you will need to add a '.TO &WHOM' instruction to your modified template form, as by default the user will not receive a copy.
   .QQ	Cancels the message. LISTSERV stops reading the template form and does not send anything. This is useful if you want to completely remove a particular message; note however that this can be confusing with certain commands, as LISTSERV may say "Notification is being sent to the list owners" when in fact nothing will be sent because of the .QQ command in the template form.

   A number of more advanced commands are available to list owners with more sophisticated needs and some programming experience. If you encounter one of these commands in a template, you will probably want to leave it alone.

   .IM name	Imbeds (inserts) another template form at this point in the message. This is used to avoid duplicating large pieces of text which are mostly identical, such as the templates for "you have been added to list X by Y" and "your subscription to list X has been accepted". As noted above, LISTSERV will not pick up an "imbedded" template form from $SITE$.MAILTPL. If you wish to include an "imbedded" template form (e.g., $SIGNUP) in $SITE$.MAILTPL, you must also include the template form that calls it with the .im command.
   .DD ddname	Copies the contents of the specified DD into the message. This is meaningful only if a DD has been set up by LISTSERV for this purpose. As a rule of thumb, you should either leave these statements unchanged or remove them.
   .BB cond	Begin conditional block. The boolean expression following the keyword is evaluated and, if false, all the text between the .BB and .EB delimiters is skipped. Conditional blocks nest to an arbitrary depth. The expression evaluator is recursive but not very sophisticated; the restriction you are most likely to encounter is that all sub-expressions have to be enclosed in parentheses if you are using boolean operators. That is, ".BB &X = 3" is valid but ".BB &X = 3 and &Y = 4" is not. String literals do not require quoting unless they contain blanks, but quotes are accepted if supplied. Comparison operators are = <> ^= IN and NOT IN (the last two look for a word in a blank-separated list of options, such as a keyword value). These operators are not case-sensitive; == and ^== are available when case must be respected. Boolean operators are AND and OR.
   .SE var text	Defines or redefines a substitution variable. This is convenient for storing temporary (text) expression results which need to be used several times. Even standard variables such as &LISTNAME can be redefined - at your own risk. You must enclose the text expression in single quotes if you want leading or trailing blanks.
   .TY text	Types one line of text on the LISTSERV console log. This can be useful to the LISTSERV maintainer for debugging, and also to record information in the console log.

   10.5. Creating and editing a <listname>.MAILTPL file for a list

   Make a copy of DEFAULT.MAILTPL on your local machine and name it listname.MAILTPL. Keep the original DEFAULT.MAILTPL around in case you make a mistake and need to start over.

   At this point, you could theoretically store the listname.MAILTPL back on the LISTSERV host. However, without making any changes that would be somewhat pointless. At the very least you should edit the INFO template form before storing the template. Note also that you need only store the sections of the template that you have changed. For instance, if you edit the INFO template form but leave the rest of the template untouched, you can delete the rest of the template and store the INFO template form alone as listname.MAILTPL. The benefit to this approach is that any administrative changes to the rest of the default template are automatically applicable to your list as soon as they are made, rather than requiring that you edit your mail template individually to reflect such changes. L-Soft recommends that this approach be followed as the default.

   10.5.1. The INFO template form

   The first section of DEFAULT.MAILTPL is called the INFO template form, and it is LISTSERV's response to the command INFO listname. By default, it contains the following:

   ---

   >>> INFO Information about the &LISTNAME list
   There is no information file for the &LISTNAME list. Here is a copy ofthe list "header", which usually contains a short description of the
   purpose of the list, although its main purpose is to define various
   list configuration options, also called
   "keywords". If you have any question about the &LISTNAME list, write to
   the list owners at the generic address:
    
   .ce &LISTNAME-Request@&MYHOST
    .dd &LISTHDR

   ---

   Figure 10.1. The default contents of the INFO template form of DEFAULT.MAILTPL.

   Note the replaceable parameters &LISTNAME and &MYHOST. Don't change &MYHOST; LISTSERV replaces it with the correct value for the name of the host site. &LISTNAME automatically inserts the name of the list. It's probably best to use &LISTNAME to refer to the list throughout the document rather than to replace it with something like "MYLIST-L". This ensures that the template form will be consistent with the default and will be simpler to debug should a problem arise. Also, in the event the name of the list changes, it will be unnecessary to edit the template form (although it would have to be renamed to match the new name of the list, of course).

   Should it be desirable to replace the default INFO template form with information about the list, it is probably best to remove the .dd &LISTHDR line. This line instructs LISTSERV to read in the header of the list and add it to the response in lieu of any other data about the list. Many list owners add descriptive comment lines to their list headers, thus this default.

   Here is a minimally-edited sample INFO section for a list called MONKEYS:

   ---

   >>> INFO Information about the &LISTNAME list
   &LISTNAME is an open, unmoderated discussion list featuringmonkeys.  Things such as how to care for a pet monkey, monkey
   diseases, monkey lore, endangered species of monkeys, and
   monkey psychology are likely to be discussed.  The list is
   NOT intended for discussion of Darwinism and/or theories of
   evolution.
   
   If you have any question about the &LISTNAME list, write tothe list owners at the generic address: 
   .ce &LISTNAME-Request@&MYHOST

   ---

   Figure 10.2. Sample edited INFO template form.

   10.5.2. Other available template forms

   Version 1.8b introduced many new configurable message template forms, and, in particular, two new types of message templates for "linear" and optional messages. Several more template forms were added in version 1.8c. Traditionally, message templates have contained the text of "long" administrative messages, such as messages informing subscribers that they have been removed from a mailing list. These notices were sent unconditionally, as a separate message. The template processor now supports "linear" messages, which are sent as a normal command reply and allow the list owner to modify the replies from selected commands, and "optional" messages, which are only sent if a template for this action has been specifically provided by the list owner.

   In a linear message, most special instructions are ignored. This is because the contents of the template are just a few lines out of a larger message that is being prepared by LISTSERV to contain the reply to the user's command(s). For instance, you do not have any control over the "Reply-To:" field of the message, because the message in question is shared with other commands and, in fact, may not be a mail message at all but an interactive message to the user's terminal, a GUI request, etc. Generally speaking, with a linear message you are providing the TEXT of the reply to be shown to the user, but you do not have any control over the methods used for delivering this information.

   Here is a list of all of the template forms (other than INFO, described above) available in DEFAULT.MAILTPL, in the order in which they appear and with a short description for each. Linear and optional templates are noted where applicable.

   • MOVE1: Usually active only for peered lists. This message is sent to the subscriber when the list owner or LISTSERV maintainer changes which peer the subscriber receives his or her mail from.
   • SIGNOFF1: a notification to the list owner that someone has unsubscribed from the list. Whether or not the list owner receives this notification is controlled by the "Notify=" list header keyword.
   • SIGNOFF2: this message is sent to any user who attempts to unsubscribe from a list to which he or she is not subscribed under the userid from which the unsubscribe command has been sent. For instance, joe@unix1.somehost.com may be subscribed to list MYLIST-L. If his Pine client is set so that his mail comes from his root domain (e.g., joe@somehost.com), he will get this message if he tries to unsubscribe from MYLIST-L.
   • DELETE1: the message sent when a list owner or the LISTSERV maintainer deletes a user from a list. You can suppress the sending of this message by prepending "QUIET" to your "DELETE" command.
   • AUTODEL1: this is the message that is sent to users who are deleted by the delivery error monitor. You can customize it to fit your needs, or suppress it for your list by simply redefining it in the 'listname.MAILTPL' and using the .QQ instruction:

     >>> AUTODEL1 This message is not wanted for our list 
     .QQ 

     Note that L-Soft does not generally recommend suppressing this message, as it may indicate a serious problem for the deleted subscriber.

   • ADD1: the message sent when a list owner or a LISTSERV maintainer manually adds a subscriber to a list.
   • ADD2: the message sent to the list owner(s) when someone subscribes to their list. As with SIGNOFF1, whether or not the list owner(s) receive this message is controlled by the "Notify=" list header keyword.
   • ADDREQ1: this message is sent to the list owner when a user requests to join a list with "Subscription= By owner". Only the list owner is sent a copy of the ADDREQ1 message. If you use this template form to send new subscribers a questionnaire, application form or similar material, you will need to add a '.TO &WHOM' instruction to your modified template form, as by default the user does not receive a copy.
   • SETINFO: the message sent to the subscriber when the list owner or LISTSERV maintainer changes their personal subscription options. Can be suppressed by the invoker with the use of the "QUIET" command modifier.
   • ADDMOD2: the message sent to the subscriber when the list owner or LISTSERV maintainer changes the subscriber's "real name" field in the SIGNUP database.
   • ADDPW1: the message sent to the user when a LISTSERV maintainer adds a personal password for that user.
   • ADDPW2: an informational message sent to the LISTSERV maintainer when a user adds or changes his password, but only if an LSV$PW exit has been enabled to do so. Most installations will never use this template form, but it should not be deleted from DEFAULT.MAILTPL in any case.
   • ADDPW3: an information message sent to the LISTSERV maintainer when a user tries to add or change his password, but only if an LSV$PW exit has been enabled to do so. Most installations will never use this template form, but it should not be deleted from DEFAULT.MAILTPL in any case.
   • DELPW: the message sent to the user when a LISTSERV maintainer deletes that user's personal password.
   • RENEW1: this message is sent to subscribers whose subscriptions are due for renewal (see the Renewal= list header keyword for more information).
   • RENEW2: this message is sent to subscribers who did not renew their subscriptions within the grace period after being notified that their subscription was due for renewal.
   • SIGNUP1: the basic "Your subscription request has been accepted" message.
   • $SIGNUP: a template form included with SIGNUP1 and ADD1 (assuming that SIGNUP1 and ADD1 templates include an ".im $SIGNUP" line, which by default they do) which gives the subscriber a basic outline of how to use the list, how various options are set, and where to get more information on using LISTSERV. This template form can be used in lieu of a WELCOME file for a list if the list owner doesn’t want two messages to go to the user at subscription time.
   • SUB_CLOSED (linear): this is the message that is sent to a subscriber attempting to join a list with "Subscription= Closed". The default is "Sorry, the &LISTNAME list is closed. Contact the list owner (&OWNER) for more information."
   • SUB_OWNER (linear): this message is sent to a subscriber attempting to join a list with "Subscription= By owner". The default is "Your request to join the &LISTNAME list has been forwarded to the list owner for approval. If you have any question about the list, you can reach the list owner at &OWNER." Because this is a linear template form (see above), it is not the best place to put long questionnaires, application forms, terms and conditions, or other material that the subscriber should be required to review prior to joining the list. See the "Tips" section below.
   • POST_EDITOR (linear): this is the message LISTSERV sends to people attempting to post to the list, if it is moderated. The default is "Your &MESSAGE has been submitted to the moderator of the &LISTNAME list: &MBX(&MODERATOR)."
   • REQACK1: this message is sent automatically in reply to any message sent to the xxx-request address. The message acknowledges receipt, explains the difference between the LISTSERV and xxx-request addresses, and contains instructions for joining and leaving the list. To suppress this message for your list, simply redefine it in the 'listname.MAILTPL' and use the .QQ instruction:

     >>> REQACK1 This message is not wanted for our list 
     .QQ 

   • CONFIRM1: The message sent whenever an "OK" confirmation is required.
   • WWW_INDEX: this template form is used by sites which have implemented LISTSERV’s WWW archive interface. It includes the HTML code for the main archive access screen for the list. List owners should probably should leave this alone unless they know exactly what they are doing.
   • PROBE1: this template form is sent as part of LISTSERV's new bounce processing feature if this feature is activated for your list. The desired response from the user is to discard the message and do nothing. See chapter 4.6.2 of the List Owner's Manual for details on the "Probe" option.
   • PROBE2: If the mail containing the PROBE1 message bounces, this template form is sent along with a copy of the bouncing mail. See chapter 4.6.2 of the List Owner's Manualfor details on the "Probe" option.

   Several template forms for the WWW archive interface follow PROBE1. For more information on these template forms, see section 10.8, below.

   The following are template forms that can be defined, but which are not present in DEFAULT.MAILTPL.

   • POSTACK1 (optional): when present, this message is sent in reply to any message posted to the list. This is very useful for creating "infobots", or just for returning a standard acknowledgement to contributors. The &SUBJECT variable contains the subject of the original message, and naturally the usual substitutions (&LISTNAME, &DATE, &TIME) are available.
   • TOP_BANNER, BOTTOM_BANNER (optional): when these template forms are present, their contents are automatically inserted at the top (respectively bottom) of each and every message posted to the list. Typically, the top banner would be used for a copyright or short legal warning which absolutely has to be seen by each and every reader. The bottom banner could contain instructions for signing off the list, a disclaimer, an acknowledgement of a sponsor's contribution, a "tip of the week", etc.

     ---

     WARNING

     Documented Restriction: The use in banners of substitutions which do not yield a constant result (e.g., &TIME) will defeat the duplicate mail detection part of LISTSERV's loop-checking heuristics in any case where a subscriber is forwarding all mail back to the list. L-Soft advises that such substitutions never be used in a TOP_BANNER or BOTTOM_BANNER.

     ---

   For digests, note that the BOTTOM_BANNER is printed only once, at the top of the digest, directly following the table of contents. This avoids having the banner repeat after every message in the digest. The default behavior can be overridden if preferred by adding the "BOTTOM_BANNER" parameter to the Digest= list header keyword.

   10.5.3. Tips for using templates

   • Many list owners require prospective subscribers to fill in a little questionnaire before being added to the list, or to explicitly state that they have read the list charter and agree to follow all rules or be removed from the list. The most convenient method, for both list owner and subscriber, is to have the SUBSCRIBE command return a copy of the questionnaire (or list charter, etc), and not forward the request to the owner. The user answers the questions and returns them directly to the list owner, who then adds the subscriber manually. Naturally, it is more convenient for the user if this information arrives in a separate message, with a 'Reply-To:' field pointing to the list owner's address. Thus, you should not use the SUB_OWNER template form for this purpose, because it is a linear template and does not give you any control over the 'Reply-To:' field. The SUB_OWNER template form could be modified to read "A copy of the list charter is being sent to you, please read it carefully and follow the instructions to confirm your acceptance of our terms and conditions." The list charter would then be sent separately, through the ADDREQ1 template form. You would use the .RE OWNERS command to instruct LISTSERV to point the 'Reply-To:' field to the list owners, and .TO &WHOM to change the destination from list owner to subscriber. If you want to receive a copy of the message, you can use .TO &WHOM cc: xxx@yyy.
   • When writing templates, it is a good idea to use substitutions (&XXXX) for information which may change in the future. In particular, it is not uncommon for lists to have to be moved from one host to another, and this will be a lot easier if the template forms use substitutions for the list address and list host. The &LISTADDR substitution translates the full address of the list (XYZ-L@XYZ.COM), whereas &LISTNAME is just the name (XYZ-L). For references to the server and host, use &MYHOST for the Internet hostname, &MYSELF for the server address (normally LISTSERV@&MYHOST), and &OWNER for the xxx-request mailbox address. These substitutions are "universal" and can be used in all template forms. For instance, if you decide to make a bottom banner with instructions for leaving the list, the text could read: "To leave the list, send a SIGNOFF &LISTNAME command to &MYSELF or, if you experience difficulties, write to &OWNER."

   10.6. Storing the <listname>.MAILTPL file on the host machine

   The procedure differs slightly on VM systems, but the following will work for unix, VMS and Windows systems:

   1. Get a copy of DEFAULT.MAILTPL and edit it.
   2. Be sure that you have defined a "personal password" to LISTSERV with the PW ADD command before you PUT the template file. If you have done this but can't remember the password, send a PW RESET command to LISTSERV, then a new PW ADD command.
   3. Send the file to LISTSERV with a PUT listname MAILTPL PW=XXXXXXXX command at the top of the file, just as if you were storing 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 it can be PUT on the server and seen by LISTSERV.

   Note also that the LISTSERV maintainer can create and edit these files in place with any standard text editor. Changes made to template files in this way are available to LISTSERV immediately after they are saved.

   10.7. Other template files: DIGEST-H and INDEX-H

   Two other template files that are available pertain to the automatic digestification feature. You may create and store files called listname DIGEST-H and listname INDEX-H. These files define custom digest headers and custom index headers, respectively. Two other template files that are available pertain to the automatic digestification feature. You may create and store files called listname DIGEST-H and listname INDEX-H. These files define custom digest headers and custom index headers, respectively. The DIGEST-H and INDEX-H files are plain text files, like the WELCOME and FAREWELL files, and the instructions for storing them on the server are identical. Note that, as with the WELCOME and FAREWELL files, you cannot use the template formatting commands and replaceable parameters discussed above.

   A typical DIGEST-H or INDEX-H file for a list called MYLIST might contain:

   ---

   The MYLIST list is sponsored by ABig Corporation.
   
   See http://www.abig.com for information on ABig Corporation's products.

   ---

   Figure 10.3. Typical contents of a DIGEST-H or INDEX-H file.

   The contents of DIGEST-H and INDEX-H are appended to the digest or index, respectively, immediately following the list of topics. For instance,

   ---

   Date: Tue, 11 Jun 1996 11:52:41 -0500
   From: Automatic digest processor <LISTSERV@MYHOST.COM>
   Reply-To: My test list <MYLIST@MYHOST.COM>
   To: Recipients of MYLIST digests <MYLIST@MYHOST.COM>
   Subject: MYLIST Digest - 10 Jun 1996 to 11 Jun 1996
   
   There is one message totalling 10 lines in this issue.
   
   Topics in this issue:
   
     1. Testing 125...3 sir!
   
   The MYLIST list is sponsored by ABig Corporation.
   
   See http://www.abig.com for information on ABig Corporation's products.
   

   ---

   Figure 10.4. Sample DIGEST output for a list with a DIGEST-H file. The INDEX-H output would be similar, following the list of postings.

   (Note that you can't add a digest or index "footer" because anything after the end of the digest text is supposed to be discarded.)

   10.8. Template forms for the WWW archive feature

   The following are template forms for the WWW archive interface. L-Soft does not advise modifying these templates unless you know exactly what you are doing.

   Note that, although these templates are available in DEFAULT MAILTPL, individual list owners cannot tamper with them. If the LISTSERV maintainer desires to change the "look" of the site, it is preferable to create a file called www_archive.mailtpl (per chapter 5.4.5) rather than to edit the forms in DEFAULT MAILTPL.

   • WWW_ARCHIVE_LPOWERED: An internal file for the WWW archive interface. Do not alter this template.
   • WWW_ARCHIVE_INDEX: The basic INDEX.HTML page for the WWW archive interface. While this template form is available in DEFAULT MAILTPL, it cannot be changed by list owners.
   • WWW_ARCHIVE_USER_FORMS: Tells LISTSERV which additional "user" forms to format for your list. Do not alter this template form.
   • WWW_ARCHIVE_TRAILER: The page trailer file included by the WWW interface's CGI script.
   • WWW_ARCHIVE_HEADER: The page header file included by the WWW interface's CGI script.
   • $WWW_ARCHIVE_HEADER: Contains the header text for the WWW archive interface, e.g., what prints at the top of the page.
   • $WWW_ARCHIVE_TRAILER: Contains trailer text for the WWW archive interface, e.g., what prints at the bottom of the page.
   • WWW_ARCHIVE_SEARCH_HELP: Contains help text for the WWW archive interface's search functions. Do not alter this template form.

   10.9. Using the DAYSEQ(n) function

   A very powerful function introduced in 1.8c is the DAYSEQ(n) function. This function allows the list owner to code template forms (such as the PROBE1 or BOTTOM_BANNER messages) that change or "rotate" automatically.

   The DAYSEQ(n) function is invoked in a .BB - .EB conditional block, and n corresponds to the number of days in the rotation period, i.e., to the number of variations that you want to make to the text of the message. &DAYSEQ(n) returns a number from 1 to n which increases by 1 every day, with no special regard for weekends. That is, if the rotation period is to last for a week, you code DAYSEQ(7). If the rotation period is 15 days, you code DAYSEQ(15). Two examples follow:

   10.9.1. Rotating bottom banner

   To create a rotating bottom banner, follow this example. A list has three commercial sponsors, each of whom are provided with an advertisement every three days. (Note that this doesn't take weekends into account; in this example, if company A is featured in the banner on Monday, it will be featured again on Thursday and then again on Sunday. However, in the following week it will be featured on Wednesday, Saturday, and Tuesday, so it will actually get rather good coverage.) Our BOTTOM_BANNER template form would look like this:

   >>> BOTTOM_BANNER
   .BB &DAYSEQ(3) = 1
   Today's copy of the &LISTNAME newsletter has been brought to you
   by Company A.
   .EB
   .BB &DAYSEQ(3) = 2
   Today's  copy of  the &LISTNAME  newsletter has  been brought  to you  by
   Company B.
   .EB
   .BB &DAYSEQ(3) = 3
   Today's  copy of  the &LISTNAME  newsletter has  been brought  to you  by
   Company C.
   .EB

   (Naturally you can feel free to be more florid with your prose :)

   If a company needs to get a higher percentage of "air" time than another, you can simply assign it more than one of the possible n values of &DAYSEQ(n). For instance, if you have two companies but one should get twice as many days of "air" time, you might code something like this:

   >>> BOTTOM_BANNER
   .BB (&DAYSEQ(3) = 1) OR (&DAYSEQ(3) = 3)
   Today's copy of the &LISTNAME newsletter has been brought to you
   by Company A.
   .EB
   .BB &DAYSEQ(3) = 2
   Today's  copy of  the &LISTNAME  newsletter has  been brought  to you  by
   Company B.
   .EB

   This would cause Company A's message to appear on days 1 and 3 of the rotation period and Company B's message to appear on day 2 only.

   10.9.2. Rotating FAQ via the PROBE1 template and "Renewal= xx-Daily"

   In 1.8c, you can now code subscription renewal with daily granularity (however, please note that it is and remains inadvisable to use renewal intervals of less than a week). If you further code subscription probing into the "Renewal=" keyword with the ",Probe" parameter, you open up the possibility of turning the standard PROBE1 template form into a periodic FAQ. Here's how:

   We'll assume to start that you will code "Renewal= 15-Daily,Probe" in your list header. (You can experiment with other numbers, but since we have two messages and will be using &DAYSEQ(2), we need an odd renewal period.) We'll also assume that you want to send two versions of your FAQ each month; the first, a complete FAQ document, and the second, an abbreviated "reminder" version that just contains information about how to sign off, how to post to the list, and so forth. The basic algorithm is therefore:

   When &DAYSEQ(2) = 1, send the full FAQ.

   When &DAYSEQ(2) = 2, as it will 15 days later, send the abbreviated FAQ.

   Your PROBE1 template form would thus look like this:

   >>> PROBE1 Periodic FAQ posting for &LISTNAME
   &WEEKDAY, &DATE &TIME
   .BB &DAYSEQ(2) = 1 
   This is the  complete FAQ for &LISTNAME.  Please read it and  keep a copy
   for future reference.  A FAQ document for &LISTNAME  is distributed every
   15 days, the full FAQ alternating with a shorter "reminder" FAQ.
   
   <body of the full FAQ document>
   
   .EB
   .BB &DAYSEQ(2) = 2
   This is the abbreviated FAQ for &LISTNAME. Please read it and keep a copy
   for future reference.  A FAQ document for &LISTNAME  is distributed every
   15 days, the full FAQ alternating with a shorter "reminder" FAQ.
   
   <body of the abbreviated FAQ document>
   
   .EB

   11. The DISTRIBUTE Feature

   Note that DISTRIBUTE is also documented in RFC1429.

   11.1. Introduction

   The Relayed File Distribution (also known as DISTRIBUTE) feature was developed in an attempt to provide an efficient and network-resources-saving means whereby files and mail can be distributed to a large number of persons on the network by ANY network user, without having to resort to predefined distribution lists (which have other advantages but are basically static).

   This information guide is composed of two independent sections. The first one is a description of the distribution algorithm used by Relayed File Distribution. It is general enough to be accessible to inexpert computer users, but does not explain how to send a Relayed File Distribution Request (RFDR) to LISTSERV. The second section gives a detailed technical description of RFDRs and assumes the reader is familiar with the basic concepts of the Commands-Jobs Language Interpreter (CJLI). More information about CJLI is available in Appendix D.

   11.2. What is Relayed File Distribution?

   Relayed File Distribution is a service provided by the (growing) network of L-Soft LISTSERV servers to all users connected to the Internet and allowed to send and receive files or messages. (The origins of the service were on BITNET and associated services where it was possible to send files, as opposed to messages.) The user desiring to send the file (which we will call the 'sender') provides its nearest L-Soft LISTSERV host with a copy of the file to be distributed and the list of persons who are to receive it. He can optionally indicate the full name of these persons as well as his own full name, and they will be used in information messages and mail headers as appropriate. The LISTSERV hosts will then relay the file to each other as explained below and distribute the file to all the indicated recipients in the most efficient way they could 'manage'.

   The server that initially receives the file from the sender will first distribute the file to the (possible) recipients of its local node, which does not generate any network traffic. It will then examine the list of non-local recipients and determine, for each of them, which of the L-Soft LISTSERV servers is nearest. Whenever it finds itself to be the nearest server, it distributes the file directly, and removes the recipient from the list. It then uses a rather complex algorithm to "route" the remaining recipients through its nearest servers, and transmits the request to them. This will be best illustrated by an example.

   User X@FRECP11 sends a file distribution request for the following list of people:

   Y@FRECP11,X@CEARN,Y@CEARN,X@CZHRZU1A,X@NEUVM1,X@IBACSATA, X@EARNET, X@PSUVM

   We will assume that a L-Soft LISTSERV server has been installed at the following sites: FRECP11, CEARN, DEARN, DKEARN, EARNET

   Finally we will assume the following topology, which will not necessarily reflect the actual network topology at the time you read this chapter (it has been simplified and nodes which do not participate in the transfer have been removed)

                                    CZHRZU1A
                                        |
                                        |
                                        V
   FRECP11 --> FRORS31 --> FRHEC11 --> CEARN --> DEARN --> DKEARN --> NEUVM1
                                        |         |
                                        |         |
                                        |         V
                                        |       GWUVM --> PSUVM
                                        V
                                      EARNET --> IBACSATA

   The file is distributed by LISTSERV@FRECP11 to Y@FRECP11, and then forwarded to LISTSERV@CEARN, which will distribute to the two CEARN recipients and to X@CZHRZU1A. LISTSERV@CEARN then forwards one copy of the file to LISTSERV@DEARN and one to LISTSERV@EARNET, with the appropriate list of recipients. LISTSERV@EARNET distributes to the EARNET recipient and to X@IBACSATA. LISTSERV@DEARN distributes to X@PSUVM, and also to X@NEUVM1. LISTSERV@DKEARN does not receive anything because it would have served only a unique recipient, and in that case a direct send can only be better.

   The file has therefore crossed a total of 11 links. If it had been sent the normal way from FRECP11, it would have had to cross 32 links, i.e. thrice more. The reduction is very important because we assumed that a server is installed at all the central nodes in the network, which is not necessarily the case in practice.

   11.3. A description of Relayed File Distribution Requests

   Relayed File Distribution Requests (RFDR) must imperatively be transmitted as a commands-job file. It is recommended that you read Appendix D ("LISTSERV 'Commands-Job' Feature and CJL Interpreter") of this manual if you are not familiar with the basic concepts of CJLI.

   The job sent to the server must contain:

   • A JOB card with the "Echo=No" option to avoid tracing the unique command to the job output. The "Reply-via=" keyword can be set to "Message" if so desired, although this is not recommended. The job name can be anything you want, eg filename.filetype
   • A DISTRIBUTE command with the appropriate arguments:

     DISTribute < <MAIL> <DD=ddname> <FROM=u@n | FROM=DD=ddname>
     <ACK=NOne | MAIL | MSG> <TO DD=ddname | TO u@n1
     <...>> >
     <PRIOR=* | nn> <INFORM=MSG | MAIL>

     All the keywords can be omitted, but must be specified in the indicated order. The "PRIOR" and "INFORM" keywords are indepedent from the others and can appear anywhere in the command line. A description of the keywords follows:

     • MAIL indicates that the file to be distributed is a mailfile, to be sent to the MAILER at the destination node. The contents of the file are proofread and the "mail origin" is verified so that users cannot send forged mail. MAIL-type distribution is 100% transparent to the mail recipient, which is not the case with file distribution -- a file would come from the LISTSERV userid instead of the sender's userid. The mailfile must contain a blank "To:" line where the actual name and network address of each recipient will be automatically inserted as the file is distributed to him.
     • DD=ddname is the ddname corresponding to the data to be transmitted (ie the file or mailfile). The default is "DD=DATA"
     • FROM=xxxx indicates either the network address of the file sender or the name of a dataset of which the first line indicates the network address and full name of the file sender, eg FROM=DD=XXX and //XXX DD "JPB@BIGNODE John P. Brown". The default is FROM= your-userid. You are not allowed to specify an origin different from your own network address, of course, so you should not use that option unless you want to specify your full name. You do not have to indicate your name when distributing MAIL-type files -- put your name in the "From:"/"Sender:"/whatever field, as appropriate.
     • ACK= indicates the amount of acknowledgement you want to get. The default is NOne and indicates you do not want to receive messages as the file is distributed. MAIL indicates mail acknowledgements while MSG indicate interactive messages.
     • TO indicates the list of recipients for the file or mailfile. It can either be a list of network addresses ("TO u@n1 u@n2...."), which must not cause the physical command line to exceed 255 characters (use continuation cards in that case), or a ddname of which each line is a "userid@node <full name>" pair. The former is best suited to file distribution while the latter should be preferred for MAIL-type distribution since the recipient's full name will be inserted in the "To:" field of the mail file. The default is "TO DD=TO". Note that distributing a file to a LISTSERV userid will cause it to be interpreted as a command job for execution or a PUT request, as appropriate. Releases 1.5b and earlier did not accept such a destination for DISTRIBUTEd files and ignored the recipient.
     • PRIOR is the network transmission priority you want to assign to the file. If specified, it can be either "*" or an integer number between 0 and 99, inclusive. "*" indicates that the file priority is left up to LISTSERV, which will use an internal algorithm to assign a reasonable priority to the file according to its number of records.
     • INFORM specifies the media by which you want users to be informed of the arrival of the file. The default is MSG for interactive messages -- specify MAIL if you want LISTSERV to notify recipients via mail. Note that this option is ignored when MAIL distribution has been selected.

     --> Note about the PRIOR and INFORM keywords: these two options are not supported by servers whose release number is lower than 1.5d and would result in an error message if sent to such a server. However, those servers which can accept the keyword are able to identify the "older" servers and will suppress the option when forwarding the file to distribution to such a server. There should therefore be no compatibility problem.

     • A dataset for the "FROM=DD=" keyword, if specified -- the DD "text" syntax is recommended since the dataset will contain only a single line of data.
     • A dataset for the "TO DD=" keyword, if specified -- the DD * syntax is best suited to this dataset.
     • Finally, a dataset for the "DD=" keyword, to contain the file. This should be the last dataset in the file and the DD *,EOF syntax should be used to ensure that the dataset is not prematurely ended by a possible "/*" card in the data. Also, for storage space saving and performance considerations, the "Res=Disk" option should be specified on that DD card, ie: DD *,EOF,Res=Disk. Statistics have shown that this decreases the CPU time required to process the request by a factor of six...

   Mail-type RFDR must IMPERATIVELY use raw-image (PUNCH) format for the mail dataset, since the header will be scanned and modified by the server. File-type RFDRs can use any type of network filke format -- the contents of the "data" dataset will be sent "as is" to the recipients, without anything added on top or bottom of it. The only difference will be the RSCS file origin -- the file will come from the LISTSERV userid instead of the sender's userid. The file class, spool fileid and DIST-code are preserved, but the FORM is changed to QU-DIST to trigger the "quiet file transfer" feature installed in some RSCSs in the network.

   Non-BITNET addresses: non-BITNET recipients are routed to their gateway, as determined by the DOMAIN NAMES file. The first server in the chain that finds itself unable to determine the gateway distributes the file directly. Whenever non-mail file is distributed to a non-BITNET user, LISTSERV generates a sample mail envelope with the current date, sender's name and address, recipient's address and transfers it to the mailer. Any possible rejection mail will be sent directly to the sender by the mailing system (and not to the LISTSERV userid).

   11.4. Sample mail RFDR job

   //V22.5y JOB Echo=No
   DISTRIBUTE MAIL
   //TO DD *
   USER1@NODE1.SOMEHOST.COM Howard P. Craftlove
   USER2@NODE2.ANOTHERHOST.EDU June Guiness
   USER3@NODE3.YETANOTHERHOST.ORG 
        .
        .
   USERn@NODEn.LASTHOST.SE Sarah Crawford
   /*
   //DATA DD *,EOF,Res=Disk
   Date:          Sun, 12 May 1996 22:51:20 SET
   From:          O. Roger Simpson '31' <ORS@BIGVM.SOMEHOST.SE>
   Subject:       Version 22.5y of the WONDERful conferencing system
   To:
    
   Dear colleagues,
    
     Version 22.5y of the WONDER conferencing system is now ready. I am sen-
   ding  it now  via the  new DISTRIBUTE command of  L-Soft's LISTSERV.  You
   should receive three files, WONDER PKG1, WONDER PKG2 and WONDER INSTL225.
   Don't forget to issue a GIMME  CANCER command to the server after instal-
   ling the  new version, so that  you receive an up-to-date  version of the
   CANCER full-screen interface. Those of  you that are confined to teletype
   terminals may still use the old FRAIL  interface -- I didn't change it in
   this release.
    
   Happy WONDERing... /Roger

   12. List Exits

   ---

   Background for non-technical users: an "exit" is a program supplied by the customer to modify the behavior of a product (such as LISTSERV) in ways that the supplier of the product could not anticipate, or could not afford to support via standard commands or options. The product checks for the presence of the "exit" program and calls it on a number of occasions, called "exit points". In some cases, the "exit" program supplies an answer ("return code") to the main program, which adjusts its behavior accordingly. For instance, LISTSERV may ask an exit program "Is it ok to add JOE@XYZ.EDU to the ABC-L list?", and the program will answer yes or no, and possibly send a message to the user explaining why his subscription was accepted or rejected. In other cases, the "exit point" call is purely informative: the exit program gets a chance to do something, such as sending an informational message to a user, but does not return any answer. Because the exit is a computer program, it must be prepared by a technical person and installed by the LISTSERV maintainer.

   ---

   12.1. What is a "list exit"?

   Starting with version 1.8a, list "exits" have been available to control the major events associated with list maintenance. These exits are now available for non-VM systems as well. While the implementation of list exits is necessarily system dependent, the list exit themselves (i.e. the tasks that they may carry out, as opposed to how such tasks would be carried out on a particular operating system) are system independent.

   To prepare a list exit, you must go through the following steps:

   1. Create an appropriate exit program, as explained below. Let's assume that the program's name is XYZ.
   2. Modify the LIST_EXITS configuration option in the LISTSERV site configuration file (create one if none was present in your configuration). This variable lists the names of all the "known" exits. For security reasons, LISTSERV will not call an exit which is not listed there. To enable XYZ and ABC as valid list exits, you would set LIST_EXITS to "XYZ ABC" (with or without the quotes, depending on your operating system). You must reboot LISTSERV after making this change.
   3. Modify the header of all the lists which should call the XYZ exit, and add "Exit= XYZ". This tells LISTSERV to call the XYZ exit at various exit points.

   IMPORTANT SECURITY NOTE: Once an exit has been listed in the LIST_EXITS option, ANY list owner may activate it for his own lists. In other words, step 2 merely tells LISTSERV that the program is a "bona fide" exit. There is no mechanism to restrict the use of an exit to a particular list, because it is very easy to implement this in the exit itself, by checking that the name of the list is what you expect or allow.

   LISTSERV exits receive one or more parameters as input, and may provide a numeric and (in a few cases) supplemental string result as output. Each operating system has its own set of numeric return codes for various kinds of failures, but LISTSERV always uses the same internal return code system for its exits - anything else would quickly become unmanageable. The value 0 always means "success" or "normal/default action". Positive values indicate various non-default actions, depending on the particular exit point. Negative values indicate system errors. Exit programs are responsible for doing their own error reporting, since LISTSERV has no way to know which errors they may or may not run into.

   The location, name, programming language and calling conventions of the exit program vary from one operating system to another. Let's examine the basics first:

   • On VM, the program must be called XYZ EXEC A1 (on LISTSERV's A-disk) and must be written in REXX.
   • On VMS™, the program must be called XYZ.COM on LISTSERV's [.MAIN] subdirectory (LISTSERV_LISTS_DIR) and must be written in DCL.
   • On unix®, the program must be called XYZ and must be located in the 'home/' subdirectory (i.e., $A). To distinguish them from the standard L-Soft provided scripts and executables, exit programs must always be spelled in upper case. Thus, the program must be called XYZ and not xyz. It can be written in any supported language and LISTSERV must have execute permission.
   • On Windows NT™, the program must be called XYZ.CMD and must be located in the MAIN subdirectory. It must be written in the NT batch language.
   • On Windows 95™, the program must be called XYZ.BAT and must be located in the MAIN subdirectory. It must be written in the DOS batch language.

   Naturally, you are free to call a program in another language from your exit program. The programming language restriction only applies to the exit program itself.

   IMPORTANT: Even though the exit program is usually called from LISTSERV's root directory, it should not make any assumption about its current directory. For optimal portability, the program should always use absolute pathnames to access the various files it might need. For instance, list files should be accessed (if at all) as $A/ or A: or %A%\, and so forth.

   The exit may receive one or more string parameters as input. Most operating systems provide a mechanism to pass one parameter to a script or program, with some restrictions. However, LISTSERV may need to pass several parameters, and the restrictions may not be acceptable. Thus, a system independent parameter passing convention had to be designed. This convention is used by all systems except VM, where multiple parameters of arbitrary length and contents may be passed to a REXX program. On VM, the system independent convention is never used, because it is unnecessary and less efficient than the native method. VM exits use the standard PARSE ARG directive to retrieve their parameters.

   The system independent convention uses a disk file called 'exit.input' in the same directory as the exit program. This is a standard text file, where each record is one input string parameter. This file is always created if there are 2 or more string parameters for the exit, or if the EXIT_INPUT configuration parameter is set to the value 1. In addition, it is always created on Windows™ operating systems. Under VMS™ and unix®, the file is not created when there is only one parameter and EXIT_INPUT defaults to 0. Since most exits only have a single parameter, this improves performance in most cases. Note that LISTSERV will take care of deleting the 'exit.input' when appropriate.

   Regardless of whether or not the 'exit.input' file is created, the first parameter is always passed to the exit using system-specific methods under VMS™ and unix®. Under Windows™ systems, the first parameter is only passed through the 'exit.input' file. Again, this may simplify programming for simple exits.

   IMPORTANT SECURITY NOTE: LISTSERV will always quote/escape the first parameter to prevent the recognition of special characters by the underlying operating system. However, your program should be very careful in its use of the parameters in any subsequent system call. For instance, if the parameter to your unix® exit is the string "a|b", LISTSERV will quote the vertical bar so that it does not result in the execution of the program 'b', and so that the value "a|b" is present in your argument vector. However, you must still be careful in the use of the arguments within your program, especially if you plan to launch a compiled program from a shell and pass it the same arguments. In that case L-Soft recommends the use of EXIT_INPUT = 1, which allows the second program to read its parameters safely from the 'exit.input' file.

   For list exits, there is at least one input parameter, of the form (blank separated):

   epname listname more

   where 'epname' is the name of the entry point being called (SUB_FILTER, SUB_FAIL, etc), 'listname' is the name of the list, and 'more' depends on the particular exit point. Under VM, 'more' may contain '15'x characters delimiting additional parameters. Again, while 'epname' and 'listname' are unlikely to contain "tricky" characters, the same cannot be assumed about the remainder of the parameter string.

   In most cases, your program will only handle a limited set of exit points. When it does not recognize the 'epname', it should exit with the numeric result 0, which tells LISTSERV to take the default action. To exit with the result 0, you can take a normal operating system dependent exit. In particular, success status codes are translated to 0 under VMS™. To return any other numeric code, or to return a string code, you must use the system independent parameter return convention return below, except on VM where the operating system provides a suitable native convention for the return of one parameter of arbitrary length and contents. So, REXX programs return their results with a standard RETURN or EXIT statement. The first blank-delimited word is interpreted as the numeric result, and the rest, if any, is the string result. In other words, the return string is broken up into number and string in exactly the same manner as with a PARSE VAR RESULT NUMBER STRING instruction. On VM, the system independent return convention is not used, because it is unnecessary and less efficient than the native method.

   The system independent convention is based on a file called 'exit.output', in the same directory as the exit program. LISTSERV erases this file before calling your program, and reads it when it regains control. This file is a standard text file, which contains a number of directives. To set the numeric return code, you use the EXIT directive:

   EXIT 2

   This would set the numeric return code to 2. To set the string result, use:

   EXIT-STRING This is the exit string

   Note that you must ALWAYS set the numeric code if you want the string result to have any effect. The default numeric code is 0, which means "default behavior", and the default behavior never uses the string you supply. By definition, the default behavior is whatever LISTSERV would do if the exit were not present.

   In addition to EXIT and EXIT-STRING, a number of other directives are available. For instance, you can tell LISTSERV to send a message to the originating user, to explain why the exit rejected his subscription request, or whatever. These directives are processed sequentially until the end of the file. Note that the EXIT directives merely set the final exit codes. They do not interrupt the processing of the 'exit.output' file, which is always read to the end of the file. This means that, if you change your mind about the exit code, you can write a new EXIT instructions and LISTSERV will use the last value that you supplied.

   Each directive has 0 or more mandatory parameters, and may support a number of optional parameters, which are always listed after the mandatory ones. Some parameters may be simple blank-delimited keywords or options, while others may contain arbitrary data. The exit should not need to provide placeholders for optional parameters, and above all it should be possible to add new optional parameters without requiring all exits to be rewritten. To solve this problem, each directive was given two forms: a simple form, where the entire directive fits in a single line, and an explicit form, where you indicate the number of parameters that you intend to provide, and each parameter follows on a line by its own. In the simple form, the mandatory parameters are filled from the data supplied on the single directive line, and all the optional parameters are set to their default value. Each blank delimited word supplies one parameter, until the first N-1 parameters have been set. The remainder is used for the last parameter. Here is an example:

   TELL jack@XYZ.COM The FOO-L list is only open to FOO Inc. employees.

   Parameter 1 (mandatory): "jack@XYZ.COM"

   Parameter 2 (mandatory): "The FOO-L list is only open to FOO Inc. employees."

   Parameter 3 (optional): <default>

   If, on the other hand, you want to send the message to more than one person, you need to use the explicit form:

   TELL2
   jack@XYZ.COM cc: honcho@FOO.COM
   The FOO-L list is only open to FOO Inc. employees.

   It is always safer to use the explicit form if you are not sure how many words you will have in the various parameters. The simple form is provided mostly for directives such as EXIT or EXIT-STRING which only take one parameter, and for hardcoded parameters.

   Currently, the supported directives are as follows. The "VM API" indicates the corresponding REXX API for VM users (it is not possible to provide an API for non-VM systems because the exits run in a different virtual address space and may not call back into LISTSERV entry points).

   Name:	EXIT, EXIT-CODE, RETURN
   P1:	Numeric return code
   Action:	Sets numeric return code; does NOT abort exit.output processing!
   VM API:	EXIT/RETURN

   Name:	EXIT-STRING
   P1:	String result code
   Action:	Sets exit string result
   VM API:	EXIT/RETURN

   Name:	TELL, LTELL
   P1:	List of RFC822 addresses
   P2:	Message text
   P3 (opt):	Blank separated list of options (default = off)
   	- ECHO: echoes message to log
   	- RAGGED: flows but does not justify message
   Action:	Sends long (paragraph) message to specified users
   VM API:	LSVLTELL

   Name:	TELLNF
   P1:	List of RFC822 addresses
   P2:	Message text
   P3 (opt):	Blank separated list of options (default = off)
   	- ECHO: echoes message to log
   Action:	Sends unformatted message to specified users
   VM API:	LSVTELL

   12.2. List Exit Points

   The following list exit points are available as of Version 1.8c:

   12.2.1. ADD/SUBSCRIBE exit points

   Name:	SUB_FILTER
   Parameters:	One; originator's e-mail address
   Return code:	0=Accept, 1=Reject
   Description:	This exit point gives you a chance to reject a subscription request by returning a nonzero value. This adds to rather than replaces the "Filter=" keyword.

   Name:SUB_FAIL Parameters:One; originator's e-mail address Return code:Ignored/reserved - always return 0 Description:This exit point is called whenever a subscription is rejected (in particular, it is called if you return 1 from SUB_FILTER). You may send additional messages to the user, log the event, and so on.

   Name:	SUB_REQ
   Parameters:	One; originator's e-mail address
   Return code:	Ignored/reserved - always return 0
   Description:	The user's request for subscription is being forwarded to the list owners. You may send additional messages to the user, log the event, and so on. To implement custom subscription/rejection, use the SUB_FILTER exit with "Subscription= Open". When SUB_REQ is called, it is too late to let the user through.

   Name:	SUB_NEW, ADD_NEW
   Parameters:	One; originator's e-mail address
   Return code:	Ignored/reserved - always return 0
   Description:	This exit point notifies you that the user has been successfully subscribed to the list (SUB_NEW is for the SUBSCRIBE command, ADD_NEW corresponds to the ADD command). You can send additional messages, log the event, and so on.

   12.2.2. DELETE/SIGNOFF entry points

   Name:	DEL_FILTER
   Parameters:	One or two; target e-mail address '15'x originator's address
   Return code:	0=Accept, 1=Reject, 2=Interrupt processing of command
   Description:	This exit point is called for all SIGNOFF commands, and for DELETE commands issued by a registered Node Administrator. It is NOT called for DELETE commands originating from the list owner. If you return the value 1, LISTSERV does not delete the target e-mail address but continues to look for more addresses matching the pattern provided, and the exit will be called again as appropriate. If you return the value 2, LISTSERV simply interrupts the processing of the SIGNOFF command and terminates the command with no further message (i.e., you have to send your own explanation back to the command originator). If the request is rejected, you should check for the presence of the second parameter and send an explanatory message to that address, or to the target address if only one parameter was specified.

   Name:	DEL_SIGNOFF
   Parameters:	One; originator's e-mail address
   Return code:	0=Continue, 1=Do not notify owner
   Description:	This exit point is called for the SIGNOFF command only, when a user has been successfully removed from the list. The farewell message, if any, has already been sent. You may issue additional messages, log the event, and so on. A return value of 1 directs LISTSERV not to mail the "SIGNOFF1" form to the list owners.

   Name:	DEL_DELETE
   Parameters:	Two; target e-mail address '15'x originator's address
   Return code:	0=Continue, 1=Do not notify owner
   Description:	This exit point is called for the DELETE command only, after a user has been removed from the list. You may issue additional messages, log the event, and so on. A return value of 1 directs LISTSERV not to mail the "DELETE1" form to the list owners.

   12.2.3. SET exit points
   

   Name:	SET_REQ
   Parameters:	Three; originator's address, list of options to be altered, target e-mail address
   Return code:	0=Accept, 1=Reject, 2=Alter
   Description:	This exit point is called for all SET commands that do not originate from the list owner. The first parameter (originator's address) is the address you should use to send replies or informational messages to the command originator. The second parameter (list of options to be altered) is a blank-separated list of command options, in their canonical spelling. If topics have been specified, they are listed last, after the word 'TOPICS:', with the spelling provided by the user. Bear in mind that topic change requests are not necessarily a list of the new topics to be enabled, and may contain complex '+' or '-' directives. Finally, the third parameter (target e-mail address) is the address as it appears in the list, and is provided for the sake of completeness; in most cases you will not need to examine it. If you return the value 1, the command is rejected and no option is modified. A return value of 2 indicates that the list of options and/or topics should be altered before the changes are performed. The exit string must contain a replacement for the second input parameter, in the same format. LISTSERV will assume that any option or topic specified in this fashion are syntactically correct; while incorrect values will not cause any problem and will be properly rejected as invalid options, the error message(s) returned to the user may not be as helpful as they ordinarily would.

   12.2.4. General remarks

   IMPORTANT: List exits may not make any change to the LIST file, because the command processor may have changes of its own to make to the file, or may have kept the file open for further processing. If you really have to change the file, use CP MSG * CMS EXEC to schedule a new call to the exit after command processing completes.

   The template processor can be called from list exits. The syntax is:

   Call LSVTMAIL recipients,template_name,listname,keywords

   keywords = 'KWD1 value of first keyword'||'15'x'KWD2 second keyword'||...

   Note the change in calling sequence from LSVIMAIL. LSVIMAIL was removed in version 1.8b and is no longer available.

   12.3. Local command definition (non-VM)

   It is now possible to define "local" LISTSERV commands on non-VM systems. A "local" command is a locally developed extension to the LISTSERV command set, which can be installed without making any modification to LISTSERV itself. To install a local commands, you must perform the following steps:

   1. Create an exit program to implement the command, as described below. Let's assume the program is called ABC. Command and list exits share the same basic attributes and programming interface, and in particular they are located in the same directory and follow the same naming and calling conventions.
   2. Choose a name for your local command. Names starting with a letter are reserved for L-Soft use; other names are reserved for customer use. You could call your command /ABC for instance.
   3. Modify (or create) the file 'localcmd.file' in the main LISTSERV subdirectory (the same directory where the lists, exits and other LISTSERV files are located). You must register the command in this file to define its existence to LISTSERV and indicate which exit should be called to execute the command. The format is:

      /ABC 3 ABC DEF

      /ABC is the full name of the command, 3 is the minimum abbreviation (allowing /AB or /ABC), ABC is the name of the exit program to execute, and DEF is an optional parameter to be passed to the exit (this allows multiple similar commands to be served by the same exit).

   4. Optionally, modify (or create) the file 'localcmd.helpfile' in the same directory to provide a brief (1-2 lines) description of your new command. This is a free form file whose contents and append to the standard HELP message. If the command is important, you may want to mention it there.

   You do not need to reboot LISTSERV for the changes to take effect.

   The ABC program is called as an exit with two parameters. The first one takes the following form:

   origin command arguments

   where 'origin' is the address of the command originator, 'command' is the name of the command ('/ABC' in the present example), and 'arguments' are the command arguments, if any, provided by the user. The second parameter is the optional DEF parameter from 'localcmd.file'.

   Typically, your program will parse the arguments, decide on a course of action, and issue a number of messages to the user. The exit code is immaterial; there is no particular course of action to select for command processing.

   13. Distribution Features and Functions

   For more information on these features, see also the List Header Keyword Reference in Appendix B of this manual.

   13.1. Controlling the default level of acknowledgement to user postings

   You can control the default level of acknowledgement sent back to users when they post to the list with the "Ack=" list header keyword (see Appendix B for details). This is particularly important because it also controls the acknowledgement level for users who are not subscribed to the list and cannot, therefore, set personal options. While the value set for "Ack=" can be overridden for subscribers both by the setting of the "Default-Options=" keyword (which sets the default at subscribe time) and by the "SET" command, this option will always be in effect when distributing mail from people who are not subscribed to the distribution list.

   13.2. Controlling the maximum number of postings per day

   13.2.1. Controlling total postings to the list per day

   You can control the maximum number of postings per day on a list-by-list basis by setting the "Daily-Threshold=" list header keyword. The default value is 50 posts per day.

   Note the following:

   • If the Daily-Threshold value is not reached by midnight, the number of postings is reset to zero and starts over for the next day.
   • If the Daily-Threshold is reached before midnight, and the list is not freed before midnight, postings released after midnight count toward the next day's quota. Thus, if the list is held on Tuesday evening and 15 postings accumulate before you free the list on Wednesday morning, the 15 postings count toward Wednesday's quota.

   13.2.2. Controlling the number of postings per day from individual users

   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 limit.\

   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.

   13.3. Controlling "prime" time

   This feature reserves certain times and days of the week when you don't want LISTSERV to process postings. Although this is not usually necessary today, there can be certain applications for the use of the "PRIMETIME=" site configuration variable and the "Prime=" list header keyword.

   "PRIMETIME=" controls the server-wide prime time setting. By default it is set to PRIMETIME= 'MON-SUN: -'. There should be no need to change this setting under normal circumstances. Please see the entry for PRIMETIME in Appendix C for further details.

   The list header keyword "Prime=" controls prime time on a list by list basis. By default it is set to "Prime= Yes", meaning that it uses the value set globally by the PRIMETIME= variable. It can be set to an explicit time definition if necessary. For instance, you might have a very large announce-only list (e.g., a newsletter) that should not be posted until after midnight (when network traffic is low and more machine resources are generally available). You might wish to set this list with a "Prime=" setting of

   * Prime= "MON-SUN: 06:00-23:59"

   or, if you want the list only to be processed between midnight and 6 AM on weekends, you might code

   * Prime= "MON-FRI: 00:00-23:59; SAT-SUN: 06:00-23:59"

   Note that the specification for "Prime=" must be enclosed in double quotes.

   Mail sent to lists during prime time is automatically held until non-prime time and then distributed normally, without requiring further intervention by anyone. This means that the newsletter editor of the example list can post their next issue on Friday afternoon and know that it won't be distributed until Saturday at midnight or shortly thereafter.

   One of the most common misconceptions regarding the prime time settings is that prime time is the time during which LISTSERV will process postings for your list (or globally for the server if you change "PRIMETIME="). Please remember that when you set a "prime time" either for a list or globally for the entire server, you are setting the time during which LISTSERV does not process postings. It is "prime time" for the machine when it should be doing other things, e.g., number crunching, daily backups, or any other function during which LISTSERV should not be using cycles.

   13.4. "Holding" and "freeing"a list

   13.4.1. Automatic list holds

   On occasion, LISTSERV will automatically "hold" a list, i.e., postpone processing new mail for the list until either the list owner or the LISTSERV maintainer manually intervenes. There are two circumstances under which a list will be automatically held:

   • When the daily threshold of postings has been reached (see above and in Appendix B under "Daily-Threshold="). Note that a mailing loop may cause this to happen.
   • When an error occurs resulting in LISTSERV being unable to process new postings for the list. LISTSERV always sends a traceback of the error to the list owner along with the notification that the list has been held.

   In both cases, the list can be freed by either the list owner or a LISTSERV maintainer sending the command

   FREE listname PW=yourpassword

   to LISTSERV. However, note that for any hold, it may be wisest to wait until the LISTSERV maintainer has had a chance to check the server for anything untoward that might be causing the error (e.g., a mailing loop) before freeing the list.

   Note that an error indicating that the current notebook archive LOG file is open and locked by another process may actually indicate that the archive file is in a directory accessible by anonymous FTP and that someone is in the process of FTPing the current notebook archive, making it impossible for LISTSERV to append the latest posting to the current notebook. This error generally occurs only on systems with FTPable notebook archives; by the time you receive the error, it is usually safe to issue the FREE command to release the list. If, on the other hand, this error persists, you may want to check the server for "zombie" processes that may have the file locked, or set the location parameter of the "Notebook=" keyword to a non-FTPable directory.

   13.4.2. Manual list holds

   If you need to stop LISTSERV from processing new mail for a list for any reason, simply issue the command

   HOLD listname PW=yourpassword

   Then, to free the list, issue the FREE command as noted above.

   13.5. Controlling the list digest feature

   List "digests" are provided for those users who prefer to receive (typically) one large, comprehensive posting per digest period that includes all of the list traffic from that period, rather than receiving each post individually as processed by the server.

   If "Notebook= Yes...", the digest feature defaults to daily digests cut at midnight with the "work" files kept in the same directory as the list's notebook archives. If "Notebook= No", digests are not enabled by default. However, note that lists without notebook archives can have digests; it is simply necessary to enable digests manually for such lists by using the "Digest=" list header keyword and specifying a valid path for the location of the digest's work files.

   Digests can be set up to cut on a Daily, Weekly, or Monthly basis, and can be further configured to cut after a certain number of lines of data have been stored regardless of the digest period setting. This ability to generate "special issues" when the digest reaches a certain size may be necessary if people complain that your 10,000 line daily digest is getting truncated by their mail host to 1500 (or even 1000) lines.

   For example, if a high volume list is set for Daily digests, and the "Size(nnn)" parameter of the "Digest=" keyword for the list is set to "Size(1000)", a "special issue" of the digest will be cut and mailed to digest subscribers whenever the listname.DIGEST file reaches 1000 lines of text. Note that LISTSERV will not cut the digest at exactly 1000 lines, thereby truncating the last message; LISTSERV will cut the digest after the end of the message that causes the digest file to go over its limit. Thus, if the digest file is 950 lines long and a 200 line message is received, the "special issue" digest will be 1150 lines long.

   13.6. Setting up list topics

   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.

   The basic keyword syntax for defining list topics in the list header file is:

   * Topics= topic1,topic2,...topic11

   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.

   Finally, it is important to note that topics are active only when the subscriber's subscription is set to MAIL. Digests are indexes always contain all the postings that were made, because the same digest is prepared and sent to all the subscribers.

   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.

   See Chapter 6 of the List Owner's Manual and Appendix B for more information on setting up and using list topics.

   14. Error Handling Features and Functions

   14.1. Defining error handling addresses

   Every LISTSERV mailing list requires that an e-mail address be defined to which all mail delivery errors are sent for disposition. The error handling address is defined by using the "Errors-To=" list header keyword.

   The value for "Errors-To=" cam be one of two things:
   

   • An access-level, such as OWNER
   • A specific internet-address, such as someuser@somehost.com

   It is strongly recommended that "Errors-To=" point to a real person's mailbox, rather than to an alias that simply dumps errors into something like /dev/null. Mail delivery errors generally indicate that a problem exists, and it's always possible to filter out the ones that don't via procmail or by using the filtering features available in most POP mail clients. After a long enough period of time, unhandled errors can grow to a significant percentage of your server's traffic and seriously impact your production.

   If not defined in the list header, "Errors-To=" defaults to "Errors-To= Postmaster" (the LISTSERV maintainer).

   14.2. The auto-deletion feature

   LISTSERV includes a powerful auto-deletion filter that can be configured in several modes, depending on the level of error handling desired by the list owner. It should be noted, however, that at the present time there is no Internet standard for delivery error messages (although RFC1893 is gaining acceptance as just such a standard). Currently, LISTSERV understands and can take action on errors generated by LMail, LSMTP, Sendmail (version 8.7.x or higher), Innosoft's PMDF (version 4.2 or higher), and MadGoat's MX (version 3.2 or higher), as well as other mailers using the "Notary" format described in RFC1893. As more and more mailers conform to RFC1893, LISTSERV naturally will be capable of handling more and more errors intelligently.

   To set up auto-deletion defaults for a list, use the syntax described in Appendix B for the "Auto-Delete=" list header keyword.

   A sample error monitoring report, generated daily and sent to the list's "Errors-To=" address if "Auto-Delete=" is activated, is shown below:

   ---

   Date:         Thu, 30 May 1996 00:00:48 -0400
   From: "L-Soft list server at PEACH.EASE.LSOFT.COM (1.8c)"
                 <LISTSERV@PEACH.EASE.LSOFT.COM>
   Subject:      EXCEL-G: Daily error monitoring report
   To: EXCGERR@LINUS.DC.LSOFT.COM
   
   The following 3 subscribers were deleted from the EXCEL-G list today:
   
     sluggo@OMNI.VOICENET.COM
     Last error was: Mailer quasar.voicenet.com said: "550
                     <sluggo@OMNI.VOICENET.COM>... User unknown"
   
     crenaud@BOSS1.BOSSNT.COM
     Last error was: Mailer BOSS1.BOSSNT.COM said: "550
                     <crenaud@BOSS1.BOSSNT.COM>... User unknown"
   
     Roger Giellis <rogerg@SUPSUN4.DEN.MMC.COM>
     Last error was: Domain "SUPSUN4.DEN.MMC.COM" doesn't exist.
   
   The following 5 subscribers are currently being monitored:
   
   Err First Last  Address
   --- ----- ----- -------
     2 05/28 05/29 "Ronald D. Stepp" <MORITURI@INTELLISYS.NET>
                   Last error: Mailer INTELLISYS.NET said: "550
                               <morituri@INTELLISYS.NET>... User unknown"
   
     1 05/29 05/29 TEST@TEST.POWERNET.CO.UK
                   Last error: Domain "TEST.POWERNET.CO.UK" doesn't exist.
   
     1 05/29 05/29 SIMONC@VOL.NET
                   Last error: Mailer h02.VOL.NET said: "550 <simonc@VOL.NET>...
                               User unknown"
   
     1 05/29 05/29 REG@NROBBO.CO.UK
                   Last error: Domain "NROBBO.CO.UK" doesn't exist.
   
     2 05/29 05/29 jmanring@INETGW.LEGGMASON.COM
                   Last error: Unavailable; notary status was 5.1.2
   
   Err=   Number of delivery errors received thus far
   First= Date first delivery error was received (mm/dd)
   Last=  Date of most current delivery error (mm/dd)
   
   Subscribers will be automatically deleted from the list when delivery errors
   have been  reported for  a period  of 2 days  or more,  or when  10 delivery
   errors have  been received,  whichever occurs  first. Monitoring  will cease
   after 3 days without any reported error.
   
   Note: manually deleted subscribers may remain on the monitoring report under
   an alias address. Such entries will expire eventually; you do not need to do
   anything about them.

   ---

   Figure 14.1. A typical daily error monitoring report.

   14.3. LISTSERV's loop detection feature

   LISTSERV has an extremely advanced loop detection heuristic that practically eliminates the chances of a mailing loop being propagated through one of its mailing lists. In general, L-Soft does not recommend that any loop-checking element be disabled, as any one missing element might let a loop through, but under certain controlled circumstances it might be needful to do this. See Appendix B under "Loopcheck=" for specific keyword options to turn off individual parts of the loop-checking feature.

   14.3.1. The anti-spamming filter

   LISTSERV's anti-spamming filter is built into the loop-checking heuristic. Depending on your local circumstances, it may be desirable to disable the anti-spamming filter for certain lists, particularly if the lists are confidential (and thus not visible in the global list of lists, making it extremely unlikely that a spammer would target them), if the lists are set to reject postings from non-subscribers (e.g., "Send= Private" or "Send= Editor"), or if your LISTSERV server is not accessible from the Internet (e.g., you're running it on an internal LAN without Internet connectivity).

   If you need to turn the anti-spamming filter off for a particular list, code:

   * Loopcheck= NoSpam

   One (tunable) aspect of the anti-spamming filter involves holding mail from non-subscribers for a pre-determined length of time (the default is 10 minutes) to see if further mail arrives from the same user for other lists that may trigger the anti-spamming filter. If you want anti-spamming protection, but want mail from non-subscribers to go directly to a list without being held up for this check, you can code

   * Loopcheck= Spam-Delay(0)

   If you want the check to be performed, but think 10 minutes is too long to hold the messages, you can change the value for "Spam-Delay()" to the preferred number of minutes. For instance, to hold non-subscriber messages for five minutes, code

   * Loopcheck= Spam-Delay(5)

   Note also that you can configure the server-wide default for this "spam quarantine" feature by adding the new SPAM_DELAY variable to your site configuration file and specifying the number of minutes. For instance,

   SPAM_DELAY= 15

   would set the server-wide spam quarantine default to 15 minutes, while

   SPAM_DELAY= 0

   disables the feature.

   The rest of the anti-spamming filter algorithm is proprietary and non-configurable.

   15. List Maintenance and Moderation Features and Functions

   15.1. Setting up edited/moderated mailing lists

   As noted above in Chapter 7.12, you need only add the following lines to the 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.

   For more information on setting up edited lists, see "Send=", "Editor=" and "Moderator=" in Appendix B, as well as Chapter 7.12.2 of this manual where setting up edited lists is discussed further.

   15.2. Restricting the size of messages posted to the list

   Using the "Sizelim=" list header keyword, you can restrict the size (in lines) of messages posted to a given list. This may be particularly desirable for lists discussing programming topics where the posting of uuencoded binaries to the list is discouraged, or simply to encourage economy in posting. In any case, if this feature is desired, simply add the keyword

   * Sizelim= nnn

   to the list header, where "nnn" is the maximum number of lines to be accepted. Note that unlike the "Size()" parameter of the "Digest=" keyword, LISTSERV will not allow a post to go over the "Sizelim=" setting, but will reject it if it is even a single line over the allowable threshold. When a posting is rejected for size, the original poster receives a notification that his post was too large.

   Note that some misconfigured mail hosts will try to bounce delivery errors, complete with the text of the message that bounced, back to the list address rather than to the RFC821 MAIL FROM: address. Setting "Sizelim=" to a reasonable level (say, 400 lines) will usually prevent a mail host from bouncing a whole digest back to the list.

   15.3. Restricting the number of posts per user per day

   Starting with 1.8c, you can restrict the number of posts to the list per user per day. This is done with a new second parameter for the "Daily-Threshold=" list header keyword. For instance, setting "Daily-Threshold= 100,5" would tell LISTSERV to hold the list after 100 postings (as in earlier versions), and additionally to stop accepting new postings from any individual subscriber after that subscriber had posted 5 messages during the 24h period from midnight to midnight (server time). After reaching the user threshold, the subscriber simply receives a message to the effect that he has reached the daily limit and that he should try to repost the message later (i.e., after midnight). Please see the entry for "Daily-Threshold=" in Appendix B for further information.

   15.4. Moving a list to a new location: the New-List= keyword

   When a list is moved to a different LISTSERV host, this keyword can be added to the list header left on the original host. This facilitates forwarding of administrative commands and postings from the original host to the new host. Users posting to the old address will also receive a short note in return listing the new address. BITNET sites running 1.8b and later which are moving from VM to workstation versions of LISTSERV should probably use "New-List=" during their migration period.

   Note that this only works for a move from one L-Soft LISTSERV server to another, not for a move from a LISTSERV server to a server running another mailing list manager.

   See "New-List=" in Appendix B for more information about this keyword and how to use it.

   16. Security Features and Functions

   LISTSERV's security options are wide ranging, from almost no protection (easiest to administer a list, but also most open to hacker attacks) to total protection requiring validation of each and every command sent to LISTSERV for the list. It is also possible to limit access to various aspects of the list, such as who can subscribe, who can review the list of subscribers, and who can access the list archives. The list can be hidden 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.

   Please note carefully that LISTSERV does not set any file system permissions for any files. LISTSERV's security features are meant to allow and deny access to LISTSERV's various files depending on how various keywords are set, but in order to make your system completely safe, you must ensure that you have also set file and directory permissions appropriately for your operating system. For instance, LISTSERV may deny GET access to certain list archive files to non-subscribers, but if you have not set the appropriate file system permissions at the operating system level, you may have left open a window for someone to reach these files via anonymous ftp.

   16.1. First line of defense: The VALIDATE= keyword

   The VALIDATE= keyword controls the level of command validation desired for the 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 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.

   The next level is VALIDATE= YES. At this level, LISTSERV requires a password for all of its "protected" commands. This password can be either the list password or the sender's personal 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 VMS or Unix systems never require validation, as they cannot be forged. See Appendix B for more information on the VALIDATE= keyword.

   16.2. Controlling subscription requests

   Subscription requests are controlled 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. Subscription requests can be refused completely by setting SUBSCRIPTION= CLOSED.

   To code a list for open subscriptions without list owner intervention, set SUBSCRIPTION= OPEN. If it is desired 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.

   16.3. Controlling the service area of the list

   It may be desirable to restrict access to a 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.

   To simply hide a 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. Note also that all other non-subscribers, including users on the local machine, will not be able to determine that the list exists via a LIST command.

   To hide a 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=. The LISTSERV maintainer should define hosts and nodes that are considered local with the LOCAL site configuration file keyword. If the global definition is not suitable, it can be overriden by defining the LOCAL= list header keyword:

   * LOCAL= bitnode1,bitnode2,some.host.edu,another.host.com
   * SERVICE= LOCAL
   * CONFIDENTIAL= SERVICE

   If there are many subdomains within your primary domain, it may be preferable to use the wildcard when defining the LOCAL or SERVICE list header keywords. For instance:

   * SERVICE= *.HOST.COM

   defines the service area for a specific list as "all subdomains ending in .HOST.COM".

   Note that defining a service area for a list controls only from which domains subscription requests may be accepted. It does not control who may post to the list. Depending on local circumstances, it may be desirable to set lists with controlled service areas to Confidential= Service.

   16.4. Controlling who may review the list of subscribers

   For whatever reason, it may be desirable 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 allow anyone, including non-subscribers, to review the list, set REVIEW= PUBLIC (which is also the default).

   To restrict reviews of the list to subscribers only, set REVIEW= PRIVATE.

   To restrict reviews of the list to list owners only, set REVIEW= OWNERS.

   Reviews can also be restricted to users within the list's service area by setting REVIEW= SERVICE , and defining the SERVICE= keyword appropriately (see the preceding section).

   16.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.)

   If enabled, notebook archives are private by default.

   16.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.

   For a list where all posts should be forwarded to a moderator/editor, there are two 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:

   ---

   From:
    "L-Soft list server at PEACH.EASE.LSOFT.COM (1.8c)"
    <LISTSERV@PEACH.EASE.LSOFT.COM>
   Subject:      ACCESS-L: approval required (701AC4)
   To:           Nathan Brindle <NATHAN@LSOFT.COM>
   
   This  message  was  originally  submitted  by  joe@unix1.foo.bar.com  to  the  
   ACCESS-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 (26 lines) --------------------------

   ---

   Figure 16.1 The editor-header for a list set to Send= Editor,Hold

   A final 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   (or Send= Editor,Hold)
   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.

   16.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.

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

   • REPLY to the command confirmation request with the text "ok" in the body of the reply. (Non-case-sensitive) LISTSERV reads the "cookie" from the subject line and if it corresponds to a held job, the job is released and processed.

   If this does not work, it is possible that the Subject: line was corrupted in transit and you may need 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.

   Also note that the confirmations must come from the user id that originated the command. You cannot send a command from one account and then approve it from another.

   16.8. Denying Service to Problem Users

   In addition to methods listed above for restricting service areas and the like, LISTSERV has a varied set of methods whereby "problem users" may be denied service on several levels.

   16.8.1. The "Filter=" list header keyword

   List owners or LISTSERV maintainers may filter specific userids (or users matching a wildcard specification) on a list-by-list basis by using the Filter= list header keyword. For more information, see Appendix B.

   16.8.2. The "FILTER_ALSO" configuration file variable

   LISTSERV maintainers may add specific or wildcarded userids to LISTSERV's built-in filter by using the FILTER_ALSO= configuration file variable. Users matching this specification will be denied service to all LISTSERV services on your server.

   16.8.3 The "SERVE" command

   The LISTSERV maintainer may selectively "serve out" specific userids with the SERVE command. This use of the SERVE command creates a "hard" serve-out which only a LISTSERV maintainer may override, as opposed to the "soft" serve-out that occurs when 51 consecutive bad commands (raised from 21 in 1.8b) are sent to LISTSERV which any user (other than the served-out user) can override. This function is particularly useful for temporary suspensions of service to certain userids, as it does not require modifying the site configuration file, but naturally it may be used to serve users out permanently. The SERVE command does not accept wildcards, so if you need to suspend service to a class of users rather than to a specific user, you should use the FILTER_ALSO configuration file variable as described in 17.8.2.

   LISTSERV writes an entry for each served-out user to its PERMVARS.FILE. (Note: PERMVARS.FILE is not a plain-text file; do not edit it by hand.) To manually serve a user out, the LISTSERV maintainer sends the command:

   [QUIET] SERVE internet-address OFF PW=password

   The password is required. Acceptable passwords are the list creation password (CREATEPW), the system file modification password (STOREPW), or your personal password set with the PW ADD command.

   Note that prepending QUIET to the SERVE command suppresses notification to the user in question. If you are serving out an ID that is causing a mailing loop, you will probably want to use QUIET to avoid sending a fresh message to the looping ID.

   To restore service to a user previously served out, the LISTSERV maintainer sends the command:

   [QUIET] SERVE internet-address PW=password

   Again, the password is required.

   When a user is served out by the LISTSERV maintainer, assuming the QUIET modifier is not prepended to the SERVE command, a message similar to the following is sent:

   Date:         Wed, 15 May 1996 12:16:13 -0400
   From: "L-Soft list server at HOME.EASE.LSOFT.COM (1.8c)"
                 <LISTSERV@home.ease.lsoft.com>
   Subject:      Message ("Your access to LISTSERV has just been suspended...")
   To:           baduser@somehost.com
   
   Your access to LISTSERV has just been suspended by nathan@lsoft.com.
   Commands and postings from you will be ignored from now on.

   17. Subscription Features and Functions

   17.1. Setting up 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:

   • SEND the subscription request to LISTSERV.
   • REPLY to the confirmation request ('ok')
   • SEND the confirmation code (if necessary) ('ok 23CBD8', for example)
   • Send mail to the list owner (not to 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.

   17.2. Defining default options for subscribers at subscription time

   The LISTSERV maintainer or the list owner may specify subscribe-time 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.

   If setting "Default-Options=" for an existing list, you will probably want to issue QUIET SET commands for existing subscribers, particularly if you are defaulting an option such as REPRO. Setting "Default-Options=" does not affect current subscribers.

   Note that any default topics are set with the "Default-Topics=" keyword. See Appendix B for details on this keyword.

   17.3. Setting up subscription renewal

   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.

   To add subscription renewal, add the following keyword to the header of the list:

   * Renewal= interval

   or

   * Renewal= interval,Delay(number)

   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 Appendix B for more information on renewal and delay periods.)

   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() 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.

   The LISTSERV maintainer or the list owner can also issue the CONFIRM command for a subscriber:

   [QUIET] CONFIRM listname FOR net-address

   LISTSERV creates a daily report on its subscription renewal activities, telling you what users were requested to confirm subscriptions, and what users were deleted for failing to confirm the renewal request. This report is sent to the "Errors-To=" address for the list. A typical subscription renewal monitoring report is reproduced below:

   ---

   Date:         Thu, 30 May 1996 06:00:01 -0400
   From: "L-Soft list server at PEACH.EASE.LSOFT.COM (1.8c)"
                 <LISTSERV@PEACH.EASE.LSOFT.COM>
   Subject:      ACCESS-L: Subscription renewal monitoring report
   To: ACCERR@LINUS.DC.LSOFT.COM
   
   The following 3 subscribers were deleted from the ACCESS-L list today:
   
    AHUIE@FIN-AID.CSUHAYWARD.EDU
    byetter@ECLAT.UCCS.EDU
    mgill1@IX.NETCOM.COM
   
   The following 5 subscribers were requested to confirm their subscription to
   the ACCESS-L list:
   
    Ernest_HILL%KN=NYC=ZE@MCIMAIL.COM
    dave@MAIL.DERBY.K12.KS.US
    dianna@INTEX.NET
    koa@KOAMAR.COM
    leider@STR.DAIMLER-BENZ.COM

   ---

   Figure 17.x. Typical daily subscription renewal monitoring report.

   18. Other Features and Functions

   18.1. Setting up national language mail templates

   While LISTSERV is not shipped with non-English language mail templates, it is possible to create such "national language" templates and make them available on a list-by-list basis by using the "Language=" list header keyword. The procedure to use national-language templates is as follows:

   1. Translate DEFAULT.MAILTPL (or a desired subset of the templates in DEFAULT.MAILTPL) into the desired language.
   2. Call the translated template file idiom.MAILTPL, where "idiom" is replaced by the name of the language, e.g., FRANCAIS.MAILTPL, ESPANOL.MAILTPL, etc.
   3. Store the file on the server with a PUT.
   4. For lists that will use the national language template, code "Language= idiom" in the list header. For instance, if the national language template is called FRANCAIS.MAILTPL, code "Language= Francais". If you've called it FRENCH.MAILTPL instead, then code "Language= French".

   Note that LISTSERV's hard-coded messages will continue to be issued in English, and any editable template not present in your national language template will be pulled from DEFAULT.MAILTPL (or the list's own MAILTPL file, if it exists) when needed.

   See chapter 10 for more information on creating and editing LISTSERV's mail templates. L-Soft does not provide national language mail templates.

   18.2. Translating control characters included in list mail

   LISTSERV now removes control characters from mail messages by default and expands tabs in the process. Control characters usually have undesirable and unexpected results, as they seldom survive the double ASCII->EBCDIC->ASCII translation and cause the recipient's terminal to execute sequences different from the ones meant by the message sender - not to mention the case of ASCII control characters on EBCDIC terminals. Furthermore, certain combinations of control characters were found to create problems with IBM's SMTP (due to unexpected CRLF sequences appearing in the middle of a record after translation). Lists which absolutely require control characters must have a "Translate= No" keyword added to their header.

   18.3. Communicating with list owners

   The LISTSERV maintainer may have occasion to communicate with some or all of the list owners who run lists on his server. This does not require that the LISTSERV maintainer keep a "super-list" of list owners, but only that he or she use certain addresses when communicating with list owners.

   18.3.1. The listname-REQUEST alias

   If you need to communicate with all of the list owners of a single list, simply address your mail to listname-REQUEST. This special address will be expanded by LISTSERV to include all non-quiet list owners of the specified list. For instance, mail to the list owners of the PEKINESE list on LISTSERV.SIRIUS.NET would be addressed to PEKINESE-REQUEST@LISTSERV.SIRIUS.NET.

   18.3.2. The ALL-REQUEST alias

   If you need to communicate with all of the list owners on your server, simply write to the special ALL-REQUEST alias. ALL-REQUEST is expanded by LISTSERV to include all list owners of all the lists on your server. Note that ALL-REQUEST should only be used in emergencies, or when all list owners need to be informed that something is happening, such as a migration from one server to another.

   18.3.3. Configuration required for unix servers and VMS servers running PMDF

   Note that VM servers, VMS servers running MX, and Windows servers do not require that any special aliasing be added for these aliases. This functionality is built-in for those installations.

   You should already have coded "listname-request" aliases into your /etc/aliases file (unix) or your PMDF aliases file (VMS running PMDF) for each list on your server. See chapter 7 for more information on coding these aliases.

   If you are running a unix server, or a VMS server running PMDF, you will probably have to code an alias for "all-request" into your aliases file, as this is not normally done at install time. See your installation guide for information on how to code the base-level "listserv" and "listserv-request" aliases and follow those instructions to add an alias for "all-request".

   19. Special Functionality for ISP's

   These functions require that your site is appropriately licensed for them. Specifically, your LAK must contain the ISP "Scope" option. Contact the L-Soft sales department for details.

   Currently the ISP functionality is under development and does not include a complete suite of tools that an ISP might find useful. If you have suggestions for useful tools (other than accounting tools which are in development), please feel free to write to MANUALS@LSOFT.COM with your comments, which will be turned over to the developers.

   19.1. Directory quotas for individual lists

   Currently there is no warning message when a list hits a preset percentage of its storage quota, so this function should be used with care.

   19.1.1. The QUOTA.FILE

   LISTSERV uses a file called quota.file to store quota information for individual lists. The quota.file must be installed in LISTSERV's "A" directory (the same directory where LISTSERV keeps list files and its other standard data files). The file is a flat text file with the information for each list kept on one line, as follow:

   /HOME/LISTS/MYLIST-L     1024    Owner
   (1)                      (2)     (3)

   Notes:

   (1) The directory where the notebook archives and any other user-maintained files belonging to the list are kept. This specification should be the same as the specification in the "Notebook=" keyword (for lists with notebook archives) or the same as the specification for the file archives directory for the list in site.catalog (for lists without notebook archives).

   (2) The size (in kilobytes) of the list's quota. Note that 1024 kilobytes = 1 megabyte, so multiply the desired number of megabytes by 1024 to set this value.

   (3) The person who should be notified when the list goes over quota; in this case, the access-level "Owner" means that the list owner is notified. This value can also be a regular internet-address.

   19.1.2. Displaying quota information

   To display current quota information, issue the command

   SHOW QUOTA

   LISTSERV will respond with a listing of the lists for which quotas are set, along with the quota setting and percentage of quota used. A typical SHOW QUOTA report is reproduced below, for lists called ALIST, BLIST, and so forth:

   ---

   Date:         Mon, 17 Jun 1996 17:09:38 -0400
   From:         "L-Soft list server at HOME.EASE.LSOFT.COM (1.8c)"
                 <LISTSERV@HOME.EASE.LSOFT.COM>
   Subject:      Output of your job "NATHAN"
   To:           Nathan Brindle <NATHAN@LSOFT.COM>
   
   > show quota
   Directory                      Quota  Usage
   ---------                      -----  -----
   E:\FTP\LISTS\ALIST                4M     0k  ( 0.0%)
   E:\FTP\LISTS\BLIST                4M     4k  ( 0.0%)
   E:\FTP\LISTS\CLIST                4M   323k  ( 7.8%)
   E:\FTP\LISTS\DLIST                1M    11k  ( 1.0%)
   E:\LISTS\ELIST                    4M    11k  ( 0.2%)
   E:\LISTS\FLIST                    4M   940k  (22.9%)
   E:\LISTS\GLIST                   50M   9.8M  (19.5%)
   E:\LISTS\HLIST                    4M    66k  ( 1.6%)
   

   ---

   Figure 19.1. Typical output of a SHOW QUOTA command issued by privileged user

   Your list owners (or the person(s) indicated by the third parameter in quota.file for the list) can also issue the SHOW QUOTA command, but they will receive quota information only for the list(s) for which they appear in that third parameter.

   19.1.3. Reloading quota information after making changes

   Whenever you change values or add or delete lists from quota.file, you must issue the command

   SHOW QUOTA RELOAD

   to reload the quota file. (Rebooting LISTSERV also reloads the information.)

   19.2. Limiting the number of subscribers to a list

   Using the special Limits= keyword, you can limit a list to a specified number of subscribers. Only a LISTSERV maintainer may raise, lower, or disable this limit. An attempt by a list owner to change or disable the limit will result in an error message being returned to the invoker and no change being made to the list header.

   To enable the subscriber limit in the list header, code

   * Limits= Sub(nnn)

   where nnn is the number of subscribers you want to limit the list to. For instance, a list coded Limits= Sub(200) would be limited to 200 subscribers.

   20. When things go wrong

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

   This FAQ is also available at http://www.lsoft.com/lsv-faq.html
   

   1. I've just made a list called TEST.LIST. When I tried to add subscribers, I got the following error:
   

   >>> Error X'0028005B' updating file F:\listserv\main\TEST.LIST <<<

   -> Severity: Error

   -> Facility: LFxxx routines

   -> Abstract: File not opened in update mode

   -> I/O mode: Record read + update
   

   This error generally occurs on the workstation systems when a list file has been manually inserted into LISTSERV's main directory (e.g., created with vi or Notepad) and LISTSERV was not restarted before a command arrived for the list (e.g., an ADD or DELETE command). LISTSERV must be restarted to reformat the plain text file before the list can be used.

   2. I've installed LISTSERV on my unix machine and can't get it to run. When I type "go", I get an error message that says ">>> Cannot create '/listserv.PID' <<<". What do I do?
   

   This is caused by the LISTSERV spool directory being either not defined or set to the empty string. Check go.user and go.sys to see if the spool directory is correctly defined, typically as something like "/home/listserv/spool/listserv.pid".

   3. Help! I have LISTSERV installed on my machine called WWW.MYCORP.COM, but when I send mail to it, it says something like "<listserv@www.mycorp.com>...no such user."
   

   There are a couple of possibilities.
   

   • Does WWW.MYCORP.COM get its mail via a mail exchanger? If so, the error may actually be coming from the mail exchanger rather than from the machine LISTSERV is running on. You may be able to fix this problem by having the system administrator change the DNS records for WWW.MYCORP.COM so that mail goes directly to the LISTSERV machine, or by adding a mail alias that redirects mail sent to the non-existent LISTSERV account on the mail exchanger machine to LISTSERV@WWW.MYCORP.COM.
   • Is WWW.MYCORP.COM the only name for your machine? Check with your system administrator to see if there are any variant CNAMEs or MX records in the DNS that point to your machine. If so, you just need to add these aliases to the MYDOMAIN variable in LISTSERV's site configuration file. This is particularly important when running under Windows NT or Windows 95.
   • If running under Unix, did you create the Sendmail aliases for listserv and owner-listserv as outlined in the Installation Guide?

   4. I've successfully created a list on my Unix machine, and it's listed when I send the LISTS command to LISTSERV, but when I try to send mail to it, I get back a "user unknown" error.
   

   You need to create Sendmail aliases for the list. This is explained in the Installation Guide that comes with the software, or above in Chapter 7.7.1.

   5. When I type "go" on a unix installation to start the server, I get a core dump.
   

   You need to execute "dbx lsv core" (or "gdb lsv core") and then type "where" (or "bt"). Then send this information to support@lsoft.com. L-Soft can't trace the problem without this traceback.

   Also, you should check go.user and go.sys for anything unusual that might have caused the dump. It will probably help (and save time) if you send copies of go.user and go.sys along with the dbx or gdb traceback.

   6. I'm running LISTSERV on OSF/1 (Digital Unix), and on the listserv account I get many messages like this:

   >Unaligned access pid=3804 <lsv> va=141c62f4 pc=12071954 ra=12071928 type=ldq

   The kernel fixes unaligned accesses, so this only affects performance. We fix them when reported, but most people ignore them because they don't have much of an impact. That is, when people migrate their applications to OSF/1, they find that many produce these errors, so they end up just disabling them for the entire system. Note that unaligned accesses are specific to OSF/1 (or Digital Unix).

   When reporting an unaligned access problem, first please do SHOW LICENSE and let us know the build date. Then use the uac command to request a core dump on the unaligned access, then do 'dbx lsv core' and 'where' and send us the traceback.

   7. I keep getting error mail that has a bad return path, e.g., "Return-Path: <<@@somehost.com>>". Why is LISTSERV doing this?
   

   The answer is that LISTSERV isn't doing this. You have a bug in sendmail, probably as a result of a bad rewrite rule in sendmail.cf. The Return-Path: line is inserted by sendmail as it delivers the message, not by LISTSERV.

   If you are running a sendmail version prior to version 8.7.x, the simple solution to this problem would be to upgrade your sendmail to the latest version. Version 8.7.x has a much-simplified sendmail.cf that eliminates most of the chance for error on a standard installation.

   8. LISTSERV is running, but mail to LISTSERV is bouncing back with errors like
   

   lsv_amin: Unable to deliver mail to: owner-listserv

   lsv_amin: **Error(13)** A call to fopen() failed.

   554 "|/usr/local/bin/lsv_amin -t owner-listserv"... unknown mailer error 202

   You must ensure that the permissions on the spool directory are set to allow lsv_amin and 'listserv' to create new files. Almost all such errors are a direct result of insufficient permission settings. In particular, Error(13) means insufficient permission. Note that the permission setting for lsv_amin itself should be 4755.

   9. Turnaround time on mail sent to LISTSERV or to lists on my server is poor.
   

   On unix machines, check the version of Sendmail you are using. Most commercial unixes ship with Sendmail version 5 or earlier, which can handle at most a few thousand deliveries/day. L-Soft recommends that any unix site running LISTSERV upgrade to Sendmail version 8.7.x.

   On non-unix machines, you will need to "tune" your MTA (mail transfer agent) for maximum efficiency. You'll want to check things like how much the machine is paging and so forth. For high-volume VMS and Windows LISTSERV machines, you will want to use the "SMTP workers" (configured with the SMTP_FORWARDx= parameter in the configuration file) to process outgoing mail in parallel.

   10. We've got a postmaster at some site complaining to the effect that, "Your server machine keeps connecting to our GenericWare SMTP server and sending EHLO. Isn't this an error?" (Note: this complaint will generally occur only when you are running LSMTP with LISTSERV.)
   

   No, it is not. The SMTP protocol (RFC821 et seq) dictates that SMTP servers must answer "500 Unrecognized command" (or similar) when they receive a command they do not understand. The new ESMTP protocol, introduced in the early 90s, relies on this assumption for proper operation. After receiving a 500 reply to the new EHLO command, the server will send a normal HELO command and the transaction will continue using the original SMTP protocol.

   SMTP servers which close the connection when they receive an unknown command are in violation of RFC821 and are unable to communicate with ESMTP servers. Closing the connection looks exactly the same, to the ESMTP server, as a network failure. Since the server thinks the network connection has failed, it enqueues the message for retransmission.

   The solution is for the problem site to modify their SMTP server to return a 500 error code when receiving an unknown SMTP command. We understand that in some cases this may not be an option. For instance, they may be using a very old product whose vendor may have gone bankrupt or may have decided not to make the change because they are phasing out the product, or whatever the case might be. However, please understand that the current versions of most SMTP products use ESMTP, and that people want to use ESMTP because of the improvements it offers over the original (1982) SMTP protocol. In other words, this problem is not specific to L-Soft; it is specific to the software the site is using. ESMTP-compatible servers are commonly available, commercially and as freeware, for most operating systems.

   11. I'm suddenly being deluged with tons of "You are not allowed to use inter-server DISTRIBUTE control keywords" errors. What's going on?
   

   When this occurs, it's usually right after you've updated BITEARN NODES, and usually because you ftp'd the file directly into the directory where it belongs while LISTSERV was running. You can fix this by issuing the NODESGEN command, either by mail or from the console, to rebuild the routing files, or simply by stopping and restarting LISTSERV.

   Another cause of this problem can be that you've ftp'd BITEARN.NODES in binary rather than ASCII mode. If so, you'll have to ftp the file again.

   Beginning with version 1.8c, BITEARN NODES on registered, networked non-VM servers is updated using the same mechanism as PEERS NAMES and other LISTSERV tables. Note that this requires that your mail server support incoming mail files of at least 1.5M. BITEARN NODES on VM servers continues to be maintained via the UPNODES procedure.

   The proper method for updating BITEARN.NODES manually (e.g., for a non-registered and/or non-networked server) is to ftp the file into a scratch directory, stop LISTSERV, move the file into the appropriate directory, then restart LISTSERV. It's never a good idea to overwrite the file when LISTSERV may be accessing it. If you're mirroring BITEARN.NODES, be sure that your mirror is not pointing to the working copy; always mirror to a directory not used by LISTSERV.

   12. Our LISTSERV is running on LISTSERV.MYCORP.COM, but the "From:" field reads WWW.MYCORP.COM.
   

   This is due to using a sendmail that rewrites the address and having LISTSERV.MYCORP.COM as a CNAME in your DNS. You can fix it by telling sendmail not to rewrite addresses, or by using a MX record. If you decide to change your sendmail.cf to remove the rewrite rule, be aware that this is a long change that is only short in the 'meta' config files for V8. Previous versions will require that you change a substantial number of lines.

   13. The LISTSERV kit for Linux compiles fine except for 'make server'.
   

   This is a problem that has been solved with the release of 1.8c. Earlier versions of the software could not be compiled under Linux ELF kernels (but pre-compiled versions ran fine) LISTSERV is now fully-ELF compatible so this problem should no longer be an issue. Note, however, that the current kits are not known to run (and are not supported) under Linux kernels prior to 1.2.13.

   14. I'm running Windows NT (or 95) and want to know if I can run a POP mail server (or other SMTP server) on the same machine as LISTSERV.
   

   For Windows 95, the answer at present is no. For Windows NT, the answer is that the only SMTP server currently available that will not conflict with LISTSERV is LSMTP. The reason for this is that, due to the lack of a true Internet mail API for Windows systems, the SMTPL.EXE "listener" requires exclusive access to the SMTP port for incoming mail. Windows NT LISTSERV machines can use LSMTP in place of SMTPL.EXE because LSMTP has a built-in interface to process mail bound to LISTSERV and lists running on LISTSERV. And LSMTP for Windows NT has a built-in POP3 server.

   L-Soft is currently reviewing other SMTP products for Windows machines to determine if they can be used with LISTSERV.

   Note that it may be possible to run a second SMTP server on the same machine if you have two network cards, each listening to a different IP address. However, PLEASE NOTE CAREFULLY that if your second SMTP server cannot be configured to listen to only one of the cards, you will not be able to resolve the conflict. This configuration has not been tested and is not supported by L-Soft at this time.

   Please note that this restriction does not prevent you from running a Web server or FTP server on the same machine with LISTSERV. Web and FTP servers don't use the SMTP port, so there is no conflict.

   15. I'm getting complaints on several of our lists that listserv is issuing duplicate copies of list mail (or digests) to the users. What could be causing this?
   

   LISTSERV probably isn't doing this (in fact, it's almost impossible for LISTSERV to be doing this), but to be sure you should check the daily log for any discrepancy. The most likely causes of this problem are:
   

   • A broken unix gateway somewhere between LISTSERV and the recipient that is sending the duplicate mail (this has to do with how unix Sendmail recovers from crashes). Generally this problem will appear and disappear, although it's entirely possible for it to go on for days or weeks, depending on how broken the gateway is.
   • Duplicate subscriptions for the user on the list. Look for UPPERCASE and lowercase userid duplications where the rest of the userid@host combination is the same; look for users who may have two slightly-different subscriptions (e.g., joe@somehost.com and joe@unix1.somehost.com); and finally, look for users who may have an account on one host .forwarded to a second host but still has subscriptions for both accounts. (This last is extremely common in these days when people jump from ISP to ISP almost on a whim.)

   16. When installing the LISTSERV evaluation kit for Windows NT, the setup program shows an hourglass but then terminates without doing anything.
   

   This is a very strange problem that only seems to occur when the Netscape WWW server is running on the LISTSERV machine. The only solution is to stop Netscape Server until after the LISTSERV setup program completes. The problem appears to be related to Netscape and certain Windows setup engines and does not affect the operation of LISTSERV itself.

   21. Contacting L-Soft

   21.1. Support

   L-Soft international recognizes that the FAQ questions in chapter 20 are not going to solve every problem you may face. We are always willing to help diagnose and correct problems you may be having with your registered LISTSERV server. To that end, please note the following when you write to L-Soft with a problem report:
   

   1. Make the subject line of your report indicative of the problem. L-Soft receives a great deal of mail with the subject "Help!", which is not very helpful when we receive them.
   2. Include any appropriate log entries. LISTSERV keeps logs of everything it does, and without the log traceback, it is often impossible to determine what caused a given error.
   3. If you're running a Unix server and LISTSERV dumps core, please run the debugger on the core file (see question #5 in chapter 20, above) and include the results.
   4. Always send a copy of your site configuration file (with the passwords x'ed out).
   5. Send along anything else that you think might be helpful in diagnosing the problem.

   If you are running an evaluation version of our software, please send your trouble reports to the evaluation users' list, LSTSRV-E@SEARN.SUNET.SE.

   If you are running the Windows 95 shareware server, please send your trouble reports to the LISTSERV for Windows 95 mailing list, LISTSERV95-L@WIN95.DC.LSOFT.COM. This includes registered users of the software.

   If you are running LISTSERV Lite, please send your trouble reports to the LISTSERV Lite support mailing list, LISTSERV-LITE@PEACH.EASE.LSOFT.COM. This includes registered users of the software.

   If your LISTSERV Classic server for VM, VMS, unix, or Windows NT is registered and has paid-up maintenance, you may send problems to SUPPORT@LSOFT.COM for a quick reply.
   

   21.2. Sales

   To reach our worldwide sales group, simply write to SALES@LSOFT.COM. You may also call 1-800-399-5449 (in the US and Canada) or +1 301-731-0440 (outside the US and Canada) to speak to our sales representatives.
   

   21.3. Manuals

   To comment on this or other L-Soft manuals, please feel free to write to MANUALS@LSOFT.COM, and be sure to mention which manual you are commenting on.

   ---

   Links:

   Go to the top of this document

   Appendix A: System Reference Library for LISTSERV® version 1.8c
   Appendix B: List Keyword Alphabetical Reference for LISTSERV® Version 1.8c
   Appendix C: Site Configuration Keyword Reference
   Appendix D: LISTSERV "Commands-Job" Feature and CJLI Interpreter
   Appendix E: LISTSERV Database Functions
   Appendix F: Sample Boilerplate Files
   Appendix G: Related Documentation and Support
   Appendix H: Acknowledgements
   

   ---