Chapter 40. 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.
40.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 next DNA ID range assigned. A replica uses its next range when it runs out of IDs in its current range. Next 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 next 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.
40.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.
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.
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.
40.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.
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:# 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 ----------------------------
40.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.
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:# 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
Restart the Directory Server service on all IdM servers in the deployment:
# systemctl restart dirsrv@IDM-EXAMPLE-COM.service
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:
# sss_cache -E
Restart the SSSD daemon:
# systemctl restart sssd
NoteIf 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:# 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 ----------------------------
40.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:
$ 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
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.
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
40.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.
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.15 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:
$ cd ~/MyPlaybooks/
Create the
idrange-present.yml
playbook with the following content:--- - 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
- 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:
$ ansible-playbook --vault-password-file=password_file -v -i inventory idrange-present.yml
SSH
toipaserver
and restart the Directory Server:# systemctl restart dirsrv@IDM.EXAMPLE.COM.service
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:# sss_cache -E
On
ipaserver
, restart the SSSD daemon:# systemctl restart sssd
NoteIf 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:
# 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 ----------------------------
Additional resources
40.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.
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:
[root@server ~]# ipa idrange-find
-
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:
[root@server ~]# ipa idrange-del AD.EXAMPLE.COM_id_range
Restart the SSSD service to remove references to the ID range you have removed.
[root@server ~]# systemctl restart sssd
40.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 next 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 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
displays the next DNA ID range currently set on all servers or, if you specify a server, only on the specified server, for example:# 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
40.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.
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.
40.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.
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
:# ipa-replica-manage dnarange-set serverA.example.com 1250-1499
To define the next DNA ID range for a specified server, use
ipa-replica-manage dnanextrange-set
:# ipa-replica-manage dnanextrange-set serverB.example.com 1500-5000
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.