Table of Contents Previous Next Index

Section 9 Relayed File Distribution & theDISTRIBUTE Command

Section 9 Relayed File Distribution & theDISTRIBUTE Command
The Relayed File Distribution (also known generically as DISTRIBUTE) feature was developed in an attempt to provide an efficient and network-resources-saving means whereby files and mail could be distributed to a large number of persons on the network by ANY network user, without having to resort to predefined distribution lists (which have other advantages but are basically static).
This section is composed of three independent sections. The first one is a description of the distribution algorithm used by Relayed File Distribution. It is general enough to be accessible to inexpert computer users, but does not explain how to send a Relayed File Distribution Request (RFDR) to LISTSERV. The next section gives a detailed technical description of RFDRs and assumes the reader is familiar with the basic concepts of the Commands-Jobs Language Interpreter (CJLI), described in Section 2 Commands-Job Feature and CJLI Interpreter. The final section is a more practical tutorial regarding the construction of RFDR jobs.
Note: While "RFDR Job" is actually the correct nomenclature for a job sent out using Relayed File Distribution, the more common (if not as entirely correct) term "DISTRIBUTE Job" may also be used herein, interchangeably, to describe such jobs.
The security validation feature of the DISTRIBUTE command changes the default behavior of DISTRIBUTE in two ways:
Only a LISTSERV maintainer (i.e., a user who is identified in LISTSERV's site configuration file as a POSTMASTER=) or a "trusted" user (identified in LISTSERV's site configuration file in the DIST_ALLOWED_USERS= variable) may issue the DISTRIBUTE command; and
The default can be relaxed back to the previous (pre-1.8d) behavior by setting the DIST_SECURITY site configuration variable appropriately. See the Site Manager's Operations Manual for details.
9.1 Relayed File Distribution
Relayed File Distribution is a service provided by the ever-growing network of L-Soft LISTSERV servers to all users connected to the Internet who are allowed to send and receive files or messages. (The origins of the service were on BITNET and associated services where it was possible to send files, as opposed to messages.) The user desiring to send the message (whom we will call the 'sender') provides his nearest L-Soft LISTSERV host with a copy of the message to be distributed and the list of persons who are to receive it. He can optionally indicate the full name of these persons as well as his own full name, and they will be used in information messages and mail headers as appropriate. The LISTSERV hosts will then relay the file to each other as explained below and distribute the file to all the indicated recipients in the most efficient way they could 'manage'.
The server that initially receives the file from the sender will first distribute the file to the (possible) recipients of its local node, which does not generate any network traffic. It will then examine the list of non-local recipients and determine, for each of them, which of the L-Soft LISTSERV servers is nearest1. Whenever it finds itself to be the nearest server, it distributes the file directly, and removes the recipient from the list. It then uses a rather complex algorithm to "route" the remaining recipients through its nearest servers, and transmits the request to them. This will be best illustrated by an example.
User X@FRECP11 sends a file distribution request for the following list of people:
We will assume that a L-Soft LISTSERV server has been installed at the following sites: FRECP11, CEARN, DEARN, DKEARN, EARNET
Finally we will assume the following topology, which will not necessarily reflect the actual network topology at the time you read this chapter (it has been simplified and nodes which do not participate in the transfer have been removed):
The file is distributed by LISTSERV@FRECP11 to Y@FRECP11, and then forwarded to LISTSERV@CEARN, which will distribute to the two CEARN recipients and to X@CZHRZU1A. LISTSERV@CEARN then forwards one copy of the file to LISTSERV@DEARN and one to LISTSERV@EARNET, with the appropriate list of recipients. LISTSERV@EARNET distributes to the EARNET recipient and to X@IBACSATA. LISTSERV@DEARN distributes to X@PSUVM, and also to X@NEUVM1. LISTSERV@DKEARN does not receive anything because it would have served only a unique recipient, and in that case a direct send can only be better.
The file has therefore crossed a total of 11 links. If it had been sent the normal way from FRECP11, it would have had to cross 32 links, i.e. thrice more. The reduction is very important because we assumed that a server is installed at all the central nodes in the network, which is not necessarily the case in practice.
9.2 Relayed File Distribution Requests
Relayed File Distribution Requests ("RFDR Jobs") must imperatively be transmitted as a commands-job file. It is recommended that you read Section 2 Commands-Job Feature and CJLI Interpreter if you are not familiar with the basic concepts of CJLI.
By default DISTRIBUTE may only be executed by a LISTSERV maintainer (defined in the POSTMASTER= variable in the site configuration file) or a "trusted" user (identified in LISTSERV's site configuration file in the DIST_ALLOWED_USERS= variable) and requires a password (the invoker's personal LISTSERV password).
The job sent to the server must contain:
A JOB card with the "Echo=No" option to avoid tracing the unique command to the job output. The "Reply-via=" keyword can be set to "Message" if so desired, although this is not recommended. The job name can be anything you want, e.g. filename.filetype
DISTribute <type> <source> <dest> <options> PW=<password>
Options for <type>:
MAIL – Data is a mail message and recipients are defined by ‘<dest>’.
MAIL-MERGE – Data is a mail-merge message.
POST – (non-VM only) Used to send pre-approved messages to moderated (Send=Editor) mailing lists. Typically, this is used only by automated scripts and LISTSERV Maestro. For more information, see Section 9.4.2 Sending Pre-Approved Messages to Moderated Lists.
FILE – (VM only) Data is not mail, recipients are defined by ‘<dest>’.
RFC822 – Data is mail, recipients are defined by the RFC822 To:/cc: fields.
<source> is:
DD=ddname – Name of a Ddname holding the data to distribute
(default: ‘DD=DATA’)
<dest> can be one of the following:
<TO> user1 <user2 <...>> – List of recipients.
<TO> DD=ddname – One recipient per line in a provided DD.
Available <options> are:
ACK=NONE|MAIL|MSG – Acknowledgement level (default: ACK=NONE).
CANON=YES – ‘TO’ list in canonical form.
DEBUG=YES – Do not actually perform the distribution; returns debug path information.
INFORM=MAIL – Send file delivery message to recipients via mail.
TRACE=YES – Similar to DEBUG=YES, but the mail or file is actually distributed.
AV=YES[,FORCE] – Check the message for viruses. The FORCE option overrides any maximum message size limit that is set.
DKIM=YES | NO – Sign (or don’t sign) the message with a DomainKeys signature. Default is DKIM=NO.
PRIO=* | NN – Set a network transmission priority level for the file.
INFORM=MSG | MAIL – For non-mail DISTRIBUTE only, specify how to inform users that they have received the file. Effective on VM only.
<options> that require postmaster-level privileges:
FROM=user – File originator (RFC821 MAIL FROM:).
FROM=DD=ddname – One line:’address name’.
PRE-APPROVED=YES – Pre-approve message (with DISTRIBUTE POST only).
All the keywords (except PW=) can be omitted, but must be specified in the indicated order. The "PRIOR" and "INFORM" keywords are independent from the others and can appear anywhere in the command line. The DISTRIBUTE command requires a password (PW=password, above) for validation purposes. A description of the keywords follows:
A "type" of DISTRIBUTE must be defined as the first parameter to the DISTRIBUTE command. Specifying MAIL indicates that the file to be distributed is a mail file, to be sent to the MAILER at the destination node. The contents of the file are proofread and the "mail origin" is verified so that users cannot send forged mail. MAIL-type distribution is 100% transparent to the mail recipient, which is not the case with file distribution -- a file would come from the LISTSERV userid instead of the sender's userid. The mail file must contain a blank "To:" line where the actual name and network address of each recipient will be automatically inserted as the file is distributed to him.

Other DISTRIBUTE "types" are MAIL-MERGE (described in the chapter below on DBMS and mail-merge), POST (a method used when messages are "pre-approved", typically by LISTSERV Maestro), FILE (obsolete except for VM servers), and RFC822 (where the data is mail and the recipients are defined by the RFC822 To: and cc: fields found in the data).

All DISTRIBUTE jobs sent from non-VM servers will be MAIL-type DISTRIBUTE jobs. Non-MAIL DISTRIBUTE is available only on VM.
FROM=xxxx indicates either the network address of the file sender or the name of a dataset of which the first line indicates the network address and full name of the file sender, e.g. FROM=DD=XXX and //XXX DD "JPB@BIGNODE John P. Brown". The default is FROM= your-userid.

This field contains the address you want bounces to go to (the RFC821 MAIL FROM: address) and it can be used to redirect bounces that should not normally go to the user invoking DISTRIBUTE--e.g., it can be set to a special address set up specifically to handle errors for this particular DISTRIBUTE job.

You do not have to indicate your name when distributing MAIL-type files -- put your name in the "From:"/"Sender:"/whatever field, as appropriate.
ACK= indicates the amount of acknowledgement you want to get. The default is NOne and indicates you do not want to receive messages as the file is distributed. MAIL indicates mail acknowledgements while MSG indicate interactive messages.
TO indicates the list of recipients for the file or mail file. It can either be a list of network addresses ("TO u@n1 u@n2...."), which must not cause the physical command line to exceed 255 characters (use continuation cards in that case), or a ddname of which each line is a "userid@node <full name>" pair. The former is best suited to file distribution while the latter should be preferred for MAIL-type distribution since the recipient's full name will be inserted in the "To:" field of the mail file. The default is "TO DD=TO". Note that distributing a file to a LISTSERV userid will cause it to be interpreted as a command job for execution or a PUT request, as appropriate. Releases 1.5b and earlier did not accept such a destination for DISTRIBUTEd files and ignored the recipient.
PRIOR is the network transmission priority you want to assign to the file. If specified, it can be either "*" or an integer number between 0 and 99, inclusive. "*" indicates that the file priority is left up to LISTSERV, which will use an internal algorithm to assign a reasonable priority to the file according to its number of records.
INFORM (effective on VM only) specifies the media by which you want users to be informed of the arrival of the file. The default is MSG for interactive messages -- specify MAIL if you want LISTSERV to notify recipients via mail. Note that this option is ignored when MAIL distribution has been selected.
Finally, a password is required to validate the command invoker. This is a standard LISTSERV personal password, set with the PW ADD command.
A dataset for the "FROM=DD=" keyword, if specified -- the DD "text" syntax is recommended since the dataset will contain only a single line of data.
A dataset for the "TO DD=" keyword, if specified -- the DD * syntax is best suited to this dataset. This dataset contains network addresses (imperatively) and per-address options, one address/options per line. The per-address options are a real-name field and the keywords BSMTP or PROBE (BSMTP and PROBE are mutually-exclusive; only one can be specified per address). For instance a TO dataset could contain lines like Jack Techie BSMTP PROBE Sue User BSMTP Pete Gunn PROBE
When the BSMTP option is specified, LISTSERV will combine the address along with any other addresses for which BSMTP is specified into a multi-recipient BSMTP envelope (which is much more efficient, since not using BSMTP tells LISTSERV to create a separate SMTP envelope for each address). For general DISTRIBUTE jobs (i.e., non-mail-merge jobs), it is probably most efficient to specify BSMTP for all addresses in the job.
When the PROBE option is specified, LISTSERV will process the address as a PROBE. This is most useful when using a backend list or a changelog file for error processing (see the section on "Advanced LISTSERV applications using DISTRIBUTE", below, for more information on these features; also see the sections on LISTSERV's address probing in the Site Manager's Operations Manual and/or in the List Owner's Manual). PROBE should not be used on one-off DISTRIBUTE jobs which do not require specialized error processing, as it has no particular usefulness otherwise.
Again, BSMTP and PROBE are mutually-exclusive; you may specify one or the other but not both.
Finally, a dataset for the "DD=" keyword, to contain the mail message or file. This should be the last dataset in the file and the DD *,EOF syntax should be used to ensure that the dataset is not prematurely ended by a possible "/*" card in the data. On VM, for storage space saving and performance considerations, the "Res=Disk" option should be specified on that DD card, i.e. DD *,EOF,Res=Disk. Statistics have shown that this decreases the CPU time required to process the request by a factor of six.
Mail-type RFDR under VM must IMPERATIVELY use raw-image (PUNCH) format for the mail dataset, since the header will be scanned and modified by the server. File-type RFDRs can use any type of network file format -- the contents of the "data" dataset will be sent "as is" to the recipients, without anything added on top or bottom of it. The only difference will be the RSCS file origin -- the file will come from the LISTSERV userid instead of the sender's userid. The file class, spool fileid and DIST-code are preserved, but the FORM is changed to QU-DIST to trigger the "quiet file transfer" feature installed in some RSCSs in the network.
Non-BITNET recipients are routed to their gateway, as determined by the DOMAIN NAMES file. The first server in the chain that finds itself unable to determine the gateway distributes the file directly. Whenever non-mail file is distributed to a non-BITNET user, LISTSERV generates a standard mail envelope with the current date, sender's name and address, recipient's address and transfers it to the mailer. Any possible rejection mail will be sent directly to the sender by the mailing system (and not to the LISTSERV userid).
9.3 Creating and Sending a Mail RFDR (“DISTRIBUTE”) Job
The instructions below are for sending plain-text messages to a one-time list via LISTSERV. If you wish to send MIME-encoded mail messages (for instance, to send encoded binaries or HTML mail), you must create and add the appropriate MIME headers along with the file (in the case of an encoded binary) to be sent.
The example described here is for 1.8d running with the default of DIST_SECURITY=1 in the site configuration.
A very basic RFDR job is shown below. This job would be sent to LISTSERV@NODE, where NODE is the NODE= site configuration setting for your local LISTSERV server.
Below is a detailed description of each element of the job.
The JOB "card" is the required first line of any RFDR job. It signifies to LISTSERV that everything that follows in this particular message is part of the same job. In this case we have called the job WIDGET1. Each RFDR job should have a name, but if for some reason you don't want it to, you simply format the JOB card with a space between "//" and "JOB".
This is the actual DISTRIBUTE command that tells LISTSERV that this is an RFDR job, and that specifically you want LISTSERV to distribute a piece of mail. PW=XXXXXXXX is part of the security mechanism described in 3.1. You replace XXXXXXXX with your personal LISTSERV password that you've previously set with LISTSERV's PW ADD command.
This part of the job tells LISTSERV to whom you want the mail distributed. There are a few options for the addresses themselves as you've probably noticed. The basic syntax for an address in the "To DD" is as follows:
userid@host.domain [Personal Name] [BSMTP | PROBE]
for instance, any of the following are correct: Jane Customer BSMTP PROBE Jane Customer PROBE
The only part of this syntax that is required is the first token (userid@host.domain). You can follow it with the user's personal name, if available. Then you can add the token "BSMTP", which tells LISTSERV to use "Batch SMTP" processing for this address, or the token "PROBE", which tells LISTSERV to send the message to the specified address as a passive PROBE. Please note carefully that the BSMTP and PROBE options cannot be used together for the same address.
If you use the BSMTP option, it isn't necessary to specify a "personal name" as LISTSERV won't use it for anything. BSMTP jobs are sent out in the same manner as regular LISTSERV list mail for users who have the FULLBSMTP user option set; that is, the To: line of the mail contains the address you have specified on the To: line in the data (message text) portion of the RFDR job. This is the most efficient way to send mail via DISTRIBUTE as it "bundles" recipients into a few large outgoing jobs rather than creating a separate outgoing job for each recipient. If you need to "personalize" each message then you do not want to use the BSMTP option. However, most large RFDR jobs will probably be sent using BSMTP since it is more efficient.
If you do not use either BSMTP or PROBE and use just the e-mail address, e.g., or Jane Customer, the recipient's e-mail address will be specified in the To: field, regardless of what you define in the To: field header further down in the job. As noted above, this is an attractive way to do the mailings but uses FAR more resources since you are creating a separate outgoing copy of the message for each subscriber. The marketing benefits of personalized mail are obvious but not using BSMTP is something that you should test to see if the return is worth the cost. Utilizing BSMTP allows your job to be processed as if it were a traditional LISTSERV list and should be used when greatest efficiency is desired.
The "/*" at the end of the "To DD" is required and may not be omitted. It tells LISTSERV where the DD ends. It must be on a line by itself. If it does not exist in the job stream, the job will fail.
This card tells LISTSERV where the actual message begins. There is no end card for the "Data DD" as it ends at the end of the message you send the job in. This is important to note as it means that you must disable any signature file that normally is sent with your mail--otherwise it will appear as part of the RFDR job and be sent out!
Following the "Data DD" job card are the RFC822 message headers for your message. The only required headers here are Date:, From:, and To:. However, while you do not technically need to provide a Subject: or a Reply-To: field, you will probably want to do so for completeness' sake. There is no specified order for these header fields so you may arrange them as suits you best.
If you do not specify a value for the Date: line, but rather simply insert a "Date:" header without a following value, LISTSERV will insert its local time and date as of when it received the job for execution. In the following example:
LISTSERV will fill the Date: header in by itself. Otherwise LISTSERV will accept any Date: field you provide without comment. If on the other hand you do not at least specify a "Date:" header line, no date will be inserted at all.
If you do not specify a From: line, LISTSERV will insert a From: line containing the address of the command invoker (you!) unless you have specified a FROM= option in the DISTRIBUTE command (see either below or in the preceding technical section for specific DISTRIBUTE options), in which case the value of the DISTRIBUTE FROM= option will be inserted. It is probably wise in most cases to ensure that there is a From: line in the "Data DD" as otherwise the result may not be as you planned.
If you do not specify a To: line, LISTSERV will insert a To: line as follows:
To: Multiple recipients <LISTSERV@NODE>
where "NODE" is the NODE= value for your LISTSERV server. As with the From: line, this is probably not what you want people to see, so you have a couple of options. For jobs which contain only BSMTP recipients, you should specify a To: value, which should point back to a real address in case someone decides to write back to it. For instance, in our example above,
and we'll assume that "" is a customer-service address where people can write, or even an existing LISTSERV list out of which you've pulled a subset of addresses for this particular RFDR job.
If you have all non-BSMTP and non-PROBE recipients, you can simply leave the To: field blank (as with Date:, above) and LISTSERV will fill the field in with the data you've provided in the "To DD". For instance, in the following example,
both the Date: and To: fields will be filled in by LISTSERV for you.
Please note that the blank line at the end of the RFC822 headers is not a misprint. According to RFC822 you MUST provide a blank line between the last header and the beginning of the message body, and LISTSERV expects it to be there. If it is not there, the job will fail with an RFC822 parser error:
Invalid RFC822 field found in mail header: "Your text here--forgot blank line". Mail not delivered.
Finally, we get to the final element: the message body.
This element is fairly self-explanatory; you simply add the actual body of the message you are sending out. Again, make sure that there is a blank line between the body of the message and the last RFC822 header as mentioned previously.
9.3.1 RFDR Job Options
There are three options that might be of use in the JOB card (the first line of the RFDR job as noted above). These options are:
This option suppresses the resource usage summary you would otherwise get upon completion of your delivery. Omitting it returns a mail message containing a summary like the following example to the e-mail address from which the RFDR job was sent.
Summary of resource utilization
To use this option and suppress the summary from being sent, simply type ECHO=NO at the end of the JOB card, e.g.,
This option controls the time period during which LISTSERV should not process the job.
Note: To all intents and purposes, this option is obsolete. It was originally designed for mainframe environments in which job scheduling was critically important, so that LISTSERV could process large jobs during non-"prime" time and not be a load on the processor during "prime" time. Therefore, and perhaps counter-intuitively to some, it defines the time period during which LISTSERV SHOULD NOT process the job. In LISTSERV 1.8e, the AFTER= RFDR job card option was added to LISTSERV to help with scheduling jobs that should be held until a particular time and then released. Therefore the use of PRIME= is deprecated for that type of job.
This function of this option is identical to the function of the "Prime=" keyword setting for LISTSERV mailing lists, where "Prime=" defines (on a list by list basis) times during which LISTSERV should not process mail for the list. By default this option is set to "PRIME=Yes", meaning that the job can be processed at any time. If you set this option to "PRIME=No", it uses the value set globally by LISTSERV's PRIMETIME= site configuration variable, which by default is set to have no prime time (in other words, by default, mail can still be processed at any time even with "PRIME=No"). The PRIME= option for RFDR jobs can be set to an explicit time definition if necessary. For instance, you might have a very large RFDR job (e.g., a newsletter) that should not be processed until after midnight (when network traffic is low and more machine resources are generally available).
RFDR jobs sent to LISTSERV during prime time are automatically held until non-prime time and then distributed normally, without requiring further intervention by anyone. For instance you could set the "PRIME=" option to
PRIME="MON-FRI: 00:00-23:59"
This means that you could send the job anytime during the regular work week--Monday morning through Friday afternoon--and know that it won't be distributed until Friday at midnight or shortly thereafter.
As another example, if you want the job only to be processed between midnight and 6 AM on weekends, you might set it to
PRIME="MON-FRI: 00:00-23:59; SAT-SUN: 06:00-23:59"
Note: The specifications for PRIME= must be enclosed in quotes and the format (spaces) should be identical to the examples.
Important: You should always leave yourself at the very least an hour processing window, and even more so for large jobs, since PRIME checks are done once each hour, on the hour, and very large jobs may require extended processing time. However, you should also be aware that all jobs are checked for PRIME= time when they are received, and if they are within the allowed time window, they are executed immediately.
Notes: The default value for seconds in a PRIME time specification is zero. Therefore, specifying "00:00-23:59" is equivalent to specifying "00:00:00-23:59:00", not "00:00:00-23:59:59", and, in this example, there is actually a one-minute "window" each night between 23:59 and 00:00 in which an arriving job could be processed. You may code the seconds in the time specification if it is vitally important that no mail be processed during that one-minute "window".
Also note that if running in Network mode, even more time is required since jobs passed across the LISTSERV network for other servers to deliver also contain the PRIME setting, and depending on which time zone it is passed to, it may miss the "window" altogether. For example,
PRIME="MON-FRI: 00:00-23:59; SAT-SUN: 06:00-23:59"
leaves six hours of processing for your DISTRIBUTE job on Saturday and Sunday, i.e., 12 hours total processing time over the two days. So if the job does not get to, say, a server in Japan before the PRIME deadline on Saturday, it will be processed the next day during non-prime time. In actuality it is probably not necessary to use such small windows on the weekend, so
PRIME="MON-FRI: 00:00-23:59"
is probably all you would need for a job to be delivered over the weekend.
To use the PRIME option, simply type it following the JOB operand. If you need to specify ECHO=, note that it must follow PRIME= or a syntax error will result. For example:
Make sure that you test the PRIME= option setting with test jobs first to make sure that the proper syntax is being used before sending mission critical jobs to be processed during off-prime hours.
The preferred method of delaying a message's distribution is to use the AFTER= JOB card option. As noted in Section 2.3 The JOB Control Card, you can specify
until which LISTSERV will hold the job.
Using AFTER= instead of PRIME= has the added advantage of not specifying a "window" of time during which the job can be processed which is propagated along with the job to other servers (which can delay distribution if the window is too small). Once the scheduled time arrives, the job will be processed without any consideration to how long it may take to run.
As with PRIME=, if ECHO= is specified, it should be the last token on the line.
9.3.2 DISTRIBUTE Command Options
There are six options that might be of use in the DISTRIBUTE command (the second line of the RFDR job as noted above). These options are:
This option tells LISTSERV to confirm deliveries with an acknowledgement sent by mail (the default is not to send delivery confirmations, but rather to simply acknowledge receipt and processing of the job), as in the following example (note that ECHO=YES in the JOB card for this particular example):
Use of this option in the DISTRIBUTE command line is as follows:
Other than the default ACK=NONE, the only other setting for this option is "MSG", which is obsolete except for NJE servers.
This option produces a report showing how the various recipients will be routed over the LISTSERV backbone, but WITHOUT actually delivering the message. Before sending out your actual posting, you may want to send the RFDR job with this option enabled to see how the mail will be routed.
Examples of the use of this option in the DISTRIBUTE command line:
This option produces a report showing how the various recipients will be routed over the LISTSERV backbone, and actually delivers the message (similar to DEBUG=YES but the message is actually delivered).
Examples of the use of this option in the DISTRIBUTE command line:
This option can point to a particular address that will receive the bounced mail, notifications of delivery problems, etc. Specifically this option sets the RFC821 MAIL FROM: address to which all compliant mailers will bounce non-deliverable mail. The single parameter netaddress is an Internet address in the standard format (userid@host.domain).
Examples of the use of this option in the DISTRIBUTE command line:
Requires LISTSERV Classic/Classic HPO 1.8e, with LISTSERV's anti-virus feature enabled.
By specifying "AV=YES", you direct LISTSERV to check the message for viruses and terminate distribution if ANY errors occur. This includes internal virus scanner errors that do not necessarily indicate the presence of a virus, out of memory errors, invalid base64 data errors, you name it.
While very safe, there is obviously the drawback that critical messages may be suppressed due to problems within the virus scanner. It should be up to the customer to decide what to do in such cases. "AV=YES,FORCE" tells LISTSERV to stop ONLY if a virus has been found. The drawback is that viruses may be let through if there was a problem with the virus checker (this includes expired maintenance), insufficient memory, or any other problem that would otherwise have caused LISTSERV to terminate the distribution. For obvious reasons, therefore, L-Soft does not recommend the indiscriminate use of the FORCE option.
"AV=NO" is also available, but does not need to be explicitly coded. This is the default and the only valid option for DISTRIBUTE of an NJE FILE (VM/VMS only) and DISTRIBUTE RFC822 (although it is doubtful that this DISTRIBUTE type is used by anyone anymore).
This option is not forwarded. It is compatible with the backbone, but checking only occurs at the originating site.
IMPORTANT for mail-merge: For performance reasons, virus checking is done only once, not for each recipient after substitution. It is theoretically possible for a virus to escape undetected if it is constructed from a combination of message text and substitution data, especially if the substitution comes from a database.
In addition, certain types of sophisticated mail-merge jobs may incorrectly raise the invalid MIME data error. This could happen if the base64 data were fetched from a database, or if it were included in a .BB/.EB block. Again, all you need to remember is that LISTSERV scans the message template rather than the X million individual substituted messages, so viruses that do not exist in the template will not be detected. The expected usage for correct scanning is something like this:
.BB whatever
--blah boundary
content-type: application/msword; blah blah
content-transfer-encoding: base64
Requires LISTSERV Classic/Classic HPO 14.5 or later, with LISTSERV's DomainKeys signing engine enabled (see Using LISTSERV with DomainKeys for implementation details).
A new DKIM=NO|YES option has been added to DISTRIBUTE (default: NO). This will fail in two cases:
Otherwise the DomainKeys signing always succeeds. Messages originating from domains for which LISTSERV has been configured to sign will be signed, while those originating from other domains won't be.
9.4 Advanced LISTESRV Applications Using DISTRIBUTE
Depending on your specific needs, it is possible for sites to "get creative" and use traditional LISTSERV lists as "back-ends" in conjunction with DISTRIBUTE jobs to handle bounces in the same way they are handled for a regular LISTSERV list, without ever using the list itself for posts.
Let's say that, to begin with, you collect addresses from a guestbook web page that you've set up for your company. You want to send out periodical updates to these people using RFDR "DISTRIBUTE" jobs but you know that you are going to have the usual 15-20% or more bad addresses from typos, pranksters, and plain old attrition. How do you find the bouncing addresses so you can purge them from your database without having to read each bounced message and determine what address actually bounced?
Simply create a traditional list with the appropriate error handling setting desired (see other sections of this manual and of the List Owner's Manual for LISTSERV for more information). Set "Change-Log= Yes" and "Auto-Delete= Yes,Full-Auto,Delay(0)" in the list's header ("Change-Log" requires LISTSERV 1.8d and later). Use an ADD IMPORT job as detailed in chapter 4.3 of the List Owner's Manual to add all of the addresses from your database to the list.
Then, in your RFDR job, set the following in the FROM= option of the DISTRIBUTE command line:
where listname is the name of the list created. For instance, if the list was named bouncelist1 and the LISTSERV host name was LISTSERV.EXAMPLE.COM, then the DISTRIBUTE command would be as follows:
Once you have the bounce list set up (and we'll continue to use our bouncelist1 example), you simply check the BOUNCELIST1.CHANGELOG file for a listing of addresses LISTSERV has auto-deleted from bouncelist1 since you sent out your RFDR job. You can then use this changelog file to update your database and clean out the bad addresses.
Do keep in mind, however, that in order for LISTSERV to take action on permanent bounces that come to the owner-bouncelist1 address and are, furthermore, in a format understandable by LISTSERV, the bouncing address(es) must also be listed as subscribers in the back-end bouncelist1 list (so do not forget to bulk add the addresses before sending the DISTRIBUTE job, as explained above).
To take this a step further, you could also use this same back-end bounce processing list as a front-end list to handle automatic subscribe and unsubscribe requests for each mailing, allowing for total flexibility for both yourself and the customers being mailed to.
9.4.1 "List-free" bounce processing for one-shot lists
This feature is not available for LISTSERV Lite or for LISTSERV Classic running on VM.
You can bounce-process a one-shot list without needing a back-end list for the bounces to come back to (as outlined above).
To use the "list-free" feature, you create and send a standard DISTRIBUTE MAIL-MERGE job with the FROM= address set to OWNER-NOLIST-xxx@hostname (where 'xxx' can be anything and 'hostname' is LISTSERV's host name), for instance OWNER-NOLIST-MYDIST@LISTSERV.MYHOST.COM. While 'xxx' can be anything, OWNER-NOLIST@whatever doesn't work--you must provide '-xxx'. Within the job you then use PROBE for each address in the manner documented above.
Note: This feature requires that you send the job as a mail-merge message using DISTRIBUTE MAIL-MERGE, even if the job is not a mail-merge job. The feature does not work with DISTRIBUTE MAIL. In addition, you MUST have EMBEDDED_MAIL_MERGE enabled, and you must use SMTP "workers" (i.e. you must have SMTP_FORWARD_n= variables set in your site configuration file so that LISTSERV sends mail to its outbound mailers in asynchronous mode).
After sending the job, you get a NOLIST-xxx.CHANGELOG in LISTSERV's A directory with entries for every bounce. (In our example above, this file would be called NOLIST-MYLIST.CHANGELOG.)The entries read BOUNCE followed by the e-mail address. As there is no monitoring and no decision to delete, the entry does not read AUTODEL, and thus bounce reporting for "list-free" DISTRIBUTE jobs is passive. By definition, however, you can't monitor one-shot jobs; monitoring (if desired) must be provided by collating all the one-shot jobs into a big monitoring database, or something similar (all jobs from client such and such, etc.).
Note: If you are running under unix with sendmail, you will have to patch sendmail in order for it to properly accept and route bouncing probe messages. As a convenience, L-Soft provides third-party sendmail patches for this purpose on its FTP site (in Please be aware that L-Soft did not write and does not support these patches in any way; they are strictly for use at your own risk and you must contact the author(s) of the patches for help with them.
9.4.2 Sending Pre-Approved Messages to Moderated Lists
It is sometimes desirable to send mail to a LISTSERV list with Send=Editor,Confirm, Send=Owner,Confirm, or Send=address,Confirm, and have it go out immediately, rather than wait for the editor to confirm it. Thus, there needs to be a mechanism for password-confirming a posting to a list as a substitute for the e-mail confirmation handshake.
To provide this mechanism, the DISTRIBUTE POST command was added beginning with LISTSERV 14.3. The syntax is based on the existing DISTRIBUTE MAIL command, with certain important differences:
The verb is POST instead of MAIL. Data and recipient are supplied as usual. For example, TO xxx, TO DD=xxx, or implied DD.
Only one recipient (the address of the list to which you are posting) is allowed in the TO DD; anything else is will generate an error message. Automated scripts should guard against supplying more than one recipient.
Although an FQDN is required in the TO DD, the hostname of this recipient is assumed to be an alias for the local host, and is ignored. The local-part must be a valid, existing list. An error message will be generated if this is not the case.
The PRE-APPROVED=NO|YES option becomes available to DISTRIBUTE POST. The default is NO and it then works like a DISTRIBUTE MAIL job with the list as sole recipient, except that it is more efficient. You must be a list owner to use PRE-APPROVED=YES. PRE-APPROVED=YES cannot be used with DISTRIBUTE MAIL and will generate an error message if so used. If the list is moderated, and the sender address is not an editor, the e-mail sent in this way will be submitted for moderation. To clarify: this replaces confirmation not moderation approval. Make sure that the poster's address (in the 'From:' line) is authorized to post to the list, or the message may be rejected or forwarded to the moderator. PRE-APPROVED=YES authenticates the origin of the message, but does not bypass the normal authorization steps.
DISTRIBUTE POST is not available under VM.
Distribution options are ignored, since DISTRIBUTE does not deliver the message at this time but passes it on to the list posting mechanism.
It is important to understand that DISTRIBUTE POST is just a submission system. The posting may be processed immediately, it may be delayed until the time specified in the list header, it may be sent to the moderator if the owner is not allowed to post to the list (perhaps not very common, but there are such lists), the list could be on hold, a virus could be detected (if you did not use AV=YES), etc.
Following is a list of the DISTRIBUTE options supported or partially supported with DISTRIBUTE POST.
Full support:
Partial support:
DD=: TO DD must refer to a list.
DEBUG=YES: The job will be executed with all verifications, but in the end the message will not be posted (this is the primary purpose of DEBUG=YES). The secondary purpose, to receive a report showing the intended message routing, number of recipients and so on, is not supported since DISTRIBUTE POST always sends 1 local message and forwards 0 jobs to other servers.
Other options are ignored as long as the syntax is correct. If there is a syntax error, the job fails.

In LISTSERV Classic only, DISTRIBUTE Jobs sent to LISTSERV Lite servers are handled exclusively by the local server and the DISTRIBUTE backbone is not employed.

L-Soft international, Inc.