UsmtUtils Syntax

Updated: May 31, 2012

Applies To: Windows 7, Windows 8, Windows 8.1

This topic describes the syntax for the utilities available in User State Migration Tool (USMT) 5.0 through the command-line interface. These utilities:

  • Improve your ability to determine cryptographic options for your migration.

  • Assist in removing hard-link stores that cannot otherwise be deleted due to a sharing lock.

  • Verify whether the catalog file or any of the other files in the compressed migration store have become corrupted.

  • Extract files from the compressed migration store when you migrate files and settings to the destination computer.

The following table lists command-line options for USMTutils.exe. The sections that follow provide further command-line options for the /verify and the /extract options.

The syntax for UsmtUtils.exe is:

usmtutils [/ec | /rd <storeDir> | /verify <filepath> [options] | /extract <filepath><destinationPath> [options]]

 

Command-line Option Description

/ec

Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. You can use this on a destination computer to determine which algorithm to use with the /encrypt command before you run the ScanState tool on the source computer.

/rd <storeDir>

Removes the directory path specified by the <storeDir> argument on the computer. You can use this command to delete hard-link migration stores that cannot otherwise be deleted at a command prompt due to a sharing lock. If the migration store spans multiple volumes on a given drive, it will be deleted from all of these volumes.

For example:

usmtutils /rd D:\MyHardLinkStore

/y

Overrides the accept deletions prompt when used with the /rd option. When you use the /y option with the /rd option, you will not be prompted to accept the deletions before USMT deletes the directories.

/verify

Returns information on whether the compressed migration store is intact or whether it contains corrupted files or a corrupted catalog.

See Verify Options for syntax and options to use with /verify.

/extract

Recovers files from a compressed USMT migration store.

See Extract Options for syntax and options to use with /extract.

Use the /verify option when you want to determine whether a compressed migration store is intact or whether it contains corrupted files or a corrupted catalog. For more information on how to use the /verify option, see Verify the Condition of a Compressed Migration Store.

The syntax for /verify is:

usmtutils /verify[:<reportType>] <filePath> [/l:<logfile>] [/v:VerbosityLevel] [/decrypt [:<AlgID>] {/key:<keystring> | /keyfile:<filename>}]

 

Command-line Option Description

<reportType>

Specifies whether to report on all files, corrupted files only, or the status of the catalog.

  • Summary. Returns both the number of files that are intact and the number of files that are corrupted in the migration store. If no algorithm is specified, the summary report is displayed as a default.

  • all. Returns a tab-delimited list of all of the files in the compressed migration store and the status for each file. Each line contains the file name followed by a tab spacing, and either “CORRUPTED” or “OK” depending on the status of the file. The last entry reports the corruption status of the "CATALOG" of the store. A catalog file contains metadata for all files in a migration store. The LoadState tool requires a valid catalog file in order to open the migration store. Returns "OK" if the catalog file is intact and LoadState can open the migration store and "CORRUPTED" if the migration store is corrupted.

  • failureonly. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.

  • Catalog. Returns only the status of the catalog file.

/l: <logfilePath>

Specifies the location and name of the log file.

/v: <VerbosityLevel>

(Verbosity)

Enables verbose output in the UsmtUtils log file. The default value is 0.

You can set the VerbosityLevel to one of the following levels:

 

Level Explanation

0

Only the default errors and warnings are enabled.

1

Enables verbose output.

4

Enables error and status output.

5

Enables verbose and status output.

8

Enables error output to a debugger.

9

Enables verbose output to a debugger.

12

Enables error and status output to a debugger.

13

Enables verbose, status, and debugger output.

/decrypt: <AlgID> /key:<KeyString>

or

/decrypt: <AlgID> /key:<“Key String”>

or

/decrypt: <AlgID> /keyfile:<FileName>

Specifies that the /encrypt option was used to create the migration store with the ScanState tool. To decrypt the migration store, specify a /key or /keyfile option as follows:

  • <AlgID> specifies the cryptographic algorithm that was used to create the migration store on the ScanState command line. If no algorithm is specified, ScanState and UsmtUtils use the 3DES algorithm as a default.

    <AlgID> valid values include: AES_128, AES_192, AES_256, 3DES, or 3DES_112.

  • /key: <KeyString> specifies the encryption key. If there is a space in <KeyString>, you must surround the argument with quotation marks.

  • /keyfile: <FileName> specifies the location and name of a text (.txt) file that contains the encryption key.

For more information about supported encryption algorithms, see Migration Store Encryption

Some examples of /verify commands:

  • usmtutils /verify D:\MyMigrationStore\store.mig

  • usmtutils /verify:catalog D:\MyMigrationStore\store.mig

  • usmtutils /verify:all D:\MyMigrationStore\store.mig /decrypt /l:D:\UsmtUtilsLog.txt

  • usmtutils /verify:failureonly D:\MyMigrationStore\store.mig /decrypt:AES_192 /keyfile:D:\encryptionKey.txt

Use the /extract option to recover files from a compressed USMT migration store if it will not restore normally with loadstate. For more information on how to use the /extract option, see Extract Files from a Compressed USMT Migration Store.

The syntax for /extract is:

/extract <filePath><destinationPath> [/i:<includePattern>] [/e: <excludePattern>] [/l: <logfile>] [/v: VerbosityLevel>] [/decrypt[:<AlgID>] {key: <keystring> | /keyfile: <filename>}] [/o]

 

Command-line Option Description

<filePath>

Path to the USMT migration store.

For example:

D:\MyMigrationStore\USMT\store.mig

<destinationPath>

Path to the folder where the tool puts the individual files.

/i:<includePattern>

Specifies a pattern for files to include in the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use /i: <includePattern> and /e: <excludePattern> options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns.

/e:<excludePattern>

Specifies a pattern for files to omit from the extraction. You can specify more than one pattern. Separate patterns with a comma or a semicolon. You can use /i: <includePattern> and /e: <excludePattern> options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns.

/l:<logfilePath>

Specifies the location and name of the log file.

/v: <VerbosityLevel>

(Verbosity)

Enables verbose output in the UsmtUtils log file. The default value is 0.

You can set the VerbosityLevel to one of the following levels:

 

Level Explanation

0

Only the default errors and warnings are enabled.

1

Enables verbose output.

4

Enables error and status output.

5

Enables verbose and status output.

8

Enables error output to a debugger.

9

Enables verbose output to a debugger.

12

Enables error and status output to a debugger.

13

Enables verbose, status, and debugger output.

/decrypt: <AlgID> /key:<KeyString>

or

/decrypt: <AlgID> /key:<“Key String”>

or

/decrypt: <AlgID> /keyfile:<FileName>

Specifies that the /encrypt option was used to create the migration store with the ScanState tool. To decrypt the migration store, you must also specify a /key or /keyfile option as follows:

  • <AlgID> specifies the cryptographic algorithm that was used to create the migration store on the ScanState command line. If no algorithm is specified, ScanState and UsmtUtils use the 3DES algorithm as a default.

    <AlgID> valid values include: AES_128, AES_192, AES_256, 3DES, or 3DES_112.

  • /key: <KeyString> specifies the encryption key. If there is a space in <KeyString>, you must surround the argument with quotation marks.

  • /keyfile:<FileName> specifies a text (.txt) file that contains the encryption key

For more information about supported encryption algorithms, see Migration Store Encryption

/o

Overwrites existing output files.

Some examples of /extract commands:

  • usmtutils /extract D:\MyMigrationStore\USMT\store.mig C:\ExtractedStore

  • usmtutils /extract D:\MyMigrationStore\USMT\store.mig /i:"*.txt, *.pdf" C:\ExtractedStore /decrypt /keyfile:D:\encryptionKey.txt

  • usmtutils /extract D:\MyMigrationStore\USMT\store.mig /e:*.exe C:\ExtractedStore /decrypt:AES_128 /key:password /l:C:\usmtlog.txt

  • usmtutils /extract D:\MyMigrationStore\USMT\store.mig /i:myProject.* /e:*.exe C:\ExtractedStore /o

Show: