5. Managing users

If ClusterVisor was installed with its full suite of features, it installs and sets up an LDAP server (specifically, a 389 directory server) to use for managing users and groups across the cluster. The page in ClusterVisor to manage the users and groups can be found under Users/groups and behaves much like Configuration page. The Users/groups page has two tabs, Users and Groups, and in this section all actions for users and groups will be occurring in those two tabs.

View all users and groups

All of the users and groups managed by ClusterVisor will be listed in the Users and Groups tabs, respectively. It should be noted that this is not all of the users and groups available on the cluster since users and groups can still be created natively on a node (e.g. using useradd and groupadd).

Using the command line

All of the users and groups managed by ClusterVisor can be viewed using the cv-useradm utility. Specifically, this can be done by running:

CODE

$ cv-useradm --show-all
or
$ cv-useradm -sa

This will display all of the users and groups, with the users at the top and the groups listed at the bottom, and they are ordered by the ID of the user/group (which is listed in parentheses). The users added to the nodes natively can still be viewed from the /etc/passwd and /etc/group files, but are not managed by ClusterVisor. There is, however, a way to synchronize the natively added users across the cluster if using LDAP for user management is not desired, which is explained further in the Synchronizing native users section of this guide.

Adding a user

From the Users tab, above the listed entries of users is an input box to the left of the Add User button. In the input box, put in the desired username for the new user and click on the Add User button. This will present a pop-up window with two tabs, General and Additional Info, and in both tabs all fields that are prefixed with an asterisk ( * ) are required fields that need to be given a value for the user to be added. Some of those fields will be automatically filled out with sane defaults, so unless there is a necessity to change them they can be left as-is.

The non-required fields do not need to be filled out and are presented only as a convenience. For this reason, the fields under the Additional Info tab can be ignored in most cases. However, it should be noted that the non-required field SSH Public Key under the General tab will also serve the purpose of allowing the user to login via SSH regardless of whether the /home directory is mounted on the system or not. Usually this is not the case since a user's SSH public key is typically stored under the .ssh directory in the user's home directory (so it is no longer present if the /home directory is not mounted).

Using the command line

A user can be added in ClusterVisor from the command line using the cv-useradm utility. This can be done by running the following command:

CODE

$ cv-useradm --add user.<username>
or
$ cv-useradm -a user.<username>

Where <username> would be replaced with the desired username for the new user. Similar to using the --add flag with cv-conf, the interface is presented in YAML by default with the editable fields at the top and the documentation of each possible field at the bottom. Like the web interface, most of the fields will be populated automatically with sane defaults, but the cn field will still need to be edited with the full name of the user along with displayName for the displayed name of the user. Upon saving and exiting the file, a prompt will be given to add a password to the new user. Once this is done, the user has been added and is ready for use.

Changing a user's password

From the Users tab, in the Actions column for each user is a Password button. Clicking this brings up a pop-up window to put in a new password for the user, which can be applied by clicking the Change password button.

Using the command line

The method for changing a password in ClusterVisor depends on whether a user wants to change their own password or if the root user wants to change another user's password. For the former, this can be done like any other account using the passwd utility. For the latter, the root user is not allowed to change a ClusterVisor user's password using passwd, so instead needs to use cv-useradmin with the --password flag to change a user's password. This will present a prompt to enter and then re-enter the new password, after which the password will be changed for the user.

Adding a group

From the Groups tab, above the listed entries of users is an input box to the left of the Add Group button. In the input box, put in the desired name for the new group and click on the Add Group button. Similar to adding a user, sane defaults will be filled out for some of the fields, so only the Description field needs to be filled out. Optionally, the group can also assign members to it under the Members field, but this can also be done later after the group is created.

Using the command line

A group can be added in ClusterVisor from the command line using the cv-useradm utility. This can be done by running the following command:

CODE

$ cv-useradm --add group.<name>
or
$ cv-useradm -a group.<name>

Where <name> would be replaced with the desired name for the new group. Similar to using the --add flag with cv-conf, the interface is presented in YAML by default with the editable fields at the top and the documentation of each possible field at the bottom. Like the web interface, most of the fields will be populated automatically with sane defaults, but the description field will still need to be edited with a description of the new group and optionally a list of the members of the group (which can also be added later). The group will be added once the file has been saved and exited.

Group management for users

A user can be added/removed from a group in two different ways in ClusterVisor, either from the Users tab or the Groups tab. To do so from the Users tab, in the Actions column for each user is a Groups button, and clicking it will bring up a pop-up window to select which groups to add/remove from the user. To do so from the Groups tab, clicking the Edit button from a group's Action column will bring up a pop-up window to select which users to add/remove from the group.

Each of these methods has its pros and cons, primarily depending upon whether a user needs to be added/removed from any groups (in which case, use the Users tab) or if multiple users need to be added/removed from a group (in which case, use the Groups tab).

Using the command line

Similar to the web interface, a user can be added/removed from a group in two different ways from the command line, both of which are done using the cv-useradm utility. To add/remove multiple groups from a single user, the --group-membership flag should be used on the user and the groups can be added/removed by changing the value of the group between true/false (true meaning the user is added to the group, and false meaning the user is removed from the group). To do the inverse of adding/removing multiple users from a single group, the --edit flag should be used on the group to add/remove users from the member field. The available users will be listed below in the documentation portion, and be sure to format the entries as user.<username> where <username> is replaced with the username of the user.

If all users are being removed from a group, the value should be set to [], otherwise it will fail validation because the member field is not a list.

Modifying a user

From the Users tab, in the Actions column for each user is an Edit button and clicking this brings up a pop-up window showing all of the configurable fields of the user. Any of these fields can be changed, but if any of the required fields (those prefixed with an asterisk) are left blank when the changes are saved it will not commit the changes until either the required fields are given a value or the pop-up window is closed (which will discard all of the changes).

Using the command line

A user can be modified in ClusterVisor from the command line using the cv-useradm utility. This can be done by running the following command:

CODE

$ cv-useradm --edit user.<username>
or
$ cv-useradm -e user.<username>

Where <username> would be replaced with the username for the user being modified. Similar to using the --edit flag with cv-conf, the interface is presented in YAML by default with the editable fields at the top and the documentation of each possible field at the bottom. Like with the web interface, there are required fields (designated with the term required next to the field's name in the documentation below) that need to have a value to pass validation before any saved changes are committed. Assuming validation passed, upon saving and exiting the file the changes will be applied.

Modifying a group

From the Groups tab, in the Actions column for each group is an Edit button and clicking this brings up a pop-up window showing all of the configurable fields of the group. Any of these fields can be changed, but if any of the required fields (those prefixed with an asterisk) are left blank when the changes are saved it will not commit the changes until either the required fields are given a value or the pop-up window is closed (which will discard all of the changes).

Using the command line

A group can be modified in ClusterVisor from the command line using the cv-useradm utility. This can be done by running the following command:

CODE

$ cv-useradm --edit group.<name>
or
$ cv-useradm -e group.<name>

Where <name> would be replaced with the name for the group being modified. Similar to using the --edit flag with cv-conf, the interface is presented in YAML by default with the editable fields at the top and the documentation of each possible field at the bottom. Like with the web interface, there are required fields (designated with the term required next to the field's name in the documentation below) that need to have a value to pass validation before any saved changes are committed. Assuming validation passed, upon saving and exiting the file the changes will be applied.

Removing a user / group

The process for removing a user and group is the same. From the Actions column for each user /group is an Edit button and clicking this brings up a pop-up window. At the bottom of this window is a red Delete button, and when clicked this will provide a confirmation box to verify that the user / group should be deleted (in case clicked by accident). In the case of the user, while this process will remove the user its home directory will remain until manually deleted.

Using the command line

A user / group can be removed in ClusterVisor from the command line using the cv-useradm utility. This can be done by running the following command:

CODE

$ cv-useradm --delete user.<username>
$ cv-useradm --delete group.<name>
or
$ cv-useradm -d user.<username>
$ cv-useradm -d group.<name>

Where <username> would be replaced with the username for the user being removed and <name> would be replaced with the name of the group being removed. This will display a prompt asking if the user / group should truly be removed or giving the option to quit the operation in case it was done by mistake. This dialog can be skipped by also passing the --yes flag, which will agree to removing the user /group without confirmation. Same as the web interface, a user's home directory will remain until manually removed.

Configuring LDAP

While ClusterVisor provides its own 389 directory server with sane default configurations, these settings can be modified along with replacing the LDAP server being used altogether. These configurations can be accessed from the Configuration page under the Configuration collection, specifically the config.ldap section. The usage of some of the less obvious fields (not already explained by their descriptions) is as follows:

Manage users / group - Determines whether or not ClusterVisor is managing an LDAP instance. This will effectively disable the Users / Groups page and all command line utilities that manage the LDAP users (e.g., cv-useradm).
LDAP URI - This is what points to the actual LDAP server being used. Keep in mind that if a non-389 directory server LDAP instance is used, the Manage users / groups field should most likely to be set to true to prevent unanticipated behavior.
LDAP CA Cert - This stores the contents of the CA SSL certificate for LDAP.
Min UID - There can be issues if a UID in LDAP clashes with the UIDs from the native users on the system. This field determines at what point the automatically generated UID will be given for the ClusterVisor users (which should at the very least start at 2000, but it is recommended to use something higher like 10000).
Min GID - Same as Min UID but for the GID; the same principles apply.
Default user GID - As opposed to automatically assigning users to their own groups, ClusterVisor will by default assign users to a single default group to make managing group permissions easier. This is the GID number that users will be assigned to be default.
Triggers - This provides a way to have scripts automatically triggered when actions are performed on ClusterVisor's users or groups. By default all types of triggers are already assigned a script, but they are intentionally left blank so that they can be edited rather than needing new scripts assigned (although there would be no issue if multiple scripts were assigned to the same type of trigger). An example use case for a trigger would be to clean up the home directory of the user being deleted.

Using the command line

The config.ldap section is modified just like any other section. For documentation on modifying configurations in ClusterVisor, see section Configurations in ClusterVisor of this guide.

Synchronizing native users

On the cluster there are different types: users that are managed by ClusterVisor and users that are not managed by ClusterVisor. The latter can be broken down into two further categories: users that are managed by some other service (e.g., Active Directory) and users that were natively added onto the system (e.g. using useradd), the latter being the focus of this section.

If users are not being managed by ClusterVisor, but there is still a desire to synchronize users across the cluster, ClusterVisor provides a system that can facilitate this through authsync. This feature is not enabled by default since the preferred method of user management in ClusterVisor is through its LDAP server, but it can be enabled by doing the following:

From the Configuration page under the Configuration collection, click the Edit button under the Actions column of the config.global section.
In the pop-up window, navigate to the Authsync tab.
For the Source field, from the drop-down menu select the node that will be the "source of truth" for the users/groups that will be synchronized to the other nodes (this will typically be the head node).
For the Minimum UID field, setting this to 1000 will only sync user accounts (since their UIDs start at 1000) while setting it to 0 will sync all accounts (however, using 0 can cause issues if the system users on the nodes do not match the UID of the source node).
For the Minimum GID field, this will typically match the Minimum UID field but can differ if a different set of groups needs to be synchronized.
For the Lookup method field, using getent will synchronize all users of the system (both native and non-native users) and using files will only synchronize native users (if LDAP is still being used, use files to avoid creating duplicate users).
Save the changes made.
Navigate to the Node collection and edit the Authsync field (found under the General tab) for each node section desired to be synchronized with the source node.
Optionally, if you only want to sync the root user (as opposed to all users on the system) you would set the Authsync option field to "root only".
Save the changes made for each edited node section.

From this point, the cv-authsync utility can be used to synchronize the users/groups from the source node to the selected nodes (using the node selector flags, to sync all node use the --all flag). As well, to help automate the synchronization whenever changes are made to the native nodes, the auth watch daemon can be enabled to do so by running the following on the source node selected earlier:

CODE

$ systemctl enable --now cv-auth-watchd

This will simultaneously start the daemon and enable it to start up automatically on all following reboots. This daemon will check to see if any native users have been changed, and if so will automatically run cv-authsync --all to sync the changes to the other nodes.

As stated earlier, none of this needs to be done if users are being managed through ClusterVisor or some other service. This is only if native users are being used and need to be synchronized across the other nodes in the cluster.