Guacamole CLI Manager

A command-line tool for managing Apache Guacamole users, groups, and VNC connections. This tool provides a simple way to manage Guacamole's MySQL database directly, allowing for easy automation and scripting of user management tasks.

Features

• Create and delete users
• Create and delete groups
• Manage user group memberships
• Automatically create VNC connections for users
• List existing users and their group memberships
• List existing groups and their members

Installation

1. Clone the repository:

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

2. Install required dependencies:

pip install -r requirements.txt

3. Create a database configuration file db_config.ini:

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

Usage

Managing Users

Create a new user

Creates a new user with an associated VNC connection:

./gcmanager.py user new \
    --username john.doe \
    --password secretpass \
    --vnc-host 192.168.1.100 \
    --vnc-port 5901 \
    --vnc-password vncpass

To create a user and add them to a group:

./gcmanager.py user new \
    --username john.doe \
    --password secretpass \
    --group developers \
    --vnc-host 192.168.1.100 \
    --vnc-port 5901 \
    --vnc-password vncpass

List all users

Shows all users and their group memberships:

./gcmanager.py user list

Delete a user

Removes a user and their associated VNC connection:

./gcmanager.py user del --username john.doe

Managing Groups

Create a new group

./gcmanager.py group new --name developers

List all groups

Shows all groups and their members:

./gcmanager.py group list

Delete a group

./gcmanager.py group del --name developers

Configuration File Format

The db_config.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
• Passwords are properly hashed before storage
• The tool handles database connections securely
• All SQL queries use parameterized statements to prevent SQL injection

Limitations

• Currently supports only VNC connections
• 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

  • Currently each user gets a single hardcoded VNC connection
  • Future conn command will allow flexible connection management:

    # Planned syntax
    gcmanager.py conn new --type vnc --name dev-server --host 192.168.1.100 --port 5901
    gcmanager.py conn grant --name dev-server --user john.doe
    gcmanager.py conn list
    gcmanager.py 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

PRs implementing any of these features are welcome!

Contributing

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

License

Copyright Roman V. Isaev [email protected] 2024

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

Support

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