Skip to main content
Version: 1.4

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.cfEvery hostYour configuration overrides
msh-zr-web.dbWeb admin serverServers, users of the web admin, directory service settings
msh-zr-master.dbWeb admin serverRules, templates and all other settings, the source the servers get their copy from
msh-zr-node.dbEvery MTA serverThe node's copy of the rules and settings, read by the milter
msh-zr-milter.dbEvery MTA serverThe limit counters and thresholds
msh-zr-history.dbEvery MTA serverMessage history and SMTP events, see Message history database
node.token, node.p12, node.p12.passwordEvery MTA serverThe node's access token and HTTPS certificate
license.id, license.keyEvery hostThe license, sent to the servers by the web admin
keystore.p12Web admin serverThe web admin's HTTPS certificate, if you enabled HTTPS
zimlet-api.tokenWeb admin serverThe token of the Zimbra extension, see Zimlet configuration or Zimlets configuration
secret.keyWeb admin serverThe 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.

warning

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​

warning

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.

info

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​