| <?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 the linked |
| <package>guacd</package> container and MySQL or PostgreSQL database will be |
| generated automatically when the image starts.</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. When properly linked to a <package>guacd</package> |
| container and either a PostgreSQL or MySQL database, the necessary Guacamole |
| configuration will be automatically generated at startup.</para> |
| <para>The name of the database and all associated credentials are specified with environment |
| variables given when the container is created. All other configuration information is |
| generated from the Docker links, and need only be explicitly provided if Docker is not |
| used to host the database.</para> |
| <important> |
| <para><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-mysql"> |
| <title>Deploying Guacamole with MySQL authentication</title> |
| <para>Before deploying Guacamole with the intent of using MySQL for authentication, |
| please ensure that you have each of the following already prepared:</para> |
| <orderedlist> |
| <listitem> |
| <para>A Docker container running the <systemitem>guacamole/guacd</systemitem> |
| image. Guacamole needs <package>guacd</package> in order to function, and |
| the Guacamole Docker image depends on a linked Docker container running |
| <package>guacd</package>.</para> |
| </listitem> |
| <listitem> |
| <para>A Docker container running the <systemitem>mysql</systemitem> image, |
| <emphasis>or</emphasis> network access to a working installation of |
| MySQL.</para> |
| </listitem> |
| </orderedlist> |
| <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> |
| <title xml:id="deploying-guacamole-docker-mysql">Deploying Guacamole</title> |
| <para>Linking Guacamole to MySQL will 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>Additional optional environment variables may be used to configure 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> |
| <para>Once your <package>guacd</package> container is ready, and the values of the |
| above variables are known, Guacamole can be deployed through Docker:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> --link <replaceable>some-guacd</replaceable>:guacd \ |
| --link <replaceable>some-mysql</replaceable>:mysql \ |
| -e MYSQL_DATABASE=<replaceable>guacamole_db</replaceable> \ |
| -e MYSQL_USER=<replaceable>guacamole_user</replaceable> \ |
| -e MYSQL_PASSWORD=<replaceable>some_password</replaceable> \ |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <para>The network connection information for MySQL is normally implied through the |
| "<property>mysql</property>" Docker link, and thus does not need to be |
| explicitly specified. 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 user that Guacamole will use to connect 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_POST</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 <replaceable>some-guacd</replaceable>:guacd \ |
| <emphasis>-e MYSQL_HOSTNAME=<replaceable>172.17.42.1</replaceable> \</emphasis> |
| -e MYSQL_DATABASE=<replaceable>guacamole_db</replaceable> \ |
| -e MYSQL_USER=<replaceable>guacamole_user</replaceable> \ |
| -e MYSQL_PASSWORD=<replaceable>some_password</replaceable> \ |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <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="verifying-guacamole-docker-mysql"> |
| <title>Verifying the Guacamole install</title> |
| <para>Now that 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.</para> |
| <para>If you cannot access Guacamole, check the logs using Docker 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> |
| <para>If Guacamole has been successfully installed, you will see the Guacamole login |
| screen. The database initialization scripts will create the default |
| administrative user as "<systemitem>guacadmin</systemitem>" with the password |
| "<systemitem>guacadmin</systemitem>". <emphasis>You should change your |
| password immediately after verifying that your login |
| works</emphasis>.</para> |
| <para>Once you have verified Guacamole has been deployed successfully, you can |
| create connections and add users through the web interface as described in <xref |
| xmlns:xlink="http://www.w3.org/1999/xlink" linkend="administration" |
| />.</para> |
| </section> |
| </section> |
| <section xml:id="guacamole-docker-postgresql"> |
| <title>Deploying Guacamole with PostgreSQL authentication</title> |
| <para>Before deploying Guacamole with the intent of using PostgreSQL for authentication, |
| please ensure that you have each of the following already prepared:</para> |
| <orderedlist> |
| <listitem> |
| <para>A Docker container running the <systemitem>guacamole/guacd</systemitem> |
| image. Guacamole needs <package>guacd</package> in order to function, and |
| the Guacamole Docker image depends on a linked Docker container running |
| <package>guacd</package>.</para> |
| </listitem> |
| <listitem> |
| <para>A Docker container running the <systemitem>postgresql</systemitem> image, |
| <emphasis>or</emphasis> network access to a working installation of |
| PostgreSQL.</para> |
| </listitem> |
| </orderedlist> |
| <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="deploying-guacamole-docker-postgresql"> |
| <title>Deploying Guacamole</title> |
| <para>Linking Guacamole to your PostgreSQL database will require 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>Additional optional environment variables may be used to configure 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> |
| <para>Once your <package>guacd</package> container is ready, and the values of the |
| above variables are known, Guacamole can be deployed through Docker:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> --link <replaceable>some-guacd</replaceable>:guacd \ |
| --link <replaceable>some-postgres</replaceable>:postgres \ |
| -e POSTGRES_DATABASE=<replaceable>guacamole_db</replaceable> \ |
| -e POSTGRES_USER=<replaceable>guacamole_user</replaceable> \ |
| -e POSTGRES_PASSWORD=<replaceable>some_password</replaceable> \ |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <para>The network connection information for PostgreSQL is normally implied through |
| the "<property>postgres</property>" Docker link, and thus does not need to be |
| explicitly specified. 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 user that Guacamole will use to connect 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_POST</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 <replaceable>some-guacd</replaceable>:guacd \ |
| <emphasis>-e POSTGRES_HOSTNAME=<replaceable>172.17.42.1</replaceable> \</emphasis> |
| -e POSTGRES_DATABASE=<replaceable>guacamole_db</replaceable> \ |
| -e POSTGRES_USER=<replaceable>guacamole_user</replaceable> \ |
| -e POSTGRES_PASSWORD=<replaceable>some_password</replaceable> \ |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <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="verifying-guacamole-docker-postgresql"> |
| <title>Verifying the Guacamole install</title> |
| <para>Now that 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.</para> |
| <para>If you cannot access Guacamole, check the logs using Docker 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> |
| <para>If Guacamole has been successfully installed, you will see the Guacamole login |
| screen. The database initialization scripts will create the default |
| administrative user as "<systemitem>guacadmin</systemitem>" with the password |
| "<systemitem>guacadmin</systemitem>". <emphasis>You should change your |
| password immediately after verifying that your login |
| works</emphasis>.</para> |
| <para>Once you have verified Guacamole has been deployed successfully, you can |
| create connections and add users through the web interface as described in <xref |
| xmlns:xlink="http://www.w3.org/1999/xlink" linkend="administration" |
| />.</para> |
| </section> |
| </section> |
| <section xml:id="guacamole-docker-ldap"> |
| <title>Deploying Guacamole with LDAP authentication</title> |
| <para>Before deploying Guacamole with the intent of using LDAP for authentication, |
| please ensure that you have each of the following already prepared:</para> |
| <orderedlist> |
| <listitem> |
| <para>A Docker container running the <systemitem>guacamole/guacd</systemitem> |
| image. Guacamole needs <package>guacd</package> in order to function, and |
| the Guacamole Docker image depends on a linked Docker container running |
| <package>guacd</package>.</para> |
| </listitem> |
| <listitem> |
| <para>Network access to a working LDAP server.</para> |
| </listitem> |
| </orderedlist> |
| <section xml:id="deploying-guacamole-docker-ldap"> |
| <title>Deploying Guacamole</title> |
| <para>Linking Guacamole to your LDAP directory will require additional configuration |
| parameters specified via environment variables. These variables collectively |
| describe how Guacamole will connect to LDAP:</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_HOSTNAME</envar></entry> |
| <entry> |
| <para>The hostname or IP address of your LDAP server.</para> |
| </entry> |
| </row> |
| <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>Additional optional environment variables may be used to configure the details |
| of your LDAP directory hierarchy, encryption, 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_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> |
| <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>Once your <package>guacd</package> container is ready, and the values of the |
| above variables are known, Guacamole can be deployed through Docker:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> --link <replaceable>some-guacd</replaceable>:guacd \ |
| -e LDAP_HOSTNAME=<replaceable>172.17.42.1</replaceable> \ |
| -e LDAP_USER_BASE_DN=<replaceable>ou=people,dc=example,dc=com</replaceable> \ |
| -e LDAP_CONFIG_BASE_DN=<replaceable>ou=connections,dc=example,dc=com</replaceable> \ |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <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. By providing the required environment variables for both systems, |
| Guacamole will automatically be configured to use both when the Docker image |
| starts:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <command>docker</command> run --name <replaceable>some-guacamole</replaceable> --link <replaceable>some-guacd</replaceable>:guacd \ |
| -e LDAP_HOSTNAME=<replaceable>172.17.42.1</replaceable> \ |
| -e LDAP_USER_BASE_DN=<replaceable>ou=people,dc=example,dc=com</replaceable> \ |
| -e LDAP_CONFIG_BASE_DN=<replaceable>ou=connections,dc=example,dc=com</replaceable> \ |
| <emphasis>-e MYSQL_HOSTNAME=<replaceable>172.17.42.1</replaceable> \ |
| -e MYSQL_DATABASE=<replaceable>guacamole_db</replaceable> \ |
| -e MYSQL_USER=<replaceable>guacamole_user</replaceable> \ |
| -e MYSQL_PASSWORD=<replaceable>some_password</replaceable> \</emphasis> |
| -d -p 8080:8080 guacamole/guacamole</screen> |
| </informalexample> |
| <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="verifying-guacamole-auth-ldap"> |
| <title>Verifying the Guacamole install</title> |
| <para>Now that 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.</para> |
| <para>If you cannot access Guacamole, check the logs using Docker 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> |
| <para>If Guacamole has been successfully installed, you will see the Guacamole login |
| screen, and should be able to login using an LDAP account beneath |
| <envar>LDAP_USER_BASE_DN</envar>. You will be able to access any connections |
| defined within <envar>LDAP_CONFIG_BASE_DN</envar> for which your user has |
| access. If a MySQL or PostgreSQL database has also been configured, and your |
| user has an account within that database, you will also be able to access your |
| connections from that database.</para> |
| </section> |
| </section> |
| </section> |
| </chapter> |
