COURIERMLM(1) | Double Precision, Inc. | COURIERMLM(1) |
NAME¶
couriermlm - The Courier mailing list manager
SYNOPSIS¶
couriermlm {command} {directory} [arg...]
DESCRIPTION¶
couriermlm is the Courier mail server's mailing list manager. This command sets up, maintains, and manages mailing lists. couriermlm automatically handles requests to subscribe and unsubscribe list members, detects undeliverable addresses and removes them from the subscription rolls. Mailing lists managed by couriermlm require zero human administrative oversight. couriermlm supports digests, write-only posting aliases, and moderated mailing lists.
CREATING A MAILING LIST¶
Anyone can use couriermlm, not just the system administrator. The Courier mail server mail server translates an address list-name@domain as a local address with a corresponding dot-courier(5)[1] file. Anyone that can install a dot-courier(5)[1] file, and can schedule cron(8) jobs, can run a couriermlm mailing list.
Note that the system administrator can optionally remove the dot-courier(5)[1] support from the the Courier mail server. couriermlm will not work in that case.
Setting up a mailing list consists of the following steps:
Run couriermlm create
Configure the mailing list
Create dot-courier(5)[1] files
Set up cron(8)
Enable SMTP pre-filtering
This is an optional step that adds some complexity, but reduces mailing list management issues.
Back up subscription lists
Note
Setting up a digest for the mailing list requires additional steps. See "Setting up a mailing list digest[2]" below for more information.
The first step is to run the following command:
couriermlm create directory ADDRESS=list@domain
directory is the mailing list directory that will be managed by couriermlm. This directory should not be created in advance, this command creates this directory, and initializes it.
list@domain is the mailing list's address, the address that sends messages to the mailing list.
An additional setting, URL may also be specified:
couriermlm create directory ADDRESS=list@domain URL=url
“url” would be the URL of the WebMLM web page for this mailing list. See webmlmd(1)[3] for more information.
The directory created by couriermlm create is initialized to contain a number of text files that couriermlm sends back as replies to administrative commands. It is necessary to edit these template files and adjust the text in those files for this mailing list. All template filenames end with .tmpl, and their contents are self explanatory. Some important template files are:
help.tmpl
sub.tmpl
sub2.tmpl
couriermlm has rudimentary support for non-English templates. The couriermlm create command has a single, optional parameter, --lang=suffix The option must be specified after the mailing list directory's name:
couriermlm create directory --lang=es ADDRESS=list@domain URL=url
The templates for the stock text files come from /usr/lib/courier/couriermlm. This directory contains all the *.tmpl and *.html template files that couriermlm create installs in the new mailing list directory.
Translated versions of template files are installed in the same directory, /usr/lib/courier/couriermlm. The translated version of file must be installed as file.suffix, for example: help.tmpl.es is the translated version of help.tmpl, with the “es” suffix.
The --lang=suffix option installs the the .suffix version of each text template file, if available. If not, the stock English template file gets copied, as usual.
Note
Do not remove the English template files, even if you never use them. They must be left in place, in /usr/lib/courier/couriermlm, for couriermlm create to work correctly.
Example:
couriermlm create /home/lists/users-list --lang=es ...
This example installs the *.es versions of mailing list template files. Only the stock, English template files come with the Courier mail server. This mechanism only provides an easy integration ability with template files from other sources.
There are some additional configuration files that can be modified to suit your taste:
headeradd
headerdel
Received: Date:
Both the headeradd and headerdel files can be used to implement a popular feature of setting the replies to every message to go to the mailing list. Having "Reply-To:" in headerdel, removes any existing Reply-To: header, and then having "Reply-To: list@domain" in headeradd appends a fixed Reply-To: header to every message.
The create command also creates the following subdirectories in the mailing list directory:
sublist
unsublist
commands, commands.dat
modqueue
archive
The last step involves installing a couple of dot-courier(5)[1] files that run couriermlm to receive mailing list messages and administrative commands. The mailing list address, list@domain, corresponds to some dot-courier(5)[1] file. For example, if your system account is john, and your mail domain is example.com, then the dot-courier(5)[1] file for the mailing list <john-list@example.com> is $HOME/.courier-list.
Let's say that the dot-courier(5)[1] file is $HOME/.courier-list. To properly support the mailing list, the following dot-courier(5)[1] files will have to be initialized as follows:
$HOME/.courier-list
| /usr/bin/couriermlm msg directory
Note
Messages to “POST=subscribers” lists from non-subscribers get rejected by couriermlm resulting in delivery failure. This generates a undeliverable message report, a “bounce”. Unfortunately this can be abused to generate a bandwidth amplification attack. Append "; exit 0" to the .courier command, to suppress bounces from delivery failures:
| /usr/bin/couriermlm msg directory; exit 0
$HOME/.courier-list-owner
$HOME/.courier-list-default
| /usr/bin/couriermlm ctlmsg directory
Configuring SMTP pre-filtering of mailing list messages¶
This is an optional step that implements filtering of mailing list messages before each message is received from the sending SMTP server. Otherwise, Courier accepts all messages, and the rejected ones generate a non-delivery report. The report gets E-mailed to the purported sender. Another option is to quietly ignore the rejections, as described above. Either way, non-delivery notifications can sometimes be problematic. This step adds some complexity to the mailing list configuration, but mostly eliminates this problem.
SMTP pre-filtering uses the localmailfilter(7)[5] interface. The following instructions repeat some of the information from the localmailfilter(7) documentation, for convenience. See that documentation for complete information.
The following instructions reference a typical mailing list configuration setup:
The first two steps enable SMTP mail filtering using maildrop, and this should be done as root:
# echo /usr/bin/maildrop >/etc/courier/maildropfilter
Note
This enables SMTP mail filtering to all local mailboxes. All local mailboxes will be able to specify their SMTP mail filters, as explained in localmailfilter(7).
The second step installs couriermlm wrappers for SMTP filters:
# mkdir /etc/courier/maildroprcs # d="/usr/lib/courier/couriermlm" # ln -s $d/couriermlm-rcptfilter-ctlmsg /etc/courier/maildroprcs # ln -s $d/couriermlm-rcptfilter-msg /etc/courier/maildroprcs # ln -s $d/couriermlm-smtpfilter-ctlmsg /etc/courier/maildroprcs # ln -s $d/couriermlm-smtpfilter-msg /etc/courier/maildroprcs
The remaining steps are done while logged in as the mailing list owner's account:
$ mkdir $HOME/.mailfilters $ chmod 700 $HOME/.mailfilters
Each mailing list needs four maildrop scripts installed in .mailfilters. Using the “lists-announcements@example.com” list as an example, owned by lists's account:
$ cd $HOME/.mailfilters $ cat rcptfilter-announcements LISTDIR="announcements" include '/etc/courier/maildroprcs/couriermlm-rcptfilter-msg' $ cat rcptfilter-announcements-default LISTDIR="announcements" FILENAMEPREFIX="rcptfilter-announcements" include '/etc/courier/maildroprcs/couriermlm-rcptfilter-ctlmsg' $ cat smtpfilter-announcements LISTDIR="announcements" include '/etc/courier/maildroprcs/couriermlm-smtpfilter-msg' $ cat smtpfilter-announcements-default LISTDIR="announcements" FILENAMEPREFIX="smtpfilter-announcements" include '/etc/courier/maildroprcs/couriermlm-smtpfilter-ctlmsg'
And the permissions must be nailed down, as always:
$ chmod 600 $HOME/.mailfilters/*
Each maildrop script sets the LISTDIR variable before invoking the couriermlm wrapper. LISTDIR is the name of the mailing list's directory, in the account's home directory. In this case the mailing list directory, created by couriermlm create is $HOME/announcements, so LISTDIR is announcements. It's possible to put mailing list directories in a subdirectory, and reference the subdirectory here. Mailing list directories' names cannot contain periods.
Additionally, the two -default scripts must set FILENAMEPREFIX to their own names, with the “-default” suffix stripped off.
The easiest way to test this configuration is to use the default mailing list configuration that allows messages only from the list's subscribers, then attempt to send a message to the mailing list, from another SMTP server, using a return address that's not subscribed to the list. The resulting non-delivery report should come from the other SMTP server, and not couriermlm's mail server.
MANUAL COMMANDS¶
couriermlm may also be run manually from the command line as follows:
/usr/bin/couriermlm command directory [ options... ]
command is a command from the following list. directory is the mailing list directory. The commands are:
create
update
Yes, this is going to be a pain. This is the first overhaul of couriermlm's infrastructure in many years. Once a decade, some elbow grease must be sacrificed in the name of progress. It's not the end of the world.
In an extreme emergency, preserve the couriermlm from the previous version of the Courier mail server. Mass-update all existing lists' .courier-list and .courier-list-default files to run the old couriermlm. Then, migrate each mailing list on a predetermined schedule. After migrating each list, put the default path back into the list's .courier files.
Keep in mind the following issues, while migrating the lists:
set
sub
unsub
lsub
laliases
export
import
ctlmsg
info
msg
hourly
daily
digest
MANUAL SUBSCRIPTION MANAGEMENT¶
The sub, unsub, lsub, laliases, export, and import commands allow manual subscription list management. Normally, subscription-related commands are done by sending an appropriate mailing list command, see "Mailing List Commands[4]", below.
couriermlm sub directory user@domain
This command adds the address <user@domain> to the subscription list. couriermlm will now read a free-form comment or a note from standard input, terminated by an end-of-file (usually CTRL-D). The free-form comment is stored in the subscription database, together with the address, and is shown by the "info" command.
couriermlm unsub directory user@domain
This command remove the address <user@domain> from the subscription rolls. couriermlm will also read a free-form comment, which is added to the subscription record. After removing this address from the subscription rolls, its subscription record is archived in the directory/unsublist directory.
couriermlm lsub directory
This command lists all the addresses subscribed to the list, on standard output, one per line.
couriermlm laliases directory
This command lists all write-only aliases that have been subscribed to the list, together with the subscriber address that added each alias. See "Write-Only Aliases[6]" for more information.
couriermlm export directory
The export command lists the contents of the subscription database on standard output. The export command produces the following output format:
address subscription information
... address subscription information
...
"address", is an address subscribed to the mailing list. This is followed by its corresponding subscription information, usually a copy of the subscription request that was used to add the address to the mailing list. The subscription information is terminated by a line containing a single period. Any lines in the subscription information that begin with a period have an extra period prepended to them.
couriermlm import directory
The import command reads on standard input a previously exported mailing list subscription database, and adds those addresses to the indicated mailing list.
It is highly recommended to make a regular backup of subscriber information using the export command, in the event that the subscription database gets corrupted. In which case the import command can be used to rebuild the subscription database, in absence of any direct backups of the database files.
SETTING MAILING LIST OPTIONS¶
The set command sets various list options:
couriermlm set directory option=value option=value...
Note
Setting the ADDRESS or the URL options, described below, automatically updates the contents of the headeradd configuration file. Its existing “List-” headers are removed and replaced by updated “List-” headers that reflect the revised list address or URL.
One or more options can be set with the same command. The available options are:
ADDRESS=address
URL=address
Note
WebMLM determines its own URL automatically, by reading its HTTP headers. This setting is used by couriermlm, which has no knowledge of the web server's configuration, and needs to know the correct URL to insert into generated messages.
CASESENSITIVE=flag
Note
Be careful when changing this setting on an active list. Changing this option to “CASESENSITIVE=1”, forces all existing subscribers to make sure their addresses are lowercase-only, otherwise they will no longer be recognized as subscribers. Changing this option to “CASESENSITIVE=0” blocks all subscribed addresses that have uppercase characters in the userid portion of their E-mail address. They will continue to receive mailing list traffic, but unable to post messages to the list, or unsubscribe from it. It will not be possible to unsubscribe those addresses even by running the couriermlm command manually.
DIGEST=directory
KEYWORD=keyword
MAXBOUNCES=n
MAXMODNOTICES=n
MAXFETCHSIZE=K
NAME=name
NOBOZOS=flag
NODSN=flag
POST=option
UNICODE=flag
Most mail servers on the Internet do not implement support for Unicode messages at this time. Accepting a Unicode message and redistributing it to a mailing list results in delivery failures to all mailing list subscribers that do not implement Unicode support, so by default this setting is turned off. Set UNICODE to 1 to accept mailing list messages with Unicode headers, and subscription requests from Unicode mailbox names.
Note
Subscription requests from E-mail addresses that have an international domain name are always accepted if the internal domain name uses ASCII-compatible encoding.
POSTARCHIVE=option
PURGEARCHIVE=d
PURGEBOUNCE=d
PURGECMD=h
REMODERATE=h
REPORTADDR=address
SIMPLECONFIRM=n
Note
The text in sub.tmpl, unsub.tmpl, and help.tmpl may need adjusting.
SUBSCRIBE=option
STARTPROBE=n
Option names and settings are case sensitive.
Note
If you set up a digest list, you MUST set identical POSTARCHIVE option for both the main list and the digest list.
DISPLAYING A SUBSCRIPTION RECORD¶
The info command displays the subscription record for the requested address:
couriermlm info directory user@domain
This displays the subscription record for "user@domain", which typically consists of a copy of the initial subscription request, and confirmation.
SENDING MESSAGES TO THE MAILING LIST¶
The msg commands reads an E-mail message on standard input, and mails the contents of the message to the mailing list's subscribers.
If the POST option is set to "subscribers", the message is rejected unless the address in its From: header is a subscriber to this mailing list.
Control files headeradd and headerdel are read, and are applied to the message, as described previously.
MAILING LIST COMMANDS¶
Mailing list commands can be sent via E-mail to couriermlm by sending a message to <list-command@domain>. The "default" dot-courier(5)[1] file runs couriermlm to receive mail for all addresses of this form.
couriermlm reads the DEFAULT environment variable, which is set by the Courier mail server, that indicates the specific command. The available commands are:
help
subscribe
subscribe-name=domain
unsubscribe
unsubscribe-name=domain
alias-subscribe
alias-subscribe-name=domain
There are other commands that are used internally for maintaining the mailing list.
WRITE-ONLY ALIASES¶
Write-only E-mail aliases can send messages to the mailing list, but they do not receive any mailing list messages themselves. A write-only alias can be set up by any subscriber. Only one write-only alias is allowed per subscribed E-mail address. Write-only aliases are not needed for mailing list that has the POST=all option set.
To set up a write-only alias, the subscriber sends a couriermlm alias-subscribe command. The subscriber's E-mail address can be explicitly specified in a similar manner as the subscribe command.
The subject line of the E-mail message must contain the E-mail write-only alias to be set up, and nothing else. couriermlm responds with a confirmation request, just like when subscribing to the list. This request must be acknowledged in the same way.
A subscriber's write-only alias can be changed at any time by repeating this procedure. The new alias replaces the previous one. To prevent abuse, there's a limit of at most one alias-subscribe command every 30 minutes.
Leave the subject of the E-mail message blank in order to remove an existing write-only alias,
SETTING UP A MAILING LIST DIGEST¶
couriermlm supports mailing list digests. Mailing list digests are created as a second, separate, mailing list. The create command initializes a second mailing list directory, and then additional configuration takes place which links the main mailing list to the digest list.
If the mailing list address is list-address@example.com, the address of the digest version of the mailing list is usually list-address-digest@example.com, but it doesn't have to be this address. The only requirement is that the directory for the digest version of the mailing list must reside on the same file system as the directory for the mailing list itself, and both must be owned by the same userid.
To set up a mailing list digest, first proceed with the steps to create the mailing list itself. After the mailing list is created and configured, proceed as follows:
Create the digest list directory
/usr/bin/couriermlm create \
/path/to/digest/list/directory \
ADDRESS=list-address-digest@example.com
Configure the digest list
Link the two lists
Note
You MUST set identical POSTARCHIVE option for both the main list, and the digest list.
Create dot-courier(5)[1] files
Create cron(8) jobs
Create a digest cron(8) job
The main mailing list is supported by three dot-courier(5)[1] files, as previously described: the posting address, the owner forwarding address, and the default address that handles administrative control messages. In the following example, the names $HOME/.courier-list, $HOME/.courier-list-owner, and $HOME/.courier-list-default are used to represent each one of these files, and the following names are used to represent the dot-courier(5)[1] files that correspond to the digest version of the mailing list: $HOME/.courier-list-digest, $HOME/.courier-list-digest-owner, and $HOME/.courier-list-digest-default. Note, however, that the digest version of the mailing list can have any name, not necessary the name of the list, followed by "digest".
The contents of both $HOME/.courier-list $HOME/.courier-list-digest must be the same. Sending a message to the digest address should really end up sending a message to the main mailing list. Do not put the address of the digest mailing list directory in $HOME/.courier-list-digest, instead specify the address of the main mailing list directory. Just copy $HOME/.courier-list to $HOME/.courier-list-digest.
However, the contents of $HOME/.courier-list-digest-default must specify the directory of the digest version of the mailing list. The digest list is managed separately from the main list, it has its own subscriber list that is separate from the list of subscribers to the main list. $HOME/.courier-list-default can simply be copied to $HOME/.courier-list-digest-default, then the directory can be changed in the latter.
$HOME/.courier-list-owner may use the same mailing list owner address as $HOME/.courier-list-digest-owner, or it can specify a different address. The both the digest and the main mailing list can have the same mailing list owner/moderator, or have a different owner/moderator.
The following command must be executed in order to link the two lists together:
/usr/bin/couriermlm set \
/path/to/main/list/directory \
DIGEST=/path/to/digest/list/directory
Setting the DIGEST option on the main list lets couriermlm know that a digest version is available. The DIGEST option must either use an absolute pathname, or a pathname that's relative to the main list directory (NOT the current directory).
When the DIGEST option is set, messages are simultaneously distributed to the mailing list's subscribers, saved in the archive subdirectory of the main list, then placed in the modqueue subdirectory of the digest list. Digest list do not employ moderation -- any moderation must take place on the main list -- so the modqueue subdirectory is recycled to compile individual messages for the digest.
Finally, something needs to be done in order to actually distribute the digest to the digest list's subscribers. This is done by running the following command:
/usr/bin/couriermlm digest /path/to/digest/directory N H
This command creates a digest, and sends it out. The N and H arguments are optional. The digest is created only if there's at least N messages that are waiting to be sent in the digest list, or if the oldest message is at least H hours old. Both options default to 0, so the default behavior is to send a digest with all unsent messages.
Note that when the digest is created, ALL unsent messages are packaged into the digest, even if some messages are more recent than the time interval specified by the H option. A cron(8) job can be set up to run the digest command, or run it manually.
couriermlm automatically provides the From:, To: headers on a message digest. Additional headers may be specified by the headeradd file in the digest list directory. The headerdel file has no effect. Note that the individual messages in the digest are copies of the messages from the main mailing list, and thus have the headeradd and headerdel headers processed from the main mailing list directory.
BUGS¶
couriermlm will not work if the Courier mail server's support for dot-courier(5)[1] extensions is disabled.
SEE ALSO¶
courier(8)[7], dot-courier(5)[1], webmlmd(1)[3].
AUTHOR¶
Sam Varshavchik
NOTES¶
- 2.
- Setting up a mailing list digest
- 3.
- webmlmd(1)
- 4.
- Mailing list commands
- 6.
- Write-Only Aliases
- 7.
- courier(8)
10/28/2020 | Courier Mail Server |