ScanState Syntax

In this topic

  • Before you begin
  • Syntax
  • Storage options
  • Migration rule options
  • Monitoring options
  • User options
  • Encrypted file options
  • Command-line option incompatibility

Before you begin

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.

Syntax

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"

Storage options

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:

  • /key:KeyString specifies the encryption key. If there is a space in KeyString, you will need to surround it in quotes.
  • /keyfile:FilePathAndName specifies a .txt file that contains the encryption key

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.

Important
You should use extreme caution with this option because anyone that has access to the ScanState command line script will also have access to the encryption key.

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

Migration rule options

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:

  • This example creates a Config.xml file in the current directory for a destination computer running Windows Vista:
    scanstate /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13
  • This example creates a Config.xml file in the current directory for a destination computer running Windows XP:
    scanstate /targetxp /i:migsys.xml /i:migapp.xml /i:miguser.xml /genconfig:config.xml /v:13

/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:

  • With the /genconfig option to create a Config.xml file. This will optimize ScanState because the Config.xml file will only contain components that pertain to Windows XP.
  • To create a store. This will optimize ScanState because the store will only contain components that pertain to Windows XP. This will shorten the amount of time that ScanState takes.

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

Note
The data located on external USB hard disks will be migrated even when you specify /localonly.

Monitoring options

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.

OptionDescription

/l:[Path\]FileName

Specifies the location and name of the ScanState 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 the log will be created in the current directory. You can specify /v to adjust the amount of output.

If you run ScanState or LoadState from a shared network resource, you must specify this option or USMT will fail with an error "USMT was unable to create the log file(s)". To fix this issue, specify /l:scan.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.

For example:

scanstate /i:migapp.xml /i:miguser.xml \fileserver\migration\mystore /progress:prog.log /l:scanlog.log

/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)

Specifies the number of times to retry when an error occurs while saving the user state to a server. The default is three times. This option is helpful in environments where network connectivity is not fully reliable.

While storing the user state, /r will not be able to recover data that is lost due to a network hardware failure (such as a faulty or disconnected network cable) or when a virtual private network (VPN) connection fails. The retry option is intended for large, busy networks where connectivity is satisfactory, but communication latency is a problem.

/w:SecondsBeforeRetry

(Wait)

Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second.

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



The estimates are applicable for both compressed and uncompressed stores because the compressed store will always be smaller. Therefore, you can make decisions based on the estimate and then turn compression back on for the final scan.

When you run this option, ScanState uses some temporary storage on the computer to create the file. However, once ScanState is complete, the temporary space is cleared.

The Usmtsize.txt file contains a list of values—one for each cluster size. The first column of numbers is the cluster size and the second column is what the store size will be for that cluster size. The first line is the cluster used for the drive where usmtsize.txt was created. The estimate that you will want to use is the line with the cluster size matching the storage drive (for example, the cluster size of your file server). These estimates use some assumed values and may not always provide a high degree of accuracy in the estimation process.

The following example turns off compression and creates a space-estimate file:

scanstate /i:miguser.xml /i:migapp.xml \fileserver\migration\mystore /nocompress /p

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)

Enables verbose output in the ScanState log. The default is 0. You can specify any number from 0 to 15. However, USMT only uses the levels in the first table below. If you specify a number that is not in the first table, USMT follows the mapping in the second table below. USMT determines the level based on the following binary bit rules:

  • Bit 0 stands for verbose output.
  • Bit 1 is not used.
  • Bit 2 stands for status output.
  • Bit 3 stands for debugger output.
For example:

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

User options

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.

OptionDescription

/all

Migrates all of the users on the computer.

USMT migrates all user accounts on the computer, unless you specifically exclude an account with /ue or /uel. For this reason, you do not need to specify this option on the command line. However, if you choose to specify /all, you cannot also specify /ui, /ue or /uel.

/ui:DomainName\UserName

or

/ui:DomainName\"User Name"

or

/ui:LocalUserName

(User include)

Migrates the specified user(s). By default, all users are included in the migration. Therefore, this option is only helpful when used with /ue or /uel. You can specify multiple /ui options, but you cannot use /ui with /all. DomainName and UserName can contain the asterisk (*) wildcard character. When you specify a user name that contains spaces, you will need to surround it with quotes.

For example:

  • To include only User2 from the Fareast domain, type:

    /ue:\\ /ui:fareast\user2
  • To migrate all users from the Fareast domain, and only the users who have been active in the last 30 days (from any domain), type:

    /uel:30 /ui:fareast\*

    In this example, a user Farwest\User1 who had last logged in 2 months ago will not be migrated.
For more examples, see /ue, and /ui examples.

/uel:NumberOfDays

or

/uel:YYYY/MM/DD

or

/uel:0

(User exclude based on last logon)

Migrates only the users that had logged onto the source computer within the specified time period. For example, /uel:30 will only migrate users who had logged on within the last 30 days when ScanState was run. You can specify a number of days or you can specify a date. You cannot use this option with /all. USMT retrieves the last logon information from local computer. Therefore, the computer does not need to be connected to the network when you run this option. In addition, if a domain user has logged into another computer, that login time is not considered by USMT.

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.



  • /uel:0 migrates any users who are currently logged on and any users whose profiles have been loaded. For example, if domain\user1 is logged on and right-clicks an application, clicks Run As, and enters the credentials for domain\user2, then the profiles for both user1 and user2 will be loaded on the computer. If you run ScanState at this time with /uel:0, then both users will be included in the store.
  • /uel:90 migrates users who have logged on within the last 90 days.
  • /uel:1 migrates users who have logged on within the last 24 hours.
  • /uel:2002/1/15 migrates users who have logged on January 15, 2002 or afterwards.


For example:

scanstate /i:migapp.xml /i:miguser.xml \\fileserver\migration\mystore /uel:0

/ue:DomainName\UserName

or

/ue:DomainName\"User Name"

or

/ue:LocalUserName

(User exclude)

Excludes the specified user(s) from the migration. You can specify multiple /ue options. You cannot use this option with /all. DomainName and UserName can contain the asterisk (*) wildcard character. When you specify a user name that contains spaces, you will need to surround it with quotes.

For example:

scanstate /i:miguser.xml /i:migapp.xml \fileserver\migration\mystore /ue:domain1\user1

For more examples, see /ue, and /ui examples.

/ue, and /ui examples

Examples for /ui and /ue.

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*

Using the options together

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:

  • On the ScanState command line, type: /ue:* /ui:domain1\*
  • On the LoadState command line, type: /ue:* /ui:domain1\user1

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:*

Encrypted file options

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.

  • If the destination computer is running Windows Vista. In this case, EFS certificates will be migrated automatically. However, by default, USMT fails if an encrypted file is found (unless you specify an /efs option). Therefore you should specify /efs:copyraw with ScanState to migrate the encrypted file. Then when you run LoadState, the encrypted file and the EFS certificate will be automatically migrated. .
  • If the destination computer is running Windows XP and you will migrate the certificates manually. You can migrate the EFS certifications using cipher.exe. For more information, see How To Migrate EFS Files and Certificates.

For example:

ScanState /i:miguser.xml /i:migapp.xml \\fileserver\migration\mystore /efs:copyraw

Command-line option incompatibility

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.