Google Git
Sign in
apache / guacamole-manual / 723075802fffe509f51abe90d85bad7061fba88b / . / src / chapters / jdbc-auth.xml
blob: da97bbac89f90f5b13f0afe62164becc19cd2cdb [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="jdbc-auth" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Database authentication</title>
<indexterm>
<primary>MySQL</primary>
</indexterm>
<indexterm>
<primary>PostgreSQL</primary>
</indexterm>
<indexterm>
<primary>load balancing</primary>
</indexterm>
<para>Guacamole supports authentication via MySQL, PostgreSQL, or SQL Server databases through
extensions available from the project website. Using a database for authentication provides
additional features, such as the ability to use load balancing groups of connections and a
web-based administrative interface. Unlike the default, XML-driven authentication module, all
changes to users and connections take effect immediately; users need not logout and back in
to see new connections.</para>
<para>While most authentication extensions function independently, the database authentication
can act in a subordinate role, allowing users from other authentication extensions to be
associated with connections within the database. Users are considered identical to users
within the database if they have the same usernames, and the authentication result of
another extension will be trusted if it succeeds. A user with an account under multiple
systems will thus be able to see data from each system after successfully logging in. For
more information on using the database authentication alongside other mechanisms, see <xref
linkend="ldap-and-database"/> within <xref linkend="ldap-auth"/>.</para>
<para>To use the database authentication extension, you will need:</para>
<orderedlist>
<listitem>
<para>A supported database - currently MariaDB, MySQL, PostgreSQL, or SQL Server.</para>
</listitem>
<listitem>
<para>Sufficient permission to create new databases, to create new users, and to grant
those users permissions.</para>
</listitem>
<listitem>
<para>Network access to the database from the Guacamole server.</para>
</listitem>
</orderedlist>
<important>
<para>This chapter involves modifying the contents of <varname>GUACAMOLE_HOME</varname> -
the Guacamole configuration directory. If you are unsure where
<varname>GUACAMOLE_HOME</varname> is located on your system, please consult <xref
linkend="configuring-guacamole"/> before proceeding.</para>
</important>
<section>
<title>Downloading the database authentication extension</title>
<para>The database authentication extension is available separately from the main
<filename>guacamole.war</filename>. The link for this and all other
officially-supported and compatible extensions for a particular version of Guacamole are
provided on the release notes for that version. You can find the release notes for
current versions of Guacamole here: <link
xlink:href="http://guacamole.apache.org/releases/"
>http://guacamole.apache.org/releases/</link>.</para>
<para>The database authentication extension is packaged as a <filename>.tar.gz</filename>
file containing:</para>
<variablelist>
<varlistentry>
<term><filename>mysql/</filename></term>
<listitem>
<para>Contains the MySQL/MariaDB authentication extension,
<filename>guacamole-auth-jdbc-mysql-1.0.0.jar</filename>, along with a
<filename>schema/</filename> directory containing MySQL-specific SQL
scripts required to set up the database. The
<filename>guacamole-auth-jdbc-mysql-1.0.0.jar</filename> file will
ultimately need to be placed within
<filename>GUACAMOLE_HOME/extensions</filename>, while the MySQL JDBC
driver must be placed within <filename>GUACAMOLE_HOME/lib</filename>.</para>
<para><emphasis>The MySQL JDBC driver is not included with the
extension.</emphasis> You must obtain the JDBC driver
<filename>.jar</filename> yourself from <link
xlink:href="http://dev.mysql.com/downloads/connector/j/">MySQL's
website</link>. The driver is known as "Connector/J", and the required
<filename>.jar</filename> will be within a <filename>.tar.gz</filename>
archive.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>postgresql/</filename></term>
<listitem>
<para>Contains the PostgreSQL authentication extension,
<filename>guacamole-auth-jdbc-postgresql-1.0.0.jar</filename>, along
with a <filename>schema/</filename> directory containing PostgreSQL-specific
SQL scripts required to set up the database. The
<filename>guacamole-auth-jdbc-postgresql-1.0.0.jar</filename> file will
ultimately need to be placed within
<filename>GUACAMOLE_HOME/extensions</filename>, while the PostgreSQL
JDBC driver must be placed within
<filename>GUACAMOLE_HOME/lib</filename>.</para>
<para><emphasis>The PostgreSQL JDBC driver is not included with the
extension.</emphasis> You must obtain the JDBC driver
<filename>.jar</filename> yourself from <link
xlink:href="https://jdbc.postgresql.org/download.html#current"
>PostgreSQL's website</link>. The proper <filename>.jar</filename> file
depends on the version of Java you have installed. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>sqlserver/</filename></term>
<listitem>
<para>Contains the SQL Server authentication extension,
<filename>guacamole-auth-jdbc-sqlserver-1.0.0.jar</filename>, along with
a <filename>schema/</filename> directory contains SQL Server-specific
scripts requires to set up the database. The JAR extension file will need to
be placed within the <filename>GUACAMOLE_HOME/extensions</filename> folder,
while the SQL Server JDBC driver must be placed within the
<filename>GUACAMOLE_HOME/lib</filename> directory.</para>
<para><emphasis>The SQL Server JDBC driver is not included with the extension.</emphasis> You
must obtain the JDBC driver <filename>.jar</filename> yourself and place it in the directory.
Furthermore, the SQL Server authentication extension supports a number of TDS-compatible
drivers, so you must make sure the one you choose is supported by the extension, that the
extension is configured properly, and that the <filename>.jar</filename> is in the correct
directory. Microsoft's JDBC driver can be downloaded from Microsoft's <link
xlink:href="https://docs.microsoft.com/en-us/sql/connect/sql-connection-libraries#anchor-20-drivers-relational-access">
SQL Connection Libraries</link> page.</para>
<para>In addition to the various parameters mentioned below, the SQL Server driver has a
unique parameter available to control the driver compatibility of the JDBC module:
<property>sqlserver-driver</property>. This parameter allows you to choose the compatibility
mode of the module with various TDS-comptabile drivers such that it can be used with different
versions of SQL Server and even non-Microsoft SQL Server databases. The following options are available
for the <property>sqlserver-driver</property> property:
<variablelist>
<varlistentry>
<term>microsoft2005</term>
<listitem>
<para>The current Microsoft driver, supporting SQL Server 2005 and later.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>microsoft</term>
<listitem>
<para>The legacy SQL Server support.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>jtds</term>
<listitem>
<para>The open source JTDS driver.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>datadirect</term>
<listitem>
<para>The Progress Sybase driver.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>Only one of the directories within the archive will be applicable to you, depending on
whether you are using MariaDB, MySQL, PostgreSQL, or SQL Server.</para>
</section>
<section xml:id="jdbc-auth-database-creation">
<title>Creating the Guacamole database</title>
<para>The database authentication module will need a database to store authentication data
and a user to use only for data access and manipulation. You can use an existing
database and existing user, but for the sake of simplicity and security, these
instructions assume you will be creating a new database and new user that will be used
only by Guacamole and only for this authentication module.</para>
<para>You need MariaDB, MySQL, PostgreSQL, or SQL Server installed, and must have sufficient
access to create and administer databases. If this is not the case, install your database
of choice now. Most distributions will provide a convenient MySQL or PostgreSQL package
which will set up everything for you, including the root database user, if
applicable. If you're using SQL Server, you need to install the packages on your platform
of choice, and also make sure that you obtain the proper licensing for the version
and edition of SQL Server you are running.</para>
<para>For the sake of clarity, these instructions will refer to the database as
"guacamole_db", but the database can be named whatever you like.</para>
<section xml:id="jdbc-auth-mysql">
<title>MySQL</title>
<informalexample>
<screen><prompt>$</prompt> <userinput>ls schema/</userinput>
<computeroutput>001-create-schema.sql 002-create-admin-user.sql upgrade</computeroutput>
<prompt>$</prompt> <userinput>cat schema/*.sql | mysql -u root -p <replaceable>guacamole_db</replaceable></userinput>
<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<prompt>$</prompt></screen>
</informalexample>
</section>
<section xml:id="jdbc-auth-postgresql">
<title>PostgreSQL</title>
<informalexample>
<screen><prompt>$</prompt> <userinput>createdb <replaceable>guacamole_db</replaceable></userinput>
<prompt>$</prompt> <userinput>ls schema/</userinput>
<computeroutput>001-create-schema.sql 002-create-admin-user.sql</computeroutput>
<prompt>$</prompt> <userinput>cat schema/*.sql | psql -d <replaceable>guacamole_db</replaceable> -f -</userinput>
<computeroutput>CREATE TYPE
CREATE TYPE
CREATE TYPE
CREATE TABLE
CREATE INDEX</computeroutput>
...
<computeroutput>INSERT 0 1
INSERT 0 4
INSERT 0 3</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
</section>
<section xml:id="jdbc-auth-sqlserver">
<title>SQL Server</title>
<informalexample>
<screen><prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <replaceable>guacamole_db</replaceable> -i schema/001-create-schema.sql</userinput>
<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<computeroutput>Rule bound to data type.
The new rule has been bound to column(s) of the specified user data type.
Rule bound to data type.
The new rule has been bound to column(s) of the specified user data type.</computeroutput>
<prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <replaceable>guacamole_db</replaceable> -i schema/002-create-admin-user.sql</userinput>
<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<computeroutput>
(1 rows affected)
(3 rows affected)
(5 rows affected)</computeroutput>
</screen>
</informalexample>
</section>
</section>
<section>
<title>Upgrading an existing Guacamole database</title>
<para>If you are upgrading from an older version of Guacamole, you may need to run one or
more database schema upgrade scripts located within the
<filename>schema/upgrade/</filename> directory. Each of these scripts is named
<filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename> where
<replaceable>VERSION</replaceable> is the version of Guacamole where those changes
were introduced. They need to be run when you are upgrading from a version of Guacamole
older than <replaceable>VERSION</replaceable>.</para>
<para>If there are no
<filename>upgrade-pre-<replaceable>VERSION</replaceable>.sql</filename> scripts
present in the <filename>schema/upgrade/</filename> directory which apply to your
existing Guacamole database, then the schema has not changed between your version and
the version your are installing, and there is no need to run any database upgrade
scripts.</para>
<para>These scripts are incremental and, when relevant, <emphasis>must be run in
order</emphasis>. For example, if you are upgrading an existing database from
version 0.9.13-incubating to version 1.0.0, you would need to run the
<filename>upgrade-pre-0.9.14.sql</filename> script (because 0.9.13-incubating is
older than 0.9.14), followed by the <filename>upgrade-pre-1.0.0.sql</filename> script
(because 0.9.13-incubating is also older than 1.0.0).</para>
<important xml:id="jdbc-auth-postgresql-upgrade">
<para>Because the permissions granted to the Guacamole-specific PostgreSQL user when the
database was first created will not automatically be granted for any new tables and
sequences, you will also need to re-grant those permissions after applying any
upgrade relevant scripts:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable></userinput>
<computeroutput>psql (9.3.6)
Type "help" for help.
</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>\q</userinput>
<prompt>$</prompt></screen>
</informalexample>
</important>
</section>
<section>
<title>Granting Guacamole access to the database</title>
<para>For Guacamole to be able to execute queries against the database, you must create a
new user for the database and grant that user sufficient privileges to manage the
contents of all tables in the database. The user created for Guacamole needs only
<code>SELECT</code>, <code>UPDATE</code>, <code>INSERT</code>, and
<code>DELETE</code> permissions on all Guacamole tables. Additionally, if using
PostgreSQL, the user will need <code>SELECT</code> and <code>USAGE</code> permission on
all sequences within all Guacamole tables. <emphasis>No other permissions should be
granted.</emphasis></para>
<para>These instructions will refer to the user as "guacamole_user" but the user can be
named whatever you like. Naturally, you should also choose a real password for your user
rather than the string "some_password" used as a placeholder below.</para>
<section>
<title>MySQL</title>
<informalexample>
<screen><prompt>$</prompt> mysql -u root -p
<prompt>Enter password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<computeroutput>Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 233
Server version: 5.5.29-0ubuntu0.12.10.1 (Ubuntu)
Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
</computeroutput>
<prompt>mysql></prompt> <userinput>CREATE DATABASE <replaceable>guacamole_db</replaceable>;</userinput>
<computeroutput>Query OK, 1 row affected (0.00 sec)</computeroutput>
<prompt>mysql></prompt> <userinput>CREATE USER '<replaceable>guacamole_user'</replaceable>@'localhost' IDENTIFIED BY '<replaceable>some_password</replaceable>';</userinput>
<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
<prompt>mysql></prompt> <userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON <replaceable>guacamole_db</replaceable>.* TO '<replaceable>guacamole_user'</replaceable>@'localhost';</userinput>
<computeroutput>Query OK, 0 rows affected (0.00 sec)</computeroutput>
<prompt>mysql></prompt> <userinput>FLUSH PRIVILEGES;</userinput>
<computeroutput>Query OK, 0 rows affected (0.02 sec)</computeroutput>
<prompt>mysql></prompt> <userinput>quit</userinput>
<computeroutput>Bye</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
</section>
<section>
<title>PostgreSQL</title>
<informalexample>
<screen><prompt>$</prompt> <userinput>psql -d <replaceable>guacamole_db</replaceable></userinput>
<computeroutput>psql (9.3.6)
Type "help" for help.
</computeroutput>
<prompt>guacamole=# </prompt><userinput>CREATE USER <replaceable>guacamole_user</replaceable> WITH PASSWORD '<replaceable>some_password</replaceable>';</userinput>
<computeroutput>CREATE ROLE</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <replaceable>guacamole_user</replaceable>;</userinput>
<computeroutput>GRANT</computeroutput>
<prompt>guacamole=# </prompt><userinput>\q</userinput>
<prompt>$</prompt></screen>
</informalexample>
</section>
<section>
<title>SQL Server</title>
<informalexample>
<screen><prompt>$</prompt> <userinput>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA</userinput>
<prompt>Password:</prompt> <userinput><replaceable>password</replaceable></userinput>
<prompt>1></prompt> <userinput>CREATE DATABASE <replaceable>guacamole_db</replaceable>;</userinput>
<prompt>2></prompt> <userinput>GO</userinput>
<prompt>1></prompt> <userinput>CREATE LOGIN <replaceable>guacamole_user</replaceable> WITH PASSWORD = '<replaceable>some_password</replaceable>';</userinput>
<prompt>2></prompt> <userinput>GO</userinput>
<prompt>1></prompt> <userinput>USE <replaceable>guacamole_db</replaceable>;</userinput>
<prompt>2></prompt> <userinput>GO</userinput>
<prompt>1></prompt> <userinput>CREATE USER <replaceable>guacamole_user</replaceable>;</userinput>
<prompt>2></prompt> <userinput>GO</userinput>
<prompt>1></prompt> <userinput>ALTER ROLE db_datawriter ADD MEMBER <replaceable>guacamole_user</replaceable>;</userinput>
<prompt>2></prompt> <userinput>ALTER ROLE db_datareader ADD MEMBER <replaceable>guacamole_user</replaceable>;</userinput>
<prompt>3></prompt> <userinput>GO</userinput></screen>
</informalexample>
</section>
</section>
<section xml:id="jdbc-auth-installation">
<title>Installing database authentication</title>
<para>Guacamole extensions are self-contained <filename>.jar</filename> files which are
located within the <filename>GUACAMOLE_HOME/extensions</filename> directory. To install
the database authentication extension, you must:</para>
<procedure>
<step>
<para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it
does not already exist.</para>
</step>
<step>
<para>Copy <filename>guacamole-auth-jdbc-mysql-1.0.0.jar</filename>
<emphasis>or</emphasis>
<filename>guacamole-auth-jdbc-postgresql-1.0.0.jar</filename>
<emphasis>or</emphasis>
<filename>guacamole-auth-jdbc-sqlserver-1.0.0.jar</filename> within
<filename>GUACAMOLE_HOME/extensions</filename>, depending on whether you are
using MySQL/MariaDB, PostgreSQL, or SQL Server.</para>
</step>
<step>
<para>Copy the JDBC driver for your database to
<filename>GUACAMOLE_HOME/lib</filename>. Without a JDBC driver for your
database, Guacamole will not be able to connect and authenticate users.</para>
</step>
<step>
<para>Configure Guacamole to use database authentication, as described below.</para>
</step>
</procedure>
<important>
<para>You will need to restart Guacamole by restarting your servlet container in order
to complete the installation. Doing this will disconnect all active users, so be
sure that it is safe to do so prior to attempting installation. If you do not
configure the database authentication properly, Guacamole will not start up again
until the configuration is fixed.</para>
</important>
<section xml:id="jdbc-auth-configuration">
<title>Configuring Guacamole for database authentication</title>
<para>Additional properties must be added to <filename>guacamole.properties</filename>
for Guacamole to properly connect to your database. These properties are specific to
the database being used, and must be set correctly for authentication to
work.</para>
<para>To use a MySQL database, you will need to specify the following:</para>
<informalexample>
<programlisting># MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: <replaceable>guacamole_db</replaceable>
mysql-username: <replaceable>guacamole_user</replaceable>
mysql-password: <replaceable>some_password</replaceable>
</programlisting>
</informalexample>
<para>For PostgreSQL, the properties are similar, but with different prefixes:</para>
<informalexample>
<programlisting># PostgreSQL properties
postgresql-hostname: localhost
postgresql-port: 5432
postgresql-database: <replaceable>guacamole_db</replaceable>
postgresql-username: <replaceable>guacamole_user</replaceable>
postgresql-password: <replaceable>some_password</replaceable>
</programlisting>
</informalexample>
<para>The SQL Server properties follow the same format:</para>
<informalexample>
<programlisting># SQL Server properties
sqlserver-hostname: localhost
sqlserver-port: 1433
sqlserver-database: <replaceable>guacamole_db</replaceable>
sqlserver-username: <replaceable>guacamole_user</replaceable>
sqlserver-password: <replaceable>some_password</replaceable>
sqlserver-driver: microsoft2005
</programlisting>
</informalexample>
<para>The properties absolutely required by the database authentication extension are
relatively few and self-explanatory, describing only how the connection to the
database is to be established, and how Guacamole will authenticate when querying the
database:</para>
<informaltable frame="all">
<tgroup cols="4">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="1*"/>
<colspec colname="c4" colnum="4" colwidth="2*"/>
<thead>
<row>
<entry>MySQL/MariaDB Property</entry>
<entry>PostgreSQL Property</entry>
<entry>SQL Server Property</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><property>mysql-hostname</property></entry>
<entry><property>postgresql-hostname</property></entry>
<entry><property>sqlserver-hostname</property></entry>
<entry>
<para>The hostname or IP address of the server hosting your
database.</para>
</entry>
</row>
<row>
<entry><property>mysql-port</property></entry>
<entry><property>postgresql-port</property></entry>
<entry><property>sqlserver-port</property></entry>
<entry>
<para>The port number of the database to connect to. For MySQL and
MariaDB, this will likely be 3306. For PostgreSQL, this will
likely be 5432.</para>
</entry>
</row>
<row>
<entry><property>mysql-database</property></entry>
<entry><property>postgresql-database</property></entry>
<entry><property>sqlserver-database</property></entry>
<entry>
<para>The name of the database that you created for Guacamole. This
is given as "guacamole_db" in the examples given in this
chapter.</para>
</entry>
</row>
<row>
<entry><property>mysql-username</property></entry>
<entry><property>postgresql-username</property></entry>
<entry><property>sqlserver-username</property></entry>
<entry>
<para>The username of the user that Guacamole should use to connect
to the database. This is given as "guacamole_user" in the
examples given in this chapter.</para>
</entry>
</row>
<row>
<entry><property>mysql-password</property></entry>
<entry><property>postgresql-password</property></entry>
<entry><property>sqlserver-password</property></entry>
<entry>
<para>The password Guacamole should provide when authenticating with
the database. This is given as "some_password" in the examples
given in this chapter.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Be sure to specify the correct username and password for the database user you
created, and to specify the correct database. Authentication will not work if these
parameters are not correct.</para>
<section>
<title>Enforcing password policies</title>
<para>Configuration options are available for enforcing rules intended to encourage
password complexity and regular changing of passwords. None of these options are
enabled by default, but can be selectively enabled through additional properties
in <filename>guacamole.properties</filename>.</para>
<section>
<title>Password complexity</title>
<para>Administrators can require that passwords have a certain level of
complexity, such as having both uppercase and lowercase letters ("multiple
case"), at least one digit, or at least one symbol, and can prohibit
passwords from containing the user's own username.</para>
<para>For the sake of password content, the database authentication defines a
"digit" as any numeric character. This takes non-English languages into
account, and is not be simply "0" thorough "9". There are quite a few <link
xlink:href="https://en.wikipedia.org/wiki/Numerals_in_Unicode">numeric
characters defined by Unicode</link>. A "symbol" is defined as any
non-alphanumeric character - any character which Unicode does not define as
alphabetic or numeric.</para>
<para>The check for whether a password contains the user's own username is
performed in a case-insensitive manner. For example, if the user's username
is "phil", the passwords "ch!0roPhil" and "PHIL-o-dendr0n" would still be
prohibited.</para>
<informalexample>
<programlisting># MySQL
mysql-user-password-min-length: <replaceable>8</replaceable>
mysql-user-password-require-multiple-case: true
mysql-user-password-require-symbol: true
mysql-user-password-require-digit: true
mysql-user-password-prohibit-username: true
# PostgreSQL
postgresql-user-password-min-length: <replaceable>8</replaceable>
postgresql-user-password-require-multiple-case: true
postgresql-user-password-require-symbol: true
postgresql-user-password-require-digit: true
postgresql-user-password-prohibit-username: true
# SQL Server
sqlserver-user-password-min-length: <replaceable>8</replaceable>
sqlserver-user-password-require-multiple-case: true
sqlserver-user-password-require-symbol: true
sqlserver-user-password-require-digit: true
sqlserver-user-password-prohibit-username: true</programlisting>
</informalexample>
</section>
<section>
<title>Password age / expiration</title>
<para>"Password age" refers to two separate concepts:</para>
<orderedlist>
<listitem>
<para>Requiring users to change their password after a certain amount of
time has elapsed since the last password change (maximum password
age).</para>
</listitem>
<listitem>
<para>Preventing users from changing their password too frequently
(minimum password age).</para>
</listitem>
</orderedlist>
<para>In both cases, these values are specified in units of days, and are both
disabled by default.</para>
<para>While it may seem strange to prevent users from changing their password
too frequently, it does make sense if you are concerned that rapid password
changes may defeat password expiration (users could immediately change the
password back) or tracking of password history (users could cycle through
passwords until the history is exhausted and their old password is
back).</para>
<para>So that administrators can always intervene in the case that a password
needs to be reset despite restrictions, the minimum age restriction does not
apply to any user with permission to administer the system.</para>
<informalexample>
<programlisting># MySQL
mysql-user-password-min-age: <replaceable>7</replaceable>
mysql-user-password-max-age: <replaceable>90</replaceable>
# PostgreSQL
postgresql-user-password-min-age: <replaceable>7</replaceable>
postgresql-user-password-max-age: <replaceable>90</replaceable>
# SQL Server
sqlserver-user-password-min-age: <replaceable>7</replaceable>
sqlserver-user-password-max-age: <replaceable>90</replaceable></programlisting>
</informalexample>
</section>
<section>
<title>Preventing password reuse</title>
<para>If desired, Guacamole can keep track of each user's most recently used
passwords, and will prohibit reuse of those passwords until the password has
been changed sufficiently many times. By default, Guacamole will not keep
track of old passwords.</para>
<para>Note that these passwords are hashed in the same manner as each user's
current password. When a user's password is changed, the hash, salt, etc.
currently stored for that user is actually just copied verbatim (along with
a timestamp) into a list of historical passwords, with older entries from
this list being automatically deleted.</para>
<informalexample>
<programlisting># MySQL
mysql-user-password-history-size: <replaceable>6</replaceable>
# PostgreSQL
postgresql-user-password-history-size: <replaceable>6</replaceable>
# SQL Server
sqlserver-user-password-history-size: <replaceable>6</replaceable></programlisting>
</informalexample>
</section>
</section>
<section xml:id="jdbc-auth-concurrency">
<title>Concurrent use of Guacamole connections</title>
<para>The database authentication module provides configuration options to restrict
concurrent use of connections or connection groups. These options are set
through <filename>guacamole.properties</filename> and specify the default
concurrency policies for connections and connection groups. The values set
through the properties can be overridden later on a per-connection basis using
the administrative interface:</para>
<informalexample>
<programlisting># MySQL
mysql-default-max-connections: 1
mysql-default-max-group-connections: 1
# PostgreSQL
postgresql-default-max-connections: 1
postgresql-default-max-group-connections: 1
# SQL Server
sqlserver-default-max-connections: 1
sqlserver-default-max-group-connections: 1</programlisting>
</informalexample>
<para>These properties are not required, but with the above properties in place,
users attempting to use a connection or group that is already in use will be
denied access. By default, concurrent access is allowed.</para>
<para>Concurrent access can also be restricted such that a particular user may only
use a connection or group a certain number of times. By default, per-user
concurrent use is limited for connection groups (to avoid allowing a single user
to exhaust the contents of the group) but otherwise unrestricted. This default
behavior can be modified through <filename>guacamole.properties</filename> or
the per-connection settings exposed in the administrative interface:</para>
<informalexample>
<programlisting># MySQL
mysql-default-max-connections-per-user: 0
mysql-default-max-group-connections-per-user: 0
# PostgreSQL
postgresql-default-max-connections-per-user: 0
postgresql-default-max-group-connections-per-user: 0
# SQL Server
sqlserver-default-max-connections-per-user: 0
sqlserver-default-max-group-connections-per-user: 0</programlisting>
</informalexample>
<para>If you wish to impose an absolute limit on the number of connections that can
be established through Guacamole, ignoring which users or connections are
involved, this can be done as well. By default, Guacamole will impose no such
limit:</para>
<informalexample>
<programlisting># MySQL
mysql-absolute-max-connections: 0
# PostgreSQL
postgresql-absolute-max-connections: 0
# SQL Server
sqlserver-absolute-max-connections: 0</programlisting>
</informalexample>
</section>
</section>
<section xml:id="jdbc-auth-restrict">
<title>Restricting authentication to database users only</title>
<para>By default, users will be allowed access to Guacamole as long as they are
authenticated by at least one extension. If database authentication is in use, and a
user is not associated with the database, then that user will be allowed access to
Guacamole if another extension grants this access, and will be provided with a view
of the data exposed by other extensions for that user account.</para>
<para>In some situations, such as when <link linkend="ldap-and-database">combining LDAP
with a database</link>, it would be preferable to let the database have the last
word regarding whether a user should be allowed into the system: restricting access
to only those users which exist in the database, and explicitly denying
authentication through all other means unless that user has been associated with the
database as well. This behavior can be forced by setting properties which declare
that database user accounts are required:</para>
<informalexample>
<programlisting># MySQL
mysql-user-required: true
# PostgreSQL
postgresql-user-required: true
# SQL Server
sqlserver-user-required: true</programlisting>
</informalexample>
<para>With the above properties set, successful authentication attempts for users which
are not associated with the database will be vetoed by the database authentication.
Guacamole will report that the login is invalid, as if the user does not exist at
all.</para>
</section>
<section>
<title>Completing the installation</title>
<para>Guacamole will only reread <filename>guacamole.properties</filename> and load
newly-installed extensions during startup, so your servlet container will need to be
restarted before the database authentication will take effect. Restart your servlet
container and give the new authentication a try.</para>
<para>
<important>
<para>You only need to restart your servlet container. <emphasis>You do not need
to restart <package>guacd</package></emphasis>.</para>
<para><package>guacd</package> is completely independent of the web application
and does not deal with <filename>guacamole.properties</filename> or the
authentication system in any way. Since you are already restarting the
servlet container, restarting <package>guacd</package> as well technically
won't hurt anything, but doing so is completely pointless.</para>
</important>
</para>
<para>If Guacamole does not come back online after restarting your servlet container,
check the logs. Problems in the configuration of the database authentication
extension will prevent Guacamole from starting up, and any such errors will be
recorded in the logs of your servlet container.</para>
</section>
</section>
<section xml:id="jdbc-auth-default-user">
<title>Logging in</title>
<indexterm>
<primary>default user</primary>
</indexterm>
<indexterm>
<primary><systemitem>guacadmin</systemitem></primary>
</indexterm>
<para>The default Guacamole user created by the provided SQL scripts is
"<systemitem>guacadmin</systemitem>", with a default password of
"<systemitem>guacadmin</systemitem>". Once you have verified that the database
authentication is working, <emphasis>you should change your password
immediately</emphasis>.</para>
<para>More detailed instructions for managing users and connections is given in <xref
linkend="administration"/>.</para>
</section>
<section xml:id="jdbc-auth-schema">
<title>Modifying data manually</title>
<indexterm>
<primary>schema</primary>
</indexterm>
<para>If necessary, it is possible to modify the data backing the authentication module
manually by executing SQL statements against the database. In general use, this will not
be common, but if you need to bulk-insert a large number of users or connections, or you
wish to translate an existing configuration automatically, you will need to know how
everything is laid out at a high level.</para>
<para>This section assumes knowledge of SQL and your chosen database, and that whatever you
need to do can be accomplished if only you had high-level information about Guacamole's
SQL schema.</para>
<section xml:id="jdbc-auth-schema-entities">
<title>Entities</title>
<indexterm>
<primary><classname>guacamole_entity</classname></primary>
</indexterm>
<para>Every user and user group has a corresponding entry in the
<classname>guacamole_entity</classname> table which serves as the basis for
assignment of a unique name, permissions, as well as relations which are common to
both users and groups like group membership. Each entity has a corresponding name
which is unique across all other entities of the same type.</para>
<para>If deleting a user or user group, the corresponding entity should also be deleted.
As any user or group which points to the entity will be deleted automatically when
the entity is deleted through cascading deletion, <emphasis>it is advisable to use
the entity as the basis for any delete operation</emphasis>.</para>
<para>The <classname>guacamole_entity</classname> table contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The unique integer associated with each entity (user or user group).
This value is generated automatically when a new entry is inserted into
the <classname>guacamole_entity</classname> table and is distinct from
the unique integer associated with the user entry in <link
linkend="jdbc-auth-schema-users"
><classname>guacamole_user</classname></link> or the user group
entry in <link linkend="jdbc-auth-schema-groups"
><classname>guacamole_user_group</classname></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>name</property></term>
<listitem>
<para>The unique name associated with each user or group. This value must be
specified manually, and must be different from any existing user or
group in the table. The name need only be unique relative to the names
of other entities having the same type (a user may have the same name as
a group).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>type</property></term>
<listitem>
<para>The type of this entity. This can be either <type>USER</type> or
<type>USER_GROUP</type>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-users">
<title>Users</title>
<indexterm>
<primary><classname>guacamole_user</classname></primary>
</indexterm>
<para>Every user has a corresponding entry in the <classname>guacamole_user</classname>
and <link linkend="jdbc-auth-schema-entities"
><classname>guacamole_entity</classname></link> tables. Each user has a
corresponding unique username, specified via
<classname>guacamole_entity</classname>, and salted password. The salted password is
split into two columns: one containing the salt, and the other containing the
password hashed with SHA-256.</para>
<para>If deleting a user, the <link linkend="jdbc-auth-schema-entities">corresponding
entity</link> should also be deleted. As any user which points to the entity
will be deleted automatically when the entity is deleted through cascading deletion,
<emphasis>it is advisable to use the entity as the basis for any delete
operation</emphasis>.</para>
<para>The <classname>guacamole_user</classname> table contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>user_id</property></term>
<listitem>
<para>The unique integer associated with each user. This value is generated
automatically when a new entry is inserted into the
<classname>guacamole_user</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
<classname>guacamole_entity</classname> entry representing this
user.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_hash</property></term>
<listitem>
<para>The result of hashing the user's password concatenated with the
contents of <property>password_salt</property> using SHA-256. The salt
is appended to the password prior to hashing.</para>
<para>Although passwords set through Guacamole will always be salted, it is
possible to use unsalted password hashes when inserted manually or
through an external system. If <property>password_salt</property> is
<constant>NULL</constant>, the <property>password_hash</property>
will be handled as a simple unsalted hash of the password.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_salt</property></term>
<listitem>
<para>A 32-byte random value. When a new user is created from the web
interface, this value is randomly generated using a
cryptographically-secure random number generator.</para>
<para>This will always be set for users whose passwords are set through
Guacamole, but it is possible to use unsalted password hashes when
inserted manually or through an external system. If
<property>password_salt</property> is <constant>NULL</constant>, the
<property>password_hash</property> will be handled as a simple
unsalted hash of the password.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_date</property></term>
<listitem>
<para>The date (and time) that the password was last changed. When a
password is changed via the Guacamole interface, this value is updated.
This, along with the contents of the
<classname>guacamole_user_password_history</classname> table, is
used to enforce password policies.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>disabled</property></term>
<listitem>
<para>Whether login attempts as this user account should be rejected. If
this column is set to <constant>TRUE</constant> or
<constant>1</constant>, login attempts by this user will be rejected
as if the user did not exist. By default, user accounts are not
disabled, and login attempts will succeed if the user provides the
correct password.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>expired</property></term>
<listitem>
<para>If set to <constant>TRUE</constant> or <constant>1</constant>,
requires that the user reset their password prior to fully logging in.
The user will be presented with a password reset form, and will not be
allowed to log into Guacamole until the password has been changed. By
default, user accounts are not expired, and no password reset will be
required upon login.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>access_window_start</property></term>
<listitem>
<para>The time of day (not date) after which this user account may be used.
If <constant>NULL</constant>, this restriction does not apply. If set to
non-<constant>NULL</constant>, attempts to log in after the
specified time will be allowed, while attempts to log in before the
specified time will be denied.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>access_window_end</property></term>
<listitem>
<para>The time of day (not date) after which this user account may
<emphasis>not</emphasis> be used. If <constant>NULL</constant>, this
restriction does not apply. If set to non-<constant>NULL</constant>,
attempts to log in after the specified time will be denied, while
attempts to log in before the specified time will be allowed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>valid_from</property></term>
<listitem>
<para>The date (not time of day) after which this user account may be used.
If <constant>NULL</constant>, this restriction does not apply. If set to
non-<constant>NULL</constant>, attempts to log in after the
specified date will be allowed, while attempts to log in before the
specified date will be denied.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>valid_until</property></term>
<listitem>
<para>The date (not time of day) after which this user account may
<emphasis>not</emphasis> be used. If <constant>NULL</constant>, this
restriction does not apply. If set to non-<constant>NULL</constant>,
attempts to log in after the specified date will be denied, while
attempts to log in before the specified date will be allowed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>timezone</property></term>
<listitem>
<para>The time zone to use when interpreting the
<property>access_window_start</property>,
<property>access_window_end</property>,
<property>valid_from</property>, and
<property>valid_until</property> values. This value may be any Java
<classname>TimeZone</classname> ID, as defined by <link
xlink:href="http://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs()"
><methodname>getAvailableIDs()</methodname></link>, though the
Guacamole management interface will only present a subset of these time
zones.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>full_name</property></term>
<listitem>
<para>The user's full name. Unlike the username, this name need not be
unique; it is optional and is meant for display purposes only. Defining
this value has no bearing on user identity, which is dictated purely by
the username. User accounts with no associated full name should have
this column set to <constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>email_address</property></term>
<listitem>
<para>The user's email address, if any. This value is optional, need not be
unique relative to other defined users, and is meant for display
purposes only. Defining this value has no bearing on user identity,
which is dictated purely by the username. If the user has no associated
email address, this column should be set to
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>organization</property></term>
<listitem>
<para>The name of the organization, company, etc. that the user is
affiliated with. This value is optional and is meant for display
purposes only. Defining this value has no bearing on user identity,
which is dictated purely by the username. Users with no associated
organization should have this column set to
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>organizational_role</property></term>
<listitem>
<para>The role or title of the user at the organization described by the
<property>organization</property> column. This value is optional and
is used for display purposes only. Defining this value has no bearing on
user identity, which is dictated purely by the username. Users with no
associated organization (or specific role/title at that organization)
should have this column set to <constant>NULL</constant>.</para>
</listitem>
</varlistentry>
</variablelist>
<important>
<para>If you choose to manually set unsalted password hashes, please be sure you
understand the security implications of doing so.</para>
<para>In the event that your database is compromised, finding the password for a
<emphasis>salted</emphasis> hash is computationally infeasible, but finding
the password for an <emphasis>unsalted</emphasis> hash is often not. In many
cases, the password which corresponds to an unsalted hash can be found simply by
entering the hash into a search engine like Google.</para>
</important>
<para>If creating a user manually, the main complication is the salt, which must be
determined before the <command>INSERT</command> statement can be constructed, but
this can be dealt with using variables. For MySQL:</para>
<informalexample>
<programlisting>-- Generate salt
SET @salt = UNHEX(SHA2(UUID(), 256));
-- Create base entity entry for user
INSERT INTO guacamole_entity (name, type)
VALUES ('<replaceable>myuser</replaceable>', 'USER');
-- Create user and hash password with salt
INSERT INTO guacamole_user (
entity_id,
password_salt,
password_hash,
password_date
)
SELECT
entity_id,
@salt,
UNHEX(SHA2(CONCAT('<replaceable>mypassword</replaceable>', HEX(@salt)), 256)),
CURRENT_TIMESTAMP
FROM guacamole_entity
WHERE
name = '<replaceable>myuser</replaceable>'
AND type = 'USER';</programlisting>
</informalexample>
<para>This sort of statement is useful for both creating new users or for changing
passwords, especially if all administrators have forgotten theirs.</para>
<para>If you are not using MySQL, or you are using a version of MySQL that lacks the
<methodname>SHA2</methodname> function, you will need to calculate the SHA-256
value manually (by using the <command>sha256sum</command> command, for
example).</para>
<section xml:id="jdbc-auth-schema-password-history">
<title>Password history</title>
<indexterm>
<primary><classname>guacamole_user_password_history</classname></primary>
</indexterm>
<para>When a user's password is changed, a copy of the previous password's hash and
salt is made within the <classname>guacamole_user_password_history</classname>.
Each entry in this table is associated with the user whose password changed,
along with the date that password first applied.</para>
<para>Old entries within this table are automatically deleted on a per-user basis
depending on the requirements of the password policy. For example, if the
password policy has been configured to require that users not reuse any of their
previous six passwords, then there will be no more than six entries in this
table for each user.</para>
<variablelist>
<varlistentry>
<term><property>password_history_id</property></term>
<listitem>
<para>The unique integer associated with each password history record.
This value is generated automatically when a new entry is inserted
into the <classname>guacamole_user_password_history</classname>
table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>user_id</property></term>
<listitem>
<para>The value of the <property>user_id</property> column from the
entry in <classname>guacamole_user</classname> associated with the
user who previously had this password.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_hash</property></term>
<listitem>
<para>The hashed password specified within the
<property>password_hash</property> column of
<classname>guacamole_user</classname> prior to the password
being changed.</para>
<para>In most cases, this will be a salted hash, though it is possible
to force the use of unsalted hashes when making changes to the
database manually or through an external system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_salt</property></term>
<listitem>
<para>The salt value specified within the
<property>password_salt</property> column of
<classname>guacamole_user</classname> prior to the password
being changed.</para>
<para>This will always be set for users whose passwords are set through
Guacamole, but it is possible to use unsalted password hashes when
inserted manually or through an external system, in which case this
may be <constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>password_date</property></term>
<listitem>
<para>The date (and time) that the password was set. The time that the
password ceased being used is recorded either by the password_date
of the next related entry in
<classname>guacamole_user_password_history</classname> or
<property>password_date</property> of
<classname>guacamole_user</classname> (if there is no such
history entry).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-login-history">
<title>Login history</title>
<indexterm>
<primary><classname>guacamole_user_history</classname></primary>
</indexterm>
<para>When a user logs in or out, a corresponding entry in the
<classname>guacamole_user_history</classname> table is created or updated
respectively. Each entry is associated with the user that logged in and the time
their session began. If the user has logged out, the time their session ended is
also stored.</para>
<para>It is very unlikely that a user will need to update this table, but knowing
the structure is potentially useful if you wish to generate a report of
Guacamole usage. The <classname>guacamole_user_history</classname> table has the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>history_id</property></term>
<listitem>
<para>The unique integer associated with each history record. This value
is generated automatically when a new entry is inserted into the
<classname>guacamole_user_history</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>user_id</property></term>
<listitem>
<para>The value of the <property>user_id</property> from the entry in
<classname>guacamole_user</classname> associated with the user
that logged in. If the user no longer exists, this will be
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>username</property></term>
<listitem>
<para>The username associated with the user at the time that they logged
in. This username value is not guaranteed to uniquely identify a
user, as the original user may be subsequently renamed or
deleted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>remote_host</property></term>
<listitem>
<para>The hostname or IP address of the machine that the user logged in
from, if known. If unknown, this will be
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>start_date</property></term>
<listitem>
<para>The time at which the user logged in. Despite its name, this
column also stores time information in addition to the date.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>end_date</property></term>
<listitem>
<para>The time at which the user logged out. If the user is still
active, the value in this column will be <constant>NULL</constant>.
Despite its name, this column also stores time information in
addition to the date.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="jdbc-auth-schema-groups">
<title>User groups</title>
<indexterm>
<primary><classname>guacamole_user_group</classname></primary>
</indexterm>
<para>Similar to <link linkend="jdbc-auth-schema-users">users</link>, every user group
has a corresponding entry in the <classname>guacamole_user_group</classname> and
<link linkend="jdbc-auth-schema-entities"
><classname>guacamole_entity</classname></link> tables. Each user group has
a corresponding unique name specified via
<classname>guacamole_entity</classname>.</para>
<para>If deleting a user group, the <link linkend="jdbc-auth-schema-entities"
>corresponding entity</link> should also be deleted. As any user group which
points to the entity will be deleted automatically when the entity is deleted
through cascading deletion, <emphasis>it is advisable to use the entity as the basis
for any delete operation</emphasis>.</para>
<para>The <classname>guacamole_user_group</classname> table contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>user_group_id</property></term>
<listitem>
<para>The unique integer associated with each user group. This value is
generated automatically when a new entry is inserted into the
<classname>guacamole_user_group</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
<classname>guacamole_entity</classname> entry representing this user
group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>disabled</property></term>
<listitem>
<para>Whether membership within this group should be taken into account when
determining the permissions granted to a particular user. If this column
is set to <constant>TRUE</constant> or <constant>1</constant>,
membership in this group will have no effect on user permissions,
whether those permissions are granted to this group directly or
indirectly through the groups that this group is a member of. By
default, user groups are not disabled, and permissions granted to a user
through the group will be taken into account.</para>
</listitem>
</varlistentry>
</variablelist>
<indexterm>
<primary><classname>guacamole_user_group_member</classname></primary>
</indexterm>
<para>Membership within a user group is dictated through entries in the
<classname>guacamole_user_group_member</classname> table. As both users and user
groups may be members of groups, each entry associates the containing group with the
entity of the member.</para>
<para>The <classname>guacamole_user_group_member</classname> table contains the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>user_group_id</property></term>
<listitem>
<para>The <property>user_group_id</property> value of the user group having
the specified member.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>member_entity_id</property></term>
<listitem>
<para>The <property>entity_id</property> value of the user or user group
that is a member of the specified group.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-connections">
<title>Connections and parameters</title>
<indexterm>
<primary><classname>guacamole_connection</classname></primary>
</indexterm>
<indexterm>
<primary><classname>guacamole_connection_parameter</classname></primary>
</indexterm>
<para>Each connection has an entry in the <classname>guacamole_connection</classname>
table, with a one-to-many relationship to parameters, stored as name/value pairs in
the <classname>guacamole_connection_parameter</classname> table.</para>
<para>The <classname>guacamole_connection</classname> table is simply a pairing of a
unique and descriptive name with the protocol to be used for the connection. It
contains the following columns:</para>
<variablelist>
<varlistentry>
<term><property>connection_id</property></term>
<listitem>
<para>The unique integer associated with each connection. This value is
generated automatically when a new entry is inserted into the
<classname>guacamole_connection</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_name</property></term>
<listitem>
<para>The unique name associated with each connection. This value must be
specified manually, and must be different from any existing connection
name in the same connection group. References to connections in other
tables use the value from <property>connection_id</property>, not
<property>connection_name</property>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>protocol</property></term>
<listitem>
<para>The protocol to use with this connection. This is the name of the
protocol that should be sent to <package>guacd</package> when
connecting, for example "<constant>vnc</constant>" or
"<constant>rdp</constant>".</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parent_id</property></term>
<listitem>
<para>The unique integer associated with the connection group containing
this connection, or <constant>NULL</constant> if this connection is
within the root group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>max_connections</property></term>
<listitem>
<para>The maximum number of concurrent connections to allow to this
connection at any one time <emphasis>regardless of user</emphasis>.
<constant>NULL</constant> will use the default value specified in
<filename>guacamole.properties</filename> with the
<property>mysql-default-max-connections</property> or
<property>postgresql-default-max-connections</property> properties,
and a value of <constant>0</constant> denotes unlimited.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>max_connections_per_user</property></term>
<listitem>
<para>The maximum number of concurrent connections to allow to this
connection at any one time <emphasis>from a single user</emphasis>.
<constant>NULL</constant> will use the default value specified in
<filename>guacamole.properties</filename> with the
<property>mysql-default-max-connections</property> or
<property>postgresql-default-max-connections</property> properties,
and a value of <constant>0</constant> denotes unlimited.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>proxy_hostname</property></term>
<listitem>
<para>The hostname or IP address of the Guacamole proxy daemon
(<package>guacd</package>) which should be used for this connection.
If <constant>NULL</constant>, the value defined with the
<property>guacd-hostname</property> property in
<filename>guacamole.properties</filename> will be used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>proxy_port</property></term>
<listitem>
<para>The TCP port number of the Guacamole proxy daemon
(<package>guacd</package>) which should be used for this connection.
If <constant>NULL</constant>, the value defined with the
<property>guacd-port</property> property in
<filename>guacamole.properties</filename> will be used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>proxy_encryption_method</property></term>
<listitem>
<para>The encryption method which should be used when communicating with the
Guacamole proxy daemon (<package>guacd</package>) for this connection.
This can be either <constant>NONE</constant>, for no encryption, or
<constant>SSL</constant>, for SSL/TLS. If <constant>NULL</constant>,
the encryption method will be dictated by the
<property>guacd-ssl</property> property in
<filename>guacamole.properties</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_weight</property></term>
<listitem>
<para>The weight for a connection, used for applying weighted load balancing
algorithms when connections are part of a BALANCING group. This is an
integer value, where values <constant>1</constant> or greater will weight
the connection relative to other connections in that group, and values
below <constant>1</constant> cause the connection to be disabled in the
group. If <constant>NULL</constant>, the connection will be assigned a
default weight of <constant>1</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>failover_only</property></term>
<listitem>
<para>Whether this connection should be used for failover situations only,
also known as a "hot spare". If this column is set to
<constant>TRUE</constant> or <constant>1</constant>, this connection
will be used only when another connection within the same
<type>BALANCING</type> connection group has failed due to an error
within the remote desktop. </para>
<para><emphasis>Connection groups will always transparently switch to the
next available connection in the event of remote desktop failure,
regardless of the value of this column.</emphasis> This column
simply dictates whether a particular connection should be
<emphasis>reserved</emphasis> for such situations, and left unused
otherwise.</para>
<para>This column only has an effect on connections within
<type>BALANCING</type> groups.</para>
</listitem>
</varlistentry>
</variablelist>
<para>As there are potentially multiple parameters per connection, where the names of
each parameter are completely arbitrary and determined only by the protocol in use,
every parameter for a given connection has an entry in table
<classname>guacamole_connection_parameter</classname> table associated with its
corresponding connection. This table contains the following columns:</para>
<variablelist>
<varlistentry>
<term><property>connection_id</property></term>
<listitem>
<para>The <property>connection_id</property> value from the connection this
parameter is for.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parameter_name</property></term>
<listitem>
<para>The name of the parameter to set. This is the name listed in the
documentation for the protocol specified in the associated
connection.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parameter_value</property></term>
<listitem>
<para>The value to assign to the parameter named. While this value is an
arbitrary string, it must conform to the requirements of the protocol as
documented for the connection to be successful.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Adding a connection and corresponding parameters is relatively easy compared to
adding a user as there is no salt to generate nor password to hash:</para>
<informalexample>
<programlisting>-- Create connection
INSERT INTO guacamole_connection (connection_name, protocol) VALUES ('<replaceable>test</replaceable>', '<replaceable>vnc</replaceable>');
-- Determine the connection_id
SELECT * FROM guacamole_connection WHERE connection_name = '<replaceable>test</replaceable>' AND parent_id IS NULL;
-- Add parameters to the new connection
INSERT INTO guacamole_connection_parameter VALUES (<replaceable>1</replaceable>, 'hostname', '<replaceable>localhost</replaceable>');
INSERT INTO guacamole_connection_parameter VALUES (<replaceable>1</replaceable>, 'port', '<replaceable>5901</replaceable>');</programlisting>
</informalexample>
<section xml:id="jdbc-auth-schema-connection-history">
<title>Usage history</title>
<indexterm>
<primary><classname>guacamole_connection_history</classname></primary>
</indexterm>
<para>When a connection is initiated or terminated, a corresponding entry in the
<classname>guacamole_connection_history</classname> table is created or
updated respectively. Each entry is associated with the user using the
connection, the connection itself, the <link
linkend="jdbc-auth-schema-sharing-profiles">sharing profile</link> in use
(if the connection is being shared), and the time the connection started. If the
connection has ended, the end time is also stored.</para>
<para>It is very unlikely that a user will need to update this table, but knowing
the structure is potentially useful if you wish to generate a report of
Guacamole usage. The <classname>guacamole_connection_history</classname> table
has the following columns:</para>
<variablelist>
<varlistentry>
<term><property>history_id</property></term>
<listitem>
<para>The unique integer associated with each history record. This value
is generated automatically when a new entry is inserted into the
<classname>guacamole_connection_history</classname>
table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>user_id</property></term>
<listitem>
<para>The value of the <property>user_id</property> from the entry in
<classname>guacamole_user</classname> associated with the user
using the connection. If the user no longer exists, this will be
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>username</property></term>
<listitem>
<para>The username associated with the user at the time that they used
the connection. This username value is not guaranteed to uniquely
identify a user, as the original user may be subsequently renamed or
deleted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_id</property></term>
<listitem>
<para>The value of the <property>connection_id</property> from the entry
in <classname>guacamole_connection</classname> associated the
connection being used. If the connection associated with the history
record no longer exists, this will be
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_name</property></term>
<listitem>
<para>The name associated with the connection at the time that it was
used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>sharing_profile_id</property></term>
<listitem>
<para>The value of the <property>sharing_profile_id</property> from the
entry in <classname>guacamole_sharing_profile</classname> associated
the sharing profile being used to access the connection. If the
connection is not being shared (no sharing profile is being used),
or if the sharing profile associated with the history record no
longer exists, this will be <constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>sharing_profile_name</property></term>
<listitem>
<para>The name associated with the sharing profile being used to access
the connection at the time this history entry was recorded. If the
connection is not being shared, this will be
<constant>NULL</constant>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>start_date</property></term>
<listitem>
<para>The time at which the connection was started by the user
specified. Despite its name, this column also stores time
information in addition to the date.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>end_date</property></term>
<listitem>
<para>The time at which the connection ended. If the connection is still
active, the value in this column will be <constant>NULL</constant>.
Despite its name, this column also stores time information in
addition to the date.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="jdbc-auth-schema-sharing-profiles">
<title>Sharing profiles and parameters</title>
<indexterm>
<primary><classname>guacamole_sharing_profile</classname></primary>
</indexterm>
<indexterm>
<primary><classname>guacamole_sharing_profile_parameter</classname></primary>
</indexterm>
<para>Each sharing profile has an entry in the
<classname>guacamole_sharing_profile</classname> table, with a one-to-many
relationship to parameters, stored as name/value pairs in the
<classname>guacamole_sharing_profile_parameter</classname> table.</para>
<para>The <classname>guacamole_sharing_profile</classname> table is simply a pairing of
a unique and descriptive name with the connection that can be shared using the
sharing profile, also known as the "primary connection". It contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>sharing_profile_id</property></term>
<listitem>
<para>The unique integer associated with each sharing profile. This value is
generated automatically when a new entry is inserted into the
<classname>guacamole_sharing_profile</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>sharing_profile_name</property></term>
<listitem>
<para>The unique name associated with each sharing profile. This value must
be specified manually, and must be different from any existing sharing
profile name associated with the same primary connection. References to
sharing profiles in other tables use the value from
<property>sharing_profile_id</property>, not
<property>sharing_profile_name</property>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>primary_connection_id</property></term>
<listitem>
<para>The unique integer associated with the primary connection. The
"primary connection" is the connection which can be shared using this
sharing profile.</para>
</listitem>
</varlistentry>
</variablelist>
<para>As there are potentially multiple parameters per sharing profile, where the names
of each parameter are completely arbitrary and determined only by the protocol
associated with the primary connection, every parameter for a given sharing profile
has an entry in the <classname>guacamole_sharing_profile_parameter</classname> table
associated with its corresponding sharing profile. This table contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>sharing_profile_id</property></term>
<listitem>
<para>The <property>sharing_profile_id</property> value from the entry in
the <classname>guacamole_sharing_profile</classname> table for the
sharing profile this parameter applies to.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parameter_name</property></term>
<listitem>
<para>The name of the parameter to set. This is the name listed in the
documentation for the protocol of the primary connection of the
associated sharing profile.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parameter_value</property></term>
<listitem>
<para>The value to assign to the parameter named. While this value is an
arbitrary string, it must conform to the requirements of the protocol as
documented.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-connection-groups">
<title>Connection groups</title>
<indexterm>
<primary><classname>guacamole_connection_group</classname></primary>
</indexterm>
<para>Each connection group has an entry in the
<classname>guacamole_connection_group</classname> table, with a one-to-many
relationship to other groups and connections.</para>
<para>The <classname>guacamole_connection_group</classname> table is simply a pairing of
a unique and descriptive name with a group type, which can be either
<type>ORGANIZATIONAL</type> or <type>BALANCING</type>. It contains the following
columns:</para>
<variablelist>
<varlistentry>
<term><property>connection_group_id</property></term>
<listitem>
<para>The unique integer associated with each connection group. This value
is generated automatically when a new entry is inserted into the
<classname>guacamole_connection_group</classname> table.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_group_name</property></term>
<listitem>
<para>The unique name associated with each connection group. This value must
be specified manually, and must be different from any existing
connection group name in the same connection group. References to
connections in other tables use the value from
<property>connection_group_id</property>, not
<property>connection_group_name</property>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>type</property></term>
<listitem>
<para>The type of this connection group. This can be either
<type>ORGANIZATIONAL</type> or <type>BALANCING</type>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>parent_id</property></term>
<listitem>
<para>The unique integer associated with the connection group containing
this connection group, or <constant>NULL</constant> if this connection
group is within the root group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>max_connections</property></term>
<listitem>
<para>The maximum number of concurrent connections to allow to this
connection group at any one time <emphasis>regardless of
user</emphasis>. <constant>NULL</constant> will use the default value
specified in <filename>guacamole.properties</filename> with the
<property>mysql-default-max-connections</property> or
<property>postgresql-default-max-connections</property> properties,
and a value of <constant>0</constant> denotes unlimited. This only has
an effect on <type>BALANCING</type> groups.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>max_connections_per_user</property></term>
<listitem>
<para>The maximum number of concurrent connections to allow to this
connection group at any one time <emphasis>from a single
user</emphasis>. <constant>NULL</constant> will use the default value
specified in <filename>guacamole.properties</filename> with the
<property>mysql-default-max-connections</property> or
<property>postgresql-default-max-connections</property> properties,
and a value of <constant>0</constant> denotes unlimited. This only has
an effect on <type>BALANCING</type> groups.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>enable_session_affinity</property></term>
<listitem>
<para>Whether session affinity should apply to this connection group. If
this column is set to <constant>TRUE</constant> or
<constant>1</constant>, users will be consistently routed to the
same underlying connection until they log out. The normal balancing
behavior will only apply for each user's first connection attempt during
any one Guacamole session. By default, session affinity is not enabled,
and connections will always be balanced across the entire connection
group. This only has an effect on <type>BALANCING</type> groups.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Adding a connection group is even simpler than adding a new connection as there
are no associated parameters stored in a separate table:</para>
<informalexample>
<programlisting>-- Create connection group
INSERT INTO guacamole_connection_group (connection_group_name, type)
VALUES ('<replaceable>test</replaceable>', '<replaceable>ORGANIZATIONAL</replaceable>');</programlisting>
</informalexample>
</section>
<section xml:id="jdbc-auth-schema-permissions">
<title>Permissions</title>
<para>There are several permissions tables in the schema which correspond to the types
of permissions in Guacamole's authentication model: system permissions, which
control operations that affect the system as a whole, and permissions which control
operations that affect specific objects within the system, such as users,
connections, or groups.</para>
<section xml:id="jdbc-auth-schema-system-permissions">
<title>lSystem permissions</title>
<indexterm>
<primary><classname>guacamole_system_permission</classname></primary>
</indexterm>
<para>System permissions are defined by entries in the
<classname>guacamole_system_permission</classname> table. Each entry grants
permission for a specific user or user group to perform a specific system
operation.</para>
<para>The <classname>guacamole_system_permission</classname> table contains the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of six
possible values: <constant>ADMINISTER</constant>, which grants the
ability to administer the entire system (essentially a wildcard
permission), <constant>CREATE_CONNECTION</constant>, which grants
the ability to create connections,
<constant>CREATE_CONNECTION_GROUP</constant>, which grants the
ability to create connections groups,
<constant>CREATE_SHARING_PROFILE</constant>, which grants the
ability to create sharing profiles,
<constant>CREATE_USER</constant>, which grants the ability to create
users, or <constant>CREATE_USER_GROUP</constant>, which grants the
ability to create user groups.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-user-permissions">
<title>User permissions</title>
<indexterm>
<primary><classname>guacamole_user_permission</classname></primary>
</indexterm>
<para>User permissions are defined by entries in the
<classname>guacamole_user_permission</classname> table. Each entry grants
permission for a specific user or user group to perform a specific operation on
an existing user.</para>
<para>The <classname>guacamole_user_permission</classname> table contains the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>affected_user_id</property></term>
<listitem>
<para>The value of the <property>user_id</property> column of the entry
associated with the user <emphasis>affected</emphasis> by this
permission. This is the user that would be the object of the
operation represented by this permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of four
possible values: <constant>ADMINISTER</constant>, which grants the
ability to add or remove permissions which affect the user,
<constant>READ</constant>, which grants the ability to read data
associated with the user, <constant>UPDATE</constant>, which grants
the ability to update data associated with the user, or
<constant>DELETE</constant>, which grants the ability to delete
the user.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-group-permissions">
<title>User group permissions</title>
<indexterm>
<primary><classname>guacamole_user_group_permission</classname></primary>
</indexterm>
<para>User group permissions are defined by entries in the
<classname>guacamole_user_group_permission</classname> table. Each entry
grants permission for a specific user or user group to perform a specific
operation on an existing user group.</para>
<para>The <classname>guacamole_user_group_permission</classname> table contains the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>affected_user_group_id</property></term>
<listitem>
<para>The value of the <property>user_group_id</property> column of the
entry associated with the user group <emphasis>affected</emphasis>
by this permission. This is the user group that would be the object
of the operation represented by this permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of four
possible values: <constant>ADMINISTER</constant>, which grants the
ability to add or remove permissions which affect the user group,
<constant>READ</constant>, which grants the ability to read data
associated with the user group, <constant>UPDATE</constant>, which
grants the ability to update data associated with the user group, or
<constant>DELETE</constant>, which grants the ability to delete
the user group.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-connection-permissions">
<title>Connection permissions</title>
<indexterm>
<primary><classname>guacamole_connection_permission</classname></primary>
</indexterm>
<para>Connection permissions are defined by entries in the
<classname>guacamole_connection_permission</classname> table. Each entry
grants permission for a specific user or user group to perform a specific
operation on an existing connection.</para>
<para>The <classname>guacamole_connection_permission</classname> table contains the
following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_id</property></term>
<listitem>
<para>The value of the <property>connection_id</property> column of the
entry associated with the connection affected by this permission.
This is the connection that would be the object of the operation
represented by this permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of four
possible values: <constant>ADMINISTER</constant>, which grants the
ability to add or remove permissions which affect the connection,
<constant>READ</constant>, which grants the ability to read data
associated with the connection (a prerequisite for connecting),
<constant>UPDATE</constant>, which grants the ability to update
data associated with the connection, or <constant>DELETE</constant>,
which grants the ability to delete the connection.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-sharing-profile-permissions">
<title>Sharing profile permissions</title>
<indexterm>
<primary><classname>guacamole_sharing_profile_permission</classname></primary>
</indexterm>
<para>Sharing profile permissions are defined by entries in the
<classname>guacamole_sharing_profile_permission</classname> table. Each
entry grants permission for a specific user or user group to perform a specific
operation on an existing sharing profile.</para>
<para>The <classname>guacamole_sharing_profile_permission</classname> table contains
the following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>sharing_profile_id</property></term>
<listitem>
<para>The value of the <property>sharing_profile_id</property> column of
the entry associated with the sharing profile affected by this
permission. This is the sharing profile that would be the object of
the operation represented by this permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of four
possible values: <constant>ADMINISTER</constant>, which grants the
ability to add or remove permissions which affect the sharing
profile, <constant>READ</constant>, which grants the ability to read
data associated with the sharing profile (a prerequisite for using
the sharing profile to share an active connection),
<constant>UPDATE</constant>, which grants the ability to update
data associated with the sharing profile, or
<constant>DELETE</constant>, which grants the ability to delete
the sharing profile.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="jdbc-auth-schema-connection-group-permissions">
<title>Connection group permissions</title>
<indexterm>
<primary><classname>guacamole_connection_group_permission</classname></primary>
</indexterm>
<para>Connection group permissions are defined by entries in the
<classname>guacamole_connection_group_permission</classname> table. Each
entry grants permission for a specific user or user group to perform a specific
operation on an existing connection group.</para>
<para>The <classname>guacamole_connection_group_permission</classname> table
contains the following columns:</para>
<variablelist>
<varlistentry>
<term><property>entity_id</property></term>
<listitem>
<para>The value of the <property>entity_id</property> column of the
entry associated with the user or user group owning this
permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>connection_group_id</property></term>
<listitem>
<para>The value of the <property>connection_group_id</property> column
of the entry associated with the connection group affected by this
permission. This is the connection group that would be the object of
the operation represented by this permission.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>permission</property></term>
<listitem>
<para>The permission being granted. This column can have one of four
possible values: <constant>ADMINISTER</constant>, which grants the
ability to add or remove permissions which affect the connection
group, <constant>READ</constant>, which grants the ability to read
data associated with the connection group,
<constant>UPDATE</constant>, which grants the ability to update
data associated with the connection group, or
<constant>DELETE</constant>, which grants the ability to delete
the connection group (and implicitly its contents).</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</section>
</chapter>