Get started Bring yourself up to speed with our introductory content.

Upgrading to Windows Vista: Migrating settings using the Microsoft Windows User State Migration Tool

Mark Minasi provides the information you need to ensure Windows Vista will run on your system. This chapter is an excerpt from Minasi's book, "Mastering Windows Vista for Business Professionals."

SP1 and R2

Mastering Windows Vista for Business Professionals
By Mark Minasi and John Paul Mueller

The following excerpt is from chapter two of Mastering Windows Vista for Business Professionals, entitled "Installing Vista."


Check out the rest of this chapter, Installing Vista.

Migrating Settings Using the Microsoft Windows User State Migration Tool (USMT)

USMT provides significantly more flexibility when transferring user information than using Windows Easy Transfer. Of course, you pay for that extra flexibility with significantly greater complexity. Consequently, if Windows Easy Transfer does the job for you, then you'll want to skip this section. You can download USMT here .

Unlike Windows Easy Transfer, USMT is actually a command-line tool that you can add to everything from batch files to the task scheduler. Given the right command-line switches, you can use it to back up all of your system settings and data on a given interval. Of course, the main use for this utility is to move user settings and data from one machine to another, even if you must use an intermediate share on a network server to do it. Here are the command-line options for the USMT utility that stores the settings, ScanState.

/compress[+ | -] Enable or disable compression of the settings files. The default setting enables settings file compression.

/localonly Use only local drives for the scan. This setting overrides any settings you provide as part of an INF file.

/l:<log file> Place the log file in a particular location. The default location is the USMT folder.

/v:<verbosity> Define the amount of information that appears in the log file. Adding more information provides additional details about the scanning process, but also increases the time and resources required to perform the scan. The verbosity levels are as follow:

Level 1 Enables verbose output.
Level 4 Enables error and status output.
Level 5 Enables verbose and status output.
Level 8 Enables error output to a debugger.
Level 9 Enables verbose output to a debugger.
Level 12 Enables error and status output to a debugger.
Level 15 Enables verbose, status, and debugger output.
/progress:<log> Defines the location of the progress log. The progress log informs you about the status of the scan.

/all Scan all of the users on a particular machine instead of just the current user. This setting lets you perform one scan per machine no matter how many users the machine supports. You must have administrator privileges to use this command-line switch.

/user:<user> Scan a particular user on the target machine. ScanState normally scans the currently logged on user. This command-line switch lets you scan other users. You must have administrator privileges to use this command-line switch. ScanState lets you use multiple /user switches on the same command line.

/ui:<timeout> Exclude any users whose accounts are inactive within the timeout value. This feature lets you get rid of any old accounts that aren't used on the current machine. The timeout value can include a number of days or appear as an actual date in Year/Month/Day format.

/i:<input inf> Use the specified INF file to configure ScanState. The INF file can define every element of the scan process. The following command-line switches augment and modify INF file use. Normally, ScanState enables all of these switches. However, if you use any of them on the command line, ScanState automatically disables the features you don't specify.

/x Remove the default migration groups from the scan. This command-line switch focuses the search on the target machine and the specified user. It applies to the [Administrator Scripts] and [Administrator User Scripts] sections of the INF file, along with the Copy This State and Copy This User State settings.

/u Perform a full scan of the HKEY_CURRENT_USER hive. Use this setting to ensure that you have all settings for every application you have loaded on your system.

/s Scan all of the system settings and applications. This command-line switch refers to the [System Settings], [Applications], and [User Settings] sections of the INF file.

/f Use file rules during the scan. This command-line switch refers to the [Files and Folders], [Administrator Scripts], and [Administrator User Scripts] sections of the INF file.

/c Continue the scan process even after encountering a nonfatal error. ScanState always fails after a fatal error.

/p Generate a space estimate file (USMTsize.txt). You must specify /compress- option to use this feature. The resulting space estimate is for an uncompressed scan.

/o Overwrite any existing store data. If you don't specify this command-line switch and the selected data store (directory or other share) contains data, ScanState will fail. Use this option only when you know you want to overwrite the existing data.

/r:<count> Specify the failure retry count. The default setting of 3 works in most cases. However, you might want to increase this value in environments where you can't count on a good connection to the target machine. On the other hand, you can save scanning time by reducing the value in environments where you know the connection is completely reliable.

/w:<timeout> Specify the delay, in seconds, when retrying after a failure. The default setting is 1 second. However, you might want to increase this value when the connection between systems isn't only unreliable, but the interruption is long lasting.

/efs:<option> Specify choice of USMT behavior for Encrypted File System (EFS) files. The following list defines the standard behaviors.

abort ScanState automatically fails when it encounters an EFS. This is the default behavior.

skip ScanState skips the EFS partition and continues with any other data stores that appear in the processing list.

decryptcopy Decrypts the EFS data and stores it in an unencrypted state. This option can fail even when the files are accessible because Windows encrypts files using the user's credentials. If you're trying to save the data for another user, the scan can fail because you don't have the credentials required to decrypt the data.

copyraw Copies the EFS data in the encrypted state. This option can backfire, in some cases, because the credentials that Windows generates for a particular user can differ between installations. When this problem occurs, the data becomes permanently inaccessible. The only way to avoid problems when using this technique is to migrate the EFS certificates. The "Saving Settings with the User Setting Migration Toolkit (USMT)" section of Chapter 39 contains additional details on working with EFS.

<store path> Specify the path to the data store. You can use a local drive or save the data to a network drive using the UNC format.

/test Places USMT in a test mode so that you can perform tasks such as verifying that an INF works as expected. You can also use this command-line switch to verify that a scan won't fail due to a lack of permissions.

Using the ScanState utility to save local settings usually means relying on the command line rather than an INF file (an option discussed in detail in Chapter 39). For example, if you want to save the settings for the local drive to a local data store, you might use the following command line.

ScanState D:\MySettings /All /LocalOnly /V:5 /L:D:\MySettings\Scan.log

These settings create a store in the D:\MySettings folder for all users by scanning only the local drives. The scan information appears in D:\MySettings\Scan.log and has a verbosity level of 5.

After you install a new operating system and its associated applications, you use the LoadState utility to restore the settings that you saved using the ScanState utility. The following commandline switches work the same as the ScanState utility.

  • /compress[+ | -]
  • /l:<log file>
  • /v:<verbosity>
  • /progress:<log>
  • /all
  • /user:<user>
  • /i:<input inf>
  • /x
  • /u
  • /s
  • /f
  • /r:<count>
  • /w:<timeout>
  • <store path>
  • /c
  • /test

The LoadState utility also has a number of specialized command-line switches. The following list describes them.

/ix Don't use Scanstate INFs. This command-line switch lets you customize the restoration process. For example, you might only want to restore some users. You can't use this feature on a compressed data store.

/md:<mapping> Maps the user to a new domain. When the data store contains multiple domains, you specify the old domain first, followed by a colon, followed by the new domain such as /md:OldDomain:NewDomain. When you want to migrate all users to the same domain, specify only the new domain value. The old domain value can contain wildcard characters so that you can match multiple old domains, even when you don't want to match all of the domains.

/mu:<mapping> Maps the user to a new username. When the data store contains multiple users, you can match a particular user by specifying the older username first, followed by a colon, followed by the new username such as /mu:OldUser:NewUser.

/q Bypass the administrator account checks. This option lets any user load their own state information without administrator credentials. However, LoadState normally fails for other accounts since the user won't have access to them. In addition, LoadState can fail when the user has insufficient credentials to perform all tasks for their own account.

/lac[:<password>] Create local accounts in a disabled state. This command-line option lets you load state information even if the local account doesn't exist. USMT will create the account for you automatically and give the account the password you provide. You should use this option with caution since the password appears in plain text.

/lae Create local accounts in an enabled state. Use this command-line switch with /lac to enable any accounts that USMT creates automatically.

/efs:recover Recover any EFS files left in backup form. Use this option when a load fails and files remain in the backup.

/rollback Enable rollback support. This option will cost you a little extra time, but it lets you rollback a bad load. Considering migrations are seldom error proof, using this command-line switch is always a good idea when time allows.

You use the LoadState utility at the command line. In most cases, you'll use it with similar command-line switches as you used for the ScanState utility, so it pays to review the scan log. The command-line switches used for the scan always appear as the first item in the log, making it easier to retrace your steps later. Here's an example of the LoadState utility.

LoadState D:\MySettings /All /LocalOnly /V:5 /L:D:\MySettings\Scan.log \rollback

Generally, the instructions in this section are all you need to use USMT effectively on a single machine. You can find more information in the "Saving Settings with the User Setting Migration Toolkit (USMT)" section of Chapter 39. These additional instructions help you understand the complexities of an enterprise environment and work with the version of USMT that comes with the BDD.

Continue to Upgrading to Windows Vista: Performing the update installation.


Mark Minasi is a best-selling author, commentator and all-around alpha geek. Mark is best known for his books in the Mastering Windows series. What separates him from others is that he knows how to explain technical things to normal humans, and make them laugh while doing it. Mark's firm, MR&D, is based in Pungo, a town in Virginia's Tidewater area that is distinguished by having one -- and only one -- traffic light.
Copyright 2007 TechTarget

Dig Deeper on Windows client management

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.