Google Git
Sign in
apache / guacamole-manual / f2e5fffd9639cc1c3993f522efd2da27e3c10dd4 / . / src / chapters / docker.xml
blob: c58cee8a9f81c6c2ca1344a6b152898d013c24bc [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="guacamole-docker" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
xmlns:xl="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Installing Guacamole with Docker</title>
<indexterm>
<primary>docker</primary>
</indexterm>
<para>Guacamole can be deployed using Docker, removing the need to build
<package>guacamole-server</package> from source or configure the web application
manually. The Guacamole project provides officially-supported Docker images for both
Guacamole and <package>guacd</package> which are kept up-to-date with each release.</para>
<para>A typical Docker deployment of Guacamole will involve three separate containers, linked
together at creation time:</para>
<variablelist>
<varlistentry>
<term><systemitem>guacamole/guacd</systemitem></term>
<listitem>
<para>Provides the <package>guacd</package> daemon, built from the released
<package>guacamole-server</package> source with support for VNC, RDP, SSH,
and telnet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><systemitem>guacamole/guacamole</systemitem></term>
<listitem>
<para>Provides the Guacamole web application running within Tomcat 8 with support
for WebSocket. The configuration necessary to connect to
<package>guacd</package>, MySQL, PostgreSQL, LDAP, etc. will be generated
automatically when the image starts based on Docker links or environment
variables.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><systemitem>mysql</systemitem> or <systemitem>postgresql</systemitem></term>
<listitem>
<para>Provides the database that Guacamole will use for authentication and storage
of connection configuration data.</para>
</listitem>
</varlistentry>
</variablelist>
<para>This separation is important, as it facilitates upgrades and maintains proper separation
of concerns. With the database separate from Guacamole and <package>guacd</package>, those
containers can be freely destroyed and recreated at will. The only container which must
persist data through upgrades is the database.</para>
<section xml:id="guacd-docker-image">
<title>Running the <package>guacd</package> Docker image</title>
<para>The <package>guacd</package> Docker image is built from the released
<package>guacamole-server</package> source with support for VNC, RDP, SSH, and
telnet. Common pitfalls like installing the required dependencies, installing fonts for
SSH or telnet, and ensuring the FreeRDP plugins are installed to the correct location
are all taken care of. It will simply just work.</para>
<section xml:id="guacd-docker-guacamole">
<title>Running <package>guacd</package> for use by the Guacamole Docker image</title>
<para>When running the <package>guacd</package> image with the intent of linking to a
Guacamole container, no ports need be exposed on the network. Access to these ports
will be handled automatically by Docker during linking, and the Guacamole image will
properly detect and configure the connection to <package>guacd</package>.</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacd</replaceable> -d guacamole/guacd</screen>
</informalexample>
<para>When run in this manner, <package>guacd</package> will be listening on its default
port 4822, but this port will only be available to Docker containers that have been
explicitly linked to
<varname><replaceable>some-guacd</replaceable></varname>.</para>
</section>
<section xml:id="guacd-docker-external">
<title>Running <package>guacd</package> for use by services outside Docker</title>
<para>If you are not going to use the Guacamole image, you can still leverage the
<package>guacd</package> image for ease of installation and maintenance. By
exposing the <package>guacd</package> port, 4822, services external to Docker will
be able to access <package>guacd</package>.</para>
<important>
<para><emphasis>Take great care when doing this</emphasis> -
<package>guacd</package> is a passive proxy and does not perform any kind of
authentication.</para>
<para>If you do not properly isolate <package>guacd</package> from untrusted parts
of your network, malicious users may be able to use <package>guacd</package> as
a jumping point to other systems.</para>
</important>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacd</replaceable> -d -p 4822:4822 guacamole/guacd</screen>
</informalexample>
<para><package>guacd</package> will now be listening on port 4822, and Docker will
expose this port on the same server hosting Docker. Other services, such as an
instance of Tomcat running outside of Docker, will be able to connect to
<package>guacd</package> directly.</para>
</section>
</section>
<section xml:id="guacamole-docker-image">
<title>The Guacamole Docker image</title>
<para>The Guacamole Docker image is built on top of a standard Tomcat 8 image and takes care
of all configuration automatically. The configuration information required for
<package>guacd</package> and the various authentication mechanisms are specified
with environment variables or Docker links given when the container is created.</para>
<important>
<para>If using <link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-docker-postgresql">PostgreSQL</link> or <link
xmlns:xlink="http://www.w3.org/1999/xlink" linkend="guacamole-docker-mysql"
>MySQL</link> for authentication, <emphasis>you will need to initialize the
database manually</emphasis>. Guacamole will not automatically create its own
tables, but SQL scripts are provided to do this.</para>
</important>
<para>Once the Guacamole image is running, Guacamole will be accessible at
<uri>http://<replaceable>HOSTNAME</replaceable>:8080/guacamole/</uri>, where
<replaceable>HOSTNAME</replaceable> is the hostname or address of the machine
hosting Docker.</para>
<section xml:id="guacamole-docker-guacd">
<title>Connecting Guacamole to <package>guacd</package></title>
<para>The Guacamole Docker image needs to be able to connect to <package>guacd</package>
to establish remote desktop connections, just like any other Guacamole deployment.
The connection information needed by Guacamole will be provided either via a Docker
link or through environment variables.</para>
<para>If you will be using Docker to provide <package>guacd</package>, and you wish to
use a Docker link to connect the Guacamole image to <package>guacd</package>, the
connection details are implied by the Docker link:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
<emphasis>--link <replaceable>some-guacd</replaceable>:guacd</emphasis> \
...
-d -p 8080:8080 guacamole/guacamole</screen>
<para>If you are not using Docker to provide <package>guacd</package>, you will need
to provide the network connection information yourself using additional
environment variables:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>GUACD_HOSTNAME</envar></entry>
<entry>
<para>The hostname of the <package>guacd</package> instance to
use to establish remote desktop connections. <emphasis>This
is required if you are not using Docker to provide
<package>guacd</package>.</emphasis></para>
</entry>
</row>
<row>
<entry><envar>GUACD_PORT</envar></entry>
<entry>
<para>The port that Guacamole should use when connecting to
<package>guacd</package>. This environment variable is
optional. If not provided, the standard
<package>guacd</package> port of 4822 will be
used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The <envar>GUACD_HOSTNAME</envar> and, if necessary, <envar>GUACD_PORT</envar>
environment variables can thus be used in place of a Docker link if using a
Docker link is impossible or undesirable:</para>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
<emphasis>-e GUACD_HOSTNAME=<replaceable>172.17.42.1</replaceable> \
-e GUACD_PORT=<replaceable>4822</replaceable></emphasis> \
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para><emphasis>A connection to <package>guacd</package> is not the only thing required
for Guacamole to work</emphasis>; some authentication mechanism needs to be
configured, as well. <link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-docker-mysql">MySQL</link>, <link
xmlns:xlink="http://www.w3.org/1999/xlink" linkend="guacamole-docker-postgresql"
>PostgreSQL</link>, and <link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-docker-ldap">LDAP</link> are supported for this, and are
described in more detail in the sections below. If the required configuration
options for at least one authentication mechanism are not provided, the Guacamole
image will not be able to start up, and you will see an error.</para>
</section>
<section xml:id="guacamole-docker-mysql">
<title>MySQL authentication</title>
<para>To use Guacamole with the MySQL authentication backend, you will need either a
Docker container running the <systemitem>mysql</systemitem> image, or network access
to a working installation of MySQL. The connection to MySQL can be specified using
either environment variables or a Docker link.</para>
<section xml:id="initializing-guacamole-docker-mysql">
<title>Initializing the MySQL database</title>
<para>If your database is not already initialized with the Guacamole schema, you
will need to do so prior to using Guacamole. A convenience script for generating
the necessary SQL to do this is included in the Guacamole image.</para>
<para>To generate a SQL script which can be used to initialize a fresh MySQL
database as documented in <xref linkend="jdbc-auth"/>:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > <replaceable>initdb.sql</replaceable></screen>
</informalexample>
<para>Alternatively, you can use the SQL scripts included with the database
authentication.</para>
<para>Once this script is generated, you must:</para>
<procedure>
<step>
<para>Create a database for Guacamole within MySQL, such as
<database><replaceable>guacamole_db</replaceable></database>.</para>
</step>
<step>
<para>Create a user for Guacamole within MySQL with access to this database,
such as
<systemitem><replaceable>guacamole_user</replaceable></systemitem>.</para>
</step>
<step>
<para>Run the script on the newly-created database.</para>
</step>
</procedure>
<para>The process for doing this via the <command>mysql</command> utility included
with MySQL is documented in <xref linkend="jdbc-auth"/>.</para>
</section>
<section xml:id="guacamole-docker-mysql-connecting">
<title>Connecting Guacamole to MySQL</title>
<para>If your MySQL database is provided by another Docker container, and you wish
to use a Docker link to connect the Guacamole image to your database, the
connection details are implied by the Docker link itself:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
--link some-guacd:guacd \
<emphasis>--link <replaceable>some-mysql</replaceable>:mysql</emphasis> \
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para>If you are not using Docker to provide your MySQL database, you will need to
provide the network connection information yourself using additional environment
variables:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>MYSQL_HOSTNAME</envar></entry>
<entry>
<para>The hostname of the database to use for Guacamole
authentication. <emphasis>This is required if you are not
using Docker to provide your MySQL
database.</emphasis></para>
</entry>
</row>
<row>
<entry><envar>MYSQL_PORT</envar></entry>
<entry>
<para>The port that Guacamole should use when connecting to
MySQL. This environment variable is optional. If not
provided, the standard MySQL port of 3306 will be
used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The <envar>MYSQL_HOSTNAME</envar> and, if necessary, <envar>MYSQL_PORT</envar>
environment variables can thus be used in place of a Docker link if using a
Docker link is impossible or undesirable:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
--link some-guacd:guacd \
<emphasis>-e MYSQL_HOSTNAME=<replaceable>172.17.42.1</replaceable> \</emphasis>
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para>Note that a Docker link to <package>guacd</package> (the <option>--link
some-guacd:guacd</option> option above) is not required any more than a
Docker link is required for MySQL. The connection information for
<package>guacd</package> can be specified using environment variables, as
described in <xref xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-docker-guacd"/>.</para>
</section>
<section xml:id="guacamole-docker-mysql-required-vars">
<title xml:id="deploying-guacamole-docker-mysql">Required environment
variables</title>
<para>Using MySQL for authentication requires additional configuration parameters
specified via environment variables. These variables collectively describe how
Guacamole will connect to MySQL:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>MYSQL_DATABASE</envar></entry>
<entry>
<para>The name of the database to use for Guacamole
authentication.</para>
</entry>
</row>
<row>
<entry><envar>MYSQL_USER</envar></entry>
<entry>
<para>The user that Guacamole will use to connect to
MySQL.</para>
</entry>
</row>
<row>
<entry><envar>MYSQL_PASSWORD</envar></entry>
<entry>
<para>The password that Guacamole will provide when connecting
to MySQL as <envar>MYSQL_USER</envar>.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>If any required environment variables are omitted, you will receive an error
message in the logs, and the image will stop. You will then need to recreate the
container with the proper variables specified.</para>
</section>
<section xml:id="guacamole-docker-mysql-optional-vars">
<title>Optional environment variables</title>
<para>Additional optional environment variables may be used to override Guacamole's
default behavior with respect to concurrent connection use by one or more users.
Concurrent use of connections and connection groups can be limited to an overall
maximum and/or a per-user maximum:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1.15*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>MYSQL_ABSOLUTE_MAX_CONNECTIONS</envar></entry>
<entry>
<para>The absolute maximum number of concurrent connections to
allow at any time, regardless of the Guacamole connection or
user involved. If set to "0", this will be unlimited.
Because this limit applies across all Guacamole connections,
it cannot be overridden if set.</para>
<para><emphasis>By default, the absolute total number of
concurrent connections is unlimited
("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>MYSQL_DEFAULT_MAX_CONNECTIONS</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow to
any one Guacamole connection. If set to "0", this will be
unlimited. This can be overridden on a per-connection basis
when editing a connection.</para>
<para><emphasis>By default, overall concurrent use of
connections is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow to
any one Guacamole connection group. If set to "0", this will
be unlimited. This can be overridden on a per-group basis
when editing a connection group.</para>
<para><emphasis>By default, overall concurrent use of connection
groups is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow a
single user to maintain to any one Guacamole connection. If
set to "0", this will be unlimited. This can be overridden
on a per-connection basis when editing a connection.</para>
<para><emphasis>By default, per-user concurrent use of
connections is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow a
single user to maintain to any one Guacamole connection
group. If set to "0", this will be unlimited. This can be
overridden on a per-group basis when editing a connection
group.</para>
<para><emphasis>By default, per-user concurrent use of
connection groups is limited to one ("1")</emphasis>, to
prevent a balancing connection group from being completely
exhausted by one user alone.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
<section xml:id="guacamole-docker-postgresql">
<title>PostgreSQL authentication</title>
<para>To use Guacamole with the PostgreSQL authentication backend, you will need either
a Docker container running the <systemitem>postgres</systemitem> image, or network
access to a working installation of PostgreSQL. The connection to PostgreSQL can be
specified using either environment variables or a Docker link.</para>
<section xml:id="initializing-guacamole-docker-postgresql">
<title>Initializing the PostgreSQL database</title>
<para>If your database is not already initialized with the Guacamole schema, you
will need to do so prior to using Guacamole. A convenience script for generating
the necessary SQL to do this is included in the Guacamole image.</para>
<para>To generate a SQL script which can be used to initialize a fresh PostgreSQL
database as documented in <xref linkend="jdbc-auth"/>:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgres > <replaceable>initdb.sql</replaceable></screen>
</informalexample>
<para>Alternatively, you can use the SQL scripts included with the database
authentication.</para>
<para>Once this script is generated, you must:</para>
<procedure>
<step>
<para>Create a database for Guacamole within PostgreSQL, such as
<database><replaceable>guacamole_db</replaceable></database>.</para>
</step>
<step>
<para>Run the script on the newly-created database.</para>
</step>
<step>
<para>Create a user for Guacamole within PostgreSQL with access to the
tables and sequences of this database, such as
<systemitem><replaceable>guacamole_user</replaceable></systemitem>.</para>
</step>
</procedure>
<para>The process for doing this via the <command>psql</command> and
<command>createdb</command> utilities included with PostgreSQL is documented
in <xref linkend="jdbc-auth"/>.</para>
</section>
<section xml:id="guacamole-docker-postgresql-connecting">
<title>Connecting Guacamole to PostgreSQL</title>
<para>If your PostgreSQL database is provided by another Docker container, and you
wish to use a Docker link to connect the Guacamole image to your database, the
connection details are implied by the Docker link itself:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
--link some-guacd:guacd \
<emphasis>--link <replaceable>some-postgres</replaceable>:postgres</emphasis> \
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para>If you are not using Docker to provide your PostgreSQL database, you will need
to provide the network connection information yourself using additional
environment variables:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>POSTGRES_HOSTNAME</envar></entry>
<entry>
<para>The hostname of the database to use for Guacamole
authentication. <emphasis>This is required if you are not
using Docker to provide your PostgreSQL
database.</emphasis></para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_PORT</envar></entry>
<entry>
<para>The port that Guacamole should use when connecting to
PostgreSQL. This environment variable is optional. If not
provided, the standard PostgreSQL port of 5432 will be
used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The <envar>POSTGRES_HOSTNAME</envar> and, if necessary,
<envar>POSTGRES_PORT</envar> environment variables can thus be used in place
of a Docker link if using a Docker link is impossible or undesirable:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
--link some-guacd:guacd \
<emphasis>-e POSTGRES_HOSTNAME=<replaceable>172.17.42.1</replaceable> \</emphasis>
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para>Note that a Docker link to <package>guacd</package> (the <option>--link
some-guacd:guacd</option> option above) is not required any more than a
Docker link is required for PostgreSQL. The connection information for
<package>guacd</package> can be specified using environment variables, as
described in <xref xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-docker-guacd"/>.</para>
</section>
<section xml:id="guacamole-docker-postgresql-required-vars">
<title>Required environment variables</title>
<para>Using PostgreSQL for authentication requires additional configuration
parameters specified via environment variables. These variables collectively
describe how Guacamole will connect to PostgreSQL:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>POSTGRES_DATABASE</envar></entry>
<entry>
<para>The name of the database to use for Guacamole
authentication.</para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_USER</envar></entry>
<entry>
<para>The user that Guacamole will use to connect to
PostgreSQL.</para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_PASSWORD</envar></entry>
<entry>
<para>The password that Guacamole will provide when connecting
to PostgreSQL as <envar>POSTGRES_USER</envar>.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>If any required environment variables are omitted, you will receive an error
message in the logs, and the image will stop. You will then need to recreate the
container with the proper variables specified.</para>
</section>
<section xml:id="guacamole-docker-postgresql-optional-vars">
<title>Optional environment variables</title>
<para>Additional optional environment variables may be used to override Guacamole's
default behavior with respect to concurrent connection use by one or more users.
Concurrent use of connections and connection groups can be limited to an overall
maximum and/or a per-user maximum:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1.15*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>POSTGRES_ABSOLUTE_MAX_CONNECTIONS</envar></entry>
<entry>
<para>The absolute maximum number of concurrent connections to
allow at any time, regardless of the Guacamole connection or
user involved. If set to "0", this will be unlimited.
Because this limit applies across all Guacamole connections,
it cannot be overridden if set.</para>
<para><emphasis>By default, the absolute total number of
concurrent connections is unlimited
("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_DEFAULT_MAX_CONNECTIONS</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow to
any one Guacamole connection. If set to "0", this will be
unlimited. This can be overridden on a per-connection basis
when editing a connection.</para>
<para><emphasis>By default, overall concurrent use of
connections is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow to
any one Guacamole connection group. If set to "0", this will
be unlimited. This can be overridden on a per-group basis
when editing a connection group.</para>
<para><emphasis>By default, overall concurrent use of connection
groups is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow a
single user to maintain to any one Guacamole connection. If
set to "0", this will be unlimited. This can be overridden
on a per-connection basis when editing a connection.</para>
<para><emphasis>By default, per-user concurrent use of
connections is unlimited ("0").</emphasis></para>
</entry>
</row>
<row>
<entry><envar>POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER</envar></entry>
<entry>
<para>The maximum number of concurrent connections to allow a
single user to maintain to any one Guacamole connection
group. If set to "0", this will be unlimited. This can be
overridden on a per-group basis when editing a connection
group.</para>
<para><emphasis>By default, per-user concurrent use of
connection groups is limited to one ("1")</emphasis>, to
prevent a balancing connection group from being completely
exhausted by one user alone.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
</section>
<section xml:id="guacamole-docker-ldap">
<title>LDAP authentication</title>
<para>To use Guacamole with the LDAP authentication backend, you will need network
access to an LDAP directory. Unlike MySQL and PostgreSQL, the Guacamole Docker image
does support Docker links for LDAP; the connection information
<emphasis>must</emphasis> be specified using environment variables:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.5*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>LDAP_HOSTNAME</envar></entry>
<entry>
<para>The hostname or IP address of your LDAP server.</para>
</entry>
</row>
<row>
<entry><envar>LDAP_PORT</envar></entry>
<entry>
<para>The port your LDAP server listens on. By default, this will be
389 for unencrypted LDAP or LDAP using STARTTLS, and 636 for
LDAP over SSL (LDAPS).</para>
</entry>
</row>
<row>
<entry><envar>LDAP_ENCRYPTION_METHOD</envar></entry>
<entry>
<para>The encryption mechanism that Guacamole should use when
communicating with your LDAP server. Legal values are "none" for
unencrypted LDAP, "ssl" for LDAP over SSL/TLS (commonly known as
LDAPS), or "starttls" for STARTTLS. If omitted, encryption will
not be used.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Only the <envar>LDAP_HOSTNAME</envar> variable is required, but you may also need
to specify <envar>LDAP_PORT</envar> or <envar>LDAP_ENCRYPTION_METHOD</envar> if your
LDAP directory uses encryption or listens on a non-standard port:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
--link some-guacd:guacd \
<emphasis>-e LDAP_HOSTNAME=<replaceable>172.17.42.1</replaceable> \</emphasis>
...
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
<para>Note that a Docker link to <package>guacd</package> (the <option>--link
some-guacd:guacd</option> option above) is not required. Similar to LDAP, the
connection information for <package>guacd</package> can be specified using
environment variables, as described in <xref
xmlns:xlink="http://www.w3.org/1999/xlink" linkend="guacamole-docker-guacd"
/>.</para>
<section xml:id="guacamole-docker-ldap-required-vars">
<title>Required environment variables</title>
<para>Using LDAP for authentication requires additional configuration parameters
specified via environment variables. These variables collectively describe how
Guacamole will query your LDAP directory:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>LDAP_USER_BASE_DN</envar></entry>
<entry>
<para>The base of the DN for all Guacamole users. All Guacamole
users that will be authenticating against LDAP must be
descendents of this base DN.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>As with the other authentication mechanisms, if any required environment
variables are omitted (including those required for connecting to the LDAP
directory over the network), you will receive an error message in the logs, and
the image will stop. You will then need to recreate the container with the
proper variables specified.</para>
</section>
<section xml:id="guacamole-docker-ldap-optional-vars">
<title>Optional environment variables</title>
<para>Additional optional environment variables may be used to configure the details
of your LDAP directory hierarchy, or to enable more flexible searching for user
accounts:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="2.25*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>LDAP_GROUP_BASE_DN</envar></entry>
<entry>
<para>The base of the DN for all groups that may be referenced
within Guacamole configurations using the standard
<property>seeAlso</property> attribute. All groups which
will be used to control access to Guacamole configurations
must be descendents of this base DN. <emphasis>If this
variable is omitted, the <property>seeAlso</property>
attribute will have no effect on Guacamole
configurations.</emphasis></para>
</entry>
</row>
<row>
<entry><envar>LDAP_SEARCH_BIND_DN</envar></entry>
<entry>
<para>The DN (Distinguished Name) of the user to bind as when
authenticating users that are attempting to log in. If
specified, Guacamole will query the LDAP directory to
determine the DN of each user that logs in. If omitted, each
user's DN will be derived directly using the base DN
specified with <envar>LDAP_USER_BASE_DN</envar>.</para>
</entry>
</row>
<row>
<entry><envar>LDAP_SEARCH_BIND_PASSWORD</envar></entry>
<entry>
<para>The password to provide to the LDAP server when binding as
<envar>LDAP_SEARCH_BIND_DN</envar> to authenticate other
users. This variable is only used if
<envar>LDAP_SEARCH_BIND_DN</envar> is specified. If
omitted, but <envar>LDAP_SEARCH_BIND_DN</envar> is
specified, Guacamole will attempt to bind with the LDAP
server without a password.</para>
</entry>
</row>
<row>
<entry><envar>LDAP_USERNAME_ATTRIBUTE</envar></entry>
<entry>
<para>The attribute or attributes which contain the username
within all Guacamole user objects in the LDAP directory.
Usually, and by default, this will simply be
"<property>uid</property>". If your LDAP directory
contains users whose usernames are dictated by different
attributes, multiple attributes can be specified here,
separated by commas, but beware: <emphasis>doing so requires
that a search DN be provided with
<envar>LDAP_SEARCH_BIND_DN</envar></emphasis>.</para>
</entry>
</row>
<row>
<entry><envar>LDAP_CONFIG_BASE_DN</envar></entry>
<entry>
<para>The base of the DN for all Guacamole configurations. If
omitted, the configurations of Guacamole connections will
simply not be queried from the LDAP directory, and you will
need to store them elsewhere, such as within a MySQL or
PostgreSQL database.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>As documented in <xref xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="ldap-auth"/>, Guacamole does support combining LDAP with a MySQL or
PostgreSQL database, and this can be configured with the Guacamole Docker image,
as well. Each of these authentication mechanisms is independently configurable
using their respective environment variables, and by providing the required
environment variables for multiple systems, Guacamole will automatically be
configured to use each when the Docker image starts.</para>
</section>
</section>
<section xml:id="guacamole-docker-guacamole-home">
<title>Custom extensions and <envar>GUACAMOLE_HOME</envar></title>
<para>If you have your own or third-party extensions for Guacamole which are not
supported by the Guacamole Docker image, but are compatible with the version of
Guacamole within the image, you can still use them by providing a custom base
configuration using the <envar>GUACAMOLE_HOME</envar> environment variable:</para>
<informaltable frame="all">
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="4*"/>
<thead>
<row>
<entry>Variable</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><envar>GUACAMOLE_HOME</envar></entry>
<entry>
<para>The absolute path to the directory within the Docker container
to use <emphasis>as a template</emphasis> for the image's
automatically-generated <link
xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-home"
><envar>GUACAMOLE_HOME</envar></link>. Any configuration
generated by the Guacamole Docker image based on other
environment variables will be applied to an independent copy of
the contents of this directory.</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>You will <emphasis>still</emphasis> need to follow the steps required to create
the contents of <link xmlns:xlink="http://www.w3.org/1999/xlink"
linkend="guacamole-home"><envar>GUACAMOLE_HOME</envar></link> specific to your
extension (placing the extension itself within
<filename><replaceable>GUACAMOLE_HOME</replaceable>/extensions/</filename>,
adding any properties to <filename>guacamole.properties</filename>, etc.), but the
rest of Guacamole's configuration will be handled automatically, overlaid on top of
a copy of the <envar>GUACAMOLE_HOME</envar> you provide.</para>
<para>Because the Docker image's <envar>GUACAMOLE_HOME</envar> environment variable must
point to a directory <emphasis>within the container</emphasis>, you will need to
expose your custom <envar>GUACAMOLE_HOME</envar> to the container using the
<option>-v</option> option of <command>docker run</command>. The container
directory chosen can then be referenced in the <envar>GUACAMOLE_HOME</envar>
environment variable, and the image will handle the rest automatically:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> \
...
<emphasis>-v <replaceable>/local/path</replaceable>:<replaceable>/some-directory</replaceable> \
-e GUACAMOLE_HOME=<replaceable>/some-directory</replaceable> \</emphasis>
-d -p 8080:8080 guacamole/guacamole</screen>
</informalexample>
</section>
<section xml:id="verifying-guacamole-docker">
<title>Verifying the Guacamole install</title>
<para>Once the Guacamole image is running, Guacamole should be accessible at
<uri>http://<replaceable>HOSTNAME</replaceable>:8080/guacamole/</uri>, where
<replaceable>HOSTNAME</replaceable> is the hostname or address of the machine
hosting Docker, and you <emphasis>should</emphasis> a login screen. If using MySQL
or PostgreSQL, the database initialization scripts will have created a default
administrative user called "<systemitem>guacadmin</systemitem>" with the password
"<systemitem>guacadmin</systemitem>". <emphasis>You should log in and change
your password immediately.</emphasis> If using LDAP, you should be able to log
in as any valid user within your LDAP directory.</para>
<para>If you cannot access Guacamole, or you do not see a login screen, check Docker's
logs using the <command>docker logs</command> command to determine if something is
wrong. Configuration parameters may have been given incorrectly, or the database may
be improperly initialized:</para>
<informalexample>
<screen><prompt>$</prompt> <command>docker</command> logs <replaceable>some-guacamole</replaceable></screen>
</informalexample>
</section>
</section>
</chapter>