Working with ezmlm

---

Dan Bernstein, the author of qmail, created ezmlm (http://cr.yp.to/ezmlm.html). It was written for use with qmail and relies on several features of qmail. Most notably, it uses Variable Envelope Return Paths (VERPs) to reliably process bounce messages. ezmlm is unique among MLMs in that it doesn't process commands sent to a central MLM address: It appends the command to the name of the list as an extension. For example, to subscribe to the [e-mail] list, one sends a message to [e-mail].

The current version of ezmlm, 0.53, includes the following features:

• Message redistribution—resends list messages to subscriber list using qmail.

• Message archiving and retrieval (single message per request).

• List subscription and unsubscription via e-mail to extension addresses.

• Automatic bounce handling—subscribers are warned about bouncing mail before being removed from the list.

• User-created lists—system administrator or mail administrator isn't required to set up new lists.

• Hashed list storage for quick updates to large lists.

• User-customizable administrative messages.

• Moderated lists—only the list owner can post to the list—as well as unmoderated lists.

• Reliable—list updates and submissions are committed to disk before success is reported.

• Secure—subscription/unsubscription requests are cryptographically secure to prevent forged requests.

ezmlm-idx is an add-on for ezmlm that adds many useful features.

Understanding ezmlm-idx

Fred Lindberg and Fred B. Ringel created ezmlm-idx (http://www.ezmlm.org/), a package that patches and adds to the basic ezmlm distribution. Some of the major features it adds include:

• Multimessage, threaded archive retrieval—grab a whole discussion with a single request.

• Digests—multiple list messages grouped into one message before being sent to subscribers.

• Remote administration.

• Message moderation—list owner can approve all postings to the list.

• Subscription moderation—list owner can approve all subscription requests.

• Subscriber-only restrictions—allow only subscribers to post to the list.

• Message trailers—append list info to messages sent to the list.

• Subject prefixes—identify the list in the Subject field of messages sent to the list.

• Multilanguage and Multimedia Internet Mail Extension (MIME) support.

• Support for storing lists in Structured Query Language (SQL) databases.

Installing ezmlm

You can install ezmlm on any system running qmail. The only prerequisite is the development environment necessary for building C programs.

1. Download ezmlm and, optionally, ezmlm-idx, using your Web browser or a command-line utility. For example:

    $ lynx -dump http://cr.yp.to/software/ezmlm-0.53.tar.gz > ezmlm-0.53.tar.gz $ lynx -dump http://www.ezmlm.org/pub/patches/ezmlm-idx-0.40.tar.gz > ezmlm-idx- 0.40.tar.gz $ 

2. Unpack the archives:

    $ zcat ezmlm-0.53.tar.gz | tar xf - $ zcat ezmlm-idx-0.40.tar.gz | tar xf - $ 

3. (ezmlm-idx only) Merge the ezmlm-idx files with the ezmlm files:

    $ mv ezmlm-idx-0.40/* ezmlm-0.53/ $ 

4. (ezmlm-idx only) Apply the ezmlm-idx patches:

    $ cd ezmlm-0.53 $ patch < idx.patch patching file `ezmlm-warn.1' patching file `ezmlm-return.1' patching file `ezmlm-send.1' patching file `ezmlm-sub.1' patching file `ezmlm-unsub.1' patching file `ezmlm-list.1' patching file `ezmlm.5' patching file `log.c' patching file `MAN' patching file `BIN' patching file `VERSION' patching file `Makefile' patching file `constmap.c' patching file `constmap.h' patching file `error.h' patching file `error.c' patching file `ezmlm-weed.c' patching file `ezmlm-weed.1' $ 

   Note 

   If the patch command fails, try installing the current version of the GNU patch, available from http://www.gnu.org/software/patch/patch.html.

5. (ezmlm-idx only) If your crontab command isn't in /usr/bin, edit conf-cron to contain the correct directory:

    $ type crontab crontab is /usr/bin/crontab $ 

6. (ezmlm-idx only) Configure SQL support, if desired:

For MySQL, edit sub_mysql/conf-sqlcc (include files) and mysql/conf-sqlld (libraries) to reflect your MySQL installation (see the MySQL documentation). The files are preset for Red Hat Linux for Intel. On some systems, the -lnsl should be removed from conf-sqlld. Do make mysql.

For PostgreSQL, edit sub_pgsql/conf-sqlcc (include files) and pgsql/conf-sqlld (libraries) to reflect your PostgresSQL installation (see the PostgreSQL documentation). Do make pgsql.

7. Build the programs and man pages:

    $ cd ezmlm-0.53 # if you're not already there $ make clean # ezmlm-idx only, or ignore error rm -f `cat TARGETS` $ make; make man    many lines of output ending with something like... nroff -man ezmlm-store.1 > ezmlm-store.0 nroff -man ezmlm-request.1 > ezmlm-request.0 nroff -man ezmlmrc.5 > ezmlmrc.0 nroff -man ezmlm-limit.1 > ezmlm-limit.0 $ 

8. (ezmlm-idx only) To select a language other than English for messages, do this:

    $ make iso cp -f ezmlmrc.iso ezmlmrc $ 

where iso is one of the following International Standards Organization (ISO) 639 language designations: cz, da, de, en_US, fr, jp, pl, pt_BR, or sv.

9. Install the programs and man pages:

    $ su Password: rootpassword # make setup ./compile install.c install.c: In function `main': install.c:123: warning: return type of `main' is not `int' ./load install getln.a strerr.a substdio.a stralloc.a \ alloc.a open.a error.a str.a fs.a ./install "`head -1 conf-bin`" < BIN ./install "`head -1 conf-man`" < MAN # 

Testing ezmlm

After installing ezmlm, create a test list to verify that the installation is correct.

1. Make sure that ezmlm-make and qmail-inject are in your path. Create a mailing list:

    $ PATH=$PATH:/usr/local/bin/ezmlm:/var/qmail/bin $ export PATH $ ezmlm-make ~/testlist ~/.qmail-testlist me-testlist domain $ 

Replace me and domain with values from your e-mail address.

2. Subscribe yourself to the list manually:

    $ ezmlm-sub ~/testlist me@domain $ 

3. Send a message to the list:

    $ qmail-inject <<MSG > to: me-testlist@domain > subject: testing > > MSG $ 

You should receive a copy of the message at me@domain.

4. View the list membership:

    $ ezmlm-list ~/testlist me@domain $ 

5. Unsubscribe yourself by e-mail:

    $ qmail-inject -f me@domain me-testlist-unsubscribe@domain < /dev/null $ 

When you receive the confirmation request from ezmlm, reply to it to complete your unsubscription. Use ezmlm-list to verify that the list is empty.

6. Retrieve the test message from the archive:

    $ qmail-inject me-testlist-get.1@domain < /dev/null $ 

You should receive a copy of your test message.

Using ezmlm

The previous testing procedure gave you an example of using ezmlm. We'll look at it a little more closely now.

Creating Lists

With ezmlm, lists can be created and owned by regular users, and have names like username-listname@domain, or they can be created by the mail administrator and owned by the alias user, and have names like listname@domain. Let's call the former user lists and the latter system lists even though they're functionally equivalent and differ only in the user- prefix.

User ezmlm lists are created using ezmlm-make. For example, user bill wants to create a list called bill-isshinryu. His mail system is called example.net. He executes the following command:

 $ ezmlm-make ~/isshinryu ~/.qmail-isshinryu bill-isshinryu example.net $ 

This creates a directory, isshinryu , in his home directory, which contains a set of files and subdirectories.

System ezmlm lists are also created using ezmlm-make, except ezmlm-make is run by the mail administrator. For example, to create a system list called isshinryu, the mail administrator executes the following command:

 $ ezmlm-make /var/qmail/alias/isshinryu /var/qmail/alias/.qmail-isshinryu \ > isshinryu example.net $ 

With basic ezmlm, ezmlm-make supports two list options: archived/not archived and public/private. The defaults for these options are archived and public. When archiving is enabled, ezmlm saves a copy of each message in the list's archive subdirectory. When a list is public, ezmlm responds to administrative requests via listname-request extension addresses.

With ezmlm-idx, ezmlm-make supports many additional options enabling features such as digest sublists, subject prefixes, message moderation, remote administration, subscription moderation, message trailers, and subscriber-only posting. The -e option allows ezmlm-make to modify an existing list, changing only the specified options. See the ezmlm-make man page for complete details.

Creating Lists in Virtual Domains

When creating lists hosted by virtual domains, a couple of adjustments must be made.

For example, say control/virtualdomains contains this:

 lists.example.com:bill-lists 

and bill wants to create an [e-mail] mailing list. Because lists.example.com mail is handled by dot-qmail files starting with .qmail-lists-, he'll tell ezmlm-make to use that prefix on the list's dot-qmail files. For example:

 $ ezmlm-make ~/isshinryu ~/.qmail-lists-isshinryu isshinryu lists.example.com $ 

This creates the list files under $HOME/isshinryu and the dot-files with names starting with .qmail-lists-isshinryu that are symbolic links to files under the list directory.

Also, the inlocal file in the list directory—in this case, $HOME/isshinryu/inlocal—will have to be modified to include the virtual domain manager's username, bill. For example, as ezmlm-make created inlocal, it contains this:

 lists-isshinryu 

It should be changed to this:

 bill-lists-isshinryu 

With ezmlm-idx, lists in virtual domains work without any adjustments.

Subscribing and Unsubscribing

There are two basic mechanisms for updating ezmlm mailing lists: commands executed directly on the list host by the list owner and commands sent by e-mail to ezmlm from the user.

Using List Owner Commands

The list owner commands are ezmlm-sub and ezmlm-unsub, and they're passed the target list's directory and the addresses to be added or removed on the command line:

 ezmlm-sub listdir addresses. . . ezmlm-unsub listdir addresses. . . 

For example, to add [e-mail] and [e-mail] to his isshinryu list, bill would do this:

 $ ezmlm-sub ~/isshinryu [e-mail] [e-mail] $ 

Using ezmlm Command Addresses

The second mechanism for updating lists is via e-mailed commands. This is the method people use to subscribe and unsubscribe themselves. To request that they be added to or removed from a list, people send messages to listname-subscribe@listhost or listname-unsubscribe@listhost. These requests are delivered to ezmlm-manage, which validates them, sends confirmation requests, and processes confirmed requests.

By default, the address that ezmlm-manage acts on is the envelope sender address—which is usually the address in the From header field. You can specify alternate addresses by encoding them in the command address with this format:

 listname-command-mailbox=domain@listhost 

For example, if a person subscribed to the [e-mail] list using the address [e-mail], her unsubscription request would be addressed to:

 isshinryu-unsubscribe-eunice-list-isshinryu=[e-mail] 

To verify that eunice really sent the message—or at least that the message was sent by someone with access to her e-mail—ezmlm-manage will send a confirmation request containing a "cookie" to the target address, [e-mail]. The cookie is an encrypted token encoded into the return address. For example, the following address, which is too long to fit on one line, would confirm the unsubscription of [e-mail]:

 isshinryu-uc.997816998.gcefchdnlongfjpkjoai-eunice-list-   isshinryu=[e-mail] 

If eunice sends a message to the confirmation cookie address, ezmlm-manage will validate the cookie and remove her from the list.

---