LISTSERV historical documentation, release 1.5d ----------------------------------------------- Copyright Eric Thomas 1986 ***************************************** * * * Privileged commands for list owners * * * ***************************************** This memo is a description of the facilities offered by the Revised LISTSERV processor to list owners. It includes a description of privi- leged list-maintenance commands and some general guidelines. Please refer to LISTKEYW MEMO for a description of list-control keywords and to LISTLINK MEMO for more information about list-linking and peer lists. List-maintenance commands: QUIET command-text This special command will execute the command specified as argument after setting a flag indicating that no notification/information mail is to be reflected to the command target. For example, a "QUIET ADD" command would NOT cause any notification mail to be sent to the person being added to the list. Note that this does not disable mail-sending per se -- it merely sets a flag that will be tested by the various command-parsers; notably, it will not suppress severe error messages which are usually sent via mail. ADD listname userid@node | DD=ddname This command allows you to add a user to one of your lists. He will automatically receive notification of his addition. Note that it is not necessary to supply the user's full-name unless he has never (been) signed on to any list of the server before. The list password must be specified only if the list is protected by the "Validate= All commands" option (qqv), AND the command is issued from a remote node. Password validation is waived when the command is sent via "direct means" (ie CP MSG or CP SMSG) from the local node. Note that the "PW=" keyword can be inserted anywhere in the command line provided it appears AFTER the command name itself. There must not be any blank between "PW" and the equal sign, ie "PW =" will not be recognized as list password. If the specified userid is already subscribed to the list, the "true name" field in his entry will be replaced with the name you specified (possibly taken from the signup file) and he will receive notification of the change. | Upon receipt of an ADD command, LISTSERV will automatically check that | there is no better suited peer list for the specified user. If there is | one, the command will be automatically forwarded to that server. You | can use the ADDHERE (see below) command to override this automatic | command forwarding. Note that an ADDHERE command is automatically per- | formed whenever ADD is used to add a peer distribution list, ie if the | words "Peer distribution" appear in the user's name, the ADD command is | automatically changed to ADDHERE. | Whenever the "DD=ddname" syntax is chosen, the specified dataset must | contain one "userid@node " per line. The password should not | be repeated on the dataset lines. See LISTJOB MEMO for more information | on this form of syntax. Important note: in order for the automatic-REView-forwarding function to work properly, it is mandatory that the words "peer distribution" appear in the "true name" of any PEER distribution list. It must *not* be specified unless the list is a PEER FRECP11-type list. See LISTLINK MEMO for more information on this subject. ADDHere listname userid@node | | The ADDHERE command is strictly identical to ADD, with the exception | that the placement of the user is not checked against the list of peer | servers, ie the specified user is added to the local list without any | further verification. DELete listname userid@node This command allows you to remove a user from one of your lists. He will automatically receive notification of his removal. The "PW=" key- word is required only when the list is protected by a "Validate= All commands" keyword (see ADD command). IMPORTANT NOTE: The "QUIET" command *must* be used whenever another LISTSERV is added to or removed from a distribution list. Failure to do so would result in the notification mail being sent to all the reci- pients of the (target) list server. Please do not forget to contact your postmaster when a remote list is being linked to yours (see below) GET listname <(options> NOLock ! OLD ! GLobal ! Sends you the contents of a list, and locks it to make further GET commands impossible. You will then be able to edit it and store it back without fear that another list owner or postmaster modifies it at the same time and cancels your changes. No ADD or DELete command will be accepted while the list is locked. Note that the command is not propaga ted to the other servers linked to your list. *** IMPORTANT *** Unlike the REView command which reformats the list file and includes some comments of its own, the GET command will send you the raw, unfor- matted contents of the list file. You should be careful not to alter the contents of columns 81-100 of the file when changing a user's name or userid@node. These columns contain non-human-readable information used by the server (notably by the SET/QUERY commands (qqv)) for which a value of 'blanks' will always be accepted and recognized as default settings. You should therefore avoid using the XEDIT C and " prefixes when adding entries to the list, since they would copy the information in columns 81-100 of the copied line, possibly setting unwanted/nonde- fault list distribution options for the new user. It is strongly recom- mended that you use the XEDIT "TRUNC 80" command when editing a list file, unless you do not plan to modify non-comment lines. The NOLock option indicates that the list is not to be locked upon com- pletion of the GET operation. It allows you to retrieve the raw, unfor- matted contents of a list file without locking it and can be useful to examine the information in columns 81-100 of the file. ! The list will be sent with a filetype of "LIST" if it has no peer or ! a filetype equal to the server's nodeid if there is one or more peer. ! This will allow you to easily keep a copy of each of the lists on your ! disk without having to rename them. ! The OLD option indicates that you want to retrieve the "backup" copy of ! the list. Whenever a list is stored by means of a PUT command, a backup ! copy is kept in case you inadvertently stored incorrect information in ! the list. For example, you might have stored the list from peer server ! A into peer server B and vice-versa. No password is required when the ! OLD option is specified, but you must still be an owner of the current ! ("new") list. ! The GLOBAL option causes the command to be forwarded to all the peer ! servers and can be very useful when there is a significant number of ! peers for the list. Note that the password must be the same for all the ! peer lists in order for the GLOBAL option to work properly. Query listname FOR userid@node List owners are authorized to query the distribution options of other users by appending "FOR userid@node" to the command text. No password is required on this command, and no notification is sent to the target user. Please refer to LISTSERV MEMO for more details on the Query com- mand. SET listname options FOR userid@node List owners can use the SET command to change distribution options for other users. The "FOR userid@node" keyword must be specified after the last argument of the command, and notification will be sent to the target user after his entry has been replaced. It is therefore necessa- ry to use "QUIET SET" when changing distribution options for a peer or slave distribution list server. Please refer to LISTSERV MEMO for a complete description of the SET command options. MOVE listname userid@node newnode | DD=ddname listid@newnode | | The MOVE command allows list owners to easily move users from one peer | server to another. It will move the complete user entry from the source | server to the destination one, including full name as it appears in the | specified list and all list distribution options. The MOVE operation | will be done in such a way that no mail can possibly be lost by the | target while the MOVE operation is in progress (duplicate mail might be | received for a short duration, though). Notification will be sent to | the target user unless the QUIET option was used. | | If the source and destination list names are identical, only the desti- | nation node ('newnode') needs be specified. Otherwise, the full network | address ('listid@newnode') must be specified. | | The MOVE command requires both source and destination lists to have the | same password. Since each server will have to send a password to the | other to validate the (special) ADD/DELETE commands it is sending to | the other, it has potentially a way to trap the password specified by | the server, thus thwarting any attempt at inventing a protocol to allow | use of this command on lists which have a different password. Besides, | no MOVE operation will be accepted on lists which do not have a pass- | word at all, because for technical reasons it would allow unauthorized | users to easily add someone to a list (since there would be no password | validation). | | The MOVE command is the proper way to effect a move operation. You | should not use any other command/set of commands unless you cannot use | MOVE. THE MOVE COMMAND SHOULD NOT BE USED TO MOVE DISTRIBUTION LISTS!!! | Since a MOVE is basically an ADD + DELETE, with the latter being done | only AFTER the ADD is completed, moving a distribution list address | with the MOVE command can cause a duplicate link to be defined for a | short period of time. This could result in a transient mailing loop, | which could become permanent if the size of the looping mailfiles is | less than the size of the inter-servers "DELETE" command jobfile, and | the RSCS priority of the latter has been altered. EXPLODE listname | | The EXPLODE command provides a means whereby a list can be automati- | cally analyzed by LISTSERV to optimize the placement of its recipients | over the various peer servers hosting the list. It requires a "Peers=" | keyword to be defined in the list header (see LISTKEYW MEMO). Non- | BITNET userids will be exploded according to the network address of the | corresponding gateway (as per the DOMAIN NAMES file), or ignored if the | gateway could not be identified. LISTSERV will create a commands-job | file containing the necessary MOVE command to transfer all the users | which were found to be (possibly) mis-allocated to the peer server | which is nearest to them. This file will then be sent to you so that | you can review it before sending it back to the server for execution. PUT listname ! Sending a list back to the server in the usual way (ie via SENDFILE) will cause it to be stored back on the server's disk and immediately ! placed online, unless you have protected it with a password. In that ! case, you must add a dummy line on top of the file with "PUT listname ! PW=list_password" before sending it to the server. The password can be changed by adding a "PW= newpassword" keyword in the list header. If this keyword is not present, the old password will be retained. Note that ANY keyword can be changed by means of the PUT command, which means that you can change the mode of operation of the list (opened or closed, public, private or dedicated, etc) as well as the owners-list and list-description. Please make sure not to remove yourself from the "Owner=" keyword list, though. The list will be automatically re-formatted and sorted by node when a PUT operation is performed, so you do not have to worry about inserting new names in the right order and at the right column. Similarly, the "signup" file will be updated so that you do not have to specify the ! user's true name on subsequent ADD commands. Other additional checks ! will be performed as to the validity of the list file you sent. For ! example, if more than one "PW=" keyword is found, or if a user is found ! to be subscribed twice to the list, the PUT operation will be rejected ! and the old list will be retained. ! Note that the old command (with dummy "* PW=password" line) ! is still accepted. However, the use of the PUT command is recommended. ! Its use is mandatory for users whose networking system imposes a fixed ! spool fileid (eg "userid OUTPUT" from MVS) -- PUT ignores the spool ! fileid. | An end-user exec, LSVPUT, is available from LISTSERV to assist you in | updating your lists (send an "Info PUT" command to LISTSERV to obtain | it). It will perform the task of adding the dummy "* PW= password" | record and sending the file to the server. UNLOCK listname Unlocks a list in case it has been inadvertently left locked. Note that this command should be used only after having checked with all the list owners and postmasters that no modification is pending. HOLD listname <(GLobal> ! | Places all mail or non-mail files sent to the list into (spool) HOLD | status after sending an appropriate message to the file sender. This | effectively suspends all mailing/file distribution operations to the | specified list without purging the files and without affecting any of | the other lists (postmasters have access to a similar command that | suspends mailing activity for ALL the distribution lists). ! ! The GLOBAL option causes the command to be forwarded to all the peer ! servers and requires the list password to be the same for all the ! peers. FREE listname <(GLobal> ! | FREE negates a previous HOLD command and releases mail or non-mail | files that may have been previously placed in HOLD status. ! ! The GLOBAL option causes the command to be forwarded to all the peer ! servers and requires the list password to be the same for all the ! peers. STats listname <(options> | LOCal | RESET | | List owners can use the RESET option of the STats command to reset the | statistics. This command will automatically be forwarded to all the | peer servers, in much the same way as a normal STats command would. You | should therefore be careful to use the LOCal option if you want to can- | cel statistics only at a particular server. Please note that you cannot | reset statistics unless you own each of the peer lists. However, the | command will be forwarded even if you are not the owner of the list, so | that statistics get cancelled at all the servers where you own the | list. In order for the command to be effective against all the peer | lists, you must make sure that all the lists share the same password. | If one of the peers has a different password, it will still forward the | command but will not reset the statistics. Moving users from one (peer) server to another: As your list grows in size, you will probably find it necessary to find peer hosts for it to reduce the load it imposes on the network. It will then become necessary to move some users to their new server. How- ever, you should be aware of the fact that a MOVE operation is not just and ADD to the new server and a DELete to the current one. This would effectively transfer the person from the old server to the new one but his distribution options would be lost in the process. Besides, you should make sure that the user does not lose any mail in the process. The proper course of action to be taken when people are moved from one list to the other is the following: 1) Send mail to the list telling people that a new peer server is being linked to the list, and that some subscribers will be moved to it. | 2a) If the prerequisites for using the MOVE command (see description | of the MOVE command above) are met, you should use either indivi- | dual MOVE commands (in the case that there are very little users | to move) or a batch-MOVE command with associated DDname (see the | LISTJOB MEMO guide for more information in commands-jobs) to move | the users. You may want to use the QUIET option to suppress noti- | fication if there are a lot of users to move. | | Warning: the MOVE command should not be used to move peer list | servers. See the MOVE command description for more | details. | | If you cannot use the MOVE command, you should try one of the | following two methods: | 2b) For each user to be moved, issue the following commands in the following order: - "Query listname FOR userid@node" (old server), write down the options. - "QUIET ADD listname userid@node name" - "QUIET SET listname options FOR userid@node" - Wait until you get confirmation for the two previous commands - "QUIET DELete listname userid@node" (old server) 2c) If there are a lot of users to move, the following method should be preferred: - "GET listname" (old server) - "GET listname" (new server) - Receive both files and use the XEDIT "PUT" and "GET" commands to move users from one list to the other. You *must* preserve the contents of columns 81-100 across the move. - Store back the two lists. List passwords: When the postmaster creates the list for you he will probably not have defined a password for it, and you will be able to store the list back by just SENDFILE-ing it to the LISTSERV userid. However, you should be aware of the fact that the structure of the RSCS networks allows privileged network system programmers to send files "from" any origin they want. This means that they could send a file "from" your userid to the server, and it would get stored as if it had actually come from you. It is therefore recommended that you protect your lists with a password for better security. A password can be easily defined by adding a "PW= password" keyword ! in the list header and sending it to the server. Any subsequent PUT ! operation will require the password to be specified as "PUT listname ! PW=password" in the first line of the list. To change your password, ! all you have to do is to specify a new "PW= password" keyword the next ! time you send the list back to the server. You must contact the postmaster if you ever forget your list password. Similarly, a means have been provided whereby password checking can be made mandatory on all the message-based commands (ADD, DELete, etc). Password validation on those commands is controlled by the "Validate=" keyword (see below), which, when set to "All commands", will force password verification on the message-based commands. The default option, "Store only", will caused the password to be verified only on ! the PUT command. Note that "Validate= All commands" and "Subcription= Open" are not conflicting options -- they just mean that everybody can sign on to the list while only a list owner can remove people from it or change names in the list file (the SIGNOFF command is always disa- bled when "Validate= All commands" is active, and only one "SUBscribe" command is allowed). List headers: A list header consists in one or several "comment" lines, ie lines which start with an asterisk in column one. The first non-blank line in the header is considered as being the "list name", to be inserted in the "Sender:" and (possibly) "Reply-to:" tags of distributed mail. Keywords can be defined on any line of the header (except the one defining the list name), in a free format (as many keywords per line as desired), to control several parameters. You should conform to the following rules or guidelines when creating the list header: - The list name must be present, and it ought to be the first non-blank line of the header. It must not contain any "=" character. In the case that the list name contains characters which are considered as "special characters" in RFC822 terms, the list name must be placed within double quotes, eg "The IBM 3278, 3279 and 3180 list". The list name should not be so long as to cause the "Sender:" line to exceed 80 columns; otherwise it will not appear on the "Sender:" field. RFC822 "special characters" are: ()<>@,;:\.[]" - No keyword should appear before the list name. The present version of LISTSERV allows you to specify keywords before the list name, but the author explicitely states that this possibily might be removed in fu- ture versions without warning. - Keywords names can be entered in mixed or upper case. Similarly, their values are converted to uppercase before being tested, and can be entered in either upper or mixed case. Note: quoted-string keywords, such as: Reply-to= "Some address " are not converted to uppercase. - Any number of blanks is allowed on either side of the equal sign. For example, "Review=Public", "Review= Public" and "Review = Public" are three equivalent forms of the same keyword definition. However, the "PW=" keyword is different in that there *must not* be any blank between "PW" and the equal sign. The "PW=" keyword receives special and intensive handling (notably removal) and must be easy to identify This is the reason of the restriction. - There must not be any blank before nor after commas (when applica- ble), except of course in quoted strings. Syntactically the value of a (non-quoted) keyword is the first blank-delimited word appearing after the equal sign. Therefore "Reply-to= List,Ignore" is valid but "Reply-to= List, Ignore" is not -- the default value for the second field, viz "Respect", would then be used. - List-type keywords (eg "Owner=") can appear several times in the header and the successive values will be concatenated to form the final keyword value (see example below). A comma will be automati- cally inserted between the keyword values. - List statistics: you should check with your postmaster before chan- ging the "Stats" keyword to "Extended". This will cause LISTSERV to consume a non-negligible amount of additional CPU time, and will not function properly unless a special data file has been made available to the server. - For similar reasons, you should check with the postmaster before acti vating the "Notebook" option. Sample list header: * * This will be the list name * * Review= Public Subscription= By_owner Send= Private * Notify= Yes Reply-to= List,Ignore Files= Yes * Validate= All commands Stats= Extended,Private * * Owner= OWNER1@NODE1 (True name 1) * Owner= OWNER2@NODE2 (True name 2) * * You can add yourself to this list by contacting one of the list owners. * Issuing a SUBSCRIBE command to the list server will cause it to forward * your request to the owners. * Please refer to LISTKEYW MEMO for a description of all available list control keywords. Customized information mail: For some reasons you may wish to add or remove some information from the notification mail that is sent to new users or to users which have been removed. For example, you may wish to tell the new users that a complete notebook is available from a certain list of persons, or remind them that the list is not to be used to discuss this or that topic, etc. In any case, if you are not satisfied with the default mail templates used for your list, you should inform the postmaster and he will send you a file named "$DEFAULT MAILFORM", containing the default mail form defini tions for his server. You should keep a copy of this file "as is" (for future reference) and create a "listname MAILFORM" file containing the mail forms you intend to revise, and only those. Whenever you do not in- tend to modify a mail form, you should be careful NOT to include it in the "listname MAILFORM" file since it would increase its size and over- ride any modifications made to the default mail forms by the postmaster (eg after installing a new release of the server). The format of this file is easy to understand -- each "form" has a name and its location in the MAILFORM file is indicated by a ":formname formsubject" line (where 'formsubject' is the line to be put in the "Subject:" tag). The body of the note follows and is ended by ":END". Anything that appears between quotes is "translated" as per the REXX "Interpret" statement; note that this is exactly the opposite of a REXX statement, ie what is WITHIN quotes gets translated. Some of the variables are always available (eg 'listname'), but some of them are specified by the calling program. Note that lines in excess of 79 characters will be split, with the remainder inserted before the next line. Also, any line longer than 70 characters will be justified. Linking to another LISTSERV list: ! You should ALWAYS contact the postmaster before deciding to link your ! list to another LISTSERV. Although there is no problem about linking to ! another Revised LISTSERV list, linking to a BITNIC-type LISTSERV is ! quite dangerous since it can cause loop conditions to occur: BITNIC- ! type LISTSERVs may send a copy of the mail file they distribute back ! to the sender, which, in the case of Revised LISTSERV, is the ! list-userid. This means that the mail would get re-distributed, and ! that a loop condition would occur. But anyway, you should check with ! your postmaster before linking your list to a BITNIC-type LISTSERV so ! that he can modify the required control files accordingly. | After the link operation has been completed, it is recommended that | you define "Peers=" keywords on lists you just linked so that you can | try to EXPLODE (qqv) them for better network efficiency. For additional information, refer to: LISTSERV MEMO, LISTLINK MEMO, LISTKEYW MEMO, LISTJOB MEMO Comments and complaints should be sent to Eric Thomas