Zimbra Relay Host Setup
Zimbra runs Postfix underneath, but you never touch the Postfix files by hand: the configuration is regenerated from Zimbra’s own database, and a hand-made change is lost at the first regeneration. That is why the relay host, authentication and TLS settings are all defined with zmprov attributes. Your inbound settings and MX records are left untouched.
The only thing that changes is the path out
Today Zimbra’s MTA delivers email straight to the recipient’s server, and whether it arrives is decided by the reputation of your server’s IP address alone. After setup, the same message is handed to MXGate first, inspected there, and sent on from continuously monitored addresses.
Zimbra relay host setup in seven steps
All commands are run as the zimbra user. The examples below use the output of zmhostname in place of the server name, so you do not need to edit them after copying.
-
Switch to the zimbra user and get the server name
Zimbra commands are run as the zimbra user, not as root; running them as root breaks file ownership. Because the attributes are stored per server, you also need the server name to use in the commands.
SHELL copysu - zimbra zmhostname # The output is the server name used in the commands below
-
Define the relay host address
You give the address that outbound mail is handed to, including the port, on a single line. Zimbra writes this value into the Postfix configuration itself; you do not need to edit any files by hand.
ZMPROV copyzmprov ms $(zmhostname) zimbraMtaRelayHost smtp.mxgate.com.tr:587
The same setting can also be entered from the relay field under Configure › MTA in the admin console. The console only sets the address; the following steps are still needed for the credentials. -
Create and build the credentials file
The username and password are kept in a separate file. The key at the start of the line must match the relay host name. The file is not read as plain text; the version built with postmap is used.
/opt/zimbra/conf/relay_password copy# One line: host, space, user:password smtp.mxgate.com.tr KULLANICI:SIFRE # Restrict the permissions and build it chmod 600 /opt/zimbra/conf/relay_password postmap lmdb:/opt/zimbra/conf/relay_password # Is the key actually found? postmap -q smtp.mxgate.com.tr lmdb:/opt/zimbra/conf/relay_password
The key carries no port. Even though the relay host is given assmtp.mxgate.com.tr:587, only the host name goes in this file. If the query on the last line does not return the username, there is no match. -
Turn on SASL authentication
Enable authentication, point Zimbra at the credentials file, and stop the address from being rewritten according to a CNAME record. The three work together; if one is missing, authentication is silently never attempted.
ZMPROV · ZCS 8.5+ copyzmprov ms $(zmhostname) zimbraMtaSmtpSaslAuthEnable yes zmprov ms $(zmhostname) zimbraMtaSmtpSaslPasswordMaps lmdb:/opt/zimbra/conf/relay_password zmprov ms $(zmhostname) zimbraMtaSmtpCnameOverridesServername no
On ZCS 8.0 the same three settings are entered aszmlocalconfig -e postfix_smtp_sasl_auth_enable=yesand the file format ishash:rather thanlmdb:. The version comparison is in the table below. -
Set the TLS and security options
Make sure the connection is encrypted and anonymous authentication is disabled. While the anonymous mechanism is available, Postfix may pick a method that sends no username or password and authentication never happens.
ZMPROV · TLS copyzmprov ms $(zmhostname) zimbraMtaSmtpTlsSecurityLevel may zmprov ms $(zmhostname) zimbraMtaSmtpSaslSecurityOptions noanonymous
-
Apply the changes and verify them
On Zimbra 8.0 and above, changes reach the Postfix configuration on their own within about two minutes. If you do not want to wait you can restart the MTA, then check on the Postfix side that the settings really took effect.
SHELL · APPLY AND VERIFY copy# If you want to apply immediately zmmtactl restart # Did it take effect on the Postfix side? postconf -n | grep -E 'relayhost|smtp_sasl|smtp_tls_security_level' # Read the values on the Zimbra side zmprov gs $(zmhostname) | grep -i mtaSmtpSasl
-
Send a message and read the log
Send a message from an account on Zimbra to an external address and confirm in the log that it left through MXGate. If you see the relay address and a sent status in the log, the setup is working.
TEST · LOG copy# Live mail log tail -f /var/log/zimbra.log # The line you should see in the log status=sent (250 2.0.0 Ok: queued) relay=smtp.mxgate.com.tr[…]:587
Setup complete. Once you see this line, all mail leaving the server is going through MXGate, authenticated and encrypted.
The six attributes the setup touches
When the setup is finished these six values should be defined on the server. If something goes wrong, compare this list with the output of zmprov gs first.
| Attribute | Value | What it does |
|---|---|---|
| zimbraMtaRelayHost | smtp.mxgate.com.tr:587 | The address outbound mail is handed to. The port is given on the same line after a colon. |
| zimbraMtaSmtpSaslAuthEnable | yes | Turns on authentication for the outbound connection. While it is off, the username and password are never sent. |
| zimbraMtaSmtpSaslPasswordMaps | lmdb:/opt/zimbra/conf/relay_password | The compiled file the credentials are read from. Zimbra 8.5 and above use lmdb, while 8.0 uses the hash format. |
| zimbraMtaSmtpSaslSecurityOptions | noanonymous | Disables anonymous authentication. Without this value Postfix may not pick a mechanism that actually sends the username and password. |
| zimbraMtaSmtpTlsSecurityLevel | may | Encrypts the connection with TLS when the other side supports it. MXGate offers STARTTLS on port 587. |
| zimbraMtaSmtpCnameOverridesServername | no | Stops Postfix from rewriting the address according to a CNAME record, which keeps the key in the credentials file matching. |
If you are on ZCS 8.0
These settings moved to zmprov attributes with Zimbra 8.5. On version 8.0 the same work is done with the local configuration command, and the credentials file is built in the hash format rather than lmdb.
zmlocalconfig -e postfix_smtp_sasl_auth_enable=yes zmlocalconfig -e postfix_smtp_sasl_password_maps=hash:/opt/zimbra/conf/relay_password zmlocalconfig -e postfix_smtp_sasl_security_options=noanonymous zmlocalconfig -e postfix_smtp_tls_security_level=may zmlocalconfig -e postfix_smtp_cname_overrides_servername=no # Build the file in the hash format too postmap hash:/opt/zimbra/conf/relay_password
The attribute names and file formats come from the vendor documentation: Zimbra Tech Center — Outgoing SMTP Authentication.
What does the error in your mail log mean?
The six rows below cover almost every problem seen after a Zimbra relay host setup. Look for the symptom in the left column.
| Symptom | What it means | Fix |
|---|---|---|
| SASL authentication failed | The key in the credentials file is not found | Query the key with postmap -q; if it does not return the username, the host name on the line does not match the relay host. Fix the file and run postmap again. |
| Authentication is never attempted | SASL is off, or the anonymous mechanism is being chosen | Confirm that zimbraMtaSmtpSaslAuthEnable is yes and zimbraMtaSmtpSaslSecurityOptions is noanonymous. Without the second one Postfix may choose a mechanism that sends no password. |
| unsupported dictionary type: lmdb | The version does not support the lmdb format | On ZCS 8.0 the file is built in the hash format. Use postmap hash:/opt/zimbra/conf/relay_password and give the setting with hash: as well. |
| The setting has no effect | The wrong server name was used in the zmprov command | The server name must match the output of zmhostname exactly. Confirm the value appears in the output of zmprov gs $(zmhostname). |
| The change does not take effect immediately | The configuration has not been regenerated yet | On Zimbra 8.0 and above changes appear within about two minutes. If you do not want to wait, run zmmtactl restart. |
| Postfix cannot read the files | The commands were run as root | Switch to the zimbra user with su - zimbra and repair the ownership with chown zimbra:zimbra. Zimbra files do not work when owned by root. |
Rolling back
If you want to undo the setup, emptying the relay host attribute is enough; there is no need to delete the credentials file. Once the configuration is regenerated, the server goes back to sending mail directly as before.
# Turn off routing and authentication zmprov ms $(zmhostname) zimbraMtaRelayHost '' zmprov ms $(zmhostname) zimbraMtaSmtpSaslAuthEnable no zmmtactl restart
Questions from Zimbra administrators
Can I run the commands as root?
No. Zimbra administration commands must be run as the zimbra user; switch with su - zimbra and continue from there. When run as root, the ownership of the files created is wrong and Postfix cannot read them. You can repair broken ownership with chown zimbra:zimbra.
Can I make these settings from the admin console?
Partly. The relay host address can be entered on the MTA tab under Configure in the admin console. The credentials and the SASL and TLS settings are not in the console; they are defined from the command line. If you only enter the address in the console and skip the command line steps, the connection is attempted without authentication and rejected.
Do I have to restart the MTA after a change?
On Zimbra 8.0 and above it is not necessary; changes reach the Postfix configuration on their own within about two minutes. If you do not want to wait, apply them immediately with zmmtactl restart. On older versions you need to run postfix reload.
Is the setting per server or for the whole installation?
The zmprov ms command applies the setting only to the named server, while zmprov mcf changes the global setting used across the whole installation. A server-level value overrides the global one. If you have several MTA servers you need to repeat the setting on each of them, or use the global setting instead.
Does this setup affect incoming email?
No. The relay host setting only determines the path that mail leaving the server takes. Your mailboxes, MX records and inbound settings stay exactly as they are. Putting inbound traffic through MXGate as well is a separate step, made through the MX record.