Skip to content

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.

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).

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.

Copy From Windows PowerShell from the card and run it in Windows PowerShell or PowerShell 7 on Windows. It:

  1. reads the certificate the instance presents on port 5986;
  2. stops unless its SHA-256 is the one on the card;
  3. 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;
  4. connects with Enter-PSSession -UseSSL, with certificate checking on.
Terminal window
$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):

Terminal window
# In the same PowerShell session, remove only the certificate verified above.
Remove-Item -LiteralPath "Cert:\CurrentUser\Root\$($cert.Thumbprint)"

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())

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.

Over port 5985 your client cannot check the instance, so Windows clients refuse a workgroup instance until you add its address to TrustedHosts:

Terminal window
Set-Item WSMan:\localhost\Client\TrustedHosts -Value '10.0.0.5' -Force
Enter-PSSession -ComputerName 10.0.0.5 -Credential Administrator -Authentication Negotiate
import winrm
winrm.Session("10.0.0.5", auth=("Administrator", password), transport="ntlm").run_ps("hostname")
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'.