ScanState Syntax
- Before you begin
- Syntax
- Storage options
- Migration rule options
- Monitoring options
- User options
- Encrypted file options
- Command-line option incompatibility
Before you run ScanState, note the following:
- When running ScanState and LoadState on Windows Vista, you need to run the tools in “Administrator” mode from an account with administrative credentials to ensure that all specified users are migrated. This is because User Access Control (UAC) is turned on in Windows Vista. To run in this mode, click Start, click All Programs, click Accessories, right-click Command Prompt, click Run as administrator, and then specify your LoadState or ScanState command. If you do not run USMT in “Administrator” mode, only the user profile that is logged on will be included in the migration.
- You must run ScanState on Windows XP from an account with administrative credentials, or some operating system settings may not migrate — for example, wallpaper settings, screen saver selections, modem options, media player settings, and Remote Access Service (RAS) connection phone book(.pbk) files and settings. For this reason, we recommend that you run ScanState (and LoadState) from within an account with administrative credentials.
- Unless otherwise specified, you can only specify each option once on the command line.
- The Command-line option incompatibility diagram shows which options you can use together.
This section explains the syntax and usage of the ScanState command-line options. The options can be specified in any order. If the option contains a parameter, you can specify either a colon or space separator.
The ScanState syntax is:
scanstate [StorePath] [/i:[Path\]FileName] [/o] [/v:VerbosityLevel] [/nocompress] [/localonly] [/encrypt /key:KeyString|/keyfile:[Path\]FileName] [/l:[Path\]FileName] [/progress:[Path\]FileName] [/r:TimesToRetry] [/w:SecondsBeforeRetry] [/c] [/p] [/all] [/ui:[DomainName\]UserName]|LocalUserName] [/ue:[DomainName\]UserName]|LocalUserName] [/uel:NumberOfDays|YYYY/MM/DD|0] [/efs:abort|skip|decryptcopy|copyraw] [/genconfig:[Path\]FileName] [/targetxp] [/config:[Path\]FileName] [/?|help]
For example:
For destination computers running Windows Vista:
- To create a Config.xml file in the current directory (does not create a store), specify:
scanstate /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13 - To create an encrypted store using Config.xml and the default migration .xml files, specify:
scanstate \\fileserver\migration\mystore /i:migapp.xml /i:miguser.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"
For destination computers running Windows XP:
- To create a Config.xml file in the current directory (does not create a store), specify:
scanstate /targetxp /i:migsys.xml /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13 - To create an encrypted store using Config.xml and the default migration .xml files, specify:
scanstate \\fileserver\migration\mystore /targetxp /i:migsys.xml /i:migapp.xml /i:miguser.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"
Option | Description | ||
---|---|---|---|
StorePath |
Indicates a folder where to save the files and settings (for example, StorePath cannot be c:\). You must specify StorePath on the ScanState command line except when using the /genconfig option. You cannot specify more than one StorePath. |
||
/o |
Overwrites any existing data in the store. If not specified, ScanState will fail if the store already contains data. You cannot specify this option more than once on a command line. |
||
/encrypt /key:KeyString or /encrypt /key:"Key String" or /encrypt /keyfile:[Path\]FileName |
Encrypts the store with the specified key (password). Encryption is disabled by default. With this option, you will need to specify the encryption key with one of the following ways:
We recommend that KeyString be at least 8 characters long, but it cannot exceed 256 characters. /key and /keyfile cannot be used on the same command line. /encrypt and /nocompress cannot be used on the same command line.
For example: scanstate /i:miguser.xml /i:migapp.xml \\fileserver\migration\mystore /encrypt /key:mykey |
||
/nocompress |
Disables compression of data and saves the files to a hidden folder named "File" at StorePath\USMT3. Compression is enabled by default. You can use the uncompressed store to view what USMT stored, troubleshoot a problem or you can run an antivirus utility against the files. You should only use this option in testing environments because we recommend that you use a compressed store during your actual migration. /nocompress and /encrypt can not be used on the same command line. However, if you do choose to migrate an uncompressed store, LoadState will migrate each file directly from the store to the correct location on the destination computer — without a temporary location. For example: scanstate /i:miguser.xml /i:migapp.xml \\fileserver\migration\mystore /nocompress |
USMT provides the following option that you can use to specify what you want to migrate.
Option | Description | ||
---|---|---|---|
/i:[Path\]FileName |
(include) Specifies an .xml file that contains rules that define what state to migrate. You can specify this option multiple times in order to specify all of your .xml files (MigApp.xml, MigSys.xml, MigUser.xml and any custom .xml files that you create). Path can be a relative or full path. If you do not specify Path, then FileName must be located in the current directory. For more information about which files to specify, see the "xml files" section of the Frequently Asked Questions topic. |
||
/genconfig:[Path\]FileName |
(Generate Config.xml) Generates the optional Config.xml file, but does not create a store. To ensure that this file contains every component, application, and setting that can be migrated, you should create this file on a source computer that contains all the components, applications and settings that will be present on the destination computers. And in addition, you should specify the other (possibly modified) migration .xml files using /i when you specify this option. After you create this file, you will need to specify it on the ScanState command line using the /config option. The only options that you can specify with this option are /i, /v, /l, and /targetxp. You cannot specify StorePath because this option does not create a store. Path can be a relative or full path. If you do not specify Path, then FileName will be created in the current directory. Examples:
|
||
/config:[Path\]FileName |
Specifies the Config.xml file that ScanState should use to create the store. You cannot specify this option more than once on the command line. Path can be a relative or full path. If you do not specify Path, then FileName must be located in the current directory. This example creates a store using the Config.xml file, MigUser.xml, and MigApp: scanstate \\fileserver\migration\mystore /config:config.xml /i:miguser.xml /i:migapp.xml /v:13 /l:scan.log This example migrates the files and settings to the destination computer using Config.xml, MigUser.xml, and MigApp: loadstate \\fileserver\migration\mystore /config:config.xml /i:miguser.xml /i:migapp.xml /v:13 /l:load.log |
||
/targetxp |
Optimizes ScanState when the destination computer is running Windows XP. You should use this option in the following situations:
|
||
/localonly |
Migrates only files that are stored on the local computer, regardless of the rules in the .xml files that you specify on the command line. You should use this option when you want to exclude the data from external drives on the source computer (USB flash drives, external hard drives, and so on) and when there are network drives mapped on the source computer. If /localonly is not specified, then ScanState will copy files from these drives into the store.
|
USMT provides several options that you can use to analyze problems that occur during migration.
Note
The ScanState log is created by default, but you can specify the name and location of the log with the /l option.
Option | Description |
---|---|
/l:[Path\]FileName |
Specifies the location and name of the ScanState log.
|
/progress:[Path\]FileName |
Creates the optional progress log. You cannot store any of the log files in StorePath. Path can be a relative or full path. If you do not specify Path, then FileName will be created in the current directory.
|
/c |
When specified, ScanState will continue to run even if there are nonfatal errors. Without the /c option, ScanState exits on the first error. When you specify this option, any files or settings that cause an error and are ignored will be logged in the progress log. For example, if there is a large file that will not fit in the store, ScanState will log an error and will continue with the migration. In addition, if a file is open or in use by an application, USMT may not be able to migrate the file and will log an error. |
/r:TimesToRetry |
(Retry)
|
/w:SecondsBeforeRetry |
(Wait)
|
/p |
Generates a space-estimate file called Usmtsize.txt that is saved to StorePath. This option does not collect the user state. You must also specify /nocompress. Important Except when migrating from x86-based computers running Windows XP, this estimate is often twice as large as the actual disk space needed on the destination computer. In these scenarios, you should take this issue into account when reviewing the estimates.
Note With Windows 2000, Convert.exe will convert the partition to a 512-byte cluster size. With Windows XP, Convert.exe will determine the best cluster size and will then (in most cases) convert the partition to a 4096-byte cluster size. The Chkdsk.exe command does not use cluster size terminology, but uses the word allocation unit instead. The Defrag.exe report uses cluster size term. |
/v:VerbosityLevel |
(Verbosity)
scanstate \\fileserver\migration\mystore /v:13 /i:miguser.xml /i:migapp.xml loadstate \\fileserver\migration\mystore /v:13 /i:miguser.xml /i:migapp.xml |
VerbosityLevel can be one of the following levels:
Level | Binary Value | Explanation |
---|---|---|
0 |
0000 |
Only the default errors and warnings are enabled. |
1 |
0001 |
Enables verbose output. |
4 |
0100 |
Enables error and status output. |
5 |
0101 |
Enables verbose and status output. |
8 |
1000 |
Enables error output to a debugger. |
9 |
1001 |
Enables verbose output to a debugger. |
12 |
1100 |
Enables error and status output to a debugger. |
13 |
1101 |
Enables verbose, status, and debugger output. |
If you specify 2, 3, 6, 7, 10, 11, 14, or 15, USMT uses the following mapping to determine VerbosityLevel.
Specified Level | Binary Value | Implied Level |
---|---|---|
2 |
0010 |
0 |
3 |
0011 |
1 |
6 |
0110 |
4 |
7 |
0111 |
5 |
10 |
1010 |
8 |
11 |
1011 |
9 |
14 |
1110 |
12 |
15 |
1111 |
13 |
By default all users are migrated. The only way to specify which users to include and exclude is by using the following options. You cannot exclude users in the migration .xml files or using Config.xml. For more information, see Identify Users and How To Migrate User Accounts.
Option | Description |
---|---|
/all |
Migrates all of the users on the computer.
|
/ui:DomainName\UserName
|
(User include)
|
/uel:NumberOfDays
|
(User exclude based on last logon)
Note USMT excludes users based on the state of the computer when ScanState was run. For example, if a user logs onto the source computer after ScanState is run but before LoadState is run, the logon will not be considered in this option.
For example: scanstate /i:migapp.xml /i:miguser.xml \\fileserver\migration\mystore /uel:0 |
/ue:DomainName\UserName
|
(User exclude)
|
The following examples apply to both /ui and /ue. That is, you can replace /ue with /ui to specify to exclude rather than include the specified users.
Behavior | Command |
---|---|
Exclude the user named User One in the Fareast domain. |
/ue:fareast\"user one" |
Exclude the user named User1 in the Fareast domain. |
/ue:fareast\user1 |
Exclude the local user named User1. |
/ue:user1 |
Exclude all local and domain users. |
/ue:*\* |
Exclude all local users. |
/ue:* |
Exclude users in all domains named User1, User2, and so on. |
/ue:*\user* |
You can use /uel, /ue, and /ui together in order to migrate only the users that you want migrated. However, if a user is specified with /ui, and also specified to exclude with either /ue or /uel, the user will be included in the migration. For example, if you specify /ui:domain1\* /ue:domain1\user1, then User1 will be migrated because /ui takes precedence.
Behavior | Command |
---|---|
Include only User2 from the Fareast domain and exclude all other users. |
/ue:*\* /ui:fareast\user2 |
Include only the local user named User1 and exclude all other users. |
/ue:*\* /ui:user1 |
Include only the domain users from Domain1, except Domain1\User1. |
This behavior cannot be completed using a single command. Instead, to migrate this set of users, you will need to specify the following:
|
Include only local (non-domain) users. |
/ue:*\* /ui:* |
Include only domain users who have logged on in the last 90 days, and only domain users. |
/uel:90 /ue:* |
You can use the following options to migrate encrypted files. In all cases, by default, USMT fails if an encrypted file is found unless you specify an /efs option. In order to migrate encrypted files, you must change the default behavior.
For more information, see How To Migrate EFS Files and Certificates.
Note
EFS certificates will be migrated automatically when migrating to Windows Vista. Therefore, you should specify the /efs:copyraw option on the ScanState command line to migrate the encrypted files
Warning
You should take extreme caution when migrating encrypted files. If you migrate an encrypted file without also migrating the certificate, end users will not be able to access the file after the migration.
Option | Explanation |
---|---|
/efs:abort |
Causes ScanState to fail with an error code if an Encrypting File System (EFS) file is found on the source computer. Enabled by default. |
/efs:skip |
Causes ScanState to ignore EFS files completely. |
/efs:decryptcopy |
Causes ScanState to decrypt the file if possible before saving it to the store, and to fail if the file cannot be decrypted. If ScanState succeeds, the file will be unencrypted in the store, and once you run LoadState, the file will be copied to the destination computer. |
/efs:copyraw |
Causes ScanState to copy the files in the encrypted format. The files will be inaccessible on the destination computer until the EFS certificates are migrated. If you use this option, ensure that the certificates will be migrated. You should only use this option in the following two situations.
For example: ScanState /i:miguser.xml /i:migapp.xml \\fileserver\migration\mystore /efs:copyraw |
The following tables indicate which command-line options are not compatible on the ScanState command line. If the table entry for a particular combination is blank, the options are compatible and you can use them together. The X symbol means that the options are not compatible. For example, you cannot use the /nocompress option with the /encrypt option.
Note
You must specify either /key or /keyfile with /encrypt.