From Qmailwiki
Revision as of 10:47, 11 July 2005 by Vol (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search



Throughout this document, I will assume that you are using an LWQ-esque setup, and will refer to many files in an LWQ-style installation. If your setup differs from LWQ, you will have to interpret this document into your configuration. LWQ is a very standard installation, and that is all I wish to try to support for this document.

Also, this document assumes that the reader understands how to use tools such as 'tar' and 'gzip' and has basic experience compiling and installing software on a UNIX system. If you are confused by 'unpack the tarball', then you should probably take a few steps back and grab a UNIX for newbies book, or call in the Professionals. For OS-specific tasks, such as adding users, I will describe how to perform the tasks on Linux and FreeBSD. If you have another system, you will have to do some more homework :)

What is vmailmgr?

vmailmgr is a simple and easy to use virtual mail management package for qmail. It provides a local delivery agent (vdeliver) for delivering mail to virtual users, a checkpassword replacement (checkvpw) for authentication, a courier-compatible auth module (authvmailmgr) for authenticating with courier-imap, courier-pop3d, and sqwebmail, and a suite of tools for managing users.

Why vmailmgr?

vmailmgr builds off the qmail principles that system users have full control over their own extension addresses and handing virtual domain control over to the user. Each virtual domain is assigned to a system user, and all of the information about the domain is stored in that user's home directory. Vmailmgr is written in C so it is very fast, and has been proven to be a solid, stable, and secure platform for virtual domain management.

How do I use vmailmgr?

First you start by (obviously) having a qmail system installed. I highly recommend using Dave Sill's Life With qmail (LWQ) to get you started, as it leaves you with a nice base install to add vmailmgr atop of.


After you have qmail set up and running, head over to vmailmgr.org, grab the latest source tarball, and unpack it into wherever you keep your sources.

vmailmgr currently doesn't have very many compile-time configuration options available, such as switching database backends, etc, so I will not cover those here. I use the standard configure, make, make install to install vmailmgr and it seems to work just fine.

# ./configure
# make
# make install

Once you've completed this, vmailmgr is ready to be implemented into your system!

Configuring password checking for vmailmgr

qmail provides an interface for checking passwords called checkpassword. vmailmgr's checkvpw program is a drop-in, checkpassword-compatible authentication module. In order to authenticate users on a vmailmgr setup, you need to use checkvpw in all places where the checkpassword interface is used. With a LWQ setup, this is the pop3 server. Change /bin/checkpassword in your pop3 run script to /usr/local/bin/checkvpw (note, you may have to change the path based on your ./configure options) and restart your pop3d.

Template:Box File

After you do this, verify you can still authenticate a normal system user (since checkvpw also checks system accounts) using telnet or netcat:

# telnet localhost 110
Connected to localhost.localdomain.
Escape character is '^]'.
+OK <10457.1108665966@FQDN>
user joeluser
pass eatatjoes
Connection closed by foreign host.

Success! Now let's set up a virtualdomain.

Setting up a virtualdomain

The first thing you will need to do to add a virtualdomain to a vmailmgr setup is to decide on a base user to handle the domain. I try to use a username that somewhat describes the domain, and use /home/virtual/username for their home directory, although it can be completely arbitrary (other than you cannot use root). I also try to put the virtualdomain users into a group called vmailmgr however that is not necessary, and is just a personal preference. I would also recommend dedicating a user for the domain, rather than trying to give a system user a virtualdomain, as it could potentially conflict with their existing .qmail file setup, if they have one at all.

In this example, we will add example.net to our system, handled by the user frank. (Please note that your operating system may have different ways of adding users, I will cover Linux and FreeBSD methods in this article)

# mkdir -p /home/virtual
#-- Linux
# groupadd vmailmgr
# useradd -g vmailmgr -m -d /home/virtual/frank frank
#-- FreeBSD
# pw group add vmailmgr
# pw user add frank -g vmailmgr -d /home/virtual/frank -m

Now that we have our user added to the system, we're ready to set the user up to receive a virtual domain.

# su - frank
$ vsetup
vsetup: created users directory.
vsetup: wrote '.qmail-default' file.
vsetup: added alias 'mailer-daemon'
vsetup: added alias 'postmaster'
vsetup: added alias 'root'

By default, vmailmgr adds a mailer-daemon, postmaster, and root alias that points to the 'system' users by the same name. You can use vdeluser to remove those, but more on that later. Your user is now ready to receive a virtualdomain! Let's log out from frank and go back to root. To delegate the virtualdomain control to frank, we need to edit the /var/qmail/control/virtualdomains file.

Template:Box File

You will also want to confirm that the domain is not in /var/qmail/control/locals, and finally send qmail-send a HUP signal: (note that killall on a solaris system acts very differently than on most other systems. replace with pkill instead)

If you are adding a real domain that you wish to accept mail for, you will also want to put this domain into your /var/qmail/control/rcpthosts file.

#-- choose one of the following to send a HUP to qmail-send
# killall -HUP qmail-send
# svc -h /service/qmail-send
# qmailctl reload

Now your virtualdomain should be set up with qmail and vmailmgr, and you're ready to add a user and test authentication and mail delivery.

Adding a user to a domain

Here we will add a user to our example.net virtualdomain called 'steve' with the password 'larry123'

# su - frank
$ vadduser steve
Enter the user's new password:
Please type it again for verification:
vadduser: user 'steve' successfully added

Now, we should test that we're able to authenticate with this virtual user:

# telnet localhost 110
Connected to localhost.localdomain.
Escape character is '^]'.
+OK <11975.1108670365@FQDN>
user steve@example.net
pass larry123
Connection closed by foreign host.

vmailmgr also supports the use of the percent sign (%) as a delimiter for the username and domain. This is required for some mail clients (especially old versions of Eudora for Windows) and some 'free pop3 webmail' sites that exist.

Testing mail delivery and retrieval

Now that we have our domain set up and a user added to it, we can test that we are able to send mail to the user, see that it is delivered, and pick it up with a pop3 mail client.

First, let's start by writing a very simple message to use for testing:

# cat <<EOF > test_msg
> This message is a test.
> We are testing email delivery and retrieval here.
> Thank you.

Now, let's use one of qmail's convenient command line utilities to send this message in an email to our test user:

# /var/qmail/bin/mailsubj "test message" steve@example.net < test_msg

If it worked, there will be no output. If there was output, fix the problem it reported and try again. If it appears to simply be hanging there doing nothing, it's actually waiting for input from you, which is a good sign that you didn't supply the < test_msg part of the command line.

If all is well, you should see an entry similar to this in your qmail-send logs: (/var/log/qmail/current)

@400000004214fac41b6724f4 new msg 799676
@400000004214fac41b67387c info msg 799676: bytes 345 from <root@localhost.localdomain> qp 12285 uid 0
@400000004214fac41cf50084 starting delivery 116593: msg 799676 to local frank-steve@example.net
@400000004214fac41cf517f4 status: local 1/10 remote 0/50
@400000004214fac42166e54c delivery 116593: success: did_0+0+1/
@400000004214fac42166f8d4 status: local 0/10 remote 0/50
@400000004214fac42166fcbc end msg 799676

As we can see from the logs, it looks like a successful delivery! Now let's try to pick it up with pop3 again:

# telnet localhost 110
Connected to localhost.localdomain.
Escape character is '^]'.
+OK <12398.1108671412@FQDN>
user steve@example.net
pass larry123
1 439

Great! It looks like we have a new email. Let's check to see that it's the email we sent:

Return-Path: <root@localhost.localdomain>
Delivered-To: frank-steve@example.net
Received: (qmail 12285 invoked by uid 0); 17 Feb 2005 20:12:42 -0000
Date: 17 Feb 2005 20:12:42 -0000
Message-ID: <20050217201242.12283.qmail@localhost.localdomain>
From: root@localhost.localdomain
Subject: test message
To: steve@example.net 

This message is a test.
We are testing email delivery and retrieval here.

Thank you.


And there's our message. So now we have a working vmailmgr setup.

Adding an alias

If you want to add an alias, the vaddalias program is what you want to use. Its usage is quite simple:

$ vaddalias
usage: vaddalias virtuser dest [dest ...]

Let's take an example. We want to make an alias called gurus that forwards to steve, root, and joe@example.com

$ vaddalias gurus steve root joe@example.com
vaddalias: alias 'gurus' successfully added

(note that the output might look slightly different, as on my test system I am using a development version of vmailmgr that has changed some of the internal architecture slightly)

Now if we send an email to gurus@example.net and check our qmail-send logs, we should see the deliveries. You will see multiple new msg and info msg lines, as when vmailmgr's local delivery agent, vdeliver, needs to forward a message to another place (such as root, since root by default is an alias to the root system account, and joe@example.com) it will queue another message with those recipients. Aliases within the virtualdomain, however, will be delivered immediately, and will not be re-queued.

Setting up a Catch-All account

Although I do not recommended to ever use a catchall account, I still feel it is important to cover how to set one up with vmailmgr.

Setting up a catchall is as simple as setting an alias, but with the special user +, as shown below:

$ vaddalias + bob@example.com
vaddalias: alias '+' successfully added

All mail that is not addressed to another user in the database, or handled otherwise by a .qmail file within the virtualdomain's home directory will be handled by this alias. The alias can be a full email address, or a user within the virtualdomain, just as any other alias with vmailmgr.

vmailmgr-based addons


What is omail-admin?

omail-admin is a php-based web interface for vmailmgr written by Olivier Mueller. It functions to allow domain administrators to manage users and aliases within their domain, and allows end-users to manage their email accounts.

Features include:

  • Password Changing
  • Alias/Forward management
  • Account management
  • Autoresponder configuration
  • Quota management

Installing omail-admin

Based on PHP4, omail-admin is designed to talk to an already configured vmailmgrd. For information on setting up vmailmgrd, please INSERT LINK TO VMAILMGRD HERE. These instructions assume you have an already functioning Apache/PHP configuration set up, and know where your DocumentRoot is for your site.

Once you have your vmailmgrd set up and working, installing omail-admin is a snap. Download the latest tarball from omail-admin's SourceForge project page into your webserver's DocumentRoot. Then extract the tarball, and rename the resulting directory to whatever you would like. On my system, I have a separate subdomain set up for administration tools (omail-admin, phpmyadmin, etc) so I simply call mine 'mail'. Once you have your directory named how you would like it, change into it, we need to edit some files.

Personal tools