29.2. Examples for Using migrate-ds
The data migration is performed with the
ipa migrate-ds command. At its simplest, the command takes the LDAP URL of the directory to migrate and exports the data based on common default settings.
ipa migrate-ds ldap://ldap.example.com:389
It is possible to customize how the
migrate-ds commands identifies and exports data. This is useful if the original directory tree has a unique structure or if some entries or attributes within entries should be excluded from migration.
29.2.1. Migrating Specific Subtrees
The default directory structure places person entries in the
ou=People subtree and group entries in the ou=Groups subtree. These subtrees are container entries for those different types of directory data. If no options are passed with the migrate-ds command, then the utility assumes that the given LDAP directory uses the ou=People and ou=Groups structure.
Many deployments may have an entirely different directory structure (or may only want to export certain parts of the directory tree). There are two options which allow administrators to give the RDN of a different user or group subtree:
--user-container--group-container
Note
In both cases, the subtree must be the RDN only and must be relative to the base DN. For example, the
ou=Employees,dc=example,dc=com subtree can be migrated using --user-container=ou=Employees, but ou=Employees,ou=People,dc=example,dc=com cannot be migrated with that option because ou=Employees is not a direct child of the base DN.
For example:
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees --group-container="ou=employee groups" ldap://ldap.example.com:389
There is a third option that allows administrators to set a base DN for migration:
--base-dn. With this option, it is possible to change the target for container subtrees. For example:
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees --base-dn="ou=people,dc=example,dc=com" ldap://ldap.example.com:389
Now, the
ou=Employees user subtree can be migrated from within the larger ou=People subtree without migrating every people-related subtree.
29.2.2. Specifically Including or Excluding Entries
By default, the
migrate-ds script exports every user entry with the person object class and every group entry within the given user and group subtrees.
In some migration paths, only specific types of users and groups may need to be exported, or, conversely, specific users and groups may need to be excluded.
On option is to set positively which types of users and groups to include. This is done by setting which object classes to search for when looking for user or group entries.
This is a really useful option when there are custom object classes used in an environment for different user types. For example, this migrates only users with the custom
fullTimeEmployee object class:
[root@ipaserver ~]# ipa migrate-ds --user-objectclass=fullTimeEmployee ldap://ldap.example.com:389
Because of the different types of groups, this is also very useful for migrating only certain types of groups (such as user groups) while excluding other types of groups, like certificate groups. For example:
[root@ipaserver ~]# ipa migrate-ds --group-objectclass=groupOfNames,groupOfUniqueNames ldap://ldap.example.com:389
Positively specifying user and groups to migrate based on object class implicitly excludes all other users and groups from migration.
Alternatively, it can be useful to migrate all user and group entries except for just a small handful of entries. Specific user or group accounts can be excluded while all others of that type are migrated. For example, this excludes a hobbies group and two users:
[root@ipaserver ~]# ipa migrate-ds --exclude-groups="Golfers Group" --exclude-users=jsmith,bjensen ldap://ldap.example.com:389
Specifying an object class to migrate can be used together with excluding specific entries. For example, this specifically includes users with the
fullTimeEmployee object class, yet excludes three managers:
[root@ipaserver ~]# ipa migrate-ds --user-objectclass=fullTimeEmployee --exclude-users=jsmith,bjensen,mreynolds ldap://ldap.example.com:389
29.2.3. Excluding Entry Attributes
By default, every attribute and object class for a user or group entry is migrated. There are some cases where that may not be realistic, either because of bandwidth and network constraints or because the attribute data are no longer relevant. For example, if users are going to be assigned new user certificates as they join the IdM domain, then there is no reason to migrate the
userCertificate attribute.
Specific object classes and attributes can be ignored by the
migrate-ds by using any of several different options:
--user-ignore-objectclass--user-ignore-attribute--group-ignore-objectclass--group-ignore-attribute
For example, to exclude the
userCertificate attribute and strongAuthenticationUser object class for users and the groupOfCertificates object class for groups:
[root@ipaserver ~]# ipa migrate-ds --user-ignore-attribute=userCertificate --user-ignore-objectclass=strongAuthenticationUser --group-ignore-objectclass=groupOfCertificates ldap://ldap.example.com:389
Note
Make sure not to ignore any required attributes. Also, when excluding object classes, make sure to exclude any attributes which are only supported by that object class.
29.2.4. Setting the Schema to Use
By default, Identity Management uses RFC2307bis schema to define user, host, hostgroup, and other network identities. This schema option can be reset to use RFC2307 schema instead:
[root@ipaserver ~]# ipa migrate-ds --schema=RFC2307 ldap://ldap.example.com:389
