guacalib 0.8

Guacamole management library and CLI

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 management 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

Installation from PyPI

Just install it with pip:

pip install guacalib

Installation from repository

1. Clone the repository:

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

2. 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

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 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_group('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')

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()

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 \
    --type vnc \
    --group developers,managers,qa  # Add to multiple groups

# Note: Will fail if user already exists

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

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

guacaman usergroup del --name developers

Modify a user group

Add or remove users from a group:

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

# Remove user from group
guacaman usergroup modify --name developers --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 \
    --group developers,qa  # Comma-separated list of groups

# RDP and SSH connections (coming soon)
# guacaman conn new --type rdp ...
# guacaman conn new --type ssh ...

List all connections

guacaman conn list

Modify a connection

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

# Set parent connection group
guacaman conn modify --name dev-server \
    --parent "production/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

Delete a connection

guacaman conn del --name dev-server

Version Information

Check the installed version:

guacaman version

Check existence

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

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

# Check user group
guacaman usergroup exists --name developers

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

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

Example output:

groups:
  group1:
    users:
      - user1
    connections:
      - conn1
users:
  user1:
    groups:
      - group1
vnc-connections:
  conn1:
    hostname: 192.168.1.100
    port: 5901
    groups:
      - group1

Output Format

All list commands (user list, usergroup list, conn list, conngroup list, dump) output data in proper, parseable YAML format. This makes it easy to process the output with tools like yq or integrate with other systems.

Example:

# Parse with yq
guacaman user list | yq '.users[].groups'

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

Error Handling

The tool includes comprehensive error handling for:

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

All errors are reported with clear messages to help diagnose issues.

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

• Must be run on a machine with MySQL client access to the Guacamole database

TODO

Current limitations and planned improvements:

• Separate connection management from user creation ✓

  • Implemented in conn command:

    # Create VNC connection
    guacaman conn new --type vnc --name dev-server --hostname 192.168.1.100 --port 5901 --password somepass
    
    # List connections
    guacaman conn list
    
    # Delete connection
    guacaman conn del --name dev-server
    

• Support for other connection types

  • RDP (Remote Desktop Protocol)
  • SSH

• User permissions management

  • More granular permissions control
  • Permission templates

• Connection parameters management

  • Custom parameters for different connection types
  • Connection groups

• Implement dumping RDP connections

  • Add RDP connection support to dump command
  • Include RDP-specific parameters in output

PRs implementing any of these features are welcome!

Version

This is version 0.8

Contributing

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

License

Copyright Roman V. Isaev [e-mail] 2024, though 95% of the code is written with Aider/DeepSeek-V3/Sonnet-3.5/etc

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

Support

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