Migrating Files During a Remote Installation with USMT and Windows Deployment Services

The User State Migration Toolkit (USMT) 4.0 can be used with Windows Deployment Services in Windows Server® 2003, Windows Server 2008, or Windows Server 2008 R2 to migrate user state when installing a new operating system from a pre-boot execution environment (PXE). When combined with a customized Windows image containing both the operating system and applications, this 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 7 using USMT 4.0 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 removing an old operating system and installing a new operating system. At the end of this process, you have a Windows Deployment Services menu option for a Windows 7 installation with migrated settings.

In this example, you create a command script and modify an answer file to call the USMT 4.0 tools during the unattended installation. You also create a customized .xml file for your USMT migration. Then, you add the USMT 4.0 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 your remote installation.

In this Document

Benefits

Requirements

Install the Windows AIK

Step 1: Create a custom .xml file for USMT

Step 2: Create a command script to run USMT tools

Step 3: Modify 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:

  • Deployment speed. Files are not moved or copied during a hard-link migration using USMT 4.0. This helps to decrease the amount of time it takes to migrate files to a new operating system. For more information about hard-link migration stores, see this Microsoft Web site.

  • Recoverable data. Files are not deleted from the system during the setup process. The user profile and other data are moved to the Windows.old directory. If an error occurs, user data is still accessible in the Windows.old directory.

  • Hardware resources. Using a hard-link migration store eliminates the need for an external storage device when migrating 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 7 product DVD

    The steps in this document can also be modified to be used with Windows Vista deployments by substituting a Windows Vista DVD, Boot.wim file, and Install.wim file.

  • Windows Automated Installation Kit (Windows AIK) DVD

    You can download the Windows AIK .iso file from this Microsoft Web site and burn the .iso file onto a blank DVD.

  • A technician computer

    A technician computer is any computer on which you will install the Windows AIK. The technician computer must be running Windows Server 2003, Windows Vista, or Windows 7.

  • A Windows Deployment Services server

    The Windows Deployment Services server must be running Windows Server 2003, Windows Server 2008, or Windows Server 2008 R2. For more information about configuring 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 this Microsoft Web site.

Important

The Install.wim file 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 AIK

To install the Windows AIK:

  1. Insert the Windows AIK DVD into the technician computer's DVD-ROM drive.

    The Setup program automatically starts.

  2. Follow the online instructions.

Note

If the Setup program does not start automatically, in Windows Explorer, browse to the DVD drive containing the Windows AIK DVD, and then click StartCD.exe. Click Windows AIK Setup to begin the installation.

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 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 of 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 with 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 7.

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 of 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 this document.

For more information about creating custom .xml files for USMT, see this Microsoft Web site.

Save this 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.

  1. Open Notepad or another text editor that you can use to create a command script.

  2. Create a variable for the processor architecture of the destination computer. The USMT 4.0 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)
    
  3. 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 4.0 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.

If you are creating this file for use with a new Windows Vista installation, include the **/targetvista** option in the ScanState command line.  
  
For more information about using the ScanState tool, see [this Microsoft Web site](https://go.microsoft.com/fwlink/?linkid=161220).  
  
  1. 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 4.0 tools when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.

    For more information about using the LoadState tool, see this Microsoft Web site.

  2. 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 4.0 tools when you mount the Windows image in Step 4, for example, %windir%\sources\$OEM$\$$\usmt.

  3. Add error checking to your command script. See the Appendix of Sample Files for an example.

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

You can create a new unattended answer file using Windows System Image Manager (Windows SIM), or use an existing answer file you want to modify for use with USMT and Windows Deployment Services. For more information about creating an answer file with Windows SIM, see this Microsoft Web site.

To create an answer file

  1. On your technician computer, insert the Windows 7 product DVD.

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

  3. To open Windows SIM, click Start, click All Programs, click Microsoft Windows AIK, and then click Windows System Image Manager.

  4. On the File menu, click Select Windows Image.

  5. In the Select a Windows Image dialog box, navigate 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.

  6. 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 AIK. 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.

  1. Expand the list of components. In the Windows Image pane of Windows SIM, click Components, click Microsoft-Windows-Shell-Setup, and then click FirstLogonCommands.

  2. Add a SynchronousCommand to run the command file you created. Right-click SynchronousCommand and click Add Setting to Pass 7 oobeSystem.

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

  3. In the SynchronousCommand Properties pane of Windows SIM, set the value of Order to 1 and include the file name of the command file you created to call the USMT 4.0 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 *\
  1. Add another SynchronousCommand to restart the computer after USMT is run. Right-click SynchronousCommand in the Windows Image pane and click Add Setting to Pass 7 oobeSystem.

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

  2. 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 running USMT

Order

2

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

  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 *\* and *\* are the identifiers you will use in the Windows Deployment Services console on your Windows Deployment Services server.

Important

<DiskID> and <PartitionID> values are dependent 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.

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

  2. Include DiskConfiguration values appropriate for your environment. For an example, see the sample answer file in the appendix of this document.

Important

DiskConfiguration values are dependent on your environment. It is important to select values that will preserve the disk and the user files in the Windows.old directory. Using the wrong DiskConfiguration values for your installation could format the disk and remove the files and settings before they can be migrated.

  1. Optional: Add domain-joining commands to the answer file. Depending on your 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 your network environment. For example, include JoinWorkgroup and include Domain, Username, and Password under the Credentials node.

    For more information about using 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 AIK.

Validate and save settings

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

  2. 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 click Save.

  3. 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 4.0 tools and your customized files.

  1. Copy the Boot.wim file from the Windows DVD to your technician computer. For example, at a command prompt type:

    xcopy f:\sources\boot.wim d:\imaging\
    
  2. At an elevated command prompt on your technician computer, open the DISM directory. For example:

    cd /d "C:\Program Files\Windows AIK\Tools\<architecture>"
    

    where <architecture> can be x86, amd64, or ia64.

  3. Create a directory and mount the image with read/write permission. For example:

    mkdir c:\mounted_images
    dism /Mount-Wim /WimFile: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 1 is the reference number of the specific volume in the .wim file.

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

    xcopy "C:\Program Files\Windows AIK\Tools\USMT" C:\mounted_images\sources\$OEM$\$$\usmt /e
    
  5. 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
    
  6. 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
    
  7. Create or modify a Winpeshl.ini file to call Windows setup with the unattended-setup file from Windows PE. For example:

    1. Open 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
      
  8. 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-WIM /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 will need to import the customized images and configure the Windows Deployment Services server to add the new USMT integrated deployment to the PXE menu.

  1. Copy your customized files and images to a network share or removable media. For example, \\Network\Share\WDS.

  2. Start the Windows Deployment Services console on the Windows Deployment Services server. Click Start, click Administrative Tools, and then click Windows Deployment Services.

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

  4. 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 from 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.

  1. Browse to the Boot.wim file. For example, \\Network\Share\WDS\boot.wim. Click Next.

  2. Select an image name for the Boot.wim image, for example, win7_withUSMT. Enter an image description such as "Installs Windows 7 and migrates user files", and then click Next.

  3. Click Next on the Summary screen and then click Finish.

  4. In the left pane of the Windows Deployment Services window, right-click the Install Images directory for your selected server and click Add Image Group.

  5. Enter a name and 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.

  1. Right-click the image group you created and then click Add Install Image.

    The Add Image Wizard opens.

  2. Browse to the Install.wim file. For example, \\Network\Share\WDS\install.wim. Click Next.

  3. Select the images you want to add from the file and then click Next.

  4. Click Next on the Summary screen and then click Finish.

  5. 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 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 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 your 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, including Windows Vista installations, using the steps in this document. For more information about what USMT migrates and using USMT 4.0 with Windows Vista, see this Microsoft Web site.

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. Using the wrong values for your installation 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>win7_usmt_ultimate</ImageName>
               <ImageGroup>win7_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>

See Also

Other Resources

USMT 4.0 User's Guide
Windows Deployment Services Getting Started Guide