1. Home
  2. Docs
  3. ClusterControl
  4. Components
  5. ClusterControl CLI
  6. Configuration


The first thing that must be done is to create a user that is allowed to connect to and use the controller. Communication between the s9s command-line client and the controller (the cmon process) is encrypted using TLS on port 9501. Public and private RSA key pairs associated with a username are used to encrypt the communication. The s9s command-line client is responsible for setting up the user and the required private and public key.

The command-line client can be located on the same server as the controller (localhost communication) or on a remote server. The configuration differs depending on the location – localhost or remote access, and both cases are covered below.

Localhost Access

SSH into the controller and then let us create a user called ‘dba’ that is allowed to access the controller. This will create the first user.


All users have the right to perform all operations on the managed clusters. There is no access control or roles implemented at the moment. However, the user must be an authenticated user to be able to access the controller.

$ s9s user --create --generate-key --controller="https://localhost:9501" --group=admins dba
Grant user 'dba' succeeded.

If this is the first time you use the s9s client, then a new directory has been created in $HOME/.s9s/ storing the private/public key and a configuration file.

Let us see what has been created:

$ ls $HOME/.s9s/
dba.key dba.pub s9s.conf

Viewing the configuration file we will see:

cmon_user = dba
# controller_host_name = localhost
# controller_port = 9500
# rpc_tls = false

Now we need to set the controller_host_name and controller_port, and the rpc_tls so the file looks:

cmon_user = dba
controller_host_name = localhost
controller_port = 9501
rpc_tls = true
# controller = "https://localhost:9501"

In order to verify it is working you can list the available clusters:

$ s9s cluster --list
cluster_1 cluster_2 cluster_3

If the authentication fails you will see messages like:

Authentication failed: User 'dba' is not found.

The above means that the user has not been created. Or if there is a problem connecting to cmon:

Authentication failed: Connect to localhost:9501 failed: "{{ Failure message }}".

In this case, double-check the ~/.s9s/s9s.conf file and check that cmon is started with TLS:

$ sudo grep -i tls /var/log/cmon.log
2016-11-28 15:00:31 : (INFO) Server started at tls://

And also:

$ sudo netstat -atp | grep 9501
tcp 0 0 localhost:9501 *:* LISTEN 22096/cmon

To view the users, and list which is the currently used user (marked with an “A” – a short form of “Authenticated”):

$ s9s user --list --long
- 1 system admins - System User
- 2 nobody nobody - -
A 3 dba users - -
- 4 remote_dba users - -

The ‘nobody’ user is a legacy user. No one should ever see a job issued by the user ‘nobody’. The ‘system’ user is the ClusterControl server itself creating internal jobs (e.g internal Cron jobs).

Remote Access

The steps to setup the s9s command-line client for remote access is similar as for localhost, except:

  • The s9s command-line client must exist on the remote server
  • The controller (cmon) must be accepting TLS connections from the remote server.
  • The remote server can connect to the controller with key-based authentication (no password). This is required only during the user creation of a private/public key setup.

1. Setup the bind-address from the cmon process as follow:

$ vi /etc/init.d/cmon

Locate the line:


And change to:


Here we assume the public IP address of the controller is


Naturally, you should lock down this IP with firewall rules only allowing access from the remote servers you wish to access the controller from.

2. Restart the controller and check the log:

$ service cmon restart # sysvinit
$ systemctl restart cmon # systemd

3. Verify the ClusterControl Controller is listening to the configured IP address on port 9501:

$ cat /var/log/cmon.log | grep -i tls
2016-11-29 12:34:04 : (INFO) Server started at tls://
2016-11-29 12:34:04 : (INFO) Server started at tls://

4. On the remote server/computer, we have to enable key-based authentication and create a user called ‘remote_dba’. Create a system user called ‘remote_dba’:

$ useradd -m remote_dba

As the current user (root or sudoer for example) in the remote server, setup a passwordless SSH to the ClusterControl host. Generate one SSH key if you don’t have one:

$ ssh-keygen -t rsa # press 'Enter' for all prompts

5. Copy the SSH public key to the ClusterControl Controller host, for example,

$ ssh-copy-id [email protected]

6. Create the s9s client user:

$ s9s user --generate-key --create --group=admins --controller="" remote_dba
Warning: Permanently added '' (ECDSA) to the list of known hosts.
Connection to closed.
Grant user 'remote_dba' succeeded.

7. Ensure the config file located at ~/.s9s/s9s.conf looks like this (take note the IP of the controller may be different):

cmon_user = remote_dba
controller_host_name =
controller_port = 9501
rpc_tls = true

Finally, test the connection:

$ s9s cluster --list
cluster_1 cluster_2 cluster_3

For more details on the usage, see ClusterControl User Guide (CLI).

Was this article helpful to you? Yes No

How can we help?