http:// / smtp-service.shtml

Setting up an SMTP service

This page details how to set up a qmail SMTP service, using the patches and scripts on my web site.

One of the things which most people don't realize is that you can, and in many cases you should, have multiple SMTP services running on a server- especially if it provides different types of service for different people.

Everybody seems to miss this point, and I'm tired of saying it over and over and over again... so here it is again, in big ugly letters, for what I hope is the last time:

You can, and in many cases you should, have MULTIPLE SMTP SERVICES running on a server.

Does everybody see that? I honestly don't know how to make it any more obvious, and I am REALLY tired of having to explain this over and over so many times.

For instance you may need a normal SMTP service on port 25 which also supports STARTTLS (to allow your authorized users to relay), an SSL-secured service on port 465 (again, to allow authorized users to relay), and a full open relay server on localhost port 25 to allow local programs to send whatever mail they need without the overhead of checking blacklists or anything.

The last example (the full open relay on localhost port 25) also leads to another point which most people don't realize- an IP address doesn't correspond to a MACHINE, it corresponds to an INTERFACE on a machine. On a machine like a firewall, you may have two or three ethernet cards, a VPN connection, and a localhost interface, and all of them will have their own IP addresses. Even on a simple desktop or server machine you normally have two interfaces- one is the ethernet card, and one is the localhost interface.

The localhost interface is, by definition, only available to and from the machine on which it exists. There is no way for one machine to send packets to another machine's localhost interface (unless you jump through some major hoops, and even then it would be of very limited utility.) This means that incoming connections FROM the localhost interface can be trusted, at least as much as the machine trusts itself.


One of the biggest sources of confusion when setting up a server is trying to decide which set of options to use in the run script. This web page explains the options and shows the combinations which most people need.


To set up a daemontools SMTP service, you first need to select a physical location for the service directory. This may be something like /var/qmail/supervise/qmail-smtp, or /var/service/smtp, or some other location. It can technically be done anywhere on the system, as long as the filesystem (the disk partition) which contains the directory will have enough room to store the log files which will build up over time.

The ony requirement is that it NOT BE PHYSICALLY LOCATED IN THE "/service" DIRECTORY. If you try to set it up here, daemontools will complain about not being able to start the service- and once you do get it running, if you ever decide to shut it down, you won't be able to. svscan will start a supervise process for anything it sees in /service/, whether it's a directory or a symbolic link, and does so within five seconds of the time it's first created. The idea is to set up all of the files and directories needed in another location, and then create a symlink so that it's all there at the same time.

For this example, we will use "/var/service/qmail-smtp" as the physical location of the service directory. Note that all commands listed below are meant to be run as root.

First set up the service directory, download the script, and set its permissions.

# mkdir -m 1755 /var/service/qmail-smtp
# cd /var/service/qmail-smtp
# wget
# mv service-qmail-smtpd-run run
# chmod 700 run

Now edit the "run" script using your editor of choice. Set the options as needed for your service. The file itself contains documentation on the options you can set within the file.

In particular, you should also make sure that your "vchkpw" binary has setuid permissions, so that when qmail-smtpd runs it will have permission to read the password files.

# chown vpopmail:vchkpw ~vpopmail/bin/vchkpw
# chmod 6711 ~vpopmail/bin/vchkpw

Then set up the "log" directory, download its "run" script, and set its permissions.

# mkdir -m 755 log
# cd log
# wget
# mv service-any-log-run run
# chmod 700 run

The final step is to start the service running.

Note that you must specify the full absolute path of the directory in the following command. Unless you understand exactly what you are doing, using any kind of "relative" path for the target of the symbolic link (i.e. anything not starting with "/") will not work.

# ln -s /var/service/qmail-smtp /service/

Wait about ten seconds, and then make sure the service is running correctly.

# svstat /service/smtp
/service/smtp: up (pid 24620) 7 seconds

The number of seconds should be three or greater, and if you re-run the same command again, you should see the count going up rather than cycling back to zero. If the count never passes three, or if the service is not listed as "up" to start with, check the logs to see what's going on.

# tail log/main/current

Options in the run script

The options within the "run" script are documented on the service-qmail-smtpd-run web page.

Setting up the tcpserver access files

I do something a little different with my tcpserver access control files than most other people. Instead of calling the files /etc/tcp.smtp and /etc/tcp.smtp.cdb (the files are in /etc/ and have names which start with "tcp.") I call them /etc/tcp/smtp and /etc/tcp/smtp.cdb. The idea is that /etc/tcp is a directory containing all of my tcpserver access control files, along with a Makefile which rebuilds any out-of-date cdb files whenever their source text files have been updated.

If you use the "run" scripts from my web site, you will find them written this way. Of course you can edit the scripts and change the filenames if you like, but I have found this to be a much easier way to administer the control files (I use tcpserver for a lot more than just qmail.)

To set this up on your own server...

# mkdir -m 755 /etc/tcp
# cd /etc/tcp
# wget
# mv etc-tcp-makefile Makefile

At this point it should be ready to go- all you need to do is create the "smtp" file, containing the normal access control list. It may look something like this:


After creating the file, type make to build the smtp.cdb file. The same goes any time you edit the file- run "make" to bring the .cdb files up to date.

If you want to use this for more than just smtp.cdb, you can edit the Makefile itself. You will see a line which looks like this:

all: smtp.cdb

Change it to have a full list of the cdb files you want built:

all: smtp.cdb smtpssl.cdb imapssl.cdb ftp.cdb

Then, make sure the source files (in this case, "smtp", "smtpssl", "imapssl", and "ftp") exist in the /etc/tcp directory, and run "make" to build any and all of them which need updating.

Creating an SSL key file

If you are setting up an SSL or TLS server, you will need to create a /var/qmail/control/servercert.pem file. This file contains the public and private keys used to set up SSL or TLS encryption. It should be readable to the userid which your "qmail-smtpd" program runs as (which is normally the "qmaild" user.)

Part of the file is a "certificate", which is the public key with a signature applied to it. This is the same kind of signature used when you create an SSL key for use with a secure web site- in fact, if you already have such a certificate from an SSL web site, you can use it (with the matching ".key" file) to build this .pem file. As long as the key and the certificate are both stored in PEM-encoded format, you can "cat" the files together and save the result as "servercert.pem", and it will work.

If you don't have such a key, you can create a key and then sign it using itself (also known as a "self-signed" certificate.) Clients will complain about the certificate not being signed by a trusted certificate authority, but the encryption is just as secure. The following example shows how to create a self-signed certificate which expires ten years from the date it was created.

# cd /var/qmail/control
# openssl req -newkey rsa:1024 -x509 -nodes -days 3650 -out servercert.pem -keyout servercert.pem
Generating a 1024 bit RSA private key
writing new private key to 'servercert.pem'
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Florida
Locality Name (eg, city) []:Orlando
Organization Name (eg, company) [Internet Widgits Pty Ltd]:John Simpson
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) [] This name MUST MATCH the name your clients will put into their mail program as their SMTP server name.
Email Address []
# chown root:nofiles servercert.pem The "nofiles" group is the group which "qmaild" belongs to. This combination of ownership and permissions allows qmail-smtpd to read the key, but not change or delete it.
# chmod 640 servercert.pem

After creating the .pem file, you can make sure it has the right basic format by looking at it (with any standard utility, such as "cat" or "less".) It should look something like this:

# cat servercert.pem
-----BEGIN RSA PRIVATE KEY----- MIICXgIBAAKBgQDg/u+tJTzqAEG3kI64N0/fJCSFepgGABjf2ZXwRwamILARmJrO Htj2kgAbTB98xr5SzX53BTHfralkCB8xmerYzgk4uk0X1dlrq8xu4D2KGndqtIGc 0UGF9t14LxYyVfBJElqpwL6TZqhxLy5ulg5VjNHp1WYi00SnWHCnZ9EClwIDAQAB AoGBANvA5EOO3WIIAifSLzNKAt8FJA6i4Jzrt1/b2xClrp7PymhFTt4HTw31J9mB jjeGvhmNz/lbv4yix5GGRUFi/fYSK+IGRQ83m74hbzYj5rEnIsvl//HguP/YZfrG KzMp1C3H+RdSS0baV5qXDI6qKX7NxqVOIKg4liY7PohfENFxAkEA/bdBu/YaPE6g 0Y0oq6Zl19znmv01lvehqM36NU2oz/79RuZ5IXOHuVTQm7yYAcIylNdJevz3jRo0 IYePkLmfjQJBAOMFfOyJyvDmkjNfMu6XCpverF67I6CpQCo8HMhFbKK3eYPWatsI ji+qGyNgqoDYA872r8mkPxT++0id39m9/7MCQQCHu6OSIA5XFyWYFfGdKw8vFcJe O3qRAnfc7B0gqSRX6i2r4Z8KE1mX/9T+jD2yKyeOU0K/Zlg1h8A9890NaxD9AkEA y6c1rN/jjP3aM3l4MC6Q1skHqieIy2xpYjnwu/wDe2jJ+mnUC8999eZMWA00h0bB C92iTmooKMagV0FA+Y0HHwJAF//cpUBx8wy6ZV82Z0PeSmc1kEv4r9hiya/d4JcB Tvm0et90voEq88LyvTkb4qD6fSeZz3avevzAohnZs/RxeA== -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIIDXDCCAsWgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBgTELMAkGA1UEBhMCVVMx EDAOBgNVBAgTB0Zsb3JpZGExEDAOBgNVBAcTB09ybGFuZG8xFTATBgNVBAoTDEpv aG4gU2ltcHNvbjEZMBcGA1UEAxMQdGVzdGtleS5qbXMxLm5ldDEcMBoGCSqGSIb3 DQEJARYNam1zMUBqbXMxLm5ldDAeFw0wNTA2MTgwNzQ2NTBaFw0xNTA2MTYwNzQ2 NTBaMIGBMQswCQYDVQQGEwJVUzEQMA4GA1UECBMHRmxvcmlkYTEQMA4GA1UEBxMH T3JsYW5kbzEVMBMGA1UEChMMSm9obiBTaW1wc29uMRkwFwYDVQQDExB0ZXN0a2V5 LmptczEubmV0MRwwGgYJKoZIhvcNAQkBFg1qbXMxQGptczEubmV0MIGfMA0GCSqG SIb3DQEBAQUAA4GNADCBiQKBgQDg/u+tJTzqAEG3kI64N0/fJCSFepgGABjf2ZXw RwamILARmJrOHtj2kgAbTB98xr5SzX53BTHfralkCB8xmerYzgk4uk0X1dlrq8xu 4D2KGndqtIGc0UGF9t14LxYyVfBJElqpwL6TZqhxLy5ulg5VjNHp1WYi00SnWHCn Z9EClwIDAQABo4HhMIHeMB0GA1UdDgQWBBSGbFx/WXzECfKhdI8MMbNCsJQzSTCB rgYDVR0jBIGmMIGjgBSGbFx/WXzECfKhdI8MMbNCsJQzSaGBh6SBhDCBgTELMAkG A1UEBhMCVVMxEDAOBgNVBAgTB0Zsb3JpZGExEDAOBgNVBAcTB09ybGFuZG8xFTAT BgNVBAoTDEpvaG4gU2ltcHNvbjEZMBcGA1UEAxMQdGVzdGtleS5qbXMxLm5ldDEc MBoGCSqGSIb3DQEJARYNam1zMUBqbXMxLm5ldIIBADAMBgNVHRMEBTADAQH/MA0G CSqGSIb3DQEBBAUAA4GBAMdifHZtq5gM2bmJz7fdCiioCTIFBsFdYpaoyZllJWz2 JVuKRcylD9oPU4ax0T8w6rlTvi81Y1Y0mqXLNojC1QPgbCOfiybIIJZdZYLZihsP q9i014hDLYontCxHaIqzLe4gyccYJnFmGsgP/rKwnSgoKPfkUfglJy4z1S9KpZyJ -----END CERTIFICATE-----

The data you see here is the actual .pem file I made while writing the page. This is not a live key pair which is actually used anywhere, it only exists as an example on this page- and while it is technically possible to copy and paste this into a text file and use that as a real key pair, please don't. Anybody in the world can look at this web page, and if you were to use this exact key, they would be able to decrypt your traffic. You have been warned.

You can also inspect the data in the certificate using this command:

# openssl x509 -text -noout -in servercert.pem
Certificate: Data: Version: 3 (0x2) Serial Number: 0 (0x0) Signature Algorithm: md5WithRSAEncryption Issuer: C=US, ST=Florida, L=Orlando, O=John Simpson, Validity Not Before: Jun 18 07:46:50 2005 GMT Not After : Jun 16 07:46:50 2015 GMT Subject: C=US, ST=Florida, L=Orlando, O=John Simpson, Subject Public Key Info: Public Key Algorithm: rsaEncryption RSA Public Key: (1024 bit) Modulus (1024 bit): 00:e0:fe:ef:ad:25:3c:ea:00:41:b7:90:8e:b8:37: 4f:df:24:24:85:7a:98:06:00:18:df:d9:95:f0:47: 06:a6:20:b0:11:98:9a:ce:1e:d8:f6:92:00:1b:4c: 1f:7c:c6:be:52:cd:7e:77:05:31:df:ad:a9:64:08: 1f:31:99:ea:d8:ce:09:38:ba:4d:17:d5:d9:6b:ab: cc:6e:e0:3d:8a:1a:77:6a:b4:81:9c:d1:41:85:f6: dd:78:2f:16:32:55:f0:49:12:5a:a9:c0:be:93:66: a8:71:2f:2e:6e:96:0e:55:8c:d1:e9:d5:66:22:d3: 44:a7:58:70:a7:67:d1:02:97 Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Subject Key Identifier: 86:6C:5C:7F:59:7C:C4:09:F2:A1:74:8F:0C:31:B3:42:B0:94:33:49 X509v3 Authority Key Identifier: keyid:86:6C:5C:7F:59:7C:C4:09:F2:A1:74:8F:0C:31:B3:42:B0:94:33:49 DirName:/C=US/ST=Florida/L=Orlando/O=John Simpson/ serial:00 X509v3 Basic Constraints: CA:TRUE Signature Algorithm: md5WithRSAEncryption c7:62:7c:76:6d:ab:98:0c:d9:b9:89:cf:b7:dd:0a:28:a8:09: 32:05:06:c1:5d:62:96:a8:c9:99:65:25:6c:f6:25:5b:8a:45: cc:a5:0f:da:0f:53:86:b1:d1:3f:30:ea:b9:53:be:2f:35:63: 56:34:9a:a5:cb:36:88:c2:d5:03:e0:6c:23:9f:8b:26:c8:20: 96:5d:65:82:d9:8a:1b:0f:ab:d8:b4:d7:88:43:2d:8a:27:b4: 2c:47:68:8a:b3:2d:ee:20:c9:c7:18:26:71:66:1a:c8:0f:fe: b2:b0:9d:28:28:28:f7:e4:51:f8:25:27:2e:33:d5:2f:4a:a5: 9c:89

Once you have verified that the certificate is valid, you can copy the "servercert.pem" file to "clientcert.pem", and qmail-remote will be able to use it to encrypt the connection when sending outbound messages to remote SMTP servers which advertise the ability to support TLS.

# cp servercert.pem clientcert.pem
# chown root:qmail clientcert.pem The "qmail" group is the group with the "qmailr" user belongs to. This user should be able to read, but not write, the "clientcert.pem" file.
# chmod 640 clientcert.pem