| <?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 and user groups from other authentication |
| extensions to be associated with connections within the database. Users and groups are |
| considered identical to those within the database if they have the same names, 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.2.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.2.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.2.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.2.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.2.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.2.0.jar</filename> |
| <emphasis>or</emphasis> |
| <filename>guacamole-auth-jdbc-postgresql-1.2.0.jar</filename> |
| <emphasis>or</emphasis> |
| <filename>guacamole-auth-jdbc-sqlserver-1.2.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>With respect to password content, the database authentication defines a |
| "digit" as any numeric character and a "symbol" is any non-alphanumeric |
| character. This takes non-English languages into account, thus a digit is |
| not simply "0" through "9" but rather <link |
| xlink:href="https://en.wikipedia.org/wiki/Numerals_in_Unicode">any |
| character defined in Unicode as numeric</link>, and a symbol is 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>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 usable |
| again).</para> |
| <para>By default, the database authentication does not apply any limits to |
| password age, and users with permission to change their passwords may do so |
| as frequently or infrequently as they wish. Password age limits can be |
| enabled using a pair of properties, each accepting values given in units of |
| days:</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> |
| <important> |
| <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> |
| </important> |
| </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> |