Web admin server

info

This page is for a multi-server installation. For a single Zimbra server, follow Single server instead. Java 21 or later must be installed on this host, see Java.

In a multi-server installation the web admin runs on a server of its own. It is the only service on that server:

Component	Service unit	Default port	Purpose
msh-zr-web	msh-zr-web.service	7081	Web admin UI. Holds the rules and settings and sends them to every MTA server

The web admin server needs to reach every MTA server on TCP 7082, the Zimbra LDAP on TCP 389 (or your LDAP port) and license.mshsoftware.com on TCP 443. See Ports and firewall.

Commands

Here are the commands needed to install and start the web admin service. They can be invoked one by one in the terminal. If you would like to have a description of each command, please refer to the Description section below.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin --home /opt/msh-zr msh
sudo tar zxvf msh-zr-<VERSION>.tgz -C /opt
sudo sh /opt/msh-zr/lib/fixperms.sh
sudo systemctl link /opt/msh-zr/lib/msh-zr-web.service
sudo systemctl daemon-reload
sudo systemctl enable msh-zr-web.service
sudo systemctl start msh-zr-web.service

Description

Add the msh system user.

• --system - creates a system account (no password, no interactive login)
• --no-create-home - won't auto-create /home/msh, since /opt/msh-zr is its home
• --shell /usr/sbin/nologin - prevents login
• --home /opt/msh-zr - sets /opt/msh-zr as its "home"
• msh - username

sudo useradd --system --no-create-home --shell /usr/sbin/nologin --home /opt/msh-zr msh

Extract the msh-zr-<VERSION>.tgz package to the /opt system directory. This creates /opt/msh-zr. Use the same package version as on the MTA servers.

sudo tar zxvf msh-zr-<VERSION>.tgz -C /opt

Run the fixperms.sh script, which secures the application installation by:

1. Ensuring proper ownership (msh user/group)
2. Restricting directory access (750)
3. Restricting file access (640, making files non-executable by default)
4. Explicitly making only the necessary scripts executable (750)
5. Making the token files readable by the msh user only (600)
6. Making the Zimbra extension and zimlets in zimbra/ readable by everyone (755 and 644); for that, /opt/msh-zr itself lets others pass through without listing it (751)

sudo sh /opt/msh-zr/lib/fixperms.sh

Create a symbolic link for the web admin unit file, allowing the system to recognize and manage the service. Only the web admin runs on this server; the node and the milter run on the MTA servers.

sudo systemctl link /opt/msh-zr/lib/msh-zr-web.service

Reload systemd to apply changes from the newly linked service file.

sudo systemctl daemon-reload

Enable the service to start automatically on system boot.

sudo systemctl enable msh-zr-web.service

Start the service.

sudo systemctl start msh-zr-web.service

On its first start the web admin creates its databases in etc/ and the token of the Zimbra extension (etc/zimlet-api.token, see Zimlets configuration).

Verify

systemctl status msh-zr-web.service

It must show Active: active (running). Live logs:

journalctl -u msh-zr-web.service -f

The same output is also appended to /opt/msh-zr/var/log/web.out.

First login

Open the web admin UI in your browser:

http://<host>:7081

The first login uses the seeded admin / admin account. Change the password immediately on the Access Control page.

The Servers page is empty at this point, and the Dashboard shows the notice No server is configured, so rules are not applied to any mail. You add each MTA server there once it is installed, see Milters configuration.

Next, set up the Directory service so the web admin can read users and groups from the Zimbra LDAP.

Enable HTTPS for the web UI (recommended)

The web UI serves plain HTTP by default, which sends the administrator password in clear text over the network. On a server of its own the web admin is always reached over the network, so enabling HTTPS is recommended. To serve HTTPS you need a PKCS12 keystore in etc/. The keystore is host-specific and contains a private key, so it is always created on the server itself and never shipped in the package.

Generate a self-signed certificate (good for an internal admin UI; browsers warn until the certificate is trusted):

sudo -u msh /opt/msh-zr/bin/gen-cert -host "$(hostname -f)" -pass 'choose-a-password'

Then set the two values it prints in etc/config.cf:

/opt/msh-zr/etc/config.cf

WEB_SSL_KEYSTORE=etc/keystore.p12
WEB_SSL_KEYSTORE_PASSWORD=choose-a-password

To use a real certificate (CA / Let's Encrypt) instead, convert it to PKCS12 and point the same two settings at it. openssl asks for an export password; that is the value of WEB_SSL_KEYSTORE_PASSWORD:

sudo openssl pkcs12 -export \
  -in fullchain.pem -inkey privkey.pem \
  -name msh-zr-web -out /opt/msh-zr/etc/keystore.p12
sudo chown msh:msh /opt/msh-zr/etc/keystore.p12
sudo chmod 640 /opt/msh-zr/etc/keystore.p12

Restart the web service to apply the change:

sudo systemctl restart msh-zr-web.service

When a keystore is configured, the web UI serves HTTPS on the same port (7081 by default) and no longer plain HTTP, so open it at https://<host>:7081. If the keystore path is set but the file is missing, the launcher logs a warning and falls back to HTTP.

The launcher hands the password to the web app through the environment, not on the command line, so it does not show in the process list, and the web app masks passwords, secrets, keys and tokens as ****** in its startup log (see Logs).

This certificate is for the web admin only. The nodes on the MTA servers always serve HTTPS with the certificates they create themselves. If you install the Zimlets configuration, the Zimbra extension on the mailbox servers trusts this certificate by its fingerprint; when you replace the certificate, update web.fingerprint on every mailbox server.

What's next

• Milters configuration - install the node and milter on every MTA server and add them on the Servers page