Using the migration utility

Centrify provides the command-line program admigrate to simplify the process of migrating profiles, rights, roles, role assignments, and NIS maps from a classic zone to a hierarchical zone.

The admigrate program is installed by default in the following directory:

/usr/share/centrifydc/adedit/admigrate

Note that the first zone you migrate becomes the primary source of profile information for the other zones you migrate. You should start with the zone that it contains the most consistent profile attributes.

Note:    Admigrate does not migrate classic SFU zones (Ref: CS-28289a) nor zone delegation rights (Ref: IN-90002).

To migrate zone information from a classic to hierarchical zone:

  1. Log on to a Linux or UNIX computer running adclient and open a terminal window.
  2. Open a text editor to create a file with bind information for each domain to which admigrate must connect.

    Specify the Active Directory credentials for an account with permission to create child zones, rights, roles, user profiles, and group profiles in the parent zone with one line per domain in the format:

    bind domain_account_password

    For example, create a file named migrate.conf with information similar to the following:

    bind finance.acme.com administrator {myP@$swd}
    bind eng.acme.com engadmin {@lt!pas$}
  3. Save and close the file.
  4. Run the admigrate command.

    admigrate -in classicZone -z targetZone -hz parentZone -config configFile
    For this variable Specify this information

    classicZone

    The distinguished name of the classic zone to migrate.

    For example:

    “cn=finance,cn=zones,ou=unix,dc=acme,dc=com”

    targetZone

    The distinguished name of the new zone.

    It can be the same as the existing classic zone name, however the new zone will be a child zone of the specified parent zone, so the distinguished name is different.

    For example:

    “cn=finance,cn=global,cn=zones,ou=unix,dc=acme,dc=com”

    parentZone

    The parent zone for the migration.

    The specified zone must be an existing zone. The target zone becomes a child zone of this zone. You can run admigrate multiple times and specify the same parent zone and different source and target zones each time to migrate multiple zones to different child zones of this parent.

    For example:

    “cn=global,cn=zones,ou=unix,dc=acme,dc=com”

    configFile

    The configuration file to use with the migration. The configuration file is primarily useful to specify bind information if you are migrating zones from domains that are different from the target zone’s domain.

    The file is a simple text file, for example:

    -config admigrate.txt

    For more information about other options you can use when running admigrate, see the man page for admigrate.

    The first time you run admigrate, the command copies all of the user profiles from the source zone to the parent zone. Everything else defined in the source zone—including groups, rights, role definitions, role assignments, and NIS maps—is copied from the source zone to a new target child zone.

  5. Repeat Step 4 for each classic zone you want to migrate as a child of the parent zone.

Sample migration

To illustrate how to use the admigrate command, assume you are migrating two classic zones—finance and engineering—into a new empty parent zone named global. For this example, the distinguished name of the classic finance zone (the source zone) is this:

“cn=finance,cn=zones,ou=unix,dc=test,dc=org”

After migration, the distinguished name of the finance child zone (the target zone) is this:

“cn=finance,cn=global,cn=zones,ou=unix,dc=test,dc=org”

To migrate the classic finance zone, you would run a command similar to the following:

/usr/share/centrifydc/adedit/admigrate \
-in “cn=finance,cn=zones,ou=unix,dc=test,dc=org” \
-z “cn=finance,cn=global,cn=zones,ou=unix,dc=test,dc=org” \ -hz “cn=global,cn=zones,ou=unix,dc=test,dc=org” \
-config ~/migrate.conf \ -v > migrate_finance.txt

In this example, the target zone name is the same as that of the input classic zone, except its distinguished name is different because it is a child zone of the global zone. The -config parameter specifies the file that contains bind information, in this cases ~/migrate.conf. The -v option directs verbose output to a text file.

You would then run admigrate for the next zone to migrate. For example:

/usr/share/centrifydc/adedit/admigrate \
-in “cn=engineering,cn=zones,ou=unix,dc=test,dc=org” \
-z “cn=engineering,cn=global,cn=zones,ou=unix,dc=test,dc=org” \
-hz “cn=global,cn=zones,ou=unix,dc=test,dc=org” \
-config ~/admigrate.txt \
-f -v > migrate_eng.txt

To simplify the migration process for multiple zones, you could put admigrate in a shell script and specify the source zone as an input variable or read it from a file with a listing of all your zones.

Inheritance and overrides

Each time you run admigrate with the same parent zone and a different source and target zone, the admigrate utility does the following:

  • If a user profile from the source zone does not exist in the parent zone, the utility creates a profile for the user in the parent zone.
  • If a user profile exists in the parent zone and matches the user profile from the source zone, the new child zone will inherit the user profile attributes as they are defined in the parent zone.
  • If a user profile already exists in the parent zone and has attribute values that differ from those for the user from the source zone, the utility creates a user profile in the child zone with overrides for the differing attribute values. For example, if a user profile exists for oscar.romero in the parent zone, but has a different numeric identifier (UID) in the engineering zone, the UID attribute value would be different in the engineering child zones. The other attributes would be inherited from the parent zone.
  • Copies the groups, rights, role definitions, role assignments, and NIS maps from the source zone to the target child zone.

The admigrate utility does not copy delegated permissions from the existing classic zones to the new child zones. In addition, delegated permissions are not automatically inherited from parent zones to the child zones. After migrating classic zones, you must explicitly delegate administrative permissions on a zone-by-zone basis.