Guacamole Management Library and CLI Utility

A comprehensive Python library and command-line tool for managing Apache Guacamole users, groups, connections, and connection groups. Provides direct MySQL database access with secure operations and YAML output.

Features

CLI Utility

User management (create, delete, modify, list)
User group management (create, delete, modify membership)
Connection management (create, delete, modify parameters)
Connection group management (create, delete, modify hierarchy)
Comprehensive listing commands with YAML output
Data dump functionality
Version information
Secure database operations with parameterized queries
Detailed error handling and validation

Python Library

Full programmatic access to all management features
Context manager for automatic connection handling
Type-safe parameter handling
Comprehensive error reporting
Advanced permission management with atomic operations
Entity resolution with both name and ID support
Connection group cycle detection
Debug utilities for troubleshooting
Transaction-safe operations

Installation from PyPI

Just install it with pip:

pip install guacalib

Installation from repository

Clone the repository:

git clone https://github.com/burbilog/guacalib.git
cd guacalib

Install the library:

pip install .

Setting up configuration file

Create a database configuration file in $HOME called .guacaman.ini for guacaman command line utility:

[mysql]
host = localhost
user = guacamole_user
password = your_password
database = guacamole_db

Ensure permissions are strict:

chmod 0600 $HOME/.guacaman.ini

Python Library Usage

The guacalib library provides programmatic access to all Guacamole management features. Here are some examples:

Basic Setup

from guacalib import GuacamoleDB

# Initialize with config file
guacdb = GuacamoleDB('~/.guacaman.ini')

# Use context manager for automatic cleanup
with GuacamoleDB('~/.guacaman.ini') as guacdb:
    # Your code here

Logging Configuration

When using guacalib as a library, you can configure logging to capture debug output. The library uses Python's standard logging module with logger name "guacalib".

Simple approach - enable debug mode:

# Debug mode automatically configures a basic logger
with GuacamoleDB('~/.guacaman.ini', debug=True) as guacdb:
    guacdb.create_user('test', 'password')
    # Debug output will be printed to stderr

Advanced approach - custom logging configuration:

import logging
from guacalib import GuacamoleDB

# Configure the guacalib logger yourself
logger = logging.getLogger('guacalib')
logger.setLevel(logging.DEBUG)

# Add custom handler (e.g., to file)
handler = logging.FileHandler('/var/log/guacalib.log')
handler.setFormatter(logging.Formatter(
    '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
))
logger.addHandler(handler)

# Now use the library
with GuacamoleDB('~/.guacaman.ini') as guacdb:
    # All debug messages go to your log file
    guacdb.create_user('test', 'password')

Integration with existing logging:

import logging

# If your app already has logging configured
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Enable guacalib debug logging when needed
guacalib_logger = logging.getLogger('guacalib')
guacalib_logger.setLevel(logging.DEBUG)

Managing Users

# Create user
guacdb.create_user('john.doe', 'secretpass')

# Check if user exists
if guacdb.user_exists('john.doe'):
    print("User exists")

# Delete user
guacdb.delete_existing_user('john.doe')

Managing User Groups

# Create user group
guacdb.create_usergroup('developers')

# Check if user group exists
if guacdb.usergroup_exists('developers'):
    print("User group exists")

# Add user to a user group
guacdb.add_user_to_usergroup('john.doe', 'developers')

# Delete user group
guacdb.delete_existing_usergroup('developers')

Managing Connections

# Create VNC connection
conn_id = guacdb.create_connection(
    'vnc',
    'dev-server',
    '192.168.1.100',
    5901,
    'vncpass'
)

# Grant connection to group
guacdb.grant_connection_permission(
    'developers',
    'USER_GROUP',
    conn_id
)

# Check if connection exists
if guacdb.connection_exists('dev-server'):
    print("Connection exists")

# Delete connection
guacdb.delete_existing_connection('dev-server')

Managing Connection Groups

Connection groups allow organizing connections into hierarchical groups. Here are the key methods:

# Create a top-level connection group
guacdb.create_connection_group('production')

# Create a nested connection group
guacdb.create_connection_group('vnc_servers', parent_group_name='production')

# List all connection groups with their hierarchy
groups = guacdb.list_connection_groups()
for group_name, data in groups.items():
    print(f"{group_name}:")
    print(f"  Parent: {data['parent']}")
    print(f"  Connections: {data['connections']}")

# Check if a connection group exists
if guacdb.connection_group_exists('production'):
    print("Group exists")

# Modify a connection group's parent
guacdb.modify_connection_group_parent('vnc_servers', 'infrastructure')

# Remove a connection group's parent
guacdb.modify_connection_group_parent('vnc_servers', '')

# Delete a connection group
guacdb.delete_connection_group('vnc_servers')

Advanced Library Features

The GuacamoleDB class provides additional methods for complex operations:

Permission Management

# Connection permissions
guacdb.grant_connection_permission_to_user('john.doe', 'dev-server')
guacdb.revoke_connection_permission_from_user('john.doe', 'dev-server')

# Connection group permissions (advanced)
guacdb.grant_connection_group_permission_to_user('john.doe', 'production')
guacdb.grant_connection_group_permission_to_user_by_id('john.doe', 42)
guacdb.revoke_connection_group_permission_from_user('john.doe', 'production')
guacdb.revoke_connection_group_permission_from_user_by_id('john.doe', 42)

Entity Resolution and Validation

# Resolve entities by name or ID with validation
conn_id = guacdb.resolve_connection_id(connection_name='dev-server')
conn_id = guacdb.resolve_connection_id(connection_id=42)

group_id = guacdb.resolve_conngroup_id(group_name='production')
group_id = guacdb.resolve_conngroup_id(group_id=15)

usergroup_id = guacdb.resolve_usergroup_id(group_name='developers')
usergroup_id = guacdb.resolve_usergroup_id(group_id=8)

Advanced Query Methods

# Get specific entities by ID
connection = guacdb.get_connection_by_id(42)
conngroup = guacdb.get_connection_group_by_id(15)

# Get names by ID
name = guacdb.get_connection_name_by_id(42)
name = guacdb.get_connection_group_name_by_id(15)
name = guacdb.get_usergroup_name_by_id(8)

# Check existence by ID
exists = guacdb.usergroup_exists_by_id(8)
exists = guacdb.connection_group_exists('production')
exists = guacdb.connection_exists('dev-server')

Debug and Utility Methods

# Debug permission issues
guacdb.debug_connection_permissions('dev-server')

# Validate positive IDs
guacdb.validate_positive_id(42, "connection")

Listing Data

# List users with their groups
users = guacdb.list_users_with_usergroups()

# List groups with their users and connections
groups = guacdb.list_usergroups_with_users_and_connections()

# List all connections
connections = guacdb.list_connections_with_conngroups_and_parents()

# List connection groups with hierarchy
groups = guacdb.list_connection_groups()

# List groups with users
groups_users = guacdb.list_groups_with_users()

Command line usage

Managing Users

Create a new user

# Basic user creation
guacaman user new \
    --name john.doe \
    --password secretpass

# Create with group memberships (comma-separated)
guacaman user new \
    --name john.doe \
    --password secretpass \
    --usergroup developers,managers,qa  # Add to multiple groups

# Note: Will fail if user already exists

Modify a user

Modifies user's settings or changes password. Allowed parameters are:

Parameter	Type	Default	Description
access_window_end	time	NULL	End of allowed access time window (HH:MM:SS)
access_window_start	time	NULL	Start of allowed access time window (HH:MM:SS)
disabled	tinyint	0	Whether the user is disabled (0=enabled, 1=disabled)
email_address	string	NULL	User's email address
expired	tinyint	0	Whether the user account is expired (0=active, 1=expired)
full_name	string	NULL	User's full name
organization	string	NULL	User's organization
organizational_role	string	NULL	User's role within the organization
timezone	string	NULL	User's timezone (e.g., "America/New_York")
valid_from	date	NULL	Date when account becomes valid (YYYY-MM-DD)
valid_until	date	NULL	Date when account expires (YYYY-MM-DD)

guacaman user modify --name john.doe --set disabled=1
guacaman user modify --name john.doe --password newsecret

List all users

Shows all users and their group memberships:

guacaman user list

Delete a user

Removes a user:

guacaman user del --name john.doe

Check if a user exists

Check user existence (returns 0 if exists, 1 if not):

guacaman user exists --name john.doe

Managing User Groups

Create a new user group

guacaman usergroup new --name developers

List all user groups

Shows all groups and their members:

guacaman usergroup list

Delete a user group

Supports both name and ID-based deletion:

# Delete by name
guacaman usergroup del --name developers

# Delete by ID
guacaman usergroup del --id 42

Check if a user group exists

Supports both name and ID-based existence checking:

# Check by name
guacaman usergroup exists --name developers

# Check by ID
guacaman usergroup exists --id 42

Modify a user group

Add or remove users from a group with comprehensive ID support:

# Add user to group by name
guacaman usergroup modify --name developers --adduser john.doe

# Remove user from group by name
guacaman usergroup modify --name developers --rmuser john.doe

# Use ID-based group selectors
guacaman usergroup modify --id 42 --adduser john.doe
guacaman usergroup modify --id 42 --rmuser john.doe

Managing Connections

Create a new connection

# Create a VNC connection
guacaman conn new \
    --type vnc \
    --name dev-server \
    --hostname 192.168.1.100 \
    --port 5901 \
    --password vncpass \
    --usergroup developers,qa  # Comma-separated list of groups

# Create other types of connections
guacaman conn new --type rdp ...
guacaman conn new --type ssh ...  # Basic support available

List all connections

guacaman conn list

# List specific connection by ID
guacaman conn list --id 42

Modify a connection

# Change basic connection parameters
guacaman conn modify --name dev-server \
    --set hostname=192.168.1.200 \
    --set port=5902 \
    --set max_connections=5 \
    --set max_connections_per_user=2

# Change protocol-specific parameters
guacaman conn modify --name dev-server \
    --set color-depth=32 \
    --set enable-sftp=true \
    --set enable-audio=true

# Grant permission to user
guacaman conn modify --name dev-server --permit john.doe

# Revoke permission from user
guacaman conn modify --name dev-server --deny john.doe

# Set parent connection group
guacaman conn modify --name dev-server --parent "vnc_servers"

# Remove parent connection group
guacaman conn modify --name dev-server --parent ""

# Invalid parameter handling example (will fail)
guacaman conn modify --name dev-server --set invalid_param=value

Available Connection Parameters:

The --set option supports 50+ parameters organized by category:

Connection Table Parameters:

protocol - Connection protocol (vnc, rdp, ssh)
max_connections - Maximum concurrent connections
max_connections_per_user - Max connections per user
proxy_hostname - Guacamole proxy hostname
proxy_port - Guacamole proxy port
connection_weight - Load balancing weight
failover_only - Use for failover only

Protocol-Specific Parameters:

VNC: hostname, port, password, color-depth, clipboard-encoding
RDP: hostname, port, username, password, domain, color-depth
SSH: hostname, port, username, password, private-key, passphrase

Advanced Features:

SFTP: enable-sftp, sftp-hostname, sftp-port, sftp-username, sftp-password
Audio: enable-audio, audio-servername
Session Recording: recording-path, recording-name
Network: autoretry, server-alive-interval
Security: host-key, disable-copy, disable-paste

Check if a connection exists

Supports both name and ID-based existence checking:

# Check by name
guacaman conn exists --name dev-server

# Check by ID
guacaman conn exists --id 42

Delete a connection

Supports both name and ID-based deletion:

# Delete by name
guacaman conn del --name dev-server

# Delete by ID
guacaman conn del --id 42

Managing Connection Groups

Connection groups allow you to organize connections into hierarchical groups and manage user permissions for entire groups of connections. Features include cycle detection, atomic operations, and comprehensive permission management.

Create a new connection group

# Create a top-level group
guacaman conngroup new --name production

# Create a nested group under production
guacaman conngroup new --name vnc_servers --parent production

List all connection groups

Shows all groups and their hierarchy with database IDs:

guacaman conngroup list

# List specific connection group by ID
guacaman conngroup list --id 15

Delete a connection group

Supports both name and ID-based deletion with automatic cleanup of child references:

# Delete by name
guacaman conngroup del --name vnc_servers

# Delete by ID
guacaman conngroup del --id 42

Check if a connection group exists

Supports both name and ID-based existence checking:

# Check by name
guacaman conngroup exists --name vnc_servers

# Check by ID
guacaman conngroup exists --id 42

Modify a connection group

Advanced modification with cycle detection, atomic operations, and comprehensive ID support:

Parent Group Management:

# Move group to new parent (with cycle detection)
guacaman conngroup modify --name vnc_servers --parent "infrastructure"

# Remove parent (make top-level)
guacaman conngroup modify --name vnc_servers --parent ""

# Use ID-based selectors
guacaman conngroup modify --id 42 --parent "infrastructure"

Connection Management within Groups:

# Add connection to group by name
guacaman conngroup modify --name vnc_servers --addconn-by-name dev-server

# Add connection to group by ID
guacaman conngroup modify --name vnc_servers --addconn-by-id 42

# Remove connection from group by name
guacaman conngroup modify --name vnc_servers --rmconn-by-name dev-server

# Remove connection from group by ID
guacaman conngroup modify --name vnc_servers --rmconn-by-id 42

# Use ID-based group selectors
guacaman conngroup modify --id 15 --addconn-by-name dev-server

Advanced User Permission Management: The system supports atomic permission operations with comprehensive validation:

# Grant permission to user for connection group using name selector
guacaman conngroup modify --name vnc_servers --permit john.doe

# Grant permission to user for connection group using ID selector
guacaman conngroup modify --id 42 --permit jane.doe

# Revoke permission from user for connection group using name selector
guacaman conngroup modify --name vnc_servers --deny john.doe

# Revoke permission from user for connection group using ID selector
guacaman conngroup modify --id 42 --deny jane.doe

# Multiple users in single operation (repeat flags)
guacaman conngroup modify --name vnc_servers --permit john.doe --permit jane.doe

Combined Operations:

# Combine parent modification with permission operations
guacaman conngroup modify --name vnc_servers --parent "infrastructure" --permit john.doe

# Add connection and grant permission in one command
guacaman conngroup modify --name vnc_servers --addconn-by-name dev-server --permit jane.doe

# Complex operation with ID-based selectors
guacaman conngroup modify --id 42 --parent "infrastructure" --addconn-by-id 15 --permit john.doe

Version Information

Check the installed version:

guacaman version

Debug Mode

Enable debug output to see SQL queries and internal state:

guacaman --debug conn list
guacaman --debug user new --name test --password test

Check existence

Check if a user, group, connection, or connection group exists (returns 0 if exists, 1 if not):

# Check user
guacaman user exists --name john.doe

# Check user group (supports both name and ID)
guacaman usergroup exists --name developers
guacaman usergroup exists --id 42

# Check connection (supports both name and ID)
guacaman conn exists --name dev-server
guacaman conn exists --id 42

# Check connection group (supports both name and ID)
guacaman conngroup exists --name production
guacaman conngroup exists --id 15

These commands are silent and only return an exit code, making them suitable for scripting.

Dump all data

Dumps all groups, users and connections in YAML format:

guacaman dump

Output Format

All list commands (user list, usergroup list, conn list, conngroup list, dump) output data in YAML-like format. The output includes additional fields that may be useful for scripting and integration.

Connection List Output:

connections:
  dev-server:
    id: 42
    type: vnc
    hostname: 192.168.1.100
    port: "5901"
    parent: vnc_servers
    groups:
      - developers
    permissions:
      - john.doe

Connection Group List Output:

conngroups:
  vnc_servers:
    id: 15
    parent: production
    connections:
      - dev-server
      - test-server

User List Output:

users:
  john.doe:
    usergroups:
      - developers
      - qa

Example parsing with yq:

# Get all connection names
guacaman conn list | yq '.connections | keys[]'

# Get connections in a specific group
guacaman conngroup list | yq '.conngroups.vnc_servers.connections[]'

# Get user groups
guacaman user list | yq '.users[].usergroups[]'

Configuration File Format

The $HOME/.guacaman.ini file should contain MySQL connection details:

[mysql]
host = localhost
user = guacamole_user
password = your_password
database = guacamole_db

SSH Tunnel Configuration (Optional)

For remote MySQL access through an SSH gateway, add an [ssh_tunnel] section:

[ssh_tunnel]
enabled = true
host = ssh-gateway.example.com
port = 22
user = ssh_username
private_key = /home/user/.ssh/id_rsa
# password = ssh_password  # alternative to private_key
# private_key_passphrase = passphrase  # if key is encrypted

Note: Either password or private_key is required for SSH authentication.

Environment Variables (have priority over config file):

GUACALIB_SSH_TUNNEL_ENABLED - set to "true" to enable
GUACALIB_SSH_TUNNEL_HOST - SSH gateway hostname
GUACALIB_SSH_TUNNEL_PORT - SSH port (default: 22)
GUACALIB_SSH_TUNNEL_USER - SSH username
GUACALIB_SSH_TUNNEL_PASSWORD - SSH password (if not using key)
GUACALIB_SSH_TUNNEL_PRIVATE_KEY - path to SSH private key
GUACALIB_SSH_TUNNEL_PRIVATE_KEY_PASSPHRASE - key passphrase (if encrypted)

Error Handling

The tool provides comprehensive error handling for:

Database connection issues
Missing users or groups
Duplicate entries
Permission problems
Invalid configurations

Validation Rules:

Exactly one of --name or --id must be provided for most operations
IDs must be positive integers greater than 0
Names cannot be empty strings
Configuration files must have secure permissions (0600)
Mutual exclusion validation for conflicting options
Cycle detection for connection group parent relationships
Type validation for connection parameters (colors, booleans, integers)

Transaction Handling:

Connection group modifications use explicit transactions
Automatic rollback on errors
Proper error messages with context
Atomic permission operations to prevent partial state corruption
Comprehensive input validation before database operations

Advanced Features:

Connection group cycle detection prevents infinite hierarchies
Centralized entity resolution with consistent error messages
Debug mode for troubleshooting (--debug flag)
Parameter validation based on protocol-specific requirements

All errors are reported with clear messages to help diagnose issues. Use --debug flag to see detailed SQL queries and internal state.

Security Considerations

Database credentials are stored in a separate configuration file
Configuration file must have strict permissions (0600/-rw-------)
- Script will exit with error code 2 if permissions are too open
Passwords are properly hashed before storage
The tool handles database connections securely
All SQL queries use parameterized statements to prevent SQL injection

Limitations

Requires MySQL client access to the Guacamole database
SSH connections have basic support with limited parameter validation
Connection creation only supports basic parameters (use modify for advanced parameters)

TODO

Current limitations and planned improvements:

PRs implementing any of these features are welcome!

AI guidelines

For all AI agents: use rules in AGENTS.md

Version

This is version 0.26

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Copyright Roman V. Isaev rm@isaeff.net 2024-2026, though 95% of the code is written with the help of various LLMs and coding agents.

This software is distributed under the terms of the GNU General Public license, version 3.

Support

For bugs, questions, and discussions please use the GitHub Issues.

Name		Name	Last commit message	Last commit date
Latest commit History 381 Commits
doc		doc
guacalib		guacalib
scripts		scripts
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE.md		LICENSE.md
Makefile		Makefile
PROMPT.md		PROMPT.md
README.md		README.md
TODO.md		TODO.md
configuring-guacamole.txt		configuring-guacamole.txt
debug_permissions.py		debug_permissions.py
guacalib.ini.example		guacalib.ini.example
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Guacamole Management Library and CLI Utility

Features

CLI Utility

Python Library

Installation from PyPI

Installation from repository

Setting up configuration file

Python Library Usage

Basic Setup

Logging Configuration

Managing Users

Managing User Groups

Managing Connections

Managing Connection Groups

Advanced Library Features

Permission Management

Entity Resolution and Validation

Advanced Query Methods

Debug and Utility Methods

Listing Data

Command line usage

Managing Users

Create a new user

Modify a user

List all users

Delete a user

Check if a user exists

Managing User Groups

Create a new user group

List all user groups

Delete a user group

Check if a user group exists

Modify a user group

Managing Connections

Create a new connection

List all connections

Modify a connection

Check if a connection exists

Delete a connection

Managing Connection Groups

Create a new connection group

List all connection groups

Delete a connection group

Check if a connection group exists

Modify a connection group

Version Information

Debug Mode

Check existence

Dump all data

Output Format

Configuration File Format

SSH Tunnel Configuration (Optional)

Error Handling

Security Considerations

Limitations

TODO

AI guidelines

Version

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages