Connect to Windows instances over WinRM
Updated
WinRM is PowerShell remoting: Enter-PSSession, Invoke-Command and tools such as pywinrm and
Ansible use it. You choose whether instances accept it when you build the Windows image.
Choose WinRM when you build the image
Section titled “Choose WinRM when you build the image”On Images → Build Windows image, step Edition and options, pick one of:
| WinRM | Instances from the image |
|---|---|
| Off (default) | Do not accept WinRM from the network. |
| HTTP (port 5985) | Accept WinRM on port 5985. Messages are encrypted, but your client cannot check which machine it reached. Use it only on internal networks. |
| HTTPS (port 5986) | Accept WinRM on port 5986 over TLS, with a certificate each instance makes for itself. Your client can check that it reached this instance. |
| HTTP and HTTPS | Both listeners. |
When you enable WinRM, the service starts automatically, the firewall lets the chosen ports in on every network profile from any address, and sign-in uses Negotiate (NTLM or Kerberos) with the administrator account you give at creation. Basic authentication and unencrypted traffic stay off. A port you did not choose is closed in the image.
The Images page and the create form show what an image was built with, for example RDP, WinRM over HTTPS (5986).
How the HTTPS certificate works
Section titled “How the HTTPS certificate works”The image carries no certificate. When an instance boots for the first time, Windows makes a self-signed certificate for it:
- its subject is the instance’s computer name, and it is valid for the computer name and the instance’s current IPv4 and IPv6 addresses;
- its private key cannot be exported, so it never leaves the instance;
- it is valid for one year.
The instance checks this at every boot, when it connects to a network and every 5 minutes. If the computer name or an address changed, or the certificate expires within 30 days, it makes a new one. A new certificate has a new fingerprint.
Virtainer’s guest agent reports the certificate to the host. The instance’s page shows it on Overview → WinRM over HTTPS:
- Certificate SHA-256: the fingerprint to check, with a copy button. This is the SHA-256 of the certificate, not the SHA-1 thumbprint Windows shows in the certificate store.
- Expires and Valid for: the expiry date and the names and addresses the certificate covers. Connect to one of these addresses.
The card appears once the instance has reported a listener, a minute or two after it has finished provisioning. It needs Virtainer Guest Agent 0.4.4 or newer in the image.
Connect from Windows PowerShell
Section titled “Connect from Windows PowerShell”Copy From Windows PowerShell from the card and run it in Windows PowerShell or PowerShell 7 on Windows. It:
- reads the certificate the instance presents on port 5986;
- stops unless its SHA-256 is the one on the card;
- adds exactly that certificate to your account’s trusted root certificates (Windows asks you to
confirm). Windows can only ask on a desktop: in a session without one, such as over SSH, adding
it fails with “The request is not supported”. There, run the commands from an elevated prompt
with
'LocalMachine'in place of'CurrentUser', which trusts the certificate for every user of that computer; - connects with
Enter-PSSession -UseSSL, with certificate checking on.
$vm = '10.0.0.5'$sha256 = 'e298d4be182e6fcc146856d156ef50514390dfe07db0c557b3b22d9f44d2ead1'# Read the certificate the VM presents and check it is the one Virtainer reported.$tcp = [Net.Sockets.TcpClient]::new($vm, 5986)$tls = [Net.Security.SslStream]::new($tcp.GetStream(), $false, { $true })$tls.AuthenticateAsClient($vm)$cert = [Security.Cryptography.X509Certificates.X509Certificate2]::new($tls.RemoteCertificate)$tls.Dispose(); $tcp.Dispose()$seen = -join ([Security.Cryptography.SHA256]::Create().ComputeHash($cert.RawData) | ForEach-Object { $_.ToString('x2') })if ($seen -ne $sha256) { throw "The certificate on $vm is not the one Virtainer reported" }# Trust exactly this certificate for your account (Windows asks you to confirm; with no desktop to ask on, as over SSH, use 'LocalMachine' from an elevated prompt).$store = [Security.Cryptography.X509Certificates.X509Store]::new('Root', 'CurrentUser')$store.Open('ReadWrite'); $store.Add($cert); $store.Close()Enter-PSSession -ComputerName $vm -Port 5986 -UseSSL -Credential (Get-Credential -UserName 'Administrator')Once the certificate is trusted, later sessions only need the last line, or the same parameters on
Invoke-Command and New-PSSession. Over HTTPS you do not add the instance to TrustedHosts.
To stop trusting the certificate, for example after the instance made a new one (Cert:\LocalMachine\Root,
from an elevated prompt, if you added it there):
# In the same PowerShell session, remove only the certificate verified above.Remove-Item -LiteralPath "Cert:\CurrentUser\Root\$($cert.Thumbprint)"Connect with Python (pywinrm)
Section titled “Connect with Python (pywinrm)”From Linux, macOS or Windows with pip install pywinrm, copy From Python (pywinrm) from the
card. It makes the same check, saves the certificate to winrm-vm.pem and uses it as the only
trusted certificate:
import getpass, hashlib, ssl, winrm
vm, sha256 = "10.0.0.5", "e298d4be182e6fcc146856d156ef50514390dfe07db0c557b3b22d9f44d2ead1"# Read the certificate the VM presents and check it is the one Virtainer reported.pem = ssl.get_server_certificate((vm, 5986))if hashlib.sha256(ssl.PEM_cert_to_DER_cert(pem)).hexdigest() != sha256: raise SystemExit(f"the certificate on {vm} is not the one Virtainer reported")with open("winrm-vm.pem", "w") as f: f.write(pem)# Trust exactly this certificate; every request checks it.session = winrm.Session( "https://10.0.0.5:5986/wsman", auth=("Administrator", getpass.getpass()), transport="ntlm", server_cert_validation="validate", ca_trust_path="winrm-vm.pem",)print(session.run_ps("hostname").std_out.decode())Connect from PowerShell 7 on Linux
Section titled “Connect from PowerShell 7 on Linux”The card also offers From PowerShell 7 on Linux. Copy that command for the Linux client: it sets up PSWSMan and its native WSMan library, checks the same certificate SHA-256 and trusts that certificate before connecting. This needs permission to install the module and client library. Use pywinrm instead if that client setup is unavailable; pywinrm is also the option shown here for macOS. SSH is another choice if you built the image with OpenSSH.
Connect over HTTP
Section titled “Connect over HTTP”Over port 5985 your client cannot check the instance, so Windows clients refuse a workgroup
instance until you add its address to TrustedHosts:
Set-Item WSMan:\localhost\Client\TrustedHosts -Value '10.0.0.5' -ForceEnter-PSSession -ComputerName 10.0.0.5 -Credential Administrator -Authentication Negotiateimport winrmwinrm.Session("10.0.0.5", auth=("Administrator", password), transport="ntlm").run_ps("hostname")Troubleshooting
Section titled “Troubleshooting”| What you see | What to do |
|---|---|
| No WinRM over HTTPS card | Check the image on Images: it must say WinRM over HTTPS (5986) or WinRM (5985, HTTPS 5986). The instance must be running with Virtainer Guest Agent 0.4.4 or newer, and the card appears a minute or two after provisioning. |
| The listener on port 5986 has no certificate to present | The instance is making a new certificate. Wait up to 5 minutes. If it stays, restart the instance. |
| The certificate on … is not the one Virtainer reported | Something other than the instance answered, or the instance made a new certificate since the page last refreshed. Reload the page and compare again; do not connect while the fingerprints differ. |
The SSL certificate contains a common name (CN) that does not match the hostname |
Connect to an address listed under Valid for. After an address change, wait up to 5 minutes for the new certificate and run the commands again. |
Access is denied |
Use the administrator account and password you gave when you created the instance. |
| Port 5986 does not answer | The image was built without HTTPS, or a firewall between you and the instance blocks it. |
| Expires is shown in red | The instance did not renew its certificate. Restart the instance; if it stays, open a Shell (SYSTEM) on the instance and run Start-ScheduledTask 'Virtainer WinRM HTTPS'. |