Skip to main content
Version: 1.4

add-server

add-server adds an MTA server to the Servers page, as Add Server does there. Use it in an automated multi-server installation, where a script installs the MTA servers.

sudo -u msh /opt/msh-zr/bin/mshctl add-server <host> <port> --token-file <file> [--name <name>]

Run it on the web admin server, see Running mshctl.

Parameters​

ParameterRequiredMeaning
<host>YesThe host name or IP address of the MTA server, as the web admin reaches it
<port>YesThe node port of the MTA server, usually 9012
--token-file <file>YesA file with the content of /opt/msh-zr/etc/node.token of the MTA server
--name <name>NoHow the server is shown on the Servers page. The host by default.
-h, --helpNoShow the help of the command

The token is read from a file and is not a parameter of its own, because a command line is visible to every user of the host.

Example​

Copy the content of /opt/msh-zr/etc/node.token of the MTA server into a file on the web admin server that only the msh user can read, for example by pasting it and pressing Ctrl+D:

sudo -u msh sh -c 'umask 077; cat > /opt/msh-zr/var/mta2-node.token'

Add the server:

sudo -u msh /opt/msh-zr/bin/mshctl add-server mta2.example.com 9012 --token-file /opt/msh-zr/var/mta2-node.token --name mta2
Server 'mta2' added at mta2.example.com:9012. Check the Servers page: the web admin connects to it within a few seconds.

The command only stores the server; it does not contact it. The web admin connects to the server within a few seconds and trusts the certificate of its node from then on. Check the state of the server on the Servers page: Up to date once the web admin sent it the settings, Token refused when the token in the file is not the one of the server.

Delete the token file afterwards:

sudo rm /opt/msh-zr/var/mta2-node.token

Errors​

The command adds nothing when it fails, and ends with exit code 1:

MessageReason
add-server: 'mta2 example.com' is not a valid host name or IP address.The host is not a host name or an IP address
add-server: port must be between 1 and 65535.The port is out of range
add-server: name must not be empty.--name is empty
add-server: cannot read the token file: /opt/msh-zr/var/mta2-node.tokenThe file does not exist, or the msh user cannot read it
add-server: token file is empty: /opt/msh-zr/var/mta2-node.tokenThe file holds no token
add-server: a server named 'mta2' already exists.Another server has this name
add-server: a server at mta2.example.com:9012 already exists.The server is listed already
add-server: database not found: /opt/msh-zr/etc/msh-zr-web.dbThe command runs on a server without the web admin, for example an MTA server

A missing parameter, such as the port or --token-file, ends with exit code 2 and the usage of the command, for example Missing required parameters: '<host>', '<port>'.

Additional resources​