Command-line tool (mshctl)
mshctl is the command-line tool of MSH Zimbra Rules. It does on the server what otherwise needs the administrator panel, for cases where the panel cannot help or a script has to do it:
- reset the password of an administrator panel account, for example when you are locked out,
- add an MTA server to the Servers page, for example in an automated multi-server installation.
It ships with every installation in /opt/msh-zr/bin/mshctl.
Commands
| Command | What it does |
|---|---|
| change-password | Sets a new password for an administrator panel account |
| add-server | Adds an MTA server to the Servers page |
help | Shows the help of the tool or of a command |
Running mshctl
Run mshctl on the server where the web admin runs: on a single server that is the Zimbra server, in a multi-server installation the web admin server.
Run it as the msh user, which the services run as:
sudo -u msh /opt/msh-zr/bin/mshctl <command> <arguments>
The web admin does not have to be stopped: it picks the change up while it runs.
mshctl runs on the Java of the installation, MSH_JAVA_BIN in /opt/msh-zr/etc/config.cf, like the services. When it cannot find it, it stops with mshctl: MSH_JAVA_BIN ('java') does not point to a valid Java executable., see Java.
Help and version
Without a command, or with --help, mshctl lists its commands:
sudo -u msh /opt/msh-zr/bin/mshctl --help
Usage: mshctl [-hV] [COMMAND]
MSH Zimbra Rules command-line tool.
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Commands:
change-password Set a new password for a web login user.
add-server Add an MTA server (msh-zr-node) to the Servers page.
help Display help information about the specified command.
The help of one command, with all its parameters:
sudo -u msh /opt/msh-zr/bin/mshctl help add-server
mshctl -h add-server and mshctl add-server --help show the same.
The version of the installation:
sudo -u msh /opt/msh-zr/bin/mshctl --version
It prints the version, the build and when it was built, for example:
MSH Zimbra Rules 1.4.0 (build 1.4.0, 2026-11-18T10:21:47Z)
Exit codes
For use in scripts:
| Code | Meaning |
|---|---|
0 | The command succeeded |
1 | The command failed and changed nothing, for example a user that does not exist. The reason is printed to the error output. |
2 | Wrong usage, for example a missing parameter. The error and the usage of the command are printed. |
Additional resources
- How to reset credentials - get back into a locked administrator panel with
change-password - Servers - the servers the web admin manages