Local User and Group Migration Guide

Applies To: Windows Server 2008 R2

Local user and group migration is a part of the data and share migration process that is supported by Windows Server Migration Tools. Administrators can use Windows Server Migration Tools to migrate server roles, features, shares, operating system settings, and other data to computers that are running Windows Server® 2008 R2.

In this guide

  • Supported operating systems

  • Supported attributes

  • Attributes that are not supported

  • User rights required to perform migration on both source and destination servers

  • Prepare the destination server

  • Prepare the source server

  • Migrate local users and groups

  • Verify the migration

  • Troubleshooting cmdlet-based migration

Supported operating systems

The following table indicates the Windows Server operating systems that are supported by Windows Server Migration Tools.

Source server processor Source server operating system Destination server operating system Destination server processor

x86- or x64-based

Windows Server 2003 with Service Pack 2

Windows Server 2008 R2, both full and Server Core installation options

x64-based

x86- or x64-based

Windows Server 2003 R2

Windows Server 2008 R2, both full and Server Core installation options

x64-based

x86- or x64-based

Full installation option of Windows Server 2008

Windows Server 2008 R2, both full and Server Core installation options

x64-based

x64-based

Windows Server 2008 R2, both full and Server Core installation options

Windows Server 2008 R2, both full and Server Core installation options

x64-based

The versions of operating systems shown in the previous table are the oldest combinations of operating systems and service packs that are supported. Newer service packs, if available, are supported.

Foundation, Standard, Enterprise, and Datacenter editions of Windows Server are supported as either source or destination servers.

Migrations between physical operating systems and virtual operating systems are supported.

Migration from a source server to a destination server that is running an operating system in a different system UI language (that is, the installed language) than the source server is not supported. For example, you cannot use Windows Server Migration Tools to migrate roles, operating system settings, data, or shares from a computer that is running Windows Server 2008 in the French system UI language to a computer that is running Windows Server 2008 R2 in the German system UI language.

Note

The system UI language is the language of the localized installation package that was used to set up the Windows operating system.

Both x86- and x64-based migrations are supported for Windows Server 2003 and Windows Server 2008 R2. All editions of Windows Server 2008 R2 are x64-based.

Roles that are running on Server Core installations of Windows Server 2008 cannot be migrated, because there is no .NET Framework available on Server Core installations of Windows Server 2008.

Supported attributes

  • The following local user account attributes on the General tab of the User Properties dialog box are migrated from the source server without changes.

    • Name

    • Full Name

  • The following local user account attributes are changed during migration.

    • User must change password at next logon is always enabled on the destination computer.

    • Security ID is mapped to a new value on the destination server.

  • The following local group account attributes are migrated.

    • Name

    • Description

    • Membership (including members that are local users, other local groups, domain users, and domain groups)

  • The following local group account attributes are changed during migration.

    • Security ID is mapped to a new value on the destination server.

Attributes that are not supported

Migration of the following user account attributes or scenarios is not supported.

  • User password. Users are prompted to set new passwords the first time that they log on to the destination server.

  • Overwriting the attributes of existing users or groups that have the same names on the destination server as on the source server

  • Account is disabled. All migrated user accounts are disabled on the source server after migration, for security reasons.

  • The following attributes on the General tab of the User Properties dialog box are not supported.

    • User cannot change password

    • Description

    • Account is locked out

  • No attributes on other tabs are supported.

    • Profile tab

    • Environment tab

    • Sessions tab

    • Remote Control tab

    • Terminal Services Profile tab

    • Dial-in tab

User rights required to perform migration on both source and destination servers

Local Administrator rights are required on both the source and destination servers to install Windows Server Migration Tools on both the source and destination servers.

Prepare the destination server

Install Windows Server Migration Tools by following procedures in the Windows Server Migration Tools Installation, Access and Removal guide on the Microsoft Web site.

Verify that the destination server can resolve the names of domain users who are members of the local group during the import operation. If source and destination servers are in different domains, the destination server must be able to contact a global catalog server for the forest in which the source domain user accounts are located.

Prepare the source server

Install Windows Server Migration Tools by following procedures in the Windows Server Migration Tools Installation, Access and Removal guide on the Microsoft Web site. The installation guide contains additional detailed steps to deploy Windows Server Migration Tools to source servers that are running either Windows Server 2003 or Windows Server 2008.

Important

Before you run the Import-SmigServerSetting, Export-SmigServerSetting, or Get-SmigServerFeature cmdlets, verify that during migration, both source and destination servers can contact the domain controller that is associated with domain users or groups who are members of local groups on the source server.
Before you run the Send-SmigServerData or Receive-SmigServerData cmdlets, verify that during migration, both source and destination servers can contact the domain controller that is associated with those domain users who have rights to files or shares that are being migrated.

Migrate local users and groups

The Windows Server Migration Tools cmdlets that are used to migrate local user and group data are Export-SmigServerSetting on the source server, and Import-SmigServerSetting on the destination server.

On the source server, the Export-SmigServerSetting cmdlet lets you export all local users to a migration store, the location of which you specify in the cmdlet. You can also export all local groups in the either the same cmdlet, or in different command instances.

Note

Windows Server Migration Tools does not allow for additions to an existing migration store. To migrate both local user and group data to the same migration store, export both in a single command instance. Otherwise, you must migrate users and groups to different migration stores in two separate migrations.

On the destination server, the Import-SmigServerSetting cmdlet lets you import all local users from a migration store, the location of which you specify in the cmdlet. You can also import all local groups in either the same cmdlet or in different command instances.

To obtain detailed Help about any Windows Server Migration Tools cmdlet, type Get-Help <cmdlet_name> -full in a Windows PowerShell session, in which cmdlet_name represents the name of the Windows Server Migration Tools cmdlet for which you want help.

Add the -Verbose parameter to a Windows PowerShell cmdlet, as provided in the steps in this guide, to see detailed information about the operation.

Local user and group migration procedures

Complete the procedures in this section to migrate local users and groups.

Security Note
If the source server is a domain member server, yet the destination server is a domain controller, imported local users are elevated to domain users, and imported local groups become Domain Local groups on the destination server.

If the source server is a domain controller, but the destination server is not, Domain Local groups are migrated as local groups, and domain users are migrated as local users.

To export local users and groups from the source server

  1. On the source server, do one of the following.

    • On computers that are running Windows Server 2003, open a Windows PowerShell session by clicking Start, clicking All Programs, opening the Windows PowerShell folder, and then clicking the Windows PowerShell shortcut.

    • On computers that are running Windows Server 2008, open a Windows PowerShell session with elevated user rights. To do this, click Start, click All Programs, open the Windows PowerShell folder, right-click Windows PowerShell, and then click Run as administrator.

    • On computers that are running Windows Server 2008 R2, open a Windows Server Migration Tools custom Windows PowerShell session with elevated user rights. To do this, click Start, click Administrative Tools, click Windows Server Migration Tools, right-click the Windows Server Migration Tools shortcut, and then click Run as administrator.

  2. If you opened the current Windows PowerShell session by using the Windows Server Migration Tools shortcut on the Start menu, skip this step and go on to the next. Only load the Windows Server Migration Tools snap-in in a Windows PowerShell session that was opened by using some other method, and into which the snap-in has not already been loaded.

    Load Windows Server Migration Tools into your Windows PowerShell session. To load Windows Server Migration Tools, type the following, and then press Enter.

    Add-PSSnapin Microsoft.Windows.ServerManager.Migration
    
  3. Export local users and groups to a migration store. Type the following command, and then press Enter, in which MigrationStorePath represents the path of the location where you want to store migrated data.

    Export-SmigServerSetting -User <Enabled | Disabled | All> -Group -Path <MigrationStorePath> -Verbose
    

    Use one of the following values with the -User parameter, as shown in the previous cmdlet.

    • Enabled   Export only enabled local users

    • Disabled   Export only disabled local users

    • All   Export both enabled and disabled local users

Note

You are prompted to provide a password to encrypt the migration store. Remember this password, because you must provide the same password to import data from the migration store on the destination server.
If the path is not a shared location to which the destination server has access, you must copy the migration store to the destination server manually, or to a location that this destination server can access as it runs the Import-SmigServerSetting cmdlet.

To import local users and groups to the destination server

  1. Do one of the following.

    • Open a Windows Server Migration Tools custom Windows PowerShell session with elevated user rights. To do this, click Start, click Administrative Tools, click Windows Server Migration Tools, right-click the Windows Server Migration Tools shortcut, and then click Run as administrator.

    • On the destination server, open a Windows PowerShell session with elevated user rights. To do this, click Start, click All Programs, click Accessories, open the Windows PowerShell folder, right-click Windows PowerShell, and then click Run as administrator.

  2. If you opened the current Windows PowerShell session by using the Windows Server Migration Tools shortcut on the Start menu, skip this step and go on to the next. Only load the Windows Server Migration Tools snap-in in a Windows PowerShell session that was opened by using some other method, and into which the snap-in has not already been loaded.

    Load Windows Server Migration Tools into your Windows PowerShell session. To load Windows Server Migration Tools, type the following, and then press Enter.

    Add-PSSnapin Microsoft.Windows.ServerManager.Migration
    
  3. Import local users and groups from the migration store that you created in To export local users and groups from the source server. Type the following command, and then press Enter, in which MigrationStorePath represents the path of the location from which you want to import migrated data.

    Import-SmigServerSetting -User <Enabled | Disabled | All> -Group -Path <MigrationStorePath> -Verbose
    

    Use one of the following values with the -User parameter, as shown in the previous cmdlet.

    • Enabled   Import only enabled local users

    • Disabled   Import only disabled local users

    • All   Import both enabled and disabled local users

Note

After you enter the Import-SmigServerSetting cmdlet, you are prompted to provide the same password to decrypt the migration store that you created during the export process.
To import local users and groups in two separate migration passes, you must first import local users, and then import local groups to import memberships of local users correctly.

Verify the migration

Verify that all local users and groups that you expected to migrate exist on the destination server by comparing the lists of users and groups that are shown in the Local Users and Groups Microsoft Management Console (MMC) snap-in, on both source and destination servers. To open the Local Users and Groups snap-in, do the following.

To open the Local Users and Groups snap-in

  • Click Start, click Run, type lusrmgr.msc in the Open text box, and then click OK, or press ENTER.

You can also compare lists of users and groups that are shown on both source and destination servers by using the net command.

To obtain lists of users and groups by using the net command

  1. On either the source or destination computer, open a Command Prompt window. Click Start, click Run, type cmd, and then press Enter.

  2. Export a list of all local users to a text file by typing the following command, and then pressing Enter.

    net user > localusers.txt
    
  3. Export a list of all local groups to a text file by typing the following command, and then pressing Enter.

    net localgroup > localgroups.txt
    
  4. Be sure to save the resulting text files to a convenient location.

Troubleshooting cmdlet-based migration

The Windows Server Migration Tools deployment log file is located at %windir%\Logs\SmigDeploy.log. Additional Windows Server Migration Tools log files are created at the following locations.

  • %windir%\Logs\ServerMigration.log

  • On Windows Server 2008 and Windows Server 2008 R2: %localappdata%\SvrMig\Log

  • On Windows Server 2003: %userprofile%\Local Settings\Application Data\SvrMig\Log

If migration log files cannot be created in the previous locations, ServerMigration.log and SmigDeploy.log are created in %temp%, and other logs are created in %windir%\System32.

If a migration cmdlet fails, and the Windows PowerShell session closes unexpectedly with an access violation error message, look for a message similar to the following example in the %localappdata%\SvrMig\Logs\setuperr.log file.

FatalError [0x090001] PANTHR Exception (code 0xC0000005: ACCESS_VIOLATION) occurred at 0x000007FEEDE9E050 in C:\Windows\system32\migwiz\unbcl.dll (+000000000008E050).  Minidump attached (317793 bytes).

This failure occurs when the server cannot contact domain controllers that are associated with domain users or groups who are members of local groups, or who have rights to files or shares that are being migrated. When this happens, each domain user or group is displayed in the GUI as an unresolved security identifier (SID). An example of a SID is S-1-5-21-1579938362-1064596589-3161144252-1006.

To prevent this problem, verify that required domain controllers or global catalog servers are running, and that network connectivity allows communication between both source and destination servers and required domain controllers or global catalog servers.  Then, run the cmdlets again.

If connections between either the source or destination servers and the domain controllers or global catalog servers cannot be restored, do the following.

  1. Before you run Export-SmigServerSetting, Import-SmigServerSetting or Get-SmigServerFeature again, remove all unresolved domain users or groups who are members of local groups from the server on which you are running the cmdlet.

  2. Before you run Send-SmigServerData or Receive-SmigServerData again, remove all unresolved domain users or groups who have user rights to files, folders, or shares on the migration source server.

Viewing the content of Windows Server Migration Tools result objects

All Windows Server Migration Tools cmdlets return results as objects. You can save result objects, and query them for more information about settings and data that were migrated. You can also use result objects as input for other Windows PowerShell commands and scripts.

Result object descriptions

The Windows Server Migration Tools Import-SmigServerSetting and Export-SmigServerSetting cmdlets return results in a list of MigrationResult objects. Each MigrationResult object contains information about the data or setting that the cmdlet processes, the result of the operation, and any related error or warning messages. The following table describes the properties of a MigrationResult object.

Property name Type Definition

ItemType

Enum

The type of item being migrated. Values include General, WindowsFeatureInstallation, WindowsFeature, and OSSetting.

ID

String

The ID of the migrated item. Examples of values include Local User, Local Group, and DHCP.

Success

Boolean

The value True is displayed if migration was successful; otherwise, False is displayed.

DetailsList

List <MigrationResultDetails>

A list of MigrationResultDetails objects.

Send-SmigServerData and Receive-SmigServerData cmdlets return results in a list of MigrationDataResult objects. Each MigrationDataResult object contains information about the data or share that the cmdlet processes, the result of the operation, any error or warning messages, and other related information. The following table describes the properties of a MigrationDataResult object.

Property name Type Definition

ItemType

Enum

The type of migrated item. Values include File, Folder, Share, and Encrypted File.

SourceLocation

String

The source location of the item, shown as a path.

DestinationLocation

String

The destination location of the item, shown as a path.

Success

Boolean

The value True is displayed if migration was successful; otherwise, False is displayed.

Size

Integer

The item size, in bytes.

ErrorDetails

List <MigrationResultDetails>

A list of MigrationResultDetails objects.

Error

Enum

Errors enumeration for errors that occurred.

WarningMessageList

List <String>

A list of warning messages.

The following table describes the properties of objects within the MigrationResultDetails object that are common to both MigrationResult and MigrationDataResult objects.

Property name Type Definition

FeatureId

String

The name of the migration setting that is related to the item. Examples of values include IPConfig and DNS. This property is empty for data migration.

Messages

List <String>

A list of detailed event messages.

DetailCode

Integer

The error or warning code associated with each event message.

Severity

Enum

The severity of an event, if events occurred. Examples of values include Information, Error, and Warning.

Title

String

Title of the result object. Examples of values include the network adapter physical address for IP configuration, or user name for local user migration.

Examples

The following examples show how to store the list of the result objects in a variable, and then use the variable in a query to return the content of result objects after migration is complete.

To store a list of result objects as a variable for queries

  1. To run a cmdlet and save the result in variable, type a command in the following format, and then press Enter.

    $VariableName = $(Cmdlet)
    

    The following is an example.

    $ImportResult = $(Import-SmigServerSetting -FeatureId DHCP -User all -Group -Path D:\rmt\DemoStore -force -Verbose)
    

    This command runs the Import-SmigServerSetting cmdlet with several parameters specified, and then saves result objects in the variable ImportResult.

  2. After the Import-SmigServerSetting cmdlet has completed its operations, return the information that is contained in the result object by typing a command in the following format, and then pressing Enter.

    $VariableName
    

    In the following example, the variable is named ImportResult.

    $ImportResult
    

    This command returns information that was contained in the result objects that were returned by Import-SmigServerSetting in the example shown in step 1. The following is an example of the output that is displayed by calling the ImportResult variable.

               ItemType  ID                              Success  DetailsList
               --------  --                              -------  -----------
              OSSetting  Local User                         True  {Local User, Loc...
              OSSetting  Local Group                        True  {Local Group, Lo...
         WindowsFeature  DHCP                               True  {}
    

    Each line of the previous sample is a migration result for an item that was migrated by using the Import-SmigServerSetting cmdlet. The column heading names are properties of MigrationResult objects. You can incorporate these properties into another command to return more detail about result objects, as shown by examples in step 3 and forward.

  3. To display a specific property for all result objects in the list, type a command in the following format, and then press Enter.

    $<VariableName>| Select-Object -ExpandProperty <PropertyName>
    

    The following is an example.

    $importResult | Select-Object -ExpandProperty DetailsList
    
  4. You can run more advanced queries to analyze result objects by using Windows PowerShell cmdlets. The following are examples.

    • The following command returns only those details of result objects that use the ID Local User.

      $ImportResult | Where-Object { $_.ID -eq "Local User" } | Select-Object -ExpandProperty DetailsList
      
    • The following command returns only those details of result objects that use an ID of Local User that have a message severity equal to Warning.

      $ImportResult | Where-Object { $_.ID -eq "Local User" } | Select-Object -ExpandProperty DetailsList | ForEach-Object { if ($_.Severity -eq "Warning") {$_} }
      
    • The following command returns only the details of result objects that use an ID of Local Group that also have the title Remote Desktop Users.

      $ImportResult | Where-Object { $_.ID -eq "Local Group" } | Select-Object -ExpandProperty DetailsList | ForEach-Object { if ($_.Title -eq "Remote DesktopUsers") {$_} }
      

More information about querying results

For more information about the cmdlets that are used in the previous examples, see the following additional resources.

For more information about Windows PowerShell scripting techniques, see What Can I Do With Windows PowerShell? - Scripting Techniques on the Microsoft Script Center Web site (https://go.microsoft.com/fwlink/?LinkId=134862).