BITNET Network Information Center LISTMGT HELP EDUCOM, Suite 600, 1112 16th Street, NW, Washington, DC 20036, USA, 202-872-4200 List Management Tips for LISTSERV Postmasters and List Owners Version (1) 12-5-91 Lisa M. Covi Systems Support Professional covi@educom.edu, COVI@BITNIC @ Copyright CREN 1991. May be reproduced with credit. Table of Contents ------------------------ 0 Introduction 1 Prerequisites 2 Setting up LISTSERV 2.1 Who has privileges? 2.2 Issuing LISTSERV commands 2.3 Shutting down LISTSERV 3 What lists already exist? 3.1 Directory of LISTSERVs 3.2 Directory of LISTSERV lists 3.3 Tools for Parsing Lists of Lists 3.4 Directory of Electronic Journals 3.5 New List Announcements 4 Adding and Deleting users from existing lists 4.1 Checking subscriptions 4.2 Adding and Deleting subscriptions 4.3 Unsubscribing a user from all BITNET lists 4.4 Deleting Lists 5 Setting up New Lists 5.1 Introduction 5.2 The Cookie Cutter Method 5.3 Modifying the configuration (keyword headers) of lists 5.4 Adding a group of users to a closed list 5.5 List Keyword Defaults 5.6 List-Keyword Recommendations 5.7 Keyword Options for Small Lists 5.8 Formatting REVIEW output 5.9 Aliasing List Names 5.10 System Tuning 5.11 Maintenance Updates 5.12 Maximum size of a message to a list 5.13 Daily Maximum number of messages 5.14 Suppressing Subscription/Unsubscription Announcements 6 Individual List Subscriber Option Flags 6.1 Tired of /Want more Extra Messages from LISTSERV? 6.2 Going on vacation? 6.3 Want to restrict a user from sending files to a list? 6.4 Want to get a copy of your mail to a list? 6.5 Suppressing the names on mail from LISTSERV 6.6 How does LISTSERV track subscriptions? 6.7 Want an unlisted address? 1 7 Edited Lists 8 Subscription Renewal (the RENEWAL= list header) 9 Large Lists and Peering 10 Archives (List Notebooks or Logs) 11 Troubleshooting - Miscellaneous problems 11.1 Are one or more lists not sending mail? 11.2 Are you getting no LISTSERV response? 11.3 Is LISTSERV misplacing your PUT's? 11.4 Are your requests to DELETE a file from a file list result in requests getting forwarded to some LISTSERV POSTMASTER? 11.5 Are you running up against the 256K daily limit on getting files from LISTSERV? 11.6 Are you puzzled why mail is bouncing? 11.7 Need to get rid of mail that violates BITNET usage rules (i.e. broadcast messages or files)? 12 Customized List Messages - Mailforms 13 List gateways to Usenet Newsgroups 14 File Server Functions 14.1 Obtaining files from the LISTSERV File Servers 14.2 Adding files to an Existing FILELIST 14.3 Deleting a file from an existing FILELIST 14.4 Creating your own FILELIST 14.5 Peered FILELISTs 14.6 Maximum file length 14.7 Troubleshooting -only getting the header of your FILELIST request? 14.8 Packages - Sending out a group of files with one GET command 14.9 Automatic File Subscription 15 Searching LISTSERV Files 16 Acknowledgements ------------------------ 1 0 Introduction This document will outline the procedures necessary for managing and supporting the popular electronic mailing list management software LISTSERV. Before you read this document, you should be familiar with the basic use of LISTSERV outlined in the document BITNET INTRO (1) and how to use your local mail software. The purpose of the document is to get you started in becoming the local LISTSERV expert or provide a reference for those who may already have experience managing LISTSERV or owning lists. Other good sources of information are the lists LSTSRV-L@UGA and LSTOWN-L@INDYCMS. This document will not discuss details of installation and maintenance of the LISTSERV software itself (LSTSRV-M@SEARN is a good reference for those topics). If you want to skip to instructions on how to look up topics on these lists, look in Section 15 Searching LISTSERV Files. I hope that you will enjoy exploring and making use of these LISTSERV functions as much as I have. Although it is often frustrating to use voluntarily written and maintained software (mostly due to lack of documentation), LISTSERV has been so well-written and utility-oriented that its usefulness greatly outweighs initial frustration. Please feel free to make suggestions for contributions to this document by sending mail to me at covi@bitnic. This document has grown out of my own learning process (making mistakes is the ultimate learning experience) and I'm sure there are many gaps (and much more to learn). 1 Prerequisites The more you know about your mailers and editing your mail, the more productive you will be in managing LISTSERV. If you have not had the opportunity to use LISTSERV before being thrust into your current predicament, please subscribe to LSTSRV-L or another list that interests you (see Section 3.2 Directory of LISTSERV lists) as an exercise. The list of documentation that is provided with LISTSERV can be obtained by sending your nearest LISTSERV (try LISTSERV@BITNIC if you don't know) the command INFO. Be forewarned that the standard LISTSERV documents are not complete and should be used in conjunction with other resources mentioned in this document. 2 Setting up LISTSERV LISTSERV is a VM/CMS based software package available free of charge to BITNET members that offers interactive subscription, unsubscription and file server capabilities on BITNET and, by way of mail gateways (2) from the Internet. In order to set up a LISTSERV, one of the BITNET registered contacts (anybody from your node listed in the BITEARN NODES or the MAINT account should send mail to ERIC@SEARN (Eric Thomas, the author of LISTSERV) who will send him/her the code. Be forewarned that this is not a commercial product and that Eric is not available for a great deal of direct support and will tell you so. 1 2.1 Who has privileges? There are only two levels of "privileges" on LISTSERV: POSTMASTER, who can shutdown or stop LISTSERV and has full ownership authority over all lists on that LISTSERV, and LIST OWNER, who has full ownership authority only to a particular list. There is a file called LOCAL SYSVARS on LISTSERV's 191 disk which contains LISTSERV definitions such as who has POSTMASTER privileges. LIST OWNERS are designated in the file that contains the mailing list or file list itself. The LOCAL SYSVARS file also contains creation, store and installation passwords for LISTSERV which are required to create new lists, store files on LISTSERV and install updates to the LISTSERV software. It is strongly recommended that each list be assigned an optional password created and maintained by the list owner that can control access to the way the list and files associated with that list can be accessed and modified. See the discussion about setting up new lists below for more information on list passwords. Personal passwords which are associated with specific user IDs, can be used for LISTSERV's Automatic File Distribution features mentioned in section 14.9. 2.2 Issuing LISTSERV commands There are two ways of issuing LISTSERV commands: interactively and by mail). This document will give examples of the interactive commands. To issue the the commands by mail, just send a message to LISTSERV@listnode (where listnode is the node where the LISTSERV resides) and put the comm and (the part after "TELL LISTSERV") into the message text. Note that LISTSERV ignores the subject heading. This document also assumes that the LISTSERV you are using is local. If you are using a LISTSERV at another node, the interactive command should include AT listnode, i.e. TELL LISTSERV AT listnode If you send an interactive command, you will receive an interactive response on your screen and information you request from LISTSERV will be spooled to your reader. If you are sending mail messages, your responses and data will return by mail. If you are a POSTMASTER for LISTSERV, you may issue user commands as if the command came from a different user. For example to subscribe someone (user@node) to a list, type: TELL LISTSERV FOR user@node SUB listname firstname lastname If the list is not public, this command may cause the subscription to be forwarded to the list owner, which you may or may not want. FOR is meant to be used more for debugging problems (See Section 11.6 Are you puzzled why mail is bouncing?) than for routine list management. I recommend encouraging your users to become LISTSERV-literate and learn to make full use of LISTSERV themselves. 1 2.3 Shutting down LISTSERV Occasionally a POSTMASTER may be required to shutdown the LISTSERV server for system maintenance (i.e. adding disks to LISTSERV). To perform this task, type: TELL LISTSERV SHUTDOWN Then query LISTSERV to make sure it is not logged on (it is normally disconnected -DSC): Q LISTSERV You may then login to the LISTSERV ID, if required, to perform your maintenance task. When you are ready to bring LISTSERV up, the system administrator should login to a user ID with AUTOLOG authority and type: AUTOLOG LISTSERV If you have logged in to LISTSERV interactively, you can also start it by typing: LSVPROF 3 What lists already exist? 3.1 Directory of LISTSERVs There is a complete directory of sites running LISTSERV on LISTSERV@BITNIC in the file LISTSERV SITES. If you need to get in touch with a LISTSERV site's maintainer, that information is there too. 3.2 Directory of LISTSERV lists To get a list of all the existing, publicly available lists on LISTSERV, type: TELL LISTSERV LIST GLOBAL You will receive a file with over 2800 records (lines) which has been generated by LISTSERV and thus includes all instances of a list including its peers (see Section 9 on Large Lists and Peered Lists for more information). If you don't want all this information, you may get a listing based on a search string. For example, to find all lists that have something to do with Chemistry, you could try: TELL LISTSERV LIST GLOBAL /CHEM There is also a list of lists on the Internet that contains both BITNET lists and Internet interest groups: Internet: anonymous ftp to ftp.nisc.sri.com in the file netinfo/interest-groups BITNET: send mail to mail-server@nisc.sri.com with the message text send netinfo/interest-groups 1 3.3 Tools for Parsing Lists of Lists There is a LISTSERV database called LISTS which can be searched with LISTSERV database searching utilities. See Section 15 Searching LISTSERV Files for more information. Dartmouth makes a list of lists available that includes an abridged (no duplicate entries or local lists) version of the "official" list of Internet interest groups. This list is updated monthly and has information in the form of tab-delimited fields: category list name, mailing address, subscription/command address, one line description of the list, address of list owner, long description (< 450 characters) of the list. Also available is a Macintosh Hypercard application package containing the files: LISTLIST HQX - 7 MB stack of the List of Lists LISTSERV LISTS - 5 MB file from with the above was built LISTSTUB HQX - one card of the LISTLIST stack LISTTUTR HQX - Tutorial stack on mailing lists READ ME - complete information on the Dartmouth list of lists You can get these files by requesting them from: Internet: anonymous ftp to dartcms1.dartmouth.edu in the file siglists/filename.filetype BITNET: TELL LISTSERV AT DARTCMS1 SEND filename filetype A VAX RDB/VMS software package is available on the Internet only from vax.muskingum.edu and requires BASIC. The directory dartmouth contains the files: *.EXE *.RDB *.SNP DARTMOUTH.DOC You may contact Lewis Dreblow (dreblow@vax.muskingum.edu) for more information. See the information below in Section 14.9 Automatic File Subscription to find out how to subscribe to updates of these files. 3.4 Directory of Electronic Journals There is a Directory of Electronic Journals and Newsletters available from ARL. To obtain a printed version of the directory for a small fee, contact: Office of Scientific & Academic Publishing Association of Research Libraries 1527 New Hampshire Avenue, NW Washington, DC 20036 USA ARLHQ@UMDC 202-232-2466 (voice) 202-462-7849 (fax) An online version is available from University of Ottawa by typing: TELL LISTSERV AT UOTTAWA GET EJOURNL1 DIRECTRY TELL LISTSERV AT UOTTAWA GET EJOURNL2 DIRECTRY 1 3.5 New List Announcements (3) Most people who keep and compile local copies of Lists of Lists subscribe to the NEW-LIST LISTSERV list at NDSUVM1 (vm1.nodak.edu on the Internet). NEW-LIST is a moderated list (See Section 7 Edited Lists) for new list announcements, old list deletions and major list changes (i.e. if you move a list to another host or node). You can get a copy of a sample announcement by typing: TELL LISTSERV AT NDSUVM1 GET NEW-LIST FORMAT You should announce a list only after it is well-tested. If you are interested in subscribing to NEW-LIST yourself, type: TELL LISTSERV AT NDSUVM1 SUB NEW-LIST yourfirstname yourlastname Some additional hints on how to search for additional lists are kept in the file "LISTSOF LISTS" (note the two plurals). You can get it by typing: TELL LISTSERV AT NDSUVM1 GET LISTSOF LISTS 4 Adding and Deleting users from existing lists Before I explain how to set up a new list from scratch, here are some useful, commonly-asked commands about how to work with existing lists. In order to work with an existing list, make sure you have the listname and the node name. If you aren't sure and it's a public list, do a string search of the List of Lists mentioned in Section 3.2 Directory of LISTSERV lists. 4.1 Checking subscriptions As a LISTSERV manager or list owner, you will find that the users on your lists are not always vigilant about keeping their lists subscriptions up to date. In fact, you may find that sometimes users are not even aware of all the lists to which they are subscribed (I confess, neither am I). If they don't already know this command, teach your users the following command to find out who is currently subscribed to a given list: TELL LISTSERV REVIEW listname If you want to find what lists to which a user (user@usernode) is subscribed at a particular LISTSERV type: TELL LISTSERV QUERY * FOR user@usernode 4.2 Adding and Deleting subscriptions As a list owner and/or a list manager, I would encourage you to take full advantage of LISTSERV's user capabilities by setting up lists (see Section 5.5 List Keyword Defaults) to have self-subscription and unsubscription and setting up lists to have automatic renewal to cut down on the management tasks you will have to perform. However, even if you have automatic subscription/unsubscription, you may be required to alter users' subscriptions, i.e. if a subscriber's From: address changes and s/he can no longer communicate with the list. You will also have to manually subscribe and unsubscribe (add and delete ) users if you maintain closed subscription lists. 1 When you change a subscription, LISTSERV automatically sends a message to the user explaining the change. However, if the address no longer exists, or there is an important reason you want to bypass this notification message, you can use the QUIET option (examples below). In order to delete a user from a list with no notification, type: TELL LISTSERV QUIET DELETE listname user@node In order to add a user to a local list with no notification, type: TELL LISTSERV QUIET ADD list name user@node firstname lastname In order to unsubscribe all users from a local list with no notification, type: TELL LISTSERV QUIET DELETE listname *@* 4.3 Unsubscribing a user from all BITNET lists When a node or user has disappeared, and you wish to unsubscribe a user or set of users from all LISTSERV lists across BITNET, the BITNET node administrator (the person listed in the nodes file as :useradm) should submit a command job by sending mail to LISTSERV with the message text (remember that the subject line is ignored): //USUB JOB DELETE * DD=names (NETWIDE //names DD * user1@node user2@node ... /* Note that LISTEARN, the EARN network's version of LISTSERV, does not support wildcards in name specifications * (as in *@node). 4.4 Deleting Lists When you are ready to delete a list, both the List Owner and the LISTSERV Postmaster have responsibilities. List Owners should: 1. make the decision to delete the list 2. inform any existing subscribers of the situation, 3. archive any material they wish to keep (files and logs - see below) 4. Notify the LISTSERV Postmaster and/or the system administrator The LISTSERV Postmaster will then: 1. Erase the list by typing: TELL LISTSERV CMS ERASE listname LIST 2. Have the system administrator delete the user ID for the list. 3. Erase the associated files (archives, cache, FILELIST, etc.) by typing: TELL LISTSERV CMS ERASE filename filetype for each file. 4. If you had a dedicated minidisk for the list archives, you may want to remove that minidisk from the LOCAL SYSVARS "mdisk" list and remove it from LISTSERV. Check with your systems administrator. 1 5 Setting up New Lists 5.1 Introduction Before you add new lists or new files to your LISTSERV, it would be wise to familiarize yourself with the way disks are allocated for LISTSERV. On all LISTSERV's the A disk contains the LISTSERV system files. LISTSERV notebook archives (See Section 5.5 List Keyword Defaults), and data files indexed in FILELISTs (See Section 14 File Server Functions) should not be stored on the A disk because it could fill up unexpectedly causing bad things to happen to LISTSERV (see Section 11.1 Are one or more lists not sending mail?). There is some basic information on how LISTSERV uses its disks in the LISTSERV SYSVARS A disk file (which you should not edit - local changes should go in LOCAL SYSVARS A). Another consideration if the LISTSERV node is connected to the Internet, is whether you want to allow anonymous ftp to a LISTSERV disk. If you are going to allow anonymous users to access a disk, you will be unable to control by file what data they can access. Therefore you must separate public files from private files by disk. Don't use filemodes C or D; LISTSERV's C disk is reserved for future use and LISTSERV's D disk is a work disk which is automatically erased periodically. There is a helpful discussion of how to allocate disks for LISTSERV in Ben Chi's FSV GUIDE available from LISTSERV@ALBANY and LISTSERV@BITNIC. 5.2 The Cookie Cutter Method Many novices and experts alike use what's called the cookie cutter method to copy an existing template (i.e. a currently used list) to set up new lists. If you are positive that a list you want to create should be pretty identical to an existing list, by all means copy it. However, the difference between novices and experts is that the experts know what the list settings mean. Be sure to check the settings and familiarize yourself with them (see Section 5.5 List Keyword Defaults). Here's the "cookie cutter" method: 1. Get a copy of the list you want to imitate by typing: TELL LISTSERV REVIEW similarlist 2. Edit the file to reflect the desired subscriptions, list description and any list keywords, i.e. list password. 3. Save your file as the new listname "newlistname LIST A". Consult the list of list (see Section 3.2 Directory of LISTSERV lists) to find a unique name if your list will be public. Also consult your LISTSERV Postmaster to choose a unique name if the list will be private and check with your System Administrator to make sure that you can use this name as a user ID. 4. Consult your LISTSERV POSTMASTER or System Administrator to create a new ID for your list. 5. Have your LISTSERV POSTMASTER submit your new list to LISTSERV by using the LSVPUT command. (4) LSVPUT newlistname LIST A (CREATE You should be prompted for the password for the list - use the one that is stored in the keywords of the list. You may need the assistance of the LISTSERV POSTMASTER (see above - Privileges) if you do not have the privileges to create a new list. LSVPUT may also ask if you want to record your password to disk. If you select yes, the password for your list will be stored in GLOBALV LASTING A. You will get a message announcing that newlistname was successfully started. Don't forget to TELL LISTSERV REV newlistname to check it. 1 6. After your list is created and tested, if it is a public list, check Section 3.5 New List Announcements to find out how to announce your list's availability on the network. If you are not managing the list from the machine where LISTSERV resides, instead of LSVPUT, send a message containing your list to LISTSERV@listnode with the message text before the actual keywords: PUT listname LIST PW=list_password 5.3 Modifying the configuration (keyword headers) of lists If you want to modify the way an existing list works, you must gain a deeper understanding of the list header or keywords from which you may choose. First you must obtain a copy of the list keyword headers: TELL LISTSERV GET listname (HEADER Note that this does not work for LISTEARN (EARN's version of LISTSERV). In that case you will have to get the whole file by omiting (HEADER (HEADER delivers only the headers of the file, not the subscription list and continues to process messages to the list under the old header (keyword) settings. The list will then be locked which means that no administrative maintenance (i.e. adding or deleting subscriptions, changing options) can be performed. If you decide instead, to abandon the changes, be sure to unlock the mailing list by issuing the command: TELL LISTSERV UNLOCK listname The request to unlock will be confirmed by a response. See the next section, 5.5 List Keyword Defaults, for information about the keywords you may modify or add to the header. When you have finished editing the header file, save it and update LISTSERV by typing: LSVPUT listname LIST A (PUT NEWPW You will be prompted for the password (see Section 5.6 List-Keyword Recommendations) for the list. 5.4 Adding a group of users to a closed list If you own a closed list and you want to add a group of users, instead of interactively typing each name in a mail message or in the TELL command, you may use the method above, omitting (HEADER and editing the subscriber list directly. However, the subscribers you add will not be notified of their subscription automatically. You should also avoid duplicating lines in this file because the user options are stored in colums 81-100 and can easily be overlooked (see Section 6 Individual List Subscriber Option Flags). 1 5.5 List Keyword Defaults The file, LISTKEYW MEMO (available from any LISTSERV) describes the list header keywords and their default settings. This is required reading for someone interpreting a current lists keywords (especially when you are copying an existing list). Below is a quick reference of the default settings, but these are not always recommended (see list keyword suggestions below): ACK= YES * Acknowledgement messages will be sent to list senders when a message from their ID has been successfully sent to the list. CONFIDENTIAL= NO * The list will be included in the LISTSERV list of all lists generated by the LIST GLOBAL command. ERRORS-TO= POSTMASTER * LISTSERV errors are sent only the the LISTSERV Postmaster. FILES= YES * Files can be sent to the list FORMCHECK= NO * Files to be sent to the list do not have a FORM of REDIST to be accepted. LANGUAGE= ENGLISH * LISTSERV generated mail and messages to the list subscribers will be provided in English. MAIL-VIA= DIRECT * List mail is processed on the LISTSERV node and sent directly to each user. NOTEBOOK= NO,A,SINGLE,PRIVATE * An automatic log or list archive is NOt kept on LISTSERV's A disk, putting every message in a SINGLE notebook accessible only to the members of the list. Of course, every setting after NO is meaningless since you aren't keeping a NOTEBOOK. However if you change this, read Section 5.1 Introduction to find out why it is a bad idea to store NOTEBOOK archives on LISTSERV's A disk. NOTIFY= YES * the list owner receives notifications of new subscriptions and deletions. REPLY-TO= LIST,RESPECT * when a user replies to a message from the list, the reply will be sent to the list, unless the sender specifies a different Reply-to mail header in which case the original Reply-to header is kept intact. REVIEW= PUBLIC * anyone can review the list of subscribers. SEND= PUBLIC * anyone can send mail (and if FILES= YES, files) to the list. STATS= NORMAL,PRIVATE * Elementary statistics on number of mailings, etc. are stored (as listname STATS) for access by the members of the list only. VALIDATE= STORE ONLY * a password is not required for users to unsubscribe from the list. X-TAGS= YES * Include X-To: and X-cc headers in the list mail (these are not required BITNET mail headers). WARNING: There must be *no* spaces between commas separating multiple options of a single keyword (i.e. REPLY-TO=LIST,RESPECT). Required keywords for which there is no default: OWNER= USER@NODE * This is the List Owner. SUBSCRIPTION= OPEN, BY_OWNER, or CLOSED * Whether subscription is by the user (anybody), subscription is closed but requests to subscribe are automatically forwarded to the list owner, or subscription is by the owner only and all requests to subscribe are ignored. 1 5.6 List-Keyword Recommendations Unless otherwise specified, the following recommendations apply to all kinds of lists including Peered and Edited (see Section 7 Edited Lists and Section 9 Large Lists and Peering for more information). PW= Be sure to assign Passwords to all your lists. If you aren't already aware, it is fairly easy to forge mail (set the from address to a list owner) and therefore change the keywords (behavior) of a list. To be completely secure, use the VALIDATE= ALL COMMANDS keyword. The VALIDATE= STORE ONLY checks the password only when you are PUTing the list on LISTSERV (See Section 5.2 The Cookie Cutter Method for more information). To use the password for commands such as DEL indicate it after the command: TELL LISTSERV DEL listname user@node PW=password WARNING: Unfortunately, VALIDATE=ALL COMMANDS prevents remote users from signing off a list. If, on the other hand, you want to restrict who can sign up for a list, yet allow users to unsubscribe, use VALIDATE= STORE ONLY in conjunction with SUBSCRIPTION= BY_OWNER. ERRORS-TO= OWNER Many LISTSERV POSTMASTERS may appreciate your taking responsibility for handling bounced mail and other errors on your list. FILES=NO This will prevent senders from distributing Trojan horse programs, such as CHRISTMA EXEC to list subscribers. The disadvantages are two: sites without mail software will not be able to send to your list using SENDFILE utilities (there are BITNET sites without mail software), and files you want to distribute to the list (i.e. object code) must either be embedded in a mail message or be made available via the File Serving utilities mentioned in Section 14 File Server Functions. FORMCHECK= REDIST This would be used in conjunction with FILES=YES (not recommended) which is the default. If you do allow files in the list, you can require that the user set the file form to be REDIST: CP SP D FORM REDIST (in the VM/CMS environment) before it is sent to the list . This is provided as an intermediate step between FILES=YES and FILES=NO to prevent broken mail software from submitting files to the list unless they are intentionally modified in this way. 1 MAIL-VIA= DIST There are only two values: DIST and DIRECT. You may see DIST, DIST1 and DIST2 but they are all the same as DIST. The DIST setting sends mail along the LISTSERV backbone, with the DIST2 protocol to be dropped off along the way (5). The DIRECT setting sends mail directly to each destination site. DIST is almost always much more efficient for lists with significant numbers of non-local subscribers. NOTEBOOK= YES,X,MONTHLY,PRIVATE If you don't need a log of all messages, don't set one up needlessly. However, if you do want to log your traffic, be sure to get permission from the POSTMASTER or System Administrator and fill in the X with the LISTSERV filemode s/he wants you to use. See LISTKEYW MEMO for more information on intervals and privileges. For CONFIDENTIAL=NO lists, it is recommended that you define a service area for your list and use the keyword settings: CONFIDENTIAL= SERVICE REVIEW= SERVICE SEND= SERVICE NOTEBOOK= ...,SERVICE This will help to cut down on the listings in the BITNET list of lists. Here are the two keywords that limit the service areas. LOCAL= (default is the same as the LOCAL variable in the LOCAL SYSVARS file) The LOCAL keyword allows more than one node to be considered LOCAL for the purposes of the SERVICE tag (see immediately below). SERVICE= (area1),(area2)... This keyword indicates the area outside of which subscription requests must not be accepted. Valid values for this keyword include LOCAL (see above keyword), any BITNET node name or Internet host name, or the name of any country or network. You can use a NOT or a minus sign (-) in front of a keyword to indicate sites which should be excluded. 5.7 Keyword Options for Small Lists If you are running a small list and want to notify all list users when someone makes a subscription, use the keyword NOTIFY= listname@node If you only want to have one address on the To: mail header, instead of the list name, use MAIL-VIA= DIRECT and set LOCAL= all the recipient nodes. Because of the difficulty in maintaining this, this setting is not useful for SUBSCRIPTION=OPEN lists. 5.8 Formatting REVIEW output INDENT= (default value 40) This keyword controls number of columns allowed for list addresses in the response to the REVIEW command. 1 5.9 Aliasing List Names LIST-ID= (default value user ID of list) This allows users to refer to a list with a name other than the real name of the list. This is useful for peered or gated lists with names larger than eight characters (see Section 9 Large Lists and Peering and Section 13 List gateways to Usenet Newsgroups for more information). 5.10 System Tuning LOOPCHECK= (default value FULL) This controls which of the loop-detecting heuristics are used for this list. The important ones are FULL and NONE. Send mail to LSTSRV-L@UGA for more information and do not use this unless you have a thorough understanding of what you are doing. PRIME= (default value YES) This controls whether mail for the list is processed during "prime time" (which is initially defined in LISTSERV SYSVARS, but can be modified in LOCAL SYSVARS) or waits for "non-prime time". This can be useful for controlling the load placed on your system by LISTSERV's handling of the list during periods of heavy local use. Also useful for large lists (see Section 9 Large Lists and Peering for more information). SENDER= (default value LIST) "This controls what value (if any) is placed in the Sender: header field of messages from the list. This is one of the most controversial 'knobs' in LISTSERV. If you leave it at the default value LIST, error messages will be sent back to the list (by properly operating mail systems). Usually, LISTSERV's heuristics will catch the messages and send them to the ERRORS-TO= address(es) for the list. Unfortunately, due to the endless inventiveness of mail system authors, some error messages may be missed by the heuristics and sent back to the list, including the address which caused the error, thereby causing another error, another missed error message to the list, and a mailing loop which is visible to every subscriber. When that happens, the Internet purists point out that the rules say that Sender: should always point to a human who can fix the problem, not to an automated process like a list. On the other hand, if you set SENDER= (and thus Sender:) to some other value, you will alienate the many users of Rice MAIL/MAILBOOK (and quite probably other mail reading systems) who may be relying on Sender: to determine which list sent the mail (and perhaps where to save it)". (6) Common practice within the BITNET community is to use the default, sinc there is not yet an accepted alternative for indicating the list which is sending the mail. For small, closed lists you can use the suggestion in Section 5.7 Keyword Options for Small Lists to limit the Sender mail header. 1 5.11 Maintenance Updates LISTSERV fixes which have been applied are listed on LISTSERV's 191 disk in the file: LFIX LOG For more information on the LFIX procedure and a list of fixes for your current release, type: TELL LISTSERV AT SEARN GET LFIX MEMO TELL LISTSERV AT SEARN GET Vnnn FIXLIST (i.e. for LISTSERV Version 1.7a use GET V17A FIXLIST). The GET Vnnn FIXLIST will subscribe you to future additions of the file. LFIX MEMO will include more information on actually obtaining and installing the fixes. Even seemingly minor fixes may make a big difference in how well your local LISTSERV runs. You may also check to see which fixes are installed on remote LISTSERVs by typing: TELL LISTSERV AT hostnode SHOW FIXES 5.12 Maximum size of a message to a list If users receive notification that their message was too large to be sent to a list, you may want to examine the SIZELIM variable to evaluate whether it is adequate for users on your LISTSERV. In the interests of network resource economy, you should first evaluate the user's need to send a large file and suggest sending the file in two parts if sending a large file is only an occasional requirement. SIZELIM= (default value taken from LOCAL SYSVARS variable MAILMAXL) This keyword controls the maximum number of lines for an incoming mail message to the list. You can raise it above MAILMAXL, but it cannot exceed the LOCAL SYSVARS variable FILEMAXL. If this is a PEERED LIST, make sure that you check with the PEERs' POSTMASTERS before changing this. 5.13 Daily Maximum number of messages DAILY-THRESHOLD= (default value 50) This tag sets a limit on the number of messages that may be sent to each list during a single day (by all users combined). It can be useful if a list gets into a loop, or just to cut down on the volume of messages. When that limit is reached, the list goes on HOLD (stops sending mail). See Section 11.1 Are one or more lists not sending mail? for more information on HOLD. 5.14 Suppressing Subscription/Unsubscription Announcements To make sure the owners don't receive all the routing subscription and unsubscription announcements, add NOTIFY= NO 1 6 Individual List Subscriber Option Flags The following section (up to Section 7 Edited Lists) is internal documentation that is subject to change in future LISTSERV releases and contains information about the internal characteristics of how LISTSERV lists work. Caveat emptor. Flags are settings that apply to specific users on a list and can be altered by the user, usually even if VALIDATE= ALL COMMANDS (since these settings do not alter the behavior of the entire list). You may include a default setting for users on a list, by adding to the header of a list the keyword: DEFAULT-OPTIONS= option1,option2,... For Example: DEFAULT-OPTIONS= REPRO,NOFILES If you add this header to an existing list, the current subscribers will be assigned a setting automatically. The list owner should judge how to handle the existing subscriptions. For example, the list owner could announce the addition of the default option to the list and tell subscribers how to set it: TELL LISTSERV SET listname option On the other hand, if the list subscribers would prefer to have all existing subscribers get the new option setting, the list owner can set the options of users already subscribed by typing: If you add this header to an existing list you can set the options of users already subscribed (using the wildcard *@*) by typing: TELL LISTSERV QUIET SET listname option FOR *@* These options are stored in columns 81-100 after the user's name in either the file "listname LIST" or the file "listname OLDLIST" where listname is the name of the list. You will only see them when you do a GET as is described in Section 5.4 Adding a group of users to a closed list Here is a full list of flags with their column numbers and what they mean. The default setting (even without Default-options) is listed first. 6.1 Tired of /Want more Extra Messages from LISTSERV? Column 81 ACK (A), NOACK (a), MSGACK (M) These settings control whether users receive interactive acknowledgement (A), no acknowledgement (a) or a mail message acknowledgement (M) when mail from their user ID has been successfully sent to the list. By providing an option flag, subscribers can override the list keyword setting. People who don't set this option, will have mail acknowledgement default to the ACK= list keyword setting. 6.2 Going on vacation? Column 82 MAIL (M), NOMAIL (m) To temporarily stop mail from a mailing list from filling up your spool, set the NOMAIL option, or for all lists, send to each LISTSERV node (listnode): TELL LISTSERV AT listnode SET * NOMAIL Don't forget to turn it back on when you return by typing: TELL LISTSERV AT listnode SET listname (or *) MAIL 1 6.3 Want to restrict a user from sending files to a list? Column 83 FILES (F), NOFILES (f) This is similar to MAIL/NOMAIL, but for files. See Section 5.6 List- Keyword Recommendations under FILES= for more information on the issue of whether to allow files to be sent to a list. 6.4 Want to get a copy of your mail to a list? Column 84 NOREPRO ( ), REPRO (R) By default LISTSERV does not send a copy of mail to a list to its sender, even if the sender is subscribed to the list. To change this default, SET listname REPRO or for all users on a list, TELL LISTSERV AT listnode SET listname REPRO FOR *@* 6.5 Suppressing the names on mail from LISTSERV Column 85 SHORTHDR(), FULLHDR(F), FULLBSMTP(S), SHORTBSMTP(s), IETFHDR(I) This option controls what the header on your mail messages will look like. There are three types of headers: 1. Short header, with a minimum number of fields. This is the default and the most compact. Depending on the mail delivery software, use either SHORTHDR or SHORTBSMTP. 2. Full header with a number of other fields, plus any header field unknown to LISTSERV. Depending on the mail delivery software use either FULLHDR or FULLBSMTP. 3. IETF headers - specified by the Internet Engineering Task Force in RFC1211 and RFC1123. Use IETFHDR (new in LISTSERV 1.7b). Consult the code or send a message to LSTSRV-L@UGA for more information. To make LISTSERV mail look like mail is coming from the list, SET listname SHORTBSMTP FOR *@* 6.6 How does LISTSERV track subscriptions? Columns 86-87 subscription year (yy) or deletion year (yy) What determines whether it is subscription or deletion year Columns 88-90 subscription day (ddd) or deletion day (ddd) This is what day of the year (1-366) that the user subscribed. Column 91 normal ( ), deletion pending (D), confirmation waived (W) Confirmation is waived by SET listname NORENEW These three option flags work in the following manner: When a user subscribes to a list, columns 86-90 are set to the subscription date and column 91 is set to normal( ) or the default (DEFAULT-OPTION= NORENEW). When a user subscribes to a list that includes the RENEWAL= keyword (see Subscription Renewal below), the date in columns 86-90 is set to the subscription or confirmation date. When the list is up for renewal, columns 86-90 are checked against the current date less the renewal period. If it finds a subscription that will expire soon, it sends a warning (see Subscription Renewal below), sets 86-90 to the date at which the subscription will be deleted (if not confirmed) and sets column 91 to D. If the user sends back a confirm, 91 is set to blank and 86-90 is set to the date of the confirmation. 1 6.7 Want an unlisted address? Column 92 NOCONCEAL ( ), CONCEAL (C) This option flag will conceal your subscription address when the list is REVEWed (see above). 7 Edited Lists Lists can be set up so that all mail is sent first to a person, called the list editor. That person could summarize, spell-check, proofread, etc. items before they are distributed across the network. No one except the editor would send mail directly to the list members. This facility is useful for electronic journals, digests, newsletters and moderated discussions. To set up an edited list, use the list keyword EDITOR= (net- address1),(net-address2).... and the SEND= EDITOR. All mail sent to the list will then be automatically forwarded to the first person listed in the EDITOR keyword list. Only the editors (not the owners) are allowed to mail directly to the list subscribers. Any editor can send to the list, but only the first listed editor will receive submissions. Editors receive submissions in mail messages. Make sure the Editor address is NOT a file server, list server, mailer,etc. - that may result in a mailing loop. If you need more than one editor to receive all submissions, you may create a separate (non-edited) list with just the editors subscribed. then you can use this small list, editlist in the EDITOR keyword of the edited list as follows: EDITOR=editlist,(editlist) You may also use the keyword: EDITOR-HEADER= (default value YES) to control whether mail sent to the editor includes some explanatory prose preceding the message. This preface includes the ID of the original sender and notifies the editor that s/he can forward the submission to the list and the preface will automatically be removed. If the list is merely moderated, you probably want this heading prose. If it is digested, you probably don't. Another suggestion for Edited lists is to log all requests for subscriptions. If you don't do Subscription Renewal (see Section 8 Subscription Renewal), or don't care to keep track of the subscription flags above, this can be an easy way to cut down on bounced mail and subscription patterns. (7) 1 8 Subscription Renewal (the RENEWAL= list header) You can set up a list so that the subscriptions will be regularly expired and renewed. The renewal keyword is in the form: RENEWAL= NONE | item1<,item2<,...>> where an item can be: a) an interval: MONTHLY, YEARLY, WEEKLY, BI-MONTHLY,BI-YEARLY, BI- WEEKLY, or another numeric division such as 3-MONTHLY (every 3 months - quarterly). b) an absolute date yy/mm/dd (once on this day), mm/dd (every year on this day), dd (every month on this day) c) the delay: DELAY(n) in days between when users are asked to confirm their subscription and when the user is removed from the list. The default is 7 days Where there is more than one interval specified (i.e. the default) the smallest one is used. For each user and list, the date of the last subscription/change in the subscription (SET) is kept (for more information see Section 6.6 How does LISTSERV track subscriptions?). An internal LISTSERV procedure, LSVEXPIR, will check all these values once a week against the RENEWAL= keyword in the list headers. (8) When the user's subscription is up for renewal, a message is sent (this is customizable - see Section 12 Customized List Messages - Mailforms) to ask them to send a message: CONFIRM listname or they will be removed from the list after the delay period. The list owner is also sent mail telling them when users are asked to confirm and when they are removed. The date before the subscriber is removed from the list also depends on when the LSVEXPIR procedure runs to actually removes the subscriber. A common problem with subscription renewal is that some lists subscribers have a different FROM address than their list subscription due to aliases, redistribution of the list (see Section 13 List Gateways to Usenet below) or other system settings. A list owner can confirm a subscription for a user, but I recommend asking the user resubscribed to keep the most up-to-date addresses for list subscribers, especially if the list is open. In the case of redistribution, you should waive list renewal for redistlist@node by typing: SET listname NORENEW for rdistlist@node See Section 6.6 How does LISTSERV track subscriptions? for more information on NORENEW and see Section 11.6 Are you puzzled why mail is bouncing? for more information about invalid addresses. 9 Large Lists and Peering Large lists (i.e. 2000+) can be a drain on the LISTSERV node's CPU and you may need to increase virtual storage to improve performance. You can also alleviate some of the strain, by using the MAIL-VIA: DIST and considering using Peered lists which break large LISTSERV lists into smaller distributed ones (geographically located at other LISTSERV sites). 1 To set up a peered list, consult the instructions in LISTOWN MEMO. You must coordinate with the LISTSERV sites where your list will be Peered to set up lists with similar keywords. It is strongly recommended, but not required, that these lists have identical names and passwords. To find LISTSERV sites to peer your list, send a message asking for volunteers to your list, LSTSRV-L@UGA, and/or the POSTMASTER at a LISTSERV site found in LISTSERV SITES (available from LISTSERV@BITNIC). You will be adding a list keyword PEERS=(peer1),(peer2)... . If you are splitting an existing list, you will be using the MOVE command to move your users from one peer (your original node) to another interactively or by mail. A lot of Peered lists are set up so that the keywords reside in a separate file (named listname KEYWORDS) from the list subscriptions, list name header and password keyword PW=. To direct LISTSERV to the listname KEYWORDS file, the listname LIST must have a keyword named .IK (insert keywords). The listname KEYWORDS file can also reference another keyword file with the keyword .IK filename (insert the file named filename KEYWORDS) and so on. Some lists include a topology (listname TOPOLOGY) file by means of a keyword named .IT filename. In order to update keywords, you may have to GET and PUT the listname KEYWORDS file instead of the listname LIST file (or the appropriate keywords or topology file). Also, when you GET a peered list, the remote peered list are returned to you as LISTNAME HOSTNODE instead of as LISTNAME LIST. Most peered lists need different keyword files because of different settings such as what disk the NOTEBOOK is stored on (see Section 5.6 List-Keyword Recommendations under NOTEBOOK=). If you use the .IK method and have a peered filelist (see instructions in Section 14.5 Peered FILELISTs), when a list owner changes the keywords of a peered list (by changing his/her local copy only), the changes will be propagated out automatically after the local copy is updated. However changes must be made by the list owner. The LISTSERV POSTMASTER is not authorized to change the offsite peers. You may want to use the keyword LIST-ID= (default value user ID of list) when setting up Peered lists especially when they are gated (See List Gateways below). This allows users to refer to a list with a name other than the real name of the list. This is useful for peered or gated lists with names larger than eight characters (see Large Lists - Peered Lists and List Gateways topics below). For example, there is a group of peer lists redistributing the Internet list Info-IBMPC. Most of the peer lists are named IBMPC-L, but the peer is named $$INFOPC (for historical reasons). All carry the List-ID INFO-IBMPC, so a potential subscriber may send SIGNUP INFO-IBMPC to any LISTSERV and have the request sent to the appropriate LISTSERV even though a list literally named INFO-IBMPC could not exist on any VM/CMS system (since it's over 8 characters).(9) Large lists may also have trouble if they have both keywords SUBSCRIPTION= OPEN and NOTIFY=YES. Since LISTSERV may get tied up while users unsubscribe, if you want the owner to be notified, consider setting SUBSCRIPTION= BY_OWNER. Also, consider using the PRIME= NO option to process list requests at off hours. See Section 5.6 List- Keyword Recommendations for more information on PRIME. 1 10 Archives (List Notebooks or Logs) The NOTEBOOK= YES keyword creates a file of all messages sent to the list. However, if the POSTMASTER moves or changes the name of a list, here are some things to watch out for: If you have to change the names of archives that are sequentially numbered, make sure to do a TELL LISTSERV DATABASE REFRESH listname When you are rebuilding/renaming archive files, don't forget to delete the associated DBINDEX and DBNAMES files to regenerate the lists for the index and automatic numbering commands by typing: TELL LISTSERV CMS ERASE listname DBINDEX filemode TELL LISTSERV CMS ERASE listname DBNAMES filemode If you want to set up the Notebook files based on volume number and year (like a newsletter), you must edit the listname COUNTER file to restart numbering at the beginning of each year. To move archives from one list to another, rename the files and use XEDIT to c/oldname@jhuvm/newname@jhuvm The DBINDEX and DBNAMES files should be erased. Only rename the archive files and the COUNTER file if you use a separate file per posting (NOTEBOOK=SEPARATE). 11 Troubleshooting - Miscellaneous problems 11.1 Are one or more lists not sending mail? Check to make sure that LISTSERV is disconnected (NOT not logged in) by typing Q LISTSERV. If one of your LISTSERV disks fill up, lists which are active go into a hold state and postpone all new mail. When your POSTMASTER or System Administrator has cleaned up the disk or enlarged it you must specifically take the list out of the hold state by typing: TELL LISTSERV FREE listname To find out what lists are held, TELL LISTSERV LIST and look for the line "* Note: This list is on hold" immediately following any held lists. See Section 5.13 Daily Maximum number of messages for information on other list limitations. POSTMASTERS may be interested in the LISTSERV Line Monitor described in LMONUSER MEMO available from LISTSERV@SEARN (you must be a registered LISTSERV contact to request it). The line monitor can help you manage your spool area, control your BITNET lines and keep statistics. 1 11.2 Are you getting no LISTSERV response? If you make more than 10 errors consecutively, LISTSERV will disable your ID by suspending LISTSERV services from you ("served off"). LISTSERV will send you a message informing you of your predicament and how to resolve it, but if you miss the information, here's how to get out of your state. Simply have another user type: TELL LISTSERV SERVE yourid The person doesn't even need to be the POSTMASTER. This feature of LISTSERV is important for non-human generated errors so don't take it personally if you get served off. 11.3 Is LISTSERV misplacing your PUT's? If you find that your PUT requests result in the files being sent to your reader, your LASTING GLOBALV may have been corrupted. Try using using the option TO in LSVPUT such as: LSVPUT listname FILELIST A (PUT TO listnode Please contact your system administrator or look in LSVPUT EXEC for more info. 11.4 Are your requests to DELETE a file from a file list result in requests getting forwarded to some LISTSERV POSTMASTER? You may have a problem with the FILEID for that file (see Section 14 File Server Functions). The LISTSERV POSTMASTER should identify the disk mode where the file is stored (for instance, monitor the LISTSERV console and send a TELL LISTSERV CMS LISTF filename filetype *) to it. Then you can identify the disk in a TELL LISTSERV CMS ERASE filename filetype filemode. 11.5 Are you running up against the 256K daily limit on getting files from LISTSERV? The LISTSERV POSTMASTER can add you to the GETQWAIVE variable in the LOCAL SYSVARS file (or create the variable if it doesn't exist yet). Alternatively, the postmaster can write some REXX code into the LSV$GETQ exit to bypass the limit for log files for list owners. 11.6 Are you puzzled why mail is bouncing? Here is why some list addresses bounce: 1) Someone has moved from the address to which they were subscribed on the list, but friendly systems folks made the old address work anyway. Now someone is doing some housecleaning and deleted the old alias. The subscriber has been receiving the mail fine, not knowing there was a problem and if you summarily delete them, they might well be upset. 2) There is a software problem at the receiving site (or a gateway servicing that site). The problem is likely to be solved in the next couple of days - especially if you let someone know about the problem. 1 3) There is software at the subscriber's site which is refusing to deliver the mail because disk space has been exceeded or some other such temporary problem. The easiest thing for a list owner to do is to delete a subscriber as soon as mail to them is bounced. This may or may not be appropriate depending on your judgement on what level of service you can/want to provide for the list. There may be a significant investment of time needed to figure out why the mail bounced and there are not any good tools to make it easy to do a good job. (10) 11.7 Need to get rid of mail that violates BITNET usage rules (i.e. broadcast messages or files)? To see what LISTSERV jobs are waiting to be processed POSTMASTERS or users with the correct privileges (see your System Administrator) can type: Q RDR LISTSERV ALL To remove bogos jobs from the LISTSERV Reader, the POSTMASTER should 1) get the job number by typing: Q RDR LISTSERV ALL 2) Check the file by typing CP TRAN LISTSERV RDR #### * PEEK #### 3) If it is not the file you want to get rid of, return it to LISTSERV by typing: CP TRAN RDR #### LISTSERV and then get rid of the file from the POSTMASTER's reader (user ID) PURGE RDR #### 12 Customized List Messages - Mailforms You can customize (by list) the messages that LISTSERV sends to users upon completion of a command. You will be working with a LISTSERV file called $DEFAULT MAILFORM. 1. To create a mailform, get a copy of $DEFAULT MAILFORM for the templates to see what the default messages are. Copy the form/s you want to customize for a list and put them in a file named listname MAILFORM (i.e. :ADD and :SIGNUP for subscriptions). The forms you don't customize will be taken from the $DEFAULT MAILFORM file. 2. Create the information you want to send out in the listname MAILFORM file. Keep in mind that LISTSERV will try to concatenate consecutive lines as long as they start from the first column. You can get around this by using .FO OFF (to turn off formatting) at the beginning of a block of text you don't want formatted and then .FO ON to turn it back on. 3. The text after the :formtag (i.e. :ADD :SIGNUP) is automatically enclosed in the subject line. You may customize this to your satisfaction. 4. If you have text to go in multiple forms, create a dummy form (i.e. :$SIGNUP) and use the .IM command (i.e. .IM $SIGNUP) to enclose the text in the multiple mailforms. 1 5. Make sure that no lines begin with . (you can move it to the second column if you really need to use a period). 6. Don't use single quotes. Double quotes are okay. If you really need single quotes, use them back-to-back. Single quotes in MAILFORM files are used to enclose expressions (i.e. variables or function calls) which are evaluated at the time the mailform is used. 7. In order to put your mailform on LISTSERV's A disk, the LISTSERV postmaster must use the PUTC command. For example, LSVPUT listname MAILFORM A (PUTC 13 List gateways to Usenet Newsgroups There is a list of LISTSERV lists that are gated to Usenet Newsgroups available from American University. To get it type: TELL LISTSERV AT AUVM GET NETGATE GATELIST You should also GET NETGATE POLICY for an introduction to lists, Newsgroups and how gateways are established. You can also obtain information about the gateway software by typing: TELL LISTSERV AT PSUVM GET NETNEWS PACKAGE If your list is gated, you may want to set the name of the list which will be used by Usenet using the keyword NEWSGROUPS= (default value bit.LISTSERV.userid of list). There is some information about other links to LISTSERV in the file LISTLINK MEMO available from any LISTSERV. 14 File Server Functions LISTSERV provides features to store and distribute files in conjunction with, or independently of the list management features. The LISTSERV file server functions was designed based on those of NETSERV, which is a package that is used to distribute BITNET network routing information each month. (11) On LISTSERV, files are organized in groups by topics or lists called FILELISTs. The index to all FILELISTs is the LISTSERV FILELIST. The FILELISTs have a special syntax which include whether a file is a FILELIST (/F/), File Access Codes (FAC's) that control who can modify FILELISTs and files, and updated information on the format, description and modify time for each file. Get LISTSERV's LISTFILE MEMO for a complete description. Also, be aware that LISTSERV does not necessarily use the filename listed in the FILELIST to store it on LISTSERV's disks. There is a special file associated with each FILELIST with the same filename as the FILELIST and the filetype FILEID (i.e. LISTSERV FILEID) that contains LISTSERV's internal name for the file. This file should not normally be modified. 1 14.1 Obtaining files from the LISTSERV File Servers LISTSERV stores files the same way it stores list archives and the help files. If you want to obtain the LISTSERV FILELIST, you can get it interactively (or by mail - see Section 2.2 Issuing LISTSERV Commands): TELL LISTSERV GET LISTSERV FILELIST 14.2 Adding files to an Existing FILELIST Before you add new files to your LISTSERV, please familiarize yourself with the disk allocation of your LISTSERV files. See the note above in Section 5 Setting up New Lists for a description of special considerations. As a LISTSERV maintainer or owner of a FILELIST, please note the PUT File Access Code (FAC) on the FILELISTs in LISTSERV FILELIST. Do not modify the CONTROL, INFO or TOOLS FILELISTs because they are updated by the LISTSERV Master Coordinator (FAC=LMC), Eric Thomas. For information on adding your own FACs, see the discussion in LSV GUIDE 1. Get a copy of the FILELIST (i.e. netinfo) to which you wish to add the new file in order to create an entry for the new file (see step 6 for information on updating a list or FILELIST by mail): TELL LISTSERV GET netinfo FILELIST (CTL When you obtain this file, the FILELIST will go into a locked state. This behaves similarly to a GET request for a mailing list (see Section 5.3 Modifying the configuration (keyword headers) of lists). 2. When you edit the copy of the FILELIST, note whether it has been organized by a table of contents or includes sub-FILELISTs (by using /F/ in the first column) and choose the appropriate place to add your new file. 3. If you want to copy the line preceding the place where you want to insert the entry of the newfile (in XEDIT use " in the prefix area), make sure you change the filename, filetype, GET and PUT FAC's (check the top of the file for locally defined FAC's) and the file format. LISTSERV will automatically fill in the rest of the fields until the description if after the file format, you type five periods separated by one space each followed by the description: . . . . . This is the description of the file. Also if you will be regularly adding a file with the same filename or filetype (i.e. listname *), you may use an entry with > in the first column and the wildcard character * in the first column of the filename or filetype field. When you add the file, a new entry will be created using this line's FACs as default. 4. When you save a copy of the FILELIST on your A disk (for example), return it to LISTSERV interactively using the LSVPUT EXEC (distributed with LISTSERV): LSVPUT netinfo FILELIST a (PUT You will be prompted for the LISTSERV store password (see Section 2.1 Who has privileges?). 1 5. You will receive a confirmation message from LISTSERV that the FILELIST had been refreshed, noting that the file entry you added does not exist yet. 6. Use LSVPUT to add the new file to LISTSERV: LSVPUT filename filetype a (PUT or send it by mail by sending mail to LISTSERV@listnode with the message text: PUT filename filetype filelist "TITLE=description..." PW=password (12) When issues by mail, the PUT line MUST fit within 80 bytes (columns) of ONE record! If it doesn't you may accidentally have your password "folded" onto the next line where it is treated as part of the file and will be seen by anyone who GETs the file! On the line after this PUT command, the actual file should be included. Do not include a signature at the end because it will be interpreted as part of the file. 7.You should receive a confirmation message from LISTSERV that your file has been stored. 14.3 Deleting a file from an existing FILELIST To delete a file you can type: LSVPUT filename filetype (DELETE To delete the file by mail, send a message to LISTSERV with the following as the ONLY line in the body of the text of the mail: PUT filename filetype filelist PW=password If your system adds a blank line or anything else after the text of the mail, then this will NOT delete the file, but instead replace it with whatever is there (i.e. a blank line). You will have to GET the FILELIST (see above step 1) to remove the reference to the now-defunct file. You may have to specify an additional option (FILELIST filelistname) if there are two LISTSERV files with the same name on different FILELISTs. See the LSVPUT EXEC for details. 14.4 Creating your own FILELIST 1. Add the new name to the LISTSERV FILELIST (steps 1-5 above) to add a reference to your new FILELIST. Don't forget to precede the name with /F/ in the first column. 2. Create the new file newname FILEID (you may want to copy an existing FILEID file to make sure you have RECFM=F and LRECL=80). Edit the file so only the following line appears 1 Check FSV GUIDE for more information on allocating disks dynamically. The FILEID file is the translation between LISTSERV's internal name for the file and the name recorded on the FILELIST (see the discussion in Section 14 File Server Functions). LSVPUT newname FILEID A (PUTC 1 3. Create the newname FILELIST - as I suggested above in Section 5 Setting up New Lists, you may want to copy and edit an existing FILELIST to use as a guide. You may even use LISTSERV FILELIST. Make sure you delete all the non-comment lines and create entries only for the files you want this list to contain and that non-FILELIST files are not preceded by /F/. LSVPUT newname FILELIST A (PUT 4. LSVPUT newfile filetype A (PUT 14.5 Peered FILELISTs Just as you can make distributed mailing lists, you can also create distributed FILELISTs. Review the items in Section 9 Large Lists and Peering to get the general idea. After you have a list of the peers, include a PEERS= (peer1),(peer2)... keyword in the comments section at the top of the FILELIST. When a non-local file is PUT to the FILELIST at any of the peered sites, the file will automatically be sent to all the sites included in the PEERS= keyword. The file entries that contain local files must include the /...L/ flag in column 1. This flag indicates that this file is not available on the other peered filelists (or, if available, the contents are not the same), and PUT commands should not be redistributed to other peers. 14.6 Maximum file length If you want to alter the maximum length of a file a user may retrieve, change the variable MAXGETK in LOCAL SYSVARS. Any user is allowed to retrieve one file exceeding his/her quota on any given day, but then s/he can't order anything else that day. Other similar settings are documented in LISTSERV SYSVARS. The code is contained in LSV$GETQ EXEC. 14.7 Troubleshooting - only getting the header of your FILELIST request? If you are only receiving the header when you request a FILELIST, check the "parent" FILELIST (where the entry for the requested FILELIST is contained i.e. LISTSERV FILELIST). This message usually means that there is no file code /F/ in column one. 14.8 Packages - Sending out a group of files with one GET command Packages are special files that group a set of files in a FILELIST together (they can still be accessed individually). 1. Follow the instructions for adding files to an existing FILELIST creating entries for all the files you want to group together. Also, add an entry for the file: packname $PACKAGE where packname is the name you have chosen for the grouping. 1 2. Create a file named "packname $PACKAGE" that looks something like: * PACKNAME $PACKAGE: * Shipping list for PACKNAME package * * other comments here such as electronic mail address * * filename filetype filelist *========================== packname $package packlist utility exec packlist second exec packlist 3. LSVPUT all these files on the packlist FILELIST including packname $package. When they are available, users will be able to TELL LISTSERV GET packname PACKAGE and all files will be sent. Note that the $ is not included on the GET command. 14.9 Automatic File Subscription There are two types of functions LISTSERV offers to users who want to "subscribe" to a file so they can be notified when the copy changes and automatically be sent updates. Automatic File Distribution (AFD) automatically ships an updated file to a list of users and File Update Information (FUI) notifies a list of users when a file has been updated (but does not actually send the file). To subscribe to File Update Information for a file (i.e. FSV GUIDE available from LISTSERV@ALBANY), type: TELL LISTSERV AT albany FUI ADD fsv guide PW=newpsswd To sign up for an Automatic File Distribution: TELL LISTSERV AT albany AFD ADD fsv guide PW=newpsswd To get off either FUI or AFD, substitute the command DEL for ADD. A password may be used to secure the subscription from potential "crackers" if desired. A password can be defined for each user. LISTSERV POSTMASTERs can disable or restrict the passwords. For a user to set a password type: TELL LISTSERV AT albany PW ADD newpsswd To remove it, substitute DEL for ADD If users forget their password, the local LISTSERV POSTMASTER can find the password for them: TELL LISTSERV PWC QUERY user@usernode However, you must contact a remote LISTSERV's POSTMASTER to find a forgotten password on his/her LISTSERV. For more information on how to control password access to your LISTSERV, check LSV$PW EXEC. For more information see the LISTAFD MEMO available from any LISTSERV. 15 Searching LISTSERV Files LISTSERV provides some limited database functions for searching for a string in a specified database (i.e. list archives). To find out what databases are available on a particular LISTSERV type: TELL LISTSERV database list 1 There are two ways you can search on a database: interactively using LDBASE and by mail sending a command file. To use LDBASE, you must first GET LDBASE EXEC and GET LSVIUCV MODULE unless they are available on your local applications disk (see your systems administrator for more information). Here are two examples of a search of the string 'confirm' on the database LSTSRV-L which is located on the LISTSERV at UGA: To query a remote database (i.e. at UGA), type: LDBASE uga SEARCH 'confirm' IN LSTSRV-L SENDBACK PRINT QUIT To query as an mail command job, the following commands into a file named thisfile text a : SENDFILE thisfile text a LISTSERV AT uga //ListSrch JOB Echo=No,Reply-via=msg Database Search DD=Rules //Rules DD * SEARCH 'confirm' IN listname PRINT /* Another useful database to search is the LISTS database which contains the List of Lists. First, to find the closest LISTS database which resides on some, but not all LISTSERV backbone servers, query the local LISTSERV PEERS names file: LDBASE bitnic SEARCH ':BACKBONE.YES LISTDB(YES)' IN PEERS SENDBACK PRINT QUIT This will give you all nodes that contain the LISTS database. Choosing your nearest node, you can search the LISTS based on keywords: LDBASE RUTVM1 SELECT * in LISTS where subscription=open and title contains EDUCOM SENDBACK PRINT QUIT For more information on searching, GET LISTDB MEMO from LISTSERV. For more information on the format of an mail command job, GET LISTJOB MEM from LISTSERV. There is also a list named LDBASE-L at UKANVM concerned with searching strategies. 1 16 Acknowledgements: Many thanks to the following people without which I would still be completely in the dark: Ben Chi for writing the "File Server Bible" the LSV Guide available from LISTSERV@ALBANY Diane Kovacs for her helpful overview of list ownership for non LISTSERV guru-wannabees (Kovacs PRV2N1 available from LISTSERV@BITNIC) David@dartcms1 for the List-of-Lists Readme file. Marty Hoag for help with Internet access to LISTSERV Jim McIntosh for information about List-news gateways. Helpful members of the LSTSRV-L list for their friendly (and quick!) responses especially Herb Huston and Mark Williamson. Larry Snodgrass, my office-mate for putting up with my incessant questions. Eric Thomas for providing us with such a useful program to write about! Footnotes --------- (1) To obtain this document, send mail to LISTSERV@BITNIC with the message text (the subject line is ignored): GET BITNET INTRO. (2) Internet addresses generally look like user@host.domain.xxx and BITNET addresses look like user@nodename (or, in some cases, user@nodename.BITNET). Since LISTSERV resides on BITNET, Internet subscriptions may appear in their BITNET accessible form, i.e. user%host.domain.xxx@gatenode. In the examples, although the user names are given in BITNET format, you may substitute the "%hack" Internet addresses in the command line. Check the file BITNET GATES from LISTSERV@BITNIC to find Internet-BITNET gateways in your area. (3) Contributed by Marty Hoag (4) The LSVPUT exec is provided with the LISTSERV distribution. Contact your LISTSERV POSTMASTER if it is not available on your public disks. (5) DIST2 is implemented as a command job as described in the LISTSERV documentation LISTJOB MEMO and LISTDIST MEMO. (6) Keyword information courtesy of Mark Williamson, LSTSRV-L LOG9110 (MARK@RICEVM1.RICE.EDU) (7) Suggested by John Unsworth, PMC@NCSUVM - editor of Postmodern Culture list. (8) Eric Thomas, LSTSRV-L LOG8705 available from LISTSERV@UGA. (9) Information courtesy of Mark Williamson, LSTSRV-L LOG9110 (MARK@RICEVM1.RICE.EDU (10) From LSTSRV-L, 9 Oct 91 J. Philip Miller (phil@wubios.wustl.edu). (11) To get more information on NETSERV, first you must find which NETSERV "serves" your area: TELL NETSERV AT BITNIC QUERY SERVICE Note that, like LISTSERV you can send a mail message instead of an interactive message by sending the message text (subject line is ignored): QUERY SERVICE to the address NETSERV@BITNIC. Once you have the node MYNODE that hosts the NETSERV in your service area, you can get the helpfile by typing: TELL NETSERV AT mynode GET NETSERV HELPFILE (12) Note that without the cooperation of the list manager who can update the FILELIST to add a remote user to the FAC list and a file entry to the FILELIST, remote users cannot add files(instructions courtesy of Marty Hoag).