Chapter 23. Adjusting ID ranges manually
An IdM master 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 master installation, or manually define a replica’s DNA ID range.
23.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 IdM master installation. This range cannot be modified after it is created. However, if you need to, 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 Adjusting 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 assigned automatically when a replica is deleted or you can set them manually.
The ranges are updated and shared between the master 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) and its maximum value (the top end of 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.
23.2. Automatic ID ranges assignment
By default, an IdM ID range is automatically assigned during the IdM master 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 Adjusting DNA ID ranges manually. A DNA range matching the IdM ID range is automatically created during installation.
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 master splits and is distributed between the master and replica: the replica receives half of the remaining DNA ID range that is available on the initial master. The master 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. Until then, the replica has no ID range defined.
If the initial master stops functioning before the replica requests a DNA ID range from it, the replica is unable to contact the master 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 master, and assign an ID range to the replica manually.
23.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.
You can define the IdM ID range manually during server installation by using the following two options with
--idstartgives the starting value for UID and GID numbers.
--idmaxgives the maximum UID and GID number; by default, the value is the
--idstartstarting value plus 199,999.
To check if the ID range was assigned correctly, you can display the assigned IdM ID range by using the
# 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 ----------------------------
23.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 need to assign new DNA ID ranges manually as needed. For more information on how to do this, see Adjusting DNA ID ranges manually.
To create a new IdM ID range, use the
ipa idrange-addcommand. You need to specify the new range name, the first ID number of the range and the range size:
# ipa idrange-add IDM.EXAMPLE.COM_new_range --base-id=1000000 --range-size=200000 ------------------------------------------ Added ID range "IDM.EXAMPLE.COM_new_range" ------------------------------------------ Range name: IDM.EXAMPLE.COM_new_range First Posix ID of the range: 1000000 Number of IDs in the range: 200000 Range type: local domain range
You can check if the new range is set correctly by using the
# 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: 1000000 Number of IDs in the range: 200000 Range type: local domain range ---------------------------- Number of entries returned 2 ----------------------------
23.5. 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.
To display which DNA ID ranges are configured for the servers in the topology, use the following commands:
ipa-replica-manage dnarange-showdisplays 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 masterA.example.com: 1001-1500 masterB.example.com: 1501-2000 masterC.example.com: No range set # ipa-replica-manage dnarange-show masterA.example.com masterA.example.com: 1001-1500
ipa-replica-manage dnanextrange-showdisplays 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 masterA.example.com: 2001-2500 masterB.example.com: No on-deck range set masterC.example.com: No on-deck range set # ipa-replica-manage dnanextrange-show masterA.example.com masterA.example.com: 2001-2500
23.6. Automatic DNA ID range extension
When you delete a functioning replica, the
ipa-replica-manage del command retrieves the DNA ID ranges that were assigned to the replica and adds them as a next range to another available IdM replica. This ensures that DNA ID ranges are used efficiently.
After you delete a replica, you can verify which DNA ID ranges are configured for other servers by using the commands described in Displaying currently assigned DNA ID ranges.
23.7. Manual DNA ID range adjustment
In certain situations, it is necessary to manually adjust 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 on 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 dies and needs to 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.
If you want to recover a DNA ID range belonging to a replica that stopped functioning and assign it to another server, you first need to 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 adjust a DNA ID range for a replica using the commands in Adjusting 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.
23.8. Adjusting DNA ID ranges manually
In some cases, you may need to manually adjust Distributed Numeric Assignment (DNA) ID ranges for existing replicas, for example to reassign a DNA ID range assigned to a non-functioning replica. For more information, see Manual DNA ID range adjustment.
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 will fail.
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.
- 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.
To define the current DNA ID range for a specified server, use the
# ipa-replica-manage dnarange-set masterA.example.com 1250-1499
To define the next DNA ID range for a specified server, use the
# ipa-replica-manage dnanextrange-set masterB.example.com 1500-5000
- You can check that the new DNA ranges are set correctly by using the commands described in Displaying the currently assigned DNA ID ranges.