Running vpopmaild under daemontools

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 vpopmaild, which 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 login command succeeds, the address and password are valid. If not, then they are not valid.

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 example.

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.

Setting up the service

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.

As root...

# 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.

Using the service

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
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
+OK
login userid@domain.xyz p@ssw3rd
+OK+
vpopmail_dir /home/vpopmail
domain_dir /home/vpopmail/domains/domain.xyz
uid 89
gid 89
name userid
comment userid
quota NOQUOTA
user_dir /home/vpopmail/domains/domain.xyz/userid
encrypted_password $1$ZXWVRRi9$X.ZdqlNURS32jD4YdkFkq0
clear_text_password
no_password_change 0
no_pop 0
no_webmail 0
no_imap 0
bounce_mail 0
no_relay 0
no_dialup 0
user_flag_0 0
user_flag_1 0
user_flag_2 0
user_flag_3 0
no_smtp 0
domain_admin_privileges 0
override_domain_limits 0
no_spamassassin 0
delete_spam 0
system_admin_privileges 0
.
quit
+OK
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...

• The 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 login and quit commands, along with a help command which lists just these commands.)

• If the 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 postmaster@domain.xyz, you will be able to create, delete, and modify mailboxes within the domain.xyz domain.

• If 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 using the mod_user command within the service, or using the vmoduser command line program. For example, to set the domain_admin_privileges flag for an account, you can use the following command:

  As root...
  
  # vmoduser -a postmaster@domain.xyz

  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 -S option (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.

Copyright 1995-2024 John M. Simpson KG4ZOW (email) (PGP key)
Last updated 2012-07-20 00:00:12 +0000