Step-by-Step: Migrating Files During a Remote Installation with USMT and Windows Deployment Services

Article
03/06/2014

Applies To: Windows 8, Windows 8.1

The User State Migration Tool (USMT) 5.0 can be used with Windows Deployment Services in Windows Server® 2003, Windows Server 2008, Windows Server 2008 R2, or Windows Server® 2012 to migrate user states when you install a new operating system from a pre-boot execution environment (PXE). When combined with a customized Windows image that contains both the operating system and applications, this method provides a quick way to transition users to a new operating system on their existing hardware.

This step-by-step guide provides a basic example of how to migrate files and settings from Windows Vista® to Windows® 8 using USMT during a remote installation using Windows Deployment Services. This example uses a hard-link migration. You can use a hard-link migration to perform an in-place migration where all user state is maintained on a computer while you remove an old operating system and install a new operating system. At the end of this process, you have a Windows Deployment Services menu option for a Windows 8 installation that uses migrated settings.

In this example, you create a command script and modify an answer file to call the USMT tools during the unattended installation. You also create a customized .xml file for your USMT migration. Then, you add the USMT tools and customized files to a Boot.wim image file to use on the Windows Deployment Services server. Finally, you import the necessary file to the Windows Deployment Services server and test the remote installation.

In this Document

Benefits

Requirements

Install the Windows ADK

Step 1: Create a custom .xml file for USMT

Step 2: Create a command script to run USMT tools

Step 3: Create an unattended answer file

Step 4: Customize the Boot.wim file

Step 5: Import files to the Windows Deployment Services server

Next Steps

Appendix of Sample Files

Benefits

The benefits of using this scenario include the following:

Deployment speed. Files are not moved or copied during a hard-link migration using USMT. This helps decrease the time it takes to migrate files to a new operating system. For more information about hard-link migration stores, see Hard-Link Migration Store.
Recoverable data. Files are not deleted from the system during the setup process. The user profile and other data is moved to the Windows.old directory. If an error occurs, user data is still available in the Windows.old directory.
Hardware resources. Using a hard-link migration store eliminates the need for an external storage device when you migrate files.
User initiation. Individuals who have access to the Windows Deployment Services server through PXE can decide when to install the new operating system, according to their personal schedule.

Requirements

To complete this scenario, you need the following:

Windows 8 product DVD
Windows Assessment and Deployment Kit (Windows ADK)

You can install the Windows ADK directly from the Internet. You can also use a computer that has Internet access to download the installer files so that you can run Setup on an offline computer. In the Windows ADK Setup Wizard, you can select the components that you want to install, such as USMT.
A technician computer

A technician computer is any computer on which you have installed the Windows ADK.
A Windows Deployment Services server

The Windows Deployment Services server must be running Windows Server 2008, or Windows Server 2008 R2, or Windows Server 2012. For more information about how to configure a Windows Deployment Services server, see this Microsoft Web site.
Optional: A customized Install.wim file

For more information about creating a customized Install.wim file, see Deployment Image Servicing and Management (DISM) Technical Reference and Windows Deployment Options.

Important

The Install.wim file that you use must match the version of the Boot.wim file from the product DVD. For example, if you are using a Boot.wim file from Windows Vista with SP1, you must also use an Install.wim file from Windows Vista with SP1.

Install the Windows ADK

To install the Windows ADK:

On your technician computer, run ADK Setup.
Select Install, specify the location where you want to install ADK features, and then click Next.
In the Assessment and Deployment Kit window, select the features that you want to install, including USMT, and then click Install.

Step 1: Create a custom .xml file for USMT

Create a customized .xml file to restore files from the Windows.old directory on the destination computer.

In the answer file that you create for this deployment, you will specify that Windows Setup should not wipe the disk before installation. This will preserve files and directories on the disk that are outside the directories that contain the Windows operating system. Also, Windows Setup will be able to create a Windows.old directory to archive files that would otherwise be overwritten by the new operating system.

For example, on a computer that has a C: and D: drive, where the C: drive has many directories on it, Windows Setup will only move three directories (Users, Program Files, and Windows) from the C: drive to the Windows.old directory. All of the other directories on the C: drive will be ignored, as will all the data on the D: drive. New versions of the Users, Program Files, and Windows directories will then be created on the C: drive to contain Windows 8.

When the installation is complete, all files will be in their original locations, except for the limited amount of data that was moved into the Windows.old directory.

The customized .xml file for USMT should specify parameters to scan only files that have been moved to the Windows.old directory and then to load them into the new Windows directories on your disk.

Important

If you do not create the customized .xml file for this scenario or if you use the default Migdocs.xml file, all of the files on your disk outside the Windows operating system directories will be scanned and duplicates of each file will be loaded back onto the disk.

A sample file is included in the Appendix of Sample Files of this document.

For more information about how to create custom .xml files for USMT, see Customize USMT XML Files.

Save this custom .xml file as Userprofile.xml.

Step 2: Create a command script to run USMT tools

Build a command script that calls the USMT command-line tools.

Start Notepad or another text editor that you can use to create a command script.
Create a variable for the processor architecture of the destination computer. The USMT tools are saved to different directories, based on the architecture. You can use this variable to change the path to the USMT tools. For example,
```
IF '%PROCESSOR_ARCHITECTURE%' == 'x86' (SET USMTPATH=x86) ELSE (SET USMTPATH=x64)
```
Use the ScanState tool to create a hard-link migration store and collect files and settings from the Windows.old directory on your destination computer. Specify the customized Userprofile.xml file by using the /i: option. For example,
```
call <path to USMT tools>\%USMTPATH%\scanstate.exe %systemdrive%\store /v:13 /o /c /hardlink /nocompress /efs:hardlink /i:<path to USMT tools>\scripts\UserProfile.xml /i:<path to USMT tools>\%USMTPATH%\MigApp.xml /offlineWinOld:%systemdrive%\Windows.old\Windows /l:<path to USMT tools>\scanstate.log /progress:<path to USMT tools>\progress_scanstate.log
```
Where <path to USMT tools> is the path to the directory where you copy the USMT tools when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.

Important

If a Windows.old directory is already present, the new folder is named Windows.old.nnn, where nnn is a three-digit number such as 000 or 001. If you have installed Windows multiple times on the same computer, the latest versions of files may not be in the Windows.old folder.

For more information about how to use the ScanState tool, see ScanState Syntax.
Use the LoadState tool to apply files and settings from you hard-link migration store to your new installation of Windows on your destination computer. Specify the customized Userprofile.xml file by using the /i: option. For example,
```
call <path to USMT tools>\%PATH%\loadstate.exe %systemdrive%\store /v:13 /c /hardlink /nocompress /lac /lae /i:<path to USMT tools>\scripts\UserProfile.xml /i:<path to USMT tools>\%PATH%\MigApp.xml /l:<path to USMT tools>\loadstate.log /progress:<path to USMT tools>\progress_loadstate.log
```
Where <path to USMT tools> is the path to the directory where you copy the USMT tools when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.

For more information about how to use the LoadState tool, see LoadState Syntax.
Use the USMTUtils tool with the /rd option to delete the hard-link migration tool when the migration is complete. For example.
```
call ECHO Y | <path to USMT tools>\%PATH%\usmtutils /rd %systemdrive%\store
```
Where <path to USMT tools> is the path to the directory where you copy the USMT tools when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.
Add error checking to your command script. See the Appendix of Sample Files for an example.
Save this file to your technician computer as a command script; an example file name is Usmt.cmd.

Step 3: Create an unattended answer file

To create an answer file

On your technician computer, insert the Windows 8 product DVD.
Navigate to the \Sources directory on your DVD-ROM drive and copy the Install.wim file from the Windows product DVD to a location on the computer.
To open Windows SIM, click Start, click All Programs, click Windows Kits, click Windows ADK, and then click Windows System Image Manager.
On the File menu, click Select Windows Image.
In the Select a Windows Image dialog box, move to the location of the Install.wim, and then click Open.

You will be prompted to select an image. Select the Windows image that you want to install, and then click OK.

You will be prompted to create a catalog file. Click Yes to generate a catalog file.

If you are prompted to approve the program by a User Account Control window, you can select to allow the program or cancel the installation.
On the File menu, click New Answer File. An empty answer file appears in the Answer File pane.

To add and configure Windows settings

For more information about how to customize your answer file, see the Windows® Unattended Setup Reference that is installed with the Windows ADK. For this scenario, you add a synchronous command to call the command script that runs the USMT tools, you configure Windows Deployment Services settings, and you define basic disk configurations.

Expand the list of components. In the Windows Image pane of Windows SIM, click Components, click Microsoft-Windows-Shell-Setup, and then click FirstLogonCommands.
Add a SynchronousCommand to run the command file that you created. Right-click SynchronousCommand and then click Add Setting to Pass 7 oobeSystem.

A SynchronousCommand node is added to the tree in the Answer File pane of Windows SIM.
In the SynchronousCommand Properties pane of Windows SIM, set the value of Order to 1 and include the file name of the command file that you created to call the USMT tools. You can also include a description. For example:

Property Value

CommandLine

cmd.exe /c <path to USMT.cmd>\usmt.cmd

Description

Call USMT tools

Order

1

Where <path to USMT.cmd> is the path to the directory where you copy the USMT.cmd file when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.
Add another SynchronousCommand to restart the computer after USMT is run. Right-click SynchronousCommand in the Windows Image pane and then click Add Setting to Pass 7 oobeSystem.

A SynchronousCommand node is added to the tree in the Answer File pane of Windows SIM.
In the SynchronousCommand Properties pane of Windows SIM, set the value of Order to 2 and include the command to restart the computer. You can also include a description. For example:

Property Value

CommandLine

shutdown /r /t 0

Description

Restart after you run USMT

Order

2
Add image-specific information to the answer file for Windows Deployment Services. In the Windows Image pane of Windows SIM, click Microsoft-Windows-Setup, right-click WindowsDeploymentServices, and then click Add Setting to Pass 1 windowsPE.

A WindowsDeploymentServices node is added to the tree in the Answer File pane of Windows SIM.

Property	Value
CommandLine	`cmd.exe /c <path to USMT.cmd>\usmt.cmd`
Description	Call USMT tools
Order	1

Property	Value
CommandLine	`shutdown /r /t 0`
Description	Restart after you run USMT
Order	2

Add the following values for WindowsDeploymentServices and child nodes in the Properties pane.

Property	Value
Image Selection\Install Image\Image Name	<Image Name>
Image Selection\Install Image\Image Group	<Image Group>
Image Selection\Install To\DiskID	<DiskID>
Image Selection\Install To\PartitionID	<PartitionID>

Where <Image Name> and <Image Group> are the identifiers you will use in the Windows Deployment Services console on the Windows Deployment Services server.

Important

<DiskID> and <PartitionID> values depend on your environment. It is important that the disk and partition information is included and accurate so that the disk formatting screens in Windows OOBE are automated on the destination computer. If these screens are not automated, the user can choose disk and partition options that will format the disk and remove the files and settings before they can be migrated.

Add DiskConfiguration to the answer file. In the Windows Image pane of Windows SIM, click Microsoft-Windows-Setup, right-click DiskConfiguration, and then click Add Setting to Pass 1 windowsPE.

A DiskConfiguration node is added to the tree in the Answer File pane of Windows SIM.
Include DiskConfiguration values appropriate for your environment. For an example, see the sample answer file in the Appendix of Sample Files of this document.

Important

DiskConfiguration values depend on your environment. It is important to select values that will preserve the disk and the user files in the Windows.old directory. If you use the wrong DiskConfiguration values for your installation you could format the disk and remove the files and settings before they can be migrated.
Optional: Add domain-joining commands to the answer file. Depending on the network environment, there are several ways that you can join the destination computer to your domain. You can configure Windows Deployment Services to join the domain, add a domain-joining task to the command script from Step 2, deploying an image that is already joined to the domain, or use setting available in the unattended answer file.

To use the settings in the answer file, in the Windows Image pane of Windows SIM, click Microsoft-Windows-UnattendJoin, right-click Identification, and then click Add Setting to Pass 4 specialize.

An Identification node is added to the tree in the Answer File pane of Windows SIM.

Include values that are required by the network environment. For example, include JoinWorkgroup and include Domain, Username, and Password under the Credentials node.

For more information about how to use this component in your unattended answer file, see the Microsoft-Windows-UnattendedJoin topic in the Windows® Unattended Setup Reference that is installed with the Windows ADK.

To validate and save settings

Validate the answer file by selecting Validate Answer File from the Tools menu. Any errors or warnings will appear in the Messages pane of Windows SIM.
Save the answer file as Unattend.xml. On the File menu, click Save Answer File As, browse to the location where you want to save the file, type Unattend in the File name text box, and then click Save.
Close Windows SIM.

Step 4: Customize the Boot.wim file

Use the Deployment Image Servicing and Management (DISM) tool to mount the Boot.wim file and add the USMT tools and your customized files.

Copy the Boot.wim file from the Windows DVD to your technician computer. For example, at a command prompt type:
```
xcopy D:\sources\boot.wim C:\imaging\
```
At an elevated command prompt on your technician computer, create a directory and mount the image with read/write permission. For example:
```
mkdir C:\mounted_images
dism /Mount-Image /ImageFile:D:\imaging\boot.wim /index:2 /MountDir:C:\mounted_images
```
where D:\imaging\boot.wim is the name and the location of the .wim file to mount, and 2 is the reference number of the specific volume in the .wim file.

Copy the USMT tools to the mounted image. For example:

xcopy "C:\Program Files (x86)\Windows Kits\8.0\Assessment and Deployment Kit\User State Migration Tool\" C:\mounted_images\sources\$OEM$\$$\usmt /e

Copy the command script to the mounted image. For example, at a command prompt, type:
```
xcopy C:\myscripts\USMT.cmd C:\mounted_images\sources\$OEM$\$$\usmt
```
Copy the Unattend.xml file to the mounted image. For example, at a command prompt type:
```
xcopy C:\myfiles\unattend.xml C:\mounted_images\sources\$OEM$\$$\usmt
```
Create or modify a Winpeshl.ini file to call Windows setup with the unattended-setup file from Windows PE. For example:
1. Start Notepad or another text editor that you can use to create a configuration file.
2. Include Windows Setup in the LaunchApps section and use the path of the unattended-setup file in the Windows image. For example:
```
[LaunchApp]
AppPath = %SYSTEMDRIVE%\myshell.exe
[LaunchApps]
%SYSTEMDRIVE%\setup.exe /unattend:%systemdrive%:\sources\$OEM$\$$\usmt\unattend.xml
```
3. Save the file on your technician computer as Winpeshl.ini.
4. Copy the Winpeshl.ini file to the system32 directory of the mounted image. For example, at a command prompt type:
```
xcopy C:\myfiles\winpeshl.ini C:\mounted_images\Windows\System32
```
Note

You'll need a version of Windows PE that supports your migration. For example, to migrate to Windows 8.1, you'll need Windows PE 5.0. For more info, see What's New in Windows PE.
After you modify an image, you must unmount it. You must also commit the changes to save these modifications as a permanent part of the image. At a command prompt, type:
```
dism /unmount-Image /MountDir:C:\mounted_images /commit
```
where C:\mounted_images is the location of the mount directory.

Step 5: Import files to the Windows Deployment Services server

You must import the customized images and configure the Windows Deployment Services server to add the new USMT integrated deployment to the PXE menu.

Copy your customized files and images to a network share or removable media. For example, \\Server\Share\WDS.
Start the Windows Deployment Services console on the Windows Deployment Services server. Click Start, click Administrative Tools, and then click Windows Deployment Services.
In the left pane of the Windows Deployment Services window, expand the tree view for the server where you want to import the image files.
Right-click the Boot Images directory for the server and select Add Boot Image.

The Add Image Wizard opens.

Note

You can also add images at a command prompt. For example, wdsutil.exe /add-image /imagefile:<locationofboot.wim> /imagetype:boot. Where <locationofboot.wim> is the location of the image file to be added.
Browse to the Boot.wim file. For example, \\Server\Share\WDS\boot.wim. Click Next.
Select an image name for the Boot.wim image, for example, win_withUSMT. Enter an image description such as "Installs Windows 8 and migrates user files", and then click Next.
Click Next on the Summary screen and then click Finish.
In the left pane of the Windows Deployment Services window, right-click the Install Images directory for your selected server and then click Add Image Group.
Enter a name and then click OK.

Important

The name of the install-image group and of the install image must match what is entered in the Unattend.xml file.
Right-click the image group you created and then click Add Install Image.

The Add Image Wizard opens.
Browse to the Install.wim file. For example, \\Server\Share\WDS\install.wim. Click Next.
Select the images that you want to add from the file and then click Next.
Click Next on the Summary screen and then click Finish.
In the Windows Deployment Services window, right-click the imported image and select Properties. Check Allow image to install in unattended mode and then click Select File browse to the location of the unattend.xml file that you created. Click OK.

The menu option for the customized image with USMT is now available from the Windows Deployment Services server's PXE boot menu, listed as the image name that you specified in the Windows Deployment Services wizard and the Unattended-setup file.

You can now test the installation on a destination computer.

Next Steps

You should test the Windows Deployment Services image installation; verify that your disk partitioning values are accurate and that the expected content has been migrated. In addition, you can verify that your destination computer joins the domain as expected.

You can add installation options with migrated files and settings for other configurations your company uses, by following the steps in this document. For more information about what USMT migrates, see User State Migration Tool (USMT) Overview.

Appendix of Sample Files

Sample Userprofile.xml file

<?xml version="1.0" encoding="UTF-8"?>
<migration urlid="https://www.microsoft.com/migration/1.0/migxmlext/miguser">

   <!-- This component migrates data in user context -->
   <component type="Documents" context="User">
      <displayName>MigDocUser</displayName>
      <role role="Data">
         <rules>
            <include filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
               <objectSet>
                  <script>MigXmlHelper.GenerateDocPatterns ("FALSE","TRUE","FALSE")</script>
               </objectSet>
             </include>
             <exclude filter='MigXmlHelper.IgnoreIrrelevantLinks()'>
               <objectSet>
                  <script>MigXmlHelper.GenerateDocPatterns ("FALSE","FALSE","FALSE")</script>
               </objectSet>
            </exclude>

            <!--   Example:
            <exclude>
               <objectSet>
                  <pattern type="File">%CSIDL_MYVIDEO%\* [*]</pattern>
               </objectSet>
            </exclude>
                    -->

            <contentModify script="MigXmlHelper.MergeShellLibraries('TRUE','TRUE')">
               <objectSet>
                  <pattern type="File">*[*.library-ms]</pattern>
               </objectSet>
            </contentModify>
            <merge script="MigXmlHelper.SourcePriority()">
               <objectSet>
                  <pattern type="File">*[*.library-ms]</pattern>
               </objectSet>
            </merge>
         </rules>
      </role>
   </component>
</migration>

Sample command script to call USMT tools

@echo off
IF '%PROCESSOR_ARCHITECTURE%' == 'x86' (SET USMTPATH=x86) ELSE (SET USMTPATH=amd64)
:SCAN
call %windir%\usmt\%USMTPATH%\scanstate.exe %systemdrive%\store /v:13 /o /c /hardlink /nocompress /efs:hardlink /i:%windir%\usmt\scripts\UserProfile.xml /i:%windir%\usmt\%USMTPATH%\MigApp.xml /offlineWinOld:%systemdrive%\Windows.old\Windows /l:%windir%\usmt\scanstate.log /progress:%windir%\usmt\progress_scanstate.log
if %errorlevel%==0 (GOTO :LOAD) ELSE (GOTO :FAIL)
:LOAD
call %windir%\usmt\%USMTPATH%\loadstate.exe %systemdrive%\store /v:13 /c /hardlink /nocompress /lac /lae /i:%windir%\usmt\scripts\UserProfile.xml /i:%windir%\usmt\%USMTPATH%\MigApp.xml /l:%windir%\usmt\loadstate.log /progress:%windir%\usmt\progress_loadstate.log
if %errorlevel%==0 (GOTO :CLEAN) ELSE (GOTO :FAIL)
:CLEAN
call ECHO Y | %windir%\usmt\%USMTPATH%\usmtutils /rd %systemdrive%\store
:SUCCESS
echo USMT restore from Windows.old completed successfully!
GOTO :END
:FAIL
echo USMT restore from Windows.old failed.  Check the logs for details.
:END

Sample Unattend.xml file

Security Note
This code is included as an example. It is important that you provide disk and partition values in the Microsoft-Windows-Setup configuration pass that support the destination computers in your environment. If you use the wrong values for your installation you could format the disk and remove the user's files and settings before they can be migrated.

<?xml version="1.0" encoding="utf-8"?>
<unattend xmlns="urn:schemas-microsoft-com:unattend">
<settings pass="windowsPE">

   <component name="Microsoft-Windows-Setup" processorArchitecture="amd64" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State">

      <ImageInstall>
         <OSImage>
            <WillShowUI>OnError</WillShowUI>
         </OSImage>
      </ImageInstall>

      <WindowsDeploymentServices>
         <Login>
            <WillShowUI>Always</WillShowUI>
         </Login>
         <ImageSelection>
            <WillShowUI>OnError</WillShowUI>
            <InstallImage>
               <ImageName>windows_usmt_ultimate</ImageName>
               <ImageGroup>windows_usmt</ImageGroup>
            </InstallImage>
            <InstallTo>
               <DiskID>0</DiskID>
               <PartitionID>1</PartitionID>
            </InstallTo>
         </ImageSelection>
      </WindowsDeploymentServices>

      <DiskConfiguration>
         <WillShowUI>OnError</WillShowUI>
         <Disk>            <DiskID>0</DiskID>            <WillWipeDisk>false</WillWipeDisk>            <ModifyPartitions>               <ModifyPartition>                  <Order>1</Order>                  <PartitionID>1</PartitionID>                  <Letter>C</Letter>               </ModifyPartition>            </ModifyPartitions>         </Disk>      </DiskConfiguration>
      <UpgradeData>
         <Upgrade>false</Upgrade>
      </UpgradeData>

   </component>
</settings>

<settings pass="oobeSystem">

   <component name="Microsoft-Windows-Shell-Setup" processorArchitecture="x86" publicKeyToken="31bf3856ad364e35" language="neutral" versionScope="nonSxS" xmlns:wcm="https://schemas.microsoft.com/WMIConfig/2002/State" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

      <FirstLogonCommands>
         <SynchronousCommand>
            <Order>1</Order>
            <CommandLine>cmd.exe /c %windir%\usmt\scripts\usmt.cmd</CommandLine>
            <Description>call USMT</Description>
         </SynchronousCommand>
         <SynchronousCommand>
            <Order>2</Order>
            <CommandLine>shutdown /r /t 0</CommandLine>
            <Description>reboot the machine</Description>
         </SynchronousCommand>
      </FirstLogonCommands>

   </component>

</settings>
</unattend>

Step-by-Step: Migrating Files During a Remote Installation with USMT and Windows Deployment Services

In this Document

Benefits

Requirements

Install the Windows ADK

Step 1: Create a custom .xml file for USMT

Step 2: Create a command script to run USMT tools

Step 3: Create an unattended answer file

To create an answer file

To add and configure Windows settings

To validate and save settings

Step 4: Customize the Boot.wim file

Step 5: Import files to the Windows Deployment Services server

Next Steps

Appendix of Sample Files

Sample Userprofile.xml file

Sample command script to call USMT tools

Sample Unattend.xml file

See Also

Other Resources

Additional resources