Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Assigning and managing unique numeric attribute values

Some entry attribute values require a unique number, such as uidNumber and gidNumber. Using the Distributed Numeric Assignment (DNA) plug-in, you can configure Directory Server to generate and assign unique numbers from the configured range of numbers automatically to specified attributes.

Note

The DNA plug-in does not guarantee attribute uniqueness. If you manually assigned a value from the range that the plug-in manages, the plug-in does not check if the value is unique.

With DNA plug-in, you can effectively avoid replication conflicts by setting different ranges for different local DNA plug-in instances on suppliers. For example, supplier A can assign numbers from 1 to 1000, and supplier B can assign numbers from 1001 to 2000. This ensures that each supplier is using a truly unique set of numbers.

3.1. About Dynamic Number Assignments
Copy link

The DNA plug-in assigns a range of available numbers that instance can issue. Two attributes define the range definition: the server next available number (the botton value of the range) and its maximum value (the upper value of the range). You set the initial bottom value when you configure the plug-in. Later, the plug-in udates this bottom value.

By breaking the available numbers into separate ranges on each replica, the servers can continually assign numbers without overlapping with each other.

3.1.1. Filters, searches, and target entries
Copy link

The server performs a sorted search internally to verify if another server has already taken the next specified range, requiring the managed attribute to have an equality index with the proper ordering matching rule.

The DNA plug-in is always applied to a specific area of the directory tree (the scope) and specific entry types within that subtree (the filter).

Important

The DNA plug-in works only on a single database, unable to manage number assignments for multiple databases. The DNA plug-in uses the sort control to check whether a value has been manually allocated outside of the DNA plug-in. However, this validation using the sort control works only on a single database.

Use a magic value (dnaMagicRegen) as a template value for the attribute that the DNA plug-in manages. This magic value is something outside the server range, a number or even a word. When an entry is added with the magic value and the entry is within the configured scope and filter of the DNA plug-in, the magic value automatically triggers the plug-in to generate a new unique value.

For example, you can add zero (0) as a magic value by using the ldapmodify utility: 

#  ldapmodify -D "cn=Directory Manager" -W -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: posixAccount
uid: jsmith *cn: John Smith
uidNumber: 0
gidNumber: 0
Copy to Clipboard Toggle word wrap

With the configured dnaMagicRegen, the DNA plug-in generates unique values only for attributes whose values are equal to the magic values when the entry is added. If you do not set the magic value for the DNA plug-in, then the plug-in overwrites any value of the managed attributes.

Note
In a situation, where the DNA plug-in manages only one attribute and the added entry does not contain the managed attribute, the add operation triggers the DNA plug-in to add this attribute and generate the unique value for it.

3.1.3. Multiple attributes in the same range
Copy link

The DNA plug-in can assign unique numbers to a single or multiple attribute types from a single range of unique numbers.

This offers multiple options for assigning unique numbers to attributes:

  • A single number for a single attribute type from a unique range.
  • The same unique number for two attributes in one entry.
  • Two different attributes assigned two different numbers from the same range of unique numbers.

In many cases, it is sufficient to have a unique number assigned per attribute type. For example, when assigning an employeeID to a new employee entry, it is crucial to ensure each employee entry receives a unique employeeID.

However, you can assign unique numbers from the same range of numbers to multiple attributes. For example, when assigning uidNumber and gidNumber to a posixAccount entry, the DNA plug-in can assign the same number to both attributes. To achieve this, pass both managed attributes to the modify operation and specify the magic value (0) using the ldapmodify utility: 

#  ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x

dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: uidNumber
uidNumber: 0
-
add:gidNumber
gidNumber: 0
Copy to Clipboard Toggle word wrap

When the DNA plug-in handles multiple attributes, it can assign a unique value to only one attribute if the object class permits only one. For example, the posixGroup object class allows gidNumber but not uidNumber. If the DNA plug-in manages both uidNumber and gidNumber, it assigns a unique number for gidNumber from the uidNumber and gidNumber attribute range when creating a posixGroup entry. Sharing a pool for all managed attributes ensures consistent assignment of unique numbers, preventing conflicts where uidNumber and gidNumber on different entries end up with the same number from separate ranges.

If the DNA plug-in manages multiple attributes, it assigns the same value to all of them in a single modify operation. However, in cases, where an entry does not allow each type of attribute defined for the range, or an entry allows all of the attributes types defined, but only a subset of the attributes require the unique value, you must assign different numbers from the same range by performing separate modify operations. For example: 

# ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: uidNumber
idNumber: 0
^D

# ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: uid=jsmith,ou=people,dc=example,dc=com
changetype: modify
add: employeeId
employeeId: magic
Copy to Clipboard Toggle word wrap

Example 3.1. Example. DNA and Unique Bank Account Numbers

Example Bank wants to use the same unique number for a customer’s primaryAccount and customerID attributes. The Example Bank administrator configured the DNA plug-in to assign unique values for both attributes from the same range.

Additionally, the bank wants to assign numbers for secondary accounts from the same range as the customer ID and primary account numbers, but these numbers cannot be the same as the primary account numbers. The Example Bank administrator configures the DNA plug-in to also manage the secondaryAccount attribute, but will only add the secondaryAccount attribute to an entry after the entry is created and the primaryAccount and customerID attributes are assigned. This ensures that primaryAccount and customerID share the same unique number, and any secondaryAccount numbers are entirely unique but still from the same range of numbers.

3.2. Syntax of the DNA plug-in
Copy link

The Distributed Numeric Assignment (DNA) plug-in itself is a container entry with the distinguished name (DN) cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config. Each DNA entry under the DNA plug-in entry defines a new managed range for the DNA plug-in. Therefore, to configure new managed ranges for the DNA plug-in, create entries under the container entry. For example, if you want the plug-in to manage uidNumber attribute in entries, create the cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config configuration entry where you define ranges and other plug-in settings.

The plug-in syntax varies on whether you configure the plug-in for the use on a single server or across multiple servers in a replication topology.

DNA plug-in syntax for a single server

If you use the plug-in on a single server, a basic DNA configuration entry defines the following attributes:

dnaType
Defines the attribute which value the plug-in manages.
dnaScope
Defines the entry (DN) the plug-in uses as the base to search for entries.
dnaFilter
Defines the search filter the plug-in uses to identify entries to manage.
dnaNextValue
Defines the next available value that the plug-in assigns after an entry is created.

The following is the example of the DNA configuration entry on a single server for a single attribute type: 

dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
objectClass: top
objectClass: dnaPluginConfig
cn: Account UIDs
dnatype: uidNumber
dnafilter: (objectclass=posixAccount)
dnascope: ou=people,dc=example,dc=com
dnaNextValue: 1
Copy to Clipboard Toggle word wrap

DNA plug-in syntax for servers in replication topology

To configure distributed numeric assignments on multiple suppliers, the configuration entry must also contain the following information to share and transfer ranges:

dnaMaxValue
Defines the maximum number that the server can assign.
dnaThreshold
Defines the threshold where the range is low enough to trigger a range transfer. If dnaThreshold is not set, the default value is 1.
dnaRangeRequestTimeout
Defines a timeout period that a server waits for an answer from another server when requesting a range transfer. If the server does not receive the range within this time period, the range transfer request goes to another server. By default, the value is set to 10 seconds.
dnaSharedCfgDN
Defines a configuration entry DN which is shared among all supplier servers, which stores the range information for each supplier.
dnaNextRange
Defines the specific number range that a server assigns to the manages attribute. The dnaNextRange value shows the next available range for transfer and is managed automatically by the plug-in as ranges are assigned or used by the server. This range has not yet been assigned to another server and is still available for its local Directory Server to use.

The following is the example of the DNA configuration entry on a supplier in replication topology: 

dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
objectClass: top
objectClass: dnaPluginConfig
cn: Account UIDs
dnatype: uidNumber
dnafilter: (objectclass=posixAccount)
dnascope: ou=people,dc=example,dc=com
dnanextvalue: 1
dnaMaxValue: 1300
dnasharedcfgdn: cn=Account UIDs,ou=ranges,dc=example,dc=com
dnathreshold: 100
dnaRangeRequestTimeout: 60
dnaNextRange: 1301-2301
Copy to Clipboard Toggle word wrap

For the full list of attributes you can use in the DNA configuration entry, see Distributed Numeric Assignment plug-in attributes.

With no dnaNextRange attribute value configured, Directory Server automatically assigns ranges using the dnaMaxValue value as the upper limit for the next range. You must explicitly set the dnaNextRange attribute, if you want Directory Server to assign a separate, specific range to other servers.

Each supplier keeps a track of its current range in a separate configuration entry which contains information about the range and the connection settings. This entry is a child of the location in dnaSharedCfgDN. Directory Server replicates the configuration entry to all other suppliers, so each supplier can check that configuration to find a server to contact for a new range. For example: 

dn: dnaHostname=ldap1.example.com+dnaPortNum=389,cn=Account UIDs,ou=Ranges,dc=example,dc=com
objectClass: dnaSharedConfig
objectClass: top
dnahostname: ldap1.example.com
dnaPortNum: 389
dnaSecurePortNum: 636
dnaRemainingValues: 1000
Copy to Clipboard Toggle word wrap

If you want a supplier to assign unique numbers to a managed attribute, create a DNA plug-in configuration entry for each configuration you want to apply. A DNA plug-in configuration entry is a subentry under the cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config plug-in container entry.

In a multi-supplier environment, each supplier manages its own range of values. The ranges are replicated between suppliers and each supplier is aware of which supplier manages which range. Later, a supplier uses this information to request a range transfer from another supplier if the first supplier is running out of range values.

The following example creates a new DNA plug-in configuration entry on a supplier by using the dsconf utility.

Prerequisites

  • You have root permissions.

Procedure

  1. Create the DNA configuration entry on a supplier: 

    #  dsconf -D "cn=Directory Manager" instance_name plugin dna config "Account UIDs" add --type uidNumber --filter "(objectclass=posixAccount)" --scope ou=People,dc=example,dc=com --next-value 1 --max-value 1300 --shared-config-entry "cn=Account UIDs,ou=Ranges,dc=example,dc=com" --threshold 100 --range-request-timeout 60 --magic-regen 99999

Successfully created the cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
    Copy to Clipboard Toggle word wrap

    The command creates the DNA plug-in configuration that sets a unique value to the uidNumber attribute instead of the 99999 magic value in all newly created posixAccount entries under ou=People,dc=example,dc=com. The supplier sets values up to 1300 and requests a range transfer from the second supplier when reaches the value 1200. If the second supplier is unresponsive for 60 seconds, the first supplier requests the range transfer from the third supplier.

    NOTE

    If you create the configuration entry for a server without replication or for a supplier in one-supplier environment, set only the --type, --filter, --scope, --next-value options.

    For details about the DNA plug-in configuration attributes, see Distributed Numeric Assignment Plug-in Attributes and Syntax of the DNA plug-in sections.

  2. Optional: Create the configuration entry that is shared among all supplier server: 

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x
dn: ou=Ranges,dc=example,dc=com
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: organizationalUnit
ou: Ranges
-
dn: cn=Account UIDs,ou=Ranges,dc=example,dc=com
changetype: add
objectclass: top
objectclass: extensibleObject
cn: Account UIDs
    Copy to Clipboard Toggle word wrap

  3. Enable the DNA plug-in: 

    #  dsconf -D "cn=Directory Manager" instance_name plugin dna enable

Enabled plugin 'Distributed Numeric Assignment Plugin'
    Copy to Clipboard Toggle word wrap

Verification

  • View the configuration entry details: 

    # dsconf -D "cn=Directory Manager" instance_name plugin dna config "Account UIDs" show

dn: cn=Account UIDs,cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config
cn: Account UIDs
dnaFilter: "(objectclass=posixAccount)"
dnaInterval: 1
dnaMagicRegen: 99999
dnaMaxValue: 1300
dnaNextValue: 1
dnaRangeRequestTimeout: 60
dnaScope: ou=People,dc=example,dc=com
dnaSharedCfgDN: cn=Account UIDs,ou=Ranges,dc=example,dc=com
dnaThreshold: 100
dnaType: uidNumber
objectClass: top
objectClass: dnaPluginConfig
    Copy to Clipboard Toggle word wrap

If you want Directory Server to assign unique numbers to a managed attribute, create a DNA plug-in configuration entry for each configuration you want to apply. Directory Server stores such plug-in configuration entries under the cn=Distributed Numeric Assignment Plugin,cn=plugins,cn=config plug-in container entry.

In a multi-supplier environment, each supplier manages its own range of values. The ranges are replicated between suppliers and each supplier is aware of which supplier manages which range. Later, a supplier uses this information to request a range transfer from another supplier if the first supplier is running out of range values.

Prerequisites

Procedure

  1. Select the Directory Server instance.
  2. Open the Plugins menu and select the DNA plug-in from the list.
  3. Click Add Config button to start the configuration of the new plug-in configuration entry.

  4. On the DNA Configuration tab, set the fields.

    For example, you want the plug-in to set a unique value to the uidNumber attribute instead of the 99999 magic value in all newly created posixAccount entries under ou=People,dc=example,dc=com. In addition, you want the supplier to set values up to 1300 and request a range transfer from the second supplier when the unique value reaches the value 1200. In this case, set the following fields:

    • Config Name to Account UIDs
    • DNA Managed Attributes to uidNumber
    • Filter to "(objectclass=posixAccount)"
    • Subtree Scope to ou=People,dc=example,dc=com
    • Next Value to 1
    • Max Value to 1300
    • Magic Regeneration Value to 99999
    • Threshold to 100

    • Range Request Timeout to 60

      NOTE
      If you create the configuration entry for a server without replication or for a supplier in one-supplier environment, set only the DNA Managed Attributes, Filter, Subtree Scope, and Next Value fields.
  5. Go to the Shared Config Settings tab and set the Shared Config Entry DN field to, for example, cn=Account UIDs,ou=Ranges,dc=example,dc=com. This shared configuration entry contains information which server to contact for the range transfer if the current server is out of unique values.
  6. Click the Save Config button to save the plug-in settings.
  7. Toggle the switch to the Plugin is enabled position to enable the plug-in.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat