3. Gathering Data by Running ScanState
The ScanState command captures the user
state data. It includes several options that you can use by including
different switches. The basic syntax of the ScanState command is:
ScanState <store path> [switches]
The store path is the location where you want the
migrated data stored. It can be a network location using a UNC path or
an external hard drive accessible to the source computer. You can also
specify a path on the local hard drive if desired.
You have several switches available to you when running ScanState. Table 1 shows some of the common switches associated with the following typical ScanState command.
c:\usmt>ScanState C:\USMTStore /i:migdocs.xml /i:migapp.xml /v:5
/l:MyScanState.log /o /c
Notice that this this command is issued from the C:\USMT> prompt, indicating the path has been changed to C:\USMT with the cd \usmt
command. It assumes that the appropriate USMT files (x86 for a 32-bit
source system, or amd64 for a 64-bit source system) have been copied to
the C:\USMT folder.
Table 1. Common ScanState switches
| Switch | Description |
|---|
/i:<file name>
/i:c:\usmt\migdocs.xml
/i:c:\usmt\migapp.xml
| You use the /i switch to specify the path and XML filenames that include the rules for migration. It's common to use the MigDocs.xml and MigApp.xml files for the migration. These files include rules that will locate user data and application data. |
/v:<level>
/v:5
| The /v
switch enables verbose output in the log file. The default verbosity
level is 0 and the highest is 13. You can use 0, 1, 4, 5, 8, 9, 12, or
13. Any level beyond 5 requires the use of a debugger to fully analyze
the output. |
/l:<log file name>
/l:MyScanState.log
| The /1 switch specifies the location and name of the log file. |
/o
| Overwrites any existing migration store. |
/c
| Indicates to continue even if there are nonfatal errors. If this switch is not used, ScanState will stop and exit for any error. |
The previous command is executed from the C:\USMT
folder and the XML files are located in the same folder so their path
doesn't need to be included. However, if you execute the command from a
different path, you'll have to include the path to the XML files. For
example, if the ScanState command and XML files are in a folder named USMT, and you're executing the command from the root of C: (C:\>), you'd need to use a command like this:
C:\>c:\USMT\ScanState C:\USMTStore /i:c:\usmt\migdocs.xml
/i:c:\usmt\migapp.xml /v:5 /l:MyScanState.log
3.1. Using the /auto Switch
You can also use the /auto switch to specify the location of the XML files. The /auto switch sets the verbosity to level 13. Here's an example using this switch; Table 2 explains the switches used here.
C:\>c:\usmt\scanstate /auto:c:\usmt\ c:\USMTStore /l:myscanstate.1og
Table 2. ScanState/auto switch
| Switch | Description |
|---|
| /auto | Using the /auto
switch without a directory path causes it to set the directory path to
the location where the USMT files are installed (if they were installed
rather than just copied).
The /auto switch selects all users. You can't use the /ui or /ue switches to select specific users when using the /auto switch. |
| /auto:c:\usmt | If you specify a path with the /auto switch, it will use this path to locate and use the MigDocs.xml and MigApp.xml files. |
3.2. Creating XML Files
The following two example commands show how you can create a Config.xml file and a general migration XML file. These are optional files, but you can use them to create a template Config.xml file, and to gain insight into what files ScanState will capture. Table 3 describes the use of these switches.
C:\>c:\usmt\scanstate /genmigxml:mygenmig.xml
C:\>c:\usmt\scanstate /genconfig:myconfig.xml
Table 3. ScanState switches to create XML files
| Switch | Description |
|---|
/genmigxml:<path>
/genmigxml:mygenmig.xml
| This switch
causes ScanState to search the system to locate files that will be
migrated. It then creates the XML file identifying and defining how all
the files are migrated. This command doesn't actually create the
migration store, but instead provides you with a preview of what will be
migrated. |
/genconfig:<path>
/genconfig:mygenconfig.xml
| This switch creates a Config.xml file that you can modify and then use with the /config switch. |
3.3. Identifying Users to Migrate
By default all users are migrated, but you can pick specific users to migrate with the user include (/ui) switch, or pick specific users to exclude with the user exclude (/ue)
switch. For example, the following command (which is shown on multiple
lines but is entered on a single line) will exclude all domain and local
users except the local user named TestUser:
C:\>c:\usmt\scanstate c:\USMTStore
/i:c:\usmt\migdocs.xm1 /i:c:\usmt\migapp.xm1 /v:5 /l:myscanstate.1og
/ue:*\* /ui:TestUser
This second example only migrates users who have
logged on in the past 30 days. It should also be entered on a single
line but is shown on multiple lines here:
C:\>c:\usmt\scanstate c:\USMTStore
/i:c:\usmt\migdocs.xm1 /i:c:\usmt\migapp.xm1 /v:5 /l:myscanstate.1og
/ue1:30
Table 4 shows some of the switches you can use to identify which users to migrate.
Table 4. ScanState switches to migrate users
| Switch | Description |
|---|
/all
| Migrates all the users on the system. This is the default so the switch isn't needed. |
/ue:[Domain\]UserName
/ue:Darri1
/ue:Mastering\Darri1
/ue:Mastering\*
/ue:*\*
| Excludes specified users. To exclude a local user, specify the UserName parameter only. If you want to exclude a user in a domain (such as the Mastering.hme
domain), enter the domain name and the username. You can use the*
wildcard character to exclude all domain users or all local users. This
is needed when you're using the /ui switch. |
/ui:[Domain\]UserName
/ue:*\* /ui:Mastering\
Darri1
/ue:*\* /ui:Darri1
| If you only want to migrate specific users, you can exclude all of them with the /ue switch (/ue:*\*) and then use the user include (/ui) switch to specify which users to migrate. To migrate a local user, specify the UserName parameter only. The Domain and UserName parameters can contain wildcard characters (* or ?). |
/ue1:NumberOfDays
/ue1:30
/ue1:yyyy/mm/dd
/ue1:2010/09/10
| You can use the /uel
switch to only include users based on their last logon. For example, if
you only want to migrate users who have logged on the past 30 days, you
can use /ue1:30 and users that logged on 31 or more days ago
will not be migrated. You can also specify a date and only users who
have not logged on since that date will be excluded. |
3.4. Encrypting the Migration Store
The data in the migration store may be valuable and
may need extra protection to ensure its confidentiality. You can use
several methods of encryption to protect the data. The following command
will encrypt the store using the default encryption method with a
password key of P@ssw0rd. The switches are explained in Table 5.
C:\>c:\usmt\scanstate /auto:c:\usmt\ c:\USMTStore
/l:myscanstate.1og /encrypt /key:P@ssw0rd
Table 5. ScanState encryption switches
| Switch | Description |
|---|
/encrypt
/encrypt:<method>
AES | AES_128 | AES_192 |
AES_256 | 3DES | 3DES_112
| Encrypts the
migration store using the specified cryptographic algorithm. The default
value is 3DES but the AES methods are considered stronger and more
efficient.
You must also specify the /key or /keyfile option when encrypting the store. |
/key:KeyString
/key:"my P@ssw0rd"
| Specifies the encryption key. If the encryption key has a space, it needs to be enclosed in quotes. |
/keyfile:FileName
| Specifies the location and name of a TXT file containing the encryption key. |
|
USMT version 4.0 is included with the WAIK for
Windows 7 and it supports multiple encryption algorithms, including the
Advanced Encryption Standard (AES) 128, 192, and 256 bits. However,
there are some scenarios when the source system does not support all
these methods. The Usmtutils.exe file is stored in the same
folder as the ScanState and LoadState tools, and you can use it to list
the encryption options supported by USMT tools. The command is as
follows:
usmtutils /ec
You'll see an output similar to this:
Following is a list of USMT supported Crypto AlgIDs available on this system:
3DES_112
3DES
AES_128
AES_192
AES_256
On some Windows XP systems, you may only see the 3DES_112 and 3DES encryption algorithms.
|
3.5. Creating a Hard-Link Migration Store
If you are doing a refresh and you want to do a hard-link migration, you can use the following command:
C:\>c:\usmt\scanstate /auto:c:\usmt\ /hardlink c:\HardLinkStore /1:myscanstate.
log /nocompress
Table 6 shows the switches used with the /hardlink option. Notice that you must use the /nocompress switch when using the /hardlink switch.
Table 6. ScanState /hardlink and /nocompress switches
| Switch | Description |
|---|
| /hardlink | Enables hard links for a noncompressed store. Use only for PC refresh scenarios. Requires /nocompress. |
| /nocompress | Specifies that the migration store is not compressed. |
3.6. Identifying Users and Files That Will Be Migrated
You can run ScanState at the command prompt
to generate a log file that will let you know what the USMT will
migrate. Note that this will not actually create the migration store,
but instead generates an XML file that you can explore to identify the
files that will be migrated. The following example assumes that the USMT
files were copied to a folder named C:\USMT on a 32-bit system:
C:\>c:\usmt\scanstate /genmigxm1:c:\usmt\my1ogfi1e.xm1
Log messages are being sent to 'C:\scanstate.log'
Starting the migration process
Success.
ScanState return code: 0
After running this command, there are two important files you can view. First, the Mylogfile.xml file gives you insight into what will be migrated. For example, it will have some <inc1ude>; nodes within the XML document that look something like this:
<inc1ude>
<objectSet>
<pattern type="File">c:\down1oads\*[*]</pattern>
<pattern type="File">c:\usmt test fo1der\*[*]</pattern>
<pattern type="File">c:[scanstate.1og]</pattern>
</objectSet>
</inc1ude>
These include nodes are letting you know that it discovered some non-Windows folders (C:\ downloads and C:\usmt test folder)
and it will include all subfolders (using the * wildcard) and all files
(using the [*] wildcard). Additionally, it will include the Scanstate.log file in the migration.
If you scroll through the file further, you'll see
which user profiles will be included in the migration along with a
listing of the folders within these profiles. This data is generated
from the MigXmlHelper.GenerateDocPatterns function of USMT. For
example, if you created a TestUser account, you'll see a component
section identifying the user with a node similar to this:
<component type="Documents" context="XP1\TestUser" defau1tSupported="Yes">
...
</component>
The data within the <component> node
also identifies the folders that are associated with the user in the
user profile. These folders are included in the migration.
You can also look at the C:\Scanstate.log file. It shows the progress of the ScanState command and includes a list of user accounts that will be migrated.
3.7. Migrating Files Encrypted with EFS
If any of the migrated files are encrypted with the NTFS encrypting file system (EFS), you need to specify the /efs switch. If EFS encrypted files are detected during the migration, but the /efs switch is not used, the migration will fail. Table 7 shows the available options with the /efs switch and the following command shows the typical usage:
C:\>c:\usmt\scanstate /auto:c:\usmt\ c:\USMTStore
/l:myscanstate.log /efs:copyraw
Table 7. ScanState/efs switches
| Switch | Description |
|---|
| /efs:hardlink | Creates a hard link to the EFS file instead of copying it. This is used when the /hardlink and /nocompress options are used. |
| /efs:abort | This is the default. It will cause ScanState to fail if an EFS encrypted file is detected. |
| /efs:skip | Ignores EFS files. |
| /efs:decryptcopy | Attempts to decrypt the file. If successful, the file is migrated in an unencrypted format. |
| /efs:copyraw | Copies
the encrypted file. LoadState will migrate user certificates, if
available, so that users will be able to access encrypted files after
the migration is completed. |
3.8. Running ScanState to Create the Migration Store
If you've copied the appropriate USMT folders and
files onto the source computer, you can use the following steps to see
how ScanState is used. These steps will lead you through creating a test
account and test folder prior to capturing the user state data. The
steps assume you've copied the contents of the USMT folder to a folder
named C:\USMT.
Use
the following steps to create a test account, a profile, and some test
documents. You can use this data to observe the steps of the migration.
Launch a command prompt and enter the following command to add a user:
net user /add TestUser P@ssw0rd
Log off the system and then log onto the TestUser account using P@ssw0rd as the password. This will create the profile.
Open Windows Explorer and browse to My Documents. Right-click within the folder and create a new text document. Name it USMT Test.
Browse to the root of C:. Create a folder named USMT Test Folder. Open the folder and create a new text document named USMT Test 2.
Log off the TestUser account.
Log on to the Windows XP system using an account with administrative permissions.
Launch the command prompt. Execute the following command to create an XML file named mygenmig.xml:
c:\usmt\scanstate /genmigxm1:mygenmig.xm1
Open Windows Explorer and browse to the root of C:. Open the file named mygenmig.xml. Browse through this file to identify which files and users will be included in the migration.
Return to the command prompt and execute the following command:
c:\usmt\scanstate /auto:c:\usmt\ c:\USMTStore /l:myscanstate.1og
When the command completes, it will indicate success.
You'll see an output similar to the following text, identifying the
names of the user accounts that are migrated:
Log messages are being sent to 'C:\myscanstate.1og'
Starting the migration process
Processing the settings store
Examining the system to discover the migration units
XP1\Administrator (1 of 4): 100% done
XP1\TestUser (2 of 4): 100% done
XP1\Sa11y (3 of 4): 100% done
This Computer (4 of 4): 100% done
Se1ecting migration units
Gathering data
XP1\Administrator (1 of 4): 100% done
XP1\TestUser (2 of 4): 100% done
XP1\Sa11y (3 of 4): 100% done
This Computer (4 of 4): 100% done
Commit
Success.
ScanState return code: 0
At this point, the C:\usmtstore\ folder will
include the user state data from this command. You can copy it to a
network share, an external drive, or a USB flash drive. You can later
use the LoadState command to apply the data to the new operating system.
