[OpenBSDsupport]

Installing and configuring ezmlm-idx with qmail


ezmlm is a powerful and efficient mailing-list manager for use with qmail. It was developed by the author of qmail, Dan J. Bernstein. ezmlm-idx is an extended set of patches for ezmlm that gives it extended functionality. For more information, see the ezmlm home page at http;//www.ezmlm.org/.


1.0 Introduction

This document takes a couple of things for granted.

2.0 Installation

The first item of business is to download the needed files, which are ezmlm and ezmlm-idx. These can be found at their distrubution sites:

Once downloaded, uncompress and untar the archives:

tar zxvf ezmlm-0.53.tar.gz
tar zxvf ezmlm-idx-0.40.tar.gz

ezmlm can be easily patched by placing the contents of the ezmlm-idx archive into the ezmlm source and applying the included ezmlm-idx patch:

cd ezmlm-0.53/
cp -R ../ezmlm-idx-0.40/* .
patch < idx.patch

At this point, ezmlm is patched to ezmlm-idx and ready to be configured, tested, and installed.

One nice feature (when needed) is the ability to store list information (such as subscribers, config, and other info) in a database. Although it also supports PostgreSQL, we will go through configuring ezmlm-idx to have the ability to use MySQL databases.

To accomplish this, a couple of files must contain the correct paths to the mysql libraries and include files. The following lines show what the files are and what they should contain, based on a ports-tree installation of MySQL:

In conf-sqlcc:
-I/usr/local/include/mysql
In conf-sqlld:
-L/usr/local/lib/mysql -lmysqlclient -lm

At this point we can begin to compile ezmlm-idx. A series of make commands will complete the installation. Proceed as follows:

make mysql
make clean
make
make man

The final installation step is postponed until some rudimentary tests are completed. As per the included INSTALL docs, the next step is to create a test user called eztest. This user will be used to test the newly compiled binaries and ensure that the program was compiled correctly. The process of adding this test user with the adduser command is detailed below:


# adduser
Use option ``-silent'' if you don't want to see all warnings and questions.

Reading /etc/shells
Check /etc/master.passwd
Check /etc/group

Ok, let's go.
Don't worry about mistakes. I will give you the chance later to correct any input.
Enter username [a-z0-9_-]: eztest
Enter full name []:     <-- Can leave blank
Enter shell bash csh ksh nologin sh [bash]:     <-- Accept default
Uid [1026]:     <-- Accept default
Login group eztest [eztest]:
Login group is ``eztest''. Invite eztest into other groups: guest no
[no]:     <-- Accept default
Enter password []:    <-- Since this is a temp account, set to 'eztest'

Enter password again []:

Name:     eztest
Password: ****
Fullname: eztest
Uid:      1026
Gid:      1026 (eztest)
Groups:   eztest
HOME:     /home/eztest
Shell:    /usr/local/bin/bash
OK? (y/n) [y]:
Added user ``eztest''
Copy files from /etc/skel to /home/eztest
Add another user? (y/n) [y]: n
Goodbye!

Now log in as this user so that we can run some commands as them. su can be used for this:

su eztest

STOP!!

Due to the way this test is structured, you will have problems with permissions if the ezmlm source directory is in a restricted area (such as root's home directory.) To avoid any problems, consider doing the following steps before continuing:

  1. As root, move the ezmlm source tree into ~eztest.
  2. chown -R the ezmlm source tree to user eztest.
  3. Change into the directory ~eztest/ezmlm-0.53.
  4. su to eztest.

CONTINUE...

The first test will check to make sure that the binaries neccesary for creating mailing lists and subscribing/unsubscribing/and so on are funtioning correctly. From the ezmlm-0.53 directory, run ezmlm-test:

[eztest@molodetz:/ezmlm-0.53]$ ./ezmlm-test

testing ezmlm-idx:    ezmlm-idx-0.40
Using FQDN host name: mail.sancho2k.net
ezmlm-make (1/2):     OK
Using RDBMS support:  No.
testing for qmail:    >=1.02
ezmlm-reject:         OK
ezmlm-[un|is]sub[n]:  OK
ezmlm-send (1/2):     OK
ezmlm-tstdig:         OK
ezmlm-weed:           OK
ezmlm-make (2/2):     OK
ezmlm-clean (1/2):    removed mod queue entry 3 that wasn't due

If your output looks similar to above and has OK listed for the various checks, regular list creation and storage is functioning properly. We will now test the functionality of database-stored lists and list data:

First, create a new database in mysql called ezmlm. Grant rights to the database to a user (we'll use ezmlm in this example). For assistance on how to do this, refer to the MySQL documentation on their home page.

Once the ezmlm database is set up, we can create some test tables and test the MySQL functionality of ezmlm. The ezmlm-mktab command will create the tables, and ezmlm-test will test them:

[eztest@molodetz:/ezmlm-0.53]$ ./ezmlm-mktab list | mysql -u ezmlm -p ezmlm
Enter password:     <-- Give the database password for 'ezmlm'

Notice above that ezmlm-mktab is creating tables to standard output, which is being piped into mysql and inserted into the ezmlm database we set up.

[eztest@molodetz:/ezmlm-0.53]$ ./ezmlm-test -l ezmlm -p 'ezmlm' -h localhost

testing ezmlm-idx:    ezmlm-idx-0.40
Using FQDN host name: mail.sancho2k.net
ezmlm-make (1/2):     OK
Using RDBMS support:  MySQL. Hope empty tables exist.
testing for qmail:    >=1.02
ezmlm-reject:         OK
ezmlm-[un|is]sub[n]:  OK
ezmlm-send (1/2):     OK
ezmlm-tstdig:         OK
ezmlm-weed:           OK
ezmlm-make (2/2):     OK
ezmlm-clean (1/2):    removed mod queue entry 3 that wasn't due

As seen above, we are feeding ezmlm-test the database connection parameters to connect to the ezmlm database. Since OK shows up, we know that everything is working as it should. We can now complete the last step of setup. Be sure to run the next command as the root user:

make setup

make setup will install the ezmlm binaries into /usr/local/bin/ezmlm.

3.0 Creating a List

We can now cover the process of creating a mailing list, both a simple filesystem-based list, as well as a database stored list. ezmlm allows an admin to control many different features of his list; the options are almost too many to list here. An absolutely required reading at this point is the ezmlm-make(1) man page. This should now be installed in the system under /usr/local/man/ (in case you need to add this to your $MANPATH.)

To first begin with a test mailing list, let us use the name "test." To set up this list, we can use ezmlm-make with the correct syntax, as will follow, for this list.

ezmlm-make ~alias/test ~alias/.qmail-test test mydomain.tld
chown -R alias ~alias/test ~alias/.qmail-test*

If you didn't understand the syntax of the command from the man page which you DID read by now...

This simple set up for a list takes care of the following items:

As seen, communicating with the ezmlm mailing lists is very easy.

To take this further, let's examine a slightly more sophisticated list using some of ezmlm-make's commandline switches as well as making this a database-stored list.

The first step is to set up the tables that the list will use. As when we tested, we will use the ezmlm-mktab command:

ezmlm-mktab testdb | mysql -u ezmlm -p ezmlm

This should prompt for the password of the MySQL user ezmlm. Upon entering it in, the tables for the mailing list testdb will be created. The next step is to create the framework for this mailing list in the tables.

ezmlm-make -fitux -5 "me@mydomain.com" -6 localhost:3306:ezmlm:'ezmlm-pass':ezmlm:testdb \
	~alias/testdb ~alias/.qmail-testdb testdb mydomain.tld
chown -R alias ~alias/testdb ~alias/.qmail-testdb*

Note the changes to this command; the syntax is very similar, with only the addition of the switches, which are explained as follows:

Given these steps, you should now have 2 perfectly functioning mailing lists set up.

4.0 Interacting with a List

The processes used for interacting with our new mailing lists are very straight forward. First we will look at the basics of what a list subscriber may do to manage their subscription to an ezmlm list.

Subscriber functions

List subscription

To subscribe to an ezmlm list, messages should be sent to the email address of the form listname-subscribe@listdomain.tld, where listname here is the name of our mailing list. For example, in order to subscribe to our test mailing list, the user would send a blank message to the email address test-subscribe@mydomain.tld - this is what was set up above in the first basic mailing list we created. Upon subscription request being recieved, a confirmation email is sent to the email address that the subscription request originated from. This is to ensure that no one can sign up another without their permission.

List help

An ezmlm mailing list will also respond to help requests regarding administrative functions of the list such as user subscriptions, unsubsriptions, and other options available to users. Blank messages sent to listname-help@listdomain.tld will be responded to with a message detailing the various options available to subscribers.

List unsubscription

The ezmlm unsubscribe process is just as straightforward as the subscription process. A blank message is sent to the address listname-unsubscribe@listdomain.tld. Again, a confirmation request is generated, and upon confirmation, the user is unsubscribed from the list and will recieve no further list mail.

Admin functions

List management can be made easy by different command line options available to use with new lists.

Manual Subscription

To manually subscribe an email address to a mailing list, the ezmlm-sub command can be used. For instance, if the admin wishes to manually subscribe the address newuser@somedomain.tld to the newlist list installed at /var/qmail/alias/newlist, the following command may be used:


ezmlm-sub ~alias/newlist newuser@somedomain.tld

List Subscribers

Useful for verifying our previous exercise, list membership may be viewed from the shell for individual lists. This can be done with the ezmlm-list command. For instance, to view the membership of the newlist mailing list:

ezmlm-list ~alias/newlist
This should return a list of subscribers, with the only line being the address we just subscribed.

Manual unsubscription

Unsubscription is also simple. To unsubscribe manually the address newuser@somedomain.tld from the newlist list, use the ezmlm-unsub command:

ezmlm-unsub ~alias/newlist newuser@somedomain.tld

While there are other list commands that may be used, we will not cover them here. Refer to the appropriate man pages for details on them.

5.0 - Prologue

If you found this document useful, please let me know. I'd be glad to hear any comments.



Submitted by: [ sancho <at> sancho2k <dot>net ]