ADMT Guide: Migrating and Restructuring Active Directory Domains

Applies To: Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2

Applies to: Active Directory Migration Tool 3.2 (ADMT 3.2)

The latest version of ADMT 3.2 is available on Microsoft Connect (https://go.microsoft.com/fwlink/?LinkId=401534) and it supersedes all previous versions. It runs on all versions of Windows Server and can migrate objects to and from any Active Directory environment. All previous versions of ADMT have been removed from the Microsoft Download Center.

You can download a version of this guide in .doc format (https://go.microsoft.com/fwlink/?LinkId=191734).

As part of deploying Active Directory Domain Services (AD DS), you might choose to restructure your environment for the following reasons:

• To optimize the arrangement of elements within the logical Active Directory structure.

• To assist in completing a business merger, acquisition, or divestiture.

Restructuring involves the migration of resources between Active Directory domains in either the same forest or in different forests. After you deploy Active Directory or AD DS, you might decide to further reduce the complexity of your environment by either restructuring domains between forests or restructuring domains within a single forest.

You can use the Active Directory Migration Tool (ADMT) to perform object migrations and security translation as necessary so that users can maintain access to network resources during the migration process.

In this guide

• Best Practices for Active Directory Migration

• Interforest Active Directory Domain Restructure

• Intraforest Active Directory Domain Restructure

• Appendix: Advanced Procedures

• Troubleshooting ADMT

• Additional Resources

The following sections explain the main migration scenarios for using ADMT. After you determine the appropriate scenario for your environment, follow the steps later in this guide for that scenario.

Interforest Active Directory domain restructure

You might perform an interforest restructure for business changes, such as mergers or acquisitions or divestitures, in which your organizations have to combine or divide resources. As part of the restructuring process, when you migrate objects between forests both the source and target domain environments exist simultaneously. This makes it possible for you to roll back to the source environment during the migration, if necessary.

Splitting or cloning forests—for example, to accommodate divestiture of an organization—is not supported. For more information, see Restructuring Limitations (https://go.microsoft.com/fwlink/?LinkId=121736).

Intraforest Active Directory domain restructure

When you restructure domains in a forest, you can consolidate your domain structure and reduce administrative complexity and overhead. Unlike the process for restructuring domains between forests, when you restructure domains in a forest, the migrated accounts no longer exist in the source domain. Therefore, rollback of the migration can only occur when you carry out the migration process again in reverse order from the previous target domain to the previous source domain.

The following table lists the differences between an interforest domain restructure and an intraforest domain restructure.

Migration consideration	Interforest restructure	Intraforest restructure
Object preservation	Objects are cloned rather than migrated. The original object remains in the source location to maintain access to resources for users.	User and group objects are migrated and no longer exist in the source location. Computer and managed service account objects copied and the original accounts remain enabled in the source domain.
Security identifier (SID) history maintenance	Maintaining SID history is optional.	SID history is required for user, group, and computer accounts, but not managed service accounts.
Password retention	Password retention is optional.	Passwords are always retained.
Local profile migration	You must use tools such as ADMT to migrate local profiles.	Local profiles are migrated automatically because the user’s globally unique identifier (GUID) is preserved.
Closed sets	You do not have to migrate accounts in closed sets. For more information, see Background Information for Restructuring Active Directory Domains Within a Forest (https://go.microsoft.com/fwlink/?LinkId=122123).	You must migrate accounts in closed sets.

Terms and definitions

The following terms apply to the Active Directory domain restructure process.

Migration   The process of moving or copying an object from a source domain to a target domain, while preserving or modifying characteristics of the object to make it accessible in the new domain.

Domain restructure   A migration process that involves changing the domain structure of a forest. A domain restructure can involve either consolidating or adding domains, and it can take place between forests or in a forest.

Migration objects   Domain objects that are moved from the source domain to the target domain during the migration process. Migration objects can be user accounts, service accounts, groups, or computers.

Source domain   The domain from which objects are moved during a migration. When you restructure Active Directory domains between forests, the source domain is an Active Directory domain in a different forest from the target domain.

Target domain   The domain to which objects are moved during a migration.

Built-in accounts   Default security groups that have common sets of rights and permissions. You can use built-in accounts to grant permissions to any accounts or groups that you designate as members of these groups. Built-in account SIDs are identical in every domain. Therefore, built-in accounts cannot be migration objects.

Active Directory Migration Tool

You can use ADMT to migrate objects in Active Directory forests. This tool includes wizards that automate migration tasks, such as migrating users, groups, service accounts, computers, and trusts and performing security translation.

You can perform ADMT tasks by using the ADMT console, a command line, or a script. When you run ADMT at the command line, it is often more efficient to use an option file to specify command-line options. You can use the ADMT option file reference in the following example to assist you in creating option files. Examples of command-line syntax are provided for each task that you must perform to restructure the domains within the forest.

The following listing shows common options that apply to several migration tasks. Each type of migration task has a section that lists options that are specific to that task. The section name corresponds to the task name when you run ADMT at the command line. You can comment out items with a semicolon. In the following listing, the default values are commented out.

[Migration]
;IntraForest=No
;SourceDomain="source_domain_name" 
;SourceOu="source_ou_path" 

;TargetDomain="target_domain_name" 
;TargetOu="target_ou_path" 
;PasswordOption=Complex
;PasswordServer="" 
;PasswordFile="" 
;ConflictOptions=Ignore
;UserPropertiesToExclude="" 
;InetOrgPersonPropertiesToExclude="" 
;GroupPropertiesToExclude="" 
;ComputerPropertiesToExclude="" 

[User]
;DisableOption=EnableTarget
;SourceExpiration=None
;MigrateSIDs=Yes
;TranslateRoamingProfile=No
;UpdateUserRights=No
;MigrateGroups=No
;UpdatePreviouslyMigratedObjects=No
;FixGroupMembership=Yes
;MigrateServiceAccounts=No
;UpdateGroupRights=No

[Group]
;MigrateSIDs=Yes
;UpdatePreviouslyMigratedObjects=No
;FixGroupMembership=Yes
;UpdateGroupRights=No
;MigrateMembers=No
;DisableOption=EnableTarget
;SourceExpiration=None
;TranslateRoamingProfile=No
;MigrateServiceAccounts=No

[Security]
;TranslationOption=Add
;TranslateFilesAndFolders=No
;TranslateLocalGroups=No
;TranslatePrinters=No
;TranslateRegistry=No
;TranslateShares=No
;TranslateUserProfiles=No
;TranslateUserRights=No
;SidMappingFile="SidMappingFile.txt"

When you run ADMT at the command line, you do not have to include an option in your command if you want to accept the default value. In this guide, however, tables that list possible parameters and values are provided for reference. The tables list the command-line equivalent of each option that is shown in the corresponding ADMT console procedure, including those options for which you accept the default value.

You can copy the option file reference into Notepad and save it by using a .txt file name extension.

As an example, to migrate a small number of computers, you might type each computer name at the command line, using the /N option, and then list other migration options within an option file as follows:

ADMT COMPUTER /N "<computer_name1>" "<computer_name2>" /O:"<option_file>.txt"

Where <computer_name1> and <computer_name2> are the names of computers in the source domain that you are migrating in this batch.

Using an include file

When you migrate a large number of users, groups, or computers, it is more efficient to use an include file. An include file is a text file in which you list the user, group, and computer objects that you want to migrate, with each object on a separate line. You must use an include file if you want to rename objects during the migration.

You can list users, groups, and computers together in one file, or you can create a separate file for each object type. Then, specify the include file name with the /F option, as follows:

ADMT COMPUTER /F "<includefile_name>" /IF:YES /SD:"<source_domain>” /TD:"<target_domain>" /TO:"<target_OU>"

To specify the names of users, groups, or computers, use one of the following conventions:

• The Security Accounts Manager (SAM) account name. To specify a computer name in this format, you must append a dollar sign ($) to the computer name. For example, to specify a computer with the name Workstation01, use Workstation01$.

• The relative distinguished name (also known as RDN), for example, cn= Workstation01. If you specify the account as a relative distinguished name, you must specify the source organizational unit (OU).

• The canonical name. You can specify the canonical name as DNS domain name/ou_path/object_name or ou_path/object_name, for example, Asia.trccorp.treyresearch.net/Computers/Workstation01 or Computers/Workstation01.

The following sections describe the fields of an include file and provide examples for each field:

SourceName field

The SourceName field specifies the name of the source object. You can specify either an account name or a relative distinguished name. If you only specify source names, it is optional to define a header on the first line in the file.

The following example illustrates a header line that specifies the SourceName field. The example also shows a source object name that is specified in several formats. The second line specifies an account name. The third line specifies a relative distinguished name.

SourceName

name

**CN=**name

TargetName field

You can use the TargetName field to specify a base name that is used to generate a target relative distinguished name, a target SAM account name, and a target user principal name (UPN). The TargetName field cannot be combined with other target name fields that are described later in this section.

Note

The target UPN is generated only for user objects, and only a UPN prefix is generated. A UPN suffix is appended using an algorithm that depends on whether a UPN suffix is defined for the target OU or the target forest. If the object is a computer, the target SAM account name includes a "$" suffix.

The following example of input generates the target relative distinguished name, target SAM account name, and target UPN as "CN=newname", "newname," and "newname" respectively.

SourceName,TargetName

oldname, newname

TargetRDN, TargetSAM, and TargetUPN fields

You can use the TargetRDN, TargetSAM, and TargetUPN fields to specify the different target names independently of each other. You can specify any combination of these fields in any order.

TargetRDN specifies the target relative distinguished name for the object.

TargetSAM specifies the target SAM account name for the object. For computers, the name must include a "$" suffix to be a valid SAM account name for a computer.

TargetUPN specifies the target UPN for the object. You can specify either just the UPN prefix or a complete UPN name (prefix@suffix). If the name that you specify contains a space or a comma, you must enclose the name in double quotation marks (" ").

SourceName,TargetRDN

oldname, **CN=**newname

SourceName,TargetRDN,TargetSAM

oldname, "CN=New RDN", newsamname

SourceName,TargetRDN,TargetSAM,TargetUPN

oldname, "CN=last\, first", newsamname, newupnname

Note

A comma within the CN value must be preceded with an escape ("") character or the operation will fail, and ADMT will record an invalid syntax error in the log file.

SourceName,TargetSAM,TargetUPN,TargetRDN

oldname, newsamname, newupnname**@**targetdomain, **"CN=**New Name"

Renaming objects

Use the following format in an include file to rename computer, user, or group objects during migration:

• Use SourceName, TargetRDN, TargetSAM, and TargetUPN as column headings at the top of the include file. SourceName is the name of the source account, and it must be listed as the first column heading. The TargetRDN, TargetSAM, and TargetUPN column headings are optional, and you can list them in any order.

• You must specify the account name as user name, relative distinguished name, or canonical name. If you specify the account name as a relative distinguished name, you must also specify the source OU.

The following are examples of valid include files in which the rename option is used:

SourceName,TargetSAM

abc,def

This include file entry changes the TargetSAM account name for user "abc" to "def." The TargetRDN and the TargetUPN, which are not specified in this include file, do not change as a result of the migration.

SourceName,TargetRDN,TargetUPN

abc,CN=def,def@contoso.com

This include file entry changes the TargetRDN for user abc to CN=def and the TargetUPN to def@contoso.com. The TargetSAM for user abc does not change as a result of the migration.

Important

You must specify CN= before using an RDN value.

Using an exclude file

You can exclude objects from migration by using an exclude file. An exclude file is a text file that lists the SAMAccountName attribute of the objects that you want to exclude. For example, to exclude the following managed service accounts, create a text file:

MSA_USER5$
MSA_USER6$

Then, specify the name of the exclude file when you run the admt command. For example:

admt managedserviceaccount /ef:”exclude file name”

Optionally, you can exclude specific accounts by using the /en parameter:

admt managedserviceaccount /en:”managed service account 1” “managed service account 2”

Using scripts

The sample scripts that are provided in this guide refer to the symbolic constants that are defined in a file named AdmtConstants.vbs. The listing that follows shows the ADMT constants Microsoft Visual Basic® Scripting Edition (VBScript) file. The constants are also provided in the ADMT installation folder, in the TemplateScript.vbs file, in the %systemroot%\WINDOWS\ADMT directory.

To use the sample scripts in the guide, copy the ADMT constants VBScript file into Notepad and save it as AdmtConstants.vbs. Be sure to save it in the same folder where you plan to save the sample scripts that are provided in this guide.

Option Explicit

'----------------------------------------------------------------------------
' ADMT Scripting Constants
'----------------------------------------------------------------------------

' PasswordOption constants

Const admtComplexPassword                   = &H0001
Const admtCopyPassword                      = &H0002

' Note that the following constant cannot be specified alone.
' It must be specified along with admtComplexPassword or admtCopyPassword.
Const admtDoNotUpdatePasswordsForExisting   = &H0010

' ConflictOptions constants

Const admtIgnoreConflicting           = &H0000
Const admtMergeConflicting            = &H0001
Const admtRemoveExistingUserRights    = &H0010
Const admtRemoveExistingMembers       = &H0020
Const admtMoveMergedAccounts          = &H0040

' DisableOption constants

Const admtLeaveSource        = &H0000
Const admtDisableSource      = &H0001
Const admtTargetSameAsSource = &H0000
Const admtDisableTarget      = &H0010
Const admtEnableTarget       = &H0020

' SourceExpiration constant

Const admtNoExpiration = -1

' Translation Option

Const admtTranslateReplace = 0
Const admtTranslateAdd     = 1
Const admtTranslateRemove  = 2

' Report Type

Const admtReportMigratedAccounts  = 0
Const admtReportMigratedComputers = 1
Const admtReportExpiredComputers  = 2
Const admtReportAccountReferences = 3
Const admtReportNameConflicts     = 4

' Option constants

Const admtNone     = 0
Const admtData     = 1
Const admtFile     = 2
Const admtDomain   = 3
Const admtRecurse           = &H0100
Const admtFlattenHierarchy  = &H0000
Const admtMaintainHierarchy = &H0200