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
| Parameter | Required | Meaning |
|---|---|---|
<host> | Yes | The host name or IP address of the MTA server, as the web admin reaches it |
<port> | Yes | The node port of the MTA server, usually 9012 |
--token-file <file> | Yes | A file with the content of /opt/msh-zr/etc/node.token of the MTA server |
--name <name> | No | How the server is shown on the Servers page. The host by default. |
-h, --help | No | Show 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:
| Message | Reason |
|---|---|
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.token | The file does not exist, or the msh user cannot read it |
add-server: token file is empty: /opt/msh-zr/var/mta2-node.token | The 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.db | The 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
- Servers - the Add Server dialog and the states of a server
- Milters configuration - install an MTA server and copy its node token