powershell-scripts/winrm-https/GETTING_STARTED.md

# Getting Started with WinRM HTTPS

This guide will walk you through setting up WinRM HTTPS for your shopfloor PCs step-by-step, from testing on a single device to full deployment across all 175 shopfloor computers.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Phase 1: Single Device Test](#phase-1-single-device-test)
3. [Phase 2: Small Batch Test](#phase-2-small-batch-test)
4. [Phase 3: Full Deployment](#phase-3-full-deployment)
5. [Daily Operations](#daily-operations)
6. [Troubleshooting](#troubleshooting)

---

## Prerequisites

### What You Need

- [ ] Windows computer with PowerShell 5.1 or later
- [ ] Administrator access to target computers
- [ ] Network connectivity to shopfloor PCs
- [ ] Domain credentials with admin rights
- [ ] All files from the `winrm-https` folder

### Prepare Your Environment

1. **Copy the folder to your Windows computer:**
   ```
   Copy the entire winrm-https folder to:
   C:\Scripts\winrm-https\
   ```

2. **Open PowerShell as Administrator:**
   - Press Windows + X
   - Select "Windows PowerShell (Admin)" or "Terminal (Admin)"

3. **Navigate to the folder:**
   ```powershell
   cd C:\Scripts\winrm-https
   ```

4. **Set execution policy (if needed):**
   ```powershell
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
   ```

---

## Phase 1: Single Device Test

### Step 1.1: Generate Test Certificate

**What this does:** Creates a self-signed wildcard certificate for `*.logon.ds.ge.com` that will work on all shopfloor PCs.

```powershell
# Run the certificate generator
.\Generate-WildcardCert.ps1
```

**You will be prompted for:**
- Certificate password (enter it twice)
- Install to Trusted Root? (Type `Y` for testing)

**Expected output:**
```
=== Generating Self-Signed Wildcard Certificate ===
Domain: *.logon.ds.ge.com
Validity: 2 years

Creating certificate...
[OK] Certificate created successfully

Certificate Details:
  Subject: CN=*.logon.ds.ge.com
  Thumbprint: ABC123...
  Valid From: 2025-10-17
  Valid To: 2027-10-17
  Has Private Key: True

=== Exporting Certificate to PFX ===
Export path: C:\Scripts\winrm-https\wildcard-logon-ds-ge-com-20251017.pfx
[OK] Certificate exported successfully

[SUCCESS] Wildcard certificate generation completed!
```

**Result:** You now have a PFX file (e.g., `wildcard-logon-ds-ge-com-20251017.pfx`)

---

### Step 1.2: Test on Your Local Computer

**What this does:** Tests the complete WinRM HTTPS setup on your current computer.

```powershell
# Run the automated test
.\Test-WinRM-HTTPS-Setup.ps1
```

**What happens:**
1. Uses the certificate you just generated
2. Installs it on your computer
3. Creates HTTPS listener on port 5986
4. Configures Windows Firewall
5. Tests the connection
6. Shows results

**Expected output:**
```
╔════════════════════════════════════════╗
║  WinRM HTTPS Test Setup Wizard        ║
╚════════════════════════════════════════╝

Current computer: YOUR-PC-NAME
Target FQDN: your-pc-name.logon.ds.ge.com

STEP 1: Generate Wildcard Certificate
[OK] Certificate generated: wildcard-logon-ds-ge-com-20251017.pfx

STEP 2: Configure WinRM HTTPS
[OK] WinRM HTTPS setup completed

STEP 3: Verify WinRM Configuration
[OK] WinRM service is running
[OK] HTTPS listener configured

STEP 4: Test Local HTTPS Connection
[OK] Local HTTPS connection successful

✅ Test setup complete!
```

**If you see errors:**
- Ensure you're running PowerShell as Administrator
- Check Windows Firewall is not blocking port 5986
- See [Troubleshooting](#troubleshooting) section below

---

### Step 1.3: Test Remote Connection

**What this does:** Tests connecting to your computer from PowerShell using HTTPS.

```powershell
# Get your computer's FQDN
$hostname = $env:COMPUTERNAME
$fqdn = "$hostname.logon.ds.ge.com"

# Test WinRM HTTPS
Test-WSMan -ComputerName $fqdn -UseSSL -Port 5986

# NOTE: See SECURE_CREDENTIAL_MANAGEMENT.md for secure password handling

# Try creating a remote session
$sessionOption = New-PSSessionOption -SkipCACheck -SkipCNCheck
$session = New-PSSession -ComputerName $fqdn -UseSSL -Port 5986 -SessionOption $sessionOption

# If successful, test running a command
Invoke-Command -Session $session -ScriptBlock {
    Write-Host "Successfully connected via WinRM HTTPS!"
    Get-ComputerInfo | Select-Object CsName, OsName, WindowsVersion
}

# Clean up
Remove-PSSession $session
```

**Expected output:**
```
Successfully connected via WinRM HTTPS!

CsName      OsName                    WindowsVersion
------      ------                    --------------
YOUR-PC     Microsoft Windows 11 Pro  10.0.22631
```

**✅ Success!** If this works, you're ready to move to the next phase.

---

## Phase 2: Small Batch Test

### Step 2.1: Select Test Computers

Choose 3-5 shopfloor PCs for initial testing.

```powershell
# View available shopfloor PCs
Get-Content .\shopfloor-hostnames.txt | Select-Object -First 10
```

**Create a test list:**
```powershell
# Create a small test file
@"
G1JJVH63ESF
G1JJXH63ESF
G1JKYH63ESF
"@ | Out-File -FilePath .\test-hostnames.txt -Encoding ASCII
```

---

### Step 2.2: Deploy Certificate to Test PCs

**Option A: Manual Deployment (Recommended for first test)**

For each test PC:

1. **Copy certificate to the PC:**
   ```powershell
   # Replace HOSTNAME with actual hostname
   $hostname = "G1JJVH63ESF"
   $targetPath = "\\$hostname.logon.ds.ge.com\C$\Temp\WinRM-Setup"

   # Create directory
   New-Item -Path $targetPath -ItemType Directory -Force

   # Copy files
   Copy-Item ".\wildcard-logon-ds-ge-com-*.pfx" -Destination $targetPath
   Copy-Item ".\Setup-WinRM-HTTPS.ps1" -Destination $targetPath
   ```

2. **Run setup on the PC:**
   ```powershell
   # Connect to the PC (if WinRM HTTP is available)
   Enter-PSSession -ComputerName "$hostname.logon.ds.ge.com"

   # Or physically/RDP to the PC and run:
   cd C:\Temp\WinRM-Setup

   # SECURE: Let script prompt for password
   .\Setup-WinRM-HTTPS.ps1 -CertificatePath ".\wildcard-logon-ds-ge-com-20251017.pfx" `
       -Domain "logon.ds.ge.com"
   # (Will prompt: "Enter certificate password:")

   # OR use stored password (see SECURE_CREDENTIAL_MANAGEMENT.md)
   ```

**Option B: Remote Deployment (If existing access available)**

```powershell
# If you already have WinRM HTTP or admin access
$testPCs = Get-Content .\test-hostnames.txt

# SECURE: Use stored password or let script prompt
# See SECURE_CREDENTIAL_MANAGEMENT.md for details
$certPass = Import-Clixml -Path "C:\Secure\cert-password.xml"
$cred = Get-Credential  # Domain admin credentials

foreach ($hostname in $testPCs) {
    $fqdn = "$hostname.logon.ds.ge.com"
    Write-Host "Deploying to $fqdn..." -ForegroundColor Yellow

    # Copy files via network share
    $remotePath = "\\$fqdn\C$\Temp\WinRM-Setup"
    New-Item -Path $remotePath -ItemType Directory -Force
    Copy-Item ".\wildcard-*.pfx" -Destination $remotePath
    Copy-Item ".\Setup-WinRM-HTTPS.ps1" -Destination $remotePath

    # Execute remotely (requires existing WinRM/admin access)
    Invoke-Command -ComputerName $fqdn -Credential $cred -ScriptBlock {
        param($CertPath, $CertPass, $Domain)
        Set-Location C:\Temp\WinRM-Setup
        .\Setup-WinRM-HTTPS.ps1 -CertificatePath $CertPath `
            -CertificatePassword $CertPass -Domain $Domain
    } -ArgumentList "C:\Temp\WinRM-Setup\wildcard-logon-ds-ge-com-20251017.pfx", $certPass, "logon.ds.ge.com"
}
```

---

### Step 2.3: Test HTTPS Connections

```powershell
# Test connections to your test PCs
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\test-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -TestConnections
```

**Expected output:**
```
=== Remote Asset Collection Script (HTTPS) ===
Target computers (FQDNs): G1JJVH63ESF.logon.ds.ge.com, G1JJXH63ESF.logon.ds.ge.com...

Resolving IP addresses...
Resolving G1JJVH63ESF.logon.ds.ge.com... [10.134.48.12]
Resolving G1JJXH63ESF.logon.ds.ge.com... [10.134.48.13]

Testing HTTPS connections only...
Testing G1JJVH63ESF.logon.ds.ge.com... [OK]
Testing G1JJXH63ESF.logon.ds.ge.com... [OK]
Testing G1JKYH63ESF.logon.ds.ge.com... [OK]
```

**If you see failures:**
- Check DNS resolution
- Verify certificate is installed on target PC
- Check firewall rules
- See [Troubleshooting](#troubleshooting)

---

### Step 2.4: Test Asset Collection

```powershell
# Run actual asset collection on test PCs
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\test-hostnames.txt" `
    -Domain "logon.ds.ge.com"
```

**You will be prompted for credentials** (use domain admin account)

**Expected output:**
```
Validating remote HTTPS connections and script availability...
Validating G1JJVH63ESF.logon.ds.ge.com... [OK]
Validating G1JJXH63ESF.logon.ds.ge.com... [OK]

Starting asset collection on 3 computers...
Max concurrent sessions: 5
Using HTTPS on port: 5986

Processing batch: G1JJVH63ESF.logon.ds.ge.com, G1JJXH63ESF.logon.ds.ge.com...
[OK] G1JJVH63ESF.logon.ds.ge.com - Completed successfully
[OK] G1JJXH63ESF.logon.ds.ge.com - Completed successfully
[OK] G1JKYH63ESF.logon.ds.ge.com - Completed successfully

=== Collection Summary ===
Total computers: 3
Successful: 3
Failed: 0

Collection completed. Success: 3, Failed: 0
```

**✅ Success!** If this works, you're ready for full deployment.

---

## Phase 3: Full Deployment

### Step 3.1: Plan Deployment

**Deployment strategies:**

**Option A: Rolling Deployment (Recommended)**
- Deploy to 10-20 PCs at a time
- Verify each batch before continuing
- Minimize risk, easier troubleshooting

**Option B: Mass Deployment**
- Deploy to all 175 PCs at once
- Faster but higher risk
- Requires good preparation

**We recommend Option A for first deployment.**

---

### Step 3.2: Create Deployment Batches

```powershell
# Split hostnames into batches of 20
$allHostnames = Get-Content .\shopfloor-hostnames.txt
$batchSize = 20
$batchNumber = 1

for ($i = 0; $i -lt $allHostnames.Count; $i += $batchSize) {
    $batch = $allHostnames[$i..([Math]::Min($i + $batchSize - 1, $allHostnames.Count - 1))]
    $batchFile = ".\batch-$batchNumber.txt"
    $batch | Out-File -FilePath $batchFile -Encoding ASCII
    Write-Host "Created $batchFile with $($batch.Count) hosts"
    $batchNumber++
}
```

**Result:** Creates files like `batch-1.txt`, `batch-2.txt`, etc.

---

### Step 3.3: Deploy Batch 1

```powershell
# Deploy certificate to first batch
$batch1 = Get-Content .\batch-1.txt
$certPass = ConvertTo-SecureString "YourPassword" -AsPlainText -Force

foreach ($hostname in $batch1) {
    Write-Host "Deploying to $hostname..." -ForegroundColor Cyan

    try {
        # Copy files
        $targetPath = "\\$hostname.logon.ds.ge.com\C$\Temp\WinRM-Setup"
        New-Item -Path $targetPath -ItemType Directory -Force -ErrorAction Stop
        Copy-Item ".\wildcard-*.pfx" -Destination $targetPath -ErrorAction Stop
        Copy-Item ".\Setup-WinRM-HTTPS.ps1" -Destination $targetPath -ErrorAction Stop
        Write-Host "  [OK] Files copied" -ForegroundColor Green
    }
    catch {
        Write-Host "  [FAIL] $($_.Exception.Message)" -ForegroundColor Red
    }
}
```

---

### Step 3.4: Execute Setup on Batch 1

**Option A: Remote Execution**
```powershell
$cred = Get-Credential  # Get credentials once
$batch1 = Get-Content .\batch-1.txt

foreach ($hostname in $batch1) {
    $fqdn = "$hostname.logon.ds.ge.com"
    Write-Host "Setting up WinRM HTTPS on $fqdn..." -ForegroundColor Yellow

    try {
        Invoke-Command -ComputerName $fqdn -Credential $cred -ScriptBlock {
            param($CertPath, $CertPass, $Domain)
            Set-Location C:\Temp\WinRM-Setup
            .\Setup-WinRM-HTTPS.ps1 -CertificatePath $CertPath `
                -CertificatePassword $CertPass -Domain $Domain
        } -ArgumentList "C:\Temp\WinRM-Setup\wildcard-logon-ds-ge-com-20251017.pfx", $certPass, "logon.ds.ge.com"

        Write-Host "  [OK] Setup completed" -ForegroundColor Green
    }
    catch {
        Write-Host "  [FAIL] $($_.Exception.Message)" -ForegroundColor Red
    }
}
```

**Option B: Group Policy / SCCM**
- Deploy via your organization's deployment tools
- Use startup script to run Setup-WinRM-HTTPS.ps1

---

### Step 3.5: Verify Batch 1

```powershell
# Test connections
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\batch-1.txt" `
    -Domain "logon.ds.ge.com" `
    -TestConnections

# Review results
Write-Host "`nPress any key to continue with next batch or Ctrl+C to stop..."
$null = $Host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")
```

---

### Step 3.6: Continue with Remaining Batches

```powershell
# Repeat steps 3.3-3.5 for each batch
$batchFiles = Get-ChildItem .\batch-*.txt | Sort-Object Name

foreach ($batchFile in $batchFiles) {
    Write-Host "`n========================================" -ForegroundColor Cyan
    Write-Host "Processing $($batchFile.Name)" -ForegroundColor Cyan
    Write-Host "========================================" -ForegroundColor Cyan

    # Run deployment and verification for this batch
    # (Use steps 3.3-3.5)

    Write-Host "`nBatch complete. Continue? (Y/N)" -ForegroundColor Yellow
    $continue = Read-Host
    if ($continue -ne 'Y') { break }
}
```

---

### Step 3.7: Final Verification

```powershell
# Test all 175 shopfloor PCs
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -TestConnections

# Review summary
Write-Host "`n=== Deployment Summary ===" -ForegroundColor Cyan
Write-Host "Check the log file for details:"
Write-Host ".\logs\remote-collection-https.log"
```

---

## Daily Operations

### Running Asset Collection

**Once everything is deployed, daily collection is simple:**

```powershell
# Navigate to folder
cd C:\Scripts\winrm-https

# Run collection (will prompt for credentials)
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com"
```

**Or use stored credentials:**
```powershell
# Store credentials (one time)
$cred = Get-Credential
$cred | Export-Clixml -Path "C:\Secure\shopfloor-cred.xml"

# Use in collection script
$cred = Import-Clixml -Path "C:\Secure\shopfloor-cred.xml"
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -Credential $cred
```

**Automated scheduled task:**
```powershell
# Create scheduled task to run daily
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" `
    -Argument "-ExecutionPolicy Bypass -File C:\Scripts\winrm-https\Invoke-RemoteAssetCollection-HTTPS.ps1 -HostnameListFile C:\Scripts\winrm-https\shopfloor-hostnames.txt -Domain logon.ds.ge.com"

$trigger = New-ScheduledTaskTrigger -Daily -At 2AM

Register-ScheduledTask -TaskName "Shopfloor Asset Collection" `
    -Action $action -Trigger $trigger -User "DOMAIN\ServiceAccount" `
    -RunLevel Highest
```

---

## Troubleshooting

### Problem: DNS Resolution Fails

```
Resolving hostname.logon.ds.ge.com... [DNS FAILED]
```

**Solution:**
```powershell
# Check DNS
Resolve-DnsName "hostname.logon.ds.ge.com"

# If fails, verify DNS server has records for *.logon.ds.ge.com
# Or add to hosts file temporarily:
Add-Content C:\Windows\System32\drivers\etc\hosts "10.134.48.12 G1JJVH63ESF.logon.ds.ge.com"
```

---

### Problem: Connection Refused

```
Testing hostname.logon.ds.ge.com... [FAIL]
```

**Solution:**
```powershell
# Check if port 5986 is open
Test-NetConnection -ComputerName "hostname.logon.ds.ge.com" -Port 5986

# If fails:
# 1. Check Windows Firewall on target PC
# 2. Verify WinRM HTTPS listener exists
# 3. Confirm certificate is installed
```

**On target PC:**
```powershell
# Check firewall
Get-NetFirewallRule -DisplayName "WinRM HTTPS-In"

# Check listener
winrm enumerate winrm/config/listener

# Check certificate
Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
```

---

### Problem: Certificate Error

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

**Solution for Self-Signed Certificates:**

**Option 1: Install Root Certificate on Management Server**
```powershell
# Export the certificate as CER (public key only)
$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
Export-Certificate -Cert $cert -FilePath ".\wildcard-root.cer"

# Import to Trusted Root on management server
Import-Certificate -FilePath ".\wildcard-root.cer" -CertStoreLocation Cert:\LocalMachine\Root
```

**Option 2: Skip Certificate Check (Testing Only)**
```powershell
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -SkipCertificateCheck
```

---

### Problem: Access Denied

```
[FAIL] hostname.logon.ds.ge.com - Access is denied
```

**Solution:**
```powershell
# Verify credentials have admin rights on target PC
# Test with manual connection:
$cred = Get-Credential
Enter-PSSession -ComputerName "hostname.logon.ds.ge.com" -Credential $cred -UseSSL

# If successful, credentials are correct
# If fails, check:
# 1. User is member of local Administrators group
# 2. UAC is not blocking remote admin
# 3. Correct domain/username format (DOMAIN\username)
```

---

### Problem: Script Not Found

```
[SCRIPT NOT FOUND]
Script not found on hostname at C:\Scripts\Update-PC-CompleteAsset.ps1
```

**Solution:**
```powershell
# The asset collection script must exist on target PCs
# Deploy Update-PC-CompleteAsset.ps1 to each PC first

# Or specify different path:
.\Invoke-RemoteAssetCollection-HTTPS.ps1 `
    -HostnameListFile ".\shopfloor-hostnames.txt" `
    -Domain "logon.ds.ge.com" `
    -ScriptPath "D:\Scripts\Update-PC-CompleteAsset.ps1"
```

---

### Problem: Certificate Expired

```powershell
# Check certificate expiration
$cert = Get-ChildItem Cert:\LocalMachine\My | Where-Object {$_.Subject -like "*logon.ds.ge.com*"}
$cert.NotAfter

# If expired, generate new certificate and redeploy
.\Generate-WildcardCert.ps1 -ValidityYears 2
```

---

### Getting More Help

1. **Check logs:**
   ```powershell
   Get-Content .\logs\remote-collection-https.log -Tail 50
   ```

2. **Read detailed documentation:**
   ```
   WINRM_HTTPS_DEPLOYMENT_GUIDE.md
   ```

3. **Get script help:**
   ```powershell
   Get-Help .\Setup-WinRM-HTTPS.ps1 -Full
   Get-Help .\Invoke-RemoteAssetCollection-HTTPS.ps1 -Full
   ```

4. **Test individual components:**
   ```powershell
   # Test DNS
   Resolve-DnsName "hostname.logon.ds.ge.com"

   # Test port
   Test-NetConnection -ComputerName "hostname.logon.ds.ge.com" -Port 5986

   # Test WinRM
   Test-WSMan -ComputerName "hostname.logon.ds.ge.com" -UseSSL -Port 5986
   ```

---

## Quick Reference

### Important Files

| File | Purpose |
|------|---------|
| `Generate-WildcardCert.ps1` | Create certificate |
| `Setup-WinRM-HTTPS.ps1` | Setup WinRM on PC |
| `Test-WinRM-HTTPS-Setup.ps1` | Test setup |
| `Invoke-RemoteAssetCollection-HTTPS.ps1` | Run collection |
| `shopfloor-hostnames.txt` | PC list (175 PCs) |

### Important Commands

```powershell
# Generate certificate
.\Generate-WildcardCert.ps1

# Test single PC
.\Test-WinRM-HTTPS-Setup.ps1

# Test connections
.\Invoke-RemoteAssetCollection-HTTPS.ps1 -HostnameListFile ".\shopfloor-hostnames.txt" -Domain "logon.ds.ge.com" -TestConnections

# Run collection
.\Invoke-RemoteAssetCollection-HTTPS.ps1 -HostnameListFile ".\shopfloor-hostnames.txt" -Domain "logon.ds.ge.com"

# Check logs
Get-Content .\logs\remote-collection-https.log -Tail 50
```

### Default Values

- **HTTPS Port:** 5986
- **Domain:** logon.ds.ge.com
- **Certificate Validity:** 2 years
- **Max Concurrent Sessions:** 5
- **Log Location:** `.\logs\remote-collection-https.log`

---

## Summary

Follow these phases:

1. ✅ **Phase 1:** Test on single device (your computer)
2. ✅ **Phase 2:** Test on 3-5 shopfloor PCs
3. ✅ **Phase 3:** Deploy to all 175 PCs in batches
4. ✅ **Daily Ops:** Run automated collection

**Total Time:**
- Phase 1: 15-30 minutes
- Phase 2: 1-2 hours
- Phase 3: 4-8 hours (depending on method)

**Good luck with your deployment!** 🚀