SolutionBase: Migrating user state information in Vista

Often in large-scale Windows Vista migrations, the migration of user state data -- a user's profile -- is overlooked. In this article, Brien Posey shows you how to use version 3.0 of the User State Migration Tool.

One aspect of large-scale Windows Vista migrations that is often overlooked is the migration of user state data. User state data basically refers to a user's profile. The user state data can contain anything from documents to a user's Internet Explorer favorites list. In this article, I will show you how to use version 3.0 of the User State Migration Tool.

Before I begin

Before I get started, you may be wondering why you should consider using the User State Migration Tool rather than the File and Settings Transfer Wizard. The File and Settings Transfer Wizard works really well if you only need to migrate the contents of a few PCs, but it is not suited to an enterprise environment. In contrast, the User State Migration Tool was designed specifically for use in enterprise environments.

For the most part, the User State Migration Tool is designed to transfer the same types of files as the File and Settings Transfer Wizard. Even so, there are two primary things that set the User State Migration Tool apart from the File and Settings Transfer Wizard. First, the User State Migration Tool is command line based. This is important, because it means that you can include calls to the User State Migration Tool in a script. This makes it easy to perform large-scale migrations. Second, you can configure it so that it meets your specific needs. The configuration process involves creating INF files that tell the User State Migration Tool exactly which files and settings should be transferred.

Acquiring the User State Migration Tool

You can download version 3.0.1 of the User State Migration Tool directly from the Microsoft Web site. Keep in mind that this Web page contains two separate versions of the tool; one for x86 systems, and one for x64 systems. For the purposes of this article, I will be using the x86 version.

The installation process for the User State Migration Tool is simple. Begin by double-clicking on the file that you've downloaded. Doing so will launch the User State Migration Tool Setup Wizard. Press Next to bypass the wizard's welcome screen; you will then see a screen displaying the end user license agreement. Press Next after accepting this agreement, and you will see a message indicating that installation is ready to begin. Press Next one more time and the installation process will begin. When the installation process completes, press the Close button to close the wizard.

Migrating user state data

The User State Migration Tool isn't actually a single tool, but rather a collection of command line utilities. Of these utilities, there are two of particular interest: ScanState and LoadState. There are typically five basic steps to migrating user state data. These steps are:

  1. Decide which files and settings need to be migrated.
  2. Locate the files and settings that need to be migrated, and create a migration rule file (an XML file) that ensures that the desired files and settings are included in the migration.
  3. Use ScanState to collect the user state data and store the data in an intermediate location. Typically, ScanState is launched via a log-in script, or by using some other automated method.
  4. Install the new OS onto the target PC. Presumably, this will be Windows Vista, but the current version of the User State Migration Tool also supports Windows XP.
  5. Use the LoadState utility to transfer the collected user state data to the new OS.

Deciding which files and settings need to be migrated

Before you can decide which user state data needs to be migrated, you need to have a basic understanding of the types of data the User State Migration Tool is capable of migrating. The following list is not comprehensive, but is should give you a good idea of the tool's capabilities:

  • Accessibility options
  • Configuration information for dial-up networking
  • Desktop
  • Folder options
  • Fonts
  • Internet Explorer cookies
  • Internet Explorer favorites
  • Internet Explorer settings
  • Keyboard and Mouse configuration
  • Microsoft Office configuration settings
  • My Documents folder
  • Network drive mappings
  • Outlook Express settings and data
  • Outlook settings and data
  • Phone and modem options
  • Printer configuration
  • Regional data
  • Taskbar settings
  • The current screen saver
  • Windows sounds

Creating a migration rules file

Creating a migration rules file tends to be a fairly complicated process. That being the case, I want to use the remainder of this article to teach you the basics of using the ScanState and LoadState tools. I will cover migration rule files in another article.

Collecting user state data

The key to collecting user state data is to understand the ScanState command's syntax and its various options. I will begin by showing you the command's syntax, and will then show you a few examples of how you can use the ScanState command to collect user state data.

You can find both the ScanState and the LoadState files in the \Program Files\USMT301 folder. The syntax for using the ScanState Tool is:

ScanState <store path> [options]

As you can see above, the store path is the only piece of information that is required by the ScanState tool. When you enter the store path, you do not have to enter a filename. You only have to enter a path. For example, the command ScanState C:\USMT will place the collected data into the C:\USMT   folder, as shown in Figure A. As you can see, ScanState collects user state data for any user who has a profile stored on the computer.

Figure A

The only ScanState command's only required parameter is the store path.

When you run the ScanState utility in the manner shown above, ScanState will create a subfolder named USMT3 beneath the specified location. The collected data will be placed into this subfolder in a file named USMT3.MIG, as shown in Figure B.

Figure B

ScanState stores the collected data in the store path\USMT3\USMT3.MIG file.

The options that can be used with the ScanState command are:

  • /targetxp: This option optimizes ScanState in situations in which the target system is going to be running Windows XP. If you choose to use the /targetxp parameter, you should also use the /genconfig option, which I will discuss in a moment.
  • /genconfig:FileName: This option is designed to produce an XML based configuration file, similar to the files that I will be discussing in Part 2. It is important to point out that the only optional parameters that /genconfig can be used in conjunction with are /I, /v, /l, and /targetxp.
  • /o: This option tells ScanState to overwrite any existing data found in the store path.
  • /p: The size of the USMT3.MIG file varies widely depending on the size of the user's profile and the number of documents stored on the machine. The /P option causes ScanState to produce a space-estimate file called USMTSIZE.TXT. You must use the /NOCOMPRESS option when using this parameter.
  • /localonly: This option specifies that only files that are stored on the local computer will be migrated.
  • /efs:abort|skip|decryptcopy|copyraw: This option tells ScanState how to deal with any encrypted files that it may encounter. If the Abort option is specified, then the command will fail if encrypted files are detected. If the Skip option is used, then encrypted files will be skipped. The Decryptcopy option decrypts encrypted files prior to copying them. The CopyRaw file copies encrypted files as they are. Keep in mind that encrypted files cannot be opened on the target systems unless the user's keys are also copied.
  • /encrypt: The /Encrypt option causes the store file to be encrypted. This command must be used in conjunction with the /key or /keyfile switches.
  • /key:KeyString: This parameter allows you to specify an encryption key.
  • /keyfile:FileName: This parameter allows you to specify the name and path of a text file that contains an encryption key.
  • /nocompress: This option tells ScanState not to compress the store file.
  • /l:FileName: This parameter allows you to specify that ScanState should create a log of the collection process.
  • /v:Level: You can use this option to specify the level of verboseness in the ScanState log. The default logging level is 0, but you can specify a level of 0, 1, 4, 5, 8, 9, 12, or 13.
  • /progress:FileName: This parameter allows you to specifies the path and filename of an optional progress log.
  • /c: The /C switch tells ScanState that it should continue to run in the event of a non-fatal error.
  • /r:TimesToRetry: This switch allows you to tell ScanState how many times to retry a failed operation when a non-fatal occurs. If you do not use this switch, then ScanState will retry failed operations three times.
  • /w:SecondsToWait: This switch allows you to control how long ScanState will wait prior to retrying a failed operation. If you omit this switch, then the default retry interval is one second.
  • /all: If multiple user profiles exist on a system, then this switch can be used to tell ScanState to migrate all the users.
  • /ui:[Domain\]UserName: This command parameter tells ScanState to migrate only the specified user or users. The command supports the use of local or domain users, and also supports the use of wildcard characters (* and ?).
  • /ue:[Domain\]UserName: This parameter allows you to omit one or more user accounts. Again, this command works with domain or local user accounts, and also supports the use of wildcard characters.
  • /uel:NumberOfDays|YYYY/MM/DD: You can use this parameter to exclude old user accounts that are no longer in use. For example, you could choose to omit user accounts that have not been used in the last year.
  • /i:FileName: As I mentioned earlier, you can use an XML file to control specifically which files and settings will be migrated. You can use this switch to specify the name of your XML file.
  • /?: You can enter SCANSTATE /? To view the command syntax.
  • /config:FileName: This option specifies the Config.xml file that ScanState should use.

Those are the command line switches in a nutshell. If you need more information, then be sure to check out the USMT.chm file.

Using the LoadState utility to deploy the collected information

Like the ScanState Command, the LoadState Command only has a single required parameter: the store path. There are, however, many additional options that you can use with the LoadState command. Some of these options have limited usefulness, but others are worth taking a look at. Since a lot of the command line parameters are identical to the ones that are used by ScanState, I will only be covering the ones that are unique to LoadState.

The options that are available for use with the LoadState command are as follows:

  • /lac[:Password]: This parameter can be used to create local user accounts if they do not already exist on the target computer. If this switch is used, then the accounts are disabled by default, and the password will be blank by default. In the parameter's syntax above, Password is listed in the brackets. You can replace the word Password with your desired default password.
  • /lae: You can use this switch in conjunction with the /LAC parameter. Doing so enables local user accounts.

  • /q: This parameter allows LoadState to run without administrative credentials.

  • /mu:[OldDomain\]OldUserName:[NewDomain\]NewUserName: This parameter allows you to rename a user account. Simply provide the user's old name and their new name.

  • /md:OldDomain:NewDomain: You can use this parameter to specify a new domain for existing user accounts. Simply provide the old domain name and the new domain name.

  • /decrypt: You must use this parameter when the store has been encrypted by ScanState. If the store needs to be decrypted, you must also use the /key or the /keyfile parameter to provide an encryption key.