3.4. Renaming and Moving Entries

Most rename operations are done on a leaf entry. However, some types of rename operations result in changes to the directory tree itself. These operations — subtree renames and new superior operations — are possible because of the way that entry IDs are stored in Directory Server indexes.

3.4.1. About Renaming Entries

Every DN is comprised of a long chain of elements that build on one another. Every entry has its own name, and then each of its children combine their name (the element on the far left) with the parent name. This pattern orients entries within the directory tree.

Example 3.1. Building Entry DNs

                                                                  dc=example,dc=com  =>  root suffix
                                                        ou=People,dc=example,dc=com  =>  org unit
                                          st=California,ou=People,dc=example,dc=com  =>  state/province
                          l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  city
           ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  org unit
uid=jsmith,ou=Engineering,l=Mountain View,st=California,ou=People,dc=example,dc=com  =>  leaf entry
Rename, or modrdn, operations result in changes to this tree.

3.4.1.1. Types of Rename Operations

When the naming attribute of an entry, the leftmost element of the DN, is changed, this is a modrdn operation. That's a special kind of modify operation because, in a sense, it moves the entry within the directory tree. For leaf entries (entries with no children), modrdn operations are lateral moves; the entry has the same parent, just a new name.
modrdn Operations for a Leaf Entry

Figure 3.1. modrdn Operations for a Leaf Entry

For subtree entries, the modrdn operation not only renames the subtree entry itself, but also changes the DN components of all of the children entries beneath the subtree.
modrdn Operations for a Subtree Entry

Figure 3.2. modrdn Operations for a Subtree Entry

Important

Subtree modrdn operations also move and rename all of the child entries beneath the subtree entry. For large subtrees, this can be a time- and resource-intensive process. Plan the naming structure of your directory tree hierarchy so that it will not require frequent subtree rename operations.
A similar action to renaming a subtree is moving an entry from one subtree to another. This is an expanded type of modrdn operation, which simultaneously renames the entry (even if it is the same name) and sets a newSuperior attribute which moves the entry from one parent to another.
modrdn Operations to a New Parent Entry

Figure 3.3. modrdn Operations to a New Parent Entry

3.4.1.2. The Relationships Between Entry Keys in entryrdn.db4

Both new superior and subtree rename operations are possible because of how entries are stored in the entryrdn.db4 index. Each entry is identified by its own key (a self-link) and then a subkey which identifies its parent (the parent link) and any children. This has a format that lays out the directory tree hierarchy by treating parents and children as attribute to an entry, and every entry is describes by a unique ID and its RDN, rather than the full DN.
These relationships are visible in the dbscan output for the entryrdn.db4 index. 
numeric_id:RDN => self link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
P#:RDN => parent link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
C#:RDN => child link
     ID: #; RDN: "rdn"; NRDN: normalized_rdn
For example, the ou=people subtree has a parent of dc=example,dc=com and a child of uid=jsmith. 
4:ou=people
   ID: 4; RDN: "ou=People"; NRDN: "ou=people"
P4:ou=people
   ID: 1; RDN: "dc=example,dc=com"; NRDN: "dc=example,dc=com"
C4:ou=people
   ID: 10; RDN: "uid=jsmith"; NRDN: "uid=jsmith"

Note

Version 8.2 and older of Directory Server used the entrydn.db4 index, which stored entry keys according to their full DN. To upgrade to entryrdn.db4, run the dn2rdn tool.
The defined keys for parent and child entries makes it possible for the Directory Server to perform operations that move entries in the directory tree.
  • Add operations look at the parent given in the modify statement and check for any existing leaf entries; if none exist, the new entry is added.
  • For delete operations, the server first checks the self link (the full entry key), and then deletes both the self link and then the child link in the parent entry. For example, if you deleted ou=people,dc=example,dc=com, the server deletes the ou=people key (the self-link) and then deletes the child subkey from the dc=example,dc=com entry key.
  • For new superior operations, the server changes the parent link in the entry key, removes the child link from the old parent, and adds a new child link to the new superior key.
  • For subtree rename operations, the server changes the self link in the subtree entry key to update its RDN, then tracks any child entry keys (based on the child links) and updates the parent link RDN.

3.4.1.3. Considerations for Renaming Entries

There are some things to keep in mind when performing rename operations:
  • You cannot rename the root suffix.
  • Subtree rename operations have minimal effect on replication. Replication agreements are applied to an entire database, not a subtree within the database, so a subtree rename operation does not require re-configuring a replication agreement. All of the name changes after a subtree rename operation are replicated as normal.
  • Renaming a subtree may require any synchronization agreements to be re-configured. Sync agreements are set at the suffix or subtree level, so renaming a subtree may break synchronization.
  • Renaming a subtree requires that any subtree-level ACIs set for the subtree be re-configured manually, as well as any entry-level ACIs set for child entries of the subtree.
  • You can rename a subtree with children, but you cannot delete a subtree with children.
  • Trying to change the component of a subtree, like moving from ou to dc, may fail with a schema violation. For example, the organizationalUnit object class requires the ou attribute. If that attribute is removed as part of renaming the subtree, then the operation will fail.
  • Any memberOf attributes managed by the MemberOf Plug-in will not be updated after a subtree-level rename operation. The MemberOf Plug-in does not check to see if parent entries change in order to initiate updates. If a subtree is renamed which contains either groups or group members, then launch a cn=memberof task task or use the fixup-memberof.pl command to force the MemberOf Plug-in to make the changes.
    See Section 6.1.4.6, “Synchronizing memberOf Values” to see how to clean up memberOf attribute references.

3.4.2. Renaming an Entry or Subtree

To rename an entry or subtree, use the modrdn changetype LDIF statement and use the newrdn attribute to indicate that the naming attribute is being changed and deleteoldrdn to set whether to retain the old RDN (0) or delete it (any non-zero integer). For example: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: ou=Engineering,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: ou=Development
deleteoldrdn: 1
If deleteoldrdn is set to any non-zero integer, positive or negative, then the old RDN is removed.
LDIF statements for modrdn operations are described in Section 3.3.2, “Renaming an Entry Using LDIF”.

3.4.3. Moving an Entry to a New Parent

Changing the parent entry requires setting two attributes:
  • newrdn to set the RDN of the moved entry. This is required even if the RDN remains the same.
  • newSuperior to give the DN of the new parent entry.
For example: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: uid=jsmith,l=Boston,ou=Engineering,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: uid=jsmith
deleteoldrdn: 1
newSuperior: l=Mountain View,ou=Engineering,ou=People,dc=example,dc=com

3.4.4. Disabling Subtree Rename Operations

By default, renaming subtrees is allowed. However, this can be disabled by resetting the nsslapd-subtree-rename-switch parameter to off:

Note

When a new Directory Server 9.0 instance or an upgraded instance has subtree renames enabled, then the RDNs of the entries are mapped in the entryrdn.db4 database. Instances with subtree rename disabled store their entry information in entrydn.db4. When disabling subtree renames, then the server needs to switch from using one database to the other, which is done by exporting and re-importing the directory entries. This is described in Section 3.4.1.2, “The Relationships Between Entry Keys in entryrdn.db4”.
  1. Export the directory to LDIF. 
    /etc/dirsrv/slapd-instance_name/db2ldif -n database1 -a /var/lib/dirsrv/slapd-instance_name/ldif/tree.ldif
    More export options are covered in Section 4.2, “Exporting Data”.
  2. Turn off the nsslapd-subtree-rename-switch parameter. 
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-subtree-rename-switch
nsslapd-subtree-rename-switch: off
  3. Import the LDIF file. This will populate the new entrydn.db4 file. 
    /etc/dirsrv/slapd-instance_name/ldif2db -D "cn=Directory Manager" -w secret -i /var/lib/dirsrv/slapd-instance_name/ldif/tree.ldif -n database1
    More import options are covered in Section 4.1, “Importing Data”.

3.4.5. Setting the DN Cache Size

A separate cache is used specifically to store DN information. As with the entry cache, the DN cache uses memory (RAM) used to store directory entries information in the internal representation. This is configured in the nsslapd-dncachememsize, and setting a large cache memory size improves the performance of rename operations.
The cache itself stores only the entry ID and the entry DN, so the table is relatively small when compared to the entry cache.
For the best move performance, make the entry cache large enough to contain all entries in the database.
This value can be modified from the command line by editing the nsslapd-dncachememsize attribute value for the LDBM plug-in instance for the database. For example: 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-dncachememsize
nsslapd-dncachememsize: 20971520