Red Hat Training

A Red Hat training course is available for RHEL 8

Chapter 37. 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.

37.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.

37.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.

37.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 steps

  • 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
----------------------------

37.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

  1. 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 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

  2. 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.

  3. Optional: Update the ID range immediately:

    1. Clear the System Security Services Daemon (SSSD) cache: 

      # sss_cache -E

    2. Restart the SSSD daemon: 

      # systemctl restart sssd
    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 steps

  • 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: 1000000
  Number of IDs in the range: 200000
  Range type: local domain range
----------------------------
Number of entries returned 2
----------------------------

37.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.

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

37.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

  • You know the IdM admin password.

  • You have configured your Ansible control node to meet the following requirements:

    • You are using Ansible version 2.14 or later.
    • You have installed the ansible-freeipa package on the Ansible controller.
    • 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

  1. Navigate to your ~/MyPlaybooks/ directory: 

    $ cd ~/MyPlaybooks/

  2. 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
  3. Save the file.

  4. 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

  5. SSH to ipaserver 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.

  6. Optional: Update the ID range immediately:

    1. On ipaserver, clear the System Security Services Daemon (SSSD) cache: 

      # sss_cache -E

    2. On ipaserver, restart the SSSD daemon: 

      # systemctl restart sssd
    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 steps

  • 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

37.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

  1. Display all the ID ranges that are currently in use: 

    [root@server ~]# ipa idrange-find
  2. 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.

  3. Remove the range: 

    [root@server ~]# ipa idrange-del AD.EXAMPLE.COM_id_range

  4. Restart the SSSD service to remove references to the ID range you have removed. 

    [root@server ~]# systemctl restart sssd

Additional resources

37.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

37.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.

37.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

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 steps