Share via

BranchCache Migration: Post-migration Tasks

  • Article

Applies To: Windows Server 2008 R2

The post-migration tasks for the source server are optional, depending on your migration scenario.

Completing migration

Migration is complete as soon as verification efforts demonstrate that the destination server has replaced the source server in serving the network.

If your verification efforts demonstrate that the migration failed, follow the steps in Restoring BranchCache in the event of migration failure to return to the previous valid configuration.

Configuring firewall rules

Firewall rules on the destination server must be configured post-migration. After the migration is completed, the user will have to run a NetShell command to enable the firewall rules by running as an administrator and running the following command:

netsh branchcache set service

The user will need to run this command by using arguments to configure the service in the mode they want it to operate in. The following command is most frequently used for the content server scenario:

netsh branchcache set service mode=local

The following command is used for the hosted cache server scenario:

netsh branchcache set service mode=hostedserver

Retiring BranchCache on your source server

After migration verification, the source server can be disconnected from the network and removed from service. You can keep this computer as a backup server in case you ever want to revert to your previous BranchCache configuration.

Restoring BranchCache in the event of migration failure

If the migration of BranchCache destination server fails, you can restore the source server by just pointing clients back to the source server (hosted cache).

  • If the source server is not repurposed and the computer name and IP address have not been migrated from the source to the destination server, an administrator can point clients back to the source server (hosted cache), reauthorize the server, and restart the BranchCache feature service on the source server.

  • If the computer name and IP address have been migrated from the source to the destination server, rename the destination server to a temporary name and change its IP address to a different IP address. Set the source server computer name and IP address to the values that were used before the migration, and restart the BranchCache feature service on the source server.

  • If this is not an option, use the backup files that were created on the source server, as described in BranchCache Migration: Preparing to Migrate. You can use the backup files any time after migration to restore the original BranchCache source server if a catastrophic failure occurs.

Estimated time to complete a rollback

You should be able to complete a rollback in one to two hours.

Additional configuration for Hosted Cache servers

  1. On the destination server, open a Command Prompt session with elevated user rights, if one is not already open.

  2. Bind a certificate to Secure Sockets Layer (SSL). If the hosted cache server name changed, you will need a new certificate to bind to SSL. Otherwise, server authentication to the hosted cache will fail.

  3. If you did not migrate the server identity as described in BranchCache Migration: Migrating BranchCache, then set clients in the branch to point to the hosted cache. Run the following command:

    Netsh branchcache set service mode= HOSTEDCLIENT location=<machinename>

    The destination server name should be a fully qualified domain name.

Important

SSL configuration is only required for hosted cache servers. If the hosted cache feature is not being used on this destination server, SSL configuration is unnecessary. Therefore, in that configuration, steps 2 and 3 above are not needed.

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.

Troubleshoot data migration that does not complete

If the Send-SmigServerData and Receive-SmigServerData cmdlets run indefinitely without completing, your destination server might not have sufficient disk space or a large enough FSRM or NTFS quota limit to allow for data migration to finish. To determine whether insufficient disk space is preventing the data send-receive process from completing, do the following on the destination server.

  1. Open %localappdata%/Svrmig/Log/SetupAct.log.

  2. Review the most recent log entries. If the following exception occurs, your destination server has insufficient disk space or FSRM or NTFS quota limits to complete data migration.

    Win32Exception: unable to write to FileStream: There is not enough space on the disk.

To resolve this issue, do the following:

  1. Press Ctrl+C to cancel Send-SmigServerData and Receive-SmigServerData on both source and destination servers.

  2. Check for sufficient disk space on the destination server’s hard disk drive. If the destination server’s hard disk drive has insufficient space, do one of the following.

    • Clear additional space.

    • Identify a different hard disk drive that has sufficient space.

  3. If the destination server’s hard disk drive, the destination path, or any folders that contain the destination path have an FSRM or NTFS quota enabled, and the quota limit does not allow for sufficient disk space to migrate data, do one of the following.

  4. Run the Send-SmigServerData and Receive-SmigServerData cmdlets again, specifying a destination path that has sufficient disk space, and large enough FSRM or NTFS quota limits, if applicable.

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 migrated item. 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 network adapter’s 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, to return the information that is contained in the result object, type a command in the following format, and then press ENTER.

    **$**VariableName

    In the following example, the variable is named ImportResult.

    **$**ImportResult

    This command returns information that is 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 4.

  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 have 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 include an ID of Local User and 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 include 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 (https://go.microsoft.com/fwlink/?LinkId=134862).

Additional references

Review the following resources for additional migration information and tools.

See Also

Concepts

BranchCache Migration Guide
BranchCache Migration: Preparing to Migrate
BranchCache Migration: Migrating BranchCache
BranchCache Migration: Verifying the Migration