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