***************************************************** * Appendix B: List Keyword Alphabetical Reference * * for LISTSERV(tm)version 1.8b * ***************************************************** This document is available separately as reference number 9505-UD-01. It can be retrieved in plain text from any server running L-Soft's LISTSERV(tm) with the command INFO KEYwords. ******************* * The List Header * ******************* The list header contains configuration information for the list. To edit it, use the GET (HEADER command, edit the header, and send it back to LISTSERV with the PUT PW=XXXXXXXX command. For more details on this procedure, consult the List Owner's Manual for LISTSERV, version 1.8b (L-Soft document reference number 9502-UD-02). Each line of the header must begin with an asterisk ("*"). The first line of the header must contain the list title, which must fit on a single line and not exceed 40-50 characters. Succeeding lines hold list control keywords and their values. Any words in the list header followed by the "=" character are assumed to be keywords. Following the list of keywords, you may add a few lines containing a brief description of the purpose of the list. These lines must also begin with an asterisk ("*"). This document is a description of the list control keywords that appear in the header of each list. Whenever default values are supplied for the keywords, they are listed first in the description. Words in italics are "generic parameters" which define a set of possible values for a keyword operand, as described below: Generic parameters Describes an Internet address, such as JACK@XYZ.COM. Controls which category of users has access to the information or service to which this parameter applies. can be either: Public Everybody has access to the information. Postmaster Only the postmaster (i.e. LISTSERV operations staff) has access to the information. A1,A2,... with Ai being either: Private Only users subscribed to the list have access to the information. () Only the subscribers of the named list have access to the information. Owner Only the list owner can access the information. Owner() Only the owner of the named list can access the information. Service Only people in the service area of the list can see the information. Service() Only subscribers of the named list's service area can see the information. Indicates the destination of a piece of mail, message or reply. List The reply message is sent to the list. Sender The reply message is sent to the sender of the original piece of mail. Both The reply message is sent both to the list and to the original sender. None No reply message is sent at all. "address" The reply message is sent to the specified network address if enclosed in double quotes Is a time interval that indicates how frequently an operation is to be renewed. Note that depending on the operation being performed, some of the options may not be available. For example, "Notebook= Yes,A,Daily" is not available. Yearly } Monthly } Weekly } Self-explanatory Daily } Hourly } Single The operation is to be done only a single time. Is the node-id or network address of a peer list. If the name of the peer list is the same as the name of the local list (which will usually be the case), only the node name needs be given. If the list names are different, the full list network address must be given, e.g. "REXX-L@UIUCVMD". Is a means whereby a node or list of nodes can be identified. An area can be either: * The name of a network, e.g. EARN, BITNET * The name of a country, e.g. Germany, Canada * 'Local', in which case it is equated to the value of the "Local=" keyword (q.q.v.). * A node name, e.g. SEARN * A simple wildcard nodename pattern such as FR*, *11, *ESA*, D*ESA*, etc. Is a means whereby 'list monitors' can be identified (the term 'list monitor' refers to a human person who monitors the activity of a list). A 'mon-address' can be: * A single network address, e.g. INFO@TCSVM * 'Postmaster', which indicates the "main" postmaster * 'Postmasters', which indicates ALL the postmasters, main and alternate * 'Owner', which indicates the "main" list owner (the first to be listed in the "Owner=" keyword) * 'Owners', which indicates ALL list owners Some keywords can take more than one parameter. Where multiple parameters are accepted, they will be separated by a logical OR sign (|). Unless specified otherwise, commas have "higher priority" than OR signs, that is to say, "Public|Private, Open|Closed" means "(Public|Private), (Open|Closed)", not "Public|(Private,Open)|Closed". Keywords fit into several different classifications. These classifications, and the associated keywords, are as follows: Access Control Keywords ======================= Files= Determines whether non-mail files may be distributed by the list Filter= Gives list owners control over problem users and/or gateways Review= Restricts who may review the list of subscribers Send= Restricts who may send postings to the list Stats= Determines whether or not list statistics are available, and to whom Distribution Keywords ===================== Ack= Controls the level of acknowledgement messages to those posting messages Daily-Threshold= Limits the total number of messages that will be processed by the list per day before the list is held Digest= Controls the automatic digestification option Internet-Via= Determines through which gateway Internet mail will be sent Mail-Via= Determines how LISTSERV distributes list mail Newsgroups= Defines USENET newsgroups linked to the list NJE-Via= Determines through which gateway NJE mail will be sent Prime= Controls whether or not mail will be processed during "prime time" Reply-To= Sets a default for the "Reply-To:" field in the header of list mail Sender= Defines the value LISTSERV places in the "Sender:" header field of list mail Topics= Defines up to 11 sub-topics for a list Error Handling Keywords ======================= Auto-Delete= Sets parameters for the auto-deletion feature Errors-to= Determines the network address to whom mail delivery errors are directed Loopcheck= Defines the type of mailing loop checking performed by LISTSERV Safe= Determines which built-in address filter is used by LISTSERV List Maintenance and Moderation Keywords ======================================== Editor= Defines an editor or editors for moderated lists Editor-Header= Controls if an explanatory mail header is added to list messages forwarded to the list editor (if one is defined) List-Address= Determines how the list address is announced in message headers List-ID= Defines a long alias for the list Moderator= Defines the editors on moderated lists who will receive postings for approval. New-List= Sets forwarding when a list is moved to a different LISTSERV host Notebook= Controls the notebook archive for a list Notebook-Header= Determines the type of header information included in the notebook archive Notify= Defines whether or not (or to whom) subscription notification is sent Owner= Defines the owner (or owners) of the list Peers= Defines peers for the list Renewal= Controls whether or not subscription renewal is implemented, and how Sizelim= Controls the maximum size of any single message posted to the list X-Tags= Controls whether "X-to:" and "X-cc:" tags are included in list mail headers Security Keywords ================= Confidential= Determines whether or not an entry for the list appears in the List of Lists Exit= Defines a list "exit" which modifies the default behavior of LISTSERV Local= Defines which nodes are considered "local" for this list PW= Sets a password used for validation of list maintenance commands Service= Defines an area or areas outside which subscription requests are not accepted Validate= Determines whether or not list commands must be validated with a password or the "OK" mechanism Subscription Keywords ===================== Confirm-Delay= Defines a default number of hours LISTSERV holds jobs requiring confirmation Default-Options= Defines what options should be set by default for new subscribers Subscription= Defines how new subscriptions are handled, and if confirmation is required Other Keywords ============== Indent= Defines the minimum number of columns allowed for list addresses in a REVIEW Language= Defines the language in which information mail and messages are sent Long-Lines= Controls whether long-lines support is enabled Translate= Controls how LISTSERV handles control characters in list mail *************************** * Access Control Keywords * *************************** ***************** *Files=Yes | No * ***************** (NJE only; obsolete in other versions) Indicates whether NJE files can be sent to the list or not. The default value is "No". "Files= No" may prevent some non-RFC822 mailer users from posting to lists. ***************************************************************** * Filter= Only | Also | Safe,,,.... * ***************************************************************** "Filter=" is checked when a user attempts to post or subscribe to a list (but not when the list owner issues an ADD command). The first word of this keyword is either "Only", "Also" or "Safe", and it is followed by a list of patterns such as 'X400MAIL@*' or '*@*.XYZ.EDU' (without the quotes). If "Also" is specified, your filter is used in addition to the standard LISTSERV filter; this is useful to register additional looping mailers, to prevent users behind broken gateways from subscribing until the problem is addressed, or to ban anonymous posters. LISTSERV has two built-in filters: a "minimal" one, which is used for safe lists, and a "safe" one which is used for lists running with "Safe= No". That is, the unsafe lists need a safe filter to avoid mailing loops; safe lists only need the minimal filter, but can be made even safer by selecting "Filter= Safe". This, however, prevents usernames such as 'root' from posting to the list, because they are included in the safe filter. If "Filter= Only" is used, the addresses you specify are the only ones which LISTSERV prevents from posting to the list. CAUTION: You should not use this option unless you also code "Safe= Yes", and even then you will want to ask your LISTSERV maintainer for permission. This option has been added mostly for LISTSERV maintainers with very specific problems to solve. The minimal filter is very small and you should never need to override it. Messages sent to the LISTSERV userid for execution are always checked with the minimal filter, as people with userids such as 'root' would otherwise not be allowed to subscribe to lists which were set up to allow them. Note that LISTSERV extracts as many e-mail addresses as it can from the userid being checked and runs them all through the filter. For instance if your list receives mail from 'searn.sunet.se!mailer@xyz.edu', LISTSERV will check 'searn.sunet.se!mailer@xyz.edu', 'mailer@searn.sunet.se' and 'mailer@searn' (via the 'internet.' tag). ************************** * Review= * ************************** This keyword defines the categories of users who are allowed to review the Internet addresses and names of the persons subscribed to a list. The default value is "Public". *********************************** * Send= [,Confirm] * * Editor [,Hold] * *********************************** Defines the categories of users who can mail or send files to the list. Possibly puts the list under control of an editor. The default value is "Public". When the list is controlled by an editor, any file or piece of mail sent to the list is forwarded to the editor, who is the only person (with the list owner) to be able to actually mail or send files to the list. The network address of the editor is defined by the "Editor=" keyword (see below under "List Maintenance and Moderation"). When the "Hold" option is enabled (Send= Editor,Hold), the moderator(s) may approve postings using the "OK" mechanism rather than forwarding the posts back to the list. "Hold" is valid only with "Editor". ************************************************* * Stats= Normal | None, [VM only] * ************************************************* Indicates whether or not statistics are to be maintained for the list and if yes, which level of statistics is desired and who is able to retrieve the statistics reports. The default value is "Normal,Private". Normal statistics include number of mailings for each user on the list, and similar information for file distribution. ************************* * Distribution Keywords * ************************* ****************************** * Ack= Yes | Msg | No | None * ****************************** Defines the default value of the "ACK/NOACK" distribution option for the corresponding list, i.e. the value assigned to new users when they subscribe to the list. This value can be altered by subscribers ("SET" command), but not by users who are not signed on to the list. This means that this option will always be in effect when distributing mail from people who are not on the distribution list. Yes A short acknowledgment with statistical information on the mailing will be sent back to you. This is the default. Msg Messages will be sent when your mail file is being processed. Statistical information will be sent via messages, but no acknowledgment mail will be sent. [BITNET only] No For Internet users, no acknowledgement will be sent. For BITNET users, a single interactive message will be sent as the message is processed. None No messages of any kind are sent when your mail file is processed. [same as No for non-BITNET] ***************************** * Daily-Threshold= * ***************************** This keyword limits the number of postings that may be processed by the list in a 24 hour period. The default is Daily-Threshold= 50. When the keyword's value is reached, the list is automatically placed on hold, and the list owner or LISTSERV maintainer must issue the FREE command. Note that it may or may not be advisable to increase this parameter for higher-volume lists - individual list owners should study the issue carefully before increasing the daily threshold of their high-volume lists. ************************************************************************** * Digest= No * * Yes, | Same [,] [,] [,Size()] * ************************************************************************** This keyword controls the automatic digestification function allowing subscribers who do not have the time to read large numbers of messages as they arrive to subscribe to a digestified or indexed version of the list. The list owner decides whether digests are available or not, the frequency at which they are issued and the day of week or time of day when the digest should be distributed. Digests are larger messages containing all the postings made by list subscribers over a certain period of time. Unlike real-world digests, LISTSERV digests are not edited; what you see is exactly what was posted to the list. The only difference is that you get all the messages for a given day, week or month in a single batch. This is mostly useful if you are just "listening in" to the list and prefer to read the postings at your leisure. Digests are kept separately from list archives and can be made available for mailing lists which do not archive postings (i.e. which run with "Notebook= No"). Indexes, on the other hand, only provide a few lines of information for each posting: date and time, number of lines, name and address of poster, subject. The actual text is not included. You select just the messages you are interested in, and order them from the server. This is useful for mailing lists where most messages really don't interest you at all, or as an alternative to SET NOMAIL: when you come back from vacations, you can quickly order the messages you are most interested in. Note that, since indexes are not useful without the ability to order a copy of the messages you do want to read, they are not made available unless the list is archived and digests are enabled. Users sign up for digestified rather than immediate delivery with 'SET DIGests', while indexes are selected with 'SET INDex'. These two options are alternatives to MAIL and NOMAIL. When switching around between these delivery options, users will observe the following behavior (digests will be assumed to be daily for the sake of clarity): * When switching to NOMAIL: delivery stops immediately. The day's digest is not sent, as the user is assumed to desire immediate termination of traffic from the list. * When switching from any option to DIGESTS or INDEX: mail delivery stops immediately, and the first index or digest may contain some items the user has already seen (if switching from MAIL to DIGESTS/INDEX). This is because the digests and indexes are global to the list - they are the same for everyone, just like regular issues of newspapers. * When switching from DIGESTS or INDEX to MAIL, the current, unfinished digest or index is immediately mailed to the user. New messages are delivered normally, as they arrive. Thus, a "trick" to get a copy of the current digest is to switch to MAIL and then back to DIGESTS. You can send both commands in the same mail message to make sure they are executed together. The list owner controls the availability and frequency of digests through the "Digest=" list header keyword, which defaults to "Digest= No" for lists without an archive and "Digest= Yes,Same,Daily" for archived lists. Again, it is not necessary for the list to be archived to keep a digest; LISTSERV just attempts to avoid having to store large amounts of digest data on its private area for lists which, lacking a "Notebook= Yes,xxx" keyword, do not specify any suitable directory for the digest data. Conversely, having daily as the default frequency keeps the additional cost in disk space to a minimum. The syntax of the keyword is "Digest= Yes,where,frequency,when,Size(maxsize)" when digests are enabled, or then "Digest= No". The second parameter is a disk or directory specification, just as with the "Notebook=" keyword, or "Same", which means that the digest must be stored on the same disk as the list archives. The third parameter is either "Daily" (the default), "Weekly" or "Monthly". The third parameter is optional and specifies when the digest is to be actually distributed. For daily digests, specify 'hh:ss' or just 'hh' in the usual 00-23 scale (24 is also accepted for midnight). For weekly digests, specify a weekday such as "Tuesday". For monthly digests, you may specify a number from 1 to 31 corresponding to the day of the month when the digest will be distributed, although this is not recommended. The purpose here is to make it possible for digests to be issued at mid-month rather than on the first of the month - if you code a number larger than 28, you may not get a digest every month. Finally, the last and optional parameter takes the form "Size(nnnn)" and specifies the maximum size the digest is allowed to reach before a "special issue" is cut. Bear in mind that most unix systems do not accept messages larger than 100 kilobytes, so values larger than 1500 should be avoided. The default is to have virtually no limit - 10,000 lines. The list owner must take special care when disabling digests for a list, as LISTSERV does not presently have any facility which would allow it to alter subscription options automatically on the basis of changes to the list header. Subscribers who had opted for digests would continue not to receive mail as it arrives, but would not get the digests either. The best way to solve this problem is to announce the change long enough in advance, so that people can switch back before digests are suspended. The reason nothing has been done to remove this limitation is that it is not expected to be a frequent condition. Daily digests take up very little disk space and there is no reason to disable them for a typical list. ******************************* * Internet-Via= * ******************************* There is no default value. This parameter determines whether or not mail bound for Internet addresses is routed through a specific Internet gateway. ***************************************** * Mail-Via= Direct | DISTRIBUTE | DIST2 * ***************************************** The default value is Mail-Via= DISTRIBUTE. DIST2 is functionally equivalent to DISTRIBUTE, and is included for historical reasons. Mail-Via= Direct causes LISTSERV to ignore the DISTRIBUTE algorithm for subscribers on the local system, but mail to non-local subscribers will still go out on the DISTRIBUTE backbone. ***************************************************************** * Newsgroups= None | ,... * ***************************************************************** This keyword defines the RFC822 "Newsgroups:" header for a list. This field may be required by certain news gatewaying software and should only be defined if the list is gatewayed to usenet and if the gatewaying software does require it. The default is "Newsgroups= None". A typical setting for this keyword might be: * Newsgroups= bit.listserv.lstown-l ************************** * NJE-Via= * ************************** There is no default value. This parameter determines whether or not mail bound for NJE addresses is routed through a specific gateway. **************************** * Prime= Yes | No | * **************************** Determines whether or not mail for the list is processed during "prime time", a value that is determined by the LISTSERV maintainer and is kept in the system configuration file. The default is "Prime= Yes". This can be most useful in controlling the load on the machine running LISTSERV. "Prime=" may also be set to an explicit time specification, e.g., * Prime= "MON-FRI: 09:00-17:00; SUN-SAT: -" *************************************************** * Reply-To= ,Respect | Ignore | Both * *************************************************** Indicates whether the "Reply-to:" tag supplied by the sender of the mail file is to be preserved or discarded (if present), and, if discarded or omitted, what should be placed in the new "Reply-to:" generated by the server. The default value is "List,Respect". Note that some mailing systems are unable to process a "Reply-To:" field with multiple addresses correctly and may therefore disregard the "Reply-to= Both" option and treat it as "Reply-to= List". Respect: The original "Reply-to:" tag, if any, is kept. Ignore: The original "Reply-to:" tag is ignored and discarded. ********************************************************************* * Sender= LIST | NONE | " ", * ********************************************************************* Used to define the value LISTSERV will place in the RFC822 "Sender:" field. The second parameter is optional, and is included to allow the specification of a second mailbox for use with IETF headers. The first value is used for non-IETF headers and is expected to contain the name and address of the list, or the keywords LIST or NONE. The second mailbox is used for IETF headers; if it is omitted, the generic "owner-" mailbox is substituted. Example: * Sender= "Test List ",owner-test@listserv.x.edu Note that the first address must be contained in quotes. ****************************************** * Topics= ,,... * ****************************************** List topics provide a way to run a mailing list (preferably moderated) where several sub-topics are being discussed in parallel but some subscribers are only interested in a subset of the topics. For instance, a working group might have general discussions, decisions, and messages related to meetings. People who cannot attend the meetings can then opt out of last calls for hotel reservations and discussions about seafood restaurants, whereas people who have no time to follow the discussions can elect to get just the decisions. At any rate, such a compartmented list requires a certain discipline in order to be successful, as the posters must label their messages to indicate which topic(s) they belong to. Through the "Topics=" keyword, the list owner can define up to 11 topics for the list. For instance, the list owner could code: Topics= News,Benchmarks,Meetings,Beta-tests ******************************************************** * WARNING - YOU MUST NEVER REORDER THE TOPICS= KEYWORD * ******************************************************** To save disk space, LISTSERV remembers which topics users have selected through their ordering in the "Topics=" keyword. That is, "News" is "topic number 1" for LISTSERV, "Benchmarks" is "topic number 2", and so on. This means you can change the name of a topic without requiring users to alter their subscriptions (for instance, you could decide that "Tests" is a better name than "Beta-tests" and just make the change). However, you must never change the order of the topics in the "Topics=" keyword. If you want to remove a topic, replace it with a comma. For instance, to remove the "Meetings" topic, you would change the keyword to: * Topics= News,Benchmarks,,Beta-tests This restriction might be removed in a future release. Topic names can contain any character except space, colon and comma; the use of double quotes or equal signs is discouraged, as they require special attention when coding list header keywords. In addition, topic names may not start with a plus or minus sign, and the words ALL, NONE, RE, OTHER and OTHERS are reserved. Posters label their messages through the subject field. LISTSERV first skips any possible sequence of 'Re:' keywords, and takes anything to the left of a colon as a list of topics, separated by commas. The posting is considered to belong to all the topics listed before the colon. If none of these topics is valid for the list, it is classified in a special, 12th topic, "Other". If some of the topics are valid but others are undefined, the invalid ones are ignored. At any rate the subject field is left unchanged. Here is an example: Subject: Benchmarks,News: Benchmarks for XYZ now available! Messages which should be read by everyone can be posted to the special topic "All". Topic names can be shortened to any unambiguous abbreviation. In our example, "Be" is ambiguous because it could be either "Beta-tests" or "Benchmarks", but "Bench" is acceptable. Subscribers select the topics they wish to receive with the SET command. The syntax is 'SET TOPICS: xxx' where 'xxx' can be: * A list of all the topics the user wishes to receive. In that case these topics replace any other topics the user may have subscribed to before. For instance, after 'SET XYZ-L TOPICS: NEWS BENCH', the user will receive news and benchmarks, and nothing else. * Updates to the list of topics the user 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. Do 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 you only want to receive properly labeled messages you should not include it. ALL does include OTHER. Finally, it is important to note that topics are active only when your 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. (See also Default-Topics.) *************************** * Error Handling Keywords * *************************** ******************************************************************************** * Auto-Delete= No * * Yes,Semi-Auto | Full-Auto | Manual,Delay(),Max()* ******************************************************************************** LISTSERV includes support for automatic deletion of users whose account has expired or whose system has permanently disconnected. When the delivery error is generated by LMail (any version), MX V3.2 or higher, PMDF V4.2 or higher, or LSMTP(TM) , which all implement the same delivery error format, LISTSERV may be able to automatically process the delivery error and take action based on the value of the "Auto-Delete=" list header keyword. The unix versions of LISTSERV also support sendmail’s delivery error format. If the list has been coded "Auto-Delete= No", or if the delivery error is not in LMail format and LISTSERV cannot understand it, LISTSERV simply passes it to the list owner. Otherwise LISTSERV processes the message automatically. The algorithm may be refined in a future version, but at present the following steps are taken: * LISTSERV looks for "permanent" errors (no such user, no such host, and so on). If the failing recipients are subscribed to the list, LISTSERV removes them and notifies you. No action is required from the list owner. * If there are permanent errors for users LISTSERV could not find on the list for instance because the account subscribed to the list is a totally different one which forwards mail to a dead account), or if there are only "temporary" errors (host unreachable for 3 days, system error, disk quota exceeded, and so on), LISTSERV further examines the "Auto-Delete=" keyword and passes the message to the list owner unless the list is coded "Auto-Delete= Yes,Full- Auto". * When running in full-auto mode, LISTSERV never passes back a delivery error unless it took action on it. This means that certain errors may remain unsolved, as LISTSERV presently ignores temporary errors and some of them are virtually permanent (if the owner of the account has left but for some reason his account was not closed, his disk quota is bound to remain exceeded until someone takes action). Full-auto mode is to be used only when the list owner positively does not have the time to handle the delivery errors LISTSERV sends every day. * When running in manual mode, the auto-delete monitor informs the list owner of the error(s) and takes no further action on delivery errors. Some considerations for configuring the auto-delete monitor parameters: * Setting the Delay(number) option. The default is 4. This is the number of days that a subscriber's mail needs to bounce before he's automatically deleted. If "Delay(0)" is coded, LISTSERV won't wait. * Most delivery errors occur on weekends when systems are taken down for maintenance, system administrators are not around to reboot after crashes, and the like. Because of this, most delivery errors only last for 2-3 days and may not be "permanent" even if they seem to be at first. The nature of delivery errors is such that LISTSERV has no way to establish that a problem has been fixed because it receives only negative acknowledgements when a message bounces. This taken together with the transient, "weekend" nature of most delivery errors indicates that it is not a good idea to set Delay() to a value close to 7. For instance, if Delay(7) and a subscriber's mail regularly bounces on the weekend, LISTSERV will wait until he next weekend to decide whether or not to delete him, at which point the subscriber will bounce mail again and start the process all over. The bottom line is that LISTSERV might as well have gone ahead and deleted the subscriber as soon as the first bounce occurred. * Setting the Max(number) option. To prevent auto-deletion monitoring from getting out of hand, subscribers are deleted after a specified number errors regardless of how many days it has been going on. The default is Max(100). This is so LISTSERV won't spend its life monitoring 50 bogus users x 100 messages = 5000 a day. * When you take a vacation, note that it is best to switch auto-delete to MANUAL. Then do not restore to auto on the day you come back, because you will have a number of subscribers on file ready to be deleted. Wait DELAY+n days before changing back to Full-Auto or Semi-Auto, where n is an adjustment to account for the fact that people don't fix all problems right away at 09.00 on the day your vacation ends. n=2 is a reasonable choice. The default value is "Auto-Delete= No" for lists with "Validate= All" and "Auto- Delete= Yes,Semi-Auto,Delay(4),Max(100)" for other lists. ************************************************ * Errors-To= ,,... * ************************************************ Defines the person or list of persons that are to receive rejection mail for the list. The default value is 'Postmaster', and it is recommended that the owners change it to 'Owners' or 'Owners,Postmaster' as soon as they become familiar with LISTSERV. *************************************************************** * Loopcheck= Full | None | Noorigin | Nobody | NoCRC | NoSpam * *************************************************************** Determines the type of loop checking performed by LISTSERV to avoid perpetuating mail loops. The default is "Loopcheck= Full". ****************** * Safe= Yes | No * ****************** The list header keyword, "Safe= Yes/No", controls the e-mail address LISTSERV places in the SMTP MAIL FROM: field, which is where well-behaved mailers will return delivery errors. With "Safe= No", these errors are sent to the list address as before, hopefully to be intercepted by the loop detector and passed on to the list owner. With "Safe= Yes", the error address is set to 'owner- ', and delivery errors sent to that address are passed on to the list owner without the risk of creating a mailing loop. The default is "Safe= Yes". IMPORTANT: The use of "Safe= Yes" does not guarantee that all errors will go to the 'owner-' mailbox. Unfortunately, there are many non-compliant mailers which will continue to send the error back to the list (usually because it is listed in the 'Reply-To:' or 'Sender:' field). The use of the "Safe= Yes" option significantly decreases the potential for mailing loops, but not enough to actually code "Loopcheck= No", unless you are sure that all your subscribers have compliant mailers. ******************************************** * List Maintenance and Moderation Keywords * ******************************************** ********************************************* * Editor= ,,... * ********************************************* Defines the list editor(s). When used in conjunction with the "Send=Editor" option, it causes all mail sent to the list to be automatically forwarded to the first person listed in the "Editor=" keyword, who will then send it back to the list at his discretion. The editors are the only persons (with the list owners) who are allowed to mail directly to the list. Note that ANY editor can send mail to the list while only the FIRST one will receive copies of mail sent to the list (but see also Moderator=). The file will be forwarded to the editor 'as is', without being included in a mail envelope. This method makes sure that the original "Resent-" tags (if any) and "To:" keyword are preserved. Note that the first editor must be a network address (e.g., someuser@foo.bar. com) and not an access-level. Subsequent editors may be access-levels. For instance, you can code * Editor= joe@baz.net,(MYLIST-L) which allows all subscribers from the MYLIST-L list to post without going through the editor, and diverts all non-subscriber mail to joe@baz.net for approval. IMPORTANT NOTE: The first editor MUST be a human person, not a file server, list server, mailer, or suchlike. Specifying a program's mailbox as the primary editor could result in a mailing loop for which L-Soft international, Inc., could not be held responsible. *************************** * Editor-Header= Yes | No * *************************** If an editor is defined (see Editor=), this keyword determines whether or not special header information is prepended to list messages forwarded to the editor. The default (for lists configured with an Editor) is "Editor-Header= Yes". ***************************************** * List-Address= @ * ***************************************** This keyword determines how LISTSERV announces its list address in the header of messages delivered to the list: NJE vs. Internet address, short vs. long list name, etc. The default options (when neither "List-Address=" or LIST_ADDRESS are defined) are long list name and Internet address. A corresponding LIST_ADDRESS configuration option must be added to the LISTSERV configuration file. The first token () can be either LISTNAME or LIST-ID. Do not attempt to specify the actual list name. Use LISTNAME if you want LISTSERV to use the "short" list name (always available), and LIST-ID if you would rather see the "long" list name ("List-ID=" keyword). If there is no "long" name, the short name is substituted. The second token () can be either NJE, FQDN, or the fully qualified domain name of your choice. That is, you may type the actual hostname that you want LISTSERV to use, which may be useful if the machine on which LISTSERV is running is known under several hostnames. If you only want to override one of the two parts of the list address, you do not need to specify the other. For instance, if you only want to change the hostname, you can enter "List-Address= XYZ.EDU" in the list header and let the left-hand part default from the value of the system default in the LISTSERV configuation file. Similarly, "List-Address= List-ID" takes the right-hand part from the system default. To avoid bad surprises, LISTSERV will also accept a comma in lieu of @-sign in the list header, or a blank in the LISTSERV configuration file. Here are a few examples: * "List-Address= FQDN" announces the list under the Internet address for the LISTSERV host, if one is available (for BITNET-only sites this setting has no effect). * "List-Address= List-ID@FQDN" uses the long list name and the Internet hostname. * "List-Address= Listname@XYZ.EDU" uses the short list name and the hostname XYZ.EDU. * "List-Address= XYZ-L@XYZ.EDU" is not valid. Always specify LISTNAME or LIST- ID for the left-hand part. ******************* * List-ID= * ******************* On VM systems, this keyword allows the list owner to specify a long list ID in addition to the normal 8-character list name. This is particularly useful for peered or gatewayed lists that have names longer than 8 characters. On non-VM systems, if the normal list name is longer than 8 characters and the list is being migrated from a VM system, it may be a good idea to specify the first 8 characters of the list name in this keyword, at least temporarily. This way subscribers who were used to the old 8-character name can continue to use it on the new system. Non-VM systems may use this keyword for aliasing. ********************************************** * Moderator= ,.... * ********************************************** This keyword defines which editors of a moderated list receive postings for forwarding to the list. The default is the first editor as defined by the "Editor=" keyword. If multiple moderators are defined, the load is spread across them. Note that all editors may still post directly to the list, but only those editors defined by "Moderator=" will have messages from non-editors forwarded to them. ************************** * New-List= * ************************** When a list is moved to a different LISTSERV host, this keyword can be added to the list header left on the original host. This facilitates forwarding of administrative commands and postings from the original host to the new host. Users posting to the old address will also receive a short note in return listing the new address. ************************************************************* * Notebook= No * * Yes,,|Separate,) * ************************************************************* Indicates whether or not an automatic log of every piece of mail sent to the list is to be kept, and defines at which interval of time its file name must be changed and who is allowed to retrieve it from the server. The default values are "Notebook= No,A,Single,Private". is the filemode of the minidisk (VM) or the disk and directory (non- VM) on which the notebook is to be kept. Defines the filetype or extension of the "notebook" file for the list, as indicated below (the filename will always be the same as the list name): Single: A single file with the extension "NOTEBOOK" is created. Yearly: A new file is started each yearly, extension is "LOGyy" Monthly: The extension is "LOGyymm" Weekly: The extension is "LOGyymmw" (w in "A"-"E") Separate: A separate file is kept for each mailing (e.g. announcements, newsletters). The extension is "yy-nnnnn" (sequential counter). Note: Notebooks may be retrieved by means of the GET command. A list of all available notebooks can be obtained with a GET NOTEBOOK FILELIST command. ********************************* * Notebook-Header= Short | Full * ********************************* Determines whether or not individual message in notebook archives are stored with full Internet header information or with "short" headers. The default is "Notebook-Header= Short". ************************************ * Notify= Yes | No | * ************************************ Defines whether the list owner (or the person indicated by "Notify= ") is to receive notification of new subscriptions and deletions, etc. The default is "Yes". ********************************************** * Owner= | ,... * ********************************************** Defines the person or list of persons who "own" the list. They are responsible for controlling access to the list and defining the list control keywords which are best suited to the purpose of the list. The default value for this keyword which should ALWAYS appear in the list header is the list of the userids of the postmasters. Any combination of explicit network addresses and complex access- levels is acceptable, for example: Owner= BIG@BLUE,(STAFF-L),Owner(MAIN-L) An interesting application is to create a STAFF-L list containing the userids of all the local LISTSERV staff members and set the "Owner=" keyword of all local lists to "Owner= (STAFF-L)". This way when there is a change in the local LISTSERV management it is not necessary to modify the headers of all the lists - just modify the STAFF-L list. ****************************** * Peers= ,,... * ****************************** Defines the (global) list of all the servers in the world that are peer-linked to the list, either directly or via one or more other peer servers. This information is used by the various list management commands to determine the "nearest" peer list to a given user. For example, when a SUBSCRIBE command is received from a user and it is determined that there is a better (nearer) peer list for him, the subscription request is automatically forwarded to the appropriate LISTSERV. Be sure to read the appropriate sections of the LISTSERV List Owner's Manual before peering any list. ******************************************************************* * Renewal= ,...,,Delay() * ******************************************************************* This keyword controls whether or not subscribers are required to renew their subscriptions on a regular basis, and what the subscription period is. Multiple intervals can be set, each interval being one of several things: * Monthly, Yearly, Weekly, or a numeric variation such as 3-Monthly (meaning, quarterly). * An absolute date in the format yy/mm/dd (once on this specific day), the format mm/dd (once yearly on this day), or the format dd (once monthly on this day). * The confirmation delay, in the format Delay(n), where (n)=the number of days between the time the subscriber is asked to confirm the subscription and the day the user is removed from the list. This default is Delay(7), or seven days. A typical Renewal= configuration might be: * Renewal= 6-Monthly,Delay(14) Conceivably Renewal= could also be set to something like: * Renewal= 6-Monthly,95/07/04,12/25,15,Delay(14) which would cause LISTSERV to send renewal requests once every six months on the anniversary date of the user's original subscription, a specific request on 4 July 1995, a request every year on Christmas Day, and a request every month on the 15th day of the month. Note that this is provided ONLY as an example. L-Soft does not recommend using a renewal scheme of this sort. ********************* * Sizelim= * ********************* If set, causes LISTSERV to truncate all messages to the list to the number of lines indicated. This can be helpful in discouraging subscribers from posting long screeds or uuencoded files to your lists. It can also be set higher than the LISTSERV default if desired; check with your LISTSERV maintainer before changing this upward. (Generally "Sizelim= 250" is large enough for long posts but short enough to discourage postings of uuencoded binaries, but of course, your mileage may vary.) ****************************** * X-Tags= Comment | Yes | No * ****************************** Indicates whether "X-To:" and "X-cc:" tags are to be included in the output mail files to list recipients of the original mail file (other than the list userid) or not, and how they should appear in the RFC822 header. Comment: This information must be provided in the form of "Comment:" tags, i.e. "Comment: X-To:" and "Comment: X-cc:". This is the default. Yes: This information must be provided in the form of "X-To:" and "X-cc:" tags in the RFC822 header (similar to the "To:" and "cc:" tags). No: This information must not appear at all in the mail header. ********************* * Security Keywords * ********************* ************************************ * Confidential= No | Yes | Service * ************************************ Indicates whether the list should be hidden from users or not. A confidential list will not appear on the "List" command output. "No" is the default value and indicates that the list is not confidential. "Service" indicates that the list is to be hidden from users who are not in the list's service area (see "Service=" keyword) but not from other users. "Yes" means that the list is unconditionally confidential. ******************** * Exit= * ******************** Background for non-technical users: an "exit" is a program supplied by the customer to modify the behavior of a product (such as LISTSERV) in ways that the supplier of the product could not anticipate, or could not afford to support via standard commands or options. The product checks for the presence of the "exit" program and calls it on a number of occasions, called "exit points". In some cases, the "exit" program supplies an answer ("return code") to the main program, which adjusts its behavior accordingly. For instance, LISTSERV may ask an exit program "Is it OK to add JOE@XYZ.EDU to the ABC-L list?", and the program will answer yes or no, and possibly send a message to the user explaining why his subscription was accepted or rejected. In other cases, the "exit point" call is purely informative: the exit program gets a chance to do something, such as sending an informational message to a user, but does not return any answer. Because this "exit" is a computer program, it must be prepared by a technical person and installed by the LISTSERV maintainer. Starting with version 1.8a, list "exits" are available to control the major events associated with list maintenance. This makes it easier to tailor the behavior of LISTSERV to local requirements that are too specific to be addressed through standard facilities. An exit is enabled by adding "Exit= filename" to the list header. For security reasons, all exits must be explicitly declared in the LIST_EXITS configuration variable (in the LISTSERV configuration file). This prevents list owners from causing the invocation of arbitrary executable files through the use of the "Exit=" keyword. This keyword is not generally usable by list owners without specific intervention by the LISTSERV maintainer, and thus is not otherwise documented here. ***************************** * Local= ,... * ***************************** Defines the nodes which are to be considered as 'local nodes' for both service area checking. The local node is automatically considered as a 'local node' and does not have to appear in the list. Subscribers from any of the local nodes will receive separate pieces of mail with a single recipient in the "To:" field - in other words, they will never receive a grouped piece of mail as non-local recipients would if there are more than one recipient in their node. Note that 'node' is a generic term that means "anything after the '@' sign in the network address". For instance, "SEARN" and "SEARN.SUNET.SE" are both valid node names. *********************** * PW= * *********************** Defines the list password. When sending the list back to the server, the password is prefixed to the list file for validation (see the Validate command for more specifics). The PW= parameter is "invisible" once it is defined; that is, for security reasons, it does not appear either when the list is reviewed or when it is retrieved with a GET command by the list owner. ******************************** * Service= ,,... * ******************************** Defines the 'service area' outside of which subscription requests must not be accepted. When a SUBSCRIBE command is received, the "Peers=" keyword is checked first to see if there is a nearer peer list in the network. If it is the case, the command is forwarded to this nearer server. If not, the service area is checked to ensure that the recipient is acceptable; if it is not, the subscription request is denied. When the command is forwarded, the destination server might still deny access to the list if the subscriber is outside its own service area, if any. It is important to note that the service area check is made only after the "best placement" check. This allows several servers in the same country to share an identical service area, e.g. "Service= Germany", and still have users subscribed to the best possible server. *********************************** * Validate= No | Yes,Confirm,NoPW * *********************************** Under L-Soft's LISTSERV, lists are protected by a password which must be specified by the list owner when he sends an updated version of the list back to the server. When "Validate= Yes", password validation applies to ALL the commands that modify the contents of the list, e.g. SIGNOFF, SET, etc. This implies that users cannot use these commands since they do not know the list password. A notable exception is the SUBscribe command, which can still be used (if enabled) to get on the list; however, sending a second SUBscribe command for the same list (to correct a spelling error in your name) would result in the command being forwarded to the list owner and not immediately executed. This is to protect you from network hackers who might issue a command "from" your to change list settings, such as who has the ability to GET and PUT the list, review concealed subscribers, etc. The default is "No", but it is recommended that "serious" or "important" lists be changed to "Validate= Yes". This keyword was revised substantially in versions 1.7f and 1.8a. The "OK" command confirmation mechanism was introduced in version 1.7f, where it was used to implement the "Subscription= Open,Confirm" address verification mechanism. When a user tries to subscribe to a mailing list with that setting, he is mailed a confirmation request with a randomly generated confirmation key, also known as "magic cookie". The user replies to the message, types "OK" in the message body, and the command is confirmed. If for any reason the user's address cannot be replied to, the confirmation request is never received (or the "OK" message never arrives) and the user is not added. In versions 1.8x, this procedure is also used for authentication purposes. Since the confirmation codes are valid only for a single command, this provides better security than personal passwords, while simplifying book-keeping. As before, the security level of the mailing list is controlled through the "Validate=" keyword. The contents of this keyword, however, have changed from earlier versions (the old values are still accepted for compatibility reasons, but generate a warning with an explanatory message when you update the list header. This may change in subsequent versions, so it is advisable to use the new values). The following security settings are available: * "Validate= No" (formerly "Validate= Store only"): all commands except PUT are taken at face value with no validation. While users are not bothered with validation requests, the list is totally unprotected from attacks by hackers. For compatibility reasons, this is the default setting. * "Validate= Yes" (formerly "Validate= All commands"): "protected" commands, such as DELETE or ADD, require password validation. For list owner commands, both personal and list passwords are accepted. Some user commands may accept a personal password, while others will cause the request to be forwarded to the list owners for verification. * "Validate= Yes,Confirm" (new level): protected commands are validated using the "OK" mechanism by default, although passwords are also accepted where appropriate. This is a good compromise between list security and list owner convenience. * "Validate= Yes,Confirm,NoPW" (new level): protected commands are validated using the "OK" mechanism. Passwords are not accepted, as they are not as safe as "cookies". This is the recommended setting for secure lists. * "Validate= All,Confirm" and "Validate= All,Confirm,NoPW" (new levels): all commands causing a change in state, except the PUT command, are validated using the "OK" mechanism, with or without a password alternative. Commands such as QUERY do not require any validation. Requests coming from the local system via CP MSG or CP SMSG (on VM systems) or via LCMD (on VMS or Unix systems) never require validation, as they cannot be forged. The PUT command must always be validated with the list password, because there is presently no mechanism to suspend execution of a request to which a file is attached. If the list password is used only for that purpose, the exposure is minimal as PUT operations are not part of everyday list management routine. Note that PUT requests require no validation when submitted via SENDFILE from the machine on which LISTSERV is running, as the operating system then guarantees the authenticity of the transaction. For lists operating with "Validate= Yes" (without the "Confirm" option), LISTSERV may still use the "OK" mechanism in certain cases if it is deemed appropriate. LISTSERV's rationale is that the "Validate=" keyword describes the desired behavior for interaction with the list owner and people who can be expected to use the list on a regular basis. SIGNOFF requests and DELETE requests from registered node administrators on behalf of a user on their machine, for instance, may be validated using the "OK" mechanism even though that was not requested, because users and node administrators are not generally expected to have a password with which to validate such requests. ************************* * Subscription Keywords * ************************* *************************** * Confirm-Delay= * *************************** This parameter is an integer representing the number of hours LISTSERV will hold subscription jobs requiring confirmation before flushing them from its queue. For instance, if Subscription= Open,Confirm and Confirm-Delay= 72, LISTSERV will accept a subscription request pending confirmation, send the "cookie" command confirmation request, and will wait 3 days (72 hours) for that confirmation to be received. If the period expires before the "cookie" is received, the subscription request is deleted and the subscriber must resubmit his or her request. The default setting is 48 hours (2 days). Many unreliable gateways have a turnaround time of several days, and this is another way to filter them: if the confirmation delay is long enough, they will never manage to subscribe and you will not have to put up with gateways that take a week to realize that the subscriber's account has expired and return a week's worth of delivery errors. On the other hand, if you do want to let these people in, you will have to increase the confirmation delay to a week or so (1 week=168 hours). See also Subscription=. ******************************************** * Default-Options= ,,... * ******************************************** A "Default-Options" keyword is available to define initial personal options for new subscribers. The syntax is the same as for the SET command, except that options are separated by commas in the usual fashion. Default-Options does not affect existing subscribers. A typical Default-Options setting might be: * Default-Options=Nofiles,Norepro,Msg ***************************************** * Default-Topics= ,,... * ***************************************** A "Default-Topics=" list header keyword is available to define the initial topics for new subscribers. The syntax is the same as for the SET command, except that topic names are separated by commas in the usual fashion and that the first topic may not start with a + or - sign (there is nothing to add to, as this is a new subscription). This is similar to "Default-Options=" in that it does not affect existing subscribers. Users who signed up before topics were enabled on the list are automatically subscribed to all topics. *************************************************** * Subscription= By owner | Closed | Open ,Confirm * *************************************************** This keyword defines whether or not new users are allowed to subscribe to the list, and if not, whether their subscription requests are to be forwarded to the list owner or not. Open: The users are allowed to subscribe to the list. By owner: The users are not allowed to subscribe, but their requests will be forwarded to the list owner. This is the default. Closed: The users are not allowed to subscribe, and their requests are not to be forwarded to the list owner. One problem plaguing some mailing lists is one-way or non-repliable addresses. Most of the time this is due to a small number of faulty gateways, which one can just ban from the list until their maintainers address the problem. But sometimes the very topic of the list is bound to attract a large number of people connected through such gateways, and the amount of domains to filter out becomes unmanageable. This is particularly problematic when the gateway keeps quiet for a few days, and suddenly returns hundreds of delivery errors with a promise to keep doing so every day for another 6 days. This problem can be avoided by probing the return address before accepting the subscription. If the address cannot be replied to, only one delivery error will be bounced to the list owner (perhaps for several days, but there will be a single undeliverable message). With a gateway that waits 3 days before sending its first delivery error, however, there can be hundreds of messages "in the pipe" if the subscription is accepted directly. This probing is activated by specifying "Subscription= Open,Confirm" in the list header. When a user attempts to subscribe to the list, he is mailed a confirmation request with a randomly generated "confirmation code". The procedure for confirming the subscription is simple - you just reply to the message, type "OK", and send. If the return address does not work, the request will never be confirmed and the user will not be subscribed. And since the user cannot guess the confirmation code he will be assigned, he cannot "cheat" by sending the confirmation along with his request. The subscription request also expires after a certain amount of time, as determined by the "Confirm-Delay=" keyword (the default is 48h). ****************** * Other Keywords * ****************** ********************* * Language= * ********************* Defines the language in which information mail and messages are to be sent to subscribers of the list. The postmaster must have provided the required data file to the server, of course. The default language is "English", of course. Currently only information mail is available in several languages. ******************** * Indent= * ******************** Determines the minimum number of columns allowed for list addresses in response to the REVIEW command. The default is Indent= 40. ************************ * Long-Lines= Yes | No * ************************ Enables or disables "long-lines" support. This keyword was added to maintain compatibility with LISTEARN and will be removed in a future version of LISTSERV. The default is "Long-Lines= Yes". It is unlikely that this keyword will need to be set for any list. *********************** * Translate= Yes | No * *********************** Determines whether LISTSERV keeps or removes control characters from files which it distributes. "Translate= Yes" removes control characters; "Translate= No" keeps them. The default setting is "Translate= Yes". *********************************** * Default Values for all keywords * *********************************** Ack= Yes Auto-Delete= No if "Validate= Yes", Yes,Delay(4),Max(100) otherwise Confidential= No Confirm-Delay= 48 Daily-Threshold= 50 Default-Options= Default-Topics= Digest= Yes,Daily,Same if "Notebook= Yes", No otherwise Editor= Editor-Header= Yes Errors-To= Owner Exit= Files= No Filter= Indent= 40 Internet-Via= Language= English List-Address= (per LIST_ADDRESS system default) List-ID= Local= Long-Lines= Yes Loopcheck= Full Mail-Via= DISTRIBUTE Moderator= (defaults to first Editor if "Editor=" is defined) Newsgroups= NJE-Via= Notebook= No,A,Single,Private Notebook-Header= Short Notify= Yes Owner= (This is a mandatory parameter which must be filled with at least one person's network address in or format) Peers= Prime= Yes PW= Renewal= Reply-To= List,Respect Review= Public Safe= Yes Send= Public Sender= List Service= Sizelim= Stats= Normal,Private Subscription= Open Topics= Translate= Yes Validate= No X-Tags= Yes