upperm / guacamole-powershell

PowerShell functions useful to manage Apache Guacamole

PSGuacamole

This PowerShell module provides a series of cmdlets for interacting with the Apache Guacamole API, performed by wrapping Invoke-RestMethod for the API calls.

Table of Contents

• Getting Started
  • Requirements
  • Installation
• Examples
  • Authentification
  • User Management
  • Connections Management
• Functions
  • APIConnection
  • ConnectionGroups
  • Connections
  • History
  • Languages
  • Patch
  • Permissions
  • Schemas
  • SharingProfiles
  • Tunnels
  • UserGroups
  • Users
• Author

Getting Started

Requirements

Requires PowerShell 3.0 or above as this is when Invoke-RestMethod was introduced.

Installation

Download the latest release and extract the folder to your module location ($env:PSModulePath).

Load the module

Import-Module -Name PSGuacamole

Once you've done this, all the cmdlets will be at your disposal.

Examples

Authentification

Get new token

New-GuacToken -Username "admin" -Password "MyPassword" -Server "http://srv-guacamole:8080/guacamole"

User Management

Create a new user

$Parameters = @{
    "username"= "test"
    "password"= "pass"
    "attributes"= @{
      "disabled"= ""
      "expired"= ""
      "access-window-start"= ""
      "access-window-end"= ""
      "valid-from"= ""
      "valid-until"= ""
      "timezone"= ""
      "guac-full-name"= ""
      "guac-organization"= ""
      "guac-organizational-role"= ""
    }
}

New-GuacUser -DataSource mysql -Parameters $Parameters

Retrieve user

Get-GuacUser -Username "john.doe" -DataSource "mysql"

Retrieve user connection history

Get-GuacUser -Username "john.doe" -DataSource "mysql" -Details history

Remove User

Remove-GuacUser -Username "john.doe" -DataSource "mysql"

Connections Management

Retrieving all connections

Get-GuacConnections -DataSource "mysql"

Retrieving a connection

Get-GuacConnection -DataSource mysql -ConnectionId 41 -Details $False -History $False

Create RDP connection

$RDPParameters = @{
        "parentIdentifier"= "ROOT"
        "name"= "New RDP Connection"
        "protocol"= "rdp"
        "parameters"= @{
          "port"= ""
          "read-only"= ""
          "swap-red-blue"= ""
          "cursor"= ""
          "color-depth"= ""
          "clipboard-encoding"= ""
          "disable-copy"= ""
          "disable-paste"= ""
          "dest-port"= ""
          "recording-exclude-output"= ""
          "recording-exclude-mouse"= ""
          "recording-include-keys"= ""
          "create-recording-path"= ""
          "enable-sftp"= ""
          "sftp-port"= ""
          "sftp-server-alive-interval"= ""
          "enable-audio"= ""
          "security"= ""
          "disable-auth"= ""
          "ignore-cert"= ""
          "gateway-port"= ""
          "server-layout"= ""
          "timezone"= ""
          "console"= ""
          "width"= ""
          "height"= ""
          "dpi"= ""
          "resize-method"= ""
          "console-audio"= ""
          "disable-audio"= ""
          "enable-audio-input"= ""
          "enable-printing"= ""
          "enable-drive"= ""
          "create-drive-path"= ""
          "enable-wallpaper"= ""
          "enable-theming"= ""
          "enable-font-smoothing"= ""
          "enable-full-window-drag"= ""
          "enable-desktop-composition"= ""
          "enable-menu-animations"= ""
          "disable-bitmap-caching"= ""
          "disable-offscreen-caching"= ""
          "disable-glyph-caching"= ""
          "preconnection-id"= ""
          "hostname"= ""
          "username"= ""
          "password"= ""
          "domain"= ""
          "gateway-hostname"= ""
          "gateway-username"= ""
          "gateway-password"= ""
          "gateway-domain"= ""
          "initial-program"= ""
          "client-name"= ""
          "printer-name"= ""
          "drive-name"= ""
          "drive-path"= ""
          "static-channels"= ""
          "remote-app"= ""
          "remote-app-dir"= ""
          "remote-app-args"= ""
          "preconnection-blob"= ""
          "load-balance-info"= ""
          "recording-path"= ""
          "recording-name"= ""
          "sftp-hostname"= ""
          "sftp-host-key"= ""
          "sftp-username"= ""
          "sftp-password"= ""
          "sftp-private-key"= ""
          "sftp-passphrase"= ""
          "sftp-root-directory"= ""
          "sftp-directory"= ""
        }
        "attributes"= @{
          "max-connections"= ""
          "max-connections-per-user"= ""
          "weight"= ""
          "failover-only"= ""
          "guacd-port"= ""
          "guacd-encryption"= ""
          "guacd-hostname"= ""
        }
    }
    New-GuacConnection -DataSource mysql -Parameters $RDPParameters

Remove a connection

Remove-GuacConnection -DataSource mysql -ConnectionId 74

Retrieving all connections groups

Get-GuacConnectionsGroups -DataSource mysql

Retrieving all active connections

Get-GuacActiveConnections -DataSource mysql

Functions

ConnectionGroups

• Get-GuacConnectionsGroup
• Get-GuacConnectionsGroupDetails
• Get-GuacConnectionsGroups
• Get-GuacConnectionsGroupsConnections
• New-GuacConnectionGroup
• Remove-GuacConnectionGroup
• Update-GuacConnectionGroup

Connections

• Get-GuacActiveConnections
• Get-GuacConnection
• Get-GuacConnections
• New-GuacConnection
• Remove-GuacConnection
• Stop-GuacConnection
• Update-GuacConnection

History

• Get-GuacConnectionsHistory
• Get-GuacUsersHistory

Languages

• Get-GuacLanguages

Patch

• Get-GuacPatches

Permissions

• Add-GuacConnectionGroupMember
• Add-GuacSystemPermission
• Remove-GuacConnectionGroupMember
• Remove-GuacSystemPermission

Schemas

• Get-GuacSchemaConnection
• Get-GuacSchemaConnectionGroup
• Get-GuacSchemaProtocols
• Get-GuacSchemaSharingProfile
• Get-GuacSchemaUser

SharingProfiles

• Get-GuacSharingProfile
• Get-GuacSharingProfiles
• New-GuacSharingProfile
• Remove-GuacSharingProfile

Token

• New-GuacToken
• Remove-GuacToken

Tunnels

• Get-GuacTunnel
• Get-GuacTunnels

UserGroups

• Add-GuacUserGroupConnection
• Add-GuacUserGroupMember
• Add-GuacUserGroupPermission
• Get-GuacUserGroup
• Get-GuacUserGroups
• New-GuacUserGroup
• Remove-GuacUserGroup
• Remove-GuacUserGroupConnection
• Remove-GuacUserGroupPermission
• Update-GuacUserGroup
• Update-GuacUserGroupParent

Users

• Add-GuacUserConnection
• Get-GuacUser
• Get-GuacUsers
• New-GuacUser
• Remove-GuacUser
• Remove-GuacUserConnection
• Update-GuacUser
• Update-GuacUserPassword

Author

Author: UpperM

guacamole-powershell's Issues

Cannot create new connections

With Guacamole 1.3.0 I cannot create new connections. I get error message:

VERBOSE: POST with -1-byte payload
WARNING: The remote server returned an error: (500) Internal Server Error.

Tried new tokens, but nothing seems to work.

Access PS guacamole via docker container

Is it possible to access PS guacamole via docker container with apache guacamole Installed in container.

Thanks in advance

Get-connection not showing all information from GUI profile

Hi, I'm fairly new to Guacamole, but got everything up-and-running and created 2 users and 2 connections, 1 for each user. From the Guac admin console, I can see the connection linked to a user, but not when I'm running get-user or get-connection from PShell.

Also, when running get-connection, it is not showing all settings I defined from the GUI (ignore cert, security,...); any idea how to get that information?

Get-GuacUser doesn't work because of an extra slash.

It looks like you've got an extra slash in line 34 of Get-GuacUser.ps1, which is causing malformed URLs to be used when calling the API resulting in HTTP 500 errors.

You should change this:

    begin
    {
        $Uri = "$Server/api/session/data/$($DataSource)/users/$($Username)/"

        if ($Details)
        {
            $Uri = "$Uri/$Details"
        }

to this (notice the first $Uri = line and the removal of the last slash on the right):

    begin
    {
        $Uri = "$Server/api/session/data/$($DataSource)/users/$($Username)"

        if ($Details)
        {
            $Uri = "$Uri/$Details"
        }

Also, huge thank you for sharing your awesome powershell module with the world.

adding permissions to user

It's posible to add the permission to a guacauser, "chance own password" ?
i can't find what's the name of this permission.

[Bug and solution] Error 500 using Update-GuacUserPassword

The Update-GuacUserPassword is using the "PATCH" method, and it should be using "PUT".

I manually changed that on my server and its working.
Since I have no idea how to make a pull request, I jut opened this issue.

Cheers!

Remove OldPassword parameter from Update Update-GuacUserPassword

It's dont needed to reset password

Configuration wiped when enabling wake on lan

When enabling wake on lan with Set-GuacComputerWakeOnLan, the configuariont is wiped

Possible Error in Add-GuacConnectionGroupMember

I don't believe this URI for this API call is written correctly... Or maybe I'm not looking at the right one for Assigning Connection Group to User Group. It shouldn't require a username as an argument.

Assign LDAP user to a connection or connection group

i knew this scripts are just made for mysql users in guacamole.
we have connected the ldap for authentication to guacamole to have same users and passwords for access.

with your cmdlets we could now provide automatically a new connection to a RDP Host (and delete it too). THX

now i still missing how we can add a ldap user to a connection or user-group stored in mysql (generated over your cmdlets)

Adding users in a Foreach Loop -- HTTP 500 error

The commands work independently...if I use the command "New-GuacUser -DataSource mysql -Parameters $GuacParameters" to create a single user, it works fine. I start getting the error when I put the command into a foreach loop and pull in names from a text file.

Other functions, like "Add-GuacUserConnection" in a foreach loop work just fine.

$password = "secretpassword"
$userlist=(get-content userlist.txt)
foreach ($user in $userlist) {
$GuacParameters = @{
"username"= $user
"password"= $password
"attributes"= @{
"disabled"= ""
"expired"= ""
"access-window-start"= ""
"access-window-end"= ""
"valid-from"= ""
"valid-until"= ""
"timezone"= ""
"guac-full-name"= ""
"guac-organization"= ""
"guac-organizational-role"= ""
}
}
write-host ". . . . .Adding $user to Guacamole Server"
New-GuacUser -DataSource mysql -Parameters $GuacParameters
}

add Remove-GuacUserGroupMember

Please add function for remove user from GuacUserGroup

reset user totp

plans to implement reset totp's users ?

Feature Request - Request password in a secure way

When you get a token and don't supply a password in the invocation script, it prompts you for a password. At this time, that password is displayed in the powershell window in plain text. In New-GuacToken.ps1, you should consider making password a non-required parameter, and instead doing an if-check on it as a param. If it's not passed, request it as a secure string with
Read-Host "Enter Password" -AsSecureString
or something like that.

Enable checkbox at Usergroup for ConnectionGroup below Root

Add-GuacUserGroupConnectionGroup.txt