Product SiteDocumentation Site

5.4. Managing Unique UID and GID Number Assignments

A FreeIPA server must generate random UID and GID values and simultaneously ensure that replicas never generate the same UID or GID value. The need for unique UID and GID numbers might even cross FreeIPA domains, if a single organization has multiple disparate domains.
The UID and GID numbers are divided into ranges. By keeping separate numeric ranges for individual servers and replicas, the chances are minimal that any numbers issued by one server or replica will duplicate those from another. Ranges are updated and shared intelligently between servers and replicas through the Dynamic Numeric Assignment (DNA) Plug-in, as part of the backend 389 Directory Server instance for the domain. The same range is used for user IDs (uidNumber) and group IDs (gidNumber). A user and a group may have the same ID, but since the ID is set in different attributes, there is no conflict. Using the same ID number for both a user and a group also allows an administrator to configure user private groups, where a unique system group is created for each user and the ID number is the same for both the user and the group.


When a user is created interactively or without specifying a UID or GID number, then the user account is created with an ID number that is next available in the server or replica range. This means that a user always has a unique number for its UID number and, if configured, for its private group.
If a number is manually assigned to a user entry, the server does not validate that the uidNumber is unique. It will allow duplicate IDs; this is expected (though discouraged) behavior for POSIX entries. The same is true for group entries: a duplicate gidNumber can be manually assigned to the entry.
If two entries are assigned the same ID number, only the first entry is returned in a search for that ID number. However, both entries will be returned in searches for other attributes or with ipa user-find --all.

5.4.1. About ID Range Assignments During Installation

The FreeIPA administrator can initially define a range during server installation, using the --idstart and --idmax options with ipa-server-install. These options are not required, so the setup script can assign random ranges during installation.
If no range is set manually when the first FreeIPA server is installed, a range of 200,000 IDs is randomly selected. There are 10,000 possible ranges. Selecting a random range from that number provides a high probability of non-conflicting IDs if two separate FreeIPA domains are ever merged in the future.
With a single FreeIPA server, IDs are assigned to entries in order through the range. With replicas, the initial server ID range is split and distributed.
When a replica is installed, it is configured with an invalid range. It also has a directory entry (that is shared among replicas) that instructs the replica where it can request a valid range. When the replica starts, or as its current range is depleted so that less than 100 IDs are available, it can contact one of the available servers for a new range allotment. A special extended operation splits the range in two, so that the original server and the replica each have half of the available range.

5.4.2. Adding New Ranges

If the range for the entire domain is close to depletion, a new range can be manually selected and assigned to one of the master servers. All replicas then request ID ranges from the master as necessary.
The changes to the range are done by editing the 389 Directory Server configuration to change the DNA Plug-in instance. The range is defined in the dnaNextRange parameter. For example:
ldapmodify -x -D "cn=Directory Manager" -W -h -p 389
Enter LDAP Password: *******
dn: cn=Posix IDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
changetype: modify
add: dnaNextRange
dnaNextRange: 123400000-123500000


This command only adds the specified range of values; it does not check that the values in that range are actually available. This check is performed when an attempt is made to allocate those values. If a range is added that contains mostly values that were already allocated, the system will cycle through the entire range searching for unallocated values, and then the operation ultimately fails if none are available.