Small-Time Email with Exim and Dovecot: Difference between revisions

From Alpine Linux
No edit summary
m (→‎A Word About Aliases: use path template.)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{ draft }}
If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.
If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.


== Why would you do this? ==
== Why would anyone do this? ==


My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.
My personal motivation for creating this small-time email setup was to deliver alerts from [https://mmonit.com/monit/ Monit] so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.
Line 14: Line 12:
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)
The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)


   apk add exim dovecot mailx
   apk add {{pkg|exim|arch=}} {{pkg|dovecot|arch=}} {{pkg|mailx|arch=}}


== Configuring Exim ==
== Configuring Exim ==
Line 20: Line 18:
The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.
The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.


# Make a backup of /etc/exim/exim.conf
# Make a backup of {{path|/etc/exim/exim.conf}}
# Open /etc/exim/exim.conf in your favorite text editor.
# Open {{path|/etc/exim/exim.conf}} in your favorite text editor.
# Make the changes stated below and save.
# Make the changes stated below and save.


Line 58: Line 56:
   drwxrwsr-x    3 root    mail          4096 May 11 12:58 /var/mail/
   drwxrwsr-x    3 root    mail          4096 May 11 12:58 /var/mail/


Setting the group ownership to exim, lets exim write to users' mailboxes when new mail comes in.
Setting the group ownership to ''mail'', lets exim write to users' mailboxes when new mail comes in.


== Starting the Exim Service ==
== Starting the Exim Service ==
Line 89: Line 87:
== Troubleshooting Mail Delivery ==
== Troubleshooting Mail Delivery ==


If the mail test fails, look int the directory /var/spool/exim/msglog. If there are files in here, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the /var/mail directory.
If the mail test fails, look in the directory {{path|/var/spool/exim/msglog}}. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the {{path|/var/mail}} directory or the mailbox files within the directory.
 
The directory permissions should look like this:
 
  # ls -ld /var/mail
  drwxrwsr-x    3 root    mail
 
The permissions on mailbox files inside should look like this:
 
  # ls -l
  -rw-rw----    1 dave    mail


== Configuring Dovecot ==
== Configuring Dovecot ==
Line 95: Line 103:
If everything is working with local delivery, it's time to set up IMAP using Dovecot.
If everything is working with local delivery, it's time to set up IMAP using Dovecot.


The Dovecot package for Alpine comes with twenty configuration files in /etc/dovecot/conf.d. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.
The Dovecot package for Alpine comes with twenty configuration files in {{path|/etc/dovecot/conf.d}}. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.


First, make a backup copy of /etc/dovecot/dovecot.conf.
First, make a backup copy of {{path|/etc/dovecot/dovecot.conf}}.


Next, create a new dovecot.conf that looks like this:
Next, create a new dovecot.conf that looks like this:
Line 129: Line 137:
   rc-update add dovecot
   rc-update add dovecot


== Creating a Dovecot User and Password ==
== Creating Credentials for Dovecot Users ==


As it is configured, Dovecot does not use /etc/passwd for authentication. Technically, this can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.
As it is configured, Dovecot will use {{path|/etc/passwd}} for looking up user information, but not authentication. Technically, {{path|/etc/passwd}} authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in {{path|/etc/passwd}}.


The Dovecot configuration above specifies a password file of /etc/dovecot/passwd. The Dovecot password file looks like this:
The Dovecot configuration above specifies a password file of {{path|/etc/dovecot/passwd}}. The Dovecot password file looks like this:


   dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.
   dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.
Line 146: Line 154:


The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.
The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.
The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.
  ls -l /etc/dovecot/passwd
  -rw-r-----    1 root    dovecot


== Testing the Dovecot Setup ==
== Testing the Dovecot Setup ==
Line 160: Line 173:
   Error: Failed to initialize SSL server context: Can't load SSL certificate
   Error: Failed to initialize SSL server context: Can't load SSL certificate


This was the result of a typo in the Dovecot config file.
This was the result of a typographical error I made in the Dovecot config file.


You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:
You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:


   # These are self-signed certs generated when the dovecat apk was installed.
   # These are self-signed certs generated when the dovecat apk was installed.
Line 171: Line 183:


Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!
Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!
== Using and Enjoying Your Small-Time Email Setup ==
Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use [https://mmonit.com/monit/ Monit] to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.
The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.
== A Word About Aliases ==
If you've ever used {{path|/etc/aliases}} for mail delivery, you should be aware that Exim puts this file in {{path|/etc/mail/aliases}}. The format is the same as Sendmail.
== Scripted Installation and Configuration ==
If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:
  chgrp mail /var/mail
  chmod 2775 /var/mail
 
  apk add exim mailx
 
  sed -i~ \
    -e 's/# group = mail/  group = mail/' \
    -e 's/# mode = 0660/  mode = 0660/' \
    /etc/exim/exim.conf
 
  ln -s mail/aliases /etc/aliases
 
  rc-update add exim
  service exim start
 
  apk add dovecot
 
  mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~
 
  cat <<EOF > /etc/dovecot/dovecot.conf
  listen = *
  log_path = /var/log/dovecot.log
  protocols = imap
  disable_plaintext_auth = no
  mail_privileged_group = mail
  mail_location = mbox:~/mail:INBOX=/var/mail/%u
  userdb {
    driver = passwd
  }
  passdb {
    driver = passwd-file
    args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
  }
 
  # These are self-signed certs generated when the dovecat apk was installed.
  ssl=yes
  ssl_cert=</etc/ssl/dovecot/server.pem
  ssl_key=</etc/ssl/dovecot/server.key
  EOF
 
  touch /etc/dovecot/passwd
  chown root:dovecot /etc/dovecot/passwd
  chmod 640 /etc/dovecot/passwd
 
  service dovecot start
  rc-update add dovecot
 
  echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"

Latest revision as of 01:11, 12 May 2024

If you want a super-simple SMTP / IMAP setup for a home server, this is the guide for you. This document covers the minimum steps to get email delivery up and running on a small home network. You're not going to want to use this for any serious enterprise stuff, but for a small home LAN it works well.

Why would anyone do this?

My personal motivation for creating this small-time email setup was to deliver alerts from Monit so I would know when my system needed attention. You can use it for this or similar minimalist email needs. Just don't do anything crazy like exposing it to the internet.

Why Exim and Dovecot?

For an email server, Exim is easy to configure. Dovecot is a little more complex, but not insurmountable. Both are well documented.

Installing the Packages

The first step is to install Exim, Dovecot, and Mailx. (Mailx is used for testing.)

 apk add exim dovecot mailx

Configuring Exim

The next step is to get Exim working for delivering email to users on the system. This is a pretty simple configuration and there are only a few parameters to change in the delivered exim.conf file.

  1. Make a backup of /etc/exim/exim.conf
  2. Open /etc/exim/exim.conf in your favorite text editor.
  3. Make the changes stated below and save.

Find the lines that look like this:

 # group = mail
 # mode = 0660

They'll be under the heading of local_delivery:

When you find them, remove the comment (hash symbol). The local_delivery section should now look like this:

 local_delivery:
   driver = appendfile
   file = /var/mail/$local_part_data
   delivery_date_add
   envelope_to_add
   return_path_add
   group = mail
   mode = 0660

The only thing changed is the removal of the hash symbol from the last two lines.

Fixing Ownership and Permissions on /var/mail

As it stands, Exim will not be able to deliver messages to /var/mail, where the user mailboxes are stored. This is due to permissions.

To fix it, run these two commands:

 chgrp mail /var/mail
 chmod 2775 /var/mail

When you're done, verify it with ls -ld /var/mail. It should look something like this:

 $ ls -ld /var/mail/
 drwxrwsr-x    3 root     mail          4096 May 11 12:58 /var/mail/

Setting the group ownership to mail, lets exim write to users' mailboxes when new mail comes in.

Starting the Exim Service

Start Exim and configure it to start at boot time with the usual commands.

 service exim start
 rc-update add exim

Testing the Exim Setup

Log in a a regular user and try sending a test email to yourself. You can do this with the mail command, like this:

 mail -s Testing dave
 This is a test.
 .

This sends a test message to the user dave. (Obviously, you'll want to replace dave with your username.) The final . on the last line is important. It tells the mail command the message is done.

When the message is sent, check that you received it by running mail with no command-line parameters. If everything went well, it should look like the example below.

 $ mail
 Mail version 8.1 6/6/93.  Type ? for help.
 "/var/mail/dave": 1 messages
 >   1 dave@myserver.home      Wed May 11 03:51  27/847   "Testing"
 &

You can type the message number (1) to display the contents of the mail and then type q to quit the mail program.

Troubleshooting Mail Delivery

If the mail test fails, look in the directory /var/spool/exim/msglog. If there are files there, they are stuck messages. The files are plain text. Display the contents to show any error messages. In most cases, the problem will be related to permissions on the /var/mail directory or the mailbox files within the directory.

The directory permissions should look like this:

 # ls -ld /var/mail
 drwxrwsr-x    3 root     mail

The permissions on mailbox files inside should look like this:

 # ls -l
 -rw-rw----    1 dave     mail

Configuring Dovecot

If everything is working with local delivery, it's time to set up IMAP using Dovecot.

The Dovecot package for Alpine comes with twenty configuration files in /etc/dovecot/conf.d. As a small-time email admin, you may feel overwhelmed. Don't worry, everything can be condensed down to a single config file of sixteen lines.

First, make a backup copy of /etc/dovecot/dovecot.conf.

Next, create a new dovecot.conf that looks like this:

 listen = *
 log_path = /var/log/dovecot.log
 protocols = imap
 disable_plaintext_auth = no
 mail_privileged_group = mail
 mail_location = mbox:~/mail:INBOX=/var/mail/%u
 userdb {
   driver = passwd
 }
 passdb {
   driver = passwd-file
   args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
 }
 
 # These are self-signed certs generated when the dovecat apk was installed.
 ssl=yes
 ssl_cert=</etc/ssl/dovecot/server.pem
 ssl_key=</etc/ssl/dovecot/server.key

This config does not have the !include conf.d/*.conf that was in the original dovecot.conf, so those twenty files in conf.d are going to be ignored. Everything is now in this single dovecot.conf.

Starting the Dovecot Service

Start Dovecot and configure it to start at boot time with the usual commands.

 service dovecot start
 rc-update add dovecot

Creating Credentials for Dovecot Users

As it is configured, Dovecot will use /etc/passwd for looking up user information, but not authentication. Technically, /etc/passwd authentication can be done using Pluggable Authentication Modules (PAM), but PAM is not part of the base install of Alpine Linux. The next best thing is to use a separate password file for Dovecot credentials and to use the same SHA512-Crypt hashing algorithm used in /etc/passwd.

The Dovecot configuration above specifies a password file of /etc/dovecot/passwd. The Dovecot password file looks like this:

 dave:{SHA512-CRYPT}$6$mQ1rxB0gZHqg8Tg9$nxZ8odJZ6xVpmOVpsnYfAo1i7SuoLDhsvoykieukWF9NyNBq.WwhDA7udcYxP1iEm/IzlBmnwz6/vOO3SX8gA.

There are two fields, username and password, separated by a colon. Notice the {SHA512-CRYPT} prefix to the password. This indicates the hashing algorithm.

You can create passwords with the doveadm command, like this:

 # doveadm pw -s sha512-crypt
 Enter new password:
 Retype new password:

The command will output the hashed password. You'll need to edit Dovecot's password file with a text editor and create the username/password pair by hand.

The permissions on the Dovecot password file should be such that dovecot can read it, but not write to it. Only root should be able to write it.

 ls -l /etc/dovecot/passwd
 -rw-r-----    1 root     dovecot

Testing the Dovecot Setup

To test IMAP, you'll need an email client. Personally, I've used Thunderbird on Windows and K-9 Mail on Android. The trickiest part is getting the email client to trust the self-signed certificates. Configuring email clients is beyond the scope of this document.

From the server side, the Dovecot log file can help you diagnose errors. The dovecot.conf file specifies the location of the log file.

 log_path = /var/log/dovecot.log

One of the common errors I've seen looks like this:

 Disconnected: TLS initialization failed.
 Error: Failed to initialize SSL server context: Can't load SSL certificate

This was the result of a typographical error I made in the Dovecot config file.

You can further simplify things by commenting out the ssl lines in the dovecot.conf so it looks like this:

 # These are self-signed certs generated when the dovecat apk was installed.
 #ssl=yes
 #ssl_cert=</etc/ssl/dovecot/server.pem
 #ssl_key=</etc/ssl/dovecot/server.key

Now TLS is out of the picture, letting you diagnose other potential problems. However, you may have to do some work to convince your mail client that sending login credentials in cleartext is okay. Only do this on a network where you trust your users!

Using and Enjoying Your Small-Time Email Setup

Now that everything is setup, you can start sending yourself cat pictures or you can configure other programs to use the email system to send notifications. For example, I use Monit to keep an eye on services and file system space. When Monit detects a problem, it sends me an email.

The setup presented in this guide uses port 25 for SMTP and port 143 for IMAP. There are no dedicated TLS ports. Encryption is done using STARTTLS.

A Word About Aliases

If you've ever used /etc/aliases for mail delivery, you should be aware that Exim puts this file in /etc/mail/aliases. The format is the same as Sendmail.

Scripted Installation and Configuration

If you like living dangerously (or if you have a test system you don't care about) you can do all of the server configuration presented above with a single script, as shown below:

 chgrp mail /var/mail
 chmod 2775 /var/mail
 
 apk add exim mailx
 
 sed -i~ \
   -e 's/# group = mail/  group = mail/' \
   -e 's/# mode = 0660/  mode = 0660/' \
   /etc/exim/exim.conf
 
 ln -s mail/aliases /etc/aliases
 
 rc-update add exim
 service exim start
 
 apk add dovecot
 
 mv /etc/dovecot/dovecot.conf /etc/dovecot/dovecot.conf~
 
 cat <<EOF > /etc/dovecot/dovecot.conf
 listen = *
 log_path = /var/log/dovecot.log
 protocols = imap
 disable_plaintext_auth = no
 mail_privileged_group = mail
 mail_location = mbox:~/mail:INBOX=/var/mail/%u
 userdb {
   driver = passwd
 }
 passdb {
   driver = passwd-file
   args = scheme=sha512-crypt username_format=%n /etc/dovecot/passwd
 }
 
 # These are self-signed certs generated when the dovecat apk was installed.
 ssl=yes
 ssl_cert=</etc/ssl/dovecot/server.pem
 ssl_key=</etc/ssl/dovecot/server.key
 EOF
 
 touch /etc/dovecot/passwd
 chown root:dovecot /etc/dovecot/passwd
 chmod 640 /etc/dovecot/passwd
 
 service dovecot start
 rc-update add dovecot
 
 echo "Create dovecot user passwords with: doveadm pw -s sha512-crypt"