PowerShell remoting

PowerShell remoting

This page covers the PowerShell remoting session type: an interactive remote PowerShell on a Windows server, in a terminal tab like SSH, over WinRM. It explains the options, how the login is found, what works through WireGuard, the errors people run into, what the server needs, and what the assistant can do in such a tab.

How it works

Cablebag does not speak WinRM itself. The tab runs Windows PowerShell on this PC, and that PowerShell opens the remote session (New-PSSession, then Enter-PSSession). So every way of logging in that Windows knows, Windows' own certificate checks, the TrustedHosts rule and your group policies all behave exactly as in any PowerShell window, and the remote prompt, tab completion and exit work as you expect. Nothing extra is installed: Windows PowerShell 5.1 is part of Windows 10 and 11.

The password never shows on screen or on a command line: Cablebag hands the settings and the password to PowerShell over a private pipe meant for that one process, and PowerShell keeps the password only as a SecureString. It is not in PowerShell's history, in a transcript or in Cablebag's terminal log.

The session

Press Ctrl+Shift+N and choose PowerShell remoting ("Remote PowerShell on a Windows server") under Terminal. Then:

• Remote host, User name and Port. With Negotiate or Kerberos the user name may stay empty: the placeholder says "Your Windows login", and the session logs in as you, which is the usual case in a domain. With CredSSP or Basic a user name and password are needed. Write a domain account as DOMAIN\user or user@domain.
• Connection: HTTP (port 5985) or HTTPS (port 5986). The port follows the choice unless you changed it by hand. Over HTTP the login and the session are still encrypted by Windows.
• Log in with: Negotiate (the usual choice) (Kerberos in a domain, NTLM elsewhere), Kerberos only (needs a domain and the server's name, not its IP address), CredSSP (lets the server log in further as you, to a file share or another server; it has to be allowed on this PC and on the server first) or Basic (HTTPS only) (for local accounts on servers outside a domain).
• Accept any certificate (for a self-signed one; Cablebag then cannot tell the real server from an impostor): shown with HTTPS only.
• Login from the vault: a login from one of your Credential sources.
• Network: a WireGuard network; see below.

Under PowerShell remoting options:

• Endpoint on the server: leave it empty for the usual Windows PowerShell endpoint (Microsoft.PowerShell). Fill it in for a restricted endpoint (Just Enough Administration) or for PowerShell 7 on the server (PowerShell.7).
• When the session goes through a WireGuard network, a note here states the limits (see below).

Notes, tab colour and word colours work as for other terminals. A folder's Folder settings give the session its user name, vault login and network when it has none of its own.

Settings that cannot work are refused before anything starts: Basic over HTTP, Kerberos to an IP address, and Kerberos through WireGuard.

Quick connect works too: in the search box (Ctrl+K), type winrm server to open a tab without saving a session.

Logging in

The password comes, in this order, from the login linked under Login from the vault, from the passwords kept on this PC, from a login in an open credential source that fits the server, or from a question with Remember in the password vault, which saves it only after the login worked. Settings, Passwords on this PC then lists it as WINRM.

The tab shows connecting, connected or failed for real: PowerShell reports whether the login worked. When it fails, PowerShell's own message is shown with a plain explanation under it for the common cases (below), and R connects again. Typing exit, or the remote session dropping, ends the tab with "The remote session ended."; the tab never drops you into a local shell on this PC. Closing the tab stops PowerShell, also while it is still connecting.

Through WireGuard

A PowerShell remoting session can choose a Network like other sessions, and Cablebag then reaches the server through the tunnel from a port on this PC. Because PowerShell connects to that local port rather than to the server's name, there are limits, which the editor states under PowerShell remoting options:

• HTTPS is the way. The server's certificate is made for its name, not for a local address, so Cablebag checks the certificate's name itself, through the tunnel, the way Windows would (trusted issuer, made for the real name), and Windows then checks who issued it. With Accept any certificate both checks are skipped, as without WireGuard.
• HTTP fails with the TrustedHosts message: Windows only sends this kind of login to servers on its list of trusted hosts, and the local address is not on it. The hint says to use HTTPS.
• Kerberos cannot work through WireGuard and is refused before anything starts; choose Negotiate.
• The remote prompt reads [127.0.0.1]: through WireGuard, because that is the address PowerShell connected to.

See WireGuard per session.

Common errors and what to do

Under PowerShell's own message, Cablebag adds one of these:

• The TrustedHosts rule: "Windows only sends this login to a server outside your domain over HTTPS, or to a server on its list of trusted hosts." Turn on HTTPS for the session, or have an administrator of this PC add the server to that list; the hint gives the exact command (Set-Item WSMan:\localhost\Client\TrustedHosts -Value <server> -Concatenate). Through WireGuard, only HTTPS helps.
• The certificate was not accepted: Windows does not trust who issued it, or it was made for another name. Use the name the certificate was made for, or, for a self-signed certificate, turn on Accept any certificate.
• CredSSP: it must be allowed on this PC first (by an administrator: Enable-WSManCredSSP -Role Client -DelegateComputer <server>) and on the server (Enable-WSManCredSSP -Role Server).
• Access denied: the server refused this login. Check the user name (DOMAIN\user or user@domain for a domain account) and the password; the account also has to be an administrator or a member of Remote Management Users on the server.
• No WinRM service answered: check that PowerShell remoting is switched on there (Enable-PSRemoting, as an administrator), that the HTTP or HTTPS listener is set up, and that the firewall lets the port through.

What the server needs

On the server, in an administrator PowerShell: Enable-PSRemoting -Force. That switches the WinRM service on, sets up the HTTP listener on port 5985 and opens the firewall for it.

For HTTPS as well, the server needs a certificate for its name and an HTTPS listener on port 5986. With a self-signed certificate it is, for example:

$c = New-SelfSignedCertificate -DnsName <server name> -CertStoreLocation Cert:\LocalMachine\My
New-Item -Path WSMan:\localhost\Listener -Transport HTTPS -Address * -CertificateThumbPrint $c.Thumbprint -Force
New-NetFirewallRule -DisplayName "WinRM HTTPS" -Direction Inbound -Protocol TCP -LocalPort 5986 -Action Allow

A self-signed certificate needs Accept any certificate in the session; a certificate from an authority this PC trusts does not.

The account you log in with has to be an administrator on the server or a member of its Remote Management Users group.

The assistant in a PowerShell remoting tab

The Assistant treats the tab as a Windows server. It can run commands there, written in PowerShell, as the login the tab connected with: reads run at once, changes wait for your OK as usual, and there is no sudo or elevation step. Each command runs in a hidden PowerShell of its own with the same login, kept in memory only while the tab is open. While the tab is not connected, the assistant answers with PowerShell commands for you to run yourself.