Chapter 38. Adjusting ID ranges manually
Chapter 38. Adjusting ID ranges manually An IdM server generates unique user ID (UID) and group ID (GID) numbers. By creating and assigning different ID ranges to replicas, it also ensures that they never generate the same ID numbers. By default, this process is automatic. However, you can manually adjust the IdM ID range during the IdM server installation, or manually define a replica's DNA ID range. 38.1. ID ranges ID numbers are divided into ID ranges . Keeping separate numeric ranges for individual servers and replicas eliminates the chance that an ID number issued for an entry is already used by another entry on another server or replica. Note that there are two distinct types of ID ranges: The IdM ID range , which is assigned during the installation of the first server. This range cannot be modified after it is created. However, you can create a new IdM ID range in addition to the original one. For more information, see Automatic ID ranges assignment and Adding a new IdM ID range . The Distributed Numeric Assignment (DNA) ID ranges, which can be modified by the user. These have to fit within an existing IdM ID range. For more information, see Assigning DNA ID ranges manually . Replicas can also have a DNA ID range assigned. A replica uses its range when it runs out of IDs in its current range. ranges are not assigned automatically when a replica is deleted and you must assign them manually . The ranges are updated and shared between the server and replicas by the DNA plug-in, as part of the back end 389 Directory Server instance for the domain. The DNA range definition is set by two attributes: The server's available number: the low end of the DNA range The range size: the number of ID's in the DNA range The initial bottom range is set during the plug-in instance configuration. After that, the plug-in updates the bottom value. Breaking the available numbers into ranges allows the servers to continually assign numbers without overlapping with each other. 38.2. Automatic ID ranges assignment IdM ID ranges By default, an IdM ID range is automatically assigned during the IdM server installation. The ipa-server-install command randomly selects and assigns a range of 200,000 IDs from a total of 10,000 possible ranges. Selecting a random range in this way significantly reduces the probability of conflicting IDs in case you decide to merge two separate IdM domains in the future. Note This IdM ID range cannot be modified after it is created. You can only manually adjust the Distributed Numeric Assignment (DNA) ID ranges, using the commands described in Assigning DNA ID ranges manually . A DNA range matching the IdM ID range is automatically created during installation. DNA ID ranges If you have a single IdM server installed, it controls the whole DNA ID range. When you install a new replica and the replica requests its own DNA ID range, the initial ID range for the server splits and is distributed between the server and replica: the replica receives half of the remaining DNA ID range that is available on the initial server. The server and replica then use their respective portions of the original ID range for new user or group entries. Also, if the replica is close to depleting its allocated ID range and fewer than 100 IDs remain, the replica contacts the other available servers to request a new DNA ID range. Important When you install a replica, it does not immediately receive an ID range. A replica receives an ID range the first time the DNA plug-in is used, for example when you first add a user. If the initial server stops functioning before the replica requests a DNA ID range from it, the replica is unable to contact the server to request the ID range. Attempting to add a new user on the replica then fails. In such situations, you can find out what ID range is assigned to the disabled server , and assign an ID range to the replica manually . 38.3. Assigning the IdM ID range manually during server installation You can override the default behavior and set an IdM ID range manually instead of having it assigned randomly. Important Do not set ID ranges that include UID values of 1000 and lower; these values are reserved for system use. Also, do not set an ID range that would include the 0 value; the SSSD service does not handle the 0 ID value. Procedure You can define the IdM ID range manually during server installation by using the following two options with ipa-server-install : --idstart gives the starting value for UID and GID numbers. --idmax gives the maximum UID and GID number; by default, the value is the --idstart starting value plus 199,999. Verification To check if the ID range was assigned correctly, you can display the assigned IdM ID range by using the ipa idrange-find command: 38.4. Adding a new IdM ID range In some cases, you may want to create a new IdM ID range in addition to the original one; for example, when a replica has run out of IDs and the original IdM ID range is depleted. Important Adding a new IdM ID range does not create new DNA ID ranges automatically. You must assign new DNA ID ranges to replicas manually as needed. For more information about how to do this, see assigning DNA ID ranges manually . Procedure To create a new IdM ID range, use the ipa idrange-add command. You must specify the new range name, the first ID number of the range, the range size, and the first RID number of the primary and secondary RID range: Restart the Directory Server service on all IdM servers in the deployment: This ensures that when you create users with UIDs from the new range, they have security identifiers (SIDs) assigned. Optional: Update the ID range immediately: Clear the System Security Services Daemon (SSSD) cache: Restart the SSSD daemon: Note If you do not clear the SSSD cache and restart the service, SSSD only detects the new ID range when it updates the domain list and other configuration data stored on the IdM server. Verification You can check if the new range is set correctly by using the ipa idrange-find command: 38.5. The role of security and relative identifiers in IdM ID ranges An Identity Management (IdM) ID range is defined by several parameters: The range name The first POSIX ID of the range The range size: the number of IDs in the range The first relative identifier (RID) of the corresponding RID range The first RID of the secondary RID range You can view these values by using the ipa idrange-show command: Security identifiers The data from the ID ranges of the local domain are used by the IdM server internally to assign unique security identifiers (SIDs) to IdM users and groups. The SIDs are stored in the user and group objects. A user's SID consists of the following: The domain SID The user's relative identifier (RID), which is a four-digit 32-bit value appended to the domain SID For example, if the domain SID is S-1-5-21-123-456-789 and the RID of a user from this domain is 1008, then the user has the SID of S-1-5-21-123-456-789-1008. Relative identifiers The RID itself is computed in the following way: Subtract the first POSIX ID of the range from the user's POSIX UID, and add the first RID of the corresponding RID range to the result. For example, if the UID of idmuser is 196600008, the first POSIX ID is 196600000, and the first RID is 1000, then idmuser 's RID is 1008. Note The algorithm computing the user's RID checks if a given POSIX ID falls into the ID range allocated before it computes a corresponding RID. For example, if the first ID is 196600000 and the range size is 200000, then the POSIX ID of 1600000 is outside of the ID range and the algorithm does not compute a RID for it. Secondary relative identifiers In IdM, a POSIX UID can be identical to a POSIX GID. This means that if idmuser already exists with the UID of 196600008, you can still create a new idmgroup group with the GID of 196600008. However, a SID can define only one object, a user or a group. The SID of S-1-5-21-123-456-789-1008 that has already been created for idmuser cannot be shared with idmgroup . An alternative SID must be generated for idmgroup . IdM uses a secondary relative identifier , or secondary RID, to avoid conflicting SIDs. This secondary RID consists of the following: The secondary RID base A range size; by default identical with the base range size In the example above, the secondary RID base is set to 1000000. To compute the RID for the newly created idmgroup : subtract the first POSIX ID of the range from the user's POSIX UID, and add the first RID of the secondary RID range to the result. idmgroup is therefore assigned the RID of 1000008. Consequently, the SID of idmgroup is S-1-5-21-123-456-789-1000008. IdM uses the secondary RID to compute a SID only if a user or a group object was previously created with a manually set POSIX ID. Otherwise, automatic assignment prevents assigning the same ID twice. Additional resources Using Ansible to add a new local IdM ID range 38.6. Using Ansible to add a new local IdM ID range In some cases, you may want to create a new Identity Management (IdM) ID range in addition to the original one; for example, when a replica has run out of IDs and the original IdM ID range is depleted. The following example describes how to create a new IdM ID range by using an Ansible playbook. Note Adding a new IdM ID range does not create new DNA ID ranges automatically. You need to assign new DNA ID ranges manually as needed. For more information about how to do this, see Assigning DNA ID ranges manually . Prerequisites On the control node: You are using Ansible version 2.13 or later. You have installed the ansible-freeipa package. The example assumes that in the ~/ MyPlaybooks / directory, you have created an Ansible inventory file with the fully-qualified domain name (FQDN) of the IdM server. The example assumes that the secret.yml Ansible vault stores your ipaadmin_password . The target node, that is the node on which the ansible-freeipa module is executed, is part of the IdM domain as an IdM client, server or replica. Procedure Navigate to your ~/ MyPlaybooks / directory: Create the idrange-present.yml playbook with the following content: Save the file. Run the Ansible playbook. Specify the playbook file, the file storing the password protecting the secret.yml file, and the inventory file: SSH to ipaserver and restart the Directory Server: This ensures that when you create users with UIDs from the new range, they have security identifiers (SIDs) assigned. Optional: Update the ID range immediately: On ipaserver , clear the System Security Services Daemon (SSSD) cache: On ipaserver , restart the SSSD daemon: Note If you do not clear the SSSD cache and restart the service, SSSD only detects the new ID range when it updates the domain list and other configuration data stored on the IdM server. Verification You can check if the new range is set correctly by using the ipa idrange-find command: Additional resources The role of security and relative identifiers in IdM ID ranges 38.7. Removing an ID range after removing a trust to AD If you have removed a trust between your IdM and Active Directory (AD) environments, you might want to remove the ID range associated with it. Warning IDs allocated to ID ranges associated with trusted domains might still be used for ownership of files and directories on systems enrolled into IdM. If you remove the ID range that corresponds to an AD trust that you have removed, you will not be able to resolve the ownership of any files and directories owned by AD users. Prerequisites You have removed a trust to an AD environment. Procedure Display all the ID ranges that are currently in use: Identify the name of the ID range associated with the trust you have removed. The first part of the name of the ID range is the name of the trust, for example AD.EXAMPLE.COM_id_range . Remove the range: Restart the SSSD service to remove references to the ID range you have removed. Additional resources See Removing the trust using the command line . See Removing the trust using the IdM Web UI . 38.8. Displaying currently assigned DNA ID ranges You can display both the currently active Distributed Numeric Assignment (DNA) ID range on a server, as well as its DNA range if it has one assigned. Procedure To display which DNA ID ranges are configured for the servers in the topology, use the following commands: ipa-replica-manage dnarange-show displays the current DNA ID range that is set on all servers or, if you specify a server, only on the specified server, for example: ipa-replica-manage dnanextrange-show displays the DNA ID range currently set on all servers or, if you specify a server, only on the specified server, for example: 38.9. Manual ID range assignment In certain situations, it is necessary to manually assign a Distributed Numeric Assignment (DNA) ID range, for example when: A replica has run out of IDs and the IdM ID range is depleted A replica has exhausted the DNA ID range that was assigned to it, and requesting additional IDs failed because no more free IDs are available in the IdM range. To solve this situation, extend the DNA ID range assigned to the replica. You can do this in two ways: Shorten the DNA ID range assigned to a different replica, then assign the newly available values to the depleted replica. Create a new IdM ID range, then set a new DNA ID range for the replica within this created IdM range. For information about how to create a new IdM ID range, see Adding a new IdM ID range . A replica stopped functioning A replica's DNA ID range is not automatically retrieved when the replica stops functioning and must be deleted, which means the DNA ID range previously assigned to the replica becomes unavailable. You want to recover the DNA ID range and make it available for other replicas. To do this, find out what the ID range values are , before manually assigning that range to a different server. Also, to avoid duplicate UIDs or GIDs, make sure that no ID value from the recovered range was previously assigned to a user or group; you can do this by examining the UIDs and GIDs of existing users and groups. You can manually assign a DNA ID range to a replica using the commands in Assigning DNA ID ranges manually . Note If you assign a new DNA ID range, the UIDs of the already existing entries on the server or replica stay the same. This does not pose a problem because even if you change the current DNA ID range, IdM keeps a record of what ranges were assigned in the past. 38.10. Assigning DNA ID ranges manually In some cases, you may need to manually assign Distributed Numeric Assignment (DNA) ID ranges to existing replicas, for example to reassign a DNA ID range assigned to a non-functioning replica. For more information, see Manual ID range assignment . When adjusting a DNA ID range manually, make sure that the newly adjusted range is included in the IdM ID range; you can check this using the ipa idrange-find command. Otherwise, the command fails. Important Be careful not to create overlapping ID ranges. If any of the ID ranges you assign to servers or replicas overlap, it could result in two different servers assigning the same ID value to different entries. Prerequisites Optional. If you are recovering a DNA ID range from a non-functioning replica, first find the ID range using the commands described in Displaying currently assigned DNA ID ranges . Procedure To define the current DNA ID range for a specified server, use ipa-replica-manage dnarange-set : To define the DNA ID range for a specified server, use ipa-replica-manage dnanextrange-set : Verification You can check that the new DNA ranges are set correctly by using the commands described in Displaying the currently assigned DNA ID ranges .
ipa idrange-find --------------- 1 range matched --------------- Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 882200000 Number of IDs in the range: 200000 Range type: local domain range ---------------------------- Number of entries returned 1 ---------------------------- ipa idrange-add IDM.EXAMPLE.COM_new_range --base-id 5000 --range-size 1000 --rid-base 300000 --secondary-rid-base 1300000 --type ipa-local ipa: WARNING: Service dirsrv@IDM-EXAMPLE-COM.service requires restart on IPA server <all IPA servers> to apply configuration changes. ------------------------------------------ Added ID range "IDM.EXAMPLE.COM_new_range" ------------------------------------------ Range name: IDM.EXAMPLE.COM_new_range First Posix ID of the range: 5000 Number of IDs in the range: 1000 First RID of the corresponding RID range: 300000 First RID of the secondary RID range: 1300000 Range type: local domain range systemctl restart dirsrv@IDM-EXAMPLE-COM.service sss_cache -E systemctl restart sssd ipa idrange-find ---------------- 2 ranges matched ---------------- Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 882200000 Number of IDs in the range: 200000 Range type: local domain range Range name: IDM.EXAMPLE.COM_new_range First Posix ID of the range: 5000 Number of IDs in the range: 1000 First RID of the corresponding RID range: 300000 First RID of the secondary RID range: 1300000 Range type: local domain range ---------------------------- Number of entries returned 2 ---------------------------- ipa idrange-show IDM.EXAMPLE.COM_id_range Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 196600000 Number of IDs in the range: 200000 First RID of the corresponding RID range: 1000 First RID of the secondary RID range: 1000000 Range type: local domain range cd ~/ MyPlaybooks / --- - name: Playbook to manage idrange hosts: ipaserver become: no vars_files: - /home/user_name/MyPlaybooks/secret.yml tasks: - name: Ensure local idrange is present ipaidrange: ipaadmin_password: "{{ ipaadmin_password }}" name: new_id_range base_id: 12000000 range_size: 200000 rid_base: 1000000 secondary_rid_base: 200000000 ansible-playbook --vault-password-file=password_file -v -i inventory idrange-present.yml systemctl restart dirsrv@IDM.EXAMPLE.COM.service sss_cache -E systemctl restart sssd ipa idrange-find ---------------- 2 ranges matched ---------------- Range name: IDM.EXAMPLE.COM_id_range First Posix ID of the range: 882200000 Number of IDs in the range: 200000 Range type: local domain range Range name: IDM.EXAMPLE.COM_new_id_range First Posix ID of the range: 12000000 Number of IDs in the range: 200000 Range type: local domain range ---------------------------- Number of entries returned 2 ---------------------------- ipa idrange-find ipa idrange-del AD.EXAMPLE.COM_id_range systemctl restart sssd ipa-replica-manage dnarange-show serverA.example.com: 1001-1500 serverB.example.com: 1501-2000 serverC.example.com: No range set ipa-replica-manage dnarange-show serverA.example.com serverA.example.com: 1001-1500 ipa-replica-manage dnanextrange-show serverA.example.com: 2001-2500 serverB.example.com: No on-deck range set serverC.example.com: No on-deck range set ipa-replica-manage dnanextrange-show serverA.example.com serverA.example.com: 2001-2500 ipa-replica-manage dnarange-set serverA.example.com 1250-1499 ipa-replica-manage dnanextrange-set serverB.example.com 1500-5000