Zimlets configuration
This page installs the zimlets in a multi-server installation. On a single server, see Zimlet configuration.
The package carries, in /opt/msh-zr/zimbra/, what the users of the Zimbra web client need to reach MSH Zimbra Rules:
| File | What it is |
|---|---|
extension/msh-zr-extension.jar | Zimbra server extension, for every mailbox server |
extension/msh-zr-extension.properties.sample | Its configuration |
zimlets/com_mshsoftware_change_user_info.zip | Change User Info, for the Classic web client |
zimlets/mshsoftware-zimlet-change-user-info.zip | Change User Info, for the Modern web client |
With Change User Info users see their own attributes and change the ones you made editable on the User attributes page. The values they set are used in their signatures, disclaimers and autoresponders; the Zimbra directory does not change.
The extension and the zimlets go on the Zimbra mailbox servers - the servers running mailboxd, which serve the web client. Not on servers that only run the Zimbra MTA, LDAP or proxy.
The mailbox servers call the web admin over the network, so enable HTTPS for the web admin first.
Run all commands below as a user with sudo rights: the zm... commands switch to the zimbra user with sudo su - zimbra -c, all other commands run as root through sudo.
The extension, on every mailbox server
Extract from msh-zr-<VERSION>.tgz only its zimbra/ directory to /tmp; MSH Zimbra Rules itself is not installed on a mailbox server. This creates /tmp/msh-zr/zimbra:
sudo tar zxvf msh-zr-<VERSION>.tgz -C /tmp msh-zr/zimbra
Make the extracted files readable by the zimbra user, which deploys the zimlets from there:
sudo chmod -R a+rX /tmp/msh-zr
If the mailbox server is also an MTA server with MSH Zimbra Rules installed, skip these two commands and use /opt/msh-zr/zimbra instead of /tmp/msh-zr/zimbra below.
Create the directory Zimbra loads the extension from. Zimbra loads every directory under /opt/zimbra/lib/ext/ as an extension; it is owned by the zimbra user, which runs mailboxd:
sudo install -d -o zimbra -g zimbra -m 755 /opt/zimbra/lib/ext/msh-zr
Copy the extension into it, readable by the zimbra user:
sudo install -o zimbra -g zimbra -m 644 /tmp/msh-zr/zimbra/extension/msh-zr-extension.jar /opt/zimbra/lib/ext/msh-zr/
Create the extension's configuration from the sample. The file holds the token, so only the zimbra user can read it (mode 600):
sudo install -o zimbra -g zimbra -m 600 /tmp/msh-zr/zimbra/extension/msh-zr-extension.properties.sample /opt/zimbra/conf/msh-zr-extension.properties
The web admin created the token in /opt/msh-zr/etc/zimlet-api.token on its first start. Print it on the web admin server:
sudo cat /opt/msh-zr/etc/zimlet-api.token
Print the SHA-256 fingerprint of the web admin's certificate, also on the web admin server. Run it there and not over the network, so you note the certificate of your web admin and not of something in between:
openssl s_client -connect 127.0.0.1:7081 </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256
The output looks like:
sha256 Fingerprint=AB:CD:EF:...:12
Back on the mailbox server, open /opt/zimbra/conf/msh-zr-extension.properties in an editor as root (for example sudo nano /opt/zimbra/conf/msh-zr-extension.properties) and set the URL of the web admin, the printed token, and the value after Fingerprint=:
web.url=https://zr.example.com:7081/
web.token=q3Zx8mL1vT0aYb7cRk2sNw9eHf4uJd6pGi5oCl0rEtA
web.fingerprint=AB:CD:EF:...:12
For a certificate from a public CA, leave web.fingerprint empty.
Treat the token like a password: anyone who has it and can reach the web admin port can act as any Zimbra user towards MSH Zimbra Rules.
Allow the mailbox server to reach the web admin port (7081 by default) and keep it closed for everyone else, for example with ufw on the web admin server:
sudo ufw allow from <mailbox-server-ip> to any port 7081 proto tcp
Restart mailboxd as the zimbra user, so it loads the extension:
sudo su - zimbra -c 'zmmailboxdctl restart'
Check the extension is loaded. Without a login it answers 401, not 404:
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1/service/extension/msh-zr/me
The extension does not load until the token is filled in. A configuration that is missing or wrong stops it from loading as well; the reason is in /opt/zimbra/log/mailbox.log of that mailbox server.
The zimlets, once
The zimlets are deployed on one mailbox server only; Zimbra registers them for all of them. Use any mailbox server where you extracted the package above.
Deploy Change User Info for the Classic web client. zmzimletctl deploy installs the zimlet for all mailbox servers and enables it in the default class of service:
sudo su - zimbra -c 'zmzimletctl deploy /tmp/msh-zr/zimbra/zimlets/com_mshsoftware_change_user_info.zip'
Deploy Change User Info for the Modern web client:
sudo su - zimbra -c 'zmzimletctl deploy /tmp/msh-zr/zimbra/zimlets/mshsoftware-zimlet-change-user-info.zip'
Clear the zimlet cache of mailboxd, so it serves the new zimlets:
sudo su - zimbra -c 'zmprov flushCache zimlet'
Clear the class of service cache of mailboxd. It keeps serving the class of service it cached before the deploy, so without this a zimlet deployed for the first time stays missing for users:
sudo su - zimbra -c 'zmprov flushCache cos'
Check on another mailbox server that the zimlets are registered there too:
sudo su - zimbra -c 'zmzimletctl listZimlets'
Clean up
Zimbra keeps its own copies of the extension and the zimlets, so the extracted package is no longer needed. Remove it on every mailbox server, as root:
sudo rm -rf /tmp/msh-zr
To update the extension and the zimlets to a new version, see Update. To remove them, see Uninstall.