User management reconfiguration

You can change user management control between local and LDAP-based user management or from one LDAP server to another using the Reconfiguration workflow. This section provides guidance for the different reconfiguration options.

Switching from local user management to LDAP-based user management

You can use the reconfiguration workflow to switch from local to central LDAP-based user management for a provisioned zCX instance. To preserve access and data for the existing local users (including the default administrator), you should define users and groups with corresponding attributes in the LDAP server.

The login access of the default administrator user will be removed when switching from local to LDAP-based user management because the local administrator role and capabilities are not needed to manage users centrally. However, the home directory of the administrator will remain intact. If the zCX instance has no other users, you can follow the instructions in Example of LDAP user management for zCX to define groups and users in your LDAP server.

If you want preserve the access and data of additional users and groups, you should recreate them in the LDAP server with the same attributes they had locally. (LDAP groups should have the same names and group IDs. LDAP users should have the same user names, LDAP uidNumbers corresponding to local uids, primary group assignments, and home directory settings.)

For example, imagine a zCX instance switching to OpenLDAP with existing local group appliance1 and users user1 and user2. The users and group have the following attributes:
  • Local group appliance1 has a group ID (gid) of 1004
  • Local user user1 has a user ID (uid) of 5001, primary group of appliance1, and home directory of /home/user1
  • Local user user2 has a user ID (uid) of 5002, primary group of appliance1, and home directory of /home/user2
Ignoring all other groups and users, the directory tree structure in the LDAP server is:
  • dc=example,dc=come
    • ou=Groups
      • cn=appliance1
    • ou=People
      • uid=user1
      • uid=user2
The posixGroup appliance1 can be defined in the LDAP server as follows:
dn: cn=appliance1,ou=groups,dc=example,dc=com
objectClass: top
objectClass: posixGroup
cn: appliance1
gidNumber: 1004
memberUid: user1
memberUid: user2
Note that the gidNumber matches that of the gid number of the local group appliance1.
The posixAccount user1 can be defined in the LDAP server as follows:
dn: uid=user1,ou=People, dc=example,dc=com
objectClass: shadowAccount
objectClass: posixAccount
objectClass: inetOrgPerson
cn: user1
gidNumber: 1004
homeDirectory: /home/user1
sn: user1
uid: user1
uidNumber: 5001
displayName: user1
gecos: user1
givenName: user1
loginShell: /bin/bash
The attribute uid corresponds to Linux login id while the uidNumber is user’s Linux uid. The uidNumber should match that of local user user1 (5001 in this example). The gidNumber corresponds to this user's primary group (1004 in this example). The attribute homeDirectory should also match the local home directory of the user.

User entries can be added to LDAP server by saving the user definitions in LDIF files and using the lparadd command. Passwords for LDAP users can be set using the ldappasswd command.

Switching from LDAP-based user management to local user management

You can use the reconfiguration workflow to switch from LDAP-based to local user management.

The home directories of the LDAP users who had access to the zCX instance will remain intact. For the same users to have access to the reconfigured zCX instance, the administrator must individually create local user accounts with corresponding attributes to those defined on the LDAP server.

For example, imagine a user with account name user1 defined in the LDAP with the following attributes:
  • user1 has a user ID of 5001
  • user1 has the LDAP server home directory /home/user1
  • user1 is part of the group appliance1 with a group ID of 1004
The administrator should execute the following steps to ensure that the user can log into the reconfigured zCX instance with access to the home directory created during their first LDAP-based login:
  1. Create the local group appliance1 with groups ID (gid) of 1004
    sudo groupadd  -g 1004 appliance1
  2. Create the local user user1 with the attributes identical to those defined in the LDAP server:
    sudo adduser --uid 5005 --ingroup docker --home /home/user1 user1
    sudo adduser user1appliance1

An additional step is required when a zCX instance is reconfigured from local to LDAP-based user management, and then back to local user management. The passwords of the original local users are deleted when the zCX instance is reconfigured from local to RPL-based user management. Therefore, when it is switched back to local user management, an administrator must set the passwords for the local users.

Switching between LDAP servers

You can use the reconfiguration workflow to switch user management from one LDAP server to another.

If the new LDAP server uses the exact same directory structure as the existing server, then all user groups will be maintained and home directories will remain accessible, as in a failover scenario. However, if the new LDAP server has a different directory structure, then current users and groups do not exist in the new server and will be unable log in after reconfiguration. The home directories of these users will remain intact. For access to the new server, the groups and users should be recreated in the new server with the same LDAP entry attributes. If only some of the users are defined on the new LDAP server, only they will have to access the reconfigured zCX instance.