RDP

RDP

Remote Desktop session enumeration, history, lock state, and session actions (connect/disconnect/logoff).

6 function(s) in Public/rdp/.

Functions

• Connect-RdpSession — Establishes a remote control (shadow) connection to an active RDP session
• Disconnect-RdpSession — Disconnects one or more RDP sessions on a local or remote computer
• Get-RdpSession — Retrieves live RDP and console user sessions from local or remote computers
• Get-RdpSessionHistory — Retrieves Remote Desktop Protocol (RDP) session history from Windows Event Log
• Get-RdpSessionLock — Retrieves RDP session lock and unlock event history from Windows Event Log
• Remove-RdpSession — Logs off (removes) an RDP session on local or remote computers

Reference

Connect-RdpSession

Establishes a remote control (shadow) connection to an active RDP session.

Connects to an active RDP session on a remote computer using mstsc.exe shadow mode to observe or interactively control the user's session. Session existence is verified via qwinsta.exe (wrapped by the private Invoke-NativeCommand helper) before the shadow window is opened.

v1.2.0 fix: removed reliance on Win32_TSSession (class unavailable in root\cimv2\TerminalServices) and Win32_TerminalService.RemoteControl() (method does not exist). Both are replaced by qwinsta.exe and mstsc.exe /shadow, which are the documented Windows mechanisms for RDP session shadowing.

Group Policy "Set rules for remote control of RDS user sessions" must permit shadowing on the target server. Press Ctrl+* (numpad asterisk) to exit shadow mode.

Syntax

Connect-RdpSession [-ComputerName <string>] -SessionID <int> [-ControlMode <string>] [-NoUserPrompt] [-Credential <System.Management.Automation.PSCredential>]

Examples

Connect-RdpSession -SessionID 2 -ComputerName 'SERVER01'
Shadows session 2 on SERVER01 in interactive control mode.
The user receives a consent prompt (default behavior).

Get-RdpSession -ComputerName 'APP01' |
Where-Object { $_.UserName -eq 'admin-jdoe' } |
Connect-RdpSession -ControlMode View
Finds the session for admin-jdoe via pipeline and connects in view-only mode.

Connect-RdpSession -SessionID 3 -ComputerName 'WEB01' -NoUserPrompt -WhatIf
Dry-run: shows what would happen without opening the shadow window.

$adminCred = Get-Credential -UserName 'DOMAIN\admin'
Connect-RdpSession -SessionID 5 -ControlMode View -Credential $adminCred

Opens a view-only shadow of session 5, with mstsc.exe running as $adminCred.

Output: PSWinOps.RdpSessionAction

Connection action result with session details and status. In addition to the base RdpSessionAction properties (ComputerName, SessionID, Action, Success, Timestamp), this function adds: ControlMode [string] — 'Control' or 'View'. ExitCode [int] — mstsc.exe process exit code. Message [string] — human-readable result summary.

---

Disconnect-RdpSession

Disconnects one or more RDP sessions on a local or remote computer.

Uses the built-in tsdiscon.exe utility to disconnect RDP sessions by session ID. Supports local and remote computers with optional credential pass-through via WinRM remoting. Accepts pipeline input from Get-RdpSession for bulk operations. Returns a result object per session indicating success or failure. For remote targets without credentials, Invoke-Command sends the disconnect command over WinRM. When credentials are provided, they are passed through Invoke-Command's -Credential parameter.

Syntax

Disconnect-RdpSession [-ComputerName <string>] -SessionID <int[]> [-Credential <System.Management.Automation.PSCredential>]

Examples

Disconnect-RdpSession -ComputerName 'SRV01' -SessionID 3
Disconnects session ID 3 on server SRV01 after confirmation prompt.

Get-RdpSession -ComputerName 'SRV01' | Disconnect-RdpSession -Confirm:$false
Pipes all active sessions from SRV01 and disconnects them without prompting.

Disconnect-RdpSession -ComputerName 'SRV01' -SessionID 3, 5 -Credential (Get-Credential) -Verbose
Disconnects sessions 3 and 5 on SRV01 using alternate credentials with verbose output.

Output: PSWinOps.RdpSessionAction

Disconnection action result with session details and status.

---

Get-RdpSession

Retrieves live RDP and console user sessions from local or remote computers.

Queries the Terminal Services session manager on one or more computers using quser.exe (Query User). This executable reads directly from the Windows session table maintained by the Session Manager and returns exactly one row per live session -- no stale LSA records from past connections, no duplicate entries caused by multi-package authentication (Negotiate + Kerberos).

Local machines are queried directly. Remote machines are queried via Invoke-Command (WinRM), which executes quser.exe in the remote session and returns its output. Each session is emitted as a structured PSCustomObject containing user name, session name, state, idle time, and logon time.

State values returned by quser: Active, Disc (disconnected). Idle time of zero ([TimeSpan]::Zero) means the session is currently in use.

Syntax

Get-RdpSession [-ComputerName <string[]>] [-Credential <System.Management.Automation.PSCredential>]

Examples

Get-RdpSession
Lists all live user sessions on the local computer.

Get-RdpSession -ComputerName 'SRV01', 'SRV02' -Credential (Get-Credential)
Queries two remote servers, prompting once for credentials.

'WEB01', 'APP01' | Get-RdpSession | Where-Object { $_.State -eq 'Disc' }
Finds all disconnected sessions across multiple servers via pipeline input.

Get-RdpSession | Where-Object { $_.IdleTime -gt [TimeSpan]::FromHours(4) }
Returns all sessions idle for more than 4 hours on the local machine.

Output: PSWinOps.ActiveRdpSession

Active RDP session details including user, state, and logon time.

---

Get-RdpSessionHistory

Retrieves Remote Desktop Protocol (RDP) session history from Windows Event Log.

Queries the Microsoft-Windows-TerminalServices-LocalSessionManager/Operational event log on one or more computers to retrieve RDP session logon, logoff, disconnect, and reconnection events. Returns structured objects with user, IP address, and action details.

The function filters events by ID:

• 21: Logon
• 23: Logoff
• 24: Disconnected
• 25: Reconnection

Syntax

Get-RdpSessionHistory [-ComputerName <string[]>] [-StartTime <datetime>] [-Credential <System.Management.Automation.PSCredential>]

Examples

Get-RdpSessionHistory

Retrieves all RDP session events from the local computer since January 1, 1970.

Get-RdpSessionHistory -ComputerName 'SRV01', 'SRV02' -StartTime (Get-Date).AddDays(-7)

Retrieves RDP session history from SRV01 and SRV02 for the last 7 days.

$cred = Get-Credential -UserName 'DOMAIN\admin'
'WEB01', 'APP01' | Get-RdpSessionHistory -Credential $cred

Pipeline example: queries multiple servers using alternate credentials.

Get-ADComputer -Filter "OperatingSystem -like '*Server*'" | Get-RdpSessionHistory -StartTime (Get-Date).AddHours(-24)

Retrieves last 24 hours of RDP session events from all domain servers.

Get-RdpSessionHistory -StartTime (Get-Date).AddDays(-30) | Where-Object { $_.Action -eq 'Logon' } | Group-Object -Property User

Retrieves last 30 days of RDP logon events and groups them by user.

Output: PSWinOps.RdpSessionHistory

RDP logon/logoff event history from the event log.

---

Get-RdpSessionLock

Retrieves RDP session lock and unlock event history from Windows Event Log.

Queries the Microsoft-Windows-TerminalServices-LocalSessionManager/Operational and Security event logs on one or more computers to retrieve session lock (workstation lock) and unlock events for RDP sessions. Returns structured objects with user, timestamp, and lock/unlock action details.

The function filters events by ID:

• Event 4800 (Security): Workstation was locked
• Event 4801 (Security): Workstation was unlocked

Syntax

Get-RdpSessionLock [-ComputerName <string[]>] [-StartTime <datetime>] [-Credential <System.Management.Automation.PSCredential>]

Examples

Get-RdpSessionLock
Retrieves all RDP session lock/unlock events from the local computer for the last 7 days.

Get-RdpSessionLock -ComputerName 'SRV01' -StartTime (Get-Date).AddDays(-30)
Retrieves 30 days of lock/unlock history from SRV01.

$cred = Get-Credential -UserName 'DOMAIN\admin'
'WEB01', 'APP01' | Get-RdpSessionLock -Credential $cred | Where-Object { $_.Action -eq 'Locked' }

Pipeline example: retrieves only lock events (not unlocks) from multiple servers using alternate credentials.

Get-ADComputer -Filter "OperatingSystem -like '*Server*'" | Get-RdpSessionLock -StartTime (Get-Date).AddHours(-24) | Group-Object -Property UserName
Retrieves last 24 hours of lock events from all domain servers and groups by user.

Output: PSWinOps.RdpSessionLock

Session lock and unlock events with timestamps.

---

Remove-RdpSession

Logs off (removes) an RDP session on local or remote computers.

Forces a logoff of specified RDP sessions by session ID on one or more computers using logoff.exe. This terminates the session completely and closes all applications. Unsaved work will be lost. Use Disconnect-RdpSession for a graceful disconnect without logoff.

Local machines are targeted directly via logoff.exe with no WinRM dependency. Remote machines are targeted via Invoke-Command (WinRM), which executes logoff.exe in the remote session. When -Credential is provided, it is forwarded to Invoke-Command for authentication.

Supports ShouldProcess for -WhatIf and -Confirm operations.

Syntax

Remove-RdpSession [-ComputerName <string>] -SessionID <int[]> [-Credential <System.Management.Automation.PSCredential>] [-Force]

Examples

Remove-RdpSession -SessionID 2
Logs off session ID 2 on the local computer after confirmation.

Get-RdpSession -ComputerName 'SRV01' | Where-Object { $_.IdleTime -gt (New-TimeSpan -Days 1) } | Remove-RdpSession -Force
Forcefully removes all sessions idle for more than 1 day on SRV01 without confirmation.

Remove-RdpSession -ComputerName 'WEB01' -SessionID 3 -WhatIf
Shows what would happen if session 3 were removed from WEB01.

$cred = Get-Credential -UserName 'DOMAIN\admin'
'APP01' | Get-RdpSession | Where-Object { $_.UserName -eq 'DOMAIN\olduser' } | Remove-RdpSession -Credential $cred

Removes all sessions for a specific user on APP01 using alternate credentials.

Output: PSWinOps.RdpSessionAction

Logoff action result with session details and status.

---