Description: The HOWTO to my pop3-ssl setup Author: Tim van Erven Created: 25/02/2003 Last modified: 04/10/2003 (changes listed at end of document) ----------------------------------------------------------------------- Introduction This describes a light-weight pop3 over ssl setup that I'm using to provide secure pop3 access to my mailserver. It supports both mail for real system users and virtual users that just have a mailbox but no system account. My server happens to be running Debian GNU/Linux 3.0, but this HOWTO should apply, with minor modifications, to many other flavours of *nix. If you have any questions or suggestions after reading it, feel free to contact me. Before you do, however, please verify that your comments apply to the latest version of this document, which should be available from: http://gene.science.uva.nl/~talerven/software/add-popa3d-user/pop3-ssl-using-popa3d-HOWTO Copyright, license and terms of usage The following text in this section is borrowed, with slight modifications, from the CD-Writing HOWTO by Winfried Trümper v2.9.3, 23 July 2000. Copyright Tim van Erven 2003. All rights reserved. Redistribution and use, with or without modification, are permitted provided that the name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. In this sense, translations are welcome and need not be authorized by me. The author disclaims all warranties with regard to this document, including all implied warranties of merchantability and fitness for a certain purpose; in no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use of this document. In short: read and use at your own risk. No money-back guarantee. And now on with the interesting stuff. The software The software I'm using: Name Version Website stunnel 3.22 http://www.stunnel.org/ popa3d 0.5.1 http://www.openwall.com/popa3d/ exim 3.35 http://www.exim.org/ add-popa3d-user 1.3.1 http://gene.science.uva.nl/~talerven/software/ Stunnel First, you will have to create a ssl certificate for use with stunnel. The stunnel documentation should tell you how to do that. If you're using Debian, the README.Debian file in /usr/share/doc/stunnel provides a brief summary. Anyway, assuming you've managed to create a certificate, place it in /etc/ssl/certs. I named my certificate pop3s.pem, so if yours is called differently, make sure to adjust the examples below accordingly. Popa3d Most likely you won't be able to use the version of popa3d supplied by your distro. Most don't even supply popa3d anyway. So you'll have to compile it from source yourself. Before doing this make sure to edit the file params.h. At the very least set both POP_VIRTUAL and VIRTUAL_ONLY to 1, but you might want to make some other changes as well. For instance, I've set VIRTUAL_HOME_PATH to "/home/virtual/popa3d". Note that popa3d expects to find user authentication and mail files in a subdirectory of the VIRTUAL_HOME_PATH named after the IP address of the interface it's listening on. So in my case that's /home/virtual/popa3d/127.0.0.1. Now go on and compile popa3d. Adding a pseudo-user to your system If you want to set up any virtual users (users without a real system account), you will first have to create a pseudo-user (a system account that you can't actually log in to). This pseudo-user will be the owner of the mail directories for your virtual users. You should never give it any other privileges or use it for anything else. If you are using multiple domains, you should create a separate pseudo-user for each domain. I've created a single pseudo-user called vmail, for `virtual mail'. Now the creation of a pseudo-user is somewhat distribution specific. Here's how to create a pseudo-user called vmail on a Debian system: # adduser --system --no-create-home vmail The documentation for your distribution should tell you how to create a user that can't actually log in. Add-popa3d-user If you've done all that, you're almost ready to start your pop3-ssl server. The last thing you need to do is create some (virtual) users. Configure add-popa3d-user by editing the settings at the top of the script. Make sure to set virtual_domain_root_directory to "VIRTUAL_HOME_PATH/127.0.0.1", substituting your own VIRTUAL_HOME_PATH of course. You'll then be able to add users just by running the script and answering its questions. To give you an idea of the permissions for the files, here's what I've got in my /home/virtual/popa3d/127.0.0.1 directory: # ls -l total 2 drwxr-x--- 2 root root 1024 Jan 5 23:02 auth drwxrwsr-x 2 root mail 1024 Feb 25 03:18 mail # ls -l * auth: total 4 -rw------- 1 root root 43 Jan 5 23:02 foo -rw------- 1 root root 43 Jan 5 19:31 bar -rw------- 1 root root 42 Dec 25 03:22 baz -rw------- 1 root root 41 Dec 25 03:29 tve mail: total 0 -rw-rw---- 1 vmail mail 0 Jan 5 23:08 foo -rw-rw---- 1 vmail mail 0 Jan 12 20:54 bar -rw-rw---- 1 vmail mail 0 Feb 24 22:16 baz -rw-rw---- 1 tve mail 0 Feb 25 08:34 tve tve is a real user with an account on the system, the others are virtual users. The files in VIRTUAL_HOME_PATH/127.0.0.1/mail are ordinary mbox files. The files in VIRTUAL_HOME_PATH/127.0.0.1/auth contain the authentication info popa3d needs for each user. Pop3-ssl Now you're ready to start your pop3-ssl server. Do this by typing: /usr/sbin/stunnel -d pop3s -p /etc/ssl/certs/pop3s.pem -l /usr/sbin/popa3d Change the paths if necessary. You will probably want to put this in some sort of script that is executed on boot. Exim So now you've got pop3-ssl running (hopefully), but no mail is delivered to your mailboxes yet. In this section we'll be configuring exim to do just that. Exim - Real users First, we'll configure exim to deliver mail for real users to VIRTUAL_HOME_PATH/127.0.0.1/mail/{username}. To do this, in your exim.conf locate the transport that currently handles local delivery (probably called local_delivery) and change the line looking something like file = /var/spool/mail/${local_part} to file = VIRTUAL_HOME_PATH/127.0.0.1/mail/${local_part} Of course you'll need to substitute your real VIRTUAL_HOME_PATH. Exim - Virtual users The next thing to do is add a transport for virtual users. To do this add the following transport: local_virtual_delivery: driver = appendfile user = mail check_owner = false group = mail mode = 0660 mode_fail_narrower = false envelope_to_add = true return_path_add = true file = VIRTUAL_HOME_PATH/127.0.0.1/mail/${local_part} Again, substitute your real VIRTUAL_HOME_PATH. To make use of the new transport, you'll also have to add a director that we'll call virtualuser: virtualuser: driver = aliasfile transport = local_virtual_delivery file = /etc/vmail search_type = lsearch include_domain = true The last thing you need to do is create a file /etc/vmail and put the names of your virtual users including their domains in there. Note that you don't need to put any real users in there. Here's an example /etc/vmail showing you how to do this: foo@vormig.net bar@example.org baz@example.com If you want your virtual users to be able to receive mail for all your domains, set include_domain to false in the virtualuser director for exim and put the names for your virtual users in /etc/vmail without the domain part. E.g.: foo bar baz Virtual aliases Everything should now be working... except, you'd probably like to be able to create aliases for your virtual users as you do for real users in /etc/aliases. If your virtual users are able to receive mail for all your domains, that's easy: just put aliases in /etc/aliases as you do normally. But if you've set include_domain = yes as in the example above, you will have to do some more work. Add the following director to your exim.conf virtual_aliases: driver = aliasfile file_transport = address_file pipe_transport = address_pipe file = /etc/valiases search_type = lsearch include_domain = true Then you can create a file /etc/valiases and put your aliases for virtual users in there like this: my-best-friend@example.org: foo@example.org my-worst-enemy@example.com: bar@example.com Conclusion That's all. You've now got yourself a nice, light-weight pop3-ssl setup. ----------------------------------------------------------------------- Log of changes to this document 04/10/2003 * Added copyright, license and terms of usage statement. Need to get into the habit of doing that. * Bug fix: popa3d users should be configured in VIRTUAL_HOME_PATH/127.0.0.1, not VIRTUAL_HOME_PATH. * Clarifications and cleanups Thanks to Philipp Jacob for pointing out I should add a little background information about the vmail pseudo-user. 12/03/2003 * Grammar fixes 25/02/2003 * Initial version put online