| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 6. Database authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole" /><link rel="next" href="ldap-auth.html" title="Chapter 7. LDAP authentication" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Database authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configuring-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="ldap-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="jdbc-auth"></a>Chapter 6. Database authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="jdbc-auth.html#idm46420848531088">Downloading the database authentication extension</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-database-creation">Creating the Guacamole database</a></span></dt><dd><dl><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-mysql">MySQL</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-postgresql">PostgreSQL</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-sqlserver">SQL Server</a></span></dt></dl></dd><dt><span class="section"><a href="jdbc-auth.html#idm46420849413472">Upgrading an existing Guacamole database</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#idm46420847663760">Granting Guacamole access to the database</a></span></dt><dd><dl><dt><span class="section"><a href="jdbc-auth.html#idm46420847659008">MySQL</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#idm46420847248864">PostgreSQL</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#idm46420848090912">SQL Server</a></span></dt></dl></dd><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-installation">Installing database authentication</a></span></dt><dd><dl><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-configuration">Configuring Guacamole for database authentication</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-restrict">Restricting authentication to database users only</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#idm46420848067232">Completing the installation</a></span></dt></dl></dd><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-default-user">Logging in</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema">Modifying data manually</a></span></dt><dd><dl><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-entities">Entities</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-users">Users</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-groups">User groups</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-connections">Connections and parameters</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-sharing-profiles">Sharing profiles and parameters</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-connection-groups">Connection groups</a></span></dt><dt><span class="section"><a href="jdbc-auth.html#jdbc-auth-schema-permissions">Permissions</a></span></dt></dl></dd></dl></div><a id="idm46420848123776" class="indexterm"></a><a id="idm46420848122880" class="indexterm"></a><a id="idm46420848121984" class="indexterm"></a><p>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.</p><p>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 <a class="xref" href="ldap-auth.html#ldap-and-database" title="Associating LDAP with a database">the section called “Associating LDAP with a database”</a> within <a class="xref" href="ldap-auth.html" title="Chapter 7. LDAP authentication">Chapter 7, <em>LDAP authentication</em></a>.</p><p>To use the database authentication extension, you will need:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A supported database - currently MariaDB, MySQL, PostgreSQL, or SQL Server.</p></li><li class="listitem"><p>Sufficient permission to create new databases, to create new users, and to grant |
| those users permissions.</p></li><li class="listitem"><p>Network access to the database from the Guacamole server.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>This chapter involves modifying the contents of <code class="varname">GUACAMOLE_HOME</code> - |
| the Guacamole configuration directory. If you are unsure where |
| <code class="varname">GUACAMOLE_HOME</code> is located on your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before proceeding.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm46420848531088"></a>Downloading the database authentication extension</h2></div></div></div><p>The database authentication extension is available separately from the main |
| <code class="filename">guacamole.war</code>. 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: <a class="link" href="http://guacamole.apache.org/releases/" target="_top">http://guacamole.apache.org/releases/</a>.</p><p>The database authentication extension is packaged as a <code class="filename">.tar.gz</code> |
| file containing:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">mysql/</code></span></dt><dd><p>Contains the MySQL/MariaDB authentication extension, |
| <code class="filename">guacamole-auth-jdbc-mysql-1.1.0.jar</code>, along with a |
| <code class="filename">schema/</code> directory containing MySQL-specific SQL |
| scripts required to set up the database. The |
| <code class="filename">guacamole-auth-jdbc-mysql-1.1.0.jar</code> file will |
| ultimately need to be placed within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>, while the MySQL JDBC |
| driver must be placed within <code class="filename">GUACAMOLE_HOME/lib</code>.</p><p><span class="emphasis"><em>The MySQL JDBC driver is not included with the |
| extension.</em></span> You must obtain the JDBC driver |
| <code class="filename">.jar</code> yourself from <a class="link" href="http://dev.mysql.com/downloads/connector/j/" target="_top">MySQL's |
| website</a>. The driver is known as "Connector/J", and the required |
| <code class="filename">.jar</code> will be within a <code class="filename">.tar.gz</code> |
| archive.</p></dd><dt><span class="term"><code class="filename">postgresql/</code></span></dt><dd><p>Contains the PostgreSQL authentication extension, |
| <code class="filename">guacamole-auth-jdbc-postgresql-1.1.0.jar</code>, along |
| with a <code class="filename">schema/</code> directory containing PostgreSQL-specific |
| SQL scripts required to set up the database. The |
| <code class="filename">guacamole-auth-jdbc-postgresql-1.1.0.jar</code> file will |
| ultimately need to be placed within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>, while the PostgreSQL |
| JDBC driver must be placed within |
| <code class="filename">GUACAMOLE_HOME/lib</code>.</p><p><span class="emphasis"><em>The PostgreSQL JDBC driver is not included with the |
| extension.</em></span> You must obtain the JDBC driver |
| <code class="filename">.jar</code> yourself from <a class="link" href="https://jdbc.postgresql.org/download.html#current" target="_top">PostgreSQL's website</a>. The proper <code class="filename">.jar</code> file |
| depends on the version of Java you have installed. </p></dd><dt><span class="term"><code class="filename">sqlserver/</code></span></dt><dd><p>Contains the SQL Server authentication extension, |
| <code class="filename">guacamole-auth-jdbc-sqlserver-1.1.0.jar</code>, along with |
| a <code class="filename">schema/</code> directory contains SQL Server-specific |
| scripts requires to set up the database. The JAR extension file will need to |
| be placed within the <code class="filename">GUACAMOLE_HOME/extensions</code> folder, |
| while the SQL Server JDBC driver must be placed within the |
| <code class="filename">GUACAMOLE_HOME/lib</code> directory.</p><p><span class="emphasis"><em>The SQL Server JDBC driver is not included with the extension.</em></span> You |
| must obtain the JDBC driver <code class="filename">.jar</code> 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 <code class="filename">.jar</code> is in the correct |
| directory. Microsoft's JDBC driver can be downloaded from Microsoft's <a class="link" href="https://docs.microsoft.com/en-us/sql/connect/sql-connection-libraries#anchor-20-drivers-relational-access" target="_top"> |
| SQL Connection Libraries</a> page.</p><p>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: |
| <span class="property">sqlserver-driver</span>. 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 <span class="property">sqlserver-driver</span> property: |
| </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">microsoft2005</span></dt><dd><p>The current Microsoft driver, supporting SQL Server 2005 and later.</p></dd><dt><span class="term">microsoft</span></dt><dd><p>The legacy SQL Server support.</p></dd><dt><span class="term">jtds</span></dt><dd><p>The open source JTDS driver.</p></dd><dt><span class="term">datadirect</span></dt><dd><p>The Progress Sybase driver.</p></dd></dl></div><p> |
| </p></dd></dl></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="jdbc-auth-database-creation"></a>Creating the Guacamole database</h2></div></div></div><p>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.</p><p>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.</p><p>For the sake of clarity, these instructions will refer to the database as |
| "guacamole_db", but the database can be named whatever you like.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-mysql"></a>MySQL</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ls schema/</code></strong> |
| <code class="computeroutput">001-create-schema.sql 002-create-admin-user.sql upgrade</code> |
| <code class="prompt">$</code> <strong class="userinput"><code>cat schema/*.sql | mysql -u root -p <em class="replaceable"><code>guacamole_db</code></em></code></strong> |
| <code class="prompt">Enter password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong> |
| <code class="prompt">$</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-postgresql"></a>PostgreSQL</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>createdb <em class="replaceable"><code>guacamole_db</code></em></code></strong> |
| <code class="prompt">$</code> <strong class="userinput"><code>ls schema/</code></strong> |
| <code class="computeroutput">001-create-schema.sql 002-create-admin-user.sql</code> |
| <code class="prompt">$</code> <strong class="userinput"><code>cat schema/*.sql | psql -d <em class="replaceable"><code>guacamole_db</code></em> -f -</code></strong> |
| <code class="computeroutput">CREATE TYPE |
| CREATE TYPE |
| CREATE TYPE |
| CREATE TABLE |
| CREATE INDEX</code> |
| ... |
| <code class="computeroutput">INSERT 0 1 |
| INSERT 0 4 |
| INSERT 0 3</code> |
| <code class="prompt">$</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-sqlserver"></a>SQL Server</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <em class="replaceable"><code>guacamole_db</code></em> -i schema/001-create-schema.sql</code></strong> |
| <code class="prompt">Password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong> |
| <code class="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.</code> |
| <code class="prompt">$</code> <strong class="userinput"><code>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -d <em class="replaceable"><code>guacamole_db</code></em> -i schema/002-create-admin-user.sql</code></strong> |
| <code class="prompt">Password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong> |
| <code class="computeroutput"> |
| (1 rows affected) |
| |
| (3 rows affected) |
| |
| (5 rows affected)</code> |
| </pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm46420849413472"></a>Upgrading an existing Guacamole database</h2></div></div></div><p>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 |
| <code class="filename">schema/upgrade/</code> directory. Each of these scripts is named |
| <code class="filename">upgrade-pre-<em class="replaceable"><code>VERSION</code></em>.sql</code> where |
| <em class="replaceable"><code>VERSION</code></em> 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 <em class="replaceable"><code>VERSION</code></em>.</p><p>If there are no |
| <code class="filename">upgrade-pre-<em class="replaceable"><code>VERSION</code></em>.sql</code> scripts |
| present in the <code class="filename">schema/upgrade/</code> 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.</p><p>These scripts are incremental and, when relevant, <span class="emphasis"><em>must be run in |
| order</em></span>. 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 |
| <code class="filename">upgrade-pre-0.9.14.sql</code> script (because 0.9.13-incubating is |
| older than 0.9.14), followed by the <code class="filename">upgrade-pre-1.0.0.sql</code> script |
| (because 0.9.13-incubating is also older than 1.0.0).</p><div class="important"><h3 class="title"><a id="jdbc-auth-postgresql-upgrade"></a>Important</h3><p>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:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>psql -d <em class="replaceable"><code>guacamole_db</code></em></code></strong> |
| <code class="computeroutput">psql (9.3.6) |
| Type "help" for help. |
| </code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="computeroutput">GRANT</code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="computeroutput">GRANT</code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>\q</code></strong> |
| <code class="prompt">$</code></pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idm46420847663760"></a>Granting Guacamole access to the database</h2></div></div></div><p>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 class="code">SELECT</code>, <code class="code">UPDATE</code>, <code class="code">INSERT</code>, and |
| <code class="code">DELETE</code> permissions on all Guacamole tables. Additionally, if using |
| PostgreSQL, the user will need <code class="code">SELECT</code> and <code class="code">USAGE</code> permission on |
| all sequences within all Guacamole tables. <span class="emphasis"><em>No other permissions should be |
| granted.</em></span></p><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420847659008"></a>MySQL</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> mysql -u root -p |
| <code class="prompt">Enter password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong> |
| <code class="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. |
| </code> |
| <code class="prompt">mysql></code> <strong class="userinput"><code>CREATE DATABASE <em class="replaceable"><code>guacamole_db</code></em>;</code></strong> |
| <code class="computeroutput">Query OK, 1 row affected (0.00 sec)</code> |
| |
| <code class="prompt">mysql></code> <strong class="userinput"><code>CREATE USER '<em class="replaceable"><code>guacamole_user'</code></em>@'localhost' IDENTIFIED BY '<em class="replaceable"><code>some_password</code></em>';</code></strong> |
| <code class="computeroutput">Query OK, 0 rows affected (0.00 sec)</code> |
| |
| <code class="prompt">mysql></code> <strong class="userinput"><code>GRANT SELECT,INSERT,UPDATE,DELETE ON <em class="replaceable"><code>guacamole_db</code></em>.* TO '<em class="replaceable"><code>guacamole_user'</code></em>@'localhost';</code></strong> |
| <code class="computeroutput">Query OK, 0 rows affected (0.00 sec)</code> |
| |
| <code class="prompt">mysql></code> <strong class="userinput"><code>FLUSH PRIVILEGES;</code></strong> |
| <code class="computeroutput">Query OK, 0 rows affected (0.02 sec)</code> |
| |
| <code class="prompt">mysql></code> <strong class="userinput"><code>quit</code></strong> |
| <code class="computeroutput">Bye</code> |
| <code class="prompt">$</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420847248864"></a>PostgreSQL</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>psql -d <em class="replaceable"><code>guacamole_db</code></em></code></strong> |
| <code class="computeroutput">psql (9.3.6) |
| Type "help" for help. |
| </code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>CREATE USER <em class="replaceable"><code>guacamole_user</code></em> WITH PASSWORD '<em class="replaceable"><code>some_password</code></em>';</code></strong> |
| <code class="computeroutput">CREATE ROLE</code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="computeroutput">GRANT</code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="computeroutput">GRANT</code> |
| <code class="prompt">guacamole=# </code><strong class="userinput"><code>\q</code></strong> |
| <code class="prompt">$</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420848090912"></a>SQL Server</h3></div></div></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>/opt/mssql-tools/bin/sqlcmd -S localhost -U SA</code></strong> |
| <code class="prompt">Password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong> |
| <code class="prompt">1></code> <strong class="userinput"><code>CREATE DATABASE <em class="replaceable"><code>guacamole_db</code></em>;</code></strong> |
| <code class="prompt">2></code> <strong class="userinput"><code>GO</code></strong> |
| <code class="prompt">1></code> <strong class="userinput"><code>CREATE LOGIN <em class="replaceable"><code>guacamole_user</code></em> WITH PASSWORD = '<em class="replaceable"><code>some_password</code></em>';</code></strong> |
| <code class="prompt">2></code> <strong class="userinput"><code>GO</code></strong> |
| <code class="prompt">1></code> <strong class="userinput"><code>USE <em class="replaceable"><code>guacamole_db</code></em>;</code></strong> |
| <code class="prompt">2></code> <strong class="userinput"><code>GO</code></strong> |
| <code class="prompt">1></code> <strong class="userinput"><code>CREATE USER <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="prompt">2></code> <strong class="userinput"><code>GO</code></strong> |
| <code class="prompt">1></code> <strong class="userinput"><code>ALTER ROLE db_datawriter ADD MEMBER <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="prompt">2></code> <strong class="userinput"><code>ALTER ROLE db_datareader ADD MEMBER <em class="replaceable"><code>guacamole_user</code></em>;</code></strong> |
| <code class="prompt">3></code> <strong class="userinput"><code>GO</code></strong></pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="jdbc-auth-installation"></a>Installing database authentication</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are |
| located within the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. To install |
| the database authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it |
| does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-jdbc-mysql-1.1.0.jar</code> |
| <span class="emphasis"><em>or</em></span> |
| <code class="filename">guacamole-auth-jdbc-postgresql-1.1.0.jar</code> |
| <span class="emphasis"><em>or</em></span> |
| <code class="filename">guacamole-auth-jdbc-sqlserver-1.1.0.jar</code> within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>, depending on whether you are |
| using MySQL/MariaDB, PostgreSQL, or SQL Server.</p></li><li class="step"><p>Copy the JDBC driver for your database to |
| <code class="filename">GUACAMOLE_HOME/lib</code>. Without a JDBC driver for your |
| database, Guacamole will not be able to connect and authenticate users.</p></li><li class="step"><p>Configure Guacamole to use database authentication, as described below.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-configuration"></a>Configuring Guacamole for database authentication</h3></div></div></div><p>Additional properties must be added to <code class="filename">guacamole.properties</code> |
| 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.</p><p>To use a MySQL database, you will need to specify the following:</p><div class="informalexample"><pre class="programlisting"># MySQL properties |
| mysql-hostname: localhost |
| mysql-port: 3306 |
| mysql-database: <em class="replaceable"><code>guacamole_db</code></em> |
| mysql-username: <em class="replaceable"><code>guacamole_user</code></em> |
| mysql-password: <em class="replaceable"><code>some_password</code></em> |
| </pre></div><p>For PostgreSQL, the properties are similar, but with different prefixes:</p><div class="informalexample"><pre class="programlisting"># PostgreSQL properties |
| postgresql-hostname: localhost |
| postgresql-port: 5432 |
| postgresql-database: <em class="replaceable"><code>guacamole_db</code></em> |
| postgresql-username: <em class="replaceable"><code>guacamole_user</code></em> |
| postgresql-password: <em class="replaceable"><code>some_password</code></em> |
| </pre></div><p>The SQL Server properties follow the same format:</p><div class="informalexample"><pre class="programlisting"># SQL Server properties |
| sqlserver-hostname: localhost |
| sqlserver-port: 1433 |
| sqlserver-database: <em class="replaceable"><code>guacamole_db</code></em> |
| sqlserver-username: <em class="replaceable"><code>guacamole_user</code></em> |
| sqlserver-password: <em class="replaceable"><code>some_password</code></em> |
| sqlserver-driver: microsoft2005 |
| </pre></div><p>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:</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col class="c1" /><col class="c2" /><col class="c3" /><col class="c4" /></colgroup><thead><tr><th>MySQL/MariaDB Property</th><th>PostgreSQL Property</th><th>SQL Server Property</th><th>Description</th></tr></thead><tbody><tr><td><span class="property">mysql-hostname</span></td><td><span class="property">postgresql-hostname</span></td><td><span class="property">sqlserver-hostname</span></td><td> |
| <p>The hostname or IP address of the server hosting your |
| database.</p> |
| </td></tr><tr><td><span class="property">mysql-port</span></td><td><span class="property">postgresql-port</span></td><td><span class="property">sqlserver-port</span></td><td> |
| <p>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.</p> |
| </td></tr><tr><td><span class="property">mysql-database</span></td><td><span class="property">postgresql-database</span></td><td><span class="property">sqlserver-database</span></td><td> |
| <p>The name of the database that you created for Guacamole. This |
| is given as "guacamole_db" in the examples given in this |
| chapter.</p> |
| </td></tr><tr><td><span class="property">mysql-username</span></td><td><span class="property">postgresql-username</span></td><td><span class="property">sqlserver-username</span></td><td> |
| <p>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.</p> |
| </td></tr><tr><td><span class="property">mysql-password</span></td><td><span class="property">postgresql-password</span></td><td><span class="property">sqlserver-password</span></td><td> |
| <p>The password Guacamole should provide when authenticating with |
| the database. This is given as "some_password" in the examples |
| given in this chapter.</p> |
| </td></tr></tbody></table></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm46420847149552"></a>Enforcing password policies</h4></div></div></div><p>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 <code class="filename">guacamole.properties</code>.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="idm46420847147616"></a>Password complexity</h5></div></div></div><p>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.</p><p>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 <a class="link" href="https://en.wikipedia.org/wiki/Numerals_in_Unicode" target="_top">any |
| character defined in Unicode as numeric</a>, and a symbol is any |
| character which Unicode does not define as alphabetic or numeric.</p><p>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.</p><div class="informalexample"><pre class="programlisting"># MySQL |
| mysql-user-password-min-length: <em class="replaceable"><code>8</code></em> |
| 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: <em class="replaceable"><code>8</code></em> |
| 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: <em class="replaceable"><code>8</code></em> |
| 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</pre></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="idm46420847140976"></a>Password age / expiration</h5></div></div></div><p>"Password age" refers to two separate concepts:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Requiring users to change their password after a certain amount of |
| time has elapsed since the last password change (maximum password |
| age).</p></li><li class="listitem"><p>Preventing users from changing their password too frequently |
| (minimum password age).</p></li></ol></div><p>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).</p><p>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:</p><div class="informalexample"><pre class="programlisting"># MySQL |
| mysql-user-password-min-age: <em class="replaceable"><code>7</code></em> |
| mysql-user-password-max-age: <em class="replaceable"><code>90</code></em> |
| |
| # PostgreSQL |
| postgresql-user-password-min-age: <em class="replaceable"><code>7</code></em> |
| postgresql-user-password-max-age: <em class="replaceable"><code>90</code></em> |
| |
| # SQL Server |
| sqlserver-user-password-min-age: <em class="replaceable"><code>7</code></em> |
| sqlserver-user-password-max-age: <em class="replaceable"><code>90</code></em></pre></div><div class="important"><h3 class="title">Important</h3><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="idm46420847458864"></a>Preventing password reuse</h5></div></div></div><p>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.</p><p>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.</p><div class="informalexample"><pre class="programlisting"># MySQL |
| mysql-user-password-history-size: <em class="replaceable"><code>6</code></em> |
| |
| # PostgreSQL |
| postgresql-user-password-history-size: <em class="replaceable"><code>6</code></em> |
| |
| # SQL Server |
| sqlserver-user-password-history-size: <em class="replaceable"><code>6</code></em></pre></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-concurrency"></a>Concurrent use of Guacamole connections</h4></div></div></div><p>The database authentication module provides configuration options to restrict |
| concurrent use of connections or connection groups. These options are set |
| through <code class="filename">guacamole.properties</code> 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:</p><div class="informalexample"><pre class="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</pre></div><p>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.</p><p>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 <code class="filename">guacamole.properties</code> or |
| the per-connection settings exposed in the administrative interface:</p><div class="informalexample"><pre class="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</pre></div><p>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:</p><div class="informalexample"><pre class="programlisting"># MySQL |
| mysql-absolute-max-connections: 0 |
| |
| # PostgreSQL |
| postgresql-absolute-max-connections: 0 |
| |
| # SQL Server |
| sqlserver-absolute-max-connections: 0</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-restrict"></a>Restricting authentication to database users only</h3></div></div></div><p>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.</p><p>In some situations, such as when <a class="link" href="ldap-auth.html#ldap-and-database" title="Associating LDAP with a database">combining LDAP |
| with a database</a>, 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:</p><div class="informalexample"><pre class="programlisting"># MySQL |
| mysql-user-required: true |
| |
| # PostgreSQL |
| postgresql-user-required: true |
| |
| # SQL Server |
| sqlserver-user-required: true</pre></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420848067232"></a>Completing the installation</h3></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> 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.</p><p> |
| </p><div class="important"><h3 class="title">Important</h3><p>You only need to restart your servlet container. <span class="emphasis"><em>You do not need |
| to restart <span class="package">guacd</span></em></span>.</p><p><span class="package">guacd</span> is completely independent of the web application |
| and does not deal with <code class="filename">guacamole.properties</code> or the |
| authentication system in any way. Since you are already restarting the |
| servlet container, restarting <span class="package">guacd</span> as well technically |
| won't hurt anything, but doing so is completely pointless.</p></div><p> |
| </p><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="jdbc-auth-default-user"></a>Logging in</h2></div></div></div><a id="idm46420848059040" class="indexterm"></a><a id="idm46420848058144" class="indexterm"></a><p>The default Guacamole user created by the provided SQL scripts is |
| "<code class="systemitem">guacadmin</code>", with a default password of |
| "<code class="systemitem">guacadmin</code>". Once you have verified that the database |
| authentication is working, <span class="emphasis"><em>you should change your password |
| immediately</em></span>.</p><p>More detailed instructions for managing users and connections is given in <a class="xref" href="administration.html" title="Chapter 16. Administration">Chapter 16, <em>Administration</em></a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="jdbc-auth-schema"></a>Modifying data manually</h2></div></div></div><a id="idm46420848052880" class="indexterm"></a><p>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.</p><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-entities"></a>Entities</h3></div></div></div><a id="idm46420848169472" class="indexterm"></a><p>Every user and user group has a corresponding entry in the |
| <code class="classname">guacamole_entity</code> 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.</p><p>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, <span class="emphasis"><em>it is advisable to use |
| the entity as the basis for any delete operation</em></span>.</p><p>The <code class="classname">guacamole_entity</code> table contains the following |
| columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The unique integer associated with each entity (user or user group). |
| This value is generated automatically when a new entry is inserted into |
| the <code class="classname">guacamole_entity</code> table and is distinct from |
| the unique integer associated with the user entry in <a class="link" href="jdbc-auth.html#jdbc-auth-schema-users" title="Users"><code class="classname">guacamole_user</code></a> or the user group |
| entry in <a class="link" href="jdbc-auth.html#jdbc-auth-schema-groups" title="User groups"><code class="classname">guacamole_user_group</code></a>.</p></dd><dt><span class="term"><span class="property">name</span></span></dt><dd><p>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).</p></dd><dt><span class="term"><span class="property">type</span></span></dt><dd><p>The type of this entity. This can be either <span class="type">USER</span> or |
| <span class="type">USER_GROUP</span>.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-users"></a>Users</h3></div></div></div><a id="idm46420848154192" class="indexterm"></a><p>Every user has a corresponding entry in the <code class="classname">guacamole_user</code> |
| and <a class="link" href="jdbc-auth.html#jdbc-auth-schema-entities" title="Entities"><code class="classname">guacamole_entity</code></a> tables. Each user has a |
| corresponding unique username, specified via |
| <code class="classname">guacamole_entity</code>, 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.</p><p>If deleting a user, the <a class="link" href="jdbc-auth.html#jdbc-auth-schema-entities" title="Entities">corresponding |
| entity</a> should also be deleted. As any user which points to the entity |
| will be deleted automatically when the entity is deleted through cascading deletion, |
| <span class="emphasis"><em>it is advisable to use the entity as the basis for any delete |
| operation</em></span>.</p><p>The <code class="classname">guacamole_user</code> table contains the following |
| columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">user_id</span></span></dt><dd><p>The unique integer associated with each user. This value is generated |
| automatically when a new entry is inserted into the |
| <code class="classname">guacamole_user</code> table.</p></dd><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| <code class="classname">guacamole_entity</code> entry representing this |
| user.</p></dd><dt><span class="term"><span class="property">password_hash</span></span></dt><dd><p>The result of hashing the user's password concatenated with the |
| contents of <span class="property">password_salt</span> using SHA-256. The salt |
| is appended to the password prior to hashing.</p><p>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 <span class="property">password_salt</span> is |
| <code class="constant">NULL</code>, the <span class="property">password_hash</span> |
| will be handled as a simple unsalted hash of the password.</p></dd><dt><span class="term"><span class="property">password_salt</span></span></dt><dd><p>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.</p><p>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 |
| <span class="property">password_salt</span> is <code class="constant">NULL</code>, the |
| <span class="property">password_hash</span> will be handled as a simple |
| unsalted hash of the password.</p></dd><dt><span class="term"><span class="property">password_date</span></span></dt><dd><p>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 |
| <code class="classname">guacamole_user_password_history</code> table, is |
| used to enforce password policies.</p></dd><dt><span class="term"><span class="property">disabled</span></span></dt><dd><p>Whether login attempts as this user account should be rejected. If |
| this column is set to <code class="constant">TRUE</code> or |
| <code class="constant">1</code>, 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.</p></dd><dt><span class="term"><span class="property">expired</span></span></dt><dd><p>If set to <code class="constant">TRUE</code> or <code class="constant">1</code>, |
| 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.</p></dd><dt><span class="term"><span class="property">access_window_start</span></span></dt><dd><p>The time of day (not date) after which this user account may be used. |
| If <code class="constant">NULL</code>, this restriction does not apply. If set to |
| non-<code class="constant">NULL</code>, attempts to log in after the |
| specified time will be allowed, while attempts to log in before the |
| specified time will be denied.</p></dd><dt><span class="term"><span class="property">access_window_end</span></span></dt><dd><p>The time of day (not date) after which this user account may |
| <span class="emphasis"><em>not</em></span> be used. If <code class="constant">NULL</code>, this |
| restriction does not apply. If set to non-<code class="constant">NULL</code>, |
| attempts to log in after the specified time will be denied, while |
| attempts to log in before the specified time will be allowed.</p></dd><dt><span class="term"><span class="property">valid_from</span></span></dt><dd><p>The date (not time of day) after which this user account may be used. |
| If <code class="constant">NULL</code>, this restriction does not apply. If set to |
| non-<code class="constant">NULL</code>, attempts to log in after the |
| specified date will be allowed, while attempts to log in before the |
| specified date will be denied.</p></dd><dt><span class="term"><span class="property">valid_until</span></span></dt><dd><p>The date (not time of day) after which this user account may |
| <span class="emphasis"><em>not</em></span> be used. If <code class="constant">NULL</code>, this |
| restriction does not apply. If set to non-<code class="constant">NULL</code>, |
| attempts to log in after the specified date will be denied, while |
| attempts to log in before the specified date will be allowed.</p></dd><dt><span class="term"><span class="property">timezone</span></span></dt><dd><p>The time zone to use when interpreting the |
| <span class="property">access_window_start</span>, |
| <span class="property">access_window_end</span>, |
| <span class="property">valid_from</span>, and |
| <span class="property">valid_until</span> values. This value may be any Java |
| <code class="classname">TimeZone</code> ID, as defined by <a class="link" href="http://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs()" target="_top"><code class="methodname">getAvailableIDs()</code></a>, though the |
| Guacamole management interface will only present a subset of these time |
| zones.</p></dd><dt><span class="term"><span class="property">full_name</span></span></dt><dd><p>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 <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">email_address</span></span></dt><dd><p>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 |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">organization</span></span></dt><dd><p>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 |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">organizational_role</span></span></dt><dd><p>The role or title of the user at the organization described by the |
| <span class="property">organization</span> 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 <code class="constant">NULL</code>.</p></dd></dl></div><div class="important"><h3 class="title">Important</h3><p>If you choose to manually set unsalted password hashes, please be sure you |
| understand the security implications of doing so.</p><p>In the event that your database is compromised, finding the password for a |
| <span class="emphasis"><em>salted</em></span> hash is computationally infeasible, but finding |
| the password for an <span class="emphasis"><em>unsalted</em></span> 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.</p></div><p>If creating a user manually, the main complication is the salt, which must be |
| determined before the <span class="command"><strong>INSERT</strong></span> statement can be constructed, but |
| this can be dealt with using variables. For MySQL:</p><div class="informalexample"><pre class="programlisting">-- Generate salt |
| SET @salt = UNHEX(SHA2(UUID(), 256)); |
| |
| -- Create base entity entry for user |
| INSERT INTO guacamole_entity (name, type) |
| VALUES ('<em class="replaceable"><code>myuser</code></em>', '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('<em class="replaceable"><code>mypassword</code></em>', HEX(@salt)), 256)), |
| CURRENT_TIMESTAMP |
| FROM guacamole_entity |
| WHERE |
| name = '<em class="replaceable"><code>myuser</code></em>' |
| AND type = 'USER';</pre></div><p>This sort of statement is useful for both creating new users or for changing |
| passwords, especially if all administrators have forgotten theirs.</p><p>If you are not using MySQL, or you are using a version of MySQL that lacks the |
| <code class="methodname">SHA2</code> function, you will need to calculate the SHA-256 |
| value manually (by using the <span class="command"><strong>sha256sum</strong></span> command, for |
| example).</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-password-history"></a>Password history</h4></div></div></div><a id="idm46420848519264" class="indexterm"></a><p>When a user's password is changed, a copy of the previous password's hash and |
| salt is made within the <code class="classname">guacamole_user_password_history</code>. |
| Each entry in this table is associated with the user whose password changed, |
| along with the date that password first applied.</p><p>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.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">password_history_id</span></span></dt><dd><p>The unique integer associated with each password history record. |
| This value is generated automatically when a new entry is inserted |
| into the <code class="classname">guacamole_user_password_history</code> |
| table.</p></dd><dt><span class="term"><span class="property">user_id</span></span></dt><dd><p>The value of the <span class="property">user_id</span> column from the |
| entry in <code class="classname">guacamole_user</code> associated with the |
| user who previously had this password.</p></dd><dt><span class="term"><span class="property">password_hash</span></span></dt><dd><p>The hashed password specified within the |
| <span class="property">password_hash</span> column of |
| <code class="classname">guacamole_user</code> prior to the password |
| being changed.</p><p>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.</p></dd><dt><span class="term"><span class="property">password_salt</span></span></dt><dd><p>The salt value specified within the |
| <span class="property">password_salt</span> column of |
| <code class="classname">guacamole_user</code> prior to the password |
| being changed.</p><p>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 <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">password_date</span></span></dt><dd><p>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 |
| <code class="classname">guacamole_user_password_history</code> or |
| <span class="property">password_date</span> of |
| <code class="classname">guacamole_user</code> (if there is no such |
| history entry).</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-login-history"></a>Login history</h4></div></div></div><a id="idm46420848325632" class="indexterm"></a><p>When a user logs in or out, a corresponding entry in the |
| <code class="classname">guacamole_user_history</code> 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.</p><p>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 <code class="classname">guacamole_user_history</code> table has the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">history_id</span></span></dt><dd><p>The unique integer associated with each history record. This value |
| is generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_user_history</code> table.</p></dd><dt><span class="term"><span class="property">user_id</span></span></dt><dd><p>The value of the <span class="property">user_id</span> from the entry in |
| <code class="classname">guacamole_user</code> associated with the user |
| that logged in. If the user no longer exists, this will be |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">username</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">remote_host</span></span></dt><dd><p>The hostname or IP address of the machine that the user logged in |
| from, if known. If unknown, this will be |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">start_date</span></span></dt><dd><p>The time at which the user logged in. Despite its name, this |
| column also stores time information in addition to the date.</p></dd><dt><span class="term"><span class="property">end_date</span></span></dt><dd><p>The time at which the user logged out. If the user is still |
| active, the value in this column will be <code class="constant">NULL</code>. |
| Despite its name, this column also stores time information in |
| addition to the date.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-groups"></a>User groups</h3></div></div></div><a id="idm46420847186848" class="indexterm"></a><p>Similar to <a class="link" href="jdbc-auth.html#jdbc-auth-schema-users" title="Users">users</a>, every user group |
| has a corresponding entry in the <code class="classname">guacamole_user_group</code> and |
| <a class="link" href="jdbc-auth.html#jdbc-auth-schema-entities" title="Entities"><code class="classname">guacamole_entity</code></a> tables. Each user group has |
| a corresponding unique name specified via |
| <code class="classname">guacamole_entity</code>.</p><p>If deleting a user group, the <a class="link" href="jdbc-auth.html#jdbc-auth-schema-entities" title="Entities">corresponding entity</a> 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, <span class="emphasis"><em>it is advisable to use the entity as the basis |
| for any delete operation</em></span>.</p><p>The <code class="classname">guacamole_user_group</code> table contains the following |
| columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">user_group_id</span></span></dt><dd><p>The unique integer associated with each user group. This value is |
| generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_user_group</code> table.</p></dd><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| <code class="classname">guacamole_entity</code> entry representing this user |
| group.</p></dd><dt><span class="term"><span class="property">disabled</span></span></dt><dd><p>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 <code class="constant">TRUE</code> or <code class="constant">1</code>, |
| 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.</p></dd></dl></div><a id="idm46420847170544" class="indexterm"></a><p>Membership within a user group is dictated through entries in the |
| <code class="classname">guacamole_user_group_member</code> table. As both users and user |
| groups may be members of groups, each entry associates the containing group with the |
| entity of the member.</p><p>The <code class="classname">guacamole_user_group_member</code> table contains the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">user_group_id</span></span></dt><dd><p>The <span class="property">user_group_id</span> value of the user group having |
| the specified member.</p></dd><dt><span class="term"><span class="property">member_entity_id</span></span></dt><dd><p>The <span class="property">entity_id</span> value of the user or user group |
| that is a member of the specified group.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-connections"></a>Connections and parameters</h3></div></div></div><a id="idm46420847876752" class="indexterm"></a><a id="idm46420847875728" class="indexterm"></a><p>Each connection has an entry in the <code class="classname">guacamole_connection</code> |
| table, with a one-to-many relationship to parameters, stored as name/value pairs in |
| the <code class="classname">guacamole_connection_parameter</code> table.</p><p>The <code class="classname">guacamole_connection</code> 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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">connection_id</span></span></dt><dd><p>The unique integer associated with each connection. This value is |
| generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_connection</code> table.</p></dd><dt><span class="term"><span class="property">connection_name</span></span></dt><dd><p>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 <span class="property">connection_id</span>, not |
| <span class="property">connection_name</span>.</p></dd><dt><span class="term"><span class="property">protocol</span></span></dt><dd><p>The protocol to use with this connection. This is the name of the |
| protocol that should be sent to <span class="package">guacd</span> when |
| connecting, for example "<code class="constant">vnc</code>" or |
| "<code class="constant">rdp</code>".</p></dd><dt><span class="term"><span class="property">parent_id</span></span></dt><dd><p>The unique integer associated with the connection group containing |
| this connection, or <code class="constant">NULL</code> if this connection is |
| within the root group.</p></dd><dt><span class="term"><span class="property">max_connections</span></span></dt><dd><p>The maximum number of concurrent connections to allow to this |
| connection at any one time <span class="emphasis"><em>regardless of user</em></span>. |
| <code class="constant">NULL</code> will use the default value specified in |
| <code class="filename">guacamole.properties</code> with the |
| <span class="property">mysql-default-max-connections</span> or |
| <span class="property">postgresql-default-max-connections</span> properties, |
| and a value of <code class="constant">0</code> denotes unlimited.</p></dd><dt><span class="term"><span class="property">max_connections_per_user</span></span></dt><dd><p>The maximum number of concurrent connections to allow to this |
| connection at any one time <span class="emphasis"><em>from a single user</em></span>. |
| <code class="constant">NULL</code> will use the default value specified in |
| <code class="filename">guacamole.properties</code> with the |
| <span class="property">mysql-default-max-connections</span> or |
| <span class="property">postgresql-default-max-connections</span> properties, |
| and a value of <code class="constant">0</code> denotes unlimited.</p></dd><dt><span class="term"><span class="property">proxy_hostname</span></span></dt><dd><p>The hostname or IP address of the Guacamole proxy daemon |
| (<span class="package">guacd</span>) which should be used for this connection. |
| If <code class="constant">NULL</code>, the value defined with the |
| <span class="property">guacd-hostname</span> property in |
| <code class="filename">guacamole.properties</code> will be used.</p></dd><dt><span class="term"><span class="property">proxy_port</span></span></dt><dd><p>The TCP port number of the Guacamole proxy daemon |
| (<span class="package">guacd</span>) which should be used for this connection. |
| If <code class="constant">NULL</code>, the value defined with the |
| <span class="property">guacd-port</span> property in |
| <code class="filename">guacamole.properties</code> will be used.</p></dd><dt><span class="term"><span class="property">proxy_encryption_method</span></span></dt><dd><p>The encryption method which should be used when communicating with the |
| Guacamole proxy daemon (<span class="package">guacd</span>) for this connection. |
| This can be either <code class="constant">NONE</code>, for no encryption, or |
| <code class="constant">SSL</code>, for SSL/TLS. If <code class="constant">NULL</code>, |
| the encryption method will be dictated by the |
| <span class="property">guacd-ssl</span> property in |
| <code class="filename">guacamole.properties</code>.</p></dd><dt><span class="term"><span class="property">connection_weight</span></span></dt><dd><p>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 <code class="constant">1</code> or greater will weight |
| the connection relative to other connections in that group, and values |
| below <code class="constant">1</code> cause the connection to be disabled in the |
| group. If <code class="constant">NULL</code>, the connection will be assigned a |
| default weight of <code class="constant">1</code>.</p></dd><dt><span class="term"><span class="property">failover_only</span></span></dt><dd><p>Whether this connection should be used for failover situations only, |
| also known as a "hot spare". If this column is set to |
| <code class="constant">TRUE</code> or <code class="constant">1</code>, this connection |
| will be used only when another connection within the same |
| <span class="type">BALANCING</span> connection group has failed due to an error |
| within the remote desktop. </p><p><span class="emphasis"><em>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.</em></span> This column |
| simply dictates whether a particular connection should be |
| <span class="emphasis"><em>reserved</em></span> for such situations, and left unused |
| otherwise.</p><p>This column only has an effect on connections within |
| <span class="type">BALANCING</span> groups.</p></dd></dl></div><p>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 |
| <code class="classname">guacamole_connection_parameter</code> table associated with its |
| corresponding connection. This table contains the following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">connection_id</span></span></dt><dd><p>The <span class="property">connection_id</span> value from the connection this |
| parameter is for.</p></dd><dt><span class="term"><span class="property">parameter_name</span></span></dt><dd><p>The name of the parameter to set. This is the name listed in the |
| documentation for the protocol specified in the associated |
| connection.</p></dd><dt><span class="term"><span class="property">parameter_value</span></span></dt><dd><p>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.</p></dd></dl></div><p>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:</p><div class="informalexample"><pre class="programlisting">-- Create connection |
| INSERT INTO guacamole_connection (connection_name, protocol) VALUES ('<em class="replaceable"><code>test</code></em>', '<em class="replaceable"><code>vnc</code></em>'); |
| |
| -- Determine the connection_id |
| SELECT * FROM guacamole_connection WHERE connection_name = '<em class="replaceable"><code>test</code></em>' AND parent_id IS NULL; |
| |
| -- Add parameters to the new connection |
| INSERT INTO guacamole_connection_parameter VALUES (<em class="replaceable"><code>1</code></em>, 'hostname', '<em class="replaceable"><code>localhost</code></em>'); |
| INSERT INTO guacamole_connection_parameter VALUES (<em class="replaceable"><code>1</code></em>, 'port', '<em class="replaceable"><code>5901</code></em>');</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-connection-history"></a>Usage history</h4></div></div></div><a id="idm46420848249248" class="indexterm"></a><p>When a connection is initiated or terminated, a corresponding entry in the |
| <code class="classname">guacamole_connection_history</code> table is created or |
| updated respectively. Each entry is associated with the user using the |
| connection, the connection itself, the <a class="link" href="jdbc-auth.html#jdbc-auth-schema-sharing-profiles" title="Sharing profiles and parameters">sharing profile</a> 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.</p><p>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 <code class="classname">guacamole_connection_history</code> table |
| has the following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">history_id</span></span></dt><dd><p>The unique integer associated with each history record. This value |
| is generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_connection_history</code> |
| table.</p></dd><dt><span class="term"><span class="property">user_id</span></span></dt><dd><p>The value of the <span class="property">user_id</span> from the entry in |
| <code class="classname">guacamole_user</code> associated with the user |
| using the connection. If the user no longer exists, this will be |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">username</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">connection_id</span></span></dt><dd><p>The value of the <span class="property">connection_id</span> from the entry |
| in <code class="classname">guacamole_connection</code> associated the |
| connection being used. If the connection associated with the history |
| record no longer exists, this will be |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">connection_name</span></span></dt><dd><p>The name associated with the connection at the time that it was |
| used.</p></dd><dt><span class="term"><span class="property">sharing_profile_id</span></span></dt><dd><p>The value of the <span class="property">sharing_profile_id</span> from the |
| entry in <code class="classname">guacamole_sharing_profile</code> 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 <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">sharing_profile_name</span></span></dt><dd><p>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 |
| <code class="constant">NULL</code>.</p></dd><dt><span class="term"><span class="property">start_date</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">end_date</span></span></dt><dd><p>The time at which the connection ended. If the connection is still |
| active, the value in this column will be <code class="constant">NULL</code>. |
| Despite its name, this column also stores time information in |
| addition to the date.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-sharing-profiles"></a>Sharing profiles and parameters</h3></div></div></div><a id="idm46420847600832" class="indexterm"></a><a id="idm46420847599792" class="indexterm"></a><p>Each sharing profile has an entry in the |
| <code class="classname">guacamole_sharing_profile</code> table, with a one-to-many |
| relationship to parameters, stored as name/value pairs in the |
| <code class="classname">guacamole_sharing_profile_parameter</code> table.</p><p>The <code class="classname">guacamole_sharing_profile</code> 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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">sharing_profile_id</span></span></dt><dd><p>The unique integer associated with each sharing profile. This value is |
| generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_sharing_profile</code> table.</p></dd><dt><span class="term"><span class="property">sharing_profile_name</span></span></dt><dd><p>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 |
| <span class="property">sharing_profile_id</span>, not |
| <span class="property">sharing_profile_name</span>.</p></dd><dt><span class="term"><span class="property">primary_connection_id</span></span></dt><dd><p>The unique integer associated with the primary connection. The |
| "primary connection" is the connection which can be shared using this |
| sharing profile.</p></dd></dl></div><p>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 <code class="classname">guacamole_sharing_profile_parameter</code> table |
| associated with its corresponding sharing profile. This table contains the following |
| columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">sharing_profile_id</span></span></dt><dd><p>The <span class="property">sharing_profile_id</span> value from the entry in |
| the <code class="classname">guacamole_sharing_profile</code> table for the |
| sharing profile this parameter applies to.</p></dd><dt><span class="term"><span class="property">parameter_name</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">parameter_value</span></span></dt><dd><p>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.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-connection-groups"></a>Connection groups</h3></div></div></div><a id="idm46420847350912" class="indexterm"></a><p>Each connection group has an entry in the |
| <code class="classname">guacamole_connection_group</code> table, with a one-to-many |
| relationship to other groups and connections.</p><p>The <code class="classname">guacamole_connection_group</code> table is simply a pairing of |
| a unique and descriptive name with a group type, which can be either |
| <span class="type">ORGANIZATIONAL</span> or <span class="type">BALANCING</span>. It contains the following |
| columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">connection_group_id</span></span></dt><dd><p>The unique integer associated with each connection group. This value |
| is generated automatically when a new entry is inserted into the |
| <code class="classname">guacamole_connection_group</code> table.</p></dd><dt><span class="term"><span class="property">connection_group_name</span></span></dt><dd><p>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 |
| <span class="property">connection_group_id</span>, not |
| <span class="property">connection_group_name</span>.</p></dd><dt><span class="term"><span class="property">type</span></span></dt><dd><p>The type of this connection group. This can be either |
| <span class="type">ORGANIZATIONAL</span> or <span class="type">BALANCING</span>.</p></dd><dt><span class="term"><span class="property">parent_id</span></span></dt><dd><p>The unique integer associated with the connection group containing |
| this connection group, or <code class="constant">NULL</code> if this connection |
| group is within the root group.</p></dd><dt><span class="term"><span class="property">max_connections</span></span></dt><dd><p>The maximum number of concurrent connections to allow to this |
| connection group at any one time <span class="emphasis"><em>regardless of |
| user</em></span>. <code class="constant">NULL</code> will use the default value |
| specified in <code class="filename">guacamole.properties</code> with the |
| <span class="property">mysql-default-max-connections</span> or |
| <span class="property">postgresql-default-max-connections</span> properties, |
| and a value of <code class="constant">0</code> denotes unlimited. This only has |
| an effect on <span class="type">BALANCING</span> groups.</p></dd><dt><span class="term"><span class="property">max_connections_per_user</span></span></dt><dd><p>The maximum number of concurrent connections to allow to this |
| connection group at any one time <span class="emphasis"><em>from a single |
| user</em></span>. <code class="constant">NULL</code> will use the default value |
| specified in <code class="filename">guacamole.properties</code> with the |
| <span class="property">mysql-default-max-connections</span> or |
| <span class="property">postgresql-default-max-connections</span> properties, |
| and a value of <code class="constant">0</code> denotes unlimited. This only has |
| an effect on <span class="type">BALANCING</span> groups.</p></dd><dt><span class="term"><span class="property">enable_session_affinity</span></span></dt><dd><p>Whether session affinity should apply to this connection group. If |
| this column is set to <code class="constant">TRUE</code> or |
| <code class="constant">1</code>, 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 <span class="type">BALANCING</span> groups.</p></dd></dl></div><p>Adding a connection group is even simpler than adding a new connection as there |
| are no associated parameters stored in a separate table:</p><div class="informalexample"><pre class="programlisting">-- Create connection group |
| INSERT INTO guacamole_connection_group (connection_group_name, type) |
| VALUES ('<em class="replaceable"><code>test</code></em>', '<em class="replaceable"><code>ORGANIZATIONAL</code></em>');</pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="jdbc-auth-schema-permissions"></a>Permissions</h3></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-system-permissions"></a>lSystem permissions</h4></div></div></div><a id="idm46420847315120" class="indexterm"></a><p>System permissions are defined by entries in the |
| <code class="classname">guacamole_system_permission</code> table. Each entry grants |
| permission for a specific user or user group to perform a specific system |
| operation.</p><p>The <code class="classname">guacamole_system_permission</code> table contains the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of six |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to administer the entire system (essentially a wildcard |
| permission), <code class="constant">CREATE_CONNECTION</code>, which grants |
| the ability to create connections, |
| <code class="constant">CREATE_CONNECTION_GROUP</code>, which grants the |
| ability to create connections groups, |
| <code class="constant">CREATE_SHARING_PROFILE</code>, which grants the |
| ability to create sharing profiles, |
| <code class="constant">CREATE_USER</code>, which grants the ability to create |
| users, or <code class="constant">CREATE_USER_GROUP</code>, which grants the |
| ability to create user groups.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-user-permissions"></a>User permissions</h4></div></div></div><a id="idm46420847550192" class="indexterm"></a><p>User permissions are defined by entries in the |
| <code class="classname">guacamole_user_permission</code> table. Each entry grants |
| permission for a specific user or user group to perform a specific operation on |
| an existing user.</p><p>The <code class="classname">guacamole_user_permission</code> table contains the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">affected_user_id</span></span></dt><dd><p>The value of the <span class="property">user_id</span> column of the entry |
| associated with the user <span class="emphasis"><em>affected</em></span> by this |
| permission. This is the user that would be the object of the |
| operation represented by this permission.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of four |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to add or remove permissions which affect the user, |
| <code class="constant">READ</code>, which grants the ability to read data |
| associated with the user, <code class="constant">UPDATE</code>, which grants |
| the ability to update data associated with the user, or |
| <code class="constant">DELETE</code>, which grants the ability to delete |
| the user.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-group-permissions"></a>User group permissions</h4></div></div></div><a id="idm46420847535344" class="indexterm"></a><p>User group permissions are defined by entries in the |
| <code class="classname">guacamole_user_group_permission</code> table. Each entry |
| grants permission for a specific user or user group to perform a specific |
| operation on an existing user group.</p><p>The <code class="classname">guacamole_user_group_permission</code> table contains the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">affected_user_group_id</span></span></dt><dd><p>The value of the <span class="property">user_group_id</span> column of the |
| entry associated with the user group <span class="emphasis"><em>affected</em></span> |
| by this permission. This is the user group that would be the object |
| of the operation represented by this permission.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of four |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to add or remove permissions which affect the user group, |
| <code class="constant">READ</code>, which grants the ability to read data |
| associated with the user group, <code class="constant">UPDATE</code>, which |
| grants the ability to update data associated with the user group, or |
| <code class="constant">DELETE</code>, which grants the ability to delete |
| the user group.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-connection-permissions"></a>Connection permissions</h4></div></div></div><a id="idm46420847923264" class="indexterm"></a><p>Connection permissions are defined by entries in the |
| <code class="classname">guacamole_connection_permission</code> table. Each entry |
| grants permission for a specific user or user group to perform a specific |
| operation on an existing connection.</p><p>The <code class="classname">guacamole_connection_permission</code> table contains the |
| following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">connection_id</span></span></dt><dd><p>The value of the <span class="property">connection_id</span> 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.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of four |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to add or remove permissions which affect the connection, |
| <code class="constant">READ</code>, which grants the ability to read data |
| associated with the connection (a prerequisite for connecting), |
| <code class="constant">UPDATE</code>, which grants the ability to update |
| data associated with the connection, or <code class="constant">DELETE</code>, |
| which grants the ability to delete the connection.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-sharing-profile-permissions"></a>Sharing profile permissions</h4></div></div></div><a id="idm46420847908848" class="indexterm"></a><p>Sharing profile permissions are defined by entries in the |
| <code class="classname">guacamole_sharing_profile_permission</code> table. Each |
| entry grants permission for a specific user or user group to perform a specific |
| operation on an existing sharing profile.</p><p>The <code class="classname">guacamole_sharing_profile_permission</code> table contains |
| the following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">sharing_profile_id</span></span></dt><dd><p>The value of the <span class="property">sharing_profile_id</span> 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.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of four |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to add or remove permissions which affect the sharing |
| profile, <code class="constant">READ</code>, which grants the ability to read |
| data associated with the sharing profile (a prerequisite for using |
| the sharing profile to share an active connection), |
| <code class="constant">UPDATE</code>, which grants the ability to update |
| data associated with the sharing profile, or |
| <code class="constant">DELETE</code>, which grants the ability to delete |
| the sharing profile.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="jdbc-auth-schema-connection-group-permissions"></a>Connection group permissions</h4></div></div></div><a id="idm46420847894128" class="indexterm"></a><p>Connection group permissions are defined by entries in the |
| <code class="classname">guacamole_connection_group_permission</code> table. Each |
| entry grants permission for a specific user or user group to perform a specific |
| operation on an existing connection group.</p><p>The <code class="classname">guacamole_connection_group_permission</code> table |
| contains the following columns:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">entity_id</span></span></dt><dd><p>The value of the <span class="property">entity_id</span> column of the |
| entry associated with the user or user group owning this |
| permission.</p></dd><dt><span class="term"><span class="property">connection_group_id</span></span></dt><dd><p>The value of the <span class="property">connection_group_id</span> 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.</p></dd><dt><span class="term"><span class="property">permission</span></span></dt><dd><p>The permission being granted. This column can have one of four |
| possible values: <code class="constant">ADMINISTER</code>, which grants the |
| ability to add or remove permissions which affect the connection |
| group, <code class="constant">READ</code>, which grants the ability to read |
| data associated with the connection group, |
| <code class="constant">UPDATE</code>, which grants the ability to update |
| data associated with the connection group, or |
| <code class="constant">DELETE</code>, which grants the ability to delete |
| the connection group (and implicitly its contents).</p></dd></dl></div></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-guacamole.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ldap-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Configuring Guacamole </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. LDAP authentication</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
