How to fix problems related to remote PowerShell connections

Problem:

Due to various PowerShell errors, you cannot configure a server connection to the target on-premises Exchange environment in your CodeTwo software. You may encounter one of the following errors:

Connecting to remote server failed with the following error message: The WinRM client cannot process the request.

or

The request for the Windows Remote Shell with Shell <ID> failed because the shell was not found on the server.

Solution:

The connection error can be caused by many different reasons. The problem is usually related to an invalid or incomplete configuration of either the source or target environment. The most common causes for those errors include:

1. The target server is not accepting incoming PowerShell connections.
2. You use an old PowerShell version in either the source or target environment.
3. The source server cannot properly authenticate with the target environment.
4. The WinRM configuration prevents the connection.
5. The network configuration prevents the connection.

You can also follow these instructions to simulate a remote PowerShell session to your server to exclude a possibility that this issue is caused by your CodeTwo software.

The target server is not accepting incoming PowerShell connections

Freshly installed Exchange servers may not be configured to accept incoming PowerShell connections. To fix this and let your server configure all the necessary services, execute the following command in PowerShell:

Enable-PSRemoting

You use an old PowerShell version in either the source or the target environment

CodeTwo software works best if the latest available Windows PowerShell version is installed on the machine that sends (migrates) the data as well as on the target Exchange server which receives the data. To check which version of PowerShell is currently installed on either of your machines, run the following cmdlet in PowerShell:

$PSVersionTable

and check the value for PSVersion (Fig. 1.).

Fig. 1. Checking the PowerShell version in Windows 10.

It is strongly recommended to run the latest version of PowerShell on both machines. If necessary, update PowerShell to the latest available version for your operating system by following the steps from this Microsoft article.

Furthermore, if have installed the software on a machine running one of previous iterations of Windows (including Windows 7, Windows Server 2008 R2, and older), it is a good idea to test the software on another machine connected to the source environment where a newer version of Windows operating system is installed. If the connection succeeds on that machine, you should consider moving your migration tool installation there.

The source server cannot properly authenticate with the target environment

It may be that your machine cannot resolve the FQDN or DNS name of the server to which you are connecting. To fix this, you can try one of the following solutions:

1. If your source environment has a physical connection with an entire target environment (including its Domain Controllers and DNS servers), you can try configuring the source DNS server so that it has the necessary information to authenticate PowerShell connections.
2. If your source environment is only able to access the target Exchange server and not the other machines in the target environment, you need to configure a connection to that Exchange Server via an IP address. However, you need to make sure that:
   • the machine where the software is installed allows using basic authentication for WinRM protocol. To verify this, execute the following command in the Command Prompt:

     winrm get winrm/config/client/auth

     If this returns Basic = false, run the following command to enable basic authentication:

     winrm set winrm/config/service/auth @{Basic="true"}
     

   • the target server has Basic authentication for PowerShell connections enabled.

The WinRM configuration prevents the connection

Another possible reason for these errors to occur is when the WinRM (Windows Remote Management) service is not configured to accept a remote PowerShell connection that the program is trying to make. You can troubleshoot this problem by:

• verifying that your source server can connect to the target one
• disabling the SSL requirement.

Verify that your source server can connect to the target one

1. Open PowerShell on your target server and execute the following cmdlet to view all trusted hosts that can connect to that server. By default, the list of trusted hosts is empty.

Get-Item WSMan:\localhost\Client\TrustedHosts

2. If your source machine is not listed as a trusted host, you can add it to the list by running this cmdlet:

Set-Item WSMan:\localhost\Client\TrustedHosts -Value '<ComputerName>' -Concatenate

where '<ComputerName>' is the FQDN of the host. Using the asterisk (*) wildcard character is permitted, e.g. *.domain.com. You can also allow all machines to connect by inserting the asterisk only:

Set-Item WSMan:\localhost\Client\TrustedHosts -Value '*'

Disable the SSL requirement 

If the SSL connection cannot be established, you can consider disabling SSL requirement for PowerShell connections. To do so, follow these steps:

1. Open Internet Information Services (IIS) Manager.
2. Navigate to <Your Server> > Sites > Default Web Site > PowerShell.
3. Double-click SSL Settings (Fig. 2).

Fig. 2. Accessing the SSL settings in IIS Manager.

4. Clear the Require SSL checkbox and select to Ignore client certificates (Fig. 3). Apply the changes.

Fig. 3. Disabling the SSL requirement for PowerShell.

The network configuration prevents the connection

If you have followed all the steps above and are still unable to configure the connection, double check your network configuration, including all physical/software firewalls. By default, PowerShell uses the following TCP ports communication:

• 5985 (or 80) for HTTP
• 5986 (or 443) for HTTPS.

Simulating a remote PowerShell session

You may attempt to manually simulate a remote PowerShell session in order to connect to your target server in the same way this is done by the software. This will help you verify whether the problem is related to the CodeTwo software or a specific configuration of your environment.

To do so, follow these steps:

• when connecting via FQDN, refer to this article;
• when connecting via IP, use the following commands in Windows PowerShell:

$LiveCred = Get-Credential
$SessionOpt = New-PSSessionOption -SkipCACheck:$true -SkipCNCheck:$true 
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://<target-server-IP-address>/powershell/ -Credential $LiveCred -SessionOption $SessionOpt

See also:

Target server mailbox addresses are not resolving