Set up Postfix to relay Checkmk's notifications
on Sep 2, 2025
Sending notifications via email with Checkmk is quite easy and quickly configurable via the interface. It has a requirement, though: it needs to have a mail server through which the emails can be dispatched. So, how does one set up such a server? That’s the scope of this tutorial.
NOTE: This tutorial covers a Postfix setup that is suitable for all kinds of sizes of Checkmk installations. In case you run a rather small installation (less than a few hundred notification mails per hour), you might want to evaluate DragonFly Mail Agent. However, the Postfix setup presented here resembles what thousands of professional Checkmk users are running.
We will show you how to install and configure the Postfix mail server since it is largely used, modern, and works well with Checkmk. We will assume the Postfix mail transport agent is running on the same machine as Checkmk and mail delivery is done locally using the “sendmail” command.
Postfix will act as a local MTA (Mail Transfer Agent) to which Checkmk can send emails and, if the destination is outside your LAN, will forward it to the right email server that will then take care of delivering it to the right address. Basically, Postfix will both deliver emails internally and reroute it to external mail servers when necessary.
Postfix installation
Postfix, if not already installed, can be added to the system via the official repositories. On a Debian/Ubuntu system:
sudo apt update
sudo apt install postfixOn RHEL/CentOS:
sudo yum install postfixIf you are prompted to choose during the installation, select “Internet Site” as the type of mail configuration. That will tell Postfix that you intend to use it to send emails to other email servers, acting as a “SmartHost” or, also, relay host.
Postfix configuration
The main configuration file of Postfix is at /etc/postfix/main.cf. Post-installation, the file should be already present and filled with the default options. We are only interested in a few of them.
Make sure that you have the following settings:
myhostname = checkmk.yourdomain.com
myorigin = /etc/mailname
inet_interfaces = loopback-only
relayhost = [smtp.yourmailprovider.com]:587
# smtp_sasl_auth_enable = yes
# smtp_sasl_password_maps = static:YOUR-SMTP-USER-NAME-HERE:YOUR-SMTP-SERVER-PASSWORD-HERE
# smtp_sasl_security_options = noanonymousThe most important setting here is relayhost, which is your server address. Port 587 is used instead of the common 25 as often ISPs (Internet Service Provider) block mails coming from the standard port for spam containment. The option myorigin refers to a file containing your full domain name. Debian and Ubuntu-based distributions usually create this for you during the Postfix installation. You may create it yourself if not present, or use your domain name as the myorigin option directly.
NOTE: The line inet_interfaces = loopback-only tells Postfix to only listen on the local interface and not open any ports on the external network interfaces. Double check external access to ports 25, 465 and 587 and additionally block access to these ports via firewall settings.
We commented out a few options related to SASL authentication as they are not strictly necessary, but your organization or your ISP may require them. In this case, uncomment smtp_sasl_auth_enable, smtp_sasl_password_maps, and smtp_sasl_security_options. The only one that you need to change is the password_maps option, by adding your name:password that needs to be used to log into your ISP’s mail server. You may also use a local implementation of SASL, and use the credentials you set up there. Most small organizations manage well by forwarding all emails through your ISP and thus using its relative credentials.
If you have more than one account on your ISP’s mail server, or if simply more than one user is going to use this Postfix installation, it is best to have their credentials in the file /etc/postfix/sasl_passwd, which should look like this:
user1@example.com
username1:password1
user2@example.com
username2:password2
# Login info for the default relayhost
[smtp.youmailprovider.com]
username:passwordAnd use in main.cf:
sudo systemctl restart postfixRemember to run postmap /etc/postfix/sasl_passwd whenever you make changes to the file.
Once the Postfix configuration is as above, reload the mail server with
sudo systemctl restart postfixAnd the settings are now applied and the Postfix mail server should be running. You can test if emails are correctly delivered with
echo "This is a test email body." | mail -s
"Subject" -r "you<your-domain-dot-com>"
you@example-dot-comCheckmk ships with Heirloom mailx that includes the above command (in ~/bin/mail). You can use it or opt for your operating system alternative, it does not matter for the purposes of this tutorial. We only need a method to check if Postfix is correctly relaying emails.
Give the server a few seconds, especially if you are delivering to a remote server, and check if the test email has been delivered. Postfix logs can be read at /var/log/mail.log. Look for a line that includes status=sent to confirm the delivery. Check also systemd’s journal with:
sudo journalctl -u postfixCheckmk configuration for email notifications
Checkmk configuration is straightforward for email notifications. You are probably already set with what you need for them to work. Checkmk needs only 3 things:
- A working email server (which is what we just set up)
- A user with a valid email address
- A contact group for such user
With the first one done, check that your user has a valid email address under Setup > Users > Users. If not, make sure to add it now. In the same user detail view, you need to check that this user is associated with a contact group, down below under “Contact Groups”. That is necessary to enable notifications via email that are triggered by specific events, depending on the set-up rules. Rules and such go much beyond what this tutorial covers; head over to the Checkmk User Guide on rules to learn more about them.
NOTE: Depending on how strict your provider’s email server is configured, it may additionally be necessary to edit Parameters for HTML email to contain the email address corresponding to the account you are using to log in.
Nothing else is needed from Checkmk’s side. With the working Postfix server, now every time a rule triggers an event for the user’s contact group, an email notification is sent to the email address associated with the user. The email will be dispatched to Postfix which will then check if it is a local address, and deliver it straight through the local network. Or, if it is an external one, Postfix will take care to route it through your mail provider you set with relayhost in the main Postfix configuration file.
It is advisable to not wait for an event to trigger a notification but try the email notification right away. You can do that under Setup > Events > Notifications where you will be presented with a button “test notification”.
For more information on email notifications, the authoritative source is the Checkmk User Guide on email notifications. It walks you through setting up rules and customizing the appearance of the email.
