Skip to main content

Maintenance Operations

Instance Sizing​

For best performance make sure that your environment supports the WebSockets protocol. Some HTTP proxies do not allow WebSockets connections. The service will then fall back to regular HTTP communication which works reasonable well but is not as efficient.

Guacamole is a Java based application. Memory consumption is therefore always a concern. If the application becomes unresponsive or if you experience 502 Bad Gateway error message, stop the instance and upgrade to a larger instance type. The recommended instance type for small teams with 15 concurrent connections is a m5.large.

Instances in the t2 family can become unresponsive if the CPU credits are exhausted. Make sure that you monitor the CPU credit balance if you choose to use this instance type. We recommend to use the t3 family if possible.

Operating System Patching​

The server can be patched manually by accessing the server via SSH. Execute sudo yum update -y to upgrade the operating system. Reboot the instance. The instance also ships with the Systems Manager Agent, allowing you to execute these operations automatically (see https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-patch.html).

We will also be publishing new AMIs after critical security vulnerabilities have been published. As a subscriber to the AMI you will be notified immediately.

Command Line Interface​

The guawsctl command line interface allows you to manage the services installed on the instance. All services are deployed as docker containers. These services are mysql (a MariaDB server), guacd (the Guacamole Server component), guac (the Guacamole web front end) and guaws (the agent that scans the AWS account).

Logs for each service can be retrieved by executing guawsctl logs -f, optionally append the service name to limit the log output to one of the services. Each service can be restarted individually by executing guawsctl restart $service (replace $service with the name of the service).

Batch Import of Users​

You can batch import users into the Guacamole database with the import-users.py script. The script expects a CSV file where the first column is the name of the user, then the password and the third column is the name of the group the user shall be assigned to. You can leave the password column empty which results in a random password being generated. You can assign a user to multiple groups by repeating the row and updating the group name.

By default, the script tries to connect to Guacamole running on localhost (i.e. on the same instance). If you want to connect to a different instance, you can specify the hostname or IP address of the Guacamole server using the --host option (e.g. --host=https://guacd.example.com). The default username is guacadmin. You can change this with the --username option.

The CSV file has the following schema (only the username is required):

username: Required<string>
password: string # a random password will be generated if not specified
access-window-start: "08:00:00" # time of day when the user will be allowed to login
access-window-end: "18:00:00" # time of day until the user will be allowed to login
disabled: "true" # set to "true" to disable the user
expired: "true" # set to "true" requires the user to reset their password prior to fully logging in
guac-email-address: "jane.doe@company.org" # email address of the user
guac-full-name: "Jane Doe" # full name of the user
guac-organization: "Some Organization" # organization of the user
guac-organizational-role: "Director" # organizational role of the user
timezone: "Europe/Amsterdam" # timezone of the user, honored by access-window attributes
valid-from: "2022-05-01" # date when the user will be allowed to login
valid-until: "2022-05-01" # date until the user will be allowed to login

The following example demonstrates how to use the script and create a simple CSV file for importing users from the command line:

curl --proto '=https' --tlsv1.2 -sSfO https://netcubed-ami.s3.us-east-1.amazonaws.com/guaws/v2.8.4/scripts/import-users.py

echo 'username,password,group,guac-full-name' > users.txt
echo 'user1@company.com,password1,group-1,Charlie Doe' >> users.txt
echo 'user2@company.com,password2,group-1,Bob Doe' >> users.txt
# Repeat a user if you want to assign them to multiple groups
echo 'user2@company.com,password2,group-2,Bob Doe' >> users.txt

# provide the password for the guacadmin user which is the instance ID for new instances
python3 import-users.py --password 'i-123412341234' < users.txt

# Output
Successfully logged in as "guacadmin".
Created user "user1@company.com".
Created user "user2@company.com".
User "user2@company.com" already exists.
Created user "user2@company.com".

Logs and Troubleshooting​

You can use several methods to troubleshoot log in or connection issues. To start with, all logs generated by the Guacamole services are accessible using the guawsctl logs command. To look at a tailing stream of logs of a all services, run guawsctl logs -f as the ec2-user. To limit the logs output to a specific service, add the service name to the command (e.g. guawsctl logs -f guacd). The following services are available:

  • nginx: HTTPS ingress controller
  • mysql: database
  • guacd: Guacamole server that establishes connections
  • guac: Guacamole web front-end and authentication layer
  • guaws: GuAWS daemon that scans the AWS environment for instances

Logs are also pushed to journald which allows access to the logs via the journalctl command. To access the logs for a given container, run journalctl -ef CONTAINER_NAME=guaws_$SERVICE_1, where $SERVICE needs to be replaced with the name of the service.

If the logs don't reveal the issue, you can increase the log level. Open the file /home/ec2-user/guaws/.env and replace the line LOG_LEVEL=info with LOG_LEVEL=debug. Then, run guawsctl up -d to restart all services affected by this change. The logs output should now contain more details. It is recommended to change the log level back to info after the issue has been resolved.

Change Docker Subnet​

Guacamole is using docker to isolate the different services on the EC2 instance. The default IP range that is used for the docker internal networking is 172.17.0.1/16 and this can cause problems where this network is also used by the VPC.

To change the default IP range, the instance must be launched with a user-data script that changes the IP range before the docker service is launched.

Please use the following user-data script to change the IP range. Feel free to adjust the bip parameter to your needs. The subnet should be of size /16.

#cloud-config

write_files:
  - path: /etc/docker/daemon.json
    content: '{"bip": "172.26.0.1/16"}'