Public/Get-GuacConnection.ps1
|
function Get-GuacConnection { <# .SYNOPSIS Gets Guacamole connections from the UserContext. .DESCRIPTION Retrieves connections from the per-data-source UserContext: - without -Id, the full collection (DirectoryResource.getObjects), with each entry wrapped so it carries an Identifier property; - with -Id, a single connection by identifier (DirectoryObjectResource.getObject), including its parameters. Each returned object is a [PSCustomObject] mirroring the APIConnection fields (name, protocol, parentIdentifier, parameters, attributes, activeConnections, lastActive) plus the Identifier property, so the results can be piped to Update-GuacConnection and Remove-GuacConnection. By default, -ResolveParentGroupName is $true and the cmdlet resolves each parentIdentifier to a human-readable connection group name, adding a ParentGroupName property. Use -ResolveParentGroupName:$false to skip resolution for raw API data. The connection parameters (host, port, credentials, guac-* options) are returned as the "parameters" property; retrieving them requires UPDATE permission on the connection (or ADMINISTER), which the server enforces in ConnectionResource.getConnectionParameters. Filter parameters (-Name, -Protocol) perform client-side filtering: the full collection is fetched and then filtered locally. This is acceptable for typical deployment sizes. -Id takes precedence over filter parameters; if both are specified, -Id wins and filters are ignored with a warning. Reference (Apache Guacamole 1.6.0): - guacamole/src/main/java/org/apache/guacamole/rest/session/UserContextResource.java (@Path("connections")) - guacamole/src/main/java/org/apache/guacamole/rest/connection/ConnectionDirectoryResource.java - guacamole/src/main/java/org/apache/guacamole/rest/connection/ConnectionResource.java - guacamole/src/main/java/org/apache/guacamole/rest/connection/APIConnection.java - guacamole/src/main/java/org/apache/guacamole/rest/directory/DirectoryResource.java (getObjects) / DirectoryObjectResource.java (getObject) .EXAMPLE Get-GuacConnection .EXAMPLE Get-GuacConnection -Session $session -Id '8b1f2c3d-...' .EXAMPLE Get-GuacConnection -Name "prod-*" .EXAMPLE Get-GuacConnection -Protocol ssh .EXAMPLE Get-GuacConnection -Name "*web*" -Protocol ssh .EXAMPLE Get-GuacConnection | Select-Object Name, ParentGroupName, Protocol .EXAMPLE Get-GuacConnection -ResolveParentGroupName:$false #> [CmdletBinding()] [OutputType([PSCustomObject])] param ( [Parameter(Mandatory = $false)] [AllowNull()] [N2C_GuacAdmin_GuacSession] $Session, [Parameter(Mandatory = $false)] [AllowEmptyString()] [string] $Server = [string]::Empty, [Parameter(Mandatory = $false)] [AllowEmptyString()] [string] $DataSource = [string]::Empty, [Parameter(Mandatory = $false, Position = 0)] [AllowEmptyString()] [string] $Id = [string]::Empty, [Parameter(Mandatory = $false)] [AllowEmptyString()] [string] $Name = [string]::Empty, [Parameter(Mandatory = $false)] [AllowEmptyString()] [string] $Protocol = [string]::Empty, [Parameter(Mandatory = $false)] [bool] $ResolveParentGroupName = $true ) # Handle -DataSource All by iterating over all available data sources if ($DataSource -ieq 'All') { $allCtx = Resolve-GuacSessionContext -Session $Session -Server $Server -DataSource $DataSource -CmdletName 'Get-GuacConnection' foreach ($ds in $allCtx.DataSources) { $singleCtx = [ordered]@{ Session = $allCtx.Session Server = $allCtx.Server Token = $allCtx.Token DataSource = $ds } try { if (-not [string]::IsNullOrWhiteSpace($Id)) { $conn = Invoke-GuacDirectory -Context $singleCtx -Collection 'connections' -Action 'Get' -Id $Id if ($conn) { Write-Output $conn } } else { $connections = @(Invoke-GuacDirectory -Context $singleCtx -Collection 'connections' -Action 'List') if (-not [string]::IsNullOrWhiteSpace($Name)) { $connections = @($connections | Where-Object { $_.Name -like $Name }) } if (-not [string]::IsNullOrWhiteSpace($Protocol)) { $connections = @($connections | Where-Object { $_.Protocol -eq $Protocol }) } if ($ResolveParentGroupName -and $connections.Count -gt 0) { $groupIds = @($connections | ForEach-Object { if ($_.ParentIdentifier -and $_.ParentIdentifier -ne 'ROOT') { $_.ParentIdentifier } }) | Select-Object -Unique $groupMap = @{} foreach ($groupId in $groupIds) { try { $group = Invoke-GuacDirectory -Context $singleCtx -Collection 'connectionGroups' -Action 'Get' -Id $groupId $groupMap[$groupId] = $group.Name } catch { $groupMap[$groupId] = '(unknown)' } } foreach ($conn in $connections) { if ($conn.ParentIdentifier) { if ($conn.ParentIdentifier -eq 'ROOT') { $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue 'ROOT' } else { $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue $groupMap[$conn.ParentIdentifier] } } } } foreach ($conn in $connections) { Write-Output $conn } } } catch { Write-Warning ('Get-GuacConnection: error querying data source "{0}": {1}' -f ($ds, $_.Exception.Message)) } } return } $ctx = Resolve-GuacSessionContext -Session $Session -Server $Server -DataSource $DataSource -CmdletName 'Get-GuacConnection' if (-not [string]::IsNullOrWhiteSpace($Id)) { if (-not [string]::IsNullOrWhiteSpace($Name) -or -not [string]::IsNullOrWhiteSpace($Protocol)) { Write-Warning 'Both -Id and filter parameters (-Name/-Protocol) were specified. -Id takes precedence; filters are ignored.' } $conn = Invoke-GuacDirectory -Context $ctx -Collection 'connections' -Action 'Get' -Id $Id if ($ResolveParentGroupName -and -not [string]::IsNullOrWhiteSpace($conn.ParentIdentifier)) { if ($conn.ParentIdentifier -eq 'ROOT') { $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue 'ROOT' } else { try { $group = Invoke-GuacDirectory -Context $ctx -Collection 'connectionGroups' -Action 'Get' -Id $conn.ParentIdentifier $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue $group.Name } catch { Write-Verbose ('Get-GuacConnection: could not resolve parent group name for {0}' -f $conn.ParentIdentifier) $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue '(unknown)' } } } return $conn } $connections = @(Invoke-GuacDirectory -Context $ctx -Collection 'connections' -Action 'List') # Client-side filtering if (-not [string]::IsNullOrWhiteSpace($Name)) { $connections = @($connections | Where-Object { $_.Name -like $Name }) } if (-not [string]::IsNullOrWhiteSpace($Protocol)) { $connections = @($connections | Where-Object { $_.Protocol -eq $Protocol }) } if ($ResolveParentGroupName -and $connections.Count -gt 0) { $groupIds = @($connections | ForEach-Object { if ($_.ParentIdentifier -and $_.ParentIdentifier -ne 'ROOT') { $_.ParentIdentifier } }) | Select-Object -Unique $groupMap = @{} foreach ($groupId in $groupIds) { try { $group = Invoke-GuacDirectory -Context $ctx -Collection 'connectionGroups' -Action 'Get' -Id $groupId $groupMap[$groupId] = $group.Name } catch { Write-Verbose ('Get-GuacConnection: could not resolve parent group name for {0}' -f $groupId) $groupMap[$groupId] = '(unknown)' } } foreach ($conn in $connections) { if ($conn.ParentIdentifier) { if ($conn.ParentIdentifier -eq 'ROOT') { $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue 'ROOT' } else { $conn | Add-Member -NotePropertyName ParentGroupName -NotePropertyValue $groupMap[$conn.ParentIdentifier] } } } } return $connections } |