Creating Migration Tables

Applies To: Windows Server 2003, Windows Server 2003 R2, Windows Server 2003 with SP1, Windows Server 2003 with SP2

Migration tables are XML format files that specify how to map security principals and UNC paths to their production domain equivalents. Migration table files have a default file name extension of .migtable. The Migration Table Editor (MTE) is a GPMC tool that can be used to create and edit migration tables. It can be accessed in either of two ways:

• You can start MTE and create or edit a migration table during a GPMC copy or import operation. In this case, MTE starts in a separate window that allows you to create a new migration table or edit an existing one.

• You can start MTE in stand-alone mode (independently of an import or copy operation) and create or edit the migration table in advance of migrating GPOs to your production environment.

You can also create migration tables by using a supplied script, as described later in this section.

An advantage of creating the migration table in advance is that you can be sure that the migration settings you define are exactly what you want before beginning the deployment. Therefore, when you are ready to move your test GPOs into production, you should first create one or more migration tables for the GPO(s) that you need to migrate. Note that a single migration table can be used for more than one GPO. You might use a single migration table that covers every possible security principal and UNC path combination for a given migration from a staging-to-a production domain. In that case you can simply apply the same migration table to every GPO that is deployed from the staging domain to the production domain, and those principals and paths that match will be correctly mapped.

Using the Stand-alone Migration Table Editor

To start MTE in stand-alone mode, run Mtedit.exe from the GPMC installation folder. MTE starts with a blank migration table that you can populate manually by typing entries into the grid, or you can auto-populate the table by using one of the auto-populate methods.

Auto-populating the migration table

The easiest way to start creating a migration table is to use one of the auto-populate features, accessed from the Tools menu in MTE. You can auto-populate from both backup GPOs and from live GPOs. To auto-populate a migration table, you need to perform the following tasks:

1. Choose to auto-populate the table from live GPOs or from backup GPOs.

   When you are ready to migrate a GPO in your staging environment into your production environment, you can use Populate From GPO against the live GPO in the staging environment to start the migration table. The process for auto-populating the table from a backup GPO is the same, except that you must provide a path to the backup GPO. In that case, if you have more than one backed up GPO, a list is displayed from which you can choose.

   Note that you can select multiple GPOs or backup GPOs when auto-populating a single migration table. This allows you to use a single migration table for all GPOs in a domain.

2. Choose whether to include security principals from the DACL on the GPO.

   When you auto-populate a migration table, you can select the option to include security principals from the DACL on the GPO. If you select this option, security principals on the GPO’s DACL are included in the table along with security principals referenced in the GPO settings. Duplicate source security principals are not repeated in the migration table. MTE supports a number of different object types that can be mapped, as described in Table 3.3.

   Table 3.3   Object Types Supported in the Migration Table

   Object Type	Used to Map...
   User	Individual user accounts.
   Domain Global Group	Domain global groups.
   Domain Local Group	Domain local groups.
   Universal Group	Universal groups.
   Computer	Computer names. For example, an individual computer can be given read and apply Group Policy permissions on a GPO.
   UNC Path	UNC paths used in software installation policy.
   Free Text or SID	Undetermined security principals. For example, you might reference security principals in a GPO by name rather than by SID (typed as "administrators" instead of "DomainX\Administrators"); or it might not be possible to resolve security principals to determine the type. This can occur because, for example, when setting restricted group security policy, you can type in the name of the group rather than resolve it against a live domain. In this case, the group name is stored in the Group Policy object as its name rather than its corresponding SID. MTE considers such a security principal as Free Text or SID. In addition, you can type raw SIDs into the MTE. In that case, because the object type is not known by MTE, it must be specified as Free Text or SID.

3. Modify the Destination Name for each security principal and UNC path.

   After you have populated the migration table, you can choose to modify the Destination Name field for each record. The default Destination Name value is Same As Source, which means that the same security principal or UNC path will be used in the destination GPO as the source. In this case, the value is copied without modification and the mapping accomplishes no changes. Typically you will need to change this field for one or more source entries when deploying a GPO from a test to a production environment. To change the destination field, you can either type in an entry or right-click the field and make a choice from the menu.

   The two menu options available are Browse and Set Destination. Choosing Browse allows you to use the object picker to select a security principal in any trusted domain. If you choose Set Destination, you can choose one of three options:

   • No Destination. If you specify No Destination, the security principal is not included in the destination GPO when migrated. This option is not available for UNC path entries.

   • Map by Relative Name. If you specify Map by Relative Name, the security principal name is assumed to already exist in the destination domain, and that destination name will be used for the mapping. For example, if the source name is Domain Admins for the test.contoso.com domain and you are migrating the GPO into the contoso.com domain, then the name Domain Admins@test.contoso.com will be mapped to Domain Admins@contoso.com. The group must already exist in the target domain for the actual import or copy operation to succeed. This option is not available for UNC path entries.

   • Same As Source. If you specify Same As Source, the same security principal is used in both the source and destination GPOs. Essentially, the security entry is left as-is. Note that this option is only practical if you are migrating from a test domain in the same forest as the production domain, or if you are migrating from a test domain in a different forest that trusts the production forest. The requirement for a source name to map successfully is that it can be resolved by users and computers in the production forest.

   There are some restrictions on the options available for the destination name. UNC paths only support the Same As Source option, or you can manually enter a different UNC path. Security Principals designated as Free Text or SID do not support Map by Relative Name.

   It is also important to note that you will receive a warning if you map from one group type to another. For example, if you have a source principal that is a Domain Global Group and you select a Domain Local Group as the destination, you will be warned that the destination name is of a different type from the source. If you then try to validate the file, the validation process fails, but you can still use the migration table to perform a migration. Note that the migration table does not support mapping to a built-in security group such as the Administrators group.

   If you need to delete a row from MTE, select the desired row, then right-click the row and choose Delete from the menu.

4. Validate the migration table.

   Before saving the migration table, it is best to validate the file. To do this, from the Tools menu, choose Validate. The validation process determines if the XML format of the resulting file is valid and verifies that the destination names are valid from a migration perspective. For example, if you enter a UNC path for the destination, and the path does not exist, the validation process will return a warning. Specifically, the validation process:

   • Validates the existence of destination security principals and UNC paths.

   • Checks that source entries with UNC paths do not have destinations of Map By Relative Name or No Destination, which are not supported.

   • Checks that the type of each destination entry in the table matches the real type in Active Directory.

     If you are entering data manually, the validation process is especially important to ensure that an entry error does not prevent a successful migration. Note that a validation of the mapping file might fail because the user editing the file does not have the ability to resolve the security principals or UNC paths specified in the file. However, that does not mean that the file will not work as expected during a migration, provided that the user who performs the migration can resolve the security principal and UNC names. Validation messages will indicate whether there is a syntax error in the table or whether the validator simply cannot resolve a security principal name or UNC path. In the case of a name resolution failure, ensure that you will have sufficient access to both source and destination resources during the actual migration.

5. When you are finished editing the table, save the resulting .migtable file by choosing Save from the File menu.

Entering Migration Table Entries Manually

If you choose not to use the Auto-Populate feature, or if you need to enter some data manually, take care to adhere to the proper formats in order for the migration table to be valid. Table 3.4 shows the proper form for each object type supported in the migration table. Note that these formats are required in both source and destination fields.

Table 3.4   Required Formats for Migration Objects

Creating a Migration Table by Using a Script

If you need to automate the process of creating migration tables, you can use a supplied script, CreateMigrationTable.wsf. You can also use this script in place of MTE to generate the initial migration table, and then use MTE to modify the table. The script CreateMigrationTable.wsf is located in the Scripts folder in the GPMC installation folder. The script supports auto-populating a migration table using either a live GPO or a backup GPO location. You can also have the script read from all GPOs within a domain. In that case, all possible security principals found in GPOs in the staging domain are put into the migration table, and that single migration table can be used for any GPO deployment from that staging domain to a production domain.

To use the script CreateMigrationTable.wsf, from the command line, change directories to the Scripts folder and run the script, preceded by the Cscript.exe command. Note that the script always includes the security principals that are part of the DACL on the GPO, unlike MTE, which gives you the option to include them. The script also has an option to set the destination name to Map by Relative Name rather than the default Same As Source. You use the /MapByName argument to implement relative naming. The following command illustrates how the script can be used. In this command, a GPO named Finance OU Desktop Policy is located in a staging domain named staging.contoso.com. This command auto-populates the migration table called FinanceStaging.migtable from the live GPO:

Cscript.exe CreateMigrationTable.wsf c:\migtables\FinanceStaging.migtable /GPO: "Finance OU Desktop Policy" /domain:staging.contoso.com

To create a migration table from the backup of this GPO instead of from the live copy, simply add the /BackupLocation option to the command above, and provide a folder path that contains the backup copy of the GPO. Note that if you use the /BackupLocation option and there is more than one backup GPO located in that folder path, all available backed up GPOs will be used to populate the migration table.

Final Preparations for Deployment

As a final step before your production deployment, you should back up your staging GPOs. A backup is required if you are using a GPO import to perform your migration from staging to production. This method is required in cases where your staging environment is in a forest that is separate from and not trusted by your production domain, or where you need to update an existing GPO that already exists in your production environment. You can use GPMC to back up one or more GPOs or, you can use the script BackupGPO.wsf to back up a single GPO, or use the script BackupAllGPOs.wsf to back up all GPOs in the staging domain. To back up a GPO by using GPMC, in the console tree, right-click the GPO and select Backup from the menu.

To back up a GPO by using BackupGPO.wsf, run the script from the Scripts folder in the GPMC installation folder. The following command-line syntax backs up the GPO Finance OU Workstation Security Policy in the domain staging.contoso.com to the folder c:\gpobacks:

Cscript.exe backupgpo.wsf "Finance OU Workstation Security Policy" c:\gpobacks /comment:"Backup prior to prod" /domain:staging.contoso.com

The preceding syntax includes a comment that indicates the purpose of the backup.