Glyptodon Enterprise This documentation assumes that you already have access to a MySQL server or hosted MySQL database, and that Guacamole has already been installed using Glyptodon Enterprise. If you do not already a MySQL server ready, please set up MySQL before proceeding. If you do not already have Guacamole installed, please see the quickstart guide.
Glyptodon Enterprise packages Guacamole’s MySQL support within the glyptodon-guacamole-auth-jdbc-mysql package. This package must be installed before creating Guacamole’s database within MySQL, as it includes the SQL scripts necessary for doing so:
$ sudo yum install glyptodon-guacamole-auth-jdbc-mysql
If you haven’t already done so, a database specific to Guacamole needs to be created within MySQL. The database can be called anything you like; all that matters is that the database be dedicated to Guacamole, and not shared by different applications:
CREATE DATABASE guacamole_db;
Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the glyptodon-guacamole-auth-jdbc-mysql package, which are located within the /usr/share/guacamole-auth-jdbc-mysql/schema directory:
| Filename | Description |
|---|---|
001-create-schema.sql | Creates all tables and indexes which are required for the MySQL authentication extension to function. |
002-create-admin-user.sql | Creates a default administrative user, “guacadmin”, with password “guacadmin”. These credentials will need to be changed once MySQL authentication is confirmed to be working. |
The above scripts must be run in sequence, as it is the first script which actually creates the database schema. The second script, which defines a default administrative user, can only successfully run if the tables created by the first script exist. The simplest way to run both scripts in sequence is to concatenate them:
$ cat /usr/share/guacamole-auth-jdbc-mysql/schema/*.sql | mysql -u root -p guacamole_db
Alternatively, the scripts can be run individually, as long as the order is correct:
$ mysql -u root -p guacamole_db < /usr/share/guacamole-auth-jdbc-mysql/schema/001-create-schema.sql $ mysql -u root -p guacamole_db < /usr/share/guacamole-auth-jdbc-mysql/schema/002-create-admin-user.sql
To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes:
CREATE USER 'guacamole_user' IDENTIFIED BY 'some_password'; GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'; FLUSH PRIVILEGES;
Guacamole's main configuration file, /etc/guacamole/guacamole.properties, must now be modified to specify the credentials of the MySQL user and to point the MySQL database:
$ sudo vi /etc/guacamole/guacamole.properties
The guacamole.properties file provided with Glyptodon Enterprise is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked "JDBC-1" and defines the TCP connection information for the database in use. Uncomment the mysql-hostname and mysql-port properties, modifying their values to point to your MySQL server:
## ## [JDBC-1] Database TCP connection information ## ## The TCP connection details for the PostgreSQL or MySQL / MariaDB database. ## mysql-hostname: localhost mysql-port: 3306
The "JDBC-2" section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the mysql-database, mysql-username, and mysql-password properties respectively:
## ## [JDBC-2] Database name and credentials ## ## The name of the database to use, as well as the credentials to use when ## connecting to the database. THESE PROPERTIES ARE REQUIRED if one of the ## database authentication extensions will be used. ## mysql-database: guacamole_db mysql-username: guacamole_user mysql-password: some_password
Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole (and thus Tomcat) must be restarted:
$ sudo systemctl restart tomcat
To make sure everything is working as expected, you should also visit your Guacamole instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script:
| Username: | guacadmin |
|---|---|
| Password: | guacadmin |
Once you have verified that you can log in successfully, you should immediately change the password, as keeping default accounts unchanged is dangerous. While logged into Guacamole, you can access the built-in password changing interface by clicking on your username in the upper-right corner of the screen and selecting "Settings".
This documentation assumes that you already have access to a PostgreSQL server or hosted PostgreSQL database, and that Guacamole has already been installed using Glyptodon Enterprise. If you do not already a PostgreSQL server ready, please set up PostgreSQL before proceeding. If you do not already have Guacamole installed, please see the quickstart guide.
Glyptodon Enterprise packages Guacamole’s PostgreSQL support within the glyptodon-guacamole-auth-jdbc-postgresql package. This package must be installed before creating Guacamole’s database within PostgreSQL, as it includes the SQL scripts necessary for doing so:
$ sudo yum install glyptodon-guacamole-auth-jdbc-postgresql
If you haven’t already done so, a database specific to Guacamole needs to be created within PostgreSQL. The database can be called anything you like; all that matters is that the database be dedicated to Guacamole, and not shared by different applications:
CREATE DATABASE guacamole_db;
Guacamole will not automatically initialize the database with the required schema. You will need to do this yourself using the SQL scripts provided with the glyptodon-guacamole-auth-jdbc-postgresql package, which are located within the /usr/share/guacamole-auth-jdbc-postgresql/schema directory:
| Filename | Description |
|---|---|
001-create-schema.sql | Creates all tables and indexes which are required for the PostgreSQL authentication extension to function. |
002-create-admin-user.sql | Creates a default administrative user, “guacadmin”, with password “guacadmin”. These credentials will need to be changed once PostgreSQL authentication is confirmed to be working. |
The above scripts must be run in sequence, as it is the first script which actually creates the database schema. The second script, which defines a default administrative user, can only successfully run if the tables created by the first script exist. The simplest way to run both scripts in sequence is to concatenate them:
$ cat /usr/share/guacamole-auth-jdbc-postgresql/schema/*.sql | psql -d guacamole_db -f -
Alternatively, the scripts can be run individually, as long as the order is correct:
$ psql -d guacamole_db -f /usr/share/guacamole-auth-jdbc-postgresql/schema/001-create-schema.sql $ psql -d guacamole_db -f /usr/share/guacamole-auth-jdbc-postgresql/schema/002-create-admin-user.sql
To execute queries against the database, Guacamole will need its own database user with sufficient privileges. Because Guacamole does not automatically apply or update its own schema, the required privileges are minimal, dealing only with creation and maintenance of data within already-defined tables and indexes:
CREATE USER guacamole_user WITH PASSWORD 'some_password'; GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user; GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user;
Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must now be modified to specify the credentials of the PostgreSQL user and to point the PostgreSQL database:
$ sudo vi /etc/guacamole/guacamole.properties
The guacamole.properties file provided with Glyptodon Enterprise is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “JDBC-1” and defines the TCP connection information for the database in use. Uncomment the postgresql-hostname and postgresql-port properties, modifying their values to point to your PostgreSQL server:
## ## [JDBC-1] Database TCP connection information ## ## The TCP connection details for the PostgreSQL or MySQL / MariaDB database. ## #mysql-hostname: localhost #mysql-port: 3306 postgresql-hostname: localhost postgresql-port: 5432
The “JDBC-2” section, which defines the database name and associated credentials, must also be modified to specify the correct database name, username, and password. These values are given with the postgresql-database, postgresql-username, and postgresql-password properties respectively:
## ## [JDBC-2] Database name and credentials ## ## The name of the database to use, as well as the credentials to use when ## connecting to the database. THESE PROPERTIES ARE REQUIRED if one of the ## database authentication extensions will be used. ## #mysql-database: guacamole_db #mysql-username: guacamole_user #mysql-password: some_password postgresql-database: guacamole_db postgresql-username: guacamole_user postgresql-password: some_password
Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole (and thus Tomcat) must be restarted:
$ sudo systemctl restart tomcat
To make sure everything is working as expected, you should also visit your Guacamole instance with a web browser (most likely at http://HOSTNAME:8080/guacamole/, where “HOSTNAME” is the hostname or IP address of your server). If all is working correctly, you should see a login screen with a username/password prompt, and you will be able to log in using the default account created with the 002-create-admin-user.sql script:
| Username: | guacadmin |
|---|---|
| Password: | guacadmin |
Once you have verified that you can log in successfully, you should immediately change the password, as keeping default accounts unchanged is dangerous. While logged into Guacamole, you can access the built-in password changing interface by clicking on your username in the upper-right corner of the screen and selecting “Settings”.
This documentation assumes that you already have access to an LDAP directory, such as OpenLDAP or Active Directory, and that Guacamole has already been installed using Glyptodon Enterprise. If you do not already an LDAP directory ready, please set up LDAP before proceeding. If you do not already have Guacamole installed, please see the quickstart guide.
Glyptodon Enterprise packages Guacamole’s LDAP support within the glyptodon-guacamole-auth-ldap package:
$ sudo yum install glyptodon-guacamole-auth-ldap
Unlike the MySQL and PostgreSQL authentication backends, Guacamole’s LDAP support does not require a schema to be applied unless you intend to store connection data within your LDAP directory. If LDAP will be used only to authenticate Guacamole users, no schema modifications need be made, and a database should be used to store connection data.
If you do intend to store connection data within your LDAP directory, you will need to apply the provided schema modifications which create the guacConfigGroup object class. Be sure to first finish configuring Guacamole for LDAP authentication, and verify that Guacamole can successfully authenticate users against your LDAP directory.
Guacamole’s main configuration file, /etc/guacamole/guacamole.properties, must be modified to point the LDAP directory:
$ sudo vi /etc/guacamole/guacamole.properties
The guacamole.properties file provided with Glyptodon Enterprise is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “LDAP-1” and defines the TCP connection information for the LDAP directory. Uncomment the ldap-hostname property, modifying its value to point to your LDAP server:
## ## [LDAP-1] LDAP TCP connection information ## ## The TCP connection details of the LDAP server, as well as whether encryption ## should be used. ## ## Legal encryption methods are "none", for unencrypted connections, "ssl" ## for LDAP over SSL/TLS (also known as LDAPS), or "starttls" for STARTTLS. ## #ldap-hostname: localhost #ldap-port: 389 #ldap-encryption-method: none
By default, Guacamole will connect to your LDAP server without encryption. If your LDAP server uses encryption, you will need to uncomment and set the ldap-encryption-method property to “ssl” for LDAPS (LDAP over SSL/TLS) or “starttls” for STARTTLS.
The default port varies by encryption method, and will be 389 for unencrypted LDAP and STARTTLS, or 636 for LDAPS. If your LDAP server listens on a non-standard port, you will also need to uncomment and modify the ldap-port property.
To authenticate users using LDAP, Guacamole must translate usernames into their corresponding LDAP DN’s. Depending on the complexity of your LDAP directory, this can be as simple as adding a single attribute to a common base DN, or can involve an LDAP query.
The “LDAP-2” section defines the basic parameters required for either case:
## ## [LDAP-2] LDAP user / user DN description ## ## The base DN of all Guacamole users within the LDAP directory, and the ## attribute which contains each user's username. If the username attribute ## is not part of the DN, a seach DN will need to be provided, as well. ## #ldap-user-base-dn: ou=people,dc=example,dc=net #ldap-username-attribute: uid
The base DN defined by the ldap-user-base-dn property should be the common base shared by all Guacamole users within your LDAP directory, while the attribute which contains the user’s username is defined by ldap-username-attribute. The base DN is always required if LDAP is being used.
By default, Guacamole will attempt to derive the user’s DN directly by prepending the username attribute to the base DN. For example, assume a user is attempting to login with the username “someUser”. If the base DN is “ou=people,dc=example,dc=net” and the username attribute is “uid” (the default), then Guacamole will perform the following steps to authenticate the user:
For more complex cases, where the user DN is cannot be directly derived by prepending the username attribute, Guacamole can instead issue an LDAP query to determine the user DN. This requires a search DN and password, defined with the ldap-search-bind-dn and ldap-search-bind-password properties respectively, which Guacamole will bind as when performing the query:
## ## [LDAP-3] LDAP user search DN ## ## The DN and password of the user to bind as when searching for the DN of each ## user attempting to log in. If omitted, the DN of each user will be derived ## directly using the user base DN and username attribute. ## #ldap-search-bind-dn: cn=someUser,ou=people,dc=example,dc=net #ldap-search-bind-password: some_password
With the search DN and password configured, Guacamole will perform the following steps to authenticate a user:
Guacamole will generally only load new extensions and reread guacamole.properties during the startup process. To apply the configuration changes, Guacamole (and thus Tomcat) must be restarted:
$ sudo systemctl restart tomcat
Glyptodon, Inc.
995 Market St. Second Floor
San Francisco, CA 94103