39.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
gidNumberattribute, that is required by the
posixAccountobject class, and a
snattribute, that is required by the
- 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
--helpto the command.
- Bind DN
- By default, the DN "
cn=Directory Manager" is used to bind to the remote LDAP directory. Pass the
--bind-dnoption to the command to specify a custom bind DN. For further information, see Section 188.8.131.52, “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=comis migrated to
uid=user,ou=people,dc=idm,dc=example,dc=com. Pass the
--base-dnto the ipa migrate-ds command to set the base DN used on the remote LDAP server for the migration.
39.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:
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=comdirectory tree can be migrated using
[root@ipaserver ~]# ipa migrate-ds --user-container=ou=employees \ --group-container="ou=employee groups" \ ldap://ldap.example.com:389
--scopeoption 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.
39.2.2. Specifically Including or Excluding Entries
By default, the ipa migrate-ds script imports every user entry with the
personobject class and every group entry with the
groupOfUniqueNamesor 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
uidand to groups matching it in the
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
39.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
Specific object classes and attributes can be ignored by the migrate-ds by using any of several different options:
For example, to exclude the
userCertificateattribute 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
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.
39.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
--schemaoption to the ipa migrate-ds command:
[root@ipaserver ~]# ipa migrate-ds --schema=RFC2307 ldap://ldap.example.com:389