[How-to] Enable SPF, DKIM, DMARC on FreePBX

This document explains how to enable SPF, DKIM and DMARC email validation on a FreePBX system.

Prerequisites

It is beyond the scope of this document to explain what SPF, DKIM and DMARC are. There are hundreds of online resources that do a far better job of this than the author possibly could.

What is SPF?
- What is DKIM?
- What is DMARC?

Assumptions

You are running the FreePBX Distro
Your PBX has a routable IP
- There are ways around this, you can totally send mail without one, but RDNS can get interesting this way. It also usually implies your behind someone else's NAT, and getting any of the big ISPs to publish RDNS can be fun
You are sending mail from FreePBX
- not through another SMTP relay - particularly if you are just sending through a gmail account, they take care of most of this for you
You have set up DNS and RDNS (RDNS is critical for SPF)

SPF Setup

No on-system config is necessary, assuming you have set DNS and RDNS appropriately, add an a: record to your existing SPF. i.e.

Sample SPF Record

mydomain.com. TXT "v=spf1 a:freepbx.mydomain.com include:_spf.google.com ~all"

In my case, I use google domain apps for most of my email.

Important Note: if you send email for this domain from other sources, you must set up SPF for them as well. If you publish an incomplete SPF record, mail from other sources can/will be marked as spam.

DKIM Setup

For this step, on-system config is necessary, and you will need command line access.

1.) Install OpenDKIM:

# yum install opendkim

2.) Generate the DKIM key. mydomain is your domain, myselector is an alpha-numeric string of your choice, I used "freepbx" for clarity with my configuration.

# cd /etc/opendkim/keys
 
# opendkim-genkey -d mydomain.com -s myselector
 
# chown opendkim:opendkim myselector.private

3.) Edit the OpenDKIM configuration file (/etc/opendkim.conf)

# vim /etc/opendkim.conf

CHANGES to /etc/opendkim.conf

## Selects operating modes. Valid modes are s (sign) and v (verify). Default is v.
## Must be changed to s (sign only) or sv (sign and verify) in order to sign outgoing
## messages.
Mode sv
 
## Create a socket through which your MTA can communicate.
Socket inet:8891@localhost
 
## Selects the canonicalization method(s) to be used when signing messages.
Canonicalization relaxed/simple
 
## Domain(s) whose mail should be signed by this filter. Mail from other domains will
## be verified rather than being signed. Uncomment and use your domain name.
## This parameter is not required if a SigningTable is in use.
Domain mydomain.com
 
## Defines the name of the selector to be used when signing messages.
Selector myselector
 
## Gives the location of a private key to be used for signing ALL messages. This
## directive is ignored if KeyTable is enabled.
KeyFile /etc/opendkim/keys/myselector.private

4.) Edit the Postfix configuration file (/etc/postfix/main.cf)

The socket configuration is a carry over from the above configuration file. If for some reason you made a change to it there, be sure to reflect that change here as well. These directives get added to the end of the existing file.

# vim /etc/postfix/main.cf

ADDITIONS to /etc/postfix/main.cf

smtpd_milters = inet:127.0.0.1:8891
non_smtpd_milters = $smtpd_milters
milter_default_action = accept

5.) Add the DKIM DNS record.

Your life will be better if you add the DNS TXT record before sending your first test, as most mail services cache their lookups for a good while, and having to wait for a re-read can be frustrating.

The full record can be found in:

# cat /etc/opendkim/keys/myselector.txt

It's an exercise for the reader to understand how to update their DNS records, reload and propagate them. You can check that it is in there with something like:

# dig -t txt myselector._domainkey.mydomain.com @8.8.8.8

6.) Start and enable OpenDKIM, restart Postfix:

# systemctl start opendkim ; systemctl enable opendkim ; systemctl restart postfix

7.) Check that is works

To ensure that OpenDKIM has started correctly, look for a line like this in /var/log/maillog:

Oct 7 10:30:19 freepbx opendkim[3642]: OpenDKIM Filter v2.11.0 starting (args: -x /etc/opendkim.conf -P /var/run/opendkim/opendkim.pid)

To ensure that OpenDKIM is signing messages, look for a line like this in /var/log/maillog:

Oct 7 10:32:15 freepbx opendkim[3642]: 754A6602F3B0: DKIM-Signature field added (s=myselector, d=mydomain.com)

If it works, and you have gmail, clicking on "show original" will give you the SPF / DKIM / DMARC results. A "good" result looks something like this, pardon the redactions.

DMARC Setup

This document doesn't really touch on how this bit works - there are too many much better resources out there that do a far better job than I could, and it does not require anything done on the FreePBX system itself. The most useful bit of DMARC is the reporting feature - there are lots of services out there that can help out with this and make sure that you did all of the above correctly - and also find other places in your mail chain that you may have missed.

FreePBX Community Documentation