deepblue/windows-itpro-docs
1
0
Fork 0
mirror of https://github.com/MicrosoftDocs/windows-itpro-docs.git synced 2025-06-16 19:03:46 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Metadata update deployment/usmt 17

Browse Source
This commit is contained in:
Frank Rojas
2022-11-04 15:11:10 -04:00
parent 883a7ce855
commit d90dd9e71d
12 changed files with 362 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
windows/deployment/usmt/understanding-migration-xml-files.md
View File

@ -131,7 +131,10 @@ The default `MigUser.xml` file migrates the following data:
- Files with the following extensions:
`.qdf`, `.qsd`, `.qel`, `.qph`, `.doc*`, `.dot*`, `.rtf`, `.mcw`, `.wps`, `.scd`, `.wri`, `.wpd`, `.xl*`, `.csv`, `.iqy`, `.dqy`, `.oqy`, `.rqy`, `.wk*`, `.wq1`, `.slk`, `.dif`, `.ppt*`, `.pps*`, `.pot*`, `.sh3`, `.ch3`, `.pre`, `.ppa`, `.txt`, `.pst`, `.one*`, `.vl*`, `.vsd`, `.mpp`, `.or6`, `.accdb`, `.mdb`, `.pub`
`.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*`
> [!NOTE]
> The asterisk (`*`) stands for zero or more characters.
The default `MigUser.xml` file doesn't migrate the following data:

2
windows/deployment/usmt/usmt-common-issues.md
View File

@ -19,7 +19,7 @@ The following sections discuss common issues that you might see when you run the
When you encounter a problem or error message during migration, you can use the following general guidelines to help determine the source of the problem:
- Examine the **ScanState**, **LoadState**, and UsmtUtils logs to obtain the exact USMT error messages and Windows® application programming interface (API) error messages. For more information about USMT return codes and error messages, see [Return codes](usmt-return-codes.md). For more information about Windows API error messages, type **nethelpmsg** on the command line.
- Examine the **ScanState**, **LoadState**, and UsmtUtils logs to obtain the exact USMT error messages and Windows® application programming interface (API) error messages. For more information about USMT return codes and error messages, see [Return codes](usmt-return-codes.md). You can obtain more information about any listed **Windows** system error codes by typing in a command prompt window `net.exe helpmsg <error_number>` where *<error_number>* is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-).
In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. We recommend that you use the `/v:5` option when testing your migration. This verbosity level can be adjusted in a production migration; however, reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a verbosity level higher than 5 if you want the log files output to go to a debugger.

26
windows/deployment/usmt/usmt-loadstate-syntax.md
View File

@ -13,7 +13,7 @@ ms.technology: itpro-deploy
# LoadState syntax
This article discusses the `LoadState.exe` command syntax and options available with it.
The `LoadState.exe` command is used with the User State Migration Tool (USMT) 10.0 to restore a store previously captured by the `ScanState.exe` command onto a destination computer. This article discusses the `LoadState.exe` command syntax and the options available with it.
## Before you begin
@ -37,7 +37,11 @@ This section explains the syntax and usage of the command-line options available
The `LoadState.exe` command's syntax is:
`loadstate.exe` *StorePath* \[/i:\[*Path*\\\]*FileName*\] \[/v:*VerbosityLevel*\] \[/nocompress\] \[/decrypt /key:*KeyString*|/keyfile:\[Path\\\]*FileName*\] \[/l:\[*Path*\\\]*FileName*\] \[/progress:\[*Path*\\\]*FileName*\] \[/r:*TimesToRetry*\] \[/w:*SecondsToWait*\] \[/c\] \[/all\] \[/ui:\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/ue:\[\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/uel:*NumberOfDays*|*YYYY/MM/DD*|0\] \[/md:*OldDomain*:*NewDomain*\] \[/mu:*OldDomain*\\*OldUserName*:\[*NewDomain*\\\]*NewUserName*\] \[/lac:\[*Password*\]\] \[/lae\] \[/config:\[*Path*\\\]*FileName*\] \[/?|help\]
<!--
`loadstate.exe StorePath [/i:[Path\]FileName] [/v:VerbosityLevel] [/nocompress] [/decrypt /key:KeyString|/keyfile:[Path\]FileName] [/l:[Path\]FileName] [/progress:[Path\]FileName] [/r:TimesToRetry] [/w:SecondsToWait] [/c] [/all] [/ui:[DomainName|ComputerName\]UserName] [/ue:[[DomainName|ComputerName\]UserName] [/uel:NumberOfDays|YYYY/MM/DD|0] [/md:OldDomain:NewDomain] [/mu:OldDomain\OldUserName:[NewDomain\]NewUserName] [/lac:[Password]] [/lae] [/config:[Path\]FileName] [/?|help]`
-->
> loadstate.exe *StorePath* \[/i:\[*Path*\\\]*FileName*\] \[/v:*VerbosityLevel*\] \[/nocompress\] \[/decrypt /key:*KeyString*|/keyfile:\[Path\\\]*FileName*\] \[/l:\[*Path*\\\]*FileName*\] \[/progress:\[*Path*\\\]*FileName*\] \[/r:*TimesToRetry*\] \[/w:*SecondsToWait*\] \[/c\] \[/all\] \[/ui:\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/ue:\[\[*DomainName*|*ComputerName*\\\]*UserName*\] \[/uel:*NumberOfDays*|*YYYY/MM/DD*|0\] \[/md:*OldDomain*:*NewDomain*\] \[/mu:*OldDomain*\\*OldUserName*:\[*NewDomain*\\\]*NewUserName*\] \[/lac:\[*Password*\]\] \[/lae\] \[/config:\[*Path*\\\]*FileName*\] \[/?|help\]
For example, to decrypt the store and migrate the files and settings to a computer, type the following command:
@ -50,7 +54,7 @@ USMT provides the following options that you can use to specify how and where th
| Command-Line Option | Description |
|--- |--- |
| **StorePath** | Indicates the folder where the files and settings data are stored. You must specify *StorePath* when using the `LoadState.exe` command. You can't specify more than one *StorePath*. |
| **/decrypt /key**:*KeyString* <br/>or <br/>**/decrypt /key**:"*Key String*" <br/>or <br/>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, you'll need to specify the encryption key in one of the following ways:<ul><li>`/key:`*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks.</li><li>`/keyfile:`*FilePathAndName* specifies a text (.txt) file that contains the encryption key</li></ul> <br/>*KeyString* can't exceed 256 characters. <br/>The `/key` and `/keyfile` options can't be used on the same command line. <br/>The `/decrypt` and `/nocompress` options can't be used on the same command line. <br/><div class="alert">**Important** <br/> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options will also have access to the encryption key.</div> <br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **/decrypt /key**:*KeyString* <br/>or <br/>**/decrypt /key**:"*Key String*" <br/>or <br/>**/decrypt /keyfile**:[*Path*]*FileName* | Decrypts the store with the specified key. With this option, you'll need to specify the encryption key in one of the following ways:<ul><li>`/key`:*KeyString* specifies the encryption key. If there's a space in *KeyString*, you must surround the argument with quotation marks (`"`).</li><li>`/keyfile`:*FilePathAndName* specifies a text (`.txt`) file that contains the encryption key</li></ul> <br/>*KeyString* can't exceed 256 characters. <br/>The `/key` and `/keyfile` options can't be used on the same command line. <br/>The `/decrypt` and `/nocompress` options can't be used on the same command line. <br/><div class="alert">**Important** <br/> Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `LoadState.exe` command with these options will also have access to the encryption key.</div> <br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /decrypt /key:mykey` |
| **/decrypt**:*"encryption strength"* | The `/decrypt` option accepts a command-line parameter to define the encryption strength specified for the migration store encryption. For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/hardlink** | Enables user-state data to be restored from a hard-link migration store. The `/nocompress` parameter must be specified with `/hardlink` option. |
| **/nocompress** | Specifies that the store isn't compressed. You should only use this option in testing environments. We recommend that you use a compressed store during your actual migration. This option can't be used with the `/decrypt` option. <br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /nocompress` |
@ -61,8 +65,8 @@ USMT provides the following options to specify what files you want to migrate.
| Command-Line Option | Description |
|--- |--- |
| **/i**:[*Path*]*FileName* | **(include)** <br/>Specifies an .xml file that contains rules that define what state to migrate. You can specify this option multiple times to include all of your .xml files (MigApp.xml, MigSys.xml, MigDocs.xml and any custom .xml files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. <br/><br/>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory. <br/><br/>This example migrates the files and settings based on the rules in the Config.xml, MigDocs.xml, and MigApp.xml files: <br/><br/>`loadstate.exe \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:5 /l:loadstate.log` |
| **/i**:[*Path*]*FileName* | **(include)** <br/>Specifies an .xml file that contains rules that define what state to migrate. You can specify this option multiple times to include all of your .xml files (`MigApp.xml`, `MigSys.xml`, `MigDocs.xml` and any custom .xml files that you create). *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory. <br/><br/>For more information about which files to specify, see the &quot;XML files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) article. |
| **/config**:[*Path*]*FileName* | Specifies the `Config.xml` file that the `LoadState.exe` command should use. You can't specify this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the *FileName* must be located in the current directory. <br/><br/>This example migrates the files and settings based on the rules in the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files: <br/><br/>`loadstate.exe \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:5 /l:loadstate.log` |
| **/auto**:*"path to script files"* | This option enables you to specify the location of the default .xml files and then launch your migration. If no path is specified, USMT will use 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`. |
## Monitoring options
@ -71,24 +75,24 @@ USMT provides several command-line options that you can use to analyze problems
| Command-Line Option | Description |
|--- |--- |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log will be created in the current directory. You can specify the `/v` option to adjust the verbosity of the log. <br/><br/>If you run the `LoadState.exe` command from a shared network resource, you must specify this option, or USMT will fail with the error:<br/><br/> ***USMT was unable to create the log file(s)***<br/><br/> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/l**:[*Path*]*FileName* | Specifies the location and name of the **LoadState** log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then the log will be created in the current directory. You can specify the `/v` option to adjust the verbosity of the log. <br/><br/>If you run the `LoadState.exe` command from a shared network resource, you must specify the `l` option, or USMT will fail with the error:<br/><br/>***USMT was unable to create the log file(s)***<br/><br/> To fix this issue, make sure to specify the `/l` option when running `LoadState.exe` from a shared network resource. |
| **/v**:*`<VerbosityLevel>`* | **(Verbosity)** <br/><br/>Enables verbose output in the **LoadState** log file. The default value is 0. <br/>You can set the *VerbosityLevel* to one of the following levels:<ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul><br/>For example: <br/>`loadstate.exe \server\share\migration\mystore /v:5 /i:migdocs.xml /i:migapp.xml` |
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory. <br/><br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /progress:prog.log /l:loadlog.log` |
| **/c** | When this option is specified, the `LoadState.exe` 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's a large file that won't fit on the computer, the `LoadState.exe` command will log an error and continue with the migration. Without the **/c** option, the `LoadState.exe` command will exit on the first error. You can use the new &lt;**ErrorControl**&gt; 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 error control 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 &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the Config.xml file. |
| **/c** | When this option is specified, the `LoadState.exe` 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's a large file that won't fit on the computer, the `LoadState.exe` command will log an error and continue with the migration. Without the `/c` option, the `LoadState.exe` command will exit on the first error. You can use the new &lt;**ErrorControl**&gt; 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 error control 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 &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r**:*`<TimesToRetry>`* | **(Retry)** <br/><br/>Specifies the number of times to retry when an error occurs while migrating the user state from a server. The default is three times. This option is useful in environments where network connectivity isn't reliable. <br/><br/>While restoring the user state, the `/r` option won't 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)** <br/><br/>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/?** or **/help** | Displays Help on 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 can't exclude users in the migration .xml files or by using the Config.xml file. For more information, see [Identify Users](usmt-identify-users.md).
By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. You can't exclude users in the migration .xml files or by using the `Config.xml` file. For more information, see [Identify Users](usmt-identify-users.md).
| Command-Line Option | Description |
|--- |--- |
| **/all** | Migrates all of the users on the computer. <br/><br/>USMT migrates all user accounts on the computer, unless you specifically exclude an account with the `/ue` or `/uel` options. For this reason, you don't need to specify this option on the command line. However, if you choose to use the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*DomainName UserName* <br/>or <br/>**/ui**:*"DomainName User Name"* <br/>or <br/>**/ui**:*ComputerName LocalUserName* | **(User include)** <br/><br/>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't 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'll need to surround it with quotations marks. <br/>For example:<ul><li>To include only User2 from the Corporate domain, type: <br/>`/ue:* /ui:corporate\user2`</li></ul> <div class="alert">**Note** <br/>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration.</div> <br/> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`* <br/>or <br/>**/uel**:*`<YYYY/MM/DD>`* <br/>or <br/>**/uel**:0 | **(User exclude based on last logon)** <br/><br/>Migrates only 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 user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user has signed into another computer, that sign-in instance isn't considered by USMT. <div class="alert">**Note** <br/>The `/uel` option isn't valid in offline migrations.</div> <br/>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts have been modified within the last 24 hours.</li><li>`/uel:2002/1/15` migrates users who have logged on or whose accounts have been modified since January 15, 2002.</li></ul> <br/>For example: <br/>`loadstate.exe/i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName* <br/>or <br/>**/ue** *"DomainName\User Name"* <br/>or <br/>**/ue**:*ComputerName\LocalUserName* | **(User exclude)** <br/><br/>Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk () wildcard character. When you specify a user name that contains spaces, you'll need to surround it with quotation marks. <br/><br/>For example: <br/>`loadstate.exe/i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /ue:contoso\user1` <br/>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/ui**:*DomainName UserName* <br/>or <br/>**/ui**:*"DomainName User Name"* <br/>or <br/>**/ui**:*ComputerName LocalUserName* | **(User include)** <br/><br/>Migrates the specified user. By default, all users are included in the migration. Therefore, this option is helpful only when used with the `/ue` option. You can specify multiple `/ui` options, but you can't 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'll need to surround it with quotations marks (`"`). <br/>For example:<ul><li>To include only User2 from the Corporate domain, type: <br/>`/ue:* /ui:corporate\user2`</li></ul> <div class="alert">**Note** <br/>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration.</div> <br/> For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/uel**:*`<NumberOfDays>`* <br/>or <br/>**/uel**:*`<YYYY/MM/DD>`* <br/>or <br/>**/uel**:0 | **(User exclude based on last logon)** <br/><br/>Migrates only 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 user account was modified, within the last 30 days from the date when the `ScanState.exe` command is run. You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user has signed into another computer, that sign-in instance isn't considered by USMT. <div class="alert">**Note** <br/>The `/uel` option isn't valid in offline migrations.</div> <br/>Examples:<ul><li>`/uel:0` migrates accounts that were logged on to the source computer when the `ScanState.exe` command was run.</li><li>`/uel:90` migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose accounts have been modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who have logged on or whose accounts have been modified since February 15, 2020.</li></ul> <br/>For example: <br/>`loadstate.exe/i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /uel:0` |
| **/ue**:*DomainName\UserName* <br/>or <br/>**/ue** *"DomainName\User Name"* <br/>or <br/>**/ue**:*ComputerName\LocalUserName* | **(User exclude)** <br/><br/>Excludes the specified users from the migration. You can specify multiple `/ue` options but you can't use the `/ue` option with the `/all` option. *DomainName* and *UserName* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you'll need to surround it with quotation marks (`"`). <br/><br/>For example: <br/>`loadstate.exe/i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /ue:contoso\user1` <br/>For more examples, see the descriptions of the `/uel`, `/ue`, and `/ui` options in this table. |
| **/md**:*OldDomain*:*NewDomain* <br/>or <br/>**/md**:*LocalComputerName:NewDomain* | **(Move domain)** <br/><br/>Specifies a new domain for the user. Use this option to change the domain for users on a computer or to migrate a local user to a domain account. *OldDomain* may contain the asterisk () wildcard character. <br/><br/>You can specify this option more than once. You may want to specify multiple `/md` options if you're consolidating users across multiple domains to a single domain. For example, you could specify the following to consolidate the users from the Corporate and FarNorth domains into the Fabrikam domain: `/md:corporate:fabrikam` and `/md:farnorth:fabrikam`. <br/><br/>If there are conflicts between two `/md` commands, the first rule that you specify is applied. For example, if you specify the `/md:corporate:fabrikam` and `/md:corporate:farnorth` commands, then Corporate users would be mapped to the Fabrikam domain. <div class="alert"> **Note** <br/>If you specify an *OldDomain* that didn't exist on the source computer, the `LoadState.exe` command will appear to complete successfully, without an error or warning. However, in this case, users won't be moved to *NewDomain* but will remain in their original domain. For example, if you misspell **contoso** and you instead specify **/md:contso:fabrikam**, the users will remain in **contoso** on the destination computer.</div> <br/> For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore` <br/>` /progress:prog.log /l:load.log /md:contoso:fabrikam` |
| **/mu**:*OldDomain OldUserName*:[*NewDomain*]*NewUserName* <br/>or <br/>**/mu**:*OldLocalUserName*:*NewDomain NewUserName* | **(Move user)** <br/><br/>Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple `/mu` options. You can't use wildcard characters with this option. <br/><br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore` <br/>`/progress:prog.log /l:load.log /mu:contoso\user1:fabrikam\user1` |
| **/lac**:[*Password*] | **(Local account create)** <br/><br/>Specifies that if a user account is a local (non-domain) account, and it doesn't exist on the destination computer, USMT will create the account on the destination computer but it will be disabled. To enable the account, you must also use the `/lae` option. <br/><br/>If the `/lac` option isn't specified, any local user accounts that don't already exist on the destination computer won't be migrated. <br/><br/>*Password* is the password for the newly created account. An empty password is used by default. <div class="alert"> **Caution** <br/>Use the *Password* variable with caution because it's provided in plain text and can be obtained by anyone with access to the computer that is running the `LoadState.exe` command. <br/>Also, if the computer has multiple users, all migrated users will have the same password.</div> <br/>For example: <br/>`loadstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore` <br/><br/>For instructions, see [Migrate user accounts](usmt-migrate-user-accounts.md). |

2
windows/deployment/usmt/usmt-requirements.md
View File

@ -34,7 +34,7 @@ The following table lists the operating systems supported in USMT.
## Unsupported scenarios
- USMT doesn't support any of the Windows Server® operating systems.
- USMT for Windows 10 shouldn't be used for migrating between previous versions of Windows. USMT for Windows 10 is only meant to migrate to Windows 10 or between Windows 10 versions. For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) Overview](/previous-versions/windows/hh825227(v=win.10).
- USMT for Windows 10 shouldn't be used for migrating between previous versions of Windows. USMT for Windows 10 is only meant to migrate to Windows 10 or between Windows 10 versions. For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
## Windows PE

66
windows/deployment/usmt/usmt-return-codes.md
View File

@ -13,7 +13,7 @@ ms.technology: itpro-deploy
# Return codes
This topic describes User State Migration Tool (USMT) 10.0 return codes and error messages. Also included is a table listing the USMT return codes with their associated mitigation steps. In addition, this topic provides tips to help you use the logfiles to determine why you received an error.
This article describes User State Migration Tool (USMT) 10.0 return codes and error messages. Also included is a table listing the USMT return codes with their associated mitigation steps. In addition, this article provides tips to help you use the logfiles to determine why you received an error.
Understanding the requirements for running USMT can help minimize errors in your USMT migrations. For more information, see [USMT Requirements](usmt-requirements.md).
@ -33,11 +33,11 @@ Return codes are grouped into the following broad categories that describe their
- Fatal Errors
As a best practice, we recommend that you set verbosity level to 5, `v:5`, on the `ScanState.exe`, `LoadState.exe`, and `USMTUtils.exe` command lines so that the most detailed reporting is available in the respective USMT logs. You can use a higher verbosity level if you want the log files output to go to a debugger.
As a best practice, we recommend that you set verbosity level to 5, `v:5`, on the `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe` command lines so that the most detailed reporting is available in the respective USMT logs. You can use a higher verbosity level if you want the log files output to go to a debugger.
## USMT error messages
Error messages provide more detailed information about the migration problem than the associated return code. For example, the **ScanState**, **LoadState**, or **USMTUtils** tool might return a code of **11** (for **USMT_INVALID_PARAMETERS**) and a related error message that reads **/key and /keyfile both specified**. The error message is displayed at the command prompt and is identified in the **ScanState**, **LoadState**, or **USMTUtils** log files to help you determine why the return code was received.
Error messages provide more detailed information about the migration problem than the associated return code. For example, the **ScanState**, **LoadState**, or **UsmtUtils** tool might return a code of **11** (for **USMT_INVALID_PARAMETERS**) and a related error message that reads **/key and /keyfile both specified**. The error message is displayed at the command prompt and is identified in the **ScanState**, **LoadState**, or **UsmtUtils** log files to help you determine why the return code was received.
You can obtain more information about any listed **Windows** system error codes by typing in a command prompt window `net.exe helpmsg <error_number>` where *<error_number>* is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-).
@ -139,7 +139,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Log path argument is invalid for /l** | When /l is specified in the ScanState command line, USMT validates the path. Verify that the drive and other information, for example file system characters, are correct. |
| **Log path argument is invalid for /l** | When `/l` is specified in the ScanState command line, USMT validates the path. Verify that the drive and other information, for example file system characters, are correct. |
### 14: USMT_ERROR_USE_LAC
@ -147,7 +147,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Unable to create a local account because /lac was not specified** | When creating local accounts, the command-line options /lac and /lae should be used. |
| **Unable to create a local account because /lac was not specified** | When creating local accounts, the command-line options `/lac` and `/lae` should be used. |
### 26: USMT_INIT_ERROR
@ -155,9 +155,9 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Multiple Windows installations found** | Listfiles.txt could not be created. Verify that the location you specified for the creation of this file is valid. |
| **Software malfunction or unknown exception** | Check all loaded .xml files for errors, common error when using /I to load the Config.xml file. |
| **Unable to find a valid Windows directory to proceed with requested offline operation; Check if offline input file is present and has valid entries** | Verify that the offline input file is present and that it has valid entries. USMT could not find valid offline operating system. Verify your offline directory mapping. |
| **Multiple Windows installations found** | Listfiles.txt couldn't be created. Verify that the location you specified for the creation of this file is valid. |
| **Software malfunction or unknown exception** | Check all loaded .xml files for errors, common error when using `/i` to load the Config.xml file. |
| **Unable to find a valid Windows directory to proceed with requested offline operation; Check if offline input file is present and has valid entries** | Verify that the offline input file is present and that it has valid entries. USMT couldn't find valid offline operating system. Verify your offline directory mapping. |
### 27: USMT_INVALID_STORE_LOCATION
@ -165,12 +165,12 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **A store path can't be used because an existing store exists; specify /o to overwrite** | Specify /o to overwrite an existing intermediate or migration store. |
| **A store path can't be used because an existing store exists; specify /o to overwrite** | Specify `/o` to overwrite an existing intermediate or migration store. |
| **A store path is missing or has incomplete data** | Make sure that the store path is accessible and that the proper permission levels are set. |
| **An error occurred during store creation** | Make sure that the store path is accessible and that the proper permission levels are set. Specify /o to overwrite an existing intermediate or migration store. |
| **An error occurred during store creation** | Make sure that the store path is accessible and that the proper permission levels are set. Specify `/o` to overwrite an existing intermediate or migration store. |
| **An inappropriate device such as a floppy disk was specified for the store** | Make sure that the store path is accessible and that the proper permission levels are set. |
| **Invalid store path; check the store parameter and/or file system permissions** | Invalid store path; check the store parameter and/or file system permissions. |
| **The file layout and/or file content is not recognized as a valid store** | Make sure that the store path is accessible and that the proper permission levels are set. Specify /o to overwrite an existing intermediate or migration store. |
| **The file layout and/or file content is not recognized as a valid store** | Make sure that the store path is accessible and that the proper permission levels are set. Specify `/o` to overwrite an existing intermediate or migration store. |
| **The store path holds a store incompatible with the current USMT version** | Make sure that the store path is accessible and that the proper permission levels are set. |
| **The store save location is read-only or does not support a requested storage option** | Make sure that the store path is accessible and that the proper permission levels are set. |
@ -180,7 +180,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Script file is invalid for /i** | Check all specified migration .xml files for errors. This is a common error when using /i to load the Config.xml file. |
| **Script file is invalid for /i** | Check all specified migration .xml files for errors. This error is common when using `/i` to load the `Config.xml` file. |
| **Unable to find a script file specified by /i** | Verify the location of your script files, and ensure that the command-line options are correct. |
### 29: USMT_FAILED_MIGSTARTUP
@ -203,15 +203,13 @@ The following information lists each return code by numeric value, along with th
| --- | --- |
| **An error occurred during the discover phase; the log should have more specific information** | Check the ScanState log file for migration .xml file errors. |
### 32: USMT_FAILED_SETMIGRATIONTYPE
- **Category**: Setup and Initialization
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **An error occurred processing the migration system** | Check the ScanState log file for migration .xml file errors, or use online Help by typing /? on the command line. |
| **An error occurred processing the migration system** | Check the ScanState log file for migration .xml file errors, or use online Help by typing `/?` on the command line. |
### 33: USMT_UNABLE_READKEY
@ -219,8 +217,8 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Error accessing the file specified by the /keyfile parameter** | Check the ScanState log file for migration .xml file errors, or use online Help by typing /? on the command line. |
| **The encryption key must have at least one character** | Check the ScanState log file for migration .xml file errors, or use online Help by typing /? on the command line. |
| **Error accessing the file specified by the /keyfile parameter** | Check the ScanState log file for migration .xml file errors, or use online Help by typing `/?` on the command line. |
| **The encryption key must have at least one character** | Check the ScanState log file for migration .xml file errors, or use online Help by typing `/?` on the command line. |
### 34: USMT_ERROR_INSUFFICIENT_RIGHTS
@ -228,9 +226,9 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Directory removal requires elevated privileges** | Log on as Administrator, and run with elevated privileges. |
| **No rights to create user profiles; log in as Administrator; run with elevated privileges** | Log on as Administrator, and run with elevated privileges. |
| **No rights to read or delete user profiles; log in as Administrator, run with elevated privileges** | Log on as Administrator, and run with elevated privileges. |
| **Directory removal requires elevated privileges** | Sign in as Administrator, and run with elevated privileges. |
| **No rights to create user profiles; log in as Administrator; run with elevated privileges** | Sign in as Administrator, and run with elevated privileges. |
| **No rights to read or delete user profiles; log in as Administrator, run with elevated privileges** | Sign in as Administrator, and run with elevated privileges. |
### 35: USMT_UNABLE_DELETE_STORE
@ -238,8 +236,8 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **A reboot is required to remove the store** | Reboot to delete any files that could not be deleted when the command was executed. |
| **A store path can't be used because it contains data that could not be overwritten** | A migration store could not be deleted. If you are using a hardlink migration store you might have a locked file in it. You should manually delete the store, or use **USMTUtils /rd** command to delete the store. |
| **A reboot is required to remove the store** | Reboot to delete any files that couldn't be deleted when the command was executed. |
| **A store path can't be used because it contains data that could not be overwritten** | A migration store couldn't be deleted. If you're using a hardlink migration store, you might have a locked file in it. You should manually delete the store, or use `UsmtUtils.exe /rd` command to delete the store. |
| **There was an error removing the store** | Review ScanState log or LoadState log for details about command-line errors. |
### 36: USMT_ERROR_UNSUPPORTED_PLATFORM
@ -248,9 +246,9 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Compliance check failure; please check the logs for details** | Investigate whether there is an active temporary profile on the system. |
| **Use of /offline is not supported during apply** | The **/offline** command was not used while running in the Windows Preinstallation Environment (WinPE). |
| **Use /offline to run gather on this platform** | The **/offline** command was not used while running in WinPE. |
| **Compliance check failure; please check the logs for details** | Investigate whether there's an active temporary profile on the system. |
| **Use of /offline is not supported during apply** | The `/offline` command wasn't used while running in the Windows Preinstallation Environment (WinPE). |
| **Use /offline to run gather on this platform** | The `/offline` command wasn't used while running in WinPE. |
### 37: USMT_ERROR_NO_INVALID_KEY
@ -258,9 +256,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **The store holds encrypted data but the correct encryption key was not provided** | Verify that you have included the correct encryption /key or /keyfile. |
- **Category**: Setup and Initialization
| **The store holds encrypted data but the correct encryption key was not provided** | Verify that the correct encryption key or keyfile was included with the `/key` or `/keyfile` option. |
### 38: USMT_ERROR_CORRUPTED_NOTENCRYPTED_STORE
@ -277,7 +273,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Error reading Config.xml** | Review ScanState log or LoadState log for details about command-line errors in the Config.xml file. |
| **File argument is invalid for /config** | Check the command line you used to load the Config.xml file. You can use online Help by typing /? on the command line. |
| **File argument is invalid for /config** | Check the command line you used to load the Config.xml file. You can use online Help by typing `/?` on the command line. |
### 40: USMT_ERROR_UNABLE_CREATE_PROGRESS_LOG
@ -285,8 +281,8 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Error writing to the progress log** | The Progress log could not be created. Verify that the location is valid and that you have write access. |
| **Progress log argument is invalid for /progress** | The Progress log could not be created. Verify that the location is valid and that you have write access. |
| **Error writing to the progress log** | The Progress log couldn't be created. Verify that the location is valid and that you have write access. |
| **Progress log argument is invalid for /progress** | The Progress log couldn't be created. Verify that the location is valid and that you have write access. |
### 41: USMT_PREFLIGHT_FILE_CREATION_FAILED
@ -294,7 +290,7 @@ The following information lists each return code by numeric value, along with th
| Error message | Troubleshooting, mitigation, workarounds |
| --- | --- |
| **Can't overwrite existing file** | The Progress log could not be created. Verify that the location is valid and that you have write access. |
| **Can't overwrite existing file** | The Progress log couldn't be created. Verify that the location is valid and that you have write access. |
| **Invalid space estimate path. Check the parameters and/or file system permissions** | Review ScanState log or LoadState log for details about command-line errors. |
### 42: USMT_ERROR_CORRUPTED_STORE
@ -303,7 +299,7 @@ The following information lists each return code by numeric value, along with th
| Error message | The store contains one or more corrupted files |
| --- | --- |
| **The store holds encrypted data but the correct encryption key was not provided** | Review UsmtUtils log for details about the corrupted files. For information on how to extract the files that are not corrupted, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md). |
| **The store holds encrypted data but the correct encryption key was not provided** | Review UsmtUtils log for details about the corrupted files. For information on how to extract the files that aren't corrupted, see [Extract files from a compressed USMT migration store](usmt-extract-files-from-a-compressed-migration-store.md). |
### 61: USMT_MIGRATION_STOPPED_NONFATAL
@ -322,7 +318,7 @@ The following information lists each return code by numeric value, along with th
| **A Windows Win32 API error occurred** | Data transfer has begun, and there was an error during the creation of migration store or during the apply phase. Review the ScanState log or LoadState log for details. |
| **An error occurred when attempting to initialize the diagnostic mechanisms such as the log** | Data transfer has begun, and there was an error during the creation of migration store or during the apply phase. Review the ScanState log or LoadState log for details. |
| **Failed to record diagnostic information** | Data transfer has begun, and there was an error during the creation of migration store or during the apply phase. Review the ScanState log or LoadState log for details. |
| **Unable to start. Make sure you are running USMT with elevated privileges** | Exit USMT and log in again with elevated privileges. |
| **Unable to start. Make sure you are running USMT with elevated privileges** | Exit USMT and sign in again with elevated privileges. |
### 72: USMT_UNABLE_DOMIGRATION
@ -336,7 +332,7 @@ The following information lists each return code by numeric value, along with th
| **Out of disk space while writing the store** | Data transfer has begun, and there was an error during migration-store creation or during the apply phase. Review the ScanState log or LoadState log for details. |
| **Out of temporary disk space on the local system** | Data transfer has begun, and there was an error during migration-store creation or during the apply phase. Review the ScanState log or LoadState log for details. |
## Related topics
## Related articles
[User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)

208
windows/deployment/usmt/usmt-scanstate-syntax.md
View File

@ -1,6 +1,6 @@
---
title: ScanState Syntax (Windows 10)
description: The ScanState command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store.
title: **ScanState** Syntax (Windows 10)
description: The **ScanState** command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store.
ms.reviewer:
manager: aaroncz
ms.author: frankroj
@ -11,85 +11,67 @@ ms.topic: article
ms.technology: itpro-deploy
---
# ScanState Syntax
# ScanState syntax
The ScanState command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store.
The `ScanState.exe` command is used with the User State Migration Tool (USMT) 10.0 to scan the source computer, collect the files and settings, and create a store. This article discusses the `ScanState.exe` command syntax and the options available with it.
## In This Topic
## Before you begin
[Before You Begin](#bkmk-beforeyoubegin)
Before you run the `ScanState.exe` command, note the items:
[Syntax](#bkmk-syntax)
- To ensure that all operating system settings migrate, in most cases you must run the `ScanState.exe` commands in administrator mode from an account with administrative credentials.
[Storage Options](#bkmk-storageoptions)
- If you encrypt the migration store, you'll 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 isn't kept anywhere in the migration store. You'll need this information when you run the `LoadState.exe` 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.
[Migration Rule Options](#bkmk-migrationruleoptions)
[Monitoring Options](#monitoring-options)
[User Options](#bkmk-useroptions)
[Encrypted file options](#encrypted-file-options)
[Incompatible Command-Line Options](#bkmk-iclo)
## <a href="" id="bkmk-beforeyoubegin"></a>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](usmt-requirements.md).
- For information about software requirements for running the `ScanState.exe` command, see [USMT requirements](usmt-requirements.md).
- 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 extra configuration.
- The [Incompatible Command-Line Options](#bkmk-iclo) table lists which options you can use together and which command-line options are incompatible.
- The [Incompatible command-line options](#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.
## <a href="" id="bkmk-syntax"></a>Syntax
## 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.
This section explains the syntax and usage of the command-line options available when you use the `ScanState.exe` command. 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:
The `ScanState.exe` command's syntax is:
> scanstate \[*StorePath*\] \[/apps\] \[/ppkg:*FileName*\] \[/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\]
> scanstate.exe \[*StorePath*\] \[/apps\] \[/ppkg:*FileName*\] \[/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:
For example, to create a `Config.xml` file in the current directory, use:
`scanstate /i:migapp.xml /i:migdocs.xml /genconfig:config.xml /v:13`
`scanstate.exe /i:migapp.xml /i:migdocs.xml /genconfig:config.xml /v:13`
To create an encrypted store using the Config.xml file and the default migration .xml files, use:
To 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"`
`scanstate.exe \\server\share\migration\mystore /i:migapp.xml /i:migdocs.xml /o /config:config.xml /v:13 /encrypt /key:"mykey"`
## <a href="" id="bkmk-storageoptions"></a>Storage Options
## Storage options
| Command-Line Option | Description |
|-----|-----|
| *StorePath* | Indicates a folder where files and settings will be saved. Note that *StorePath* cannot be **C:&#92;**. You must specify the *StorePath* option in the **ScanState** command, except when using the **/genconfig** option. You cannot specify more than one *StorePath* location. |
| *StorePath* | Indicates a folder where files and settings will be saved. *StorePath* can't be `C:\`. You must specify the *StorePath* option in the `ScanState.exe` command, except when using the `/genconfig` option. You can't specify more than one *StorePath* location. |
| **/apps** | Scans the image for apps and includes them and their associated registry settings. |
| **/ppkg** [*&lt;FileName&gt;*] | Exports to a specific file 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 **&lt;ErrorControl&gt;** section. <br/><br/>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:** *&lt;KeyString&gt;* &#124; **/keyfile**:*&lt;file&gt;*]} | 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: <ul><li>**/key:** *KeyString* specifies the encryption key. If there is a space in *KeyString*, you will need to surround *KeyString* with quotation marks.</li><li>**/keyfile:** *FilePathAndName* specifies a text (.txt) file that contains the encryption key.</li></ul> <br/>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. <div class="alert">**Important**<br/>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.</div> <br/>The following example shows the ScanState command and the **/key** option: <br/>`scanstate /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt**:*&lt;EncryptionStrength&gt;* | 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](usmt-migration-store-encryption.md). |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; 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. <br/><br/>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. <br/><br/>For example:<br/>`scanstate /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /nocompress` |
| **/o** | Required to overwrite any existing data in the migration store or `Config.xml` file. If not specified, the `ScanState.exe` command will fail if the migration store already contains data. You can't 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 **&lt;ErrorControl&gt;** section. <br/><br/>This option is only used with the **ScanState** executable file and can't 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:** *&lt;KeyString&gt;* &#124; **/keyfile**:*&lt;file&gt;*]} | Encrypts the store with the specified key. Encryption is disabled by default. With this option, you'll need to specify the encryption key-in one of the following ways: <ul><li>`/key`: *KeyString* specifies the encryption key. If there's a space in *KeyString*, you'll need to surround *KeyString* with quotation marks (`"`).</li><li>`/keyfile`: *FilePathAndName* specifies a text (`.txt`) file that contains the encryption key.</li></ul> <br/>*KeyString* is recommended to be at least eight characters long, but it can't exceed 256 characters. The `/key` and `/keyfile` options can't be used on the same command line. The `/encrypt` and `/nocompress` options can't be used on the same command line. <div class="alert">**Important**<br/>Use caution when using the `/key` or `keyfile` options. For example, anyone who has access to scripts that run the `ScanState.exe` command with these options will also have access to the encryption key.</div> <br/>The following example shows the `ScanState.exe` command and the `/key` option: <br/>`scanstate.exe /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /encrypt /key:mykey` |
| **/encrypt**:*&lt;EncryptionStrength&gt;* | 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](usmt-migration-store-encryption.md). |
| **/nocompress** | Disables compression of data and saves the files to a hidden folder named &quot;File&quot; 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're combining the `/nocompress` option with the `/hardlink` option. <br/><br/>The `/nocompress` and `/encrypt` options can't be used together in one statement on the command line. However, if you do choose to migrate an uncompressed store, the `LoadState.exe` command will migrate each file directly from the store to the correct location on the destination computer without a temporary location. <br/><br/>For example:<br/>`scanstate.exe /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /nocompress` |
## <a href="" id="run-the-scanstate-command-on-an-offline-windows-system-"></a>Run the ScanState Command on an Offline Windows System
## Run the ScanState command on an offline Windows system
You can run the **ScanState** command in Windows Preinstallation Environment (WinPE). 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 WinPE or a Windows.old directory when you run the **ScanState** command in Windows.
You can run the `ScanState.exe` command in Windows Preinstallation Environment (WinPE). 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.exe` command in WinPE or a Windows.old directory when you run the `ScanState.exe` command in Windows.
There are several benefits to running the **ScanState** command on an offline Windows image, including:
There are several benefits to running the `ScanState.exe` command on an offline Windows image, including:
- **Improved Performance.**
- **Improved performance.**
Because WinPE 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.
Because WinPE is a thin operating system, there are fewer running services. In this environment, the `ScanState.exe` command has more access to the local hardware resources, enabling **ScanState** to perform migration operations more quickly.
- **Simplified end to end deployment process.**
@ -97,68 +79,68 @@ There are several benefits to running the **ScanState** command on an offline Wi
- **Improved success of migration.**
The migration success rate is increased because files will not be locked for editing while offline, and because WinPE provides administrator access to files in the offline Windows file system, eliminating the need for administrator-level access to the online system.
The migration success rate is increased because files won't be locked for editing while offline, and because WinPE 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
## 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 WinPE.|
|**/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.|
|**/offlinewindir:** *"path to a Windows directory"*|This option specifies the offline Windows directory that the `ScanState.exe` command gathers user state from. The offline directory can be Windows.old when you run the `ScanState.exe` command in Windows or a Windows directory when you run the `ScanState.exe` command in WinPE.|
|**/offlinewinold:** *"Windows.old directory"*|This command-line option enables the offline migration mode and starts the migration from the location specified. It's only intended to be used in Windows.old migration scenarios, where the migration is occurring from a Windows.old directory.|
## <a href="" id="bkmk-migrationruleoptions"></a>Migration Rule Options
## Migration rule options
USMT provides the following options to specify what files you want to migrate.
| Command-Line Option | Description |
|-----|-----|
| **/i:**[*Path*]*FileName* | **(include)** <br/><br/>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 &quot;XML Files&quot; section of the [Frequently Asked Questions](usmt-faq.yml) topic. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**) <br/><br/>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.<br/><br/>After you create this file, you will need to make use of it with the **ScanState** command using the **/config** option.<br/><br/>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.<br/><br/>Examples: <ul><li>The following example creates a Config.xml file in the current directory:<br/>`scanstate /i:migapp.xml /i:migdocs.xml /genconfig:config.xml /v:13`</li></ul> |
| **/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.<br/><br/>The following example creates a store using the Config.xml file, MigDocs.xml, and MigApp.xml files:<br/>`scanstate \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:scan.log`<br/><br/>The following example migrates the files and settings to the destination computer using the **Config.xml**, **MigDocs.xml**, and **MigApp.xml** files:<br/>`loadstate \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:load.log` |
| **/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. |
| **/targetwindows8** | Optimizes Scanstate.exe when using USMT 10.0 to migrate a user state to Windows 8 or Windows 8.1 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a Config.xml file by using the /genconfig option.** Using the **/targetwindows8** option optimizes the Config.xml file so that it only contains components that relate to Windows 8 or Windows 8.1.</li><li>**To create a migration store.** Using the **/targetwindows8** option ensures that the ScanState tool gathers the correct set of operating system settings. Without the **/targetwindows8** command-line option, some settings can be lost during the migration.</li></ul> |
| **/targetwindows7** | Optimizes Scanstate.exe when using USMT 10.0 to migrate a user state to Windows 7 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a Config.xml file by using the /genconfig option.** Using the **/targetwindows7** option optimizes the Config.xml file so that it only contains components that relate to Windows 7.</li><li>**To create a migration store.** Using the **/targetwindows7** option ensures that the ScanState tool gathers the correct set of operating system settings. Without the **/targetwindows7** command-line option, some settings can be lost during the migration.</li></ul> |
| **/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.<br/><br/>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](usmt-exclude-files-and-settings.md).<br/><br/>The **/localonly** command-line option includes or excludes data in the migration as identified in the following:<ul><li>**Removable drives such as a USB flash drive** - Excluded</li><li>**Network drives** - Excluded</li><li>**Fixed drives** - Included</li></ul>|
| **/i:**[*Path*]*FileName* | **(include)** <br/><br/>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 don't specify the *Path* variable, then *FileName* must be located in the current directory. For more information about which files to specify, see the &quot;XML Files&quot; section of the [Frequently asked questions](usmt-faq.yml) article. |
| **/genconfig:**[*Path*]*FileName* | (Generate **Config.xml**) <br/><br/>Generates the optional `Config.xml` file, but doesn't 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.<br/><br/>After you create this file, you'll need to make use of it with the `ScanState.exe` command using the **/config** option.<br/><br/>The only options that you can specify with this option are the `/i`, `/v`, and `/l` options. You can't specify *StorePath*, because the `/genconfig` option doesn't create a store. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory.<br/><br/>Examples: <ul><li>The following example creates a `Config.xml` file in the current directory:<br/>`scanstate.exe /i:migapp.xml /i:migdocs.xml /genconfig:config.xml /v:13`</li></ul> |
| **/config:**[*Path*]*FileName* | Specifies the `Config.xml` file that the `ScanState.exe` command should use to create the store. You can't use this option more than once on the command line. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* must be located in the current directory.<br/><br/>The following example creates a store using the `Config.xml` file, `MigDocs.xml`, and `MigApp.xml` files:<br/>`scanstate.exe \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:scan.log`<br/><br/>The following example migrates the files and settings to the destination computer using the `Config.xml`, `MigDocs.xml`, and `MigApp.xml` files:<br/>`loadstate.exe \server\share\migration\mystore /config:config.xml /i:migdocs.xml /i:migapp.xml /v:13 /l:load.log` |
| **/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.exe` 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.exe` command is running. |
| **/targetwindows8** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 8 or Windows 8.1 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a `Config.xml` file by using the `/genconfig` option.** Using the `/targetwindows8` option optimizes the `Config.xml` file so that it only contains components that relate to Windows 8 or Windows 8.1.</li><li>**To create a migration store.** Using the `/targetwindows8` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows8` command-line option, some settings can be lost during the migration.</li></ul> |
| **/targetwindows7** | Optimizes `ScanState.exe` when using USMT 10.0 to migrate a user state to Windows 7 instead of Windows 10. You should use this command-line option in the following scenarios: <ul><li>**To create a `Config.xml` file by using the `/genconfig` option.** Using the **/targetwindows7** option optimizes the `Config.xml` file so that it only contains components that relate to Windows 7.</li><li>**To create a migration store.** Using the `/targetwindows7` option ensures that the **ScanState** tool gathers the correct set of operating system settings. Without the `/targetwindows7` command-line option, some settings can be lost during the migration.</li></ul> |
| **/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 isn't specified, then the `ScanState.exe` command will copy files from these removable or network drives into the store.<br/><br/>Anything that isn't 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](usmt-exclude-files-and-settings.md).<br/><br/>The `/localonly` command-line option includes or excludes data in the migration as identified in the following storage locations:<ul><li>**Removable drives such as a USB flash drive** - Excluded</li><li>**Network drives** - Excluded</li><li>**Fixed drives** - Included</li></ul>|
## 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.
> 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**:&lt;FileName&gt; | 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. <br/><br/>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. <br/><br/>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: &quot;USMT was unable to create the log file(s)&quot;. To fix this issue, use the /**l: scan.log** command. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the ScanState log file. The default value is 0. <br/><br/>You can set the *VerbosityLevel* to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> <br/>For example: <br/>`scanstate \server\share\migration\mystore /v:13 /i:migdocs.xml /i:migapp.xml`|
| /**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.<br/><br/>For example: <br/>`scanstate /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /progress:prog.log /l:scanlog.log` |
| **/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.<br/><br/>You can use the new &lt;**ErrorControl**&gt; 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 advantage in the Config.xml file 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 &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the Config.xml file. |
| **/r:***&lt;TimesToRetry&gt;* | **(Retry)**<br/><br/>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.<br/><br/>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. |
| **/listfiles**:&lt;FileName&gt; | You can use the `/listfiles` command-line option with the `ScanState.exe` 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. <br/><br/>You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't 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. <br/><br/>If you run the `ScanState.exe` command from a shared network resource, you must specify the `/l` option, or USMT will fail with the following error:<br><br>***USMT was unable to create the log file(s)***<br><br>To fix this issue, make sure to specify the `/l` option when running `ScanState.exe` from a shared network resource. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **ScanState** log file. The default value is 0. <br/><br/>You can set the *VerbosityLevel* to one of the following levels: <ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> <br/>For example: <br/>`scanstate.exe \server\share\migration\mystore /v:13 /i:migdocs.xml /i:migapp.xml`|
| **/progress**:[*Path*]*FileName* | Creates the optional progress log. You can't store any of the log files in *StorePath*. *Path* can be either a relative or full path. If you don't specify the *Path* variable, then *FileName* will be created in the current directory.<br/><br/>For example: <br/>`scanstate.exe /i:migapp.xml /i:migdocs.xml \server\share\migration\mystore /progress:prog.log /l:scanlog.log` |
| **/c** | When this option is specified, the `ScanState.exe` 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's a large file that won't fit in the store, the `ScanState.exe` 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.exe` command will exit on the first error.<br/><br/>You can use the new &lt;**ErrorControl**&gt; 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 advantage in the `Config.xml` file 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 &lt;**ErrorControl**&gt; section that is enabled by specifying error messages and desired behaviors in the `Config.xml` file. |
| **/r:***&lt;TimesToRetry&gt;* | **(Retry)**<br/><br/>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 isn't reliable.<br/><br/>While storing the user state, the `/r` option won't 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:***&lt;SecondsBeforeRetry&gt;* | **(Wait)**<br/><br/>Specifies the time to wait, in seconds, before retrying a network file operation. The default is 1 second. |
| **/p:***&lt;pathToFile&gt;* | 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:<br/>`Scanstate.exe C:\MigrationLocation [additional parameters]`<br/>`/p:"C:\MigrationStoreSize.xml"`<br/><br/>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br/><br/>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, you can use the **/p** option, without specifying *&quot;pathtoafile&quot;*, 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. |
| **/p:***&lt;pathToFile&gt;* | When the `ScanState.exe` 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:<br/>`Scanstate.exe C:\MigrationLocation [additional parameters]`<br/>`/p:"C:\MigrationStoreSize.xml"`<br/><br/>For more information, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md).<br/><br/>To preserve the functionality of existing applications or scripts that require the previous behavior of USMT, you can use the `/p` option, without specifying *&quot;pathtoafile&quot;*, 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. |
## <a href="" id="bkmk-useroptions"></a>User Options
## 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](usmt-identify-users.md) and [Migrate User Accounts](usmt-migrate-user-accounts.md).
By default, all users are migrated. The only way to specify which users to include and exclude is by using the following options. You can't exclude users in the migration .xml files or using the `Config.xml` file. For more information, see [Identify users](usmt-identify-users.md) and [Migrate user accounts](usmt-migrate-user-accounts.md).
| Command-Line Option | Description |
|-----|-----|
| /**all** | Migrates all of the users on the computer. <br/><br/>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**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>or<br/>/**ui**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User include)** <br/><br/>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 (<em>) wildcard character. When you specify a user name that contains spaces, you will need to surround it with quotation marks. <div class="alert">**Note**<br/>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.</div><br/>For example:<br/><ul><li>To include only User2 from the Fabrikam domain, type:<br/>`/ue:*\* /ui:fabrikam\user2`</li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that have been active or otherwise modified in the last 30 days, type:<br/>`/uel:30 /ui:fabrikam\*`<br/>In this example, a user account from the Contoso domain that was last modified two months ago will not be migrated.</li></ul><br/>For more examples, see the descriptions of the /**ue** and /**ui** options in this table. |
| /**uel**:*&lt;NumberOfDays&gt;*<br/>or<br/>/**uel**:*&lt;YYYY/MM/DD&gt;*<br/>or<br/>**/uel:0** | **(User exclude based on last logon)**<br/><br/>Migrates the users that logged on to 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.<br/><br/>You can specify the 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 signed in to another computer, that sign-in instance is not considered by USMT. <div class="alert">**Note**<br/>The /**uel** option is not valid in offline migrations.</div><ul><li>**/uel:0** migrates any users who are currently logged on.</li><li>**/uel:90** migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>**/uel:1** migrates users whose account has been modified within the last 24 hours.</li><li>**/uel:2002/1/15** migrates users who have logged on or been modified January 15, 2002 or afterwards.</li></ul> <br/>For example: <br/>`scanstate /i:migapp.xml /i:migdocs.xml \\server\share\migration\mystore /uel:0` |
| /**ue**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>-or-<br/><br/>/**ue**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User exclude)**<br/><br/>Excludes the specified users from the migration. You can specify multiple /**ue** options. You cannot use this option with the /**all** option. *&lt;DomainName&gt;* and *&lt;UserName&gt;* can contain the asterisk (</em>) wildcard character. When you specify a user name that contains spaces, you need to surround it with quotation marks.<br/><br/>For example:<br/>`scanstate /i:migdocs.xml /i:migapp.xml \\server\share\migration\mystore /ue:contoso\user1` |
| **/all** | Migrates all of the users on the computer. <br/><br/>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 don't need to specify this option on the command line. However, if you choose to specify the `/all` option, you can't also use the `/ui`, `/ue` or `/uel` options. |
| **/ui**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>or<br/>**/ui**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User include)** <br/><br/>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 can't 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'll need to surround it with quotation marks (`"`). <div class="alert">**Note**<br/>If a user is specified for inclusion with the `/ui` option and also specified to be excluded with either the `/ue` or `/uel` options, the user will be included in the migration.</div><br/>For example:<br/><ul><li>To include only User2 from the Fabrikam domain, type:<br/>`/ue:*\* /ui:fabrikam\user2`</li><li>To migrate all users from the Fabrikam domain, and only the user accounts from other domains that have been active or otherwise modified in the last 30 days, type:<br/>`/uel:30 /ui:fabrikam\*`<br/>In this example, a user account from the Contoso domain that was last modified two months ago won't be migrated.</li></ul><br/>For more examples, see the descriptions of the `/ue` and `/ui` options in this table. |
| **/uel**:*&lt;NumberOfDays&gt;*<br/>or<br/>**/uel**:*&lt;YYYY/MM/DD&gt;*<br/>or<br/>**/uel:0** | **(User exclude based on last logon)**<br/><br/>Migrates the users that logged on to 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.exe` command is run.<br/><br/>You can specify the number of days or you can specify a date. You can't use this option with the `/all` option. USMT retrieves the last sign-in information from the local computer, so the computer doesn't need to be connected to the network when you run this option. In addition, if a domain user has signed in to another computer, that sign-in instance isn't considered by USMT. <div class="alert">**Note**<br/>The `/uel` option isn't valid in offline migrations.</div><ul><li>`/uel:0` migrates any users who are currently logged on.</li><li>`/uel:90` migrates users who have logged on, or whose accounts have been otherwise modified, within the last 90 days.</li><li>`/uel:1` migrates users whose account has been modified within the last 24 hours.</li><li>`/uel:2020/2/15` migrates users who have logged on or been modified February 15, 2020 or afterwards.</li></ul> <br/>For example: <br/>`scanstate.exe /i:migapp.xml /i:migdocs.xml \\server\share\migration\mystore /uel:0` |
| **/ue**:*&lt;DomainName&gt;*&#92;*&lt;UserName&gt;*<br/>-or-<br/><br/>**/ue**:*&lt;ComputerName&gt;*&#92;*&lt;LocalUserName&gt;* | **(User exclude)**<br/><br/>Excludes the specified users from the migration. You can specify multiple `/ue` options. You can't use this option with the `/all` option. *&lt;DomainName&gt;* and *&lt;UserName&gt;* can contain the asterisk (`*`) wildcard character. When you specify a user name that contains spaces, you need to surround it with quotation marks (`"`).<br/><br/>For example:<br/>`scanstate.exe /i:migdocs.xml /i:migapp.xml \\server\share\migration\mystore /ue:contoso\user1` |
## How to Use /ui and /ue
## 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.
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|
|--- |--- |
@ -169,73 +151,73 @@ The following examples apply to both the /**ui** and /**ue** options. You can re
|Exclude all local users.|`/ue:%computername%\*`|
|Exclude users in all domains named User1, User2, and so on.|`/ue:*\user*`|
## Using the Options Together
## Using the options together
You can use the /**uel**, /**ue** and /**ui** options together to migrate only the users that you want migrated.
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 `/ui` option has precedence over the `/ue` and `/uel` options. If a user is specified for inclusion with the `/ui` option and also specified to be excluded with 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.
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're excluded by using the `/ue` option. For example, if you specify `/ue:fixed\user1 /uel:14`, the User1 will be migrated if they've logged on to the computer within the last 14 days.
|Behavior|Command|
|--- |--- |
|Include only User2 from the Fabrikam domain and exclude all other users.|`/ue:*\* /ui:fabrikam\user2`|
|Include only the local user named User1 and exclude all other users.|`/ue:*\* /ui:user1`|
|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 commands: <ul><li>On the **ScanState** command line, type: `/ue:*\* /ui:contoso\*`</li><li>On the **LoadState** command line, type: `/ue:contoso\user1`</li></ul>|
|Include only the domain users from Contoso, except Contoso\User1.|This behavior can't be completed using a single command. Instead, to migrate this set of users, you'll need to specify the following commands: <ul><li>On the `ScanState.exe` command line, type: `/ue:*\* /ui:contoso\*`</li><li>On the `LoadState.exe` command line, type: `/ue:contoso\user1`</li></ul>|
|Include only local (non-domain) users.|`/ue:*\* /ui:%computername%\*`|
## 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.
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](usmt-migrate-efs-files-and-certificates.md).
> [!NOTE]
> EFS certificates will be migrated automatically when migrating to Windows 7, Windows 8 or Windows 10. Therefore, you should specify the /**efs:copyraw** option with the **ScanState** command to migrate the encrypted files
> EFS certificates will be migrated automatically when migrating to Windows 7, Windows 8 or Windows 10. Therefore, you should specify the `/efs:copyraw` option with the `ScanState.exe` 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.<br/><br/>For example: <br/>`ScanState /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important** <br/>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder has been removed, the file will be encrypted during the migration using the credentials of the account used to run the LoadState tool. For more information, see [Migrate EFS Files and Certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
| **/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.exe` 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.exe` command to ignore EFS files. |
| **/efs:decryptcopy** | Causes the `ScanState.exe` command to decrypt the file, if possible, before saving it to the migration store, and to fail if the file can't be decrypted. If the `ScanState.exe` command succeeds, the file will be unencrypted in the migration store, and once you run the `LoadState.exe` command, the file will be copied to the destination computer. |
| **/efs:copyraw** | Causes the `ScanState.exe` 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.exe` command to migrate the encrypted file. Then, when you run the `LoadState.exe` command, the encrypted file and the EFS certificate will be automatically migrated.<br/><br/>For example: <br/>`scanstate.exe /i:migdocs.xml /i:migapp.xml \server\share\migration\mystore /efs:copyraw` <div class="alert">**Important** <br/>All files must be encrypted if the parent folder is encrypted. If the encryption attribute on a file inside an encrypted folder has been removed, the file will be encrypted during the migration using the credentials of the account used to run the **LoadState** tool. For more information, see [Migrate EFS files and certificates](usmt-migrate-efs-files-and-certificates.md).</div>|
## <a href="" id="bkmk-iclo"></a>Incompatible Command-Line Options
## 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.
The following table indicates which command-line options aren't compatible with the `ScanState.exe` 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 aren't compatible. For example, you can't use the `/nocompress` option with the `/encrypt` option.
|Command-Line Option|/keyfile|/nocompress|/genconfig|/all|
|--- |--- |--- |--- |--- |
|**/i**|||||
|**/o**|||||
|**/v**|||||
|/**nocompress**||||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**:*&lt;option&gt;*|||X||
|/**genconfig**|||N/A||
|/**config**|||X||
|**/nocompress**||||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**:*&lt;option&gt;*|||X||
|**/genconfig**|||N/A||
|**/config**|||X||
|*&lt;StorePath&gt;*|||X||
> [!NOTE]
> You must specify either the /**key** or /**keyfile** option with the /**encrypt** option.
> You must specify either the `/key` or `/keyfile` option with the `/encrypt` option.
## Related topics
## Related articles
[XML Elements Library](usmt-xml-elements-library.md)

45
windows/deployment/usmt/usmt-technical-reference.md
View File

@ -12,42 +12,43 @@ ms.custom: seo-marvel-apr2020
ms.technology: itpro-deploy
---
# User State Migration Tool (USMT) Technical Reference
The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK) for Windows 10. USMT provides a highly customizable user-profile migration experience for IT professionals.
# User State Migration Tool (USMT) technical reference
Download the Windows ADK [from this website](/windows-hardware/get-started/adk-install).
The User State Migration Tool (USMT) is included with the Windows Assessment and Deployment Kit (Windows ADK) for Windows 10. USMT provides a highly customizable user-profile migration experience for IT professionals.
**USMT support for Microsoft Office**
>USMT in the Windows ADK for Windows 10, version 1511 (10.1.10586.0) supports migration of user settings for installations of Microsoft Office 2003, 2007, 2010, and 2013.<BR>
>USMT in the Windows ADK for Windows 10, version 1607 (10.1.14393.0) adds support for migration of user settings for installations of Microsoft Office 2016.
Download the Windows ADK [from this website](/windows-hardware/get-started/adk-install).
## USMT support for Microsoft Office
- USMT in the Windows ADK for Windows 10, version 1511 (10.1.10586.0) supports migration of user settings for installations of Microsoft Office 2003, 2007, 2010, and 2013.
- USMT in the Windows ADK for Windows 10, version 1607 (10.1.14393.0) adds support for migration of user settings for installations of Microsoft Office 2016.
USMT includes three command-line tools:
- ScanState.exe<BR>
- LoadState.exe<BR>
- ScanState.exe
- LoadState.exe
- UsmtUtils.exe
USMT also includes a set of three modifiable .xml files:
- MigApp.xml<BR>
- MigDocs.xml<BR>
- MigApp.xml
- MigDocs.xml
- MigUser.xml
Additionally, you can create custom .xml files to support your migration needs. You can also create a Config.xml file to specify files or settings to exclude from the migration.
Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
USMT tools can be used on several versions of Windows operating systems, for more information, see [USMT Requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) 4.0 User's Guide](/previous-versions/windows/server/dd560801(v=ws.10)).
USMT tools can be used on several versions of Windows operating systems, for more information, see [USMT requirements](usmt-requirements.md). For more information about previous releases of the USMT tools, see [User State Migration Tool (USMT) overview](/previous-versions/windows/hh825227(v=win.10)).
## In this section
|Topic |Description|
|Article |Description|
|------|-----------|
|[User State Migration Tool (USMT) Overview Topics](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.|
|[User State Migration Tool (USMT) How-to topics](usmt-how-to.md)|Includes step-by-step instructions for using USMT, as well as how-to topics for conducting tasks in USMT.|
|[User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md)|Provides answers to frequently asked questions and common issues in USMT, as well as a reference for return codes used in USMT.|
|[User State Migration Toolkit (USMT) Reference](usmt-reference.md)|Includes reference information for migration planning, migration best practices, command-line syntax, using XML, and requirements for using USMT.|
|[User State Migration Tool (USMT) overview topics](usmt-topics.md)|Describes what's new in USMT, how to get started with USMT, and the benefits and limitations of using USMT.|
|[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)|Includes step-by-step instructions for using USMT and how-to topics for conducting tasks in USMT.|
|[User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)|Provides answers to frequently asked questions and common issues in USMT and a reference for return codes used in USMT.|
|[User State Migration Toolkit (USMT) reference](usmt-reference.md)|Includes reference information for migration planning, migration best practices, command-line syntax, using XML, and requirements for using USMT.|
## Related articles
## Related topics
- [Windows Assessment and Deployment Kit](/previous-versions/windows/it-pro/windows-8.1-and-8/dn247001(v=win.10))
 
 

32
windows/deployment/usmt/usmt-test-your-migration.md
View File

@ -11,32 +11,26 @@ ms.topic: article
ms.technology: itpro-deploy
---
# Test Your Migration
# Test your migration
Always test your migration plan in a controlled laboratory setting before you deploy it to your entire organization. In your test environment, you need at least one computer for each type of operating system from which you're migrating data.
Always test your migration plan in a controlled laboratory setting before you deploy it to your entire organization. In your test environment, you need at least one computer for each type of operating system from which you are migrating data.
After you've thoroughly tested the entire migration process on a single computer running each of your source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust your initial calculations accordingly. For details about estimating the space needed for your migration, see [Estimate migration store size](usmt-estimate-migration-store-size.md). You might also need to adjust the registry-setting and file-location information in your migration-rule files. If you make changes, test the migration again. Then verify that all data and settings have migrated as expected. A pilot migration also gives you an opportunity to test your space estimates for the intermediate store.
After you have thoroughly tested the entire migration process on a single computer running each of your source operating systems, conduct a pilot migration with a small group of users. After migrating a few typical user states to the intermediate store, note the space required and adjust your initial calculations accordingly. For details about estimating the space needed for your migration, see [Estimate Migration Store Size](usmt-estimate-migration-store-size.md). You might also need to adjust the registry-setting and file-location information in your migration-rule files. If you make changes, test the migration again. Then verify that all data and settings have migrated as expected. A pilot migration also gives you an opportunity to test your space estimates for the intermediate store.
If your test migration encounters any errors, examine the **ScanState** and **LoadState** logs to obtain the exact User State Migration Tool (USMT) 10.0 return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return codes](usmt-return-codes.md). You can obtain more information about any listed **Windows** system error codes by typing in a command prompt window `net.exe helpmsg <error_number>` where *<error_number>* is the error code number generated by the error message. For more information about System Error Codes, see [System Error Codes (0-499)](/windows/win32/debug/system-error-codes--0-499-).
If your test migration encounters any errors, examine the ScanState and LoadState logs to obtain the exact User State Migration Tool (USMT) 10.0 return code and associated error messages or Windows application programming interface (API) error message. For more information about USMT return codes and error messages, see [Return Codes](usmt-return-codes.md). You can also obtain more information about a Windows API error message by typing **net helpmsg** and the error message number on the command line.
In most cases, the **ScanState** and **LoadState** logs indicate why a USMT migration is failing. We recommend that you use the `/v:5` option when testing your migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a higher verbosity level if you want the log files output to go to a debugger.
In most cases, the ScanState and LoadState logs indicate why a USMT migration is failing. We recommend that you use the **/v**<em>:5</em> option when testing your migration. This verbosity level can be adjusted in a production migration. Reducing the verbosity level might make it more difficult to diagnose failures that are encountered during production migrations. You can use a higher verbosity level if you want the log files output to go to a debugger.
> [!NOTE]
> Running the **ScanState** and **LoadState** tools with the `/v:5` option creates a detailed log file. Although this option makes the log file large, it is helpful in determining where migration errors occurred.
**Note**  
Running the ScanState and LoadState tools with the **/v**<em>:5</em> option creates a detailed log file. Although this option makes the log file large, it is helpful in determining where migration errors occurred.
After you've determined that the pilot migration successfully migrated the specified files and settings, you're ready to add USMT to the server that is running Microsoft Configuration Manager, or a non-Microsoft management technology. For more information, see [Manage user state in Configuration Manager](/configmgr/osd/get-started/manage-user-state).
> [!NOTE]
> For testing purposes, you can create an uncompressed store using the `/hardlink /nocompress` option. When compression is disabled, the **ScanState** tool saves the files and settings to a hidden folder named **File** at `<StorePath>\USMT`. You can use the uncompressed store to view what USMT has stored or to troubleshoot a problem, or you can run an antivirus utility against the files. Additionally, you can also use the `/listfiles` command-line option and the diagnostic log to list the files that were gathered and to troubleshoot problems with your migration.
## Related articles
After you have determined that the pilot migration successfully migrated the specified files and settings, you are ready to add USMT to the server that is running Microsoft Configuration Manager, or a non-Microsoft management technology. For more information, see [Manage user state in Configuration Manager](/configmgr/osd/get-started/manage-user-state).
[Plan your migration](usmt-plan-your-migration.md)
**Note**  
For testing purposes, you can create an uncompressed store using the **/hardlink /nocompress** option. When compression is disabled, the ScanState tool saves the files and settings to a hidden folder named "File" at *StorePath*\\USMT. You can use the uncompressed store to view what USMT has stored or to troubleshoot a problem, or you can run an antivirus utility against the files. Additionally, you can also use the **/listfiles** command-line option and the diagnostic log to list the files that were gathered and to troubleshoot problems with your migration.
## Related topics
[Plan Your Migration](usmt-plan-your-migration.md)
[Log Files](usmt-log-files.md)
[Log files](usmt-log-files.md)

26
windows/deployment/usmt/usmt-topics.md
View File

@ -1,6 +1,6 @@
---
title: User State Migration Tool (USMT) Overview Topics (Windows 10)
description: Learn about User State Migration Tool (USMT) overview topics that describe USMT as a highly customizable user-profile migration experience for IT professionals.
description: Learn about User State Migration Tool (USMT) overview articles that describe USMT as a highly customizable user-profile migration experience for IT professionals.
ms.reviewer:
manager: aaroncz
ms.author: frankroj
@ -11,18 +11,20 @@ ms.topic: article
ms.technology: itpro-deploy
---
# User State Migration Tool (USMT) Overview Topics
The User State Migration Tool (USMT) 10.0 provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: ScanState.exe, LoadState.exe, and UsmtUtils.exe. USMT also includes a set of three modifiable .xml files: MigApp.xml, MigDocs.xml, and MigUser.xml. Additionally, you can create custom .xml files to support your migration needs. You can also create a Config.xml file to specify files or settings to exclude from the migration.
# User State Migration Tool (USMT) overview topics
## In This Section
The User State Migration Tool (USMT) 10.0 provides a highly customizable user-profile migration experience for IT professionals. USMT includes three command-line tools: `ScanState.exe`, `LoadState.exe`, and `UsmtUtils.exe`. USMT also includes a set of three modifiable .xml files: `MigApp.xml`, `MigDocs.xml`, and `MigUser.xml`. Additionally, you can create custom .xml files to support your migration needs. You can also create a `Config.xml` file to specify files or settings to exclude from the migration.
|Topic |Description|
## In this section
|Article |Description|
|------|-----------|
|[User State Migration Tool (USMT) Overview](usmt-overview.md)|Describes the benefits and limitations of using USMT.|
|[Getting Started with the User State Migration Tool (USMT)](getting-started-with-the-user-state-migration-tool.md)|Describes the general process to follow to migrate files and settings, and provides links to more information.|
|[Windows Upgrade and Migration Considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft® tools you can use to move files and settings between installations, as well as special considerations for performing an upgrade or migration.|
|[User State Migration Tool (USMT) overview](usmt-overview.md)|Describes the benefits and limitations of using USMT.|
|[Getting started with the User State Migration Tool (USMT)](getting-started-with-the-user-state-migration-tool.md)|Describes the general process to follow to migrate files and settings, and provides links to more information.|
|[Windows upgrade and migration considerations](../upgrade/windows-upgrade-and-migration-considerations.md)|Discusses the Microsoft® tools you can use to move files and settings between installations and special considerations for performing an upgrade or migration.|
## Related topics
- [User State Migration Tool (USMT) How-to topics](usmt-how-to.md)
- [User State Migration Tool (USMT) Troubleshooting](usmt-troubleshooting.md)
- [User State Migration Toolkit (USMT) Reference](usmt-reference.md)
## Related articles
- [User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
- [User State Migration Tool (USMT) troubleshooting](usmt-troubleshooting.md)
- [User State Migration Toolkit (USMT) reference](usmt-reference.md)

18
windows/deployment/usmt/usmt-troubleshooting.md
View File

@ -1,6 +1,6 @@
---
title: User State Migration Tool (USMT) Troubleshooting (Windows 10)
description: Learn about topics that address common User State Migration Tool (USMT) 10.0 issues and questions to assist in troubleshooting.
description: Learn about topics that address common User State Migration Tool (USMT) 10.0 issues and questions to help troubleshooting.
ms.reviewer:
manager: aaroncz
ms.author: frankroj
@ -11,11 +11,11 @@ ms.topic: article
ms.technology: itpro-deploy
---
# User State Migration Tool (USMT) Troubleshooting
# User State Migration Tool (USMT) troubleshooting
The following table describes topics that address common User State Migration Tool (USMT) 10.0 issues and questions. These topics describe tools that you can use to troubleshoot issues that arise during your migration.
The following table describes articles that address common User State Migration Tool (USMT) 10.0 issues and questions. These articles describe tools that you can use to troubleshoot issues that arise during your migration.
## In This Section
## In this section
| Link | Description |
|--- |--- |
@ -25,12 +25,12 @@ The following table describes topics that address common User State Migration To
|[Return Codes](usmt-return-codes.md)|Learn how to use return codes to identify problems in USMT.|
|[USMT Resources](usmt-resources.md)|Find more information and support for using USMT.|
## Related topics
## Related articles
[USMT Best Practices](usmt-best-practices.md)
[USMT best practices](usmt-best-practices.md)
[User State Migration Tool (USMT) Overview Topics](usmt-topics.md)
[User State Migration Tool (USMT) overview topics](usmt-topics.md)
[User State Migration Tool (USMT) How-to topics](usmt-how-to.md)
[User State Migration Tool (USMT) how-to topics](usmt-how-to.md)
[User State Migration Toolkit (USMT) Reference](usmt-reference.md)
[User State Migration Toolkit (USMT) reference](usmt-reference.md)

89
windows/deployment/usmt/usmt-utilities.md
View File

@ -1,6 +1,6 @@
---
title: UsmtUtils Syntax (Windows 10)
description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface.
description: Learn about the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface.
ms.reviewer:
manager: aaroncz
ms.author: frankroj
@ -13,97 +13,88 @@ ms.technology: itpro-deploy
# UsmtUtils Syntax
This topic describes the syntax for the utilities available in User State Migration Tool (USMT) 10.0 through the command-line interface. These utilities:
This article describes the syntax for the utilities available in User State Migration Tool (USMT) 10.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.
- Help removing hard-link stores that can't 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.
## In This Topic
## UsmtUtils.exe
[Usmtutils.exe](#bkmk-usmtutils-exe)
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.
[Verify Options](#bkmk-verifyoptions)
The syntax for `UsmtUtils.exe` is:
[Extract Options](#bkmk-extractoptions)
## <a href="" id="bkmk-usmtutils-exe"></a>Usmtutils.exe
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 *&lt;storeDir&gt;* | /verify *&lt;filepath&gt;* \[options\] | /extract *&lt;filepath&gt;* *&lt;destinationPath&gt;* \[options\]\]
> UsmtUtils.exe \[/ec | /rd *&lt;storeDir&gt;* | /verify *&lt;filepath&gt;* \[options\] | /extract *&lt;filepath&gt;* *&lt;destinationPath&gt;* \[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** *&lt;storeDir&gt;* |Removes the directory path specified by the *&lt;storeDir&gt;* 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. <br/><br/>For example:<br/>`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. <br/><br/>See [Verify Options](#bkmk-verifyoptions) for syntax and options to use with **/verify**.|
|**/extract**|Recovers files from a compressed USMT migration store. <br/><br/>See [Extract Options](#bkmk-extractoptions) for syntax and options to use with **/extract**.|
|**/ec**|Returns a list of supported cryptographic algorithms (AlgIDs) on the current system. You can use this option 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** *&lt;storeDir&gt;* |Removes the directory path specified by the *&lt;storeDir&gt;* argument on the computer. You can use this command to delete hard-link migration stores that can't 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. <br/><br/>For example:<br/>`UsmtUtils.exe /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 won't 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. <br/><br/>See [Verify options](#verify-options) for syntax and options to use with `/verify`.|
|**/extract**|Recovers files from a compressed USMT migration store. <br/><br/>See [Extract options](#extract-options) for syntax and options to use with `/extract`.|
## <a href="" id="bkmk-verifyoptions"></a>Verify Options
## Verify options
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](verify-the-condition-of-a-compressed-migration-store.md).
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](verify-the-condition-of-a-compressed-migration-store.md).
The syntax for **/verify** is:
The syntax for `/verify` is:
usmtutils /verify\[:*&lt;reportType&gt;*\] *&lt;filePath&gt;* \[/l:*&lt;logfile&gt;*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*&lt;AlgID&gt;*\] {/key:*&lt;keystring&gt;* | /keyfile:*&lt;filename&gt;*}\]
> UsmtUtils.exe /verify\[:*&lt;reportType&gt;*\] *&lt;filePath&gt;* \[/l:*&lt;logfile&gt;*\] \[/v:*VerbosityLevel*\] \[/decrypt \[:*&lt;AlgID&gt;*\] {/key:*&lt;keystring&gt;* | /keyfile:*&lt;filename&gt;*}\]
| Command-line Option | Description |
|-----|--------|
| *&lt;reportType&gt;* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. <ul><li>**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.</li><li>**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 &quot;CATALOG&quot; 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 &quot;OK&quot; if the catalog file is intact and LoadState can open the migration store and &quot;CORRUPTED&quot; if the migration store is corrupted.</li><li>**failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.</li><li>**Catalog**. Returns only the status of the catalog file.</li></ul> |
| *&lt;reportType&gt;* | Specifies whether to report on all files, corrupted files only, or the status of the catalog. <ul><li>**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.</li><li>**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 &quot;OK&quot; if the catalog file is intact and **LoadState** can open the migration store and &quot;CORRUPTED&quot; if the migration store is corrupted.</li><li>**failureonly**. Returns a tab-delimited list of only the files that are corrupted in the compressed migration store.</li><li>**Catalog**. Returns only the status of the catalog file.</li></ul> |
| **/l:** <br/>*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:** *&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the UsmtUtils log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt** *&lt;AlgID&gt;* **/**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt** *&lt;AlgID&gt;* **/**:*&lt;“Key String”&gt;*<br/>or<br/>**/decrypt:** *&lt;AlgID&gt;* **/keyfile**:*&lt;FileName&gt;* | 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:<br/><ul><li>*&lt;AlgID&gt;* 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.<br/>*&lt;AlgID&gt;* valid values include: AES_128, AES_192, AES_256, 3DES, or 3DES_112.</li><li>**/key:** *&lt;KeyString&gt;* specifies the encryption key. If there is a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li>**/keyfile**: *&lt;FileName&gt;* specifies the location and name of a text (.txt) file that contains the encryption key.</li></ul><br/>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md) |
| **/v:** *&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt** *&lt;AlgID&gt;* **/**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt** *&lt;AlgID&gt;* **/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:** *&lt;AlgID&gt;* **/keyfile**:*&lt;FileName&gt;* | 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:<br/><ul><li>*&lt;AlgID&gt;* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li> `/key:` *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li> `/keyfile`: *&lt;FileName&gt;* specifies the location and name of a text (.txt) file that contains the encryption key.</li></ul><br/>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md) |
Some examples of **/verify** commands:
Some examples of `/verify` commands:
- `usmtutils /verify D:\MyMigrationStore\store.mig`
- `UsmtUtils.exe /verify D:\MyMigrationStore\store.mig`
- `usmtutils /verify:catalog D:\MyMigrationStore\store.mig`
- `UsmtUtils.exe /verify:catalog D:\MyMigrationStore\store.mig`
- `usmtutils /verify:all D:\MyMigrationStore\store.mig /decrypt /l:D:\UsmtUtilsLog.txt`
- `UsmtUtils.exe /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`
- `UsmtUtils.exe /verify:failureonly D:\MyMigrationStore\store.mig /decrypt:AES_192 /keyfile:D:\encryptionKey.txt`
## <a href="" id="bkmk-extractoptions"></a>Extract Options
## Extract options
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](usmt-extract-files-from-a-compressed-migration-store.md).
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](usmt-extract-files-from-a-compressed-migration-store.md).
The syntax for `/extract` is:
The syntax for **/extract** is:
/extract *&lt;filePath&gt;* *&lt;destinationPath&gt;* \[/i:*&lt;includePattern&gt;*\] \[/e: *&lt;excludePattern&gt;*\] \[/l: *&lt;logfile&gt;*\] \[/v: *VerbosityLevel&gt;*\] \[/decrypt\[:*&lt;AlgID&gt;*\] {key: *&lt;keystring&gt;* | /keyfile: *&lt;filename&gt;*}\] \[/o\]
> /extract *&lt;filePath&gt;* *&lt;destinationPath&gt;* \[/i:*&lt;includePattern&gt;*\] \[/e: *&lt;excludePattern&gt;*\] \[/l: *&lt;logfile&gt;*\] \[/v: *VerbosityLevel&gt;*\] \[/decrypt\[:*&lt;AlgID&gt;*\] {key: *&lt;keystring&gt;* | /keyfile: *&lt;filename&gt;*}\] \[/o\]
| Command-line Option | Description |
|-------|-----|
| *&lt;filePath&gt;* | Path to the USMT migration store. <br/><br/>For example:<br/>`D:\MyMigrationStore\USMT\store.mig` |
| *&lt;destinationPath&gt;* | Path to the folder where the tool puts the individual files. |
| **/i**:*&lt;includePattern&gt;* | 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**: *&lt;includePattern&gt;* and **/e**: *&lt;excludePattern&gt;* 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**:*&lt;excludePattern&gt;* | 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**: *&lt;includePattern&gt;* and **/e**: *&lt;excludePattern&gt;* options in the same command. When both include and exclude patterns are used on the command line, include patterns take precedence over exclude patterns. |
| **/i**:*&lt;includePattern&gt;* | 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`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* 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**:*&lt;excludePattern&gt;* | 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`: *&lt;includePattern&gt;* and `/e`: *&lt;excludePattern&gt;* 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**:*&lt;logfilePath&gt;* | Specifies the location and name of the log file. |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the UsmtUtils log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt***&lt;AlgID&gt;***/key**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt***&lt;AlgID&gt;***/**:*&lt;“Key String”&gt;*<br/>or<br/>**/decrypt:***&lt;AlgID&gt;***/keyfile**:*&lt;FileName&gt;* | 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:<br/><ul><li>*&lt;AlgID&gt;* 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.<br/>*&lt;AlgID&gt;* valid values include: AES_128, AES_192, AES_256, 3DES, or 3DES_112.</li><li>**/key**: *&lt;KeyString&gt;* specifies the encryption key. If there is a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li>**/keyfile**:*&lt;FileName&gt;* specifies a text (.txt) file that contains the encryption key</li></ul><br/>For more information about supported encryption algorithms, see [Migration Store Encryption](usmt-migration-store-encryption.md). |
| **/v:***&lt;VerbosityLevel&gt;* | **(Verbosity)**<br/><br/>Enables verbose output in the **UsmtUtils** log file. The default value is 0.<br/><br/>You can set the *VerbosityLevel* to one of the following levels:<br/><ul><li>**0** - Only the default errors and warnings are enabled.</li><li>**1** - Enables verbose output.</li><li>**4** - Enables error and status output.</li><li>**5** - Enables verbose and status output.</li><li>**8** - Enables error output to a debugger.</li><li>**9** - Enables verbose output to a debugger.</li><li>**12** - Enables error and status output to a debugger.</li><li>**13** - Enables verbose, status, and debugger output.</li></ul> |
| **/decrypt***&lt;AlgID&gt;***/key**:*&lt;KeyString&gt;*<br/>or<br/>**/decrypt***&lt;AlgID&gt;***/**:*&lt;"Key String"&gt;*<br/>or<br/>**/decrypt:***&lt;AlgID&gt;***/keyfile**:*&lt;FileName&gt;* | 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 the `/key` or `/keyfile` option as follows:<br/><ul><li>*&lt;AlgID&gt;* specifies the cryptographic algorithm that was used to create the migration store on the `ScanState.exe` command line. If no algorithm is specified, **ScanState** and **UsmtUtils** use the 3DES algorithm as a default.<br/>*&lt;AlgID&gt;* valid values include: `AES_128`, `AES_192`, `AES_256`, `3DES`, or `3DES_112`.</li><li>`/key`: *&lt;KeyString&gt;* specifies the encryption key. If there's a space in *&lt;KeyString&gt;*, you must surround the argument with quotation marks.</li><li>`/keyfile`:*&lt;FileName&gt;* specifies a text (.txt) file that contains the encryption key</li></ul><br/>For more information about supported encryption algorithms, see [Migration store encryption](usmt-migration-store-encryption.md). |
| **/o** | Overwrites existing output files. |
Some examples of **/extract** commands:
Some examples of `/extract` commands:
- `usmtutils /extract D:\MyMigrationStore\USMT\store.mig C:\ExtractedStore`
- `UsmtUtils.exe /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.exe /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.exe /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`
- `UsmtUtils.exe /extract D:\MyMigrationStore\USMT\store.mig /i:myProject.* /e:*.exe C:\ExtractedStore /o`
## Related topics
## Related articles
[User State Migration Tool (USMT) Command-line Syntax](usmt-command-line-syntax.md)
[User State Migration Tool (USMT) command-line syntax](usmt-command-line-syntax.md)
[Return Codes](usmt-return-codes.md)
[Return codes](usmt-return-codes.md)

123
windows/deployment/usmt/usmt-what-does-usmt-migrate.md
View File

@ -1,6 +1,6 @@
---
title: What does USMT migrate (Windows 10)
description: Learn how User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language.
description: Learn how User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language.
ms.reviewer:
manager: aaroncz
ms.author: frankroj
@ -13,35 +13,49 @@ ms.technology: itpro-deploy
# What does USMT migrate?
## <a href="" id="bkmk-defaultmigscripts"></a>Default migration scripts
## Default migration scripts
The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts:
The User State Migration Tool (USMT) 10.0 is designed so that an IT engineer can precisely define migrations using the USMT .xml scripting language. USMT provides the following sample scripts:
- **MigApp.XML.** Rules to migrate application settings.
- **MigApp.XML** - Rules to migrate application settings.
- **MigDocs.XML.** Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration .xml files.
- **MigDocs.XML** - Rules that use the **MigXmlHelper.GenerateDocPatterns** helper function, which can be used to automatically find user documents on a computer without the need to author extensive custom migration .xml files.
- **MigUser.XML.** Rules to migrate user profiles and user data.
- **MigUser.XML** - Rules to migrate user profiles and user data.
MigUser.xml gathers everything in a user’s profile and then does a file extension- based search of most of the system for other user data. If data doesn’t match either of these criteria, the data won’t be migrated. For the most part, this file describes a "core" migration.
`MigUser.xml` gathers everything in a user's profile and then does a file extension- based search of most of the system for other user data. If data doesn't match either of these criteria, the data won't be migrated. Usually, this file describes a core migration.
The following data does not migrate with MigUser.xml:
The following data doesn't migrate with `MigUser.xml`:
- Files outside the user profile that don’t match one of the file extensions in MigUser.xml.
- Files outside the user profile that don't match one of the file extensions in `MigUser.xml`.
- Access control lists (ACLs) for folders outside the user profile.
## <a href="" id="bkmk-3"></a>User data
## User data
This section describes the user data that USMT migrates by default, using the MigUser.xml file. It also defines how to migrate ACLs.
This section describes the user data that USMT migrates by default, using the `MigUser.xml` file. It also defines how to migrate access control lists (ACLs).
- **Folders from each user profile.** When you specify the MigUser.xml file, USMT migrates everything in a user’s profiles including the following:
- **Folders from each user profile.** When you specify the `MigUser.xml` file, USMT migrates everything in a user's profiles including the following items:
My Documents, My Video, My Music, My Pictures, desktop files, Start menu, Quick Launch settings, and Favorites.
- My Documents
- My Video
- My Music
- My Pictures
- Desktop files
- Start menu
- Quick Launch settings
- Favorites
> [!IMPORTANT]
> Starting in Windows 10, version 1607 the USMT does not migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](./usmt-common-issues.md#usmt-doesnt-migrate-the-start-layout).
- **Folders from the All Users and Public profiles.** When you specify the MigUser.xml file, USMT also migrates the following from the **All Users** profile in Windows® XP, or the **Public** profile in Windows Vista, Windows 7, or Windows 8:
- **Folders from the All Users and Public profiles.** When you specify the `MigUser.xml` file, USMT also migrates the following from the **Public** profile in Windows Vista, Windows 7, Windows 8, or Windows 10:
- Shared Documents
@ -57,21 +71,21 @@ This section describes the user data that USMT migrates by default, using the Mi
- Shared Favorites
- **File types.** When you specify the MigUser.xml file, the ScanState tool searches the fixed drives, collects, and then migrates files with any of the following file extensions:
- **File types.** When you specify the `MigUser.xml` file, the **ScanState** tool searches the fixed drives, collects, and then migrates files with any of the following file extensions:
**.accdb, .ch3, .csv, .dif, .doc\*, .dot\*, .dqy, .iqy, .mcw, .mdb\*, .mpp, .one\*, .oqy, .or6, .pot\*, .ppa, .pps\*, .ppt\*, .pre, .pst, .pub, .qdf, .qel, .qph, .qsd, .rqy, .rtf, .scd, .sh3, .slk, .txt, .vl\*, .vsd, .wk\*, .wpd, .wps, .wq1, .wri, .xl\*, .xla, .xlb, .xls\*.**
`.accdb`, `.ch3`, `.csv`, `.dif`, `.doc*`, `.dot*`, `.dqy`, `.iqy`, `.mcw`, `.mdb*`, `.mpp`, `.one*`, `.oqy`, `.or6`, `.pot*`, `.ppa`, `.pps*`, `.ppt*`, `.pre`, `.pst`, `.pub`, `.qdf`, `.qel`, `.qph`, `.qsd`, `.rqy`, `.rtf`, `.scd`, `.sh3`, `.slk`, `.txt`, `.vl*`, `.vsd`, `.wk*`, `.wpd`, `.wps`, `.wq1`, `.wri`, `.xl*`, `.xla`, `.xlb`, `.xls*`
> [!NOTE]
> The asterisk (\*) stands for zero or more characters.
> The asterisk (`*`) stands for zero or more characters.
- **Access control lists.** USMT migrates ACLs for specified files and folders from computers running both Windows® XP and Windows Vista. For example, if you migrate a file named File1.txt that is read-only for User1 and read/write for User2, these settings will still apply on the destination computer after the migration.
- **Access control lists.** USMT migrates access control lists (ACLs) for specified files and folders from computers running both Windows® XP and Windows Vista. For example, if you migrate a file named `File1.txt` that is **read-only** for **User1** and **read/write** for **User2**, these settings will still apply on the destination computer after the migration.
> [!IMPORTANT]
> To migrate ACLs, you must specify the directory to migrate in the MigUser.xml file. Using file patterns like \*.doc will not migrate a directory. The source ACL information is migrated only when you explicitly specify the directory. For example, `<pattern type="File">c:\test docs</pattern>`.
> [!IMPORTANT]
> To migrate ACLs, you must specify the directory to migrate in the MigUser.xml file. Using file patterns like \*.doc will not migrate a directory. The source ACL information is migrated only when you explicitly specify the directory. For example, `<pattern type="File">c:\test docs</pattern>`.
## <a href="" id="bkmk-4"></a>Operating-system components
## Operating-system components
USMT migrates operating-system components to a destination computer from computers running Windows 7 and Windows 8
USMT migrates operating-system components to a destination computer from computers running Windows 7 and Windows 8
The following components are migrated by default using the manifest files:
@ -81,7 +95,7 @@ The following components are migrated by default using the manifest files:
- Command-prompt settings
- \*Desktop wallpaper
- Desktop wallpaper **¹**
- EFS files
@ -91,9 +105,9 @@ The following components are migrated by default using the manifest files:
- Fonts
- Group membership. USMT migrates users’ group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. When running an offline migration, the use of a **&lt;ProfileControl&gt;** section in the Config.xml file is required.
- Group membership. USMT migrates users' group settings. The groups to which a user belongs can be found by right-clicking **My Computer** on the Start menu and then selecting **Manage**. When running an offline migration, the use of a **&lt;ProfileControl&gt;** section in the `Config.xml` file is required.
- \*Windows Internet Explorer® settings
- Windows Internet Explorer® settings **¹**
- Microsoft® Open Database Connectivity (ODBC) settings
@ -101,46 +115,47 @@ The following components are migrated by default using the manifest files:
- Network drive mapping
- \*Network printer mapping
- Network printer mapping **¹**
- \*Offline files
- Offline files **¹**
- \*Phone and modem options
- Phone and modem options **¹**
- RAS connection and phone book (.pbk) files
- \*Regional settings
- Regional settings **¹**
- Remote Access
- \*Taskbar settings
- Taskbar settings **¹**
- User personal certificates (all)
- Windows Mail.
- Windows Mail
- \*Windows Media Player
- Windows Media Player **¹**
- Windows Rights Management
\* These settings aren't available for an offline migration. For more information, see [Offline Migration Reference](offline-migration-reference.md).
**¹** These settings aren't available for an offline migration. For more information, see [Offline migration reference](offline-migration-reference.md).
> [!IMPORTANT]
> This list may not be complete. There may be additional components that are migrated.
> [!NOTE]
> Some settings, such as fonts, aren't applied by the LoadState tool until after the destination computer has been restarted. For this reason, restart the destination computer after you run the LoadState tool.
> Some settings, such as fonts, aren't applied by the **LoadState** tool until after the destination computer has been restarted. For this reason, restart the destination computer after you run the **LoadState** tool.
## <a href="" id="bkmk-2"></a>Supported applications
## Supported applications
Even though it's not required for all applications, it's good practice to install all applications on the destination computer before restoring the user state. Installing applications before migrating settings helps to ensure that migrated settings aren't overwritten by the application installers.
> [!NOTE]
>
> - The versions of installed applications must match on the source and destination computers. USMT does not support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office.
> - USMT migrates only the settings that have been used or modified by the user. If there is an application setting on the source computer that was not touched by the user, the setting may not migrate.
When you specify the MigApp.xml file, USMT migrates the settings for the following applications:
When you specify the `MigApp.xml` file, USMT migrates the settings for the following applications:
|Product|Version|
|--- |--- |
@ -156,7 +171,7 @@ When you specify the MigApp.xml file, USMT migrates the settings for the followi
|Google Picasa|3|
|Google Talk|beta|
|IBM Lotus 1-2-3|9|
|IBM Lotus Notes|6,7, 8|
|IBM Lotus Notes|6, 7, 8|
|IBM Lotus Organizer|5|
|IBM Lotus WordPro|9.9|
|Intuit Quicken Deluxe|2009|
@ -189,54 +204,52 @@ When you specify the MigApp.xml file, USMT migrates the settings for the followi
|Yahoo Messenger|9|
|Microsoft Zune™ Software|3|
## <a href="" id="no"></a>What USMT doesn't migrate
## What USMT doesn't migrate
The following is a list of the settings that USMT doesn't migrate. If you are having a problem that isn't listed here, see [Common Issues](usmt-common-issues.md).
The following items are settings that USMT doesn't migrate. If you're having a problem that isn't listed here, see [Common issues](usmt-common-issues.md).
### Application settings
USMT does not migrate the following application settings:
USMT doesn't migrate the following application settings:
- Settings from earlier versions of an application. The versions of each application must match on the source and destination computers. USMT does not support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. USMT can migrate from an earlier version of Microsoft Office to a later version.
- Settings from earlier versions of an application. The versions of each application must match on the source and destination computers. USMT doesn't support migrating the settings of an earlier version of an application to a later version, except for Microsoft Office. USMT can migrate from an earlier version of Microsoft Office to a later version.
- Application settings and some operating-system settings when a local account is created. For example, if you run /lac to create a local account on the destination computer, USMT will migrate the user data, but only some of the operating-system settings, such as wallpaper and screensaver settings, and no application settings will migrate.
- Application settings and some operating-system settings when a local account is created. For example, if you run `/lac` to create a local account on the destination computer, USMT will migrate the user data, but only some of the operating-system settings, such as wallpaper and screensaver settings, and no application settings will migrate.
- Microsoft Project settings, when migrating from Office 2003 to Office 2007 system.
- Microsoft Project settings, when migrating from Office 2003 to Office 2007 system.
- ICQ Pro settings, if ICQ Pro is installed in a different location on the destination computer. To successfully migrate the settings of ICQ Pro, you must install ICQ Pro in the same location on the destination computer as it was on the source computer. Otherwise, after you run the LoadState tool, the application won't start. You may encounter problems when:
- ICQ Pro settings, if ICQ Pro is installed in a different location on the destination computer. To successfully migrate the settings of ICQ Pro, you must install ICQ Pro in the same location on the destination computer as it was on the source computer. Otherwise, after you run the **LoadState** tool, the application won't start. You may encounter problems when:
- You change the default installation location on 32-bit destination computers.
- You attempt to migrate from a 32-bit computer to a 64-bit computer. This is because the ICQ Pro default installation directory is different on the two types of computers. When you install ICQ Pro on a 32-bit computer, the default location is "C:\\Program Files\\...". The ICQ Pro default installation directory on an x64-based computer, however, is “C:\\Program Files (x86)\\...”.
- You attempt to migrate from a 32-bit computer to a 64-bit computer. Attempting to migrate settings between different architectures doesn't work because the ICQ Pro default installation directory is different on the two types of computers. When you install ICQ Pro on a 32-bit computer, the default location is `C:\Program Files\...`. The ICQ Pro default installation directory on an x64-based computer, however, is `C:\Program Files (x86)\...`.
### Operating-System settings
USMT does not migrate the following operating-system settings.
USMT doesn't migrate the following operating-system settings.
- Local printers, hardware-related settings, drivers, passwords, application binary files, synchronization files, DLL files, or other executable files.
- Permissions for shared folders. After migration, you must manually reshare any folders that were shared on the source computer.
- Permissions for shared folders. After migration, you must manually re-share any folders that were shared on the source computer.
- Files and settings migrating between operating systems with different languages. The operating system of the source computer must match the language of the operating system on the destination computer.
- Customized icons for shortcuts may not migrate.
- Taskbar settings, when the source computer is running Windows XP.
You should also note the following items:
You should also note the following:
- You should run USMT from an account with administrative credentials. Otherwise, some data won't migrate. When running the **ScanState** and **LoadState** tools, you must run the tools in Administrator mode from an account with administrative credentials. If you don't run USMT in Administrator mode, only the user profile that is logged on will be included in the migration.
- You should run USMT from an account with administrative credentials. Otherwise, some data will not migrate. When running the ScanState and LoadState tools you must run the tools in Administrator mode from an account with administrative credentials. If you don't run USMT in Administrator mode, only the user profile that is logged on will be included in the migration. In addition, you must run the ScanState tool on Windows XP from an account with administrative credentials. Otherwise, some operating-system settings will not migrate. To run in Administrator mode, select **Start**, **All Programs**, **Accessories**, right-click **Command Prompt**, and then select **Run as administrator**.
- You can use the /**localonly** option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when you specify /**localonly**, see [ScanState Syntax](usmt-scanstate-syntax.md).
- You can use the `/localonly` option to exclude the data from removable drives and network drives mapped on the source computer. For more information about what is excluded when you specify `/localonly`, see [ScanState syntax](usmt-scanstate-syntax.md).
### Start menu layout
Starting in Windows 10, version 1607 the USMT does not migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](./usmt-common-issues.md#usmt-doesnt-migrate-the-start-layout).
Starting in Windows 10, version 1607 the USMT doesn't migrate the Start menu layout. To migrate a user's Start menu, you must export and then import settings using the Windows PowerShell cmdlets **Export-StartLayout** and **Import-StartLayout**. For more information, see [USMT common issues](./usmt-common-issues.md#usmt-doesnt-migrate-the-start-layout).
### User profiles from Active Directory to Azure Active Directory
USMT doesn't support migrating user profiles from Active Directory to Azure Active Directory.
## Related topics
## Related articles
[Plan your migration](usmt-plan-your-migration.md)