Attention
This tutorial is for servers deployed with downloadable iRedMail installer, if you're looking for tutorial for servers deployed with iRedMail Easy platform, plase check this one instead.
Attention
Check out the lightweight on-premises email archiving software developed by iRedMail team: Spider Email Archiver.
iRedMail generates a self-signed SSL certificate during installation, it's strongly recommended to use a valid ssl cert.
You can either request free cert, or buy one from ssl cert vendors. In this
tutorial, we will show you how to request a free cert for host name
mail.mydomain.com
from Let's Encrypt, and ssl
related configurations in relevant software running on iRedMail server.
Let's Encrypt supports wildcard host names, but it's not covered in this tutorial, please read its User Guide instead.
We use Let's Encrypt official tool named certbot
to request cert, there're
some other third-party tools you can use. On OpenBSD, you can use command
acme-client
which is in base system (check its manual page here:
acme-client(1). To get a list of other
tools, please visit Let's Encrypt website: ACME Client
Implementations.
You must understand which host names you need to support in the SSL cert:
The full hostname of your mail server.
Server hostname is usually used as SMTP/IMAP/POP3 server address in user's mail client application like Outlook, Thunderbird.
You can get full hostname with command hostname -f
on Linux, or
hostname
on OpenBSD.
The web host names you need to access via https.
For example, https://mydomain.com
, https://support.mydomain.com
, then
you need to support both mydomain.com
and support.mydomain.com
in ssl
cert.
No need to support mail domain name in SSL cert, unless it's also a web host name.
Dovecot and Nginx support reading/loading multiple ssl certs (for different host names), but old Postfix software doesn't, so we recommend to use one cert for all host names which are used by SMTP and IMAP/POP3 services.
The way we request free Let's Encrypt cert requires correct A type DNS record for the host name, because Let's Encrypt organization needs to make sure you actually own or control the domain name.
To check the DNS record, you can use dig
command like below:
dig +short -t a mail.mydomain.com
It should return the (public) IP address of your server.
Install the certbot
package first:
yum install -y certbot
(offered by EPEL repo)apt install -y certbot
Let's Encrypt has request rate limit control, you can request limited times for same domain in one day, but the verification process doesn't have such limit. We suggest run verification process first to make sure we fully match its requirements.
Run command below as root user to verify the request process with
--dry-run
argument. It will print some text on console to ask you few
simple questions, please read carefully and answer them.
certbot certonly --webroot --dry-run -w /var/www/html -d mail.mydomain.com
If you need to support multiple domain names in one cert, please append them
with `-d` arguments like this:
certbot certonly --webroot --dry-run \
-w /var/www/html \
-d mail.mydomain.com \
-d 2nd-domain.com \
-d 3rd-domain.com \
-d 4th-domain.com
certbot
program on
console, that means we fully match the requirements, and it's ok to
actually request the cert by running above command again but without
--dry-run
argument:certbot certonly --webroot -w /var/www/html -d mail.mydomain.com
If the command finished successfully, it will create and store cert files under
/etc/letsencrypt/live/mail.mydomain.com/
(You may have different host name
instead of mail.mydomain.com
in this sample path).
Created cert files:
cert.pem
: Server certificate.chain.pem
: Additional intermediate certificate or certificates that web
browsers will need in order to validate the server certificate.fullchain.pem
: All certificates, including server certificate (aka leaf
certificate or end-entity certificate). The server certificate is the first
one in this file, followed by any intermediates.privkey.pem
: Private key for the certificate.Directory /etc/letsencrypt/live/
and /etc/letsencrypt/archive/
are owned by
root user and group, with permission 0700 (set by certbot
program) by
default, it means other users can not access them -- including the daemon users
used to run network services like Postfix/Dovecot/OpenLDAP/MariaDB/PostgreSQL.
It's necessary to set the permission to 0755 for other applications to access them.
chmod 0755 /etc/letsencrypt/{live,archive}
The easiest and quickest way to use Let's Encrypt cert is creating symbol links to the self-signed SSL cert generated by iRedMail installer, then restart services to load the cert files.
mv /etc/pki/tls/certs/iRedMail.crt{,.bak} # Backup
mv /etc/pki/tls/private/iRedMail.key{,.bak} # Backup
ln -s /etc/letsencrypt/live/mail.mydomain.com/fullchain.pem /etc/pki/tls/certs/iRedMail.crt
ln -s /etc/letsencrypt/live/mail.mydomain.com/privkey.pem /etc/pki/tls/private/iRedMail.key
mv /etc/ssl/certs/iRedMail.crt{,.bak} # Backup. Rename iRedMail.crt to iRedMail.crt.bak
mv /etc/ssl/private/iRedMail.key{,.bak} # Backup. Rename iRedMail.key to iRedMail.key.bak
ln -s /etc/letsencrypt/live/mail.mydomain.com/fullchain.pem /etc/ssl/certs/iRedMail.crt
ln -s /etc/letsencrypt/live/mail.mydomain.com/privkey.pem /etc/ssl/private/iRedMail.key
Now restart Postfix / Dovecot / Nginx services to use the cert:
systemctl restart postfix dovecot nginx
Cert can be renewed manually with command certbot renew
, or run same command
in a daily or weekly cron job to renew automatically. Only those certs which
expires in less than 30 days will be renewed. Applications use ssl cert must
be restarted to load renewed cert files.
If cert was renewed, private key /etc/letsencrypt/live/<domain>/privkey.pem
is re-created and linked to file under /etc/letsencrypt/archive/<domain>/privkey<X>.pem
(<X>
is a digit number), but all files linked to
/etc/letsencrypt/live/<domain>/privkey.pem
were left to the old one,
so we must update all files linked to /etc/letsencrypt/live/<domain>/privkey.pem
with argument --post-hook
right after renewed to make sure they're linked to
correct one.
Here's a sample cron job that runs at 3:01AM everyday, and restart postfix/nginx/dovecot after renewed:
Attention
<domain>
by the real domain name./etc/ssl/private/iRedMail.key
by the real linked private key file path on your server./etc/pki/tls/private/iRedMail.key
./etc/ssl/private/iRedMail.key
.1 3 * * * certbot certificates; certbot renew --post-hook 'ln -sf /etc/letsencrypt/live/<domain>/privkey.pem /etc/ssl/private/iRedMail.key; /usr/sbin/systemctl restart postfix dovecot nginx'
File /etc/postfix/main.cf
(on Linux/OpenBSD) or /usr/local/etc/postfix/main.cf
(on FreeBSD):
smtpd_tls_cert_file = /etc/ssl/certs/iRedMail.crt
smtpd_tls_key_file = /etc/ssl/private/iRedMail.key
smtpd_tls_CAfile = /etc/ssl/certs/iRedMail.crt
File /etc/dovecot/dovecot.conf
(on Linux/OpenBSD) or /usr/local/etc/dovecot/dovecot.conf
(on FreeBSD):
ssl = required
ssl_cert = </etc/ssl/certs/iRedMail.crt
ssl_key = </etc/ssl/private/iRedMail.key
ssl_ca = </etc/ssl/certs/iRedMail.crt
File /etc/nginx/templates/ssl.tmpl
(on Linux/OpenBSD) or /usr/local/etc/nginx/templates/ssl.tmpl
(on FreeBSD):
ssl_certificate /etc/ssl/certs/iRedMail.crt;
ssl_certificate_key /etc/ssl/private/iRedMail.key;
If MySQL/MariaDB is listening on localhost and not accessible from external network, this is OPTIONAL.
/etc/my.cnf
/etc/mysql/my.cnf
./etc/mysql/mariadb.conf.d/mysqld.cnf
./usr/local/etc/my.cnf
./etc/my.cnf
.[mysqld]
ssl-ca = /etc/ssl/certs/iRedMail.crt
ssl-cert = /etc/ssl/certs/iRedMail.crt
ssl-key = /etc/ssl/private/iRedMail.key
If OpenLDAP is listening on localhost and not accessible from external network, this is OPTIONAL.
/etc/openldap/slapd.conf
./etc/ldap/slapd.conf
./usr/local/etc/openldap/slapd.conf
./etc/openldap/slapd.conf
.TLSCACertificateFile /etc/ssl/certs/iRedMail.crt
TLSCertificateKeyFile /etc/ssl/private/iRedMail.key
TLSCertificateFile /etc/ssl/certs/iRedMail.crt