1. Home
  2. Docs
  3. ClusterControl
  4. User Guide (GUI)
  5. Sidebar
  6. User Management

User Management

Team and Users

A user belongs to one or more teams. Users created here will be able to log in and see specific cluster(s), depending on their team and the cluster they have been assigned to.

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.

Attention

ClusterControl 1.8.2 introduces new user management handled by the controller service, instead of the frontend service. By default, it is available for all new installations of ClusterControl in version 1.8.2 or later. For existing installations that have been upgraded to version 1.8.2, it has to be enabled manually. Please refer to Enabling New User Management for details. For LDAP settings, please refer to the LDAP Migration Procedure section.

Note

By default ClusterControl creates two teams: “admins” and “users”. There is also a hidden team for internal usage called “nobody”.

Field Description
Create Team
  • Creates a new ClusterControl Team. A team created here is also equal to a group inside the CMON data tree, which accessible via s9s CLI. See s9s-user.
Create User
  • Creates a new ClusterControl user. A user must belong to a team. A user created here is also equal to a user inside the CMON data tree, which accessible via s9s CLI. See s9s-user.
Access Control
  • A shortcut to quickly assign access and privileges to the corresponding team.
Delete Group
  • Deletes the corresponding group.
Search
  • Filter the user in the list.
Attention

Starting from ClusterControl 1.9.7 (September 2023), ClusterControl GUI v2 is the default frontend graphical user interface (GUI) for ClusterControl. Note that the GUI v1 is considered a feature-freeze product with no future development. All new developments will be happening on ClusterControl GUI v2. See User Guide (GUI v2).

Access Control

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.

The privileges are depending on the ClusterControl components as described below:

Component Access Control Description
Clusters Admin
  • 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 manage (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.
Read
  • Allows viewing the cluster and its properties such as jobs, backups, charts, metrics, and settings of the cluster.
No Access
  • Access to the resource is denied.
Cluster Deployment Admin
  • Allows deploying a new cluster.
No Access
  • Access to the resource is denied.
User Management and LDAP Admin
  • Allows reading existing users and groups, create new users and groups, read access-group rights, change access and add members to created groups.
  • For LDAP, it allows enabling and modifying the LDAP settings.
Read
  • Allows accessing and reading users, groups and access rights. For LDAP, it allows accessing and reading the LDAP settings.
No Access
  • Access to the user management is denied.
Controller Configuration Admin
  • Allows reading and modifying the configuration parameters in Operational Reports, Email Notifications, Integrations and Key Management.
Read
  • Allows reading configuration parameters in Operational Reports, Email Notifications, Integrations and Key Management.
No Access
  • Access to Operational Reports, Email Notifications, Integrations and Key Management is denied.

For the “clusters” component, only the owner’s team is allowed to delete the cluster. All clusters created by a specific user also belong to the same team.

LDAP Settings

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 would ensure 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.
  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.
  4. Enable the LDAP authentication by toggling ON the LDAP Settings → Enable LDAP Authentication.
  5. Log in into ClusterControl by using the value of 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 and LDAP authentications would work.

The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated. To delete the last entry, set Enable LDAP Authentication to OFF and you will notice the Remove Group button is no longer greyed out, allowing you to remove the last group mapping entry.

LDAP Settings

Section Field Description
General Settings Enable LDAP Authentication
  • Enables LDAP authentication. The native authentication in ClusterControl will also work.
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, you also need to 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 Settings 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.
  • 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.
  • 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.
  • 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.
  • 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 being used.
Time Limit
  • The limit in seconds for an LDAP query to finish, any query which takes longer will be aborted.
SSL/TLS Settings CA Cert File
  • Only if you specify ldaps:// in the LDAP URI. This is the location of the CA certificate file on the ClusterControl host. 
Certificate File
  • Only if you specify ldaps:// in the LDAP URI. This is the location of the certificate file on the ClusterControl host. 
Key File
  • Only if you specify ldaps:// in the LDAP URI. This is the location of the key file on the ClusterControl host.

Map LDAP Groups

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, click on the Map LDAP Group button. Pick 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. 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 this configuration file, /etc/cmon-ldap.cnf. It is recommended to configure LDAP setting and group mappings via the ClusterControl UI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the UI. You may also make direct modifications to the file, however, you have to reload the cmon service manually by using the systemctl restart cmon command, or service cmon restart.

Field Description
Map LDAP Group
  • Opens a pop-up to configure the group mappings.
Remove Group
  • Removes the corresponding group mapping entry.
  • The last entry of the group mapping can not be deleted while LDAP authentication is enabled and activated. To delete the last entry, set Enable LDAP Authentication to OFF and you will notice the Remove Group button is no longer greyed out, allowing you to remove the last group mapping entry.
Edit Group
  • Edit an existing group mapping entry.

Enabling New User Management

Attention

Enabling “New” User Management procedure below is applicable only if you have upgraded from < 1.8.2. If you have newly installed the most latest version of ClusterControl (starting 1.8.2 version), the procedure below is not required. By default, the “New” User Management is enabled and applied for latest installed versions of ClusterControl starting 1.8.2 versions.

If you are running old version of ClusterControl i.e. versions <=1.8.2, once you view any of your cluster dashboards, a prompt should be visible to enable new User Management. The example screenshot below (with the marked in red rectangular box) has to be clicked.

Once clicked, ClusterControl will transition to a pop-up UI in the right side corner allowing you to create a New Admin User. Technically, ClusterControl will be able to detect if you have a current user that is already compatible with the New User Management. This means, that if you have been from versions < 1.8.2 and just upgraded to the latest version of ClusterControl (i.e. >= 1.8.2), your current users are not yet compatible with the New User Management. That’s why ClusterControl will let you create a New Admin User. Otherwise, if this prompt is clicked but you have a user that is already compatible with the New” User Management, you will be redirected to the main User Management UI.

Note

If you don’t see the notification “As of ClusterControl 1.8.2, we have …” anymore, probably you have clicked on the “Never show again” which will save it in your browser’s cache. You can make it re-appear if you log into ClusterControl using the incognito mode, or clear your browser’s cache.

Creating New Admin User

Clicking on the link allows to create a new administrator account for the new system. Take note that the User name field is case sensitive. ClusterControl technically creates an admin user. In that case, you cannot re-use admin for User name, but Admin as your User name is allowed. The screenshot below allows ClusterControl to create an Admin user apart from its default admin user in this case.

Once the user is created, the following prompt will appear:

As stated, it is required to log out now and log in as a newly added user.

After this, new options will be accessible in the User Management screen:

From version 1.8.2,

Starting from version 1.9.0, we no longer have the old settings for User Management.

New User Managemement from 1.9.0 and up

 

Creating a New Team

To create a new team, click on the Create Team button and give a name to the team:

Creating a New User

A user belongs to one team. Users created here will be able to log in and see specific cluster(s), depending on their team and the cluster they have been assigned to.

To create a user, click on the Create User button and specify the details:

Users may be deleted, edited, or have their password reset. Users can be active or disabled.

Assigning Privileges

Access control defines privileges and permissions for a specific team. There are up to three privileges:

Privilege Description
Read Access to the resource is read-only
Admin Full access to the resource is granted
No Access Access to the resource is denied

Access privileges are granted to teams for the following resources:

  • Clusters
  • Cluster Deployment
  • LDAP Configuration
  • Controller Configuration

From version 1.8.2,

Since version 1.9.0, we no longer have the old settings for User Management. Access Control can be viewed then by just clicking other than Access Control tab as shown below,

It is also possible to use the “wildcard” team: “All Other Teams”. This privilege will be applied to users that are members of a team other than the team that created a given cluster and teams other than those explicitly listed. From the screenshot above, this means that for all the list of “Clusters“, only the owner that deployed the cluster have access (including the admins – which has all access of the clusters by default), while “All Other Teams” have “No Access” at all. For more details on the privileges, see Access Control.

LDAP Migration Procedure

In the previous versions (1.8.1 and older), LDAP authentication was handled by the frontend component through a number of tables (dcps.ldap_settings and dcps.ldap_group_roles). Starting from ClusterControl 1.8.2, the new LDAP authentication is handled by the backend component and all LDAP-related configuration will reside in /etc/cmon-ldap.cnf.

The older implementation (frontend LDAP) will be automatically disabled, therefore it is necessary to perform this migration for a working LDAP authentication in 1.8.2.

Migrating LDAP Configurations

1) Retrieve the old LDAP settings from the ClusterControl server:

$ mysql -uroot -p dpcs
MariaDB [dcps]> SELECT * FROM ldap_settings\G
*************************** 1. row***************************
              id: 1
enable_ldap_auth: 1
            host: ad.s9s.com
            port: 389
           login: CN=Administrator,CN=Users,DC=s9s,DC=com
        password: ¦Qiç¾÷É5žu
        base_dsn: DC=s9s,DC=com
         user_dn: CN=Users,DC=s9s,DC=com
        group_dn: OU=Groups,DC=s9s,DC=com
Attention

Note that the password value is encrypted and not the actual value.

2) Based on the collected information above, we can configure the new LDAP Configuration Settings under ClusterControl → User Management → LDAP Settings, with the following details:

  • General Settings
    • Enable LDAP Authentication: No
    • LDAP/LDAPS URI: {Construct the URI based on ldap(s)://{value of “host”}:{value of “port”}, as in the ldap_settings. If you use LDAPS, configure the TLS configuration under SSL/TLS Settings}
    • Login DN: {The value of login, as in the ldap_settings table}
    • Login DN password: {The password of Login DN. Do not take the value from ldap_settings table since the value is encrypted}
    • User Base DN: {The value of user_dn, as in the ldap_settings table}
    • Group Base DN: {The value of group_dn, as in the ldap_settings table}
  • Advanced Settings
    • User base filter: {Set to empty, unless you want to filter specific objectclasses during LDAP user lookups}
    • Username attributes: {Set to sAMAccountName for Active Directory, or uid for OpenLDAP}
    • Real name attributes: {Set to displayName for Active Directory, or cn for OpenLDAP}
    • Email attributes: {Set to userPrincipalName, or mail for OpenLDAP}
    • Group base filter: {Set to empty, unless you want to filter specific objectclasses during LDAP group lookups}
    • Static member attributes: {Set to member for Active Directory. For OpenLDAP, posixGroup uses memberUid, while groupOfNames uses member}
    • Group mapping attributes: {Set to dn for Active Directory, or uid for OpenLDAP}
    • Group name attribute: {Set to cn for both Active Directory and OpenLDAP}
  • SSL/TLS Settings
    • CA cert file: {Location of CA cert file on the ClusterControl server}
    • Certificate file: {Location of TLS certificate file on the ClusterControl server}
    • Key file: {Location of TLS key file on the ClusterControl server}

3) Click the Save Settings button to save the configuration. At this point, LDAP authentication is NOT activated since we specified “No” under Enable LDAP Authentication. ClusterControl does not allow enabling LDAP authentication without a group mapping. Therefore, we need to set this to “No” at the initial stage where ClusterControl will only save the LDAP Configurations without activating it.

Migrating Group Mappings

1) Retrieve the old group mapping from the dcps database on the ClusterControl server:

$ mysql -uroot -p dcps
MariaDB> SELECT lg.id, lg.ldap_group_name AS "LDAP Group", r.role_name AS "Role", c.name AS "Team" FROM ldap_group_roles lg, roles r, companies c WHERE lg.role_id=r.id AND lg.company_id=c.id;
+----+------------+-------------+-------+
| id | LDAP Group | Role        | Team  |
+----+------------+-------------+-------+
|  1 | CN=DBA     | Super Admin | Admin |
|  2 | CN=Dev     | Admin       | Dev   |
+----+------------+-------------+-------+

Based on the above output, pay attention to the following:

  • LDAP Group: This mapping should be similar to the new LDAP Settings. However, in the new implementation, the attribute name (CN) should be specified as LDAP Settings → Advanced Settings → Group name attribute. When specifying the group mapping, just set the attribute value (DBA or Dev).
  • Role: There will be no role in the new user management. Instead, it is equivalent to user permission in the new user management which is “No Access”, “Read” or “Admin”.
  • Team: In the new user management, this term is corresponding to “group”. To check out the group, run s9s user --list-groups. A user must belong to a group, thus ClusterControl will automatically map the LDAP user with the mapped group. An LDAP group that is not mapped has no authorization to log into ClusterControl.

2) Now we need to create ClusterControl groups (or you can use any existing groups) for this purpose. Since we are going to have two LDAP groups to log into the ClusterControl system, we will create two ClusterControl groups called “DBA” and “Dev” to be mapped on. Go to ClusterControl → User Management → Teams and Users → Create Team and create the following groups:

  • DBA
  • Dev

3) Optionally, you can map a cluster to a group by going to ClusterControl → User Management → Access Control → Clusters. Click on the Add Team button for the corresponding cluster and specify the following:

  • Team: DBA (select from the dropdown)
  • Permissions: Admin

Repeat the same step to allow access for other groups to any cluster, as in this case is “Dev”.

4) Now we can perform the LDAP group mapping. Go to ClusterControl → User Management → LDAP Settings → Map LDAP Group, and specify the following for group DBA:

  • ClusterControl Team: DBA
  • LDAP Group: DBA (which basically translates to CN=DBA,OU=Groups,DC=s9s,DC=com)

5) Repeat step #4 for the other groups, like in this case Dev:

  • ClusterControl Team: Dev
  • LDAP Group: Dev (which basically translates to CN=Dev,OU=Groups,DC=s9s,DC=com)

6) We can then enable the LDAP authentication by toggling ON Enable LDAP Authentication under ClusterControl → User Management → LDAP Settings → General Settings. Note that you can not delete the last group mapping entry in the list until you disable again LDAP Authentication. In simple words, enabling LDAP authentication is only allowed if there is at least one group mapping entry.

At this point, the LDAP configuration is complete. You may open a new browser and try to authenticate as an LDAP user. The username to log in is the value of Username Attributes.

Troubleshooting

  • ClusterControl Controller (cmon) will log all user authentication into /var/log/cmon.log. Observe this logfile when troubleshooting all LDAP authentication issues.
  • All LDAP configurations will be stored inside this configuration file, /etc/cmon-ldap.cnf. It is recommended to configure LDAP via the ClusterControl UI because any changes to this file will require a reload to the controller process, which is triggered automatically when configuring LDAP via the UI. You may also make direct modifications to the file, however, you have to reload the cmon service manually by using the systemctl restart cmon command, or service cmon restart.
  • For reference, a working LDAP authentication should have the configuration file, /etc/cmon-ldap.cnf looking something like this (example for Active Directory, without TLS):
    $ grep -v '^\s*$\|^\s*\#' /etc/cmon-ldap.cnf
    enabled = true
    ldapServerUri = "ldap://ad.s9s.com"
    ldapAdminUser = "cn=Administrator,cn=Users,dc=s9s,dc=com"
    ldapAdminPassword = "moyGp6pUwLZ"
    ldapUserSearchRoot = "cn=Users,dc=s9s,dc=com"
    ldapGroupSearchRoot = "ou=Groups,dc=s9s,dc=com"
    [ldap_settings]
    ldapUserClassName = ""
    ldapUsernameAttributes = "sAMAccountName"
    ldapRealnameAttributes = "displayName"
    ldapEmailAttributes = "userPrincipalName"
    ldapGroupClassName = ""
    ldapMemberAttributes = "member"
    ldapGroupIdAttributes = "dn"
    ldapGroupNameAttribute = "cn"
    [security]
    [mapping0]
    ldapGroupId   = "DBA"
    cmonGroupName = "DBA"
    [mapping1]
    ldapGroupId   = "Dev"
    cmonGroupName = "Dev"
Was this article helpful to you? Yes 1 No 1