2020-10-24 00:08:35 +00:00
---
2020-12-01 18:09:42 +00:00
stage: Enablement
group: Distribution
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-24 00:08:35 +00:00
---
2021-06-02 21:10:00 +00:00
# Set up Postfix for incoming email **(FREE SELF)**
2016-09-25 09:55:14 +00:00
This document will take you through the steps of setting up a basic Postfix mail
2020-04-21 15:21:10 +00:00
server with IMAP authentication on Ubuntu, to be used with [incoming email ](incoming_email.md ).
2016-09-25 09:55:14 +00:00
2021-04-25 21:09:26 +00:00
The instructions make the assumption that you are using the email address `incoming@gitlab.example.com` , that is, username `incoming` on host `gitlab.example.com` . Don't forget to change it to your actual host when executing the example code snippets.
2016-09-25 09:55:14 +00:00
## Configure your server firewall
1. Open up port 25 on your server so that people can send email into the server over SMTP.
2018-11-13 00:39:21 +00:00
1. If the mail server is different from the server running GitLab, open up port 143 on your server so that GitLab can read email from the server over IMAP.
2016-09-25 09:55:14 +00:00
## Install packages
1. Install the `postfix` package if it is not installed already:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo apt-get install postfix
```
2016-09-25 09:55:14 +00:00
2019-08-23 08:50:24 +00:00
When asked about the environment, select 'Internet Site'. When asked to confirm the hostname, make sure it matches `gitlab.example.com` .
2016-09-25 09:55:14 +00:00
1. Install the `mailutils` package.
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo apt-get install mailutils
```
2016-09-25 09:55:14 +00:00
## Create user
1. Create a user for incoming email.
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo useradd -m -s /bin/bash incoming
```
2016-09-25 09:55:14 +00:00
1. Set a password for this user.
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo passwd incoming
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Be sure not to forget this, you'll need it later.
2016-09-25 09:55:14 +00:00
## Test the out-of-the-box setup
1. Connect to the local SMTP server:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
telnet localhost 25
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see a prompt like this:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
If you get a `Connection refused` error instead, verify that `postfix` is running:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postfix status
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
If it is not, start it:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postfix start
```
2016-09-25 09:55:14 +00:00
2020-09-25 06:09:42 +00:00
1. Send the new `incoming` user an email to test SMTP, by entering the following into the SMTP prompt:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
ehlo localhost
mail from: root@localhost
rcpt to: incoming@localhost
data
Subject: Re: Some issue
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Sounds good!
.
quit
```
2016-09-25 09:55:14 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-11-04 03:09:14 +00:00
The `.` is a literal period on its own line.
2016-09-25 09:55:14 +00:00
2020-11-04 03:09:14 +00:00
If you receive an error after entering `rcpt to: incoming@localhost`
2019-07-09 07:16:17 +00:00
then your Postfix `my_network` configuration is not correct. The error will
say 'Temporary lookup failure'. See
[Configure Postfix to receive email from the Internet ](#configure-postfix-to-receive-email-from-the-internet )._
2016-09-25 09:55:14 +00:00
1. Check if the `incoming` user received the email:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
su - incoming
mail
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see output like this:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
"/var/mail/incoming": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Quit the mail app:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
q
```
2016-09-25 09:55:14 +00:00
2020-10-05 18:08:51 +00:00
1. Sign out of the `incoming` account, and go back to being `root` :
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
logout
```
2016-09-25 09:55:14 +00:00
## Configure Postfix to use Maildir-style mailboxes
2021-04-25 21:09:26 +00:00
Courier, which we install later to add IMAP authentication, requires mailboxes to have the Maildir format, rather than mbox.
2016-09-25 09:55:14 +00:00
1. Configure Postfix to use Maildir-style mailboxes:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postconf -e "home_mailbox = Maildir/"
```
2016-09-25 09:55:14 +00:00
1. Restart Postfix:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo /etc/init.d/postfix restart
```
2016-09-25 09:55:14 +00:00
1. Test the new setup:
2019-07-09 07:16:17 +00:00
1. Follow steps 1 and 2 of _[Test the out-of-the-box setup](#test-the-out-of-the-box-setup)_ .
1. Check if the `incoming` user received the email:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
su - incoming
MAIL=/home/incoming/Maildir
mail
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see output like this:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@localhost 59/2842 Re: Some issue
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Quit the mail app:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
q
```
2016-09-25 09:55:14 +00:00
2020-11-04 03:09:14 +00:00
If `mail` returns an error `Maildir: Is a directory` then your
2019-07-09 07:16:17 +00:00
version of `mail` doesn't support Maildir style mailboxes. Install
`heirloom-mailx` by running `sudo apt-get install heirloom-mailx` . Then,
try the above steps again, substituting `heirloom-mailx` for the `mail`
2020-11-04 03:09:14 +00:00
command.
2016-09-25 09:55:14 +00:00
2020-10-05 18:08:51 +00:00
1. Sign out of the `incoming` account, and go back to being `root` :
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
logout
```
2016-09-25 09:55:14 +00:00
## Install the Courier IMAP server
1. Install the `courier-imap` package:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo apt-get install courier-imap
```
2018-03-02 11:32:39 +00:00
2019-07-09 07:16:17 +00:00
And start `imapd` :
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
imapd start
```
2018-03-02 11:32:39 +00:00
2021-04-25 21:09:26 +00:00
1. The `courier-authdaemon` isn't started after installation. Without it, IMAP authentication fails:
2019-07-09 07:16:17 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo service courier-authdaemon start
```
2020-03-24 03:09:28 +00:00
You can also configure `courier-authdaemon` to start on boot:
2019-07-09 07:16:17 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo systemctl enable courier-authdaemon
```
2016-09-25 09:55:14 +00:00
## Configure Postfix to receive email from the internet
1. Let Postfix know about the domains that it should consider local:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postconf -e "mydestination = gitlab.example.com, localhost.localdomain, localhost"
```
2016-09-25 09:55:14 +00:00
1. Let Postfix know about the IPs that it should consider part of the LAN:
2021-04-25 21:09:26 +00:00
Let's assume `192.168.1.0/24` is your local LAN. You can safely skip this step if you don't have other machines in the same local network.
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"
```
2016-09-25 09:55:14 +00:00
1. Configure Postfix to receive mail on all interfaces, which includes the internet:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postconf -e "inet_interfaces = all"
```
2016-09-25 09:55:14 +00:00
1. Configure Postfix to use the `+` delimiter for sub-addressing:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo postconf -e "recipient_delimiter = +"
```
2016-09-25 09:55:14 +00:00
1. Restart Postfix:
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
sudo service postfix restart
```
2016-09-25 09:55:14 +00:00
## Test the final setup
1. Test SMTP under the new setup:
2019-07-09 07:16:17 +00:00
1. Connect to the SMTP server:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
telnet gitlab.example.com 25
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see a prompt like this:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
Trying 123.123.123.123...
Connected to gitlab.example.com.
Escape character is '^]'.
220 gitlab.example.com ESMTP Postfix (Ubuntu)
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
If you get a `Connection refused` error instead, make sure your firewall is set up to allow inbound traffic on port 25.
2016-09-25 09:55:14 +00:00
2020-09-25 06:09:42 +00:00
1. Send the `incoming` user an email to test SMTP, by entering the following into the SMTP prompt:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
ehlo gitlab.example.com
mail from: root@gitlab.example.com
rcpt to: incoming@gitlab.example.com
data
Subject: Re: Some issue
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Sounds good!
.
quit
```
2016-09-25 09:55:14 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2020-11-04 03:09:14 +00:00
The `.` is a literal period on its own line.
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
1. Check if the `incoming` user received the email:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
su - incoming
MAIL=/home/incoming/Maildir
mail
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see output like this:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
"/home/incoming/Maildir": 1 message 1 unread
>U 1 root@gitlab.example.com 59/2842 Re: Some issue
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Quit the mail app:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
q
```
2016-09-25 09:55:14 +00:00
2020-10-05 18:08:51 +00:00
1. Sign out of the `incoming` account, and go back to being `root` :
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
logout
```
2016-09-25 09:55:14 +00:00
1. Test IMAP under the new setup:
2019-07-09 07:16:17 +00:00
1. Connect to the IMAP server:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
telnet gitlab.example.com 143
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see a prompt like this:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
Trying 123.123.123.123...
2020-08-19 18:10:34 +00:00
Connected to mail.gitlab.example.com.
2019-07-09 07:16:17 +00:00
Escape character is '^]'.
- OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THREAD=REFERENCES SORT QUOTA IDLE ACL ACL2=UNION] Courier-IMAP ready. Copyright 1998-2011 Double Precision, Inc. See COPYING for distribution information.
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
1. Sign in as the `incoming` user to test IMAP, by entering the following into the IMAP prompt:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
a login incoming PASSWORD
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
Replace PASSWORD with the password you set on the `incoming` user earlier.
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
You should see output like this:
2016-09-25 09:55:14 +00:00
2020-03-06 03:08:08 +00:00
```plaintext
2019-07-09 07:16:17 +00:00
a OK LOGIN Ok.
```
2016-09-25 09:55:14 +00:00
2019-07-09 07:16:17 +00:00
1. Disconnect from the IMAP server:
2016-09-25 09:55:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2019-07-09 07:16:17 +00:00
a logout
```
2016-09-25 09:55:14 +00:00
2019-08-22 08:50:31 +00:00
## Done
2016-09-25 09:55:14 +00:00
2020-04-21 15:21:10 +00:00
If all the tests were successful, Postfix is all set up and ready to receive email! Continue with the [incoming email ](incoming_email.md ) guide to configure GitLab.
2016-09-25 09:55:14 +00:00
---
2019-01-24 06:52:33 +00:00
_This document was adapted from < https: / / help . ubuntu . com / community / PostfixBasicSetupHowto > , by contributors to the Ubuntu documentation wiki._