Share via


LoadState Syntax

In this topic

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

Before you begin

Before you run LoadState, note the following:

  • When running ScanState and LoadState on Windows Vista, you need to run the tools in “Administrator” mode from an account with administrative credentials to ensure that all specified users are migrated. This is because User Access Control (UAC) is turned on in Windows Vista. To run in this mode, click the start button, click All Programs, click Accessories, right-click Command Prompt, click Run as administrator, and then specify your LoadState or ScanState command. If you do not run USMT in “Administrator” mode, only the user profile that is logged on will be included in the migration.
  • You should log off after you run LoadState. Some settings (for example, fonts, wallpaper, and screensaver settings) will not take effect until the next time the user logs in.
  • You need to be a local or domain administrator to run LoadState unless you specify the /q option.
  • Unless otherwise specified, you can only specify each option once on the command line.
  • The Command-line option incompatibility diagram shows which options you can use together.

Syntax

This section explains the syntax and usage of the LoadState command-line options. The options can be specified in any order. If the option contains a parameter, you can specify either a colon or space separator.

The LoadState syntax is:

loadstate 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\]UserName]|LocalUserName] [/ue:[[DomainName\]UserName]|LocalUserName] [/uel:NumberOfDays|YYYY/MM/DD|0] [/md:OldDomain:NewDomain] [/mu:OldDomain\OldUserName:[NewDomain\]NewUserName] [/lac:[Password]] [/lae] [/q] [/config:[Path\]FileName] [/?|help]

For example:

  • To decrypt the store and migrate the files and settings to a computer running Windows Vista, specify:
    loadstate \\fileserver\migration\mystore /i:migapp.xml /i:miguser.xml /v:13 /decrypt /key:"mykey"
  • To decrypt the store and migrate the files and settings to a computer running Windows XP, specify:
    loadstate \\fileserver\migration\mystore /i:migsys.xml /i:migapp.xml /i:miguser.xml /v:13 /decrypt /key:"mykey"

Storage options

USMT provides the following options that you can use to specify how and where the migrated data is stored.

Option Description

StorePath

Indicates the folder where the files and settings data are stored. You must specify StorePath on the LoadState command line. You cannot specify more than one StorePath.

/decrypt /key:KeyString

or

/decrypt /key:"Key String"

or

/decrypt /keyfile:[Path\]FileName

Decrypts the store with the specified key. With this option, you will need to specify the encryption key with one of the following ways:

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

KeyString cannot exceed 256 characters.

/key and /keyfile cannot be used on the same command line.

/decrypt and /nocompress cannot be used on the same command line.

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

For example:

loadstate /i:miguser.xml /i:miguser.xml \\fileserver\migration\mystore /decrypt /key:mykey

/nocompress

Specifies that the store is not compressed. You should only use this option in testing environments because we recommend that you use a compressed store during your actual migration. This option cannot be used in with the /decrypt option.

For example:

loadstate /i:miguser.xml /i:miguser.xml \\fileserver\migration\mystore /nocompress

Migration rule options

USMT provides the following option that you can use to specify what you want to migrate.

OptionDescription

/i:[Path\]FileName

(include)

Specifies an .xml file that contains rules that define what state to migrate. You can specify this option multiple times in order to specify all of your .xml files (MigApp.xml, MigSys.xml, MigUser.xml and any custom .xml files that you create). Path can be a relative or full path. If you do not specify Path, then FileName must be located in the current directory.

For more information about which files to specify, see the "xml files" section of the Frequently Asked Questions topic.

/q

Allows LoadState to run without administrative credentials. This option will only migrate the settings and account for the user who is currently logged on. Errors will occur if you try to apply settings to a location for which the user does not have sufficient credentials. For example, you will receive an error if a file needs to be written to "C:\Program Files" and the user you are running LoadState under does not have sufficient credentials to that folder.

/config:[Path\]FileName

Specifies the Config.xml file that LoadState should use. You cannot specify this option more than once on the command line. Path can be a relative or full path. If you do not specify Path, then FileName must be located in the current directory.

This example migrates the files and settings based on the rules in Config.xml, MigUser.xml, and MigApp.xml:

loadstate \fileserver\migration\mystore /config:config.xml /i:miguser.xml /i:migapp.xml /v:13 /l:loadstate.log

Monitoring options

USMT provides several options that you can use to analyze problems that occur during migration.

OptionDescription
/l:[Path\]FileName

Specifies the location and name of the LoadState log. You cannot store any of the log files in StorePath. Path can be a relative or full path. If you do not specify Path, then the log will be created in the current directory. You can specify /v to adjust the amount of output.

If you run LoadState from a shared network resource, you must specify this option or USMT will fail with an error "USMT was unable to create the log file(s)". To fix this issue, specify /l:load.log.

/progress:[Path\]FileName

Creates the optional progress log. You cannot store any of the log files in StorePath. Path can be a relative or full path. If you do not specify Path, then FileName will be created in the current directory.

For example:

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

/c

When specified, LoadState will continue to run even if there are nonfatal errors. Without the /c option, LoadState exits on the first error. When you specify this option, any files or settings that cause an error and are ignored will be logged in the progress log. For example, if a file is open or if there is a large file that will not fit on the destination computer, LoadState will log an error and will continue with the migration.

/r:TimesToRetry

(Retry)

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

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

/w:SecondsBeforeRetry

(Wait)

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

/v:VerbosityLevel

(Verbosity)

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

  • Bit 0 stands for verbose output.

  • Bit 1 is not used.

  • Bit 2 stands for status output.

  • Bit 3 stands for debugger output.


For example:

loadstate \\fileserver\migration\mystore /v:13 /i:migapp.xml /i:miguser.xml

VerbosityLevel can be one of the following levels:

Level Binary Value Explanation

0

0000

Only the default errors and warnings are enabled.

1

0001

Enables verbose output.

4

0100

Enables error and status output.

5

0101

Enables verbose and status output.

8

1000

Enables error output to a debugger.

9

1001

Enables verbose output to a debugger.

12

1100

Enables error and status output to a debugger.

13

1101

Enables verbose, status, and debugger output.

If you specify 2, 3, 6, 7, 10, 11, 14, or 15, USMT uses the following mapping to determine VerbosityLevel.

Specified Level Binary Value Implied Level

2

0010

0

3

0011

1

6

0110

4

7

0111

5

10

1010

8

11

1011

9

14

1110

12

15

1111

13

User options

By default all users are migrated. The only way to specify which users to include and exclude is by using the following options. You cannot exclude users in the migration .xml files or using Config.xml. For more information, see Identify Users.

OptionDescription
/all

Migrates all of the users on the computer.

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

/ui:DomainName\UserName

or

/ui:DomainName\"User Name"

or

/ui:LocalUserName

(User include)

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

For example:

  • To include only User2 from the Fareast domain, type:
    /ue:\\ /ui:fareast\user2

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

In this example, a user Farwest\User1 who had last logged on 2 months ago will not be migrated.

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

/uel:NumberOfDays

or

/uel:YYYY/MM/DD

or

/uel:0

(User exclude based on last logon)

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

Note

USMT excludes users based on the state of the computer when ScanState was run. For example, if a user logs onto the source computer after ScanState is run but before LoadState is run, the logon will not be considered in this option.



Examples:

  • /uel:0 migrates accounts that were logged on to the source computer and any accounts whose profiles had been loaded when ScanState was run. For example, if domain\user1 was logged on and right-clicked an application, clicked Run As, and entered the credentials for domain\user2, then the profiles for both user1 and user2 would have been loaded on the computer. If ScanState was run at this time with /uel:0, then both users would be included in the store.

  • /uel:90 migrates users who have logged on within the last 90 days.

  • /uel:1 migrates users who have logged on within the last 24 hours.

  • /uel:2002/1/15 migrates users who have logged on January 15, 2002 or afterwards.

For example:

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

/ue:DomainName\UserName

or

/ue:DomainName\"User Name"

or

/ue:LocalUserName

(User exclude)

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

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

For example:

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

/md:OldDomain:NewDomain

or

/md:LocalComputerName:NewDomain

(move domain)

Specifies a new domain for the user(s). You should 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.

You can specify this option more than once. You may want to specify multiple /md options if you are consolidating users across multiple domains to a single domain. For example, you could specify /md:fareast:farwest and /md:farnorth:farwest.

If there are conflicts between two /md commands, the first rule that you specify is applied. For example, if you specify /md:fareast:farwest and /md:fareast:farnorth, then FarEast users would be mapped to the FarWest domain.

Note

If you specify an OldDomain that did not exist on the source computer, LoadState will appear to complete successfully (without an error or warning). However, in this case, user(s) will not be moved to NewDomain but will remain in their original domain. For example, if you miss-spell "domain1" and you specify "/md:domai1:domain2", the user(s) will remain in domain1 on the destination computer.



For example:

loadstate /i:migapp.xml /i:miguser.xml \fileserver\migration\mystore

/progress:prog.log /l:load.log /md:fareast:farwest

/mu:OldDomain\OldUserName:[NewDomain\]NewUserName

or

/mu:OldLocalUserName:NewDomain\NewUserName

Specifies a new user name for the specified user. If the store contains more than one user, you can specify multiple /mu options. You cannot use wildcard characters with this option.

For example:

loadstate /i:migapp.xml /i:miguser.xml \\fileserver\migration\mystore

/progress:prog.log /l:load.log /mu:fareast\user1:farwest\user1

/lac:[Password]

(local account create)

Specifies that if a user account is a local (non-domain) account, and it does not 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 specify /lae.

If /lac is not specified, any local user accounts (that do not already exist on the destination computer) will not be migrated. Password is the password for the new created account. An empty password is used by default.

Warning

You should use Password with caution because it is provided in plain text and can be obtained by anyone with access to the computer that is running LoadState. Also, if the computer has multiple users, all migrated users will have the same password.



For example:

loadstate /i:migapp.xml /i:miguser.xml \fileserver\migration\mystore

/progress:prog.log /l:load.log /lac:password /lae

For more information, see Migrating local and domain accounts. For instructions, see How To Migrate User Accounts.

/lae

(local account enable)

Enables the account that was created with /lac. You must specify /lac with this option.

For example:

loadstate /i:migapp.xml /i:miguser.xml \\fileserver\migration\mystore

/progress:prog.log /l:load.log /lac:password /lae

For more information, see [Migrating local and domain accounts](cc749260\(v=ws.10\).md). For instructions, see [How To Migrate User Accounts](cc721893\(v=ws.10\).md).

/ue, and /ui examples

Examples for /ui and /ue.

The following examples apply to both /ui and /ue. That is, you can replace /ue with /ui to specify to include rather than exclude the specified users.

Behavior Command

Exclude the user named User One in the Fareast domain.

/ue:fareast\"user one"

Exclude the user named User1 in the Fareast domain.

/ue:fareast\user1

Exclude the local user named User1.

/ue:user1

Exclude all local and domain users.

/ue:*\*

Exclude all local users.

/ue:*

Exclude users in all domains named User1, User2, and so on.

/ue:*\user*

Using the options together

You can use /uel, /ue, and /ui together in order to migrate only the users that you want migrated. However, if a user is specified with /ui, and also specified to exclude with either /ue or /uel, the user will be included in the migration. For example if you specify /ui:domain1\* /ue:domain1\user1, then User1 will be migrated because /ui takes precedence.

Behavior Command

Include only User2 from the Fareast domain and exclude all other users.

/ue:*\* /ui:fareast\user2

Include only the local user named User1 and exclude all other users.

/ue:*\* /ui:user1

Include only the domain users from Domain1, except Domain1\User1.

This behavior cannot be completed using a single command. Instead, to migrate this set of users, you will need to specify the following:

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

Include only local (non-domain) users.

/ue:*\* /ui:*

Include only users.

/ue:*\* /ui:*

Command-line option incompatibility

The following tables indicate which command-line options are not compatible on the LoadState command line. If the table entry for a particular combination is blank, the options are compatible and you can use them together. The X symbol means that the options are not compatible. For example, you cannot use the /nocompress option with the /decrypt option.