Update
An update replaces the code (jars, launchers, lib/defaults.cf, service units) and keeps everything host-local. Pick the page for your deployment layout:
- Single server - the one Zimbra server, all three services at once, then the zimlets.
- Multi server - every MTA server first, the web admin server last, then the zimlets on the mailbox servers.
What the update keeps
Everything host-local lives in /opt/msh-zr/etc/, so the update unpacks the new package with etc/ excluded.
File in etc/ | On which host (on a single server, all of them) | Holds |
|---|---|---|
config.cf | Every host | Your configuration overrides |
msh-zr-web.db | Web admin server | Servers, users of the web admin, directory service settings |
msh-zr-master.db | Web admin server | Rules, templates and all other settings, the source the servers get their copy from |
msh-zr-node.db | Every MTA server | The node's copy of the rules and settings, read by the milter |
msh-zr-milter.db | Every MTA server | The limit counters and thresholds |
msh-zr-history.db | Every MTA server | Message history and SMTP events, see Message history database |
node.token, node.p12, node.p12.password | Every MTA server | The node's access token and HTTPS certificate |
license.id, license.key | Every host | The license, sent to the servers by the web admin |
keystore.p12 | Web admin server | The web admin's HTTPS certificate, if you enabled HTTPS |
zimlet-api.token | Web admin server | The token of the Zimbra extension, see Zimlet configuration or Zimlets configuration |
secret.key | Web admin server | The key the bind password of the Directory service is encrypted with |
The scripts/ directory is kept as well: the update replaces only the shipped samples accept.sh, reject.sh and README.txt. Stored attachments in var/attachments/ are kept.
Keep the files in etc/, in particular node.token and node.p12 on the MTA servers. If they are lost, the node creates a new token and certificate, and the web admin no longer accepts the server until you remove it and add it again on the Servers page.
The Zimbra extension and the zimlets are not part of the services. If you installed them, the pages above update them from the new package as well; their configuration in /opt/zimbra/conf/msh-zr-extension.properties is kept.
Back up first
Copy the etc/ directory of each host before you update it, for example:
sudo cp -a /opt/msh-zr/etc /opt/msh-zr/etc.backup-$(date +%F)
On the web admin server, also export a backup on the Backup & Restore page.
Mail flow during the update
While msh-zr-milter.service is stopped on a host, the Postfix on that host cannot reach the milter and falls back to milter_default_action. With the recommended tempfail (see Milter configuration) no message passes unfiltered: Postfix answers every incoming message with 451 4.7.1 Service unavailable - try again later, sending mail servers keep the message in their own queue and retry (typically within 5-15 minutes), and locally injected mail stays in Zimbra's queue. Nothing is lost, only delayed. Users sending from the Zimbra web client during those seconds see the same 451 error and have to resend.
With accept mail keeps flowing, but no rules are applied - messages arriving during the update are delivered without signatures, disclaimers, blocking or any other action, and nothing is logged about them. The window is usually only a few seconds, but if your rules matter for security (blocked senders, attachment filtering, quarantine), do not rely on it being empty.
Stopping the milter, for an update or any restart, takes up to 20 seconds. It accepts no new connection, lets the messages it is processing finish, and then saves the sending limit counters and the SMTP events. Its log says how many sessions finished and how many were cut off when the 20 seconds ran out. From the moment it stops accepting, Postfix applies milter_default_action to new mail.
Stopping the web admin or the node does not affect mail: the milter keeps working with the rules and settings it already has. Only the milter matters for mail flow, and only on the host it runs on. In a multi-server installation the other MTA servers keep filtering normally while one is being updated.
A host already set to tempfail needs no extra steps. If a host uses accept and unfiltered mail during the update is not acceptable, temporarily switch that host to tempfail.
Before stopping the services, on that host:
sudo su - zimbra -c 'zmprov ms $(zmhostname) zimbraMtaMilterDefaultAction tempfail'
sudo su - zimbra -c 'zmmtactl reload'
Wait until Postfix has picked up the change before you stop the milter - check with postconf milter_default_action until it reports tempfail.
After the update, once msh-zr-milter.service is running again, switch back:
sudo su - zimbra -c 'zmprov ms $(zmhostname) zimbraMtaMilterDefaultAction accept'
sudo su - zimbra -c 'zmmtactl reload'
Deferred messages are delivered as soon as the sending servers retry; run mailq on the Zimbra host to see anything still waiting locally.
Stopping the whole MTA instead (zmmtactl stop) also prevents unfiltered mail, but it additionally pauses outbound delivery and rejects connections at the TCP level, so tempfail is the less disruptive option.
Additional resources
- Servers - server states after the update
- Troubleshooting starting services - diagnostic steps if the services do not start after the update