Skip to content

Users and Teams

ClusterControl comes with an advanced user management system, managed by ClusterControl Controller (cmon) service. All users’ activities are logged and accessible via the Audit Log, available under the Activity center section.

Users

Every operation initiated by ClusterControl clients (GUI or CLI) is associated with a user. A user must be authenticated with the controller service before performing any operation. ClusterControl supports private/public key and password authentication. A user can be disabled or enabled by anyone in the "admins" team.

Info

For security reason, a user will be disabled (suspended) after 3 consequent login failures over a pre-defined short time.

Create user

A ClusterControl user must belong to a primary team (primary team is the first group the user belongs to). Once created, the user can be assigned to more than one group if necessary.

Note

The username "admin" is reserved for ClusterControl internal usage. It is a system user and is not intended to be used by anyone.

To create a user, go to Create user or team → Create user and fill up all the following information:

Field Description
Details
First name The first name of the user.
Last name The last name of the user.
Username The username of the user. In CC v2, the username shall be used when logging in to the login page, in contrast to CC v1 (old GUI) where you had to use e-mail address and password combination in order to login.
Password The user's password.
Email Email address of the user. This should be a valid email address (despite not mandatory), for password reset and receiving alerts via email.
Timezone Choose a timezone from the dropdown list. This timezone will reflect the date/time presentation of the ClusterControl events and monitoring data points.
Team
Team Choose a team from the dropdown. This is considered the primary group for this user. A user can be assigned to multiple groups (teams). See Create Team.

  • List all users:

    s9s user --list --long
    Example 
    $ s9s user --list --long
A ID UNAME      GNAME  EMAIL REALNAME
-  1 system     admins -     System User
-  2 nobody     nobody -     -
A  3 dba        users  -     -
-  4 remote_dba users  -     -

  • Create an admin user called "dba" with private/public key authentication only (for local usage):

    s9s user --create \
    --generate-key \
    --controller="https://localhost:9501" \
    --group=admins \
    dba

  • Create a read-only user called "readeruser" with a same-name group and generate both key and password:

    s9s user \
    --create \
    --group=readergroup \
    --create-group \
    --generate-key \
    --new-password=s3cr3tP455 \
    --email-address=reader@somewhere.com \
    --first-name=Reader \
    --last-name=User \
    --batch \
    readeruser

Attention

Starting from ClusterControl 1.9.7 (September 2023), upon logging in to ClusterControl GUI v2, make sure you use the username you have assigned or set during the User Registration page. Whereas in CC GUI v1, you can use e-mail address when logging in to the login page, but in CC v2, make sure you use the username and password combination in order to login to the home page.

Edit user

Use the Edit action to modify existing user's information, re-assign the user to another primary team or force the user to change password:

  1. Login to ClusterControl GUI as a user in the "admins" team.

  2. Go to ClusterControl GUI → User management → Users → find the user → Actions → Edit.

  3. Update all information in the corresponding fields and click Save.

  • Set new first name, last name and email address for user "john":

    s9s user \
    --set \
    --first-name=John \
    --last-name=Doe \
    --email-address=johndoe@example.com \
    --batch \
    john

  • Set a new group for user "devops":

    s9s user \
    --set-group \
    --group=infra_team \
    devops

Info

System users' information like "admin", "ccrpc", "system" and "nobody" are immutable.

Change password

Only users in the "admins" team can change password of other users. For users that belong to a non-admins team, they can only change their own password.

To change password for other users:

  1. Login to ClusterControl GUI as a user in the "admins" team.

  2. Go to ClusterControl GUI → User management → Users → find the user → Actions → Change Password.

  3. Speficy the new password in the New password field and click Change.

  • Set new password for user "devops":

    s9s user \
    --change-password \
    --new-password="MynewP455w0rd" \
    devops

Info

System users' password like "admin", "ccrpc", "system" and "nobody" are immutable.

Teams

Teams group users. Each team may consist of zero or more users. A single user may be a part of one team. Teams may be assigned to zero or more clusters.

Create team

When creating a team, the primary team where the user who creates it belongs, will be the team owner. Only the team owner is allowed to delete or modify the team. Only the owner’s team is allowed to delete the cluster. All clusters created by a specific user also belong to the same team.

To create a team, go to Create user or team → Create team and fill up all the following information:

Field Description
Details
Team name The name of the team or group.
Users
Users Select one or more users from the list. You can always add users later. The selected users will be moved from their current teams to this new team.
Permissions
Change controller configuration Toggle on to allow users on this team to change all cluster configurations of this controller.
Change LDAP settings Toggle on to allow users to change LDAP settings under the User Management page.
Manage users and teams Toggle on to allow users to create, edit, and delete ClusterControl users and teams.
Deploy clusters Toggle on to allow users to deploy a new cluster or import an existing cluster into ClusterControl.
Clusters permission level Choose one of the permissions for all clusters. This permission can be adjusted later for each cluster. If you want to have fine-grained permission per cluster, choose Custom. See Cluster-Level permissions.

Note

By default ClusterControl comes with two teams: "admins" and "users". There is also a hidden team for internal usage called "nobody".

Cluster-level permissions

ClusterControl uses access control to restrict access to clusters and their respective deployment, management, and monitoring features. Access control defines privileges and permissions for a specific team. This ensures that only authorized user requests are allowed.

There are 3 types of access levels for clusters:

Permission Description
Manage Allows viewing the cluster and its properties such as jobs, backups, charts, metrics, and settings of the cluster. It also allows changing the settings of the cluster and managing (clone, create, delete, abort ) jobs on the specific cluster.It does not allow the creation or deletion of the cluster, which is only permissible to the team’s owner.
View Allows viewing the cluster and its properties such as jobs, backups, charts, metrics, and settings of the cluster.The user can not modify the cluster.
No access Access to the resource is denied.
Custom Allows specific permission levels for each cluster.

Edit team

Edit team allows administrator to add or remove users into the team, change global permissions and access level for every cluster managed by ClusterControl. Only the team owner can change the underlying team permission. For example, if user "dba" created a group called "infra", only user "dba" is able to edit "infra" team.

  1. Login to ClusterControl GUI as a user who owns the team.

  2. Go to ClusterControl GUI → User management → Teams → find the team → Actions → Edit.

  3. Configure the users, permission and access level sections and click Save.

  • Set a new group for user "devops":

    s9s user \
    --set-group \
    --group=infra_team \
    devops

  • Add user "myuser" into group admins:

    s9s user \
    --add-to-group \
    --group=admins \
    myuser

LDAP

ClusterControl supports integration with directory services like Active Directory, FreeIPA, and OpenLDAP authentication. This allows users to log into ClusterControl by using their corporate credentials instead of a separate password. LDAP groups can be mapped onto ClusterControl user groups to apply privileges to the entire group. This ensures that ClusterControl authorizes the logged-in user based on the group assigned. It supports up to the LDAPv3 protocol based on RFC2307.

To integrate with a directory service, one has to perform the following steps:

  1. Fill up the LDAP Settings configuration wizard. See LDAP Settings.
  2. Save the settings. At this point, LDAP is saved but not activated because no group mapping has been created yet.
  3. Create at least one group mapping entry by going to Map LDAP Group. See Map LDAP Group.
  4. Enable the LDAP authentication by toggling on the LDAP Settings → Enable LDAP Authentication.
  5. Log in to ClusterControl by using the value of LDAP Username Attributes with the respective password. The user will be authenticated and redirected to the ClusterControl dashboard page based on the assigned group.
  6. From this point, both ClusterControl native authentication and LDAP authentications are enabled.

Attention

The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated. See Delete mapping group.

LDAP settings

Field Description
General Settings
Enable LDAP Authentication Enables LDAP authentication. The native authentication in ClusterControl will also work. Refer to the steps mentioned above, on enabling LDAP authentication.
LDAP/LDAPS URI Enter the LDAP or LDAPS Uniform Resource Identifier (URI), with the port number (if applicable). An example is ldaps://ad.s9s.com:636. For LDAPS, provide the certificates and key files under SSL/TLS Settings section.
Login DN The Distinguished Name is used to bind the LDAP server. This user requires read access to all LDAP users and group entries to work correctly. ClusterControl must perform an LDAP search using the DN before any user can log in. This field is case-sensitive. An example is cn=Administrator,cn=Users,dc=s9s,dc=com.
Login DN Password The password for Login DN.
User Base DN The Distinguished Name (DN) to locate the users’ information. This field is case-sensitive. An example is cn=Users,dc=s9s,dc=com.
Group Base DN The Distinguished Name (DN) to locate the group information. ClusterControl does not support LDAP users that do not belong to at least one LDAP group. An example is ou=Groups,dc=s9s,dc=com.
Advanced
Pre-fill for Fill up all required fields based on common settings for Active Directory or OpenLDAP. Clicking on Reset will clear all textfields.
User Base Filter Filter the object class of the LDAP users. If empty, all object classes will be returned.
Username Attributes The LDAP attributes which hold the username, separated by a comma (whitespace value is not allowed). For Active Directory, this is commonly sAMAccountName and uid for OpenLDAP. When authenticating with ClusterControl (via ClusterControl GUI login page, ClusterControl CLI or RPC API), use the value of this attribute. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the login username.
Real Name Attributes The LDAP attributes which hold the full name of the user, separated by a comma. For Active Directory, this is commonly displayName and cn for OpenLDAP. This value of this attribute will be used as the first and last name of the user. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the user’s full name.
Email Attributes The LDAP attributes which hold the email address of the user, separated by a comma. For Active Directory, this is commonly userPrincipalName and mail for OpenLDAP. This value of this attribute will be used as the email address of the user. If more than one attribute is specified, ClusterControl will attempt to look up all of them with the first non-empty reply (in the particular order) used for the user’s email address.
Group Base Filter Filter the object class for the LDAP groups. If empty, all object classes will be returned.
Static Member Attributes The LDAP attributes which represent the group’s members, separated by a comma. For Active Directory, this is commonly member. For OpenLDAP, posixGroup uses memberUid, while groupOfNames uses member. The value of these attributes will be used to create combinations with the value of Group Mapping Attributes when querying the LDAP server to retrieve the group’s information.
Group Mapping Attributes The LDAP attributes of which name holds the group membership, separated by a comma. For Active Directory, this is commonly dn and uid for OpenLDAP. The value of these attributes will be used to create combinations with Static Member Attributes to query the LDAP server to retrieve the group.
Group Name Attributes The LDAP attribute where the name represents the group’s name. This is commonly cn. The value of this attribute will be used in the group mapping with ClusterControl's Team for authorization purposes.
Network Timeout The connection timeout in seconds if the LDAP server is unreachable or takes too long to respond.
Protocol Version The current LDAP protocol version is used.
Time Limit The limit in seconds for an LDAP query to finish, any query that takes longer will be aborted.
SSL/TLS
CA Cert File Only if specified ldaps:// in the LDAP URI. This is the location of the CA certificate file on the ClusterControl host. 
Certificate File Only if specified ldaps:// in the LDAP URI. This is the location of the certificate file on the ClusterControl host. 
Key File Only if specified ldaps:// in the LDAP URI. This is the location of the key file on the ClusterControl host.

Map LDAP group

ClusterControl requires at least one LDAP group mapping entry to be defined before the LDAP authentication can be activated. Otherwise, ClusterControl would only save the LDAP settings without activating them.

To create a group mapping:

  1. Click on the Map LDAP Group button.
  2. Choose an existing team from the dropdown and specify the value of the LDAP’s Group Name Attributes that you want to be mapped with the ClusterControl team. For single-tier RDN, specify the attribute value for example "DBA". ClusterControl will prepend the Group name attribute configured under the LDAP Settings with the value specified, and append it with the Group base DN value. The final constructed DN will be {Group name attribute}={value specified},{Group base DN}. For multi-tier RDNs, specify the attribute name and value (for multiple RDNs, delimited by a comma) for example cn=DBA,cn=IT,ou=org1. ClusterControl will append the value specified with the Group base DN value under the LDAP Settings. The final constructed DN will be {value specified},{Group base DN}.
  3. After creating the first entry, you may proceed to activate the LDAP authentication by going to LDAP Settings → Enable LDAP Authentication.

All LDAP configurations and mappings will be stored inside a configuration file at /etc/cmon-ldap.cnf. It is recommended to configure LDAP settings and group mappings via the ClusterControl GUI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the GUI.

Note

It is also possible to modify the configuration file directly, however, the cmon service must be reloaded manually by using the systemctl restart cmon command, or service cmon restart.

Delete mapping group

Click on Delete of the entry in the list to delete it. The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated (the button will be greyed out). To delete the last entry, set Enable LDAP Authentication to OFF and you will notice the Remove Group button is now clickable, allowing you to remove the last group mapping entry and effectively deactivating LDAP authentication for ClusterControl.

Copyright © 2014-2025 Severalnines AB. All rights reserved.

Severalnines and ClusterControl are registered trademarks in the US, UK, and EU. The 3rd-party trademarks on this site are property of their respective owners and are used for referential purposes only.

Made with Material for MkDocs