1. Home
  2. Docs
  3. ClusterControl
  4. User Guide (CLI)
  5. 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 to set up the user and the required private and public keys.

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.

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

Group “admins” have the right to perform all operations on the managed clusters. For a fine-grained access level, please create a different group and assign it with proper ACLs. See s9s-tree.

If this is the first time you use the s9s client, then a new directory has been created in $HOME/.s9s/ storing the private and public keys in PEM format and a configuration file. Let’s 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"

By default, the client will look into the {username}.key for the private key file and {username}.pub for the public key file in the same directory as the s9s.conf configuration file.

In order to verify it is working you can try to 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 set up 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/default/cmon

Add the line:


Here we assume the public IP address of the controller is


Ideally, you should lock down this IP address 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

5. As the current user (root or sudoer for example) in the remote server, set up 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

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.
See also

Documentation for s9s-user.

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

cmon_user = remote_dba
controller_host_name =
controller_port = 9501
rpc_tls = true

8. Finally, test the connection:

$ s9s cluster --list
cluster_1 cluster_2 cluster_3
Was this article helpful to you? Yes No