ScanState Syntax
Applies To: Windows 7, Windows 8, Windows 8.1, Windows Vista
The ScanState command is used with the User State Migration Tool (USMT) 5.0 to scan the source computer, collect the files and settings, and create a store.
In This Topic
Before You Begin
Syntax
Storage Options
Migration Rule Options
Monitoring Options
User Options
Encrypted File Options
Incompatible Command-Line Options
Before You Begin
Before you run the ScanState command, note the following:
To ensure that all operating system settings migrate, in most cases you must run the ScanState commands in administrator mode from an account with administrative credentials.
If you encrypt the migration store, you will be required to enter an encryption key or a path to a file containing the encryption key. Be sure to make note of the key or the key file location, because this information is not kept anywhere in the migration store. You will need this information when you run the LoadState command to decrypt the migration store, or if you need to run the recovery utility. An incorrect or missing key or key file results in an error message.
For information about software requirements for running the ScanState command, see USMT Requirements.
Important
Windows XP and Windows Vista® are supported only as operating systems on the source computer.
Unless otherwise noted, you can use each option only once when running a tool on the command line.
You can gather domain accounts without the source computer having domain controller access. This functionality is available without any additional configuration.
The Incompatible Command-Line Options table lists which options you can use together and which command-line options are incompatible.
The directory location where you save the migration store will be excluded from the scan. For example, if you save the migration store to the root of the D drive, the D drive and all of its subdirectories will be excluded from the scan.
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 use either a colon or a space separator.
The ScanState command's 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|ComputerName\]UserName] [/ue:[DomainName|ComputerName\]UserName] [/uel:NumberOfDays|YYYY/MM/DD|0] [/efs:abort|skip|decryptcopy|copyraw] [/genconfig:[Path\]FileName[/config:[Path\]FileName] [/?|help]
For example:
To create a Config.xml file in the current directory, use:
scanstate /i:migapp.xml /i:migdocs.xml /genconfig:config.xml /v:13To create an encrypted store using the Config.xml file and the default migration .xml files, use:
scanstate \\server\share\migration\mystore /i:migapp.xml /i:migdocs.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"
Storage Options
| Command-Line Option | Description |
|---|---|
StorePath |
Indicates a folder where files and settings will be saved. Note that StorePath cannot be c:\. You must specify the StorePath option in the ScanState command, except when using the /genconfig option. You cannot specify more than one StorePath location. |
/o |
Required to overwrite any existing data in the migration store or Config.xml file. If not specified, the ScanState command will fail if the migration store already contains data. You cannot use this option more than once on a command line. |
/vsc |
This option enables the volume shadow-copy service to migrate files that are locked or in use. This command-line option eliminates most file-locking errors that are typically encountered by the <ErrorControl> section. This option can be used only with the ScanState executable file and cannot be combined with the /hardlink option. |
/hardlink |
Enables the creation of a hard-link migration store at the specified location. The /nocompress option must be specified with the /hardlink option. |
/encrypt [{/key:<KeyString> | /keyfile:<file>]} |
Encrypts the store with the specified key. Encryption is disabled by default. With this option, you will need to specify the encryption key in one of the following ways:
We recommend that KeyString be at least eight characters long, but it cannot exceed 256 characters. The /key and /keyfile options cannot be used on the same command line. The /encrypt and /nocompress options cannot be used on the same command line. > [!IMPORTANT] > You should use caution with this option, because anyone who has access to the ScanState command-line script will also have access to the encryption key. >The following example shows the ScanState command and the /key option:
|
/encrypt:<EncryptionStrength> |
The /encrypt option accepts a command-line parameter to define the encryption strength to be used for encryption of the migration store. For more information about supported encryption algorithms, see Migration Store Encryption. |
/nocompress |
Disables compression of data and saves the files to a hidden folder named "File" at StorePath\USMT. Compression is enabled by default. Combining the /nocompress option with the /hardlink option generates a hard-link migration store. You can use the uncompressed store to view what USMT stored, troubleshoot a problem, or run an antivirus utility against the files. You should use this option only in testing environments, because we recommend that you use a compressed store during your actual migration, unless you are combining the /nocompress option with the /hardlink option. The /nocompress and /encrypt options cannot be used together in one statement on the command line. However, if you do choose to migrate an uncompressed store, the LoadState command will migrate each file directly from the store to the correct location on the destination computer without a temporary location. For example:
|
Run the ScanState Command on an Offline Windows System
You can run the ScanState command in Windows PE. In addition, USMT supports migrations from previous installations of Windows contained in Windows.old directories. The offline directory can be a Windows directory when you run the ScanState command in Windows PE or a Windows.old directory when you run the ScanState command in Windows.
There are several benefits to running the ScanState command on an offline Windows image, including:
Improved performance.
Because Windows PE is a thin operating system, there are fewer running services. In this environment, the ScanState command has more access to the local hardware resources, enabling ScanState to perform migration operations more quickly.
Simplified end-to-end deployment process.
Migrating data from Windows.old simplifies the end-to-end deployment process by enabling the migration process to occur after the new operating system is installed.
Improved success of migration.
The migration success rate is increased because files will not be locked for editing while offline, and because Windows PE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system.
Ability to recover an unbootable computer.
It might be possible to recover and migrate data from an unbootable computer.
Offline Migration Options
| Command-Line Option | Definition |
|---|---|
/offline: "path to an offline.xml file" |
This option is used to define a path to an offline .xml file that might specify other offline migration options, for example, an offline Windows directory or any domain or folder redirection required in your migration. |
/offlinewindir: "path to a Windows directory" |
This option specifies the offline Windows directory that the ScanState command gathers user state from. The offline directory can be Windows.old when you run the ScanState command in Windows or a Windows directory when you run the ScanState command in Windows PE. |
/offlinewinold: "Windows.old directory" |
This command-line option enables the offline migration mode and starts the migration from the location specified. It is only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory. |
Migration Rule Options
USMT provides the following options to specify what files you want to migrate.
| Command-Line Option | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
/i:[Path\]FileName |
(include) Specifies an .xml file that contains rules that define what user, application or system state to migrate. You can specify this option multiple times to include all of your .xml files (MigApp.xml, MigDocs.xml, and any custom .xml files that you create). Path can be either a relative or full path. If you do not specify the Path variable, 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 migration 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. In addition, you should specify the other migration .xml files, using the /i option, when you specify this option. After you create this file, you will need to make use of it with the ScanState command using the /config option. The only options that you can specify with this option are the /i, /v, and /l options. You cannot specify StorePath, because the /genconfig option does not create a store. Path can be either a relative or full path. If you do not specify the Path variable, then FileName will be created in the current directory. Examples:
|
||||||||
/config:[Path\]FileName |
Specifies the Config.xml file that the ScanState command should use to create the store. You cannot use this option more than once on the command line. Path can be either a relative or full path. If you do not specify the Path variable, then FileName must be located in the current directory. The following example creates a store using the Config.xml file, MigDocs.xml, and MigApp.xml files:
The following example migrates the files and settings to the destination computer using the Config.xml, MigDocs.xml, and MigApp.xml files:
|
||||||||
/auto: path to script files |
This option enables you to specify the location of the default .xml files and then begin the migration. If no path is specified, USMT will reference the directory where the USMT binaries are located. The /auto option has the same effect as using the following options: /i:MigDocs.xml/i:MigApp.xml /v:5. |
||||||||
/genmigxml: path to a file |
This option specifies that the ScanState command should use the document finder to create and export an .xml file that defines how to migrate all of the files on the computer on which the ScanState command is running. |
||||||||
/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 removable drives on the source computer, such as USB flash drives (UFDs), some external hard drives, and so on, and when there are network drives mapped on the source computer. If the /localonly option is not specified, then the ScanState command will copy files from these removable or network drives into the store. Anything that is not considered a fixed drive by the OS will be excluded by /localonly. In some cases large external hard drives are considered fixed drives. These drives can be explicitly excluded from migration by using a custom.xml file. For more information about how to exclude all files on a specific drive, see Exclude Files and Settings. The /localonly command-line option includes or excludes data in the migration as identified in the following table:
|
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.
| Command-Line Option | Description | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
/listfiles:<FileName> |
You can use the /listfiles command-line option with the ScanState command to generate a text file that lists all of the files included in the migration. |
||||||||||||||||||
|
/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 either a relative or full path. If you do not specify the Path variable, then the log will be created in the current directory. You can use the /v option to adjust the amount of output. If you run the ScanState or LoadState commands from a shared network resource, you must specify this option or USMT will fail with the following error: "USMT was unable to create the log file(s)". To fix this issue, use the /l:scan.log command. |
||||||||||||||||||
|
/v: <VerbosityLevel> |
(Verbosity) Enables verbose output in the ScanState log file. The default value is 0. You can set the VerbosityLevel to one of the following levels:
For example:
|
||||||||||||||||||
|
/progress:[Path\]FileName |
Creates the optional progress log. You cannot store any of the log files in StorePath. Path can be either a relative or full path. If you do not specify the Path variable, then FileName will be created in the current directory. For example:
|
||||||||||||||||||
|
/c |
When this option is specified, the ScanState command will continue to run, even if non-fatal errors occur. Any files or settings that cause an error are logged in the progress log. For example, if there is a large file that will not fit in the store, the ScanState command will log an error and 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. Without the /c option, the ScanState command will exit on the first error. You can use the new <ErrorControl> section in the Config.xml file to specify which file or registry read/write errors can be safely ignored and which might cause the migration to fail. This enables the /c command-line option to safely skip all input/output (I/O) errors in your environment. In addition, the /genconfig option now generates a sample <ErrorControl> section that is enabled by specifying error messages and desired behaviors in the Config.xml file. |
||||||||||||||||||
|
/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 useful in environments where network connectivity is not reliable. While storing the user state, the /r option 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: <pathToFile> |
When the ScanState command runs, it will create an .xml file in the path specified. This .xml file includes improved space estimations for the migration store. The following example shows how to create this .xml file:
For more information, see Estimate Migration Store Size. To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, you can use the /p option, without specifying "pathtoafile", in USMT. If you specify only the /p option, the storage space estimations are created in the same manner as with USMT3.x releases. |
||||||||||||||||||
|
/? or /help |
Displays Help at the command line. |
||||||||||||||||||
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 the Config.xml file. For more information, see Identify Users and Migrate User Accounts.
| Command-Line Option | Description | |
|---|---|---|
|
/all |
Migrates all of the users on the computer. USMT migrates all user accounts on the computer, unless you specifically exclude an account with either the /ue or /uel options. For this reason, you do not need to specify this option on the command line. However, if you choose to specify the /all option, you cannot also use the /ui, /ue or /uel options. |
|
|
/ui: <DomainName>\<UserName> or /ui: <ComputerName>\<LocalUserName> |
(User include) Migrates the specified users. By default, all users are included in the migration. Therefore, this option is helpful only when used with the /ue or /uel options. You can specify multiple /ui options, but you cannot use the /ui option with the /all option. 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 quotation marks. Note If a user is specified for inclusion with the /ui option, and also is specified to be excluded with either the /ue or /uel options, the user will be included in the migration. For example:
For more examples, see the descriptions of the /ue and /ui options in this table. |
|
|
/uel: <NumberOfDays> or /uel: <YYYY/MM/DD> or /uel:0 |
(User exclude based on last logon) Migrates the users that logged onto the source computer within the specified time period, based on the Last Modified date of the Ntuser.dat file on the source computer. The /uel option acts as an include rule. For example, the /uel:30 option migrates users who logged on, or whose account was modified, within the last 30 days from the date when the ScanState command is run. You can specify a number of days or you can specify a date. You cannot use this option with the /all option. USMT retrieves the last logon information from the local computer, so the computer does not need to be connected to the network when you run this option. In addition, if a domain user has logged onto another computer, that logon instance is not considered by USMT. Note The /uel option is not valid in offline migrations.
For example:
|
|
|
/ue: <DomainName>\<UserName> -or-
/ue: <ComputerName>\<LocalUserName> |
(User exclude) Excludes the specified users from the migration. You can specify multiple /ue options. You cannot use this option with the /all option. <DomainName> and <UserName> can contain the asterisk (*) wildcard character. When you specify a user name that contains spaces, you need to surround it with quotation marks. For example:
|
|
How to Use /ui and /ue
The following examples apply to both the /ui and /ue options. You can replace the /ue option with the /ui option to include, rather than exclude, the specified users.
| Behavior | Command |
|---|---|
Exclude the user named User One in the Fabrikam domain. |
|
Exclude the user named User1 in the Fabrikam domain. |
|
Exclude the local user named User1. |
|
Exclude all domain users. |
|
Exclude all local users. |
|
Exclude users in all domains named User1, User2, and so on. |
|
Using the Options Together
You can use the /uel, /ue and /ui options together to migrate only the users that you want migrated.
The /ui option has precedence over the /ue and /uel options. If a user is specified to be included using the /ui option, and also specified to be excluded using either the /ue or /uel options, the user will be included in the migration. For example, if you specify /ui:contoso\* /ue:contoso\user1, then User1 will be migrated, because the /ui option takes precedence over the /ue option.
The /uel option takes precedence over the /ue option. If a user has logged on within the specified time period set by the /uel option, that user’s profile will be migrated even if they are excluded by using the /ue option. For example, if you specify /ue:fixed\user1 /uel:14, the User1 will be migrated if they have logged on to the computer within the last 14 days.
| Behavior | Command |
|---|---|
Include only User2 from the Fabrikam domain and exclude all other users. |
|
Include only the local user named User1 and exclude all other users. |
|
Include only the domain users from Contoso, except Contoso\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. |
|
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. To migrate encrypted files, you must change the default behavior.
For more information, see Migrate EFS Files and Certificates.
Note
EFS certificates will be migrated automatically when migrating to Windows Vista, Windows 7, or Windows 8. Therefore, you should specify the /efs:copyraw option with the ScanState command to migrate the encrypted files
Caution
Take 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.
| Command-Line Option | Explanation |
|---|---|
/efs:hardlink |
Creates a hard link to the EFS file instead of copying it. Use only with the /hardlink and the /nocompress options. |
/efs:abort |
Causes the ScanState command 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 the ScanState command to ignore EFS files. |
/efs:decryptcopy |
Causes the ScanState command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file cannot be decrypted. If the ScanState command succeeds, the file will be unencrypted in the migration store, and once you run the LoadState command, the file will be copied to the destination computer. |
/efs:copyraw |
Causes the ScanState command to copy the files in the encrypted format. The files will be inaccessible on the destination computer until the EFS certificates are migrated. EFS certificates will be automatically migrated; however, by default USMT fails if an encrypted file is found, unless you specify an /efs option. Therefore you should specify the /efs:copyraw option with the ScanState command to migrate the encrypted file. Then, when you run the LoadState command, the encrypted file and the EFS certificate will be automatically migrated. For example:
|
Incompatible Command-Line Options
The following table indicates which command-line options are not compatible with the ScanState command. 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.
| Command-Line Option | /keyfile | /nocompress | /genconfig | /all |
|---|---|---|---|---|
/i |
||||
/o |
||||
/v |
||||
/nocompress |
X |
N/A |
||
/localonly |
X |
|||
/key |
X |
X |
||
/encrypt |
Required* |
X |
X |
|
/keyfile |
N/A |
X |
||
/l |
||||
/progress |
X |
|||
/r |
X |
|||
/w |
X |
|||
/c |
X |
|||
/p |
X |
N/A |
||
/all |
X |
|||
/ui |
X |
X |
||
/ue |
X |
X |
||
/uel |
X |
X |
||
/efs:<option> |
X |
|||
/genconfig |
N/A |
|||
/config |
X |
|||
<StorePath> |
X |
Note
You must specify either the /key or /keyfile option with the /encrypt option.