【Guacamole中文文档】二、用户指南 —— 3.用Docker安装Guacamole

用Docker安装Guacamole

可以使用Docker部署Guacamole，无需从源代码构建guacamole-server或手动配置web应用程序。Guacamole项目为Guacamole和guacd提供了官方支持的Docker图像，并在每次发布时保持最新。

Guacamole典型的Docker部署方式将涉及三个单独的容器，在创建时连接在一起：

• guacamole/guacd

  提供guacd守护进程，从guacamole-server源码构建，支持VNC、RDP、SSH、telnet以及Kubernetes协议。

• guacamole/guacamole

  提供运行在Tomcat 8上的Guacamole Web应用程序，支持WebSocket。当基于Docker链接或环境变量启动时，将自动生成连接到guacd，MySQL ，PostgreSQL ，LDAP等所需的配置。

• MysqL或postgresql

  提供Guacamole用于身份验证和存储连接配置数据的数据库。

这种分离很重要，因为它有助于升级并保持适当的关注点分离。由于数据库与Guacamole和guacd分开，这些容器可以随意销毁和重新制作。唯一必须通过升级来维持数据的容器是数据库。

运行guacd的Docker镜像

guacd的Docker镜像从guacamole-server的发行版源代码中以支持VNC，RDP，SSH，telnet和Kubernetes的方式构建。常见如安装所需的依赖项、为SSH、telnet或Kubernetes安装字体，以及确保将FreeRDP插件安装到正确的位置等陷阱都得到了解决。它将简单地只是运转。

运行Guacamole的Docker镜像使用的guacd

当运行guacd映像以链接到Guacamole容器时，网络上不需要暴露任何端口。链接期间，Docker将自动处理对这些端口的访问，Guacamole镜像将正确检测和配置与guacd的连接。

$ docker run --name some-guacd -d guacamole/guacd

以这种方式运行时，guacd将在默认端口4822上持续侦听，但该端口将仅对已显式链接到some-guacd的Docker容器可用。

guacd的日志等级可以通过GUACD_LOG_LEVEL环境变量控制。默认值是info，且可以被设置成guacd日志标志（-L）的任何有效设置。

$ docker run -e GUACD_LOG_LEVEL=debug -d guacamole/guacd

运行guacd供Docker外的服务使用

如果你不打算使用Guacamole镜像，你仍然可以利用guacd镜像来方便地安装和维护。通过公开guacd端口4822，Docker外部的服务将能够访问到guacd。

❗重点:
执行此操作时要格外小心，guacd是一个被动代理，不执行任何类型的身份验证。
如果你没有将guacd与网络中不受信任的部分正确隔离，恶意用户可能会将guacd用作其他系统的跳转点。

$ docker run --name some-guacd -d -p 4822:4822 guacamole/guacd

guacd现在将监听4822端口，Docker将在托管Docker的同一服务器上公开该端口。其他服务，例如在Docker外部运行的Tomcat实例，将能够直接连接到该guacd。

Guacamole的Docker镜像

Guacamole的Docker镜像构建在标准Tomcat 8镜像之上，并自动处理所有配置。在创建容器时，使用环境变量或Docker链接指定了guacd和各种身份验证机制所需的配置信息。

❗重点:
如果使用Postgresql或MysqL进行身份验证，需要手动初始化数据库。Guacamole不会自动生成它的数据表，但会提供所需的sql脚本。

Guacamole镜像运行后，就可以通过http://*HOSTNAME*:8080/guacamole/链接访问Guacamole，其中HOSTNAME是托管Docker服务的机器的主机名或IP地址。

用Docker方式启动时配置Guacamole

使用Docker运行Guacamole时，通过编辑guacamole.properties来配置Guacamole的传统方法不太方便。在使用Docker方式时，你可能希望使用enable-environment-properties配置属性，以允许使用环境变量为任意Guacamole配置属性指定值。将在《配置Guacamole》章节中进行介绍。

连接Guacamole到guacd

Guacamole的Docker镜像需要能够连接到guacd以建立远程桌面连接，就像任何其他Guacamole部署一样。Guacamole所需的连接信息将通过Docker链接或环境变量提供。

如果你将使用Docker提供guacd，并且希望使用Docker链接将Guacamole镜像连接到guacd，连接详情暗含在Docker链接中：

$docker run --name some-guacamole \
    --link some-guacd:guacd        \
    ...
    -d -p 8080:8080 guacamole/guacamole

如果你不是通过Docker提供的guacd，你需要使用额外的环境变量提供网络连接信息：

• GUACD_HOSTNAME

  guacd实例用于建立远程桌面连接的主机名。如果没有通过Docker方式来提供guacd则需要这一项。

• GUACD_POST

  Guacamole连接到guacd时使用的端口。该环境变量是可选的。如果没有提供，则会使用标准的guacd端口，4822。

因此，如果不能或不希望使用Docker链接的方式，则可以使用GUACD_HOSTNAME和GUACD_PORT环境变量来替代：

$ docker run --name some-guacamole \
    -e GUACD_HOSTNAME=172.17.42.1  \
    -e GUACD_PORT=4822             \
    ...
    -d -p 8080:8080 guacamole/guacamole

要想让Guacamole发挥作用，与guacd的连接并不是唯一的要求；还需要配置一些身份验证机制。MySQL、PostgreSQL和LDAP在这方面都是受支持的，下面的章节将对此进行更详细的描述。如果没有提供至少一种身份验证机制所需的配置选项，Guacamole镜像将无法启动，并且你将会看到一个错误。

MysqL身份验证

以MysqL身份验证后端机制使用Guacamole，你需要运行MysqL镜像的Docker容器，或通过网络访问MysqL运转设备。可以使用环境变量或Docker链接指定MysqL的连接。

初始化MysqL数据库

如果数据库尚未使用Guacamole模式初始化，则需要在使用Guacamole之前进行初始化。Guacamole镜像中包含了一个方便的脚本，用于生成执行此操作所需的sql。

生成用于初始化新MysqL数据库的sql脚本（如《数据库身份验证》中所述），请执行以下操作：

$ docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --MysqL > initdb.sql

或者，可以使用《数据库身份验证》中包含的sql脚本。生成此脚本后，你必须：

1. 在MysqL中为Guacamole创建一个数据库，如guacamole_db。
2. 在MysqL中为Guacamole创建一个可以访问该数据库的用户，如guacamole_user。
3. 在新创建的数据库上运行上述生成的sql脚本。

通过MysqL附带的MysqL实用程序执行此操作的过程记录在《数据库身份验证》。

连接Guacamole到MysqL

如果你的MysqL数据库是被其他Docker容器提供的，并且你希望使用一个Docker链接连通Guacamole镜像和你的数据库，连接详情暗含在Docker链接中：

$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    --link some-MysqL:MysqL        \
    ...
    -d -p 8080:8080 guacamole/guacamole

如果你不是通过Docker来提供你的MysqL数据库，你需要使用额外的环境变量来提供你的数据库网络连接信息：

• MysqL_HOSTNAME

  Guacamole身份验证使用的数据库的主机名。如果你没有通过Docker来提供你的MysqL数据库，则需要该项。

• MysqL_PORT

  Guacamole连接到MysqL时使用的端口。该环境变量是可选的。如果没有提供，则会使用标准的MysqL服务端口，3306。

因此，如果不能或不希望通过Docker链接的方式，MysqL_HOSTNAME和MysqL_PORT环境变量可以用于替代：

$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    -e MysqL_HOSTNAME=172.17.42.1  \
    ...
    -d -p 8080:8080 guacamole/guacamole

注意，与MysqL的Docker链接一样，也可以不需要guacd的Docker链接（上述--link some-guacd:guacd选项）。guacd的连接信息可以使用环境变量指定，如《连接Guacamole到guacd》章节中所述。

必须的环境变量

使用MysqL进行身份验证需要通过环境变量指定其他配置参数。这些变量共同描述了Guacamole将如何连接到MysqL：

• MysqL_DATABASE

  Guacamole身份验证使用的数据库名称。

• MysqL_USER

  Guacamole用于连接MysqL的数据库用户。

• MysqL_PASSWORD

  Guacamole使用MysqL_USER连接MysqL数据库时使用的密码。

省略了任何必需的环境变量，都将在日志中收到一条错误消息，镜像将停止运行。然后需要使用指定的正确的变量重新创建容器。

可选的环境变量

对于一个或多个用户并发使用的连接，可以使用其他可选环境变量来覆盖Guacamole的默认行为。连接和连接组的并发使用可以限制为一个总的最大值和（或）每用户的最大值：

• MysqL_ABSOLUTE_MAX_CONNECTIONS

  在任何时候允许的并发连接的绝对最大数量，无论涉及的是Guacamole连接还是用户参与。如果设置为0，则表示没有限制。由于此限制适用于所有Guacamole连接，因此如果设置此限制，则无法覆盖。

  默认情况下，并发连接的绝对总数是没有限制的（0）。

• MysqL_ABSOLUTE_MAX_CONNECTIONS

  允许任何一个Guacamole连接的最大并发连接数。如果设置为0，则表示没有限制。编辑连接时，可以在每个连接的基础上覆盖此选项。

  默认情况下，连接的总体并发使用是没有限制的（0）。

• MysqL_DEFAULT_MAX_GROUP_CONNECTIONS

  允许连接到任何一个Guacamole连接组的最大并发连接数。如果设置为0，则表示没有限制。在编辑连接组时，可以基于每个组覆盖此选项。

  默认情况下，连接组的总体并发使用是没有限制的（0）。

• MysqL_DEFAULT_MAX_CONNECTIONS_PER_USER

  允许单个用户维护任何一个Guacamole连接的最大并发连接数。如果设置为0，则表示没有限制。编辑连接时，可以在每个连接的基础上覆盖此选项。

  默认情况下，每个用户并发使用的连接是没有限制的（0）。

• MysqL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER

  允许单个用户维护任何一个Guacamole连接组的最大并发连接数。如果设置为0，则表示没有限制。在编辑连接组时，可以基于每个组覆盖此选项。
  默认情况下，每个用户并发使用的连接组仅限于一个（1），以防止平衡连接组被一个用户完全耗尽。

• MysqL_AUTO_CREATE_ACCOUNTS

  当通过其他模块成功验证时，MysqL数据库中不存在的帐户是否会自动创建。如果设置为true，将自动创建帐户。否则，默认情况下，不会自动创建帐户，需要手动创建帐户，以便将MysqL数据库扩展中的权限分配给通过其他模块验证的用户。

Postgresql身份验证

以Postgresql身份验证后端机制使用Guacamole，你需要运行postgres镜像的Docker容器，或通过网络访问Postgresql运转设备。可以使用环境变量或Docker链接指定Postgresql的连接。

初始化Postgresql数据库

如果数据库尚未使用Guacamole模式初始化，则需要在使用Guacamole之前进行初始化。Guacamole镜像中包含了一个方便的脚本，用于生成执行此操作所需的sql。

生成用于初始化新Postgresql数据库的sql脚本（如《数据库身份验证》中所述），请执行以下操作：

$ docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgres > initdb.sql

或者，可以使用《数据库身份验证》中包含的sql脚本。生成此脚本后，你必须：

1. 在Postgresql中为Guacamole创建一个数据库，如guacamole_db。
2. 在新创建的数据库上运行上述生成的sql脚本。
3. 在Postgresql中为Guacamole创建一个可以访问该数据库的表和序列的用户，如guacamole_user。

通过Postgresql附带的psql和createdb实用程序执行此操作的过程记录在《数据库身份验证》。

连接Guacamole到Postgresql

如果你的Postgresql数据库是被其他Docker容器提供的，并且你希望使用一个Docker链接连通Guacamole镜像和你的数据库，连接详情暗含在Docker链接中：

$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    --link some-postgres:postgres  \
    ...
    -d -p 8080:8080 guacamole/guacamole

如果你不是通过Docker来提供你的Postgresql数据库，你需要使用额外的环境变量来提供你的数据库网络连接信息：

• POSTGRES_HOSTNAME

  Guacamole身份验证使用的数据库的主机名。如果你没有通过Docker来提供你的Postgresql数据库，则需要该项。

• POSTGRES_PORT

  Guacamole连接到Postgresql时使用的端口。该环境变量是可选的。如果没有提供，则会使用标准的Postgresql服务端口，5432。

因此，如果不能或不希望通过Docker链接的方式，POSTGRES_HOSTNAME和POSTGRES_PORT环境变量可以用于替代：

$ docker run --name some-guacamole   \
    --link some-guacd:guacd          \
    -e POSTGRES_HOSTNAME=172.17.42.1 \
    ...
    -d -p 8080:8080 guacamole/guacamole

注意，与Postgresql的Docker链接一样，也可以不需要guacd的Docker链接（上述--link some-guacd:guacd选项）。guacd的连接信息可以使用环境变量指定，如《连接Guacamole到guacd》章节中所述。

必须的环境变量

使用Postgresql进行身份验证需要通过环境变量指定其他配置参数。这些变量共同描述了Guacamole将如何连接到Postgresql：

• POSTGRES_DATABASE

  Guacamole身份验证使用的数据库名称。

• POSTGRES_USER

  Guacamole用于连接Postgresql的数据库用户。

• POSTGRES_USER

  Guacamole使用POSTGRES_USER连接Postgresql数据库时使用的密码。

省略了任何必需的环境变量，都将在日志中收到一条错误消息，镜像将停止运行。然后需要使用指定的正确的变量重新创建容器。

可选的环境变量

对于一个或多个用户并发使用的连接，可以使用其他可选环境变量来覆盖Guacamole的默认行为。连接和连接组的并发使用可以限制为一个总的最大值和（或）每用户的最大值：

• POSTGRES_ABSOLUTE_MAX_CONNECTIONS

  在任何时候允许的并发连接的绝对最大数量，无论涉及的是Guacamole连接还是用户参与。如果设置为0，则表示没有限制。由于此限制适用于所有Guacamole连接，因此如果设置此限制，则无法覆盖。

  默认情况下，并发连接的绝对总数是没有限制的（0）。

• POSTGRES_DEFAULT_MAX_CONNECTIONS

  允许任何一个Guacamole连接的最大并发连接数。如果设置为0，则表示没有限制。编辑连接时，可以在每个连接的基础上覆盖此选项。

  默认情况下，连接的总体并发使用是没有限制的（0）。

• POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS

  允许连接到任何一个Guacamole连接组的最大并发连接数。如果设置为0，则表示没有限制。在编辑连接组时，可以基于每个组覆盖此选项。

  默认情况下，连接组的总体并发使用是没有限制的（0）。

• POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER

  允许单个用户维护任何一个Guacamole连接的最大并发连接数。如果设置为0，则表示没有限制。编辑连接时，可以在每个连接的基础上覆盖此选项。

  默认情况下，每个用户并发使用的连接是没有限制的（0）。

• POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER

  允许单个用户维护任何一个Guacamole连接组的最大并发连接数。如果设置为0，则表示没有限制。在编辑连接组时，可以基于每个组覆盖此选项。
  默认情况下，每个用户并发使用的连接组仅限于一个（1），以防止平衡连接组被一个用户完全耗尽。

• POSTGRES_AUTO_CREATE_ACCOUNTS

  当通过其他模块成功验证时，Postgresql数据库中不存在的帐户是否会自动创建。如果设置为true，将自动创建帐户。否则，默认情况下，不会自动创建帐户，需要手动创建帐户，以便将Postgresql数据库扩展中的权限分配给通过其他模块验证的用户。

可选环境变量也可用于覆盖Guacamole在数据库和网络级别的默认超时行为：

• POSTGRES_DEFAULT_STATEMENT_TIMEOUT

  驱动程序在中止查询之前等待数据库响应的秒数。默认值为0表示超时被禁用。

• POSTGRES_SOCKET_TIMEOUT

  等待套接字读取操作的秒数。如果从服务器读取数据的时间长于此值，则连接将关闭。这可用于处理网络问题，例如与数据库的连接断开。与POSTGRES_DEFAULT_STATEMENT_TIMEOUT类似，它还将中止耗时过长的查询。默认值为0表示超时被禁用。

LDAP身份验证

以LDAP身份验证后端机制使用Guacamole，需要对LDAP目录进行网络访问。与MysqL和Postgresql不同，Guacamole的Docker镜像不支持LDAP的Docker链接，必须使用环境变量指定连接信息：

• LDAP_HOSTNAME

  你的LDAP服务的主机名或IP地址。

• LDAP_PORT

  你的LDAP服务监听的端口。默认情况下，对于未加密的LDAP或使用STARTTLS的LDAP，是389，对于通过SSL加密的LDAP（LDAPS），这将是636。

• LDAP_ENCRYPTION_METHOD

  与LDAP服务器通信时，Guacamole应该使用的加密机制。对于未加密的LDAP，合法值为none；对于通过SSL/TLS加密的LDAP，合法值为ssl（通常称为LDAPS）；对于使用STARTTLS的LDAP，合法值为starttls。如果省略，将不使用加密。

只有LDAP_HOSTNAME变量是必须的，但如果你的LDAP目录使用加密或监听在非标准端口，则你可能仍需要指定LDAP_PORT或LDAP_ENCRYPTION_METHOD：

$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    -e LDAP_HOSTNAME=172.17.42.1   \
    ...
    -d -p 8080:8080 guacamole/guacamole

注意，guacd的Docker链接（上述--link some-guacd:guacd选项）不是必须的，与LDAP类似，guacd的连接信息可以使用环境变量指定，就如《连接Guacamole到guacd》中所述。

必须的环境变量

使用LDAP进行身份验证需要通过环境变量指定其他配置参数。这些变量共同描述了Guacamole将如何查询LDAP目录：

• LDAP_USER_BASE_DN

  所有Guacamole用户的DN基础。所有将根据LDAP进行身份验证的Guacamole用户必须是此基本DN的后代。

与其他身份验证机制一样，如果省略了任何必需的环境变量（包括通过网络连接到LDAP目录所需的环境变量），都将在日志中收到错误消息，镜像将停止。然后需要使用指定的适当变量重新创建容器。

可选的环境变量

其他可选环境变量可用于配置LDAP目录层次结构的详细信息，或支持更灵活的用户帐户搜索：

• LDAP_GROUP_BASE_DN

  使用标准seeAlso属性的Guacamole配置中可能引用的所有组的DN基础。用于控制Guacamole配置访问的所有组都必须是此基本DN的后代。如果省略此变量，seeAlso属性对Guacamole配置将没有影响。

• LDAP_GROUP_SEARCH_FILTER

  其他扩展可能用于定义权限的组用于查询LDAP树的搜索筛选器。如果省略此属性，则使用默认值（objectClass=*）。

• LDAP_SEARCH_BIND_DN

  验证试图登录的用户时要绑定的用户的DN（可分辨名称）。如果指定，Guacamole将查询LDAP目录，以确定每个登录用户的DN。如果省略，每个用户的DN将使用LDAP_USER_BASE_DN指定的基本DN直接派生。

• LDAP_SEARCH_BIND_PASSWORD

  作为LDAP_SEARCH_BIND_DN进行绑定以验证其他用户时提供给LDAP服务器的密码。此变量仅在指定LDAP_SEARCH_BIND_DN时使用。如果省略，但指定了LDAP_SEARCH_BIND_DN，Guacamole将尝试在没有密码的情况下与LDAP服务器绑定。

• LDAP_USERNAME_ATTRIBUTE

  LDAP目录中所有Guacamole用户对象中包含用户名的一个或多个属性。通常，默认情况下，这将只是uid。如果LDAP目录包含用户名由不同属性指定的用户，则可以在此处指定多个属性，并用逗号分隔，但请注意：这样做需要在LDAP_search_BIND_DN中提供搜索DN。

• LDAP_CONfig_BASE_DN

  所有Guacamole配置的DN基础。如果省略，将无法从LDAP目录中查询Guacamole连接的配置，你需要将它们存储在其他位置，例如MysqL或Postgresql数据库中。

正如《LDAP身份验证》中所述，Guacamole确实支持将LDAP与MysqL或Postgresql数据库相结合，且也可以通过Guacamole的Docker镜像进行配置。每个认证机制都可以使用各自的环境变量独立配置，通过为多个系统提供所需的环境变量，Guacamole将自动配置为在Docker镜像启动时使用每个机制。

Header身份验证

Header身份验证扩展可用于通过受信任的第三方服务对Guacamole进行身份验证，在该服务上，经过身份验证的用户的用户名通过特定的HTTP标头传递回Guacamole。以下是用于启用和配置header身份验证的有效Docker变量：

• HEADER_ENABLED

  启用通过header扩展进行身份验证，这会导致Guacamole启动时加载扩展。默认值是false，不会加载header扩展名。

• HEADER_ENABLED

  可选环境变量，如果设置了该变量，将配置HTTP头的名称，该头将用于验证用户是否使用Guacamole。如果未指定，将使用默认值REMOTE_USER。

自定义扩展以及GUACAMOLE_HOME

如果你有自己的或第三方的Guacamole扩展，它不被Guacamole的Docker镜像所支持，但与镜像中的Guacamole版本兼容，你仍然可以通过使用GUACAMOLE_HOME环境变量提供自定义基本配置来使用它们：

• GUACAMOLE_HOME

  Docker容器中用作镜像自动生成GUACAMOLE_HOME 模板的目录的绝对路径。Guacamole的Docker镜像基于其他环境变量生成的任何配置都将应用于该目录内容的独立副本。

你还需要按照特定于你的扩展的创建GUACAMOLE_HOME内容所需的步骤（将扩展本身放在GUACAMOLE_HOME/extensions/中，向guacamole.properties添加任何属性等），但GUACAMOLE的其余配置将自动处理，覆盖在你提供的GUACAMOLE_HOME的副本上。

Docker镜像的GUACAMOLE_HOME环境变量必须指向容器中的一个目录，因此你需要通过docker run命令的-v选项将自定义的GUACAMOLE_HOME暴露给容器。然后，选择的容器目录可以在GUACAMOLE_HOME环境变量中引用，且镜像将自动处理剩余的配置。

$ docker run --name some-guacamole    \
    ...
    -v /local/path:/some-directory   \
    -e GUACAMOLE_HOME=/some-directory \
    -d -p 8080:8080 guacamole/guacamole

验证Guacamole安装

一旦Guacamole镜像开始运行，Guacamole可以在 http://HOSTNAME:8080/guacamole/进行访问，其中HOSTNAME是Docker主机的主机名或IP地址，并且你可以看到一个登录界面。如果你使用MysqL或Postgresql进行身份验证后端，数据库初始化脚本将创建一个名为guacadmin的默认管理用户，密码是guacadmin。你应该立刻登录并修改密码。如果是使用LDAP方式，你可以用任何LDAP目录中的有效用户进行登录。

如果你无法访问Guacamole网站，或没有看到登录界面，请使用docker logs命令检查容器日志，以确定是否有问题。可能是配置参数不正确或者是数据库没有正确初始化：

$ docker logs some-guacamole