Security Keywords

Change-Log=

Change-Log= No | Yes[,Yearly|Monthly|Weekly|Daily|Single]

This keyword is not available in LISTSERV Lite.

When set to YES, causes LISTSERV to write a listname.CHANGELOG file (listname CHANGLG on VM) in the "A" disk or directory which contains information about all changes made to individual subscriptions. Commands tracked include SUBscribe/JOIN, SIGNOFF/UNSUBscribe, auto-deletions, and all changes to users' personal options. A CHANGELOG file can be retrieved by list owners and site maintainers with the GET command and deleted with the PUT command like any other file (it is not necessary to make catalog entries for CHANGELOG files).

In 1.8d, change-logs could be only enabled or disabled. There was no facility to rotate change-logs at all, so once enabled, a change-log simply kept growing until it was deleted. Since it can grow quite large, it was recommended that this option be enabled under 1.8d only if the list owner(s) kept it pruned on a regular basis.  Alternately the option could be enabled for problem resolution, and disabled after debugging.

Non-VM LISTSERV 1.8e and later has an enhanced Change-Log= list header keyword that allows list owners to rotate change-logs along the same lines as they rotate list notebook logs.

Rotated logs are renamed to listname.CHANGELOG-yyyy[mm[dd|w]] and can be retrieved as usual with the GET command, which was changed to recognize these as change-logs.

When the feature is introduced (ie when upgrading to 1.8e or later), old logs will be renamed based on the date in the last entry. If the last entry is compatible with the newly introduced period (eg logs are YEARLY and the last entry is 2001), the log will continue, even if there were also entries for 2000. The definition of the 2001 log is that it contains all the entries for 2001, not that it is the first log started in 2001. Logs are not split as the feature is introduced.

If the rename fails (eg because you keep changing the period back and forth), the current log continues.

While LISTSERV on VM will accept all of the above settings without complaint, everything will behave as if you had specified SINGLE. This is because filetypes are limited to 8 characters on VM and it would be difficult to support a different naming convention just for VM.

The default is "Change-Log= No". For backward compatibility, "Change-Log= Yes" is equivalent to "Change-Log= Yes,Single".

Confidential=

Confidential= No | Yes | Service

Indicates whether the list should be hidden from users or not. A confidential list will not appear on the "Lists" command output. "Confidential= No" is the default value and indicates that the list is not confidential. "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. "Confidential= Yes" means that the list is unconditionally confidential.

Please note that in LISTSERV 1.8c and following, the local list of (public) lists can be retrieved only by those users who are considered local, per the setting of the server-wide LOCAL= variable in LISTSERV's site configuration file. All other users will be told that none of the lists on the server are visible via the LISTS command, and will be referred to the use of the LISTS GLOBAL search-text command or to the CataList. This is regardless of the setting of Confidential= as outlined below.

Exit=

Exit= filename

This feature and keyword are not available in LISTSERV Lite.

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.

LISTSERV version 1.8a and higher support list "exits". List "exits" allow you 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 site 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=

Local= node1,node2,...

This keyword is not available in LISTSERV Lite.

Defines the nodes that are to be considered as 'local nodes' for service area checking. The LISTSERV machine 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.

By default, this keyword takes its value from the LOCAL variable in LISTSERV's site configuration file.

PW=

PW= list-password

(Obsolete since version 1.8c [except for peered lists]; included for backwards compatibility)

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.

LISTSERV version 1.8c and higher generate a 16-character random password for lists at list creation time if this keyword is not explicitly defined, making such lists more secure from random hackers. List owners are now encouraged to use personal passwords (defined with the PW ADD command, q.q.v.) in preference to list passwords for this reason.

The one exception to this keyword's obsolescence is when you are creating peer lists. Peers must have the same PW= setting, so you cannot use the LISTSERV-generated random password when creating peers.

Service=

Service= area1,area2,...

This keyword is not available in LISTSERV Lite.

Defines the 'service area' outside of which subscription requests must not be accepted. When a SUBSCRIBE command is received, the "Peers=" keyword (if set) is checked first to see if there is a nearer peer list in the network. If this is the case, the command is forwarded to this nearer peer 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 to a peer, the destination peer 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, for example "Service= Germany", and still have users subscribed to the best possible server.

For lists running the web archive interface: Starting with LISTSERV 1.8d it is possible to define "Service=" in terms of IP address blocks in order to limit access to list archive notebooks via the web archive interface. This is implemented as follows:

1.       Notebook= ...,Service

2.       "Service=" can contain entries of the form:

[^]IP(a.b.c.d[/e])

3.       For any other keyword (call it "xxx") in "Service=" which contains neither period, wildcard nor parentheses, if a site configuration variable called IP_xxx is defined, it is processed using the syntax in #2, except that the IP() is implicit, i.e., the syntax would be (for unix; no quotes for NT as usual):

   IP_MYNETWORK="192.36.125.0/24 ^192.36.125.199"

      The corresponding setting in "Service=" would then be something like

   Service= example.com,*.example.com,MYNETWORK

      ("IP_" must not be specified in "Service=".  LISTSERV understands that when you specify "Service= MYNETWORK", you mean for it to look at the value set in the IP_MYNETWORK site configuration variable.)

If both #2 and #3 are present, they are combined. Likewise, you can have multiple occurrences of #2 or #3 and they will just be combined.

Access will be granted if the IP address matches at least one of the entries that do not begin with a ^ (you can also use a minus sign if you prefer) AND the IP address does not match any of the negative entries. Otherwise you get a normal login request without any further comment.

Note carefully that LISTSERV does not do a reverse lookup on the IP addresses you code into the Service= keyword! When coding IPs into Service= you must also code in FQDN values for allowed hostnames. Thus if you have a list that should be restricted to the 192.36.0.0/16 subnet, which belongs to a domain called FOO.COM, you really have to code something like

* Service= FOO.COM,*.FOO.COM,IP(192.36.0.0/16)

in order for everyone in the FOO.COM domain who needs access to be able to have it.

The default value is "Service= *" (e.g., any host).

Validate=

Validate= No | Yes[,Confirm[,NoPW]] | All,Confirm[,NoPW]]

The Validate= keyword determines what level of validation (if any) is performed for various LISTSERV commands that apply to individual lists. There are six different settings ranging from very basic to very strict. The two most common settings are (arguably) "Validate= No" and "Validate= Yes".

Lists are protected from hackers at the most basic level by the fact that a list PUT operation always requires validation, regardless of the setting of the Validate= keyword. In other words, the list owner or LISTSERV postmaster must always use a personal password (set with the PW ADD command, q.q.v.) when he sends an updated version either of the list header or of the entire list back to the server, even if "Validate= No". This is to protect you from network hackers who might issue a command "from" your userid@host address to change list settings, such as who has the ability to GET and PUT the list, review concealed subscribers, etc. The default for this keyword is "Validate= No", but it is recommended that "serious" or "important" lists be changed to at least "Validate= Yes".

When "Validate= Yes", password validation applies to so-called "protected" commands (all of the commands that modify the contents of the list, for example ADD, DELETE, SIGNOFF, etc.--but not SUBscribe or SET). This implies that hackers cannot use these "protected" commands since they do not know the list owner's or LISTSERV postmaster's personal password. While at first glance this would also seem to mean that legitimate subscribers cannot use the SIGNOFF command, that is not the case, because for lists operating with "Validate= Yes" (i.e., 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 from legitimate subscribers and DELETE requests from registered node administrators (NADs) 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.

A notable exception to the list of "protected" commands is the SUBscribe command, which can still be used (if enabled, for example, if "Subscription= Open") to get on the list; however, when "Validate= Yes", sending a second SUBscribe command for the same list (for instance, to correct a spelling error in your name) would result in the command being forwarded to the list owner and not immediately executed. Also note that the SET command used to set various personal subscription options is not a "protected" command and may be issued without need for validation even when "Validate= Yes".

A rundown of the six different settings and what they mean follows:

§      "Validate= No": all commands except PUT are taken at face value with no validation. While users are not bothered with validation requests, the list is almost totally unprotected from attacks by hackers. For compatibility reasons, this is the default setting.

§      "Validate= Yes": "protected" commands, such as DELETE or ADD, require password validation. For list owner commands, personal passwords set with the PW ADD command 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. Other "protected" commands include GET, but do not include SUB or SET.

§      "Validate= Yes,Confirm": protected commands are validated using the "OK" mechanism by default, although personal passwords are also accepted where appropriate. This is a good compromise between list security and list owner convenience.

§      "Validate= Yes,Confirm,NoPW": protected commands are always 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. Note that lists with this setting cannot be managed via the Web Management Interface.

§      "Validate= All,Confirm": all commands causing a change in state, except the PUT command (which is always password-validated), are validated using the "OK" mechanism by default, although personal passwords are also accepted where appropriate. "Protected" commands (see above) are included in the class of commands that cause a change of state. Non-"protected" commands that cause a change in state include SUB and SET.

§      "Validate= All,Confirm,NoPW": all commands causing a change in state (except PUT, as noted above) are always validated using the "OK" mechanism; passwords are not accepted, as with "Validate= Yes,Confirm,NoPW". Note that lists with this setting cannot be managed via the Web Management Interface.

Warning regarding obsolete values: Under Revised LISTSERV (that is, LISTSERV for VM prior to version 1.8a), "Validate= All commands" (or "Validate= All") and "Validate= Store only" (or "Validate= Store") were the only acceptable values for this keyword. These old values are still accepted for compatibility reasons, but generate a warning with an explanatory message when you update the list header. Since these values are obsolete and may not be supported in the future, you should change any instance of these settings in your lists to the current equivalent values (or to other currently-acceptable values as you see fit):

"Validate= Store only" is now "Validate= No"

"Validate= All commands" is now "Validate= Yes"

Informational commands such as QUERY, SHOW, INDEX and REVIEW do not require any validation, regardless of the setting of Validate=.

Requests originating on the local machine via CP MSG or CP SMSG (on VM systems) or originating on the local machine via LCMD (on VMS, Unix, and Windows 95/NT systems) never require validation, as they cannot be forged.

In all cases save one, the PUT command must always be validated with the personal password of the list owner or LISTSERV postmaster who is executing the PUT operation. This is because LISTSERV is not currently able to (1) suspend the execution of your PUT command, (2) store your list header or other file in a temporary file, and (3) wait for your "OK" before executing the PUT. If your password is used only for the purpose of validating PUT commands, any password exposure is minimal as PUT operations are not part of everyday list management routine. VM users should note that PUT requests require no validation when submitted via CMS SENDFILE from the machine on which LISTSERV is running, as the operating system itself guarantees the authenticity of the transaction (and thus there is no need to store the file you are PUTting and wait for an "OK"). This is the only case in which a PUT operation does not require a password.

Table B.1 shows how LISTSERV commands are influenced by the Validate= keyword under different settings. Some redundant commands (e.g., JOIN, LEAVE, and UNSUBscribe) are not documented in the table, but behave exactly as do their "official" counterparts (e.g., JOIN behaves exactly as does SUBSCRIBE). Some commands never require validation but are included for completeness because they are specifically "list-level" commands. If a command is not otherwise listed below, it is not influenced in any way by the Validate= keyword.

NONE = does not require any validation

PW = requires password validation

OK = requires OK validation, will not accept PW validation

OK/PW = requires OK validation by default but will also accept PW validation

Table B.1. LISTSERV list-level commands and how they are affected by Validate=.

(*)      All commands so marked may be issued only by a list owner or LISTSERV postmaster.

(**)     The CHANGE command has two syntaxes, one for general users, one for list owners/postmasters. General users will always be required to use "OK" confirmation, regardless of the Validate= setting. The values in the table above are for the syntax issued by list owners or the LISTSERV postmaster(s).

(***)   'GET listname' may be issued only by a list owner or LISTSERV postmaster. General users may issue GET commands for notebook archives and/or files listed in the list's file catalog and with appropriate GET FACs only.

Please note carefully that Table B.1 assumes that you have defined default values for most keywords. For instance, the SUBSCRIBE command will require an "OK" confirmation if you have "Subscription= Open,Confirm" and "Validate= No"; REVIEW will only be available depending on how you have the "Review=" keyword set; GETPOST and SEARCH may require passwords depending on the "Notebook=" setting; etc. However none of these conditions are influenced directly by "Validate=" except as noted in the table.

In some cases, "Validate= Yes" will cause an "OK" request to go out instead of requiring a password (i.e., if no password was included with the command). This is to avoid confusion on the part of a subscriber who may or may not have a LISTSERV password and who may not understand why he is being asked to provide a password before a given command will work.

Note also that even with "Validate= No" some users may be required to confirm commands with the "OK" method if they are sending commands via a web browser and WEB_BROWSER_CONFIRM= is set to 1 (the 1.8c default; under 1.8d the default is 0, or disabled) in the site configuration file.

History: 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.8b and following, this procedure is also used for authentication purposes. Since the confirmation codes are valid only for a single command, this actually 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).