21 September, 1995
The Corporation for Research and Educational Networking
Table of Contents
21 September 1995, ListProcessor 7.2
This List-Owner Reference Manual provides an overview to the list-owner
commands of the CRENÆ ListProcessorÆ list-
and file-management software, also known as ListProcÆ. The
commands documented in this reference are not generally available to
subscribers who do not own the list affected by the command being used.
This reference assumes familiarity with the ListProcessor User Manual and does not replicate that document's explanation of ListProc's subscriber commands.
This Owner's manual is one of four documents of which list owners should be aware. All are available via anonymous ftp and Gopher from info.cren.net in the /listproc directory. Each file is available in Postscript (the .ps file extension), RTF (the .rtf file extension) and plain text (no file extension). These files are listed below (base file names are enclosed in parenthesis):
1) The List Owner's Manual (ownerman) explains in detail how to manage a list.
2) The List Owner's Reference Card (ownercard) is a short reminder of the material covered in the Manual.
3) The ListProcessor User's Manual (userman) is a detailed explanation for users of how to interact with the list processor.
4) The User's Reference Card (usercard) is a short reminder of material covered in the Manual.
It is strongly recommended that you, as list owner, obtain and read all four documents. You should be familiar with end-user commands, which are not covered in this document. It is recommended that you either print this Owner's Manual out or use a multi-window program to read it so that you can more easily refer to different sections.
In this reference, ListProcessor commands are shown in this typeface, with italics used for any command options and arguments which are to be replaced by the user. The minimum command abbreviations are in UPPERCASE. The actual commands are case-insensitive. For example, the command SUB is the same as sub or subscribe. Optional arguments and keywords are enclosed in brackets ([...]) and alternatives separated by a vertical bar ( | ), both of which must be omitted when the actual command is used. The list firstname.lastname@example.org has been created for experimenting with ListProc. The term "local lists" refers to lists hosted by the ListProcessor with which you are communicating; "remote" lists are those hosted by other ListProcessors. Commands which relate to remote lists are forwarded to the appropriate ListProcessor when there is adequate information.
What is ListProcessor?
The Internet provides thousands of discussion groups via e-mail. Participants
in these discussion groups place themselves on mailing lists, called "lists"
for short, in order to be able to send messages to and receive messages from
the various lists. ListProcessor, ListProc for short, is a powerful mailing
list agent that keeps track of thousands of people subscribed to any number of
mailing lists. When a user subscribes to a list, that person's name and e-mail
address are automatically added to the list of subscribers. The new subscriber
will receive a form letter of welcome telling about the list. Then all mail
sent to the list by other subscribers will be sent to the new subscriber also.
If the new subscriber wants to reply to these messages and sends in a response
to a message, the message will be sent out to everyone who is subscribed to the
list. Users may post messages, review members of lists, review the
configuration set up of lists, etc.
ListProc allows full control over the list and its configuration to the list owner, freeing up the system manager from having to make major modifications for the list owners when needed. ListProc is also a powerful file archiver, allowing search and retrieval of text files based on regular expressions and e-mail retrieval of binary files automatically uuencoded and divided into manageable sized portions. It is automated, and eliminates the need for user intervention and maintenance of multiple aliases of the form "list, list-owner, list-request", etc. There is support provided for public and private hierarchical archives, moderated and non-moderated lists, peer lists, peer servers, private lists, address aliasing, news connections and gateways, mail queuing, digests, list ownership, owner preferences, crash recovery, batch processing, configurable headers, regular expressions, archive searching, and live user connections via TCP/IP.
What Are the Responsibilities of a List Owner?
List owners are individuals responsible for list administration via mail
commands. Thus, list owners may be remotely located. Each list has to have at
least one list owner. These owners may be different than the system's manager,
and have special privileges: they may issue commands on users' behalf (add
a user, remove a user, etc.) overriding system restrictions set on regular
users (including overriding disabled commands), obtain reports about the
lists they administer, append to the ".aliases" and ".ignored" files,
change the welcoming (".welcome") and informative (".info") messages, as
well as other system files such as the aliases file (".aliases"), the
".ignored" file, the subscribers file (".subscribers"), the news file (".news")
and the peers file (".peers"). In addition, they may moderate their lists
and they receive various error messages pertaining to their lists. All
administrative commands are author authenticated and password protected.
Whenever a message cannot be author authenticated, the list's owner and manager
are notified. On the other hand, list owners may not add restricted users;
this service can be provided by contacting the system's manager. List
owners may also receive copies of user commands and/or error messages such
as invalid postings, syntax errors on commands, etc.
List owners may assign various parts of these responsibilities to other people. List owners may assign moderators, whose function is to approve messages and guide the on-line discussion, subscription managers, whose function is to add or remove individuals to the list, and recipients of error messages, whose function is to contact users who generate error messages by submitting invalid commands and educate them as to the error, also to remove users whose addresses are no longer valid.
Special Files that ListProc Uses
ListProc makes use of a number of text files during the course of its
operation. Some files, such as the list's config file, are changeable via
commands to ListProc and are not editable, but others can be requested from
ListProc using the EDIT command, edited, and replaced using the
PUT command (see EDIT and PUT
in the command section below). These seven files all have filenames starting
with a dot "." and are .aliases, .ignored, .info, .news, .peers, .subscribers,
and .welcome. When requesting any of these files for editing from ListProc you
do not include the dot in the filename in the command line, so the discussion
below will not include the dot in the filename in order to avoid confusion.
The alias file allows the list owner to rewrite incoming e-mail addresses. Due to the wide variation in the manner in which different hosts are set up, it is possible that e-mail can come in to listproc with a different return address than the sender's real address. For example, if mail comes in from BITNET there is no way of knowing which gateway will be used for the mail. The mail may come in as email@example.com on one occasion and from firstname.lastname@example.org on another occasion. A user can likely get back a error message saying that he/she is not subscribed to a particular list. In order to get the ListProc to accept the address email@example.com no matter what gateway it comes through an alias can be set up in the alias file.
The ignored file filters out messages sent by certain users. You may, for example, want to prevent error messages coming from firstname.lastname@example.org from being posted to your list. Or perhaps you have a particularly annoying individual whose messages you want filtered out. By putting these addresses in the ignored file you prevent anything coming from these addresses from going out to your list.
Two very important files are the welcome and info files. The welcome file is a message automatically sent out to all new subscribers to a list. The info file is sent out to anyone requesting information from ListProc about your list. Both files should give the list name, names and e-mail addresses of list owners or moderators, purpose of the list, and any special rules and regulations pertaining to the list. The welcome file should additionally contain some welcome message.
The subscribers file contains a list of all subscribers to a list, their e-mail addresses, names, and switches for their subscriptions such as concealed, ack, noack, digest, etc. The subscribers file is one file that can be EDITed or can be modified by using ListProc's internal commands such as ADD, DELETE, SET, etc. The subscribers file must be in a specific format. If you chose to edit that file and then replace it with an edited version and if your text editor makes a minor reformatting such as word-wrap or if you make a small error in one character in your editing, then the newly placed subscribers file will not only not work, it will cause ListProc to crash. For this reason it is important that you not try to edit the subscribers file, but instead use ListProc's commands to modify the subscribers file.
Lists can be gatewayed to newsgroups; that is, postings to a particular newsgroup will be forwarded to a mailing list and postings to the mailing list will be placed in the newsgroup. One way gateways are also possible in which postings to the list go to the newsgroup but no postings to the newsgroup will go to the list. Or the opposite one way gateway can be set up allowing only postings from newsgroup to list. The news file contains the information necessary for establishing the gateway between newsgroup and list. Peer lists are mailing lists that are subscribed to one or more mailing lists at local or remote sites. They handle local distribution of messages just like any other list and also distribute messages that originate in the peer lists. The peers file is a special file which coordinates the peering of lists. The syntax and use of peer files and news files is beyond the scope of this owner manual and can be found in the ListProcessor site manager manual. It is suggested that the peers and news files should be edited only by the ListProc system manager, not by list owners.
Configuring Your List From the Beginning.
The first thing you need to do when your list is set up by the system
administrator is configure it and create WELCOME and INFO files. This section
will discuss some of the more important issues to consider when configuring
your list and refer you to sections of the Command Reference section for
commands related to each item discussed.
a) It is important to have WELCOME and INFO files in most cases. The INFO file serves the purpose of informing potential users what your list is all about. The INFO file should have a full description and any restrictions imposed on the list membership. Potential subscribers should be able to get the INFO file and decide upon reading it whether they want to subscribe to your list. The WELCOME file should also tell what the list is about but additionally should give instructions for how to get in touch with list owners and/or moderators and give any rules and regulations of membership in the list. For creating INFO and WELCOME files see section 6.A.1 EDIT and section 6.A.2 PUT.
b) Do you want your subscriptions to your list to be open, closed, or owner-controlled? Open means that anyone can subscribe to your list without needing your prior approval. Subscription is by simply sending a message to the ListProcessor asking to be added to the list. Owner-controlled means that all subscription commands from users get forwarded to someone who you designate as your subscription manager. If you, the owner, do not designate a subscription manager, then you, the owner, become the subscription manager by default. Closed means that no one can submit a subscribe command to your list. You, the owner, may add people to your list but if anyone tries to send a subscribe command they will get back a message saying that the list is closed to subscriptions. For configuring your list as OPEN, CLOSED, or OWNER-CONTROLLED see section 6.x.x CONFIGURATION listname password OPEN-SUBSCRIPTIONS, section 6.x.x CONFIGURATION listname password CLOSED-SUBSCRIPTIONS, and section 6.x.x.x CONFIGURATION listname password OWNER-SUBSCRIPTIONS.
c) Do you want your list to be moderated or unmoderated? Moderated means that all messages sent to the list by subscribers must be approved by the list moderator before anyone else can see them. There are two types of moderation. In moderated-no-edit the moderator is presented with the message and a tag number. The moderator may then approve or discard the message as is. In moderated-edit the moderator may not only approve the message but also may edit it before sending it back to be posted to the list. Unmoderated means that all messages sent to the list automatically get forwarded to everyone subscribed to the list without the moderator's approval. If you, the owner, do not designate a list moderator, then you, the owner, become the subscription manager by default. For configuring your list as moderated or unmoderated see section 6.B.x.x CONFIGURATION listname password MODERATED-EDIT, section 6.B.x.x CONFIGURATION listname password MODERATED-NO-EDIT, and section 6.B.x.x CONFIGURATION listname password UNMODERATED.
d) Do you want your list to be hidden or visible? Hidden means that anyone requesting a list of all lists known to the server will not see your list. Visible means that people requesting information about lists supported by your server will see your list. You can have a visible list and still restrict the amount of information people can obtain about your list. For configuring your list as hidden or visible see section 6.B.x.x CONFIGURATION listname password HIDDEN LIST and section 6.B.x.x CONFIGURATION listname password VISIBLE-LIST.
e) How much information can people get about your list? Every list has an info file, a one line description, a series of attributes or settings, and a list of its subscribers. You can restrict access to each individual piece of this information, either only to list subscribers, to the general public, or to no one. To control who can review your list see section 6.B.x.x CONFIGURATION listname password REVIEW-TO- To control who can obtain your list statistics see section 6.B.x.x CONFIGURATION listname password STATISTICS-TO- To determine whether anyone can see a list of your subscribers see section 6.B.x.x CONFIGURATION listname password DEFAULT CONCEAL YES|NO
f) Will there be archives of your list, and if so, who will have access to list archives? In addition to archives of material sent out by your list you can also have archives of supplementary material. You control access and determine whether a password is needed to access these materials. For information on configuring archives of the list messages see section 6.B.x.x CONFIGURATION listname password ARCHIVE To determine who can get access to the archives see section 6.B.x.x CONFIGURATION listname password ARCHIVES-TO-
g) How much information do you want to get about your list's operation? Getting list information and error messages is discussed in section 6.B.x.x CONFIGURATION listname password DEFAULT PREFERENCES and in section 6.F.x SET PREFERENCES with the following options for the preferences:
1. If your list is open, do you still want to know about all new subscribers? CCSUBSCRIBE CCUNSUBSCRIBE
2. Every time someone sends a request for a list of recipients, for information, for list statistics for a review of the list or a run command, do you want to receive a copy of the ListProc's response? CCREVIEW CCSTATISTICS CCINFORMATION CCRECIPIENTS
3. Every time a message comes in from someone in your 'ignore' file or someone not subscribed to your list if private, do you want to know? CCIGNORE
4. Do you want copies of all error messages? CCERRORS CCALL
These questions must be considered seriously because the more information you request, the more mail you will be getting. If you want all of these informational messages and you have an active list, you could get hundreds of informational messages filling up your mailer each day. You can designate someone else as recipient of all error messages if you want error messages monitored but cannot take the time to do it yourself. To designate someone as recipient of error messages see section 6.c.x.x CONFIGURATION listname password DELIVERY-ERRORS-TO address
g) Is your list going to be mailed out as a digest or not? A digest is a group of many messages sent out together in a single 'digest' message and has the advantage of not filling up your users' mailboxes with large amounts of mail from an active list. On the other hand, it delays the sending of individual messages until enough messages have been received to make up a digest. In a less active list this may be undesirable. To determine whether your list is sent out as a digest or not, see section 6.B.x CONFIGURATION listname password DIGEST frequency when
Keep in mind when a new list is set up that listproc has some built in defaults. These defaults may be changed by the ListProcessor manager.
ListProc defaults are listed below with short explanations. Longer explanations can be found in the various command sections below dealing with each of these options. ListProc distribution defaults are:
stats-to-all The general public can request list statistics
review-to-all The general public can review a list's settings
auto-delete Automatically delete users whose mail bounces
digest-daily Digests are sent out daily if mailmode digest is chosen
send-by-all Anyone can send mail to the list whether subscribed or not
no-archives The list is not archived
open-subscription Anyone requesting a subscription to the list is added
Everything is open, that is the default list allows maximum access to all users. If you want a restricted list you must change those defaults.