Migrating from Classic to Hierarchical Zones

Classic zones are primarily intended for backward compatibility with older versions of the Delinea Agent. If you upgrade the agent to version 5.x or later, you can migrate any or all of your classic zone information into one or more hierarchical zones.

Migrating a classic zone to a hierarchical zone is a multi-step process that requires some initial planning. For example, the first step in the migration changes the zone type but does not change any existing zone information, including the computer accounts that are joined to the zone. To take full advantage of the hierarchical zone after migration, however, it is likely that you will need to modify some of your existing zone information and move computer accounts into different zones.

Preparing for Migration

To prepare for the migration of any classic zones, you should first review the existing zone information for “dominant” user and group profiles—that is, profiles with attributes that are common to multiple classic zones. Dominant profiles will help you to identify one or more classic zones that you can use as potential parent zones. A parent zone provides a baseline for the user and group profiles that can be inherited in child zones. The parent zone also enables you to manage rights and role definitions that can be inherited in the child zones you create. If you are able to identify dominant profiles, most of your classic zones will become child zones that inherit information from the parent zone, with specific attribute overrides on a zone-by-zone or computer-by-computer basis, as necessary.

To illustrate how you should analyze your existing environment, assume you have several classic zones to address different profile requirements on different computers, but only two administrative groups that have different policies and procedures for adding users or granting privileges. In this scenario, you might create two parent zones—one for each administrative team—and use child zones or computer overrides to address specific profile attribute differences. If your organization has a single account fulfillment desk that handles all provisioning and access privileges, you might create a single parent zone for managing all or most user and group profiles, then use child zones to manage more granular account privileges.

If you have a “master” classic zone where the most commonly-used profile attributes for most of your users and groups are defined, that zone is a likely candidate to become a hierarchical parent zone. If none of your existing classic zones is suitable to become a parent zone, you should create a new parent zone as described in Creating a new parent zone. The parent zone must exist before you can use the migration utility.

Verifying You Have Upgraded Access Manager

You can use Access Manager to view and manage any combination of zones. However, the console must be version5.x or later to work with hierarchical zones. You can check the version of the console you have installed by opening Access Manager, clicking Help, then selecting About Access Manager.

Verifying You Have Upgraded UNIX Agents

The migration utility is a command-line program installed with the Delinea Agent for *NIX. You must upgrade the agent to version 5.1, or later, on at least one UNIX computer to do any migration. You can verify the agent version by running the adinfo command with the --version (-v) option.

What the Migration Utility Does

After you have identified at least one classic zone as potential parent zones, you can use the migration utility to convert the classic zone into a hierarchical parent zone. After you make the classic zone a hierarchical zone, you can run the migration utility to make other classic zones into child zones of the parent zone.

During the migration, all of the user and group profiles in the source zone are copied to the specified parent zone. If identical profiles exist in multiple classic zones, the identical profiles become a single profile in the parent zone. If there are user or group profiles in multiple zones with different attribute values—for example, a UID of 10001 in one classic zone, but 10003 in another classic zone, the migration utility creates a single profile for the user in the parent zone, and creates a profile override with the distinct attribute values in each target child zone. Each child zone inherits the base profile from the parent zone but applies the overrides for any attributes that are different in different zones.

The migration utility copies everything else—including rights, roles, role assignments, groups, and NIS maps—into the new child zone for each classic zone being migrated.

Using the Migration Utility

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

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:

Log on to a Linux or UNIX computer running adclient and open a terminal window.
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 {1234abcepassword}
bind eng.acme.com engadmin {1234abcepassword}
Save and close the file.
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.

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.

Roles and Rights for Migrated Users

The admigrate utility adds the following role definitions for migrated users:

login_at_roles assigns the UNIX system rights Password login... and Nonpassword login. It does not assign Login with non-Restricted Shell because the user may be assigned to a restricted shell.
login_all_apps assigns the login-all PAM right, which grants access to all PAM applications. It does not assign any UNIX system rights.

By default, all users are added to the login_all_apps role so that if they are granted login rights, they have access to all PAM applications, which is the default for users in classic zones. If PAM access rights are restricted by another role assignment, the restricted role assignment will override the rights granted by login_all_apps.

Access uses the following role-assignment rules when migrating roles and rights from a classic zone to a hierarchical zone:

Classic zone	Enabled or disabled	Role assignment in hierarchical child zone
User assigned to role	Enabled	Assign to the following roles: login_at_roles, which grants Password login and Nonpassword login UNIX system rights. login_all_apps, which grants access to all PAM applications. Corresponding user-created roles, which are migrated.
User assigned to role	Disabled	Assign to corresponding user-created roles, which are migrated. No login roles are assigned because the user is disabled in the classic zone.
User not assigned to role	Enabled	Assign to the default UNIX Login role, which grants all UNIX system login rights and access to all PAM applications.
User not assigned to role	Disabled	Assign to the default listed role, which makes the user visible in the zone but does not assign any UNIX system rights or PAM access rights.

In classic zones, users who are added to a zone are enabled for login access by default. As an administrator, you can leave a user profile defined in a zone but disable login access.

All the roles and rights you defined in the source zone, as well as any role assignments to user-created roles, are added, as-is, to the child zone each time you run admigrate. For example, if you defined a privileged mount command in 20 classic zones, admigrate will copy that mount command to 20 new hierarchical zones. Therefore, after migration you should analyze your role definitions and access right definitions to see if some of them can be moved up to the parent zone to take advantage of inheritance.

Assigning the Audit Level When Migrating

In hierarchical zones, role definition can be assigned an auditing level. This setting is not applicable in classic zones.During migration from classic zones to hierarchical zone, the default “Audit if possible” auditing level, is assigned to all migrated role definitions. After you have migrated, you can change the auditing level in any role definition. For more information about changing the auditing level for a role definition, see Changing the audit level for role definitions.

Moving Joined Computers to Hierarchical Zones

After you have migrated data from classic zones to new hierarchical zones, you can move the computers to the new zones using the adchzone command-line program.

When you use adchzone to change the zone for a computer, the command copies the UNIX profile from the old zone to the new zone, deletes computer profile from the old zone, then stops and restarts adclient to flush the cache and update the zone information. The advantage of this approach over leaving the old zone (adleave) and then joining (adjoin) the new zone is that it is very quick and preserves all the join information without you having to specify join options.

For example, run a command similar to the following to move a computer joined to the classic finance zone to the new child finance zone:

/usr/share/centrifydc/adedit/adchzone \
-z “cn=finance,cn=global,cn=zones,ou=unix,dc=acme,dc=com”
-u finance-adm

You will be prompted to supply a password for the specified user.

After changing the zone, you can open Access Manager to see the computer in the Computers node of the new zone, or you can run adinfo on the computer to verify the new zone information.

What to do After the Migration

The admigrate utility migrates most zone information automatically. After using the utility, however, you might want to perform the following tasks to complete the migration:

Delete unnecessary copies of right and role definitions.

You should analyze the right and role definitions to see how many of them have been copied into multiple zones. Rights and roles that are defined in the parent zone are available for use in all child zones. By moving role and right definitions to the parent zone you simplify your zone structure making it easier to understand the rights and roles that are available for your organization.
Review provisioning rules.

In many cases, hierarchical zones simplify automated provisioning by enabling you to define a baseline profile in a parent zone and only override specific attributes when necessary. If you are using automated provisioning, you should check whether you are defining the provisioning rules in parent zones or in child zones.
Delegate permissions on a zone-by-zone basis.

Use the Zone Delegation Wizard to delegate administrative tasks and the assign the corresponding permissions to the appropriate users and groups in your new child zones.