The Best of Windows 95.com 1996 September/WIN95_09961.iso/mailsrv/LSV95.ZIP/win95.z/listownr.memo

Text File | 1995-05-24 | 176KB | 3,439 lines

             LISTSERV(TM) list owner's manual, release 1.8b
             ----------------------------------------------
                Copyright 1995 L-Soft international, Inc.

                       Last update: May 24th, 1995

Note: this  document is  a plain  text version  of LISTSERV  list owner's
manual,  without the  appendices. Appendix  A is  the LISTSERV  reference
card, available via INFO REFCARD.  Appendix B (list keyword reference) is
also available separately via the  INFO KEYWORDS command. The full manual
is available  via anonymous FTP  from FTP.LSOFT.COM, CD  DOCUMENTS. Minor
typographical errors are possible in  this plain text version, especially
where spacing is concerned.

                         ******************************
                         *    List Owner's Manual     *
                         *            for             *
                         * LISTSERV(tm), version 1.8b *
                         ******************************
                                  May 23, 1995

               The reference number of this document is 9505-UD-02

================================================================================
Information in this document is subject to change without notice.  Companies,
names and data used in examples herein are fictitious unless otherwise noted. L-
Soft international, Inc. does not endorse or approve the use of any of the
product names or trademarks appearing in this document.

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

Copyright (c) 1995, L-Soft international, Inc.
All Rights Reserved Worldwide.

L-SOFT, LISTSERV and LMail are trademarks of L-Soft international, Inc.
UNIX is a registered trademark of UNIX Systems Laboratories.
AIX and IBM are registered trademarks of International Business Machines
Corporation.
Alpha AXP, Ultrix and VMS are trademarks of Digital Equipment Corporation.
OSF/1 is a registered trademark of Open Software Foundation, Inc.
Microsoft is a registered trademark and Windows, Windows NT and Windows 95 are
trademarks of Microsoft
Corporation.
HP is a registered trademark of Hewlett-Packard Company.
Sun is a registered trademark of Sun Microsystems, Inc.
IRIX is a trademark of Silicon Graphics, Inc.
PMDF is a registered trademark of Innosoft International.
All other trademarks, both marked and not marked, are the property of their
respective owners.

================================================================================

*********************
* Table of Contents *
*********************

Preface: LISTSERV Command Syntax Conventions

1.     About Mailing Lists and LISTSERV(tm)

2.     Starting a Mailing List - The Basics
    2.1.    Avoid duplication of effort
    2.2.    What skills do I need to start and maintain a LISTSERV mailing list?
    2.3.    Creating a mailing list - Where can it be done, and Who can do it?
    2.4.    List Header Keywords and what they do
        2.4.1.    Access Control Keywords
        2.4.2.    Distribution Keywords
        2.4.3.    Error Handling Keywords
        2.4.4.    List Maintenance and Moderation Keywords
        2.4.5.    Security Keywords
        2.4.6.    Subscription Keywords
        2.4.7.    Other Keywords
    2.5.    Retrieving and editing the list  -  some considerations
    2.6.    Storing the list on the host machine
    2.7.    Fixing mistakes
    2.8.    A sample list header file

3.     Advertising Your Public Mailing Lists
    3.1.    List of Lists
    3.2.    The INFO <listname> command and how to implement it
    3.3.    The NEW-LIST project at North Dakota State
    3.4.    The Internet Network Information Center (INTERNIC)
    3.5.    The Global List Exchange (GLX) and why you should mention it
    3.6.    How NOT to advertise a mailing list

4.     Managing Subscriptions
    4.1.    How to add and delete subscribers to/from a list
    4.2.    Finding users who do not appear in the list
    4.3.    Converting mailing lists  to LISTSERV from other systems
    4.4.    Using the QUIET option with commands
    4.5.    Dealing with bounced mail
        4.5.1.    What is a bounce, and what can typically cause one?
        4.5.2.    What to do about several types of bounces
        4.5.3.    Redistribution lists and why they may cause you migraines
    4.6.    Automatic and semi-automatic deletion
    4.7.    Subscription confirmation
    4.8.    Subscription renewal
    4.9.    The SERVE command
    4.10.   "Peering" Large Lists

5.     Setting Subscription Options For Subscribers
    5.1.    How to review current subscription options with QUERY
    5.2.    How to set personal subscription options for subscribers
    5.3.    Options that may be set
        5.3.1.    Mail/NOMail
        5.3.2.    DIGest
        5.3.3.    INDex
        5.3.4.    ACK/NOACK/MSGack/NONE
        5.3.5.    Options for mail headers of incoming postings
        5.3.6.    CONCEAL/NOCONCEAL
        5.3.7.    REPro/NOREPro
        5.3.8.    TOPICS
        5.3.9.    POST/NOPOST
        5.3.10.   EDITOR/NOEDITOR
        5.3.11.   REVIEW/NOREVIEW
        5.3.12.   RENEW/NORENEW
    5.4.    Setting original default options with the Default-Options= keyword

6.     Moderating and Editing Lists
    6.1.    List charters, welcome files, and administrative updates
    6.2.    The role of the list owner as moderator
    6.3.    The role of the list owner as editor
    6.4.    Setting up an edited list
    6.5.    Submitting subscriber contributions to an edited list
    6.6.    Message approval with Send= Editor,Hold
    6.7.    Using list topics
    6.8.    The listname WELCOME and listname FAREWELL files
        6.8.1.    Creating and storing listname WELCOME and FAREWELL files
        6.8.2.    Using the listname WELCOME file as a moderation tool
        6.8.3.    Using the listname FAREWELL file as a feedback tool
        6.8.4.    The alternative to using WELCOME and FAREWELL files
    6.9.    Social conventions (netiquette)
    6.10.   Spamming: what it is, and what to do about it
    6.11.   Appropriate use policies: considerations

7.     Overview of List Archives
    7.1.    What is the list archive?
    7.2.    Setting up and managing archive notebooks
    7.3.    Database Functions Overview
    7.4.    Where to find more information on Database Functions

8.     Overview of File Archives
    8.1.    What is the file archive?
    8.2.    Starting a filelist
    8.3.    Filelist maintenance
    8.4.    Giving other users access to files
    8.5.    Storing files on the host machine
    8.6.    Automatic File Distribution (AFD) and File Update Information (FUI)
    8.7.    "File Packages"
    8.8.    Where to find more information on File Archives

9.     Customizing LISTSERV's Default Mail Templates
    9.1.    What LISTSERV uses mail templates for
    9.2.    The DEFAULT.MAILTPL file and how to get a copy
    9.3.    Mail template format and embedded formatting commands
    9.4.    Creating a <listname>.MAILTPL file for a list
    9.5.    Storing the <listname>.MAILTPL file on the host machine

10.     Gatewaying to USENET
    10.1.   Why would I want to?
    10.2.   How to go about it
    10.3.   Special considerations and problems with gatewaying

11.     Solving Problems
    11.1.   Helping subscribers figure out the answers
    11.2.   Loop-checking can cause occasional problems with quoted replies
    11.3.   Broken and/or unhelpful mail servers
    11.4.   Broken and/or one-way gateways
    11.5.   Firewalls
    11.6.   If I can't find the answer, where do I turn?
    11.7.   LSTOWN-L@SEARN and LSTSRV-L@UGA  -  two other places to get
            help

Appendix A:     System Reference Library for LISTSERV* version 1.8b

Appendix B:     List Keyword Alphabetical Reference for LISTSERV(tm)
                version 1.8b

Appendix C:     Sample Boilerplate Files

Appendix D:     Related Documentation and Support

Appendix E:     Acknowledgments

************************************************
* Preface: LISTSERV Command Syntax Conventions *
************************************************

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

A-Z 0-9 $#@+-_:

Deviations from this include:

fformat    Netdata, Card, Disk, Punch, LPunch, UUencode,
           XXencode, VMSdump, MIME/text, MIME/Appl, Mail

full_name  first_name [middle_initial] surname (not your e-mail address)

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.

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:

< >    Angle brackets always indicate required parameter names that must be
       replaced by appropriate data when sending commands to LISTSERV

[ ]    Square brackets enclose optional parameters which, if used, must be
       replaced by appropriate data when sending commands to LISTSERV

****************************************
* 1.  About Mailing Lists and LISTSERV *
****************************************

LISTSERV is a system that allows you to create, manage and control electronic
"mailing lists" on a corporate network or on the Internet. Since its inception
in 1986 for IBM mainframes on the BITNET academic network, LISTSERV has been
continually improved and expanded to become the predominant system in use today.
LISTSERV is now available for VM, VMS(tm), unix(r) and  Windows NT(tm), and has
already been ported to Windows 95(tm) (formerly Windows 4.0).

Consider for a moment what the users of your electronic mail system actually use
electronic mail for. Do they discuss problems and issues that face your
organization, down to the departmental level? In an academic setting, do your
faculty and students communicate via electronic mail? As with "real world"
distribution lists, electronic mailing lists can make it possible for people to
confer in a painless manner via the written word. The electronic mail software
simply replaces the copying machine, with its associated costs, delays and
frustrations. In fact, electronic mail lists are easier to use than most modern
copiers, and a lot less likely to jam at just the worst possible moment.

Because electronic mail is delivered in a matter of seconds, or occasionally
minutes, electronic mailing lists can do a lot more than supplement the
traditional paper distribution lists. In some cases, an electronic mailing list
can replace a conference call. Even when a conference call is more suitable, the
electronic mailing list can prove a powerful tool for the distribution of
papers, figures and other material needed in preparation for the conference
call. And, when the call is over, it can be used to distribute a summary of the
discussion and the decisions that were made. What before might have been an
exchange of views between two or three people can now become an ongoing
conference on the issue or problem at hand. Announcement lists and even refereed
electronic journals can be made available to your audience, which can be as
small as a few people or as large as the entire Internet community.

If you need a further overview, please see Appendix D, Related Documents and
Support, for information on how to get one.


********************************************
* 2.  Starting a Mailing List - The Basics *
********************************************

2.1. Avoid duplication of effort
================================

Before you start your list, it pays to do a careful search in several places to
find out if you are duplicating an already-existing list, or if the name you are
considering is already in use for a list on a differing subject.

The first place to check is the "List of Lists" maintained by LISTSERV itself.
Send the command

    LIST GLOBAL <search_string>

in the body of mail to [e-mail] (or to LISTSERV at any host site).
You will receive a mail message in return containing a list of all lists known
to LISTSERV
where either the name of the list or the short list description contains your
search string.
For instance, LIST GLOBAL IBM would result in the following being returned to
you:

--------------------------------------------------------------------------------
Excerpt from the LISTSERV lists known to [e-mail] on 6 Feb
1995 09:57
Search string: IBM

***********************************************************************
* To subscribe, send mail to [e-mail] with the following *
* command in the text (not the subject) of your message:              *
*                                                                     *
*                         SUBSCRIBE listname                          *
*                                                                     *
* Replace 'listname' with the name in the first column of the table.  *
***********************************************************************

Network-wide ID  Full address and list description
---------------  ---------------------------------
9370-L           [e-mail]
                 IBM 9370 and VM/IS specific topics list

AIBIBL           [e-mail]
                 ACADEMIC INITIATIVE IBM , PROJECT "LIBRARY SYSTEMS" AIBIBL

AIX-L            [e-mail]
                 IBM AIX Discussion List

AIXNEWS          [e-mail]
                 IBM AIX News to Mail Distribution
--------------------------------------------------------------------------------
 Figure 2.1.    Sample output of LIST GLOBAL IBM

(63 more lists were deleted for brevity)

You might want to make your search more specific, as this particular search
locates every list that has IBM somewhere in its title.  For instance, if you
wanted to start a list on some aspect of the IBM 370, you might do better to
search for IBM 370.

Alternative searches you can do include:

*  Check the archive on NDSUVM1 (or VM1.NODAK.EDU), where the NEW-LIST project
   at North Dakota State University has been storing list announcements for
   several years.  The NEW-LIST archive contains information about LISTSERV
   lists as well as about lists running on other types of servers.  This
   information is accessible either via LISTSERV database searches or by Gopher
   to vm1.nodak.edu.

*  Use a Gopher or World-Wide Web (WWW) client to access the InterNIC database
   services, where a list of lists is maintained.  The InterNIC Gopher is
   located at rs.internic.net.

*  Get a copy of the Interest Groups List of Lists maintained by SRI on its
   server at sri.com.  Note that this is a 500KB (or larger) file.

    ftp sri.com
    user:  anonymous
    password:  <your_user_id>
    cd netinfo
    get interest-groups

*  Get a copy of the Interest Groups list maintained by David Avery at Dartmouth
   College.  This is a merged list of the LISTSERV list of lists and the
   Internet Groups list, with one-line entries for each group.  Again, this is a
   large file, so be sure you have room for it.  Also available on the dartcms1
   server is a Macintosh Hypercard application that formats this file nicely
   (assuming you have a Macintosh).  You may want to do a dir of the files
   available in the siglists directory to see if there is anything else there
   that might be useful.

    ftp dartcms1.dartmouth.edu
    user:  anonymous
    password:  (not required by dartcms1)
    cd siglists
    get internet.lists

   Note that all these files (except the large data stack) can also be retrieved
   from [e-mail].

*  Check the Usenet newsgroups news.announce.newusers and news.lists , if they
   are available to you via your local news feed.

2.2. What skills do I need to start and maintain a LISTSERV mailing list?
=========================================================================

You should already be familiar with your mailing system and text editor.
Otherwise, there are no special skills required.  It is the goal of this manual
to give you what you need to know about LISTSERV user commands, privileged
LISTSERV owner commands, and how to read and interpret RFC822 Internet-style
mail headers.  LISTSERV itself is designed to operate in an identical manner no
matter which operating system it is running under.  Thus the fact that LISTSERV
is running under VM, VMS, some flavor of Unix, or Windows NT should not be a
concern to the list owner, who may not even know which version of LISTSERV his
lists are running on.

Additionally, we have made an attempt to give you a basic "list owner's course"
in anticipation of some of the issues you may encounter in the course of
moderating a list.

2.3. Creating a mailing list - Where can it be done, and Who can do it?
=======================================================================

If you are looking for a site to host a list, you might consider the following:

*  First, find out if your computing center maintains a LISTSERV host.

*  If not, write a short description of your proposed list, including the
   proposed name, general topic, target audience, estimated number of
   subscribers and estimated number of messages to be processed daily.  Send
   this proposal, with a subject line of "Searching for a host site" (or
   something similar) to LSTSRV-L @UGA.CC.UGA.EDU.

*  If the first two options do not bear fruit, you might consider a commercial
   LISTSERV site. There are a number of such sites, including L-Soft's own
   EASE(sm) service. Send the description and a request for further information
   to [e-mail].

Please note also that many sites (predominantly, but not necessarily limited to,
those in .EDU domains) will not host commercial or potentially-controversial
lists because of internal policies regarding appropriate use of their computing
facilities. In such a case, your only option may be to seek a commercial
LISTSERV site.

Physically creating the list is the task of the LISTSERV maintainer (sometimes
referred to as the "LISTSERV postmaster") at a given LISTSERV host site.
Specific procedures for requesting a list startup vary from institution to
institution.  It is usually best to contact the computing center at the site for
more information.

2.4. List Header Keywords and what they do
==========================================

How a LISTSERV mailing list performs its tasks is defined by its header
keywords.  There are several different categories of keywords, each of which is
discussed below in general terms.  A complete alphabetical listing of list
header keywords, including default settings and all options available, is
provided in Appendix B.

Access Control Keywords
-----------------------
  These keywords designate the level of "openness" for a list.  They determine
  who can post to the list, who can review the list of subscribers, and whether
  or not the list is open to general subscription.

Distribution Keywords
---------------------
  This group has to do with how LISTSERV distributes postings to subscribers,
  including whether or not acknowledgments are sent back to posters, how many
  postings may go through the list daily, whether or not the list is available
  in digest form and whether it is available to USENET through a gateway.  These
  keywords also determine whether or not list topics are enabled, and how
  LISTSERV will configure outgoing postings for replies.

Error Handling Keywords
-----------------------
  Included under this group are the keywords controlling automatic deletion,
  loop-checking, and to whom error messages are sent for disposition when
  received by LISTSERV.

List Maintenance and Moderation Keywords
----------------------------------------
  A fairly large group of keywords having to do with how the list is operated,
  including definitions for the list owner, list editor, and the list archive
  notebook; whether or not (and 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.

2.5. Retrieving and editing the list - some considerations
==========================================================

Once your list has been created by the LISTSERV maintainer, you can have a copy
of the list sent to you for editing purposes.  Simply issue the GET listname
command to LISTSERV.  This will cause the server to mail you a copy of the
entire list (header and subscriber list).

If you want to change header keyword settings only, it is probably advisable to
issue the GET command with the (header switch:

    GET <listname> (header

The GET command automatically locks the list so that no changes can be made to
the operating copy on the server until you do one of two things:

*  Issue the UNLOCK listname command (if you decide no changes are needed)

*  Send the list back to the server with the PUT command.

Leaving the list locked also prevents new subscribers from signing up.  It is
therefore not advisable to leave the list locked for long periods of time.  This
necessitates remembering to issue the UNLOCK command if you decide not to make
any changes.

It is possible to request that LISTSERV not lock the list when it is sent to
you.  This is accomplished by adding the (nolock switch to the GET command.  You
can use (nolock and (header together as in the following example:

    GET <listname> (header nolock

(Note that the "(" switch character is used only once.)

CAUTION:  It is not advisable to use the (nolock switch in at least two cases:

*  Don't use the (nolock switch if you are not the sole owner of the list.  This
   prevents conflicting GETs and PUTs by different list owners.  For instance,
   Owner(A) GETs the list without locking it.  Owner(B) then also GETs the list.
   The owners make differing changes to the list header.  Owner(B) PUTs his
   changes back first.  Owner(A) then PUTs his changes back, erasing every
   change Owner(B) made.  If Owner(A) had not used the (nolock switch, Owner(B)
   would not have been able to GET a copy of the list until Owner(A) either
   unlocked the list or PUT his copy back.  (Owner(B) could also unlock the list
   himself, but it would be advisable to ask Owner(A) if he was finished editing
   the list header before doing so.)

*  Don't use the (nolock switch if you get the entire list rather than just the
   header.  You will erase all subscriptions for users who subscribed between
   the time you GET the list and PUT the list back.  It is easier to deal with
   questions as to why they got the "listname has been locked since time by
   list-owner" message than to explain why they got a subscription confirmation
   and now aren't getting list mail.

Another caution: 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:

    DELETE XYZ-L "/ADMD=ABC/PRMD=DEF/...../@X400.SOMEHOST.COM".

2.6. Adding a list password
===========================

When creating the list, the LISTSERV maintainer should assign a password for the
list. You can change this password when you store the list (with the "PW="
keyword), but the first time you store the list, you must use the original
password if it has been assigned. Note that not all LISTSERV maintainers do this
by default; if you are not given a password to use with your list, it is highly
recommended that you assign it one yourself by adding a "PW=" header line as
follows:

    * PW=MYPASSWD

Replace "MYPASSWD" with the word you choose. Note that there should not be a
space between "PW=" and your 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.

2.7. Storing the list on the host machine
=========================================

When you are ready to store your list back on the host, include the list file in
a mail message to LISTSERV.  Ensure that the PW=XXXXXXXX command is in the first
line of the mail body.  Change XXXXXXXX to the password you have previously
defined with the PW= list header keyword.  Then send the message.

If LISTSERV has trouble processing the edited list file, it will return a
discrepancy report to you with each error noted.  If the errors are categorized
as "warnings only," LISTSERV will go ahead and store the list.  However, if any
one error is categorized as a serious error, the list will not be stored and the
old version will be retained.

Caution: If you are using a mailer such as Pine or Microsoft Mail that allows
"attachments" to mail, do not "attach" the list file to your mail message.  It
must be in plain text with the PUT line at the top.  LISTSERV will not translate
encoded attachments.

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

2.9. A sample list header file
==============================

Once the LISTSERV maintainer has notified you that the basic list has been
created, you can send a GET command to the server to make any modifications
necessary. For instance,

    GET MYLIST PW=MYPASSWD (HEADER

might cause LISTSERV to send you the following list header file:

--------------------------------------------------------------------------------
PUT MYLIST.LIST PW=XXXXXXXX
* The Descriptive Title of My List
*
* Owner= [e-mail] (Nathan Brindle)
* Notebook= Yes,A,Monthly,Public
* Errors-To= Owner
* 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
*
* This list installed on 95/02/02, running under L-Soft's LISTSERV-TCP/IP
* version 1.8b for Windows NT.
*
* Comment lines...
*
--------------------------------------------------------------------------------
Figure 2.2.    A sample list header file for a list called MYLIST.

Below, we've now edited the list header and it is ready to be included in a mail
message and sent back to LISTSERV. Note that the PUT command has been modified
to include 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= [e-mail] (Nathan Brindle)
* Owner= Quiet:
* Owner= [e-mail]
* Owner= [e-mail]
* Notebook= Yes,A,Monthly,Public
* AutoDelete= Yes,Full-Auto
* Errors-To= [e-mail]
* 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 95/02/02, running under L-Soft's LISTSERV-TCP/IP
* version 1.8b for Windows NT.
*
* Comment lines...
*
--------------------------------------------------------------------------------
Figure 2.3.    The edited list header file ready to be sent back to the server.

*********************************************
* 3.  Advertising Your Public Mailing Lists *
*********************************************

3.1. List of Lists
==================

LISTSERV automatically produces a List of Lists that may be reviewed by users
anywhere on the Internet via the LIST GLOBAL command.  This List of Lists is
made up of one-line entries containing the short listname and the descriptive
title of the list (up to about 60 characters in length).  A sample of the List
of Lists format was shown in Chapter 2.

Note that it is possible to code a descriptive title in your list header that is
more than 40 columns long, but the List of Lists will include only the first 40
columns of that title. It is therefore important from this respect to be sure
that the descriptive title of your list is succinct and to the point.

3.2. The INFO <listname> command and how to implement it
========================================================

Chapter 9, Customizing LISTSERV's Default Mail Templates, includes details on
how to include an informative paragraph in the information mail template file
for your list.  When a user sends the command INFO listname to your server,
LISTSERV responds with either:

*  The default response, which simply sends a copy of the list header to the
   user; or

*  The customized paragraph included in the <listname>.MAILTPL file.

If <listname>.MAILTPL does not exist, the default response is sent.  Also note
that the user may send the INFO <listname> command to any L-Soft LISTSERV host
(including the Global List Exchange discussed below), which will forward the
request to the appropriate server.

3.3. The NEW-LIST project at North Dakota State
===============================================

The NEW-LIST project was started in 1989 to promote mailing lists via a mailing
list.  [e-mail] distributes announcements of new and changed
mailing lists to over 9500 subscribers every day.  The NEW-LIST administration
asks only that your list be well-tested and ready for new subscriptions before
you send your announcement to them.  You also want to make sure that your
announcement is as correct and comprehensive as possible, as news on the
Internet spreads quickly and a mistake in a NEW-LIST announcement may cause
problems for both you and other users months later.

For more information on the NEW-LIST project and what you need to use it, you
can:

*  Gopher to vm1.nodak.edu and choose "Local LISTSERV Resources", then "NEW-LIST
   Project"; or

*  Send the command GET NEW-LIST PACKAGE to [e-mail].

(The NEW-LIST Project also published a hard-copy version of their archive in
1992 with a newer edition in 1993 under the title Internet: Mailing Lists [ISBN
0-133-27941-3], edited by Edward T. L. Hardie and Vivian Neou.)

3.4. The Internet Network Information Center (INTERNIC)
=======================================================

Unlike many other lookup services on the Internet, the INTERNIC is not
necessarily free.  Its three distinct sections are run by General Atomics,
Network Solutions, Inc. (NSI), and AT&T.

You can register your list with the INTERNIC, but be forewarned.  A "basic"
listing is free, while an "extended" listing is not.  (On the other hand, anyone
with net access can search the INTERNIC databases for free.)

For more information, point a Gopher or WWW client at the INTERNIC gopher,
rs.internic.net.

3.5. The Global List Exchange (GLX) and why you should mention it
=================================================================

The Global List Exchange, or GLX, is a central clearinghouse for LISTSERV
subscriptions and List of List requests.  For instance, If a user knows the name
of a list but not the name of the host server, GLX simplifies the process by
giving the user a single address where all subscription requests for lists
running on L-Soft's LISTSERV can be sent.

By adding the GLX address in all advertisements for your list, you help other
list owners as well as yourself by making it simple for users to subscribe to
any list.  Additionally, if for some reason a user is unable to contact your
server directly, the GLX gives him an alternate subscription method.

The GLX address is [e-mail].

3.6. How NOT to advertise a mailing list
========================================

It is generally considered a breach of netiquette to invade the privacy of other
lists with a broadcast announcement that your list is up and running.  The only
time when this might be acceptable is when your list addresses a concern of
people already subscribed to another list.  If you feel it necessary to post an
announcement on someone else's list, it is good manners to first send private
mail to the owner of that list and ask his or her permission to do so.  (The
same policy applies to USENET newsgroups, though it may be more difficult to
find out who the moderator is.)

It is certainly a breach of netiquette (and many networks' appropriate use
policies) to blindly post multiple copies of your announcements to multiple
lists.  This kind of behavior is termed a "spam", something about which you may
read more in Chapter 6, Moderating and Editing Lists.  This kind of announcement
is guaranteed to reap a good deal of bad will and may well result in the
revocation of your network privileges.

******************************
* 4.  Managing Subscriptions *
******************************

4.1. How to add and delete subscribers to/from a list
=====================================================

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

    ADD <listname> <netaddress> <full_name>
    DELete <listname> <netaddress>

In a perfect world, subscribers would understand intuitively how to subscribe
and unsubscribe from mailing lists.  Unfortunately, this is not always the case.
Depending on an individual's style of list management, a list owner may choose
to add or delete subscribers to the list manually, or send the potential
subscriber instructions on how it is done. (See Appendix C for sample
"boilerplate" instruction files that can be modified to suit local purposes.)
And for lists coded Subscription= By Owner or Subscription= Closed, it is of
course necessary to use the ADD command to subscribe a user.

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

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

    RIGHT:      ADD GOV-L [e-mail] Al Gore
    RIGHT:      ADD GOV-L [e-mail] *
    WRONG:      ADD GOV-L [e-mail] Al
    WRONG:      ADD GOV-L [e-mail] Al-Gore

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

    From:  Al Gore <[e-mail]>

becomes an ADD command as follows:

    ADD GOV-L Al Gore <[e-mail]>

4.2. Finding users who do not appear in the list
================================================

Sometimes the list owner will get a message from a subscriber who says, in
essence, "I keep trying to (unsubscribe/change to digest/etc.) and LISTSERV says
I'm not subscribed.  Can you help?"  This requires some detective work.

There are a couple of strategies for figuring out what is wrong. List owners
should first use the powerful SCAN command to search for a pattern anywhere in
the subscriber list. The syntax is:

    SCAN <listname> <search-text>

For instance, "SCAN TEST-L Nathan" might return:

    > scan test-l Nathan
    Nathan Brindle <[e-mail]>
    Somebody Else <[e-mail]>
    Jonathan Smith <[e-mail]>
    SCAN: 3 matches.

Note that SCAN is not case-sensitive.  "Nathan", "NATHAN", and "nathan" all
return the same results.

Searches with SCAN should start out simple and become more complex as needed.
For instance, if there are only three people in the list with the string
"NATHAN" as part of their subscription record, it will be unlikely that you will
need to make the search any more complex. If you are looking for "SMITH",
however, it may be necessary to further qualify your search string, say to look
for "JOE SMITH". Another reason it is important to begin with a simple search
string is that your user may not be subscribed under the exact address the error
is returning to you. For instance, say you don't have the user's id, but you
have a host name. You can search for all occurrences of the host name, but note
that the search:

    SCAN TEST-L MAIL.FOO.BAR.COM

will not find the user [e-mail]. If you run the following search:

    SCAN TEST-L BAR.COM

however, you will find Mr. Smith's subscription.

Another possibility is that the subscriber may be using more than one address to
work with his subscription. For instance, say the user's complaint to you came
from [e-mail]. Looking at the list, you find a subscription for
[e-mail]. LISTSERV has no way to know that JOE@SUN6 is the same
person as JOE@SUN8, even though Joe and you know they are.  The solution to
Joe's problem above is for you to delete his SUN8 subscription and add his SUN6
address.  Then Joe needs to be sure that he uses SUN6 in the future, if not for
reading mail, then at least for managing his own subscription.

Another strategy would be to submit a wildcard QUERY to the list.  The drawback
to this method is that it might require multiple tries to find the subscription,
depending on the complexity of the wildcard query.

Note also that not only can this sort of problem arise from a subscriber using
more than one workstation to read mail, but it can also arise when a particular
site changes its domain configuration, forwards mail from the old addressing
scheme to the new addressing scheme, and doesn't inform its users of the change.
In these cases, users often don't realize there is a problem until they try to
unsubscribe or change personal options, because the change has been transparent
to them.

4.3. Converting mailing lists to LISTSERV from other systems
============================================================

If you are moving a list from a non-LISTSERV site, you can quickly and easily
convert the existing list file to the LISTSERV format by following these
instructions:

1.  Have the LISTSERV maintainer at your new site create the new list header and
    install it on the machine.

2.  Create an add job as follows:

    QUIET ADD listname DD=X IMPORT
    //X DD *
    <user1> <full_name>
    <user2> <full_name>
    /*

    where "listname" is the name of the new list, and "user1", "user2" and other
    users are the entries from the original list that you want to add to the new
    list. (You should remove any lines from the original list that do not
    actually identify subscriber addresses.)

3.  Send the job to LISTSERV.

The IMPORT option speeds up the operation of adding many subscribers "in bulk"
at one time by causing LISTSERV to omit success messages and to relax syntax
checking.

4.4. Using the QUIET option with commands
=========================================

Prepending the command word "QUIET" before any LISTSERV command that you issue
on behalf of a subscriber causes LISTSERV to suppress any notification to the
subscriber of the changes you have made. This is particularly helpful when
deleting subscribers whose accounts have expired and when setting subscribers
with full mailboxes to NOMAIL, as it will help avoid another error message from
the host when the notification message bounces. It is also helpful when adding
subscriptions to the list that should not receive any welcome mail, such as
redistribution lists and USENET newsgroups.

Examples of the usage of QUIET include:

    QUIET ADD EXCEL-L [e-mail]

    QUIET DELETE EXCEL-L [e-mail]

4.5. Dealing with bounced mail
==============================

4.5.1. What is a bounce, and what can typically cause one?
----------------------------------------------------------

A bounce is simply an undeliverable e-mail message.  The term "bounce" is used
to describe it because normally the system that discovers the delivery error
"bounces" a copy of the message back to you with some sort of delivery error
message.  Sometimes these messages are easy to decipher - "No such user at
foo.bar.com" - but uncomfortably often they are not that easy.  Certain systems,
as noted above, kindly format error notifications in a format that LISTSERV can
understand, and if your list is configured for auto-deletion, these bounces will
be the least of your worries - in fact, they will not be worrisome at all.

4.5.2. What to do about several types of bounces
------------------------------------------------

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

1.  no such user at host
    Most of the time, this is authoritative and indicates that the user's access
    has been curtailed for some reason (graduation, no longer employed, etc.).
    A quiet delete (syntax: "QUIET DELETE <listname> <userid@host>") is in order
    unless you have reason to believe that the message is not authoritative.

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

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

3.  no MX or A records for host
    Similar to "no such host".  Comes from a different lookup system, and
    generally means the same thing.

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

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

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

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

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

A particularly annoying error you may have to deal with comes from Banyan
networks and is of the form:

    LLONG@StarShip@Dora:  Mailbox full

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

    > scan test-l LLONG
    Bill Smith <[e-mail]>
    SCAN: 1 match.

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

Note that there are many forms of error messages.  Many mail systems do not
conform to Internet "standards" (some of them even return non-English error
messages!) and LISTSERV's auto-deletion feature will not always catch their
bounces.

4.5.3. Redistribution and forwarding
------------------------------------

Perhaps the worst type of bounce is one that comes from a user who is "hiding"
behind an account that redistributes mail (a "redistribution list"), or a user
whose Internet address has changed slightly but who is still subscribed to your
list under his original address.

Redistribution lists typically (but not always) take some form of your list's
name (such as "[e-mail]"), and thus their subscriptions tend
to be easy to find.  What is difficult is that you have no way of knowing which
users (or how many users) are hidden behind this interface, nor any way of
knowing what their userids are.

Forwarded accounts generally fall into one of two categories - those where the
user has forwarded his own mail from one account to another rather than changing
his subscription, and those where the user's system name has changed and the old
address is still valid but is forwarding mail to the new address without the
user being aware of it.

Let's say that suddenly you are bombarded with delivery errors for
[e-mail].  Your immediate reaction is to set this person to NOMAIL or
(in some cases) to delete him/her altogether.  You therefore send set xxxxx-L
nomail for [e-mail] to LISTSERV.  LISTSERV responds:  "No subscription
for [e-mail] in list XXXXX-L."

In a best-case scenario, you can query the list for *@*.baz.net and find either
a user like [e-mail] (the address has changed and the local
sysadmins didn't inform the user) or a redistribution-list account like xxxxx-
[e-mail].  These are easily-fixed redistribution bounces.  In the first case,
you delete the user and let him or her resubscribe.  In the second case, you can
try sending a message to [e-mail] with a cc: to [e-mail]
and inform them of the problem.  If it persists, you could send a further
message informing them that you are suspending the redistribution list's
subscription until such time as they tell you the problem on their end is fixed,
and simply set [e-mail] to NOMAIL.

The worst-case scenario is as follows:  baz.net may be bouncing the mail to you,
but there may not be a single subscription for baz.net in your list.  Here's
where you have to do some careful sleuthing.  First, run a wildcard query such
as QUERY xxxxx-l FOR *@*baz* or QUERY xxxxx-l FOR *baz*@*.  The former will find
users at baz.com, for instance, where baz.net is a synonym for baz.com.  The
latter query may seem somewhat strange, but it's possible that the mail is being
routed through a gateway and the actual subscription is for xxxxx-
[e-mail] or something of that sort.

4.6. Automatic and semi-automatic deletion
==========================================

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

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

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

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

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

4.6.1. Auto-Delete considerations for holidays
----------------------------------------------

Making a big increase to the DELAY threshold to provide more leniency during a
holiday may not be a good idea. While it will indeed disable the monitor for the
duration of the holiday, switching back to the normal threshold when you return
will cause the monitor to delete all the users that had been bouncing during the
holidays. In general, you should avoid making temporary changes to the DELAY
threshold, because it takes the monitor a while to adapt to the new settings.

The best way to relax the rules during a long holiday is to leave the DELAY
threshold unchanged but switch the monitor to passive mode ("Auto-Delete=
Yes,Manual"). Noone will be deleted over the holidays, but the monitor's cycle
will not be perturbed. When you return, you should wait about a week before
switching back to automatic mode. This is because, after a long holiday such as
Christmas, it usually takes about 2 working days for system administrators to
solve all problems. In some cases, the problems will have caused bounces to
remain undelivered. So, by fixing the problems, the system administrators may
actually send a flood of new bounces corresponding to problems that have now
been solved. Unfortunately, since the monitor only receives NON-delivery
reports, it has no way to know that these problems have in fact been solved. As
a rule of thumb, you will note that your daily delivery error reports are much
longer than usual over the vacation. When you return, you should wait until they
are back to their normal size before switching back to automatic mode.

4.7. Subscription confirmation
==============================

For lists coded "Subscription= Open", you can require confirmation on all new
subscription requests, thus ensuring that LISTSERV has a clear mailing path back
to the subscriber. In the past, a user could send a subscription for an open
subscription list to LISTSERV, which upon acceptance would immediately start
sending the user list mail. If the user was located behind a "broken" or one-way
gateway, this produced immediate bounced mail until the list owner noticed and
deleted the subscription. Note that requiring confirmation at the time of
subscription does not guarantee that the clear mailing path will continue to
exist permanently.

"Subscription= Open,Confirm" causes LISTSERV to send a Command Confirmation
Request to the potential subscriber before actually adding the user to the list.
The subscriber is requested to reply to the request by sending a validation
"cookie" back to LISTSERV (this "cookie" being the hexidecimal number pulled
from the subject line).

The Command Confirmation Request, while straightforward, has the potential to
cause confusion if users do not read carefully the instructions that make up the
request.  LISTSERV expects confirmation codes to be sent in a specific way
because some mail gateways add lines to the header of the message that LISTSERV
doesn't understand.  If a user forwards the request back to LISTSERV, or creates
a new mail message to send the 'cookie' back, it usually will not work
correctly.  The sequence should thus be as follows:

1.  SEND the subscription request to LISTSERV.
2.  REPLY to the confirmation request ('ok')
3.  SEND the confirmation code (if necessary) ('ok 23CBD8', for example)
4.  Send mail to the list owner (not 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.

4.8. 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, you add the following keyword to the header of your
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.

You can also issue the CONFIRM command for a subscriber:

    [QUIET] CONFIRM <listname> FOR <net-address>

4.9. The SERVE command
======================

If a user sends more than 21 consecutive invalid commands to LISTSERV, LISTSERV
automatically serves that user off so that further commands from that user will
be ignored.  Should a user become served off in this fashion, it is possible for
the list owner or any other user to issue a SERVE net-address command to restore
that user's access.  As with all other LISTSERV commands, the SERVE command is
sent to LISTSERV.

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

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

4.10. "Peering" large 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 2 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.

You should ALWAYS contact the LISTSERV maintainer before deciding to link your
list to another LISTSERV. Although there is no problem about linking to another
L-Soft LISTSERV list, linking to a non-L-Soft mailing list manager is not
supported 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.)

4.10.1 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. (For instance, if you
       are using Notepad in Microsoft Windows, ensure that "Word Wrap" is turned
       off.) 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.

4.10.1 Special commands for peered lists only
---------------------------------------------

ADDHere <listname> <userid@host> <full_name> [PW=<list_password>]

The ADDHERE command is strictly identical to ADD, with the exception that the
placement of the user is not checked against the list of peer servers, i.e. the
specified user is added to the local list without any further verification. (By
comparison, the ADD command causes LISTSERV to check automatically to see if
there is no better-suited peer list for the specified user.)

EXPLODE <listname> [F=<fformat>] [VM only]

The EXPLODE command provides a means whereby a list can be automatically
analyzed by LISTSERV to optimize the placement of its recipients over the
various peer servers hosting the list. It requires a "Peers=" keyword to be
defined in the list header (see Appendix B). Non-BITNET userids will be exploded
according to the network address of the corresponding gateway (as per the
SERVICE NAMES file), or ignored if the gateway could not be identified. LISTSERV
will create a commands-job file containing the necessary MOVE command to
transfer all the users which were found to be (possibly) mis-allocated to the
peer server which is nearest to them. This file will then be sent to you so
that you can review it before sending it back to the server for execution.

MOVE <listname> <userid@host> <TO> <newhost> [PW=<list_password>]
  DD=<ddname> <listid@newhost> [VM only]

The MOVE command allows list owners to easily move users from one peer server to
another. It will move the complete user entry from the source server to the
destination one, including full name as it appears in the specified list and all
list distribution options. The MOVE operation will be done in such a way that no
mail can possibly be lost by the target while the MOVE operation is in progress
(duplicate mail might be received for a short duration, however). Notification
will be sent to the target user unless the QUIET option was used.

If the source and destination list names are identical, only the destination
node ('newhost') needs be specified. Otherwise, the full network address
('listid@newhost') must be specified.

The MOVE command requires both source and destination lists to have the same
password. Since each server will have to send a password to the other to
validate the (special) ADD/DELETE commands it is sending to the other, it has
potentially a way to trap the password specified by the server, thus thwarting
any attempt at inventing a protocol to allow use of this command on lists which
have a different password. Besides, no MOVE operation will be accepted on lists
which do not have a password at all, because for technical reasons it would
allow unauthorized users to easily add someone to a list (since there would be
no password validation).

The MOVE command is the proper way to effect a move operation. You should not
use any other command/set of commands unless you cannot use MOVE. THE MOVE
COMMAND SHOULD NOT BE USED TO MOVE DISTRIBUTION LISTS!!! Since a MOVE is
basically an ADD + DELETE, with the latter being done only AFTER the ADD is
completed, moving a distribution list address with the MOVE command can cause a
duplicate link to be defined for a short period of time. This could result in a
transient mailing loop, which could become permanent if the size of the looping
mailfiles is less than the size of the inter-servers "DELETE" command jobfile,
and the RSCS priority of the latter has been altered.

****************************************************
* 5.  Setting Subscription Options For Subscribers *
****************************************************

5.1. How to review current subscription options with QUERY
==========================================================

The syntax is similar to the subscriber's method of reviewing his options,
except that the list owner must specify for whom the options are being checked.

    Query <listname> FOR <userid@host>

Note that it is possible to use wildcards in the subscriber address.  For
instance,

    Q LSTOWN-L FOR J*@UBVM*

will return option listings for subscribers such as JIMJ@UBVM,
[e-mail], etc.  This can be handy if you are searching the list
for someone whose subscription address differs from the address you are given in
an error report (see the examples, above, in "Dealing with bounced mail").

Using the WITH qualifier, you can also query a list for users who have a
specific option set. For instance, you might want to know which users are set to
NOMAIL. Send the command

    Q <listname> WITH NOMAIL FOR *@*

and LISTSERV will return a list of those users. It is also possible to query a
list for multiple options:

    Q <listname> with DIGEST CONCEAL FOR *@*

will return a list of those subscribers who have set their subscription to
DIGEST and also to CONCEAL.

5.2. How to set personal subscription options for subscribers
=============================================================

Again, the syntax is similar to the subscriber's method.

    [QUIET] SET <listname> <option> FOR <userid@host>

5.3. Options that may be set
============================

5.3.1. Mail/NOMail
------------------

Setting this option to Mail indicates that the subscriber will receive mail from
the list.  NOMail is the complementary command that stops mail but leaves the
user subscribed to the list.  (NOMail is often a good compromise for users who
are leaving the office for vacation or on extended business trips, and who don't
want a full mailbox on their return.) The format of the messages received is
controlled by the DIGEST/INDEX/NODIGEST/NOINDEX options (see below).

5.3.2. DIGest/NODIGest
----------------------

Causes the subscriber to receive one posting per digest cycle (typically daily)
rather than individual messages as they are processed by LISTSERV.

In version 1.8b, the MAIL/NOMAIL option has been isolated from DIGEST/INDEX. The
MAIL/NOMAIL option controls whether messages should be delivered, and the
DIGEST/INDEX/NODIGEST/NOINDEX option controls the format in which messages
should be delivered. Thus, switching to NOMAIL and back to MAIL now preserves
the digest/index/normal delivery setting. To provide as much compatibility with
the old syntax as possible, the four options operate as follows:

  DIGEST: enable digest delivery mode (which negates INDEX), enable mail
          delivery. No change from version 1.8a.

  INDEX:  enable index delivery mode (which negates DIGEST), enable mail
          delivery. No change from version 1.8a.

  NOMAIL: disable mail delivery. No change from version 1.8a.

  MAIL:   restore mail delivery, without altering the digest/index/normal
          delivery setting (new behavior). For compatibility with 1.8a, if mail
          delivery was already active, the MAIL option negates INDEX/DIGEST.
          Thus, a user going from NOMAIL to MAIL will keep his previous delivery
          options, whereas a user going from DIGEST or INDEX to MAIL will in
          fact deactivate index/digest mode.

To revert from digest/index subscription mode to normal delivery, you can use
either the MAIL option as before, or the NODIGEST/NOINDEX option. The NODIGEST
and NOINDEX options were actually present in versions 1.7f and 1.8a, as synonyms
for the MAIL option. In other words, you can update your instructions to
indicate that the DIGEST/INDEX options are negated by the NODIGEST/NOINDEX
options, even if your server is not yet running version 1.8b.

Note that in extreme cases, subscribers using the DIGEST option may receive more
than one digest per cycle if the digest limit is reached before the end of the
cycle.

5.3.3. INDex/NOINDex [VM only]
------------------------------

Causes the subscriber to receive one posting per digest cycle containing only an
index of subject topics for all messages during that cycle. See the section on
DIGEST (above) for further information.

5.3.4. ACK/NOACK/MSGack
-----------------------

These three command words control the level of acknowledgment the subscriber
receives when posting to the list.  ACK causes LISTSERV to send a short
confirmation message to the subscriber when the post has been received and
distributed.  NOACK disables the confirmation feature for the subscriber
(although BITNET subscribers will receive a short interactive message on their
terminal).  For BITNET subscribers, MSGack provides the same information as ACK
via interactive messages.

5.3.5. Options for mail headers of incoming postings
----------------------------------------------------

By specifying one of the following command words, the subscriber can control the
amount of mail header information prepended to list mail.  The syntax is SET
<listname> <headertype>, where <headertype> is one of the following:

    FULLHdr    "Full" mail headers (default) (formerly FULLBSMTP)
    SHORTHdr   Short headers (formerly SHORTBSMTP)
    IETFhdr    Internet-style headers
    DUALhdr    Dual headers, useful with PC or Mac mail programs

Note: In version 1.8b, the obsolete FULLHDR and SHORTHDR options were renamed to
FULL822 and SHORT822, while the normal BSMTP-style header options were renamed
to FULLHDR and SHORTHDR. The FULL822/SHORT822 options are only required by a
small number of ancient BITNET mail systems.

Quite a few non-technical users are relying on non-RFC822 user interfaces for
reading their mail. Quite often these user interfaces are user-friendly, quality
implementations of a proprietary mail protocol which the users are proficient
with, but which happens not to lend itself to bidirectional mapping to RFC822.
The users may have a good reason for using this particular program, and they
complain that it is not always clear what list the postings come from, or who
posted them. Other users have very primitive mail programs which do not preserve
the original RFC822 header and may not even have a "message subject" concept.
The user knows which list the message came from, but not who posted it, making
private replies impossible.

The DUALHDR (minimum abbreviation: DUAL) is provided to help solve this problem.
Dual headers are regular short (SHORTHDR) headers followed by a second header
inside the message body. This second header shows what list the message is
coming from ('Sender:'), the name and address of the person who posted it
('Poster:'), the poster's organization, if present, and the message subject. The
date is not shown because even the most primitive mail programs appear to supply
a usable message date.

Generally, users will be well-served by the FULL header option, which is the
default.

5.3.6. CONCEAL/NOCONCEAL
------------------------

Occasionally, a subscriber may not want his presence to be known to someone else
making a casual REView of the list.  Subscribers may choose to "hide" their
subscription from the REView command by using the CONCEAL command.  Conversely,
a subscriber may choose to remove this restriction by issuing the NOCONCEAL
command.  Note that the list owner can always obtain a list of all subscribers,
both concealed and unconcealed, by issuing the GET <listname> (NOLock) command,
or by issuing a QUERY <listname> WITH CONCEAL FOR *@* command.

5.3.7. REPro/NOREPro
--------------------

This option controls whether or not the subscriber will get a copy of his or her
own posts back from the list after they are processed.  Generally, if a
subscriber's mail program is configured to file copies of the subscriber's
outgoing mail, or if the subscriber has one of the acknowledgment options
(ACK/MSGack) enabled, this option should be set to NOREPro.  If, on the other
hand, the subscriber is set to NOACK and doesn't keep a copy of outgoing mail,
this option should probably be set to REPro.

5.3.8. TOPICS
-------------

If list topics are enabled, this option allows the subscriber to specify which
topics he or she will receive. The syntax of a SET TOPICS statement is
significantly different from that of the other options.  See Chapter 6, Section
6, for more information on this syntax.

5.3.9. POST/NOPOST
------------------

This option may be set only by list owners or the LISTSERV maintainer. A
subscriber set to NOPOST may not post to the list. NOPOST gives the individual
list owner the ability to serve out abusive or obnoxious posters without having
to add such users to the list's "Filter=" setting. Subscribers set to NOPOST
will still receive list mail - they just won't be able to post mail to the list.

The list owner or LISTSERV maintainer may issue the SET <listname> POST FOR
<userid@host> command to reverse a previously-set NOPOST.

Note for peered lists: NOPOST must be set globally or a user can bypass the
setting by simply posting to another peer. Thus you must add the user manually
to the other peers and then set the user to NOMAIL as well as NOPOST on the
peers.

5.3.10. EDITOR/NOEDITOR
-----------------------

This option may be set only by list owners or the LISTSERV maintainer, and is
effective only on moderated lists. A subscriber set to EDITOR on an
edited/moderated list may post directly to the list without a moderator's
intervention.  It is virtually identical to adding the subscriber's address to
the "Editor=" keyword, but easier to manage. The only difference between the
EDITOR option and the "Editor=" keyword, other than not being visible in the
list header, is that the "Editor=" keyword also defines a (seldom used) access
level class which can then be used in keywords such as "Review=". Thus, one
could have a list with "Review= Editor", indicating that only the users listed
in the "Editor=" keyword are allowed to review the list. The EDITOR option does
not confer this privilege. Note that the EDITOR option is only meaningful on
moderated lists.

The list owner or LISTSERV maintainer may issue the SET <listname> NOEDITOR FOR
<userid@host> command to reverse a previously-set EDITOR.

5.3.11. REVIEW/NOREVIEW
-----------------------

This option may be set only by list owners or the LISTSERV maintainer. When a
subscriber is set to REVIEW, all postings from that subscriber are forwarded to
the list editor or list owner for approval. Approval for these postings is
always via the OK mechanism - there is no need to forward the posting to the
list, simply reply to the approval confirmation with "OK".

Note that if a list is unmoderated, it is still possible to direct REVIEW
postings to a specific person by adding an "Editor=" or "Moderator=" keyword to
the list header.

The list owner or LISTSERV maintainer may issue the SET <listname> NOREVIEW FOR
<userid@host> command to reverse a previously-set REVIEW.

5.3.12. RENEW/NORENEW
---------------------

This option may be set only by list owners or the LISTSERV maintainer. Enables
or disables subscription renewal confirmation on an individual subscriber basis.
Setting a subscription to NORENEW is particularly useful for exempting list
owners, redistribution lists, and other subscriptions which should not or must
not receive the confirmation request message from the renewal process.

The list owner or LISTSERV maintainer may issue the SET <listname> RENEW FOR
<userid@host> command to reverse a previously-set NORENEW.

5.4. Setting original default options with the Default-Options= keyword
=======================================================================

The list owner may specify original defaults for many subscriber options by
using the "Default-Options=" keyword.  This keyword takes regular SET options as
its parameters.  Examples include:

    * Default-Options= DIGEST,NOREPRO,NOACK

    * Default-Options= REPRO,NONE

You may have more than one "Default-Options=" line in your header, as needed.

Note that any default topics are set with the "Default-Topics=" keyword.  See
Appendix B for details on this keyword.

************************************
* 6.  Moderating and Editing Lists *
************************************

Please note that much of this chapter is subjective, based on personal
experiences during several years of list ownership, and may not necessarily
match your own philosophy of "the way things ought to be."  The following
sections are offered as one way to run a list, and the author does not mean to
assert that the one way offered - his way - is the only way.  As we seem to say
so often, "your mileage may vary."

6.1. List charters, welcome files, and administrative updates
=============================================================

One of the most important things you can do as a list owner is make it clear
from the outset what policies are in place and will be enforced if it becomes
necessary.  Due to a potential for controversy, for instance, some lists may
require a formal "list charter" by which all subscribers must agree to abide
before they are allowed to subscribe.  Other lists may be able to get by with a
simple welcome file (see below) that spells out basic netiquette, polices on
"flaming" and commercial posts, and anything else that seems appropriate (such
as how to get in touch with the list owner in an emergency, where the list
archives are located, etc.).

It is particularly important on open subscription lists that you make a
concerted effort to remind your subscribers on a regular basis of the policies
you have set for your list, as well as any other information they need in order
to make best use of your list.  If you have a great deal of subscriber turnover,
it may be necessary to do this every few weeks.  You may decide to put together
a quarterly or semi-yearly post for more stable lists.  Ensure that the subject
line is indicative of what the administrative posting is so that there is no
question as to whether or not you posted it (even if subscribers don't read it).

6.2. The role of the list owner as moderator
============================================

By default, the list owner becomes a moderator of sorts, even if the list in
question is neither edited nor officially moderated.  This means that, as a list
owner, you must be prepared to maintain order if it becomes necessary.  At the
same time, you must moderate yourself so that you do not alienate users and
cause your list and/or host institution to suffer as a result.  Thankfully,
mailing lists have generally enjoyed relative peace and quiet over the years in
comparison to newsgroups, but mailing lists have unique problems of their own.

Lists dedicated to controversial subjects are more likely to become arenas for
"flame wars" between subscribers with hard-held and differing opinions than
those dedicated to the discussion of popular software packages, but this does
not mean that the latter are immune any more than it means that the former are
constantly plagued by flames.  The example set by you as list owner and as a
participating subscriber to the list is perhaps the most important factor in
whether or not your list becomes a site known for strife and controversy.  In
other words, if you appear not to care about whether or not discussion is on
topic and/or civilized, no one else will, either. Yet if you become a policeman
- the other end of the spectrum - no one will want to subscribe or participate
for fear of your wrath.  Either way, your list is unlikely to last very long.

The middle ground is, as in most things, the place to be when administering a
list.  Some call this "firm but fair," letting things go pretty much as they
will but stepping in with a wry or gently chiding remark from time to time when
exchanges get heated.  And they will!  Software discussion lists are
particularly bad about this when new subscribers ask "frequently-asked
questions" (FAQs) and veteran subscribers respond in exasperated fashion with
"RTFM!" (Read The Fine Manual) and similar nasty retorts.  Good list owner
practice at this point is likely to be a good-natured reminder from you that
flames belong in private mail, pointing out that new subscribers have no way of
knowing that the particular questions they ask have been asked (and answered!) n
random times before.

Finally, if your mailing list has an international audience, you will need to be
careful to account for language problems and cultural differences. You will need
to decide which languages are allowed or not allowed on the list; this should be
mentioned shortly in the list abstract or welcome message. In most cases, the
official language will be English. As your list grows, some subscribers may
object to this decision, arguing that people who have trouble expressing
themselves in English should be allowed to use their own language, with the
understanding that many people will be unable to understand what they are
saying. As the list owner, it will be your call. Usually, the best compromise is
to start a separate list for discussions in the new language. However, you must
be careful in wording your decision. In multi-lingual cultures, it is usually
considered a courtesy to use the other personÆs language. It is certainly
considered rude for people to demand that everyone else should speak their
language. Thus, if your native language is English, you will be in a delicate
position. To avoid a flame war, you will want to make sure that your decision
does not come out as a unilateral demand. Politely suggesting a separate list,
and tolerating an occasional non-English posting when the poster genuinely
cannot speak English, is often the best course of action.

Another possible source of flame wars is unintended rudeness. It is easy to
forget that non native speakers are making an effort every time they post
something to the list. People will make mistakes, sometimes appearing rude when
they did not mean to, simply because they used the wrong word. Another cause of
apparent rudeness is cultural difference. Things which are perfectly normal in
one culture can be insulting in another. For instance, ad hominem attacks are
perfectly acceptable in some countries. Conversely, referring to other people by
their first name ("As Peter said in his last message, ...") can be downright
insulting in some cultures, where anything short of the full title is at best
condescending. But, of course, in other countries the use of the full title is
considered sarcastic... There is no middle ground here, because there are too
many conflicting cultures and too many languages. The only way to successful
cross-cultural communication is through the tolerance of other peopleÆs cultural
habits, in return for their tolerance of yours.

6.3. The role of the list owner as editor
=========================================

Edited lists are generally used for the purpose of "full moderation" or for
refereed electronic journals or the like, for which random postings from
subscribers and/or non-subscribers may not be welcome for general distribution.
This places the list owner and any editors in the position of being full-time
monitors of what is and is not allowed to go through to the list.

A word of warning to potential list editors: Rules on the Internet are not set
in stone. Some people will insist on their right to post without what they will
term "censorship" by the list editor. Some will become upset to the point of
threatening to report you to your local computing center administrators for
abridging their freedom of speech, or (in the U.S.) even threatening to sue your
institution and you personally for an abridgment of their First Amendment
rights. It is therefore vitally important to you that you keep a "paper trail"
of such complaints in the event that threats become reality and you are asked
about them. This common practice in the business world should be common practice
in list ownership as well.

Freedom of speech and copyright issues on the Internet have not yet been tested
in the courts as of this writing. These are both areas in which list editors and
list owners in general must tread carefully. Always document any problems you
may have in these areas.

6.4. Setting up an edited list
==============================

Should you decide that an edited list is the way to go for your particular
situation, you need only add the following lines to your list header file:

    * Send= Editor
    * Editor= Owner

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= Owner,[e-mail]
    * Editor= [e-mail]

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.

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= [e-mail],[e-mail],[e-mail]
    * Moderator= [e-mail],[e-mail]

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.

6.5. Submitting subscriber contributions to an edited list
==========================================================

By default, LISTSERV forwards subscriber contributions to the Moderator/Editor
with the following paragraph prepended to the message body:

--------------------------------------------------------------------------------
This message  was  originally  submitted  by  [e-mail]  to  the ACCESS-L
list at PEACH.EASE.LSOFT.COM. If you simply  forward it back to the list, using
a mail command that generates "Resent-"  fields (ask your local user support or
consult  the documentation  of  your mail  program  if in  doubt),  it will  be
distributed  and  the  explanations  you   are  now  reading  will  be  removed
automatically. If on the other hand you edit the contributions you receive into
a digest, you will have to  remove this paragraph manually. Finally, you should
be able  to contact  the author  of this  message by  using the  normal "reply"
function of your mail program.

------------------ Message requiring your approval (25 lines) -----------------
[message body]
--------------------------------------------------------------------------------
Figure 6.1.     The "editor-header" prepended by default to subscriber
                contributions forwarded to the list moderator.

If you leave this paragraph prepended to the message, LISTSERV will strip it off
when it processes the message and to all intents and purposes the message will
appear to have come directly from the original sender.

When you are ready to edit and/or submit the contribution to the list, simply
use the "Forward" function of your mail client. You can make any changes you
feel are appropriate to the message body, but be sure to read sections 6.2 and
6.3 above before deciding to do so.

6.6. Message Approval with Send= Editor,Hold
============================================

LISTSERV includes an optional mechanism allowing you to simply "ok" messages
which are then posted with all  the correct  headers. This option is targeted
mainly at list moderators who just approve/reject messages, as opposed to people
who actually edit the content of messages.

To activate this feature, code your list "Send= Editor,Hold" and be sure that
you have defined at least one editor who will be in charge of approving the
messages. This defaults to the primary list owner if no other editor is defined.
A copy of the message on "hold" is sent to the editor with instructions on how
to OK it.

6.7. Using 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>

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 Appendix B for more information on setting up and using list topics.

6.8. The <listname> WELCOME and <listname> FAREWELL files
=============================================================

When a user subscribes and signs off of a list, LISTSERV looks for list owner-
supplied files called <listname> WELCOME and <listname> FAREWELL, respectively.
If found, it sends the user a copy of the appropriate file in addition to its
own administrative message.  The WELCOME and FAREWELL files allow the list owner
to send a more personal message to the user that can help set the tone for how
the list is used. The WELCOME file may contain information about the list
charter and netiquette rules, or be simply a message welcoming the user to the
list. The FAREWELL file can be used to gather feedback about how the list is
serving users.

6.8.1. Creating and storing the <listname> WELCOME and FAREWELL files
---------------------------------------------------------------------

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

1.  Create the file.  If you place a "Subject:" line at the top of the document,
    i.e., as the first line, LISTSERV will pick that line up and use it as the
    RFC822 "Subject:" header line. Otherwise, LISTSERV places a generic subject
    line in the mail message.

2.  Be sure that you have defined a "personal password" to LISTSERV with the PW
    ADD command before you PUT the welcome file. If you have done this but can't
    remember the password, send LISTSERV a PW RESET command.  You will then be
    able to add a new password with the PW ADD command.

3.  Send the file to LISTSERV with a PUT <listname> WELCOME PW=XXXXXXXX command
    at the top of the file, just as if you were putting the list itself.
    Replace XXXXXXXX with your personal password.

The variation for VM systems is that the LISTSERV maintainer will have to create
a fileid for the file before you can PUT it on the server. Contact the LISTSERV
maintainer before trying to store your WELCOME and/or FAREWELL files.

Here is the format of a very simple WELCOME file. (Note that the FAREWELL file
is created and stored in an identical manner.)

--------------------------------------------------------------------------------
PUT SONGTALK WELCOME PW=XXXXXXXX
Subject: Welcome to Songtalk!
Welcome to Songtalk, the list for Songwriters talking about their work.
Your list owner is Susan Lowell ([e-mail]).
--------------------------------------------------------------------------------
Figure 6.2.    Sample WELCOME file.

6.8.2. Using the <listname> WELCOME file as a moderation tool
-------------------------------------------------------------

The WELCOME file should contain information geared toward orienting the new
subscriber to several areas. The outline of a suggested WELCOME file follows:

1.  The revision date for the WELCOME file.

2.  A heading including the short and long names of the list, along with the
    name and network address of the primary list owner (or the list owner who
    handles subscription issues/problems).

3.  Any warnings about the list that you want people to see immediately. These
    might include

    *  a notice regarding the volume of mail subscribers can expect from the
       list
    *  any newsgroups that echo the list
    *  ftp sites for the list
    *  where to send LISTSERV commands
    *  where to find more in-depth information about the list (if you do a
       quarterly administrative posting or have a FAQ, where can it be found?)

4.  A short abstract of what the list is all about. This might be a duplicate of
    the description you send to NEW-LIST.

5.  The author includes the following paragraph at this point:

    Users new to the use of L-Soft's LISTSERV are encouraged to read the
    online files LISTSERV REFCARD and LISTSERV GENINTRO, which can be
    obtained by sending the following commands in the body of a mail
    message to [e-mail]:

    INFO REFCARD
    INFO GENINTRO

6.  Any guidelines for use of the list, including the list charter if you have
    one.

7.  Information about the notebook archives and how to retrieve them.

8.  Other list-specific information that might be important to new users.

Naturally, list owners should write WELCOME files based on their own experience
of what is needed. A WELCOME file should not be static - review it once in a
while to ensure that it continues to meet the needs of new subscribers.

6.8.3. Using the <listname> FAREWELL file as a feedback tool
------------------------------------------------------------

The following FAREWELL file is used on [e-mail], and
is intended as a tool to get feedback from users. ACCESS-L's list owner
typically receives 3-5 responses to this message each week.

--------------------------------------------------------------------------------
Subject:  Your ACCESS-L Signoff Request
I'm sorry to see that you're leaving ACCESS-L.  If there is anything
you believe ACCESS-L should have offered but didn't, or there are any
other suggestions you may have for the list, please feel free to write
directly to me.

Sincerely,
Nathan Brindle <[e-mail]>
ACCESS-L List Owner
--------------------------------------------------------------------------------
Figure 6.3.    FAREWELL file used as a feedback tool.

6.8.4. The alternative to using WELCOME and FAREWELL files
----------------------------------------------------------

It is possible to modify LISTSERV's default mail template so that only one
message is sent to users when they subscribe and unsubscribe, rather than an
administrative message from LISTSERV and a WELCOME or FAREWELL file from the
list owner.  See Chapter 9 for the details on modifying the default mail
templates.

However, it is likely that the average list owner will prefer to use the WELCOME
and FAREWELL files over changing the more-complicated templates. Thus both
avenues are provided, and may be used depending on the list owner's level of
comfort.

6.9. Social conventions (netiquette)
====================================

Like so many other things, network users tend to expend a great deal of virtual
gunpowder about the subject of etiquette on the network (otherwise known as
netiquette). Part of the culture of the network is built on the fact that an
individual user can put forward any face he or she cares to present. Thus over
time, the network has evolved various sets of rules that attempt to govern
conduct. To avoid taking up a great deal of space arguing the merits of
differing systems of netiquette, the following general pointers that should be
accepted by most users are offered for the convenience of the list owner.

Recognize and Accept Cultural and Linguistic Differences

The Internet is international, and while English is generally accepted as the
common language of the network, list owners and list subscribers cannot afford
to take the position that everyone on the Internet understands English well. In
a medium that is invariably connected to language, special understanding is
required to deal with questions or statements from people for whom English is
not the primary tongue. Often today (at least in the US) a person's first
sustained interaction with others on an international basis is via the Internet.
It is imperative that this interaction be on the highest level of cordiality and
respect from the outset in order for all concerned to benefit.

Additionally, care should be taken when using local idiom and slang. A common
word or phrase used by Americans in everyday speech, for instance, might be
taken as profanity or insult by those in other English-speaking countries, and
may not be understood at all by non-native speakers of English. When a list has
a high international readership, it is probably best to avoid non-standard
English so as to provide the clearest and least-objectionable exchange of ideas.

Private Mail Should Dictate Private Responses

If someone on a mailing list has sent a private message to you (i.e., not to the
list at large) and you have lost that person's address but want to respond, do
not post private mail to the list. The REVIEW command will give you a copy of
the list membership that you can search for the person's address. If this
approach does not work, contact the local postmaster or the list owner for help.

Flaming is (Usually) Inappropriate

Flames (insults) belong in private mail, if they belong in mail at all.
Discussions will often result in disagreements. Rebuttals to another person's
opinions or beliefs should always be made in a rational, logical and mature
manner, whether they are made publicly or privately. What is a flame can range
from the obvious (ranting and raving, abusive comments, etc.) to the not-so-
obvious (comments about how many "newbies" seem to be on the list these days,
"RTFM!" exhortations, etc.).

Foul Language

Subscribers should refrain from abusive or derogatory language that might be
considered questionable by even the most liberal and open-minded of networkers.
If you wouldn't say it in front of your mother, don't say it in electronic mail.

Unsolicited Advertising and Chain Letters

Most of these are contrary to appropriate use policies governing the use of the
poster's Internet access provider. Not only that, they are annoying and (in the
case of chain letters) often illegal. See Section 6.10 on the subject of
"spamming" for more details.

Other Disruptive or Abusive Behavior

Self-explanatory. It is rarely possible to catalog all forms of anti-social
network behavior. Be sure that you as a list owner cover as many bases as you
think necessary when promulgating a code of netiquette for your list. Then - be
sure to adhere to it yourself.

6.10. Spamming:  what it is, and what to do about it
====================================================

"Spamming" is a network term invented to describe the act of cross-posting the
same message to as many newsgroups and/or mailing lists as possible, whether or
not the message is germane to the stated topic of the newsgroups or mailing
lists that are being targeted.  A "spam" is defined therefore as either (1) a
specific act of spamming, such as the so-called "Green Card Spam", or (2) the
message that actually comes to your list as a result of someone initiating a
specific act of spamming ("The message you just saw was a spam, and it should be
ignored").  Spams are fairly easy to recognize at a quick glance; they often
have "To:" fields directed to large numbers of lists, usually in alphabetical
order.

If a spam gets through to your list, it will probably engender sarcastic replies
(often with the spam quoted in its entirety) - and if your list is coded "Reply-
To= List", they will likely come back to the list.  It is therefore imperative
that you make subscribers aware that when a spam occurs:

*  The person responsible for the spam is probably not subscribed to the list,
   and any response back to the list will not reach that person.

*  An appropriate response to a spam is to forward a single copy of the spam to
   the person in charge of the site from which the spam originated "POSTMASTER",
   "ROOT", etc.) pointing out that the spammer is probably violating his site's
   appropriate use policies.

*  It is inappropriate to attempt to flood the spammer's mailbox with network
   mail in response.  This is probably in violation of your network's
   appropriate use policies, and it just wastes bandwidth.

Perhaps the best policy an individual subscriber can adopt toward spammers is
simply to ignore them and allow list owners and newsgroup moderators to take
care of the problem. If this does not work and subscribers send their complaints
to the list anyway, it might be a good idea to moderate the list for a few days
until the furor dies down.

LISTSERV attempts to detect "spams" using a variety of proprietary methods. When
LISTSERV decides that a message is a spam, it locks out the user for 48 hours,
worldwide in the case of backbone servers.  While locked the user is still able
to use LISTSERV normally and to post to mailing lists, but all messages will be
forwarded to the list owners for human verification. The user is informed that
this has happened but is not informed of which lists caught the message and
which didn't, denying him any idea how successful he has been.

L-Soft will not document how LISTSERV decides a message is a spam because the
point has been reached where a number of authors are writing and selling books
detailing how to avoid such precautions. If L-Soft were to document its methods,
the next editions of these books would simply include updated instructions on
how to bypass them.

6.11. Appropriate use policies:  considerations
===============================================

As a list owner, it is important that you take into consideration any
appropriate use policies that might apply to your list. For instance, if your
list is hosted by an educational site that has a policy restricting mail with
commercial content from being sent out by its users, your list will technically
be in violation of that policy if it distributes mail from users advertising
commercial services. You would be well advised to request a copy of the
appropriate use policy (if any) from your host site and make sure that your
subscribers are aware of it by including pertinent sections in your WELCOME file
and/or your administrative postings.

Host sites are not the only entities that might have appropriate use policies.
The network your host is a part of may have such policies as well.

*********************************
* 7.  Overview of List Archives *
*********************************

7.1. What is the list archive?
==============================

The list archive consists of all of the notebook logs for your list. (If your
list is coded "Notebook= No", then it does not have a list archive, of course.)
Users can find out what notebook logs are available for a specific list by
sending the command INDex <listname> to the appropriate LISTSERV host.

7.2. Setting up and managing archive notebooks
==============================================

If your list is coded "Notebook= No", you should consult your LISTSERV
maintainer before changing the keyword to create list archive notebooks.  The
LISTSERV maintainer will have to tell you where the notebook should be kept (the
second parameter in the "Notebook=" keyword).  Also note that depending on local
policies, you may or may not be allowed to archive your list, or keep more than
a few months' or weeks' worth of archives available at a given time.

7.3. Database Functions Overview [VM only]
==========================================

In this section, we will detail the basics of a LISTSERV command job and show
you a sample database query session. Please note that it is not the purpose of
this manual to provide the user with a detailed database function reference. See
Section 7.4 for more information.

7.3.1.  LISTSERV Command Job Language Interpreter
-------------------------------------------------

The LISTSERV database command syntax used to access database functions is
English-like in structure.  This syntax is called LISTSERV Command Job Language
Interpreter, or CJLI for short.

Database commands are sent to LISTSERV in CJLI "batch jobs". When accessing the
database in "batch" mode, you must construct a CJLI job which you must then
submit to the appropriate server for execution. This means that you must know in
advance what you want to do exactly. If you are not familiar with CJLI, you can
use the following "job skeleton" to build up your database search job:

--------------------------------------------------------------------------------
//      JOB  Echo=No
Database Search DD=Rules
//Rules DD   *
command 1
command 2
...
/*
--------------------------------------------------------------------------------
Figure 7.1.  Sample database job skeleton

This CJLI job is sent in e-mail to the appropriate LISTSERV host. You will then
receive by return e-mail a "DATABASE OUTPUT" file containing the results of your
search. This file might look like this:

--------------------------------------------------------------------------------
> Select * in TEST-L
--> Database TEST-L, 4 hits.

> Index
Item #   Date   Time  Recs   Subject
------   ----   ----  ----   -------
000001 95/10/18 13:09   12   This is a test looking for upcasing
000002 95/08/24 09:18    9
000003 95/10/18 13:09    8   Test - please acknowledge receipt
000004 95/10/18 13:09    7   Does Reply-To=Both work correctly?
--------------------------------------------------------------------------------
Figure 7.2.    Sample DATABASE OUTPUT: Each of the commands in the original job
               is echoed in the output file (unless specifically disabled).

If you realize that the items you were interested in are number 1 and 3, you
will have to submit a new job to ask for a copy of them.  The new job must
include the "Select" command, as LISTSERV does not cache CJLI commands in the
expectation that you will send another command job.

7.3.2.  A basic database session
--------------------------------

Let's say that you are looking for messages in the LSTOWN-L mailing list that
pertain to the list header keyword "Digest=".  You set up a very simple CJLI job
as follows and mail it to [e-mail]:

--------------------------------------------------------------------------------
//      JOB  Echo=No
Database Search DD=Rules
//Rules DD   *
Select 'Digest=' in LSTOWN-L
Index
/*
--------------------------------------------------------------------------------
Figure 7.3.  Sample CJLI job.

Figure 7.3, when sent to LISTSERV, says:  "Look for the string 'Digest=' in all
of the archives you have for list LSTOWN-L.  Then, send me back an index of all
messages in the archives that include that string."

LISTSERV at SEARN obligingly searches the LSTOWN-L archives, finds the
following, and sends it back to you in an e-mail message:

--------------------------------------------------------------------------------
> Select 'Digest=' in LSTOWN-L
--> Database LSTOWN-L, 37 hits.

> Index
Item #   Date   Time  Recs   Subject
------   ----   ----  ----   -------
001215 93/01/06 21:58   50   New feature in 1.7f - automatic digests
001339 93/01/18 02:46  110   New features for 1.7f - "Filter=" and list keyword+
001375 93/01/28 10:02   19   Initial reports from 1.7f beta tests?
001401 93/02/08 16:39   58   Re: List of LISTSERV header keywords?
001616 93/03/18 13:42   70   DIGEST boilerplate announcement/reference
001727 93/04/04 15:22  916   Changes from release 1.7e to 1.7f
....
--------------------------------------------------------------------------------
Figure 7.4.  Part of the LISTSERV response to the CJLI job in Figure 7.3.

The next step is to send a CJLI job to request the specific message(s) you are
interested in.  Let's say that you are interested in changes from one version of
LISTSERV to another, and you therefore would like to see messages 1215, 1339,
and 1727.  You set up the following CJLI framework:

--------------------------------------------------------------------------------
//      JOB  Echo=No
Database Search DD=Rules
//Rules DD   *
Select 'Digest=' in LSTOWN-L
Print 1215 1339 1727
/*
--------------------------------------------------------------------------------
Figure 7.5.  CJLI job instructing LISTSERV to send specific messages to the
             requestor.

This example says:  "Look for the string 'Digest=' in all of the archives you
have for list LSTOWN-L.  Then, send me back message numbers 1215, 1339 and
1727."

LISTSERV will repeat the search from Figure 7.3 and will package the three
messages you have requested into a return mail message and send it back to you.

7.3.3.  Narrowing the search
----------------------------

It is possible to add further parameters to your search in order to narrow it.
You can limit a search by date with a "since. . . " predicate.  Likewise, you
can limit by sender and/or by the subject line with a "where . . ." predicate.
For instance:

    Select 'Digest=' in LSTOWN-L since 94/01/01
    Select 'Digest=' in LSTOWN-L where sender contains 'Thomas'
    Select * in LSTOWN-L where sender is ERIC@SEARN
    Select * in LSTOWN-L since 94/01/01 where subject contains 'Digest'

are all valid search commands that will (hopefully) dramatically reduce the
number of index or print entries returned to you.

7.4. Where to find more information on Database Functions
=========================================================

You can get more detailed information on database functions and the database
command syntax by requesting the file LISTDB MEMO from [e-mail] or
from any other LISTSERV host.  You can send either a "GET LISTDB MEMO" command
or an "INFO DATABASE" command to retrieve the file.

*********************************
* 8.  Overview of File Archives *
*********************************

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

*  The VM (mainframe) version of LISTSERV supports 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 workstation and PC versions of LISTSERV 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.

*  The "new", portable file server system will be a superset of the traditional
   system, in terms of functionality. 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.

In general, the three systems are compatible, with the understanding that the
temporary system does not include all the possible options. However, the
mechanism for registering files (defining them to the file server system) is
different.

Since the first two systems are going to be replaced by the third system
(projected for the end of 1995), rather than providing an exhaustive chapter
detailing all filelist aspects from the list owner side, we have provided only a
basic overview of the two systems currently in the field, 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
==========================================

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. With the temporary system, the LISTSERV
maintainer stores these definitions in a file called SITE.CATALOG, in the MAIN
directory. While files called "xxxx FILELIST" can be created and users can
retrieve them, they do not in turn define further files. The new file server
system will eliminate this confusion, but in the meantime you should be aware of
the differences between VM and workstation file server functions as many list
owners use a VM server with different conventions, and may give you incorrect
advice.

Under VM systems, 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 must register files in
the site catalog. While FILELIST files can be created on non-VM systems and can
be retrieved by users, they do not in turn provide pointers for LISTSERV to
other files existing on the server. Since the current system for workstations
and PCs will be replaced, L-Soft does not recommend that separate FILELISTs be
created on these systems unless there is a pressing reason to do so.

8.3. Filelist maintenance (VM systems only)
===========================================

Maintaining the filelist for your archive is not difficult.  It requires only
that you have a working knowledge of VM XEDIT (or your local system's editor)
and understand how to send files via e-mail.

8.3.1 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.2 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.3. 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 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.

(Note that this assumes the name of the filelist is identical to the name of the
associated mailing list - for instance, [e-mail] 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.4 Deleting files from the filelist
--------------------------------------

Before you delete files from the filelist, you should delete the files
themselves from LISTSERV's archive disk. To do this, send the following command
to LISTSERV without including any replacement data:

    PUT <filename> <filetype> <filelist> [PW=XXXXXXXX]

For instance,

    PUT MYLIST FAQ MYLIST

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.5. Storing the filelist
---------------------------

1.  Create a mail message to LISTSERV at the appropriate host. (Sending a
    filelist to [e-mail] 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.

Once LISTSERV acknowledges the receipt and storage of the filelist, you can send
the files that correspond to the file descriptors in your filelist. See section
8.5, below, for instructions.

8.4. Giving other users access to files on workstation systems
==============================================================

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:

    MY.FILE     MY.FILE.C:\FILES\XYZ  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, MY.FILE.C:\FILES\XYZ, is the name LISTSERV will use for the
actual disk file: filename, period, extension, period, directory. The strange
format is because LISTSERV uses an operating system abstraction layer for file
accesses, where all system-dependent attributes are relegated to the last item.
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:

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 MY.FILE.C:\FILES\XYZ [e-mail],[e-mail],PRIVATE(XYZ-L) CTL

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

IMPORTANT: These "file access codes" apply to LISTSERV commands (GET, PUT,
INDEX) only, and not to the workstation or PC's file security system. It is your
responsibility to protect the actual disk file by setting the file protections
for the directory in which they are created.

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

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

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.8. Where to find more information on File Archives
====================================================

A number of guides that refer to File Archive setup and maintenance are
referenced in Appendix D, Related Documentation and Support.

*****************************************************
* 9.  Customizing LISTSERV's Default Mail Templates *
*****************************************************

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

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

9.3. Mail template format and embedded formatting commands
==========================================================

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

>>> EXAMPLE1 This is the 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.

The template 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. 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 [e-mail])".

&MYSELF      LISTSERV's address, in the form [e-mail] or, if no Internet
             hostname is available, [e-mail].

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

In addition, many templates have their own specific substitutions, meaningful
only in their specific context. For instance, a message informing a user that he
was removed from a mailing list may have an &INVOKER substitution for the
address of the person who issued the DELETE command. This is not meaningful for
a template 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."

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 [e-mail]. 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 to send new
            subscribers a questionnaire, application form or similar material,
            you will need to add a '.TO &WHOM' instruction to your modified
            template, as by default the user will not receive a copy.

.QQ         Cancels the message. LISTSERV stops reading the template 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.

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

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

9.4. 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 section 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 section but leave the rest
of the template untouched, you can delete the rest of the template and store the
INFO section 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.

9.4.1. The INFO section
-----------------------

The first section of DEFAULT.MAILTPL is called the INFO section, 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 of
the 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 9.1.    The default contents of the INFO section 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 mail template 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 mail template (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 section 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 featuring
monkeys.  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 to
the list owners at the generic address:

.ce &LISTNAME-Request@&MYHOST
--------------------------------------------------------------------------------
Figure 9.2.    Sample edited INFO section for a mail template.

9.4.2. Other useful templates
-----------------------------
Version 1.8b introduced many new configurable message templates, and, in
particular, two new types of message templates for "linear" and optional
messages. 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.
Here is a list of these template messages:

*  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 (see below), 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)."

*  TOP_BANNER, BOTTOM_BANNER (optional): when these templates 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.

*  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

*  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 using the same procedure as for REQACK1.

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

*  ADDREQ1 (changed): this message, which was already present in version 1.8a,
   is sent to the list owner when a user requests to join a list with
   "Subscription= By owner". In version 1.8a, a copy of the message was sent to
   the subscriber, to confirm that the request had indeed been forwarded to the
   list owner. Unfortunately this was confusing to the many novice users who do
   not understand the difference between primary and secondary message
   recipients ('To:' vs 'cc:'). In version 1.8b, only the list owner is
   sent a copy of the ADDREQ1 template. If you were using this template to send
   new subscribers a questionnaire, application form or similar material, you
   will need to add a '.TO &WHOMæ instruction to your modified template, as by
   default the user will no longer receive a copy.

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.

9.4.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 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 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. 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 uses substitutions for the list address and list host.
The &LISTADDR substitution translates the full address of the list (XYZ-
[e-mail]), 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 templates.
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."

9.5. 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 you can PUT it on the server. Contact the LISTSERV
maintainer before trying to store your template file.

*********************************
* 10.  Gatewaying to Newsgroups *
*********************************

10.1. Why would I want to?
==========================

There are a number of reasons why it might be reasonable to gateway a list. Some
users may not be able to reach your LISTSERV host (or vice-versa) via e-mail,
but have a good USENET connection. Others may have limited mailbox space and
prefer to use a news reader. Still others may have no experience with mailing
lists at all before they encounter USENET. In any case, if you are looking for a
wider audience for a list, gatewaying it to a newsgroup may be a logical step.

10.2. How to go about it
========================

If you are contemplating gatewaying a list, get the document NETGATE POLICY from
[e-mail]. This document was written by Jim McIntosh of American
University ([e-mail]), and outlines the procedures you will need to
follow in order to gateway a LISTSERV list to USENET.

NETGATE POLICY is also available via anonymous ftp to american.edu (cd netnews).
You can also get a package of related files by sending a GET NETGATE PACKAGE
command to [e-mail].

10.3 Special considerations and problems with gatewaying
========================================================

Well-behaved newsgroup gateways will identify themselves as the source of
postings. This makes it possible for NetNews postings to come to the list if you
have coded your list Send= Private (or "Send= Editor" and "Editor=
<userid@host>,(<listname>)" - in any case, any configuration that prevents non-
subscribers from posting to the list), since the USENET gateway is subscribed to
your list. Misconfigured gateways may not include this information, causing
gatewayed mail to bounce.

If your list is coded for automatic subscription renewal with the "Renewal="
keyword, the subscription for a news gateway should always be exempted from the
subscription renewal process (SET xxxxx@yyyyy NORENEW). This will keep LISTSERV
from sending the renewal message through the gateway and confusing users who are
not subscribed to your list.

Spamming (see Chapter 6.9) was originally created on USENET, and is much more
prevalent there than on mailing lists because it is easier to do. If you gateway
to NetNews, be forewarned that you will be opening your list up to spamming via
that source.

If the topic of your list is particularly controversial, you may want to think
twice before gatewaying. Flame wars are much more common on USENET than on
mailing lists (although this position could be argued from both sides on certain
mailing lists). If you are considering gatewaying to an existing newsgroup, take
some time to read the postings there before making a final decision.

Above all, poll your subscribers about the change before making a final
decision. Some may have no objections - others may have violent objections.
Gatewaying a list can be a touchy subject, particularly if some of your
subscribers are ex-USENET users.

*************************
* 11.  Solving Problems *
*************************

11.1. Helping subscribers figure out the answers
================================================

As the saying goes:  "Give a man a fish, feed him for a day; teach a man to
fish, feed him for life." The analogy can and should be extended to all Internet
users, not the least of whom are your own subscribers.

Depending on your own preferences, some requests from subscribers for operations
that they can perform for themselves can be fulfilled by you as the list owner,
or by the subscribers with some coaching from you. While it is a negative
approach, the list owner can never assume that the subscriber reads or saves the
materials sent to him at the time of subscription. Thus you will have to deal on
a regular basis with users who ask how to unsubscribe, or how to get archive
files, or how to set their subscription to DIGEST or NOMAIL.

Often these requests for help are posted directly to the list. The proactive
approach to this problem is to do one or both of two things:

*  Respond to the list with the answer so that all can benefit
*  Respond privately to the subscriber with the answer if it has been posted
   repeatedly

If a user asks a question about a topic that has been discussed previously, you
might suggest in a tactful way that the answer can be found in the archives. If
your host server supports the LISTSERV database functions, you might even
include a sample DATABASE JOB that the user can "clip and send" to LISTSERV.

Often it is tempting to simply "get things over with" and take care of the
user's request in many cases - the user wants to be set to NOMAIL because he's
going on vacation, the user wants off the list, etc. - but while this solves the
short-term problem, it doesn't teach the user anything. Naturally it takes more
time to be a coach than it does to be the all-powerful list administrator, but
the goodwill you can create by being proactive rather than reactive outweighs
the convenience of simply sending the command yourself. You will find that many
subscribers appreciate the fact that someone takes the time to explain the
complexities of LISTSERV to them.

In order to cut down on the time it takes to respond in "coaching" situations,
many list owners prepare "boilerplate" files with the answers to common
questions that they can simply "cut and paste" into return mail. (Several such
"boilerplate" files are included in Appendix C.)

11.2. Loop-checking can cause occasional problems with quoted replies
=====================================================================

By default, LISTSERV's internal loop-checking routines look for anything in the
body of a mail message that looks like a header line - specifically anything
that looks like a "To:", "Sender:", or "Reply-To:" header line. If it finds
anything like this, LISTSERV intercepts the message and sends it to the list
owner (or the person(s) designated by the "Errors-To=" keyword) as an error.

Often a user who replies to list mail includes all or part of the message he is
replying to as part of his reply ("quoting"). While this is a questionable
practice to begin with, unfortunately a number of popular mail programs make it
worse by including the quoted message in its entirety (including header lines)
in the body of the reply. For instance, the following message ended up in the
author's error mailbox:

--------------------------------------------------------------------------------
The enclosed message, found in the ACCESS-L mailbox and shown under the spool
ID 6305 in the  system log, has been identified as  a possible delivery error
notice  for the  following reason:  "Sender:", "From:"  or "Reply-To:"  field
pointing to the list has been found in mail body.

------------------------ Message in error (42 lines) --------------------------
Received: by access.mbnet.mb.ca id AA05697
  (5.67b/IDA-1.4.4 for Microsoft Access Database Discussion List
<[e-mail]>); Wed, 1 Mar 1995 10:26:29 -0600
Date: Wed, 1 Mar 1995 10:26:29 -0600
From: xxxxxx xxxxxxxxx <[e-mail]>
Message-Id: <[e-mail]>
To: Microsoft Access Database Discussion List
Message-Id: <[e-mail]>
To: Microsoft Access Database Discussion List
<[e-mail]>
Subject: Re:      Re: Foxpro listserv address
X-Mailer: AIR Mail 3.X (SPRY, Inc.)


<---- Begin Included Message ---->
Date:         Thu, 23 Feb 1995 01:17:36 -0500
From: [e-mail]
Sender: Microsoft Access Database Discussion List
              <[e-mail]>
Subject:      Re: Foxpro listserv address
To: Microsoft Access Database Discussion List
              <[e-mail]>

>BTW, I don't know why she is still on Foxpro, I thought they went out
>into the desert??

<---- End Included Message ---->

(subscriber's reply deleted)
--------------------------------------------------------------------------------
Figure 11.1.    Sample error message with included headers.

The  problem with this reply was two-fold, from a list owner's standpoint. First
(a netiquette issue), the sender didn't bother to remove unnecessary header
lines from his reply. If properly formatted, however, this would not normally
cause an error.

Second, the mail software he was using didn't include ">" characters at the
beginning of every line of the included message. Had it done so, the message
would have passed through LISTSERV unhindered.

One variation on this error is mail software that quotes messages by adding the
">" character followed by a space for esthetic reasons. For instance, using the
above error as an example:

--------------------------------------------------------------------------------
> Date:         Thu, 23 Feb 1995 01:17:36 -0500
> From: [e-mail]
> Sender: Microsoft Access Database Discussion List
              <[e-mail]>
> Subject:      Re: Foxpro listserv address
> To: Microsoft Access Database Discussion List
              <[e-mail]>

> BTW, I don't know why she is still on Foxpro, I thought they went out
> into the desert??
--------------------------------------------------------------------------------
Figure 11.2.    A slightly different sample error message with included headers.

This won't work either. Generally this is a client configuration problem and it
can be fixed by setting the quoting character in the client's configuration
file.

On the other hand, the following quote would have worked:

--------------------------------------------------------------------------------
>Date:         Thu, 23 Feb 1995 01:17:36 -0500
>From: [e-mail]
>Sender: Microsoft Access Database Discussion List
              <[e-mail]>
>Subject:      Re: Foxpro listserv address
>To: Microsoft Access Database Discussion List
              <[e-mail]>

>BTW, I don't know why she is still on Foxpro, I thought they went out
>into the desert??
--------------------------------------------------------------------------------
Figure 11.3.    A correctly-formatted message with included headers.

The ultimate solution to the problem is to warn subscribers to limit their
quoting to a minimum, and in any case to be sure to delete anything that looks
like a header line in the body of their reply.

11.3. User can't unsubscribe and/or change personal options
===========================================================

See Chapter 4, section 4.1 where this is discussed in detail.

11.4. Firewalls
===============

Firewalls on the Internet are set up for essentially the same reason firewalls
are designed into buildings and automobiles - to keep dangerous things (in this
case, hackers, viruses, and similar undesirable intruders) from getting in and
wreaking havoc with sensitive data. Unfortunately, they don't always keep people
from behind them from sending mail out, and this can cause problems when users
from such sites attempt to subscribe to lists.

If your list is set to confirm all subscriptions with the "magic cookie" method
("Subscription= Open,Confirm"), you will receive an error message any time a
user from a firewalled site attempts to subscribe, since the "cookie"
confirmation message will bounce off the firewall. If your list is not set to
confirm subscriptions, the same user will be able to subscribe to your list but
all mail sent to him will bounce.

Some firewalls reportedly can recognize "friendly" LISTSERV mail and let it
through, but because of security considerations, it is unlikely that this
problem will ever completely go away. Thankfully it does not seem to be a major
cause of mailing list errors.

11.5. If I can't find the answer, where do I turn?
==================================================

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

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

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