| <?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, |
| telnet, and Kubernetes.</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, telnet, |
| and Kubernetes. Common pitfalls like installing the required dependencies, installing |
| fonts for SSH, telnet, or Kubernetes, 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> |
| <para>The log level of guacd can be controlled with the <varname>GUACD_LOG_LEVEL</varname> environment variable. The |
| default value is <varname><replaceable>info</replaceable></varname>, and can be set to any of the |
| valid settings for the guacd log flag (-L).</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <command>docker</command> run -e GUACD_LOG_LEVEL=<replaceable>debug</replaceable> -d guacamole/guacd</screen> |
| </informalexample> |
| </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-config-via-env"> |
| <title>Configuring Guacamole when using Docker</title> |
| <para>When running Guacamole using Docker, the traditional approach to configuring |
| Guacamole by editing <filename>guacamole.properties</filename> is less |
| convenient. When using Docker, you may wish to make use of the |
| <parameter>enable-environment-properties</parameter> configuration |
| property, which allows you to specify values for arbitrary Guacamole |
| configuration properties using environment variables. This is covered in |
| <xref xmlns:xlink="http://www.w3.org/1999/xlink" |
| linkend="configuring-guacamole"/>. |
| </para> |
| </section> |
| <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> |