Migration tables

Article
10/08/2009

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

Migration tables

When you copy or import a Group Policy object (GPO) from one domain to another, you can use a migration table to tell Group Policy Management Console (GPMC) how domain-specific data should be treated.

The key challenge when migrating GPOs from one domain to another is that some information in the GPO is actually specific to the domain where the GPO is defined. When transferring the GPO to a new domain, it may not always be desirable, or even possible, to use the exact same settings. Items that can be specific to a domain include references to security principals such as users, groups, and computers as well as UNC paths. The solution is to modify these references in the GPO that are domain-specific, during the import or copy operation, so that the settings in the destination GPO are written with the appropriate information for the destination domain. GPMC supports this capability using migration tables.

A migration table is a file that maps references to users, groups, computers, and UNC paths in the source GPO to new values in the destination GPO. A migration table consists of one or more mapping entries. Each mapping entry consists of a type, source reference, and destination reference. If you specify a migration table when performing an import or copy, each reference to the source entry will be replaced with the destination entry when writing the settings into the destination GPO.

The migration table will apply to any references in the settings within a GPO, whether you are performing an import or copy operation. In addition, during a copy operation, if you choose the option to preserve the discretionary access control list (DACL) on the GPO, the migration table will also apply to both the DACL on the GPO and the DACLs on any software installation settings in the GPO.

Migration tables store the mapping information as XML, and have their own file name extension, .migtable. You can create migration tables using the Migration Table Editor (MTE). The MTE is a convenient tool for viewing and editing migration tables without having to work in, or be familiar with, XML. The MTE is associated with the .migtable extension so that when you double click a migration table, it opens in the MTE. The MTE is installed with GPMC. For information about MTE, see The migration table editor. You can also create and edit migration tables using any XML editor or using the GPMC scripting interfaces.

For more information about using migration tables for importing GPOs from one forest to another, see the white paper, Migrating GPOs Across Domains with GPMC.

Settings impacted by migration tables

There are two types of settings that may not transfer well across domains:

Users, groups, and computers (security principals) that are referenced in the following places: the settings of the GPO, in the ACL for the GPO itself, and the ACL for any software installation settings in the GPO. Security principals do not transfer well for several reasons. For instance, domain local groups are invalid in external domains but other groups are valid if there is trust in place. Even with a trust between domains, it may not always be appropriate to use the exact same group in the new domain. If there is no trust, then none of the security principals in the source domain will be available in the destination domain.
UNC paths. When you are migrating GPOs across domains that do not have trust, such as from test to production environments, users in the destination domain may not have access to paths in the source domain.

The following items can contain security principals and can be modified using a migration table:

Security policy settings of the following types:
- User rights assignment
- Restricted groups
- Services
- File system
- Registry
Advanced folder redirection policies.
The GPO Discretionary Access Control List (DACL), if you choose to preserve it during a copy operation.
The DACL on software installation objects. This is only preserved if the option to copy the GPO DACL is specified. Otherwise the default DACL is used.

Note
- Security Principals referenced in Administrative Templates settings cannot be migrated using a migration table.

The following items can contain UNC paths and can be modified using a migration table:

Folder redirection policies.
Software installation policies (for software distribution points).
Pointers to scripts deployed through Group Policy (such as startup and shutdown scripts) that are stored outside the GPO. Note that the script itself is not copied as part of the GPO copy operation, unless the script is stored inside the source GPO.

Options for specifying migration tables

Migration tables are specified when performing import and copy operations. There are three options for using migration tables with import and copy:

Do not use a migration table. This option copies the GPO exactly as it is. All references to security principals and UNC paths are copied identically.
Use a migration table. This option maps any references in the GPO that are in the migration table. References that are not contained in the migration table are copied as is.
Use a migration table exclusively. This option requires that all references to security principals and UNC paths that are referenced in the source GPO be specified in the migration table. If a security principal or UNC path is referenced in the source GPO and is not included in the migration table, the import or copy operation fails.

In addition, cross-domain copy operations will apply the migration table to the DACL on the GPO (and any software installation settings) if you choose the option to Preserve or migrate the existing permissions.

When performing a copy or import, the wizard scans the source GPO to determine if there are any references to security principals or UNC paths in the GPO. If there are, you have the opportunity to specify a migration table. During cross-domain copy operations, if you specify the option to Preserve or migrate the permissions on the GPO, the wizard will always present the opportunity to specify a migration table, because a DACL by definition contains security principals.

Contents of Migration tables

A migration table consists of one or more mapping entries. Each mapping entry has three pieces of information: Type, source and destination. The following table describes these categories in more detail.

Description

	Description
Source Type	The type of domain-specific information in the domain for the source GPO. Migration tables support the following types: User Computer Domain Local Group Domain Global Group Universal Group UNC Path Free Text or security identifier (SID). Note: This category is only for use with security principals that are specified as free text and raw SIDs. Note Built-in groups such as "Administrators" and "Account Operators" have the same SID in all domains. If references to built-in groups are stored in the GPO using their resolved format (based on the underlying SID), they cannot be mapped using migration tables. However, if references to built-in groups are stored as free text, you can map them using a migration table, and in this case, you must specify source type="Free Text or SID." When viewed in an XML editor, the types are represented as follows: `<Type>User</Type>` `<Type>Computer</Type>` `<Type>LocalGroup</Type>` `<Type>GlobalGroup</Type>` `<Type>UniversalGroup</Type>` `<Type>UNCPath</Type>` `<Type>Unknown</Type>`
Source Name	The exact name of the User, Computer, Group or UNC Path referenced in the source GPO. For example, TestDomain\PolicyAdmins or \\server1\publicshare. The type of the source name must match the source type specified in the migration table. Security principals can be specified using any of the following formats: UPN. For example, "someone@example.com". SAM. For example, "example\someone". DNS. For example, "example.com\someone". Free text. For example, "someone". You must specify the type as Unknown Group in this case. SID. For example, S-1-11-111111111-111111111-1111111111-1112. You must specify the type as Free Text or SID in this case.
Destination Name	The destination name specifies how the name of the User, Computer, Group or UNC Path in the source GPO should be treated upon transfer to the destination GPO. There are four choices: Same as source. Copy without changes. Equivalent to not putting the source value in the migration table at all. MTE value: <Same As Source> XML tag: `<DestinationSameAsSource />` None. Removes the User, Computer or Group from the GPO. This option cannot be used with UNC paths. MTE value: <None> XML tag: <DestinationNone /> Map by relative name. For example, map SourceDomain\Group1 to TargetDomain\Group1. This option cannot be used with UNC paths. MTE value: <Map by Relative name> XML tag: `<DestinationByRelativeName />` Explicitly specify value. In the destination GPO, replace the source value with the exact literal value you specify. MTE value: `<exact name to use in target>` XML tag: `<Destination>`Exact name to use in target domain`</Destination>` Security principals can be specified using any of the following formats: UPN. For example, "someone@example.com". SAM. For example, "example\someone". DNS. For example, "example.com\someone". Free text. For example, "someone". Raw SIDs cannot be used for the destination name.

Source Type

The type of domain-specific information in the domain for the source GPO. Migration tables support the following types:

User
Computer
Domain Local Group
Domain Global Group
Universal Group
UNC Path
Free Text or security identifier (SID). Note: This category is only for use with security principals that are specified as free text and raw SIDs.

Note

Built-in groups such as "Administrators" and "Account Operators" have the same SID in all domains. If references to built-in groups are stored in the GPO using their resolved format (based on the underlying SID), they cannot be mapped using migration tables. However, if references to built-in groups are stored as free text, you can map them using a migration table, and in this case, you must specify source type="Free Text or SID."

When viewed in an XML editor, the types are represented as follows:

<Type>User</Type>
<Type>Computer</Type>
<Type>LocalGroup</Type>
<Type>GlobalGroup</Type>
<Type>UniversalGroup</Type>
<Type>UNCPath</Type>
<Type>Unknown</Type>

Source Name

The exact name of the User, Computer, Group or UNC Path referenced in the source GPO. For example, TestDomain\PolicyAdmins or \\server1\publicshare. The type of the source name must match the source type specified in the migration table.

Security principals can be specified using any of the following formats:

UPN. For example, "someone@example.com".
SAM. For example, "example\someone".
DNS. For example, "example.com\someone".
Free text. For example, "someone". You must specify the type as Unknown Group in this case.
SID. For example, S-1-11-111111111-111111111-1111111111-1112. You must specify the type as Free Text or SID in this case.

Destination Name

The destination name specifies how the name of the User, Computer, Group or UNC Path in the source GPO should be treated upon transfer to the destination GPO.

There are four choices:

Same as source. Copy without changes. Equivalent to not putting the source value in the migration table at all.
- MTE value: <Same As Source>
- XML tag:
```
<DestinationSameAsSource />
```
None. Removes the User, Computer or Group from the GPO. This option cannot be used with UNC paths.
- MTE value: <None>
- XML tag: <DestinationNone />
Map by relative name. For example, map SourceDomain\Group1 to TargetDomain\Group1. This option cannot be used with UNC paths.
- MTE value: <Map by Relative name>
- XML tag: <DestinationByRelativeName />
Explicitly specify value. In the destination GPO, replace the source value with the exact literal value you specify.
- MTE value:
```
<exact name to use in target> 
```
- XML tag: <Destination>Exact name to use in target domain</Destination>

Security principals can be specified using any of the following formats:

UPN. For example, "someone@example.com".
SAM. For example, "example\someone".
DNS. For example, "example.com\someone".
Free text. For example, "someone".

Raw SIDs cannot be used for the destination name.

A sample migration table can be found at %programfiles%\GPMC\scripts\SampleMigrationTable.migtable.

Creating Migration Tables Manually

Valid migtable files must contain the following entries, which identifies the namespace used by .migtables. If you are creating migtables by hand, you need to add this. Otherwise MTE does this for you.

<?xml version="1.0" encoding="utf-16"? >

<MigrationTable xmlns="https://www.microsoft.com/GroupPolicy/GPOOperations/MigrationTable">

Each mapping entry appears in the following format:

<Mapping>

<Type>Type</Type>

<Source>Source</Source>

<Destination>Destination</Destination>

</Mapping>

Migration Tables can also be created using the GPMC scripting interfaces. For example, see the CreateMigrationTable.wsf sample script that is included with GPMC.

Share via

Migration tables