powershell-scripts/winrm-https/TEST-REMOTE-CONNECTION-GUIDE.md

# Testing Remote WinRM HTTPS Connections

## Quick Reference

### From Your Computer to Test PC (G9KN7PZ3ESF)

```powershell
# Test basic connectivity
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986

# Interactive remote session
$cred = Get-Credential
Enter-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986

# Run single command
Invoke-Command -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -ScriptBlock { hostname }
```

---

## Step-by-Step Testing Guide

### Step 1: Test Basic WinRM Connectivity

This is the simplest test - it just checks if WinRM HTTPS is responding:

```powershell
# Open PowerShell on your computer
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986
```

**Expected Output** (Success):
```
wsmid           : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor   : Microsoft Corporation
ProductVersion  : OS: 0.0.0 SP: 0.0 Stack: 3.0
```

**If it fails**, you'll see error messages. Common issues:
- Certificate trust issues
- Network connectivity
- Firewall blocking port 5986
- WinRM service not running

---

### Step 2: Test with Credentials (Basic Authentication)

Create a credential object and test connection:

```powershell
# Get credentials (will prompt for username/password)
$cred = Get-Credential

# When prompted, enter:
#   Username: DOMAIN\username (or .\localadmin for local account)
#   Password: your password

# Test connection with credentials
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986 -Credential $cred
```

---

### Step 3: Interactive Remote Session (Enter-PSSession)

This gives you an interactive command prompt on the remote computer:

```powershell
# Create credential if not already done
$cred = Get-Credential

# Enter interactive session
Enter-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986
```

**Expected Output**:
```
[g9kn7pz3esf.logon.ds.ge.com]: PS C:\Users\username\Documents>
```

Notice your prompt changes to show `[g9kn7pz3esf.logon.ds.ge.com]:` - you're now on the remote PC!

**Try some commands**:
```powershell
# Check hostname
hostname

# Check IP configuration
ipconfig

# Check running services
Get-Service | Where-Object {$_.Status -eq 'Running'}

# Check WinRM configuration
winrm enumerate winrm/config/listener

# Exit remote session
Exit-PSSession
```

---

### Step 4: Run Commands Remotely (Invoke-Command)

Execute commands on the remote PC without entering an interactive session:

```powershell
# Single command
Invoke-Command -ComputerName g9kn7pz3esf.logon.ds.ge.com `
    -Credential $cred -UseSSL -Port 5986 `
    -ScriptBlock { hostname }

# Multiple commands
Invoke-Command -ComputerName g9kn7pz3esf.logon.ds.ge.com `
    -Credential $cred -UseSSL -Port 5986 `
    -ScriptBlock {
        $hostname = hostname
        $ip = (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -notlike "127.*"})[0].IPAddress
        [PSCustomObject]@{
            Hostname = $hostname
            IPAddress = $ip
            WinRMStatus = (Get-Service WinRM).Status
        }
    }
```

---

### Step 5: Create Persistent Session (New-PSSession)

Create a session object for reuse:

```powershell
# Create session
$session = New-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com `
    -Credential $cred -UseSSL -Port 5986

# Check session
$session

# Use the session multiple times
Invoke-Command -Session $session -ScriptBlock { Get-ComputerInfo }
Invoke-Command -Session $session -ScriptBlock { Get-Service WinRM }
Invoke-Command -Session $session -ScriptBlock { Get-Process | Select-Object -First 10 }

# Close session when done
Remove-PSSession $session
```

**Benefits of persistent sessions**:
- Faster execution (connection is reused)
- Can maintain state between commands
- More efficient for multiple operations

---

## Troubleshooting Common Issues

### Issue 1: Certificate Trust Error

**Error**:
```
Test-WSMan : The SSL certificate contains a common name (CN) that does not match the hostname.
```

or

```
The SSL certificate is signed by an unknown certificate authority.
```

**Cause**: Your computer doesn't trust the self-signed certificate.

**Solution A - Skip Certificate Check (Testing Only)**:
```powershell
# Set session option to skip certificate validation
$sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck

# Use with Test-WSMan
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986 -SessionOption $sessionOption

# Use with Enter-PSSession
Enter-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -SessionOption $sessionOption

# Use with Invoke-Command
Invoke-Command -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -SessionOption $sessionOption -ScriptBlock { hostname }
```

**Solution B - Install Certificate on Your Computer (Production)**:
```powershell
# Import the certificate to Trusted Root CAs on your computer
# This makes the certificate permanently trusted

# If you have the PFX file with password:
$certPassword = ConvertTo-SecureString "XqHuyaLZSyCYEcpsMz6h5" -AsPlainText -Force
Import-PfxCertificate -FilePath "C:\path\to\wildcard-logon-ds-ge-com-20251017.pfx" `
    -CertStoreLocation Cert:\LocalMachine\Root `
    -Password $certPassword

# Or export certificate from remote PC (without private key) and import:
# 1. On remote PC: Export certificate as .cer file
# 2. On your PC: Import to Trusted Root Certification Authorities
Import-Certificate -FilePath "C:\path\to\wildcard-cert.cer" `
    -CertStoreLocation Cert:\LocalMachine\Root
```

---

### Issue 2: Authentication Failed

**Error**:
```
Enter-PSSession : Connecting to remote server g9kn7pz3esf.logon.ds.ge.com failed with the following error message :
Access is denied.
```

**Possible Causes**:
1. Wrong username/password
2. User not in local Administrators group on remote PC
3. User Account Control (UAC) filtering

**Solutions**:
```powershell
# Try with explicit domain
$cred = Get-Credential -UserName "DOMAIN\username" -Message "Enter password"

# Or try local administrator
$cred = Get-Credential -UserName ".\Administrator" -Message "Enter password"

# Or try with computer name
$cred = Get-Credential -UserName "G9KN7PZ3ESF\username" -Message "Enter password"
```

---

### Issue 3: Network Connection Failed

**Error**:
```
Test-WSMan : <f:WSManFault xmlns:f="http://schemas.microsoft.com/wbem/wsman/1/wsmanfault" Code="2150858770"
Machine="localhost"><f:Message>The WinRM client cannot complete the operation within the time specified. Check if
the machine name is valid and is reachable over the network and firewall exception for the WinRM service is enabled.
```

**Possible Causes**:
1. PC is offline/unreachable
2. Firewall blocking port 5986
3. DNS resolution issues
4. Wrong hostname

**Troubleshooting**:
```powershell
# Test basic network connectivity
Test-Connection g9kn7pz3esf.logon.ds.ge.com

# Test DNS resolution
Resolve-DnsName g9kn7pz3esf.logon.ds.ge.com

# Test port 5986 connectivity
Test-NetConnection -ComputerName g9kn7pz3esf.logon.ds.ge.com -Port 5986

# Try with IP address instead of hostname
Test-WSMan -ComputerName 192.168.x.x -UseSSL -Port 5986 -SessionOption $sessionOption
```

---

### Issue 4: WinRM Client Configuration

**Error**:
```
The client cannot connect to the destination specified in the request.
```

**Solution**: Configure WinRM client settings on your computer:
```powershell
# Run as Administrator on your computer
# Enable basic authentication (if needed)
Set-Item WSMan:\localhost\Client\Auth\Basic -Value $true

# Add remote PC to trusted hosts (if not in same domain)
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "g9kn7pz3esf.logon.ds.ge.com" -Concatenate

# Or add wildcard for all PCs
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*.logon.ds.ge.com" -Concatenate

# View current trusted hosts
Get-Item WSMan:\localhost\Client\TrustedHosts
```

---

## Complete Testing Script

Save this as `Test-RemoteConnection.ps1`:

```powershell
#Requires -Version 5.1
<#
.SYNOPSIS
    Test WinRM HTTPS connection to remote PC
.EXAMPLE
    .\Test-RemoteConnection.ps1 -ComputerName g9kn7pz3esf.logon.ds.ge.com
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$ComputerName,

    [Parameter(Mandatory=$false)]
    [int]$Port = 5986,

    [Parameter(Mandatory=$false)]
    [switch]$SkipCertificateCheck
)

Write-Host "`n=== Testing WinRM HTTPS Connection ===" -ForegroundColor Cyan
Write-Host "Target: $ComputerName" -ForegroundColor Gray
Write-Host "Port: $Port" -ForegroundColor Gray
Write-Host ""

# Test 1: Basic connectivity
Write-Host "Test 1: Basic Network Connectivity" -ForegroundColor Yellow
try {
    $ping = Test-Connection $ComputerName -Count 2 -ErrorAction Stop
    Write-Host "  [OK] PC is reachable (avg: $($ping[0].ResponseTime)ms)" -ForegroundColor Green
} catch {
    Write-Host "  [FAIL] Cannot reach PC: $($_.Exception.Message)" -ForegroundColor Red
    exit 1
}

# Test 2: DNS resolution
Write-Host "`nTest 2: DNS Resolution" -ForegroundColor Yellow
try {
    $dns = Resolve-DnsName $ComputerName -ErrorAction Stop
    Write-Host "  [OK] DNS resolves to: $($dns.IPAddress)" -ForegroundColor Green
} catch {
    Write-Host "  [FAIL] DNS resolution failed: $($_.Exception.Message)" -ForegroundColor Red
}

# Test 3: Port connectivity
Write-Host "`nTest 3: Port $Port Connectivity" -ForegroundColor Yellow
try {
    $portTest = Test-NetConnection -ComputerName $ComputerName -Port $Port -ErrorAction Stop
    if ($portTest.TcpTestSucceeded) {
        Write-Host "  [OK] Port $Port is open" -ForegroundColor Green
    } else {
        Write-Host "  [FAIL] Port $Port is closed or filtered" -ForegroundColor Red
    }
} catch {
    Write-Host "  [FAIL] Cannot test port: $($_.Exception.Message)" -ForegroundColor Red
}

# Test 4: WinRM HTTPS connectivity
Write-Host "`nTest 4: WinRM HTTPS Connectivity" -ForegroundColor Yellow

$sessionOption = $null
if ($SkipCertificateCheck) {
    Write-Host "  [INFO] Skipping certificate validation (testing mode)" -ForegroundColor Gray
    $sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck
}

try {
    if ($sessionOption) {
        $result = Test-WSMan -ComputerName $ComputerName -UseSSL -Port $Port -SessionOption $sessionOption -ErrorAction Stop
    } else {
        $result = Test-WSMan -ComputerName $ComputerName -UseSSL -Port $Port -ErrorAction Stop
    }
    Write-Host "  [OK] WinRM HTTPS is responding" -ForegroundColor Green
    Write-Host "  Product: $($result.ProductVendor) $($result.ProductVersion)" -ForegroundColor Gray
} catch {
    Write-Host "  [FAIL] WinRM HTTPS not responding: $($_.Exception.Message)" -ForegroundColor Red
    Write-Host "`n  Tip: Try with -SkipCertificateCheck flag if certificate trust is an issue" -ForegroundColor Yellow
    exit 1
}

# Test 5: Authenticated connection
Write-Host "`nTest 5: Authenticated Connection" -ForegroundColor Yellow
Write-Host "  Enter credentials for remote connection..." -ForegroundColor Gray

$cred = Get-Credential -Message "Enter credentials for $ComputerName"

try {
    $params = @{
        ComputerName = $ComputerName
        Credential = $cred
        UseSSL = $true
        Port = $Port
        ScriptBlock = {
            [PSCustomObject]@{
                Hostname = $env:COMPUTERNAME
                IPAddress = (Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -notlike "127.*"})[0].IPAddress
                WinRMStatus = (Get-Service WinRM).Status
                OSVersion = (Get-CimInstance Win32_OperatingSystem).Caption
            }
        }
    }

    if ($sessionOption) {
        $params.SessionOption = $sessionOption
    }

    $remoteInfo = Invoke-Command @params

    Write-Host "  [OK] Successfully connected and executed remote command" -ForegroundColor Green
    Write-Host "`n  Remote Computer Information:" -ForegroundColor Cyan
    Write-Host "    Hostname: $($remoteInfo.Hostname)" -ForegroundColor Gray
    Write-Host "    IP Address: $($remoteInfo.IPAddress)" -ForegroundColor Gray
    Write-Host "    WinRM Status: $($remoteInfo.WinRMStatus)" -ForegroundColor Gray
    Write-Host "    OS: $($remoteInfo.OSVersion)" -ForegroundColor Gray

} catch {
    Write-Host "  [FAIL] Authentication or command execution failed: $($_.Exception.Message)" -ForegroundColor Red
    exit 1
}

# Summary
Write-Host "`n=== Test Summary ===" -ForegroundColor Cyan
Write-Host "All tests passed! WinRM HTTPS is working correctly." -ForegroundColor Green
Write-Host ""
Write-Host "You can now connect using:" -ForegroundColor Yellow
Write-Host "  Enter-PSSession -ComputerName $ComputerName -Credential `$cred -UseSSL -Port $Port $(if($SkipCertificateCheck){'-SessionOption $sessionOption'})" -ForegroundColor White
Write-Host ""
```

**Usage**:
```powershell
# Basic test (will fail if certificate not trusted)
.\Test-RemoteConnection.ps1 -ComputerName g9kn7pz3esf.logon.ds.ge.com

# Test with certificate check skipped (for self-signed certs)
.\Test-RemoteConnection.ps1 -ComputerName g9kn7pz3esf.logon.ds.ge.com -SkipCertificateCheck
```

---

## Testing Multiple PCs

Test all deployed PCs at once:

```powershell
# Read hostnames from file
$hostnames = Get-Content "C:\path\to\shopfloor-hostnames.txt"

# Test each PC
$results = foreach ($hostname in $hostnames) {
    $fqdn = "$hostname.logon.ds.ge.com"

    Write-Host "Testing $fqdn..." -ForegroundColor Yellow

    try {
        $test = Test-WSMan -ComputerName $fqdn -UseSSL -Port 5986 -ErrorAction Stop
        [PSCustomObject]@{
            Hostname = $hostname
            FQDN = $fqdn
            Status = "Success"
            Error = $null
        }
    } catch {
        [PSCustomObject]@{
            Hostname = $hostname
            FQDN = $fqdn
            Status = "Failed"
            Error = $_.Exception.Message
        }
    }
}

# Show summary
$results | Format-Table -AutoSize
$successCount = ($results | Where-Object {$_.Status -eq "Success"}).Count
Write-Host "`nSuccessful: $successCount / $($results.Count)" -ForegroundColor Cyan
```

---

## Quick Commands Reference

```powershell
# Basic test
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986

# Test with cert skip
$sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck
Test-WSMan -ComputerName g9kn7pz3esf.logon.ds.ge.com -UseSSL -Port 5986 -SessionOption $sessionOption

# Interactive session
$cred = Get-Credential
Enter-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -SessionOption $sessionOption

# Single command
Invoke-Command -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -SessionOption $sessionOption -ScriptBlock { hostname }

# Create session
$session = New-PSSession -ComputerName g9kn7pz3esf.logon.ds.ge.com -Credential $cred -UseSSL -Port 5986 -SessionOption $sessionOption
Invoke-Command -Session $session -ScriptBlock { Get-Service }
Remove-PSSession $session
```

---

## Next Steps

1.  Run the updated deployment on test PC (with wildcard CN fix)
2.  Use these commands to test connectivity
3.  Verify remote commands work correctly
4.  If successful, deploy to 3-5 more PCs
5.  Test connectivity to all deployed PCs
6.  Document any issues in deployment logs
7.  Proceed with production rollout

---

**Document Created**: 2025-10-17
**Status**: Ready for testing
**Target PC**: g9kn7pz3esf.logon.ds.ge.com:5986