As of the time I write this (late March 2006), the latest development
version of vpopmail (version
5.4.15) comes with a program called
provides a way for authorized clients to perform most of the tasks you can
do with the vpopmail command line tools, without having to ssh into the
server and run them by hand.
The most basic capability of vpopmaild is to verify whether or not a
given email address and password are correct. This is done with the
login command, which is required before any other
commands are accepted. Basically, if the
succeeds, the address and password are valid. If not, then they are not
One of my plans, now that
vpopmaild is available, is to
give qmail-smtpd the ability to support the AUTH command by sending a
login command to
vpopmaild. Of course, before
this can be done, we need to have
vpopmaild running as a
service. The README.vpopmaild
file which comes with the vpopmail-5.4.15 source code (local copy) is a bit thin on explaining how
to set up a vpopmaild service, so this web page will give a better
There is one real difference between my script and a "generic" script- a "generic" script, using the directions from the README.vpopmaild file, tells you to set up a service listening on IP address "0", or listening on every interface on the server. This is a MAJOR security hole- allowing clients to connect across the network allows somebody with a packet sniffer to watch every byte which goes across the wire- including passwords. My script sets up a service which only listens on 127.0.0.1, which on most systems is the "localhost" interface- which means that the packets never physically leave the machine, and therefore cannot be "sniffed" by other machines.
Before setting up the service, you may wish to look at the patches I have written for vpopmail. One is a major enhancement, the other fixes a bug which will prevent users whose passwords contain spaces from being able to authenticate.
I have written a simple "run" script for a vpopmaild service. This is
the actual script which is running the service on my own server. Note that
the commands below assume that your daemontools services are physically
running in the
/var/service directory (which is where they
are on my server.) If you keep your services somewhere else, or want to
set up your own service directory somewhere, that works as well- just make
sure that the physical location is not under
/service or you
will not be able to reliably stop the service when needed.
# mkdir -m 1755 /var/service/vpopmaild or wherever you keep your services
# cd /var/service/vpopmaild
# mkdir -m 755 log
# wget http://qmail.jms1.net/scripts/service-vpopmaild-run
# mv service-vpopmaild-run run
# chmod 755 run
# cd log
# wget http://qmail.jms1.net/scripts/service-any-log-run
# mv service-any-log-run run
# chmod 755 run
# ln -s /var/service/vpopmaild /service/
Wait a few seconds...
# svstat /service/vpopmaild
/service/vpopmaild: up (pid 22457) 7 seconds
/service/vpopmaild/log: up (pid 22460) 7 seconds
2012-07-19 I changed the service-vpopmaild-run script so that it runs the service as the vpopmail user instead of root, and it listens on port 8900 instead of port 89 (because only root can listen on a low-numbered port like that.) The directions below will use port 8900, if you are using some other port number, please adjust accordingly.
Once the service is running, you can test it by telnetting to localhost port 8900. This is a sample of what it looks like:
$ telnet 127.0.0.1 8900
Connected to 127.0.0.1.
Escape character is '^]'.
login firstname.lastname@example.org p@ssw3rd
Connection closed by foreign host.
As you can see, when you successfully log into the service, it shows you pretty much everything about the account you are logged into. A few things are worth mentioning here...
help command will show you a list of all
of the commands that
vpopmaild supports. However, you may
not have permission to use some of them.
The README.vpopmaild file from the vpopmail source code (local copy) contains a full list of the commands which are supported by vpopmaild.
The vpopmaild entry in Inter7's qmail wiki also contains a list of the commands, but does not include details for most of them. It also has some sample PHP code which may be useful if you're going to write a client program.
Note that this wiki entry was my reference for the protocol while
writing courierauthd, which uses
courier-authlib instead of libvpopmail, and only implements enough of
the protocol to support the SMTP AUTH command (i.e. the
quit commands, along with a
help command which lists just these commands.)
domain_admin_privileges flag is set to
1, you are able to administer any mailbox within the domain of your
account (i.e. if you are logged in as
email@example.com, you will be able to create, delete,
and modify mailboxes within the
system_admin_privileges flag is set to
1, you are able to administer any mailbox on the system, plus list, add,
remove, and otherwise administer entire domains.
The various flags associated with each account are manipulated
mod_user command within the service, or
vmoduser command line program. For
example, to set the
domain_admin_privileges flag for an
account, you can use the following command:
# vmoduser -a firstname.lastname@example.org
You can run
vmoduser by itself to see the list of
flags which can be set. Note that some of the flags may not have any
effect on your system, depending on how vpopmail was compiled.
Be very careful with the
(which sets the
system_admin_privileges flag.) Normally
there should be no need to set this flag on any accounts, because the
people who would need this access are usually the same people who would
have SSH access to the server and would therefore be able to run the
vpopmail command line tools directly.
However, with a working vpopmaild service it becomes possible to write a program like vqadmin or qmailadmin which does all of its work using vpopmaild commands (and therefore does not have to be given "setuid" privileges.) In order for such a program to work, the account it uses to connect to vpopmaild would need this flag.