Skip to main content
Version: 1.4

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​

CommandWhat it does
change-passwordSets a new password for an administrator panel account
add-serverAdds an MTA server to the Servers page
helpShows 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:

CodeMeaning
0The command succeeded
1The command failed and changed nothing, for example a user that does not exist. The reason is printed to the error output.
2Wrong usage, for example a missing parameter. The error and the usage of the command are printed.

Additional resources​