40.2. Examples for Using ipa migrate-ds

The data migration is performed using 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
Migrated entries
The migrate-ds command only migrates accounts containing a gidNumber attribute, that is required by the posixAccount object class, and a sn attribute, that is required by the person object class.
Customizing the process
The ipa migrate-ds command enables you to customize how data is identified and exported. This is useful if the original directory tree has a unique structure or if some entries or attributes within entries should be excluded. For further details, pass the --help to the command.
Bind DN
By default, the DN "cn=Directory Manager" is used to bind to the remote LDAP directory. Pass the --bind-dn option to the command to specify a custom bind DN. For further information, see Section 40.1.3.4, “Migration Tools”.
Naming context changes
If the Directory Server naming context differs from the one used in Identity Management, the base DNs for objects is transformed. For example: uid=user,ou=people,dc=ldap,dc=example,dc=com is migrated to uid=user,ou=people,dc=idm,dc=example,dc=com. Pass the --base-dn to the ipa migrate-ds command to set the base DN used on the remote LDAP server for the migration.

40.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 specify the RDN of a different user or group subtree on the source LDAP server:
  • --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 directory tree can be migrated using --user-container=ou=Employees.
For example: 
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees \
                        --group-container="ou=employee groups" \
			ldap://ldap.example.com:389
Pass the --scope option to the ipa migrate-ds command, to set a scope:
  • onelevel: Default. Only entries in the specified container are migrated.
  • subtree: Entries in the specified container and all subcontainers are migrated.
  • base: Only the specified object itself is migrated.

40.2.2. Specifically Including or Excluding Entries

By default, the ipa migrate-ds script imports every user entry with the person object class and every group entry with the groupOfUniqueNames or groupOfNames object class..
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.
One 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 --group-objectclass=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 --exclude-users=bjensen ldap://ldap.example.com:389
Exclude statements are applied to users matching the pattern in the uid and to groups matching it in the cn attribute.
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 --exclude-users=bjensen --exclude-users=mreynolds ldap://ldap.example.com:389

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

40.2.4. Setting the Schema to Use

Identity Management uses the RFC2307bis schema to define user, host, host group, and other network identities. However, if the LDAP server used as source for a migration uses the RFC2307 schema instead, pass the --schema option to the ipa migrate-ds command: 
[root@ipaserver ~]# ipa migrate-ds --schema=RFC2307 ldap://ldap.example.com:389