配置Guacamole

Guacamole安装后，需要配置用户和连接，才能正常工作。本章介绍Guacamole的一般配置及其默认身份验证方法的使用。

Guacamole的默认身份验证方法从一个名为user-mapping.xml的单一文件读取用户和连接。此身份验证方法旨在：

  1. 极小化部署Guacamole。
  2. 以一种相对简单的方法来验证Guacamole是否被正确装配。

其他更复杂的身份验证方法（如使用后端数据库、LDAP等）将在单独的专门地章节中讨论。

无论使用何种身份验证方法，Guacamole的配置始终由两个主要部分组成：一个称为GUACAMOLE_HOME的目录，它是配置文件的主要搜索位置，以及Guacamole及其扩展名使用的主配置文件，guacamole.properites。

GUACAMOLE_HOME（/etc/guacamole）

GUACAMOLE_HOME是Guacamole配置目录的名称，默认情况下，位于/etc/guacamole。所有的配置文件，扩展等都位于整个目录下。GUACAMOLE_HOME的结构经过严格定义，由以下可选文件组成：

  • guacamole.properties

    是主要的Guacamole配置文件。此文件中的属性指示Guacamole如何连接到guacd，且可以配置已安装的身份验证扩展的行为。

  • logback.xml

    Guacamole使用名为Logback的日志系统来记录所有消息。默认情况下，Guacamole仅将日志输出到控制台，但可以通过提供自己的Logback配置文件来更改该行为。

  • extensions/

    所有Guacamole扩展的安装位置。Guacamole将在启动时自动加载该目录下的所有.jar文件。

  • lib/

    任意Guacamole扩展所需库的搜索目录。Guacamole将使该目录下的.jar文件对所有扩展可用。如果你的扩展需要额外的库，比如数据库驱动，那么这是放置他们的恰当位置。

重载GUACAMOLE_HOME

如果你不能或不想使用/etc/guacamole作为GUACAMOLE_HOME，该位置可以通过以下任意方法进行重载：

  1. 在运行servlet容器的用户的家目录创建一个名为.guacamole的目录。如果该目录存在，则将自动被用作GUACAMOLE_HOME。
  2. 使用环境变量GUACAMOLE_HOME指定替代目录的完整路径。请务必参考你的servlet容器的文档，以确定如何正确设置环境变量。
  3. 通过系统属性guacamole.home指定替代目录的完整路径。

guacamole.properties

guacamole.properties使Guacamole web应用使用的一个主要配置文件。该文件是Guacamole或任意Guacamole扩展（包括身份提供程序）读取所有配置属性的通用位置。

在之前的版本中，该文件必须位于你的servlet容器的classpath中。现在，guacamole.properties的位置可以用环境变量或系统属性显式定义，classpath只能作为最后手段使用。搜索guacamole.properties时，Guacamole将按如下顺序查看：

  1. 先在上述定义的GUACAMOLE_HOEM中查看。
  2. 如果没有，再在servlet容器的classpath下查看。

guacamole.properties文件是可选的，用于在默认值不充分的情况下配置Guacamole，或为扩展提供附加配置信息。有几个标准属性是始终可用的：

  • api-session-timeout

    允许Guacamole会话（身份验证令牌）在不活动的情况下保持有效的时间量，以分钟为单位。如果省略，Guacamole不活动的会话将在60分钟后过期。

  • api-max-request-size

    在任何特定HTTP请求的实体主体中要接受的最大字节数，其中0表示没有任何限制。如果省略，默认情况下，请求将被限制为2097152字节（2MB）。此限制不适用于文件上传。

    如果使用一个反向代理代理SSL终端，谨记，反向代理可能会独立于此实施自己的限制。例如，默认情况下，Nginx将强制执行1MB请求大小限制。

  • allowed-languages

    以逗号分隔的语言关键字白名单，允许在Guacamole界面中显示的语言选项。例如，要将Guacamole仅限于英语和德语，可以指定：

    allowed-languages: en, de

    由于英语是备用语言，在所选语言中缺少翻译键时使用，因此只有在绝对肯定没有字符串丢失的情况下，才应从该列表中删除英语。

    此处未列出的任何内置语言的相应JSON仍将通过HTTP提供，但Guacamole界面不会使用它们，也不会基于本地浏览器语言自动使用它们。如果省略，所有定义的语言都将可用。

  • enable-environment-properties

    如果设置为true，则在使用guacamole.properties中指定的值或返回默认值之前，Guacamole将首先评估其环境变量，以获取任意给定配置属性的值。通过启用此选项，可以使用环境变量轻松覆盖任何其他配置属性。

    enable-environment-properties: true

    在环境变量中搜索配置属性时，首先转换属性的名称，方法是将所有小写字符转换为等效的大写字符，并将所有连字符（-）替换为下划线字符（_）。例如，在搜索环境变量时，guacd-hostname属性将被转换为GUACD_HOSTNAME。

  • extension-priority

    应按特定顺序加载的所有扩展的名称空间的逗号分隔列表。可以使用特殊值*代替名称空间来表示未列出的所有扩展。所有显式列出的扩展名将按给定的顺序排序，而所有未显式列出的扩展名将按其文件名排序。

    例如，为了确保首先加载对SAML的支持：

    extension-priority: saml

    或者确保最后加载对SAML的支持：

    extension-priority: *, saml

    如果不确定应用的名称空间或加载扩展的顺序，请查看Guacamole日志。所有已安装扩展的名称空间和加载顺序都被Guacamole在启动期间记录下来：

    ...
23:32:06.467 [main] INFO  o.a.g.extension.ExtensionModule - Multiple extensions are installed and will be loaded in order of decreasing priority:
23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [postgresql] "PostgreSQL Authentication" (/etc/guacamole/extensions/guacamole-auth-jdbc-postgresql-1.4.0.jar)
23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [ldap] "LDAP Authentication" (/etc/guacamole/extensions/guacamole-auth-ldap-1.4.0.jar)
23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [openid] "OpenID Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-openid-1.4.0.jar)
23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [saml] "SAML Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-saml-1.4.0.jar)
23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule - To change this order, set the "extension-priority" property or rename the extension files. The default priority of extensions is dictated by the sort order of their filenames.
...

  • guacd-hostname

    Guacamole代理守护程序（guacd）监听的host地址。如果省略，Guacamole将假定guacd监听在localhost上。

  • guacd-port

    Guacamole代理守护进程（guacd)监听的端口，如果省略，Guacamole将假定guacd监听4822端口。

  • guacd-ssl

    如果设置为true，Guacamole将要求web应用程序和guacd直接进行SSL/TLS加密。默认情况下，二者之间的通信是没有加密的。

    注意，如果启用此选项，还必须通过命令行选项将guacd配置为使用SSL。这些选项说明在guacd的参考页上（通过man guacd获取）。你将需要一个SSL证书和私钥。

  • skip-if-unavailable

    以逗号分隔的身份验证提供程序的标识符列表，应允许在不中止身份验证过程的情况下内部失败（即不会因某个验证程序失败而导致验证过程终止）。例如，请求Guacamole忽略由于LDAP目录或MySQL服务器意外关闭而导致的故障，从而允许其他身份验证提供程序继续运行：

    skip-if-unavailable: mysql, ldap

默认情况下，Guacamole对内部故障采取保守的方法，任何身份验证提供程序中出现内部错误都将中止身份验证过程。根据错误的性质，这可能意味着在解决故障原因之前，用户无法登录。skip-if-unavailable属性可用于明确告知Guacamole，一个或多个基础系统预计会偶尔出现故障，如果出现故障，则依赖其他方法系统。

一个典型的定义了guacd-hsotname和guacd-port属性明确值得guacamole.properties文件，如下所示：

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

Web应用程序中的日志记录

默认情况下，Guacamole记录所有消息到终端控制台。像Tomcat那样的servlet容器将会自动地将这些消息重定向到一个日志文件，Tomcat是catalina.out，你可以在Guacamole运行时读取该文件。根据消息的重要性和严重性，消息被记录成四种级别的日志：

  • error

    错误是致命的。尝试了日志消息中描述的操作，但无法继续，此操作失败是一个需要解决的严重问题。

  • warn

    警告通常是非致命条件。行动仍在继续，但遇到了值得注意的问题。

  • info

    ‎info消息纯粹是信息性的。它们可能对管理员有用或有趣，但对于一个Guacamole服务的正常运行通常并不重要。‎

  • debug

    调试消息非常详细，面向开发。大多数调试消息将包含堆栈跟踪和内部信息，这些信息在调查代码中的问题时非常有用。调试消息虽然冗长，但预计不会影响性能。

  • trace

    跟踪消息在意图和详细程度上与调试消息类似，但级别太低，可能会因其频率而影响性能。跟踪级别的日志记录很少是必要的，主要用于围绕所调查的问题提供非常详细的上下文 。

    Guacamole使用一个称为Logback 的日志框架来记录日志消息，默认情况下，将仅记录info或更高级别的消息。如果你想更改日志级别，或配置Guacamole记录消息的位置和方式，你可以通过在GUACAMOLE_HOME下提供自己的logback.xml配置文件来实现。例如，将debug级别的消息记录到控制台，你可以使用以下的logback.xml配置：

    <configuration>

    <!-- Appender for debugging -->
    <appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <!-- Log at DEBUG level -->
    <root level="debug">
        <appender-ref ref="GUAC-DEBUG"/>
    </root>

</configuration>

Guacamole和上面的示例只配置了一个appender来记录到控制台，但Logback非常灵活，允许任意数量的appende（每个appender都可以记录到单独的文件、控制台等），这些appender基于一些列标准，包括日志级别和消息源。

Logback项目的网站上提供了有关配置Logback的更全面的文档。

使用默认身份验证机制

Guacamole的默认身份验证模块很简单，由用户名到配置的映射组成。该身份验证模块是Guacamole自带的，只需从一个XML文件中读取用户名和密码。它始终处于启用状态，但仅当XML文件存在时才会从中读取，并且相对于任何其他身份验证扩展，它的优先级始终是最后一个。

还有其他可用的身份验证模块。Guacamole项目提供了数据库后端支持的身份验证模块，能够从web界面管理连接和用户，并且其他身份验证模块可以使用随Guacamole web应用程序一起提供的扩展API（guacamole-ext）进行创建。

user-mapping.xml

Guacamole用于读取所有用户，密码和配置信息的默认身份验证提供者，是一个位于GUACAMOLE_HOME/user-mapping.xml的被称为user mapping的文件。Guacamole中包含的一个user mapping文件示例如下：

<user-mapping>

    <!-- Per-user authentication and config information -->
    <authorize username="USERNAME" password="PASSWORD">
        <protocol>vnc</protocol>
        <param name="hostname">localhost</param>
        <param name="port">5900</param>
        <param name="password">VNCPASS</param>
    </authorize>

    <!-- Another user, but using md5 to hash the password
         (example below uses the md5 hash of "PASSWORD") -->
    <authorize
            username="USERNAME2"
            password="319f4d26e3c536b5dd871bb2c52e3178"
            encoding="md5">

        <!-- First authorized connection -->
        <connection name="localhost">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

        <!-- Second authorized connection -->
        <connection name="otherhost">
            <protocol>vnc</protocol>
            <param name="hostname">otherhost</param>
            <param name="port">5900</param>
            <param name="password">VNCPASS</param>
        </connection>

    </authorize>

</user-mapping>

每个用户都指定了相应的<authorize>标签。这个标签包含该用户的所有授权连接，每个连接都用<connection>标签表示。每个<connection>标签都包含一个相应的协议和一组特定于协议的参数，分别用<protocol>和<param>标签指定。

添加用户

使用user-mapping.xml时，username/password对由<authorize>标签指定，每个标签都有username和password属性。每个<authorize>标签都授权特定的username/password对来访问标记内的所有连接：

<authorize username="USER" password="PASS">
    ...
</authorize>

在上面的例子中，密码将以明文形式列出。如果不想这样做，也可以使用MD5哈希指定密码：

<authorize username="USER"
           password="319f4d26e3c536b5dd871bb2c52e3178"
           encoding="md5">
    ...
</authorize>

修改user-mapping.xml后，Guacamole将自动重新读取该文件，你的更改将立即生效。新添加的用户将能够登录——无需重新启动servlet容器。

向用户添加连接

要在<authorize>标签中指定连接，可以列出单个协议和一组参数（使用<protocol>标签和任意数量的<param>标签指定），在这种情况下，用户将只能访问一个名为DEFAULT的连接，或者可以使用一个或多个<connection>标签指定一个或多个连接，每个都可以命名，并包含一个<protocol>标签和任意数量的<param>标签。

配置连接

Guacamole支持的每个协议都有自己的一组配置参数。这些参数通常描述远程桌面服务器的主机名和端口、连接时要使用的凭据（如果有），以及显示器的大小和颜色深度。如果协议支持文件传输，则还将提供启用该功能的选项。

VNC

VNC协议是Guacamole支持的最简单也是第一个协议。虽然通常没有RDP那么快，但多数VNC服务器已经足够了，并且Guacamole上的VNC往往比VNC本身更快，因为带宽使用率降低了。

Guacamole的VNC支持由libguac-client-vnc库提供，如果构建过程中存在依赖要求，则会作为guacamole-server的一部分进行安装。

！注意：
除了下面VNC特定的参数外，Guacamole的VNC支持还接受Guacamole为多个协议提供的某些功能的参数：
网络参数

除了反向模式的VNC连接之外，VNC的工作原理是与运行一个或多个VNC服务器的特定主机建立出站网络连接。每个VNC服务器都与一个显示编号相关联，相应的端口号由此派生。

  • hostname

    Guacamole可能连接的VNC服务器的主机名或IP地址。

  • port

    VNC服务器监听的端口，通常为5900或5900+显示编号。例如，如果VNC服务器提供的是编号为1的显示（有时写为:1），那么这里的端口号将是5901。

  • autoretry

    在放弃并返回错误之前重试连接的次数。对于反向连接的情况，这是允许连接进程超时的次数。

身份验证

VNC标准仅定义基于密码的身份验证。其他身份验证机制也存在，但都是非标准或专有的。Guacamole目前既支持标准的仅基于密码的身份验证，也支持用户名和密码身份验证。

  • username

    尝试身份验证时使用的用户名（如果有）。此参数是可选的。

  • password

    尝试身份验证时使用的密码（如果有）。此参数是可选的。

显示设置

VNC服务器不允许客户端请求特定的显示尺寸，因此，在显示宽度和高度方面，将由你的VNC服务器决定。但是，为了减少带宽使用，你可以请求VNC服务器减少其颜色深度。Guacamole将自动检测256色图像，除了可以绝对保证通过强制将颜色深度设置为8位的通过连接发送的图形外。颜色深度由VNC服务器决定。

如果你注意到VNC的显示存在问题，例如缺少鼠标光标、存在多个鼠标光标或奇怪的颜色（例如蓝色看起来更像橙色或红色），这些通常是VNC服务器中的错误或限制造成的，可以使用额外的参数来解决这些问题。

  • color-depth

    请求的色彩深度，单位为比特/像素。该参数是可选的。如果指定，则必须是8、16、24或32。不管选择了什么值，如果某个特定更新使用的颜色少于256色，Guacamole将始终以256色PNG格式发送更新。

  • swap-red-blue

    如果你的显示器颜色显示错误（如蓝色显示为橙色或红色等），则可能是VNC服务器发送的图像数据不正确，并且每种颜色的红色和蓝色部分都被交换了。如果是这种情况，请将此参数设置为true以解决问题。该参数是可选的。

  • cursor

    如果设置为remote，鼠标指针将远程渲染，鼠标指针的本地位置将由一个小点指示。远程鼠标光标会感觉比本地光标慢，但如果VNC服务器不支持将光标图像发送到客户端，则可能需要远程鼠标光标。

  • encodings

    要使用的以空格分隔的VNC编码列表。此参数的格式由libvnclient指定，因此并不真正遵循其他Guacamole参数的结构。此参数是可选的，默认情况下，libguac-client-vnc将使用任意支持的编码。

    注意，在未来的版本中，此参数将被替换为单独的、编码特定的参数。

  • read-only

    该连接是否应为只读连接。如果设置为true，则连接上完全不接受任何输入。用户只会看到桌面以及使用同一桌面的其他用户正在执行的任何操作。该参数是可选的。

  • force-lossless

    该连接是否应对图形更新仅用无损压缩。如果设置为true，则不会使用有损压缩。此参数是可选的。默认情况下，当启发式算法确定有损压缩可能优于无损压缩时，将使用有损压缩。

VNC中继器

存在VNC中继器，例如UltraVNC中继器，它们充当中介或代理，提供单个逻辑VNC连接，然后将其路由到其他地方的另一个VNC服务器。需要额外的参数来选择中继器后面的哪个VNC主机将接收连接。

  • dest-host

    连接到VNC代理（如UltraVNC中继器）时请求的目标主机。只有在使用中的VNC代理要求连接用户指定要连接的VNC服务器时，才需要这样做。如果VNC代理自动连接到特定服务器，则不需要此参数。

  • dest-port

    连接到VNC代理（如UltraVNC中继器）时请求的目标端口。只有在使用中的VNC代理要求连接用户指定要连接的VNC服务器时，才需要这样做。如果VNC代理自动连接到特定服务器，则不需要此参数。

反向VNC连接

Guacamole支持“反向”VNC连接，其中VNC客户端监听来自VNC服务器的传入连接。当使用反向VNC连接时，VNC客户端和服务器会切换网络角色，但在其他方面，它们会正常工作。VNC服务器仍然提供远程显示，VNC客户端仍然提供所有键盘和鼠标输入。

  • reverse-connect

    是否应使用反向连接。如果设置为true，guacd将在给定的端口监听来自VNC服务器的入站连接，而不是连接到给定主机名和端口的服务器。

  • listen-timeout

    如果正在使用反向连接，则表示等待来自VNC服务器的入站连接的最长时间（毫秒）。如果为空，则默认为5000（5秒）。

音频支持（通过PulseAudio）

VNC不提供自己的音频支持，但Guacamole的VNC支持可以通过与VNC服务运行在同一台机器上的PulseaAudio服务的辅助网络连接来获取音频。

多数Linux系统通过一个名为PulseAudio的服务来提供音频。该服务能够通过网络进行通信，如果PulseAudio配置为允许TCP连接，Guacamole可以连接到PulseAudio服务器，并将其音频与通过VNC传输的图形相结合。

为网络连接配置PulseAudio需要附加一行到PulseAudio的配置文件中，通常为/etc/pulse/default.pa：

load-module module-native-protocol-tcp auth-ip-acl=192.168.1.0/24 auth-anonymous=1

这将加载PulseAudio的TCP模块，将其配置为只接受来自192.168.1.0/24子网的连接，且不进行身份验证。你需要将该值替换为guacd将要连接的子网或IP地址。允许从任何地方进行连接是可能的，但请注意，只有在网络的性质阻止未经授权的访问时，才应这样做：

load-module module-native-protocol-tcp auth-anonymous=1

无论哪种情况，都严格要求使用auth-anonymous=1参数。Guacamole目前不支持PulseAudio用于非匿名连接的基于cookie的身份验证。如果省略此参数，Guacamole将无法连接到PulseAudio。

正确修改PulseAudio配置文件后，重新启动PulseAudio服务。然后，PulseAudio应该开始监听端口4713（PulseAudio的默认端口）上监听传入的TCP连接。你可以使用netstat之类的工具来验证这一点：

$ netstat -ln | grep 4713
tcp        0      0 0.0.0.0:4713            0.0.0.0:*               LISTEN
tcp6       0      0 :::4713                 :::*                    LISTEN
$

以下参数可用于配置VNC的音频支持：

  • enable-audio

    如果设置为true，将启用音频支持，除VNC连接外，还将为PulseAudio建立第二个连接。默认情况下，VNC中的音频支持处于禁用状态。

  • audio-servername

    要连接的PulseAudio服务器的名称。这将是通过PulseAudio为你的连接提供音频的计算机的主机名，很可能与hostname参数的给定值相同。
    如果省略此参数，将使用默认的PulseAudio设备，即与guacd在同一台机器上运行的PulseAudio服务。

剪贴板编码

虽然Guacamole将始终使用UTF-8处理自己的剪贴板数据，但VNC标准要求剪贴板数据采用ISO 8859-1编码。由于大多数VNC服务器不接受任何其他格式的数据，因此在与VNC服务器交换剪贴板数据时，Guacamole将在UTF-8和ISO 8859-1之间转换，且该行为可以通过clipboard-encoding覆盖。

❗重点:
VNC服务器必然支持的唯一剪贴板编码是ISO 8859-1。如果VNC服务器支持其他编码，则只应使用clipboard-encoding参数覆盖剪贴板编码。

  • clipboard-encoding

    为VNC剪贴板假定的编码。此参数是可选的。默认情况下，将使用标准编码ISO 8859-1。只有在确定VNC服务器支持标准ISO 8859-1之外的其他编码时，才使用此参数。

    可能的值有：

    • ISO8859-1

      ISO 8859-1是VNC标准规定的剪贴板编码，仅支持基本拉丁字符。除非你的VNC服务器另有规定，否则这种编码是唯一保证有效的编码。

    • UTF-8

      UTF-8，是最常用的Unicode编码。对VNC剪贴板使用这种编码违反了VNC规范，但有些服务器确实支持这种编码。仅当你确信你的VNC服务器支持此编码时，才应使用该参数值。

    • UTF-16

      UTF-16，Unicode的16位编码，虽然不如UTF-8常见，但仍被广泛使用。对VNC剪贴板使用这种编码违反了VNC规范。仅当你确信你的VNC服务器支持此编码时，才应使用此参数值。

    • CP1252

      Code page 1252，针对拉丁字符的Windows特定编码，主要是ISO 8859-1的超集，将一些额外的可显示字符映射到原本可以作为控制字符的字符上。对VNC剪贴板使用这种编码违反了VNC规范。仅当你确信你的VNC服务器支持此编码时，才应使用此参数值。

添加一个VNC连接

如果你使用的是Guacamole内置的默认身份验证，并且希望向特定用户授予对VNC连接的访问权限，则需要在user-mapping.xml中找到该用户的<authorize>部件，并在其中添加如下部件：

<connection name="Unique Name">
    <protocol>vnc</protocol>
    <param name="hostname">localhost</param>
    <param name="port">5901</param>
</connection>

如果完全按照上述方式添加，则与包含该连接的<authorize>部件关联的用户将可以使用名为Unique Name的新连接。该连接将用VNC协议连接到localhost和5901端口。当然，你可能想要改变其中的某些或所有值。

如果你的VNC服务器需要一个密码，或者希望指定其他配置参数（例如，为了减少颜色深度），则你需要额外的添加相应地<param>标记。

其他身份验证方法将提供描述如何配置新连接的文档。如果使用的身份验证方法完全实现了Guacamole的身份验证API的功能，那么你将能够使用Guacamole内置的管理界面轻松直观地添加一个新的VNC连接。你将不需要编辑配置文件。

选择哪个VNC服务器？

在性能方面，选择VNC服务器会有很大的差异，尤其是在速度较慢的网络上。虽然许多系统默认提供VNC访问，但通常不是最快的方法。

RealVNC 或 TigerVNC

RealVNC及其衍生产品TigerVNC的表现相当不错。在我们的测试中，他们在Guacamole上表现的最好。如果你赞成使用一个只能通过VNC访问的桌面，那么其中一个可能是你的最佳选择。两者都优化了窗口移动和（取决于应用程序）滚动，提供了非常灵敏的用户体验。

TightVNC

TightVNC可广泛使用，其性能一般与RealVNC或TigerVNC相当。如果你希望将TightVNC与Guacamole一起使用，性能应该会很好，但我们强烈建议禁用它的JPEG编码。这是因为传输到Guacamole的图像总是作为PNG图像进行无损编码的。当对JPEG图像执行此操作时，JPEG有损压缩产生的伪影会降低PNG图像的可压缩性，从而导致总体体验比一开始不使用JPEG时慢。

x11vnc

使用x11vnc的主要好处是，它允许你继续正常使用桌面的同时通过VNC公开对桌面的控制。x11vnc的性能与RealVNC、TigerVNC和TightVNC相当。如果你需要在本地以及通过VNC使用你的桌面，你可能会对x11vnc非常满意。

vino

vino是Gnome桌面环境附带的VNC服务，如果通过Gnome中可用的系统首选项启用“桌面共享”，则会启用它。如果你需要共享你的本地桌面，我们建议你使用x11vnc而不是vino，因为我们的测试证明x11vnc的性能更高，功能更完整。如果你不需要共享本地桌面，只需要一个可以远程访问的环境，那么使用RealVNC、TigerVNC或TightVNC等VNC服务是更好的选择。

QEMU 或 KVM

QEMU（以及KVM）使用VNC公开虚拟机的显示。如果你需要查看虚拟机的虚拟监视器，那么使用此VNC连接实际上是你唯一的选择。由于QEMU中内置的VNC服务无法识别窗口移动、调整大小或滚动等更高级别的操作，因此这些操作的发送速度往往不理想，并且速度不如在虚拟机中运行的VNC服务快。

如果希望使用虚拟机进行桌面访问，建议在虚拟机创建后在虚拟机内安装一个本地的VNC服务。这将提供一个响应更快的桌面。

RDP

RDP协议比VNC更复杂，是Guacamole官方支持的第二个协议。由于使用了缓存，RDP往往比VNC更快，Guacamole确实利用了这一点。

libguac-client-rdp库为Guacamole提供了对RDP协议的支持，如果构建过程中存在所需的依赖项，则该库将作为guacamole-server的一部分安装。

！注意：
除了下面RDP特定的参数外，Guacamole的RDP支持还接受Guacamole为多个协议提供的某些功能的参数：
网络参数

RDP连接需要一个定义目标计算机的主机名或IP地址。RDP端口被定义为3389，在大多数情况下都是这个值。如果不用3389端口，则只需指定RDP端口即可。

  • hostname

    Guacamole要连接到的RDP服务器的主机名或IP地址。

  • port

    RDP服务监听的端口。该参数是可选的。如果没有指定，则会使用RDP的标准端口3389或VMConnect的Hyper-V默认端口2179，具体取决于所选的安全模式。

身份验证和安全

RDP通过用户名、密码以及可选的域参数提供身份验证。所有的RDP连接都是加密的。

如果省略用户名、密码和域参数，大多数RDP服务器将提供一个图形登录界面。一个值得注意的例外是网络级身份验证（NLA），它在桌面会话之外执行所有身份验证，因此没有图形界面。

需要NLA的服务器可以由Guacamole通过以下两种方式之一进行处理。一种方法是在连接配置中提供用户名和密码，通过静态值或通过带有参数令牌和LDAP身份验证的Guacamole凭据。另一种，如果未在连接配置中配置凭据，Guacamole将尝试以交互方式提示用户输入凭据，前提是正在使用的guacd和Guacamole客户端的版本都支持它。如果任一组件都不支持提示，且未配置凭据，则基于NLA的连接将失败。

  • username

    用于身份验证的用户名，如果有。该参数是可选的。

  • password

    尝试身份验证时使用的密码，如果有。该参数是可选的。

  • domain

    尝试身份验证时使用的域，如果有。该参数是可选的。

  • security

    用于RDP连接的安全模式。该模式规定了如何加密数据，以及将执行何种类型的身份验证（如果有的话）。 默认情况下，根据确定客户端和服务器都支持的协商过程选择安全模式。

    可能的值有：

    • any

      基于客户端和服务器都支持的安全协议自动选择安全模式。这是默认值。

    • nla

      网络级身份验证，有时也称为hybrid或CredSSP（驱动NLA的协议）。此模式使用TLS加密，并要求提前提供用户名和密码。与RDP模式不同，身份验证步骤在远程桌面会话实际启动之前执行，避免了Windows服务器为可能未经授权的用户分配大量资源的需要。

      如果使用的guacd和Guacamole客户端版本支持提示，并且未指定用户名、密码和域，则系统将以交互方式提示用户输入凭据以完成NLA并继续连接。否则，当不支持提示且未提供凭据时，NLA连接将失败。

    • nla-ext

      网络级身份验证扩展。此模式与NLA相同，只是NLA握手完成后，需要立即从服务器向客户端发送一份额外的“早期用户授权结果”。

    • tls

      通过 TLS（传输层安全性）实现的 RDP 身份验证和加密。TLS 安全模式也称为 RDSTLS，主要用于负载均衡配置，其中最初的 RDP 服务器可能会将连接重定向到其他 RDP 服务器。‎

    • vmconnect

      根据客户端和服务器都支持的安全协议自动选择安全模式，将协商限制为仅限于已知的被Hyper-V/VMConnect 支持的协议。

    • rdp

      旧版RDP加密。此模式通常仅用于较旧的Windows服务器或需要标准Windows登录界面的情况。较新版本的Windows在默认情况下禁用了此模式，并且除非另有明确配置，否则将仅接受NLA。

  • ignore-cert

    如果设置为true，则服务器返回的证书将被忽略，即使该证书无法验证。如果你一致信任服务器以及与服务器的连接，并且知道服务器的证书无法验证（例如，如果它是自签名的），那么这将非常有用。

  • disable-auth

    如果设置为true，身份验证将被禁用。请注意，这指的是连接时发生的身份验证。服务器通过远程桌面会话（如登录对话框）强制执行的任何身份验证仍将发生。默认情况下，身份验证处于启用状态，仅在服务器请求时使用。

    如果使用NLA，则必须根据定义启用身份验证。

剪贴板规范

与其他操作系统相比，Windows在每行末尾使用不同的字符序列。由于RDP在剪贴板中保留了行尾的格式，因此在使用非Windows计算机访问Windows时会出现问题，反之亦然。

如果使用剪贴板规范，Guacamole将自动转换剪贴板数据中的行尾，以满足远程系统想要的结果。

  • normalize-clipboard

    用于剪贴板文本的行结束规范类型（如果有）。默认情况下，不应使用行结束规范。

    可能的值有：

    • preserve

      将剪贴板中的所有行尾保持原样，不执行任何标准。这是默认设置。

    • unix

      自动将剪贴板中的所有行尾转换为Unix样式的行尾（LF）。这是Linux和Mac都使用的行尾格式。

    • windows

      自动将剪贴板中的所有行尾转换为Windows样式的行尾（CRLF）。

会话设置

RDP会话通常涉及普通用户的完整桌面环境。或者，你可以手动指定一个程序来替代RDP服务器的默认shell，或者连接到管理控制台。

虽然Guacamole与键盘布局无关，但RDP却并非如此。这是因为Guacamole根据按键的功能（“按Enter键”）表示按键，而RDP根据按键的位置（“按第二行最右边的键”）使用标识符。要在Guacamole按键事件和RDP按键事件之间转换，Guacamole必须提前知道RDP服务器的键盘布局。

默认将使用美式英语的qwerty键盘。如果这与RDP服务器的键盘布局不匹配，键将无法正确转换，你需要在连接设置中明确选择不同的布局。如果你的键盘布局不受支持，请在JIRA中打开问题通知Guacamole团队。

  • client-name

    当连接到RDP服务器时，Guacamole通常会提供自己的主机名作为客户端的名称。如果指定了此参数，Guacamole将使用该值。

    在Windows RDP服务器上，此值在会话中作为CLIENTNAME环境变量被公开。

  • console

    如果设置为true，你将会连接到RDP服务器的控制台（管理）会话。

  • initial-program

    连接后立即运行的程序的完整路径。此参数是可选的。

  • server-layout

    服务端键盘布局。这是RDP服务器的布局，与客户端上使用的键盘布局无关。Guacamole客户端独立于键盘布局。然而，RDP协议并不独立于键盘布局，为了在用户键入时发送正确的键，Guacamole需要知道服务器的键盘布局。

    可能的值通常采用LANGUAGE-REGION-VARIANT格式，其中LANGUAGE是与布局相关的主要语言的标准两字母语言代码，REGION是键盘使用位置的标准表示（最好是两字母国家代码），VARIANT是特定的键盘布局变体（如qwerty、qwertz或azerty）：

    键盘布局参数值
    巴西（葡萄牙语）pt-br-qwerty
    英语（英国）en-gb-qwerty
    英语（美国）en-us-qwerty
    法语fr-fr-azerty
    法语（比利时）fr-be-azerty
    法语（瑞士）fr-ch-qwertz
    德语de-de-qwertz
    德语（瑞士）de-ch-qwertz
    匈牙利语hu-hu-qwertz
    意大利语it-it-qwerty
    日语ja-jp-qwerty
    挪威语no-no-qwerty
    西班牙语es-es-qwerty
    西班牙语（拉丁美洲）es-latam-qwerty
    瑞典语sv-se-qwerty
    土耳其语-Qtr-tr-qwerty

    如果你服务器的键盘布局尚不受支持，并且无法将服务器设置为使用受支持的布局，则failsafe 布局可用于强制将Unicode事件用于所有输入，但请注意，这样做可能会阻碍键盘快捷键按预期工作。

  • timezone

    客户端应发送到服务器以配置该服务器的本地时间显示的时区。时区的格式是标准的IANA时区格式，这是UNIX/Linux中使用的格式。将被RDP转换为适用于Windows的正确格式。

    时区将在连接的握手阶段检测并传递给服务器，并且可能被支持它的协议（如RDP）使用。此参数可用于覆盖握手期间检测并传递的值，也可用于guacd不支持在握手阶段传递时区参数的情况（1.3.0之前的guacd版本）。

    对转发客户端时区的支持因RDP服务器实现而异。例如，在Windows中，只有安装了远程桌面服务（RDS，以前称为终端服务）的Windows服务器才支持转发时区。管理模式下的Windows服务器设备以及Windows工作站版本不允许转发时区。其他服务器实现，例如xrdp，可能根本没有实现这个功能。请参阅RDP服务器的文档，以确定是否支持此功能。

显示设置

Guacamole会根据浏览器窗口的大小和设备的DPI自动为RDP连接选择合适的显示大小。可以通过指定明确的宽度或高度值来强制显示大小。

为了减少带宽使用，你还可以请求服务器减少其色彩深度。除了可以绝对保证通过强制将颜色深度设置为8位的通过连接发送的图形外，Guacamole会自动检测256色图像。颜色深度由RDP服务器决定。

  • color-depth

    请求的色彩深度，单位为比特/像素。该参数是可选的。如果指定，则必须是8、16、24或32。不管选择了什么值，如果某个特定更新使用的颜色少于256色，Guacamole将始终以256色PNG格式发送更新。

  • width

    请求的显示器宽度，以像素为单位。此参数是可选的。如果未指定此值，则将使用连接客户端显示的宽度。

  • height

    请求的显示器高度，以像素为单位。此参数是可选的。如果未指定此值，则将使用连接客户端显示的高度。

  • dpi

    客户端显示所需的有效分辨率，单位为DPI。此参数是可选的。如果未指定此值，则客户端显示的分辨率和大小将一起用于试探性地确定RDP会话的适当分辨率。

  • resize-method

    当客户端显示的宽度或高度发生变化时，用于更新RDP服务器的方法。此参数是可选的。如果未指定此值，则当客户端显示更改大小时，不会采取任何操作。

    通常，RDP会话的显示大小是不变的，只有在最初连接时才能更改。从RDP 8.1开始，“Display Update”通道可用于请求服务器更改显示大小。对于较旧的RDP服务器，唯一的选择是断开连接并重新连接到新大小的服务器。

    可能的值有：

    • display-update

      使用RDP 8.1中添加的“ Display Update ”通道，在客户端显示大小更改时向服务器发送信号。

    • reconnect

      当客户端显示大小更改时，会自动断开RDP会话，并使用新的显示大小重新连接。

  • force-lossless

    此连接是否应仅对图形更新使用无损压缩。如果设置为true，则不会使用有损压缩。此参数是可选的。默认情况下，当启发式算法确定有损压缩可能优于无损压缩时，将使用有损压缩。

设备重定向

设备重定向是指在RDP上使用非显示设备。Guacamole的RDP支持目前允许重定向音频、打印和磁盘访问，其中一些需要额外的配置才能正常工作。

默认情况下，会启用音频重定向。如果正确安装了Guacamole，并且RDP服务器支持音频重定向，则声音就将在远程连接中播放，而无需手动干预。

打印要求在Guacamole服务器上安装GhostScript，并允许用户将任意文档直接打印到PDF。当把文档打印到重定向的打印机时，用户将在其web浏览器中收到该文档的PDF。

Guacamole通过模拟虚拟磁盘驱动器，支持通过RDP进行文件传输。此驱动器将保留在Guacamole服务器上，限制在指定的驱动器路径内。如果在Guacamole的RDP连接上启用了驱动器重定向，用户将能够根据《使用Guacamole》中的说明进行文件上传和下载。

  • disable-audio

    默认情况下，在客户端和libguac-client-rdp中都会启用音频。如果你担心带宽使用，或者声音导致问题，可以通过将此参数设置为true来显式禁用声音。

  • enable-audio-input

    如果设置为true，将启用音频输入支持（麦克风），利用RDP的标准AUDIO_INPUT通道。默认情况下，RDP中的音频输入支持被禁用。

  • enable-touch

    如果设置为true，将启用对多点触控事件的支持，利用RDP的标准RDPEI通道。默认情况下，禁用对多点触控事件的直接RDP支持。
    ‎启用对多点触控的支持允许与 RDP 会话中的应用程序进行触摸交互，但可用的触摸手势将取决于这些应用程序和操作系统的触摸支持级别。‎
    如果未启用多点触控支持，RDP会话中与应用程序的指针式交互将仅限于鼠标或模拟鼠标事件。

  • enable-printing

    默认情况下，打印处于禁用状态，但在启用打印的情况下，RDP用户可以打印到虚拟打印机，该打印机将包含要打印文档的PDF发送到Guacamole客户端。通过将此参数设置为true来启用打印。

    打印支持需要安装GhostScript。如果guacd在打印时找不到gs可执行文件，则打印尝试将失败。

  • printer-name

    传递到RDP会话的重定向打印机设备的名称。这是用户将在设备和打印机控制面板中看到的名称。

    如果未启用打印机重定向，则此选项无效。

  • enable-drive

    默认情况下，文件传输处于禁用状态，但在启用文件传输的情况下，RDP用户可以在Guacamole服务器上的虚拟驱动器之间传输文件。通过将此参数设置为true，启用文件传输支持。

    文件将存储在drive-path参数指定的目录中，如果启用了文件传输，则需要该参数。

  • disable-download

    如果设置为true，则将禁用从远程服务器到客户端（浏览器）的下载。这包括通过隐藏的Guacamole菜单进行下载，以及使用提供给远程服务器的特殊“ Download ”文件夹进行下载。默认值为false，这意味着将允许下载。

    如果未启用文件传输，则忽略此参数。

  • disable-upload

    如果设置为true，则将禁用从客户端（浏览器）到远程服务器位置的上传。默认值为false，这意味着如果启用了文件传输，将允许上载。

    如果未启用文件传输，则忽略此参数。

  • drive-name

    传递到RDP会话时使用的文件系统的名称。这是用户将在其”计算机“或”我的电脑“区域中看到的名称以及客户端名称（例如，“Guacamole on Guacamole RDP”），也是访问特殊 \\tsclient 网络位置时共享的名称。

    如果未启用文件传输，则忽略此参数。

  • drive-path

    Guacamole服务器上存储传输文件的目录。这个目录必须可以被guacd访问，并且运行guacd的用户可以读写。此参数不涉及RDP服务器上的目录。

    如果未启用文件传输，则忽略此参数。

  • create-drive-path

    如果设置为true，并且启用了文件传输，则如果 drive-path 参数指定的目录尚不存在，将自动创建该目录。只会创建路径中最后的目录，如果路径中前面的其他目录不存在，自动创建会失败，并将记录错误。

    默认情况下，不会自动创建由 drive-path 参数指定的目录，将文件传输到不存在的目录的尝试将被记录为错误。

    如果未启用文件传输，则忽略此参数。

  • console-audio

    如果设置为true，音频将在RDP服务器的控制台（管理）会话中显式启用。仅当console参数也设置为true时，将此选项设置为true才有意义。

  • static-channels

    打开并公开为管道的静态通道名称的逗号分隔的列表。如果希望在远程桌面上运行的应用程序和JavaScript之间进行通信，这是最好的方法。Guacamole将打开一个具有静态通道名称的出站管道。如果JavaScript需要在另一个方向进行通信，它应该通过打开另一个同名管道来响应。

    Guacamole允许打开任意数量的静态通道，但RDP的协议限制将每个通道名称的大小限制为7个字符。

‎预连接‎PDU (Hyper-V / VMConnect)

‎某些 RDP 服务器在侦听单个 TCP 端口的单个服务器后面托管了多个逻辑 RDP 连接（访问RDP服务器上搭建的虚拟机）。若要在这些逻辑连接之间进行选择，RDP 客户端必须发送"预连接 PDU"，即包含唯一标识目标的值（称为"RDP 源"）的消息。此机制由 RDP 协议的‎‎"会话选择扩展"‎‎定义，并由微软的 Hyper-V 虚拟机监控程序实现。‎

如果你使用的是Hyper-V，则需要在preconnection-blob参数中指定目标虚拟机的ID。此值可以使用PowerShell命令确定：

PS C:\> Get-VM VirtualMachineName | Select-Object Id

Id
--
ed272546-87bd-4db9-acba-e36e1a9ca20a


PS C:\>

预连接PDU是有意通用的。虽然它主要用于选择Hyper-V背后的虚拟机，但其他RDP服务器也可以使用它。由RDP服务器本身决定是否使用预连接ID、BLOB或两者，以及它们的值的含义。

如果你确实打算使用Hyper-V，请注意其内置的RDP服务器需要不同的参数进行身份验证，而Guacamole的默认值将不起作用。在大多数情况下，连接到Hyper-V时需要执行以下操作：

  1. 适当地指定username和password，并将security设置为vmconnect。选择vmconnect安全模式将配置Guacamole自动磋商Hyper-V支持的安全模式，并将自动选择Hyper-V的默认RDP端口（2179）。
  2. 如有必要，将ignore-cert设置为true。Hyper-V可能使用自签名证书。

  • preconnection-id

    RDP源的数字ID。这是一个非负整数值，指示应该使用几个潜在的逻辑RDP连接中的哪一个。此参数是可选的，仅当RDP服务器记录为需要此参数时才需要此参数。如果使用Hyper-V，则应将其留空。

  • preconnection-blob

    标识RDP源的任意字符串，可能是由同一RDP服务器托管的多个逻辑RDP连接之一。此参数是可选的，仅当RDP服务器被记录为需要此参数时（如Hyper-V）才需要此参数。在所有情况下，此参数的含义对RDP协议本身是不透明的，由RDP服务器决定。对于Hyper-V，这将是目标虚拟机的ID。

远程桌面网关

微软的远程桌面服务器提供了额外的网关服务，允许将外部连接转发到无法访问的内部RDP服务器。如果要使用Guacamole通过这类网关进行连接，则需要提供描述该网关连接的附加参数，以及任何必需的凭据。

  • gateway-hostname

    作为远程桌面连接的中介的远程桌面网关的主机名。如果省略，将不使用网关。

  • gateway-port

    作为远程桌面连接的中介的远程桌面网关的端口。默认情况下，这将是"443"。‎

  • gateway-username

    ‎使用远程桌面网关进行身份验证的用户的用户名（如果正在使用网关）。这不一定与实际使用的远程桌面连接的用户相同。‎

  • gateway-password

    ‎使用远程桌面网关进行身份验证时要提供的密码（如果正在使用网关）。‎

  • gateway-domain

    ‎使用远程桌面网关进行身份验证的用户的域（如果正在使用网关）。此域不一定与实际使用远程桌面连接的用户相同。‎

负载均衡和RDP连接代理

如果你的远程桌面服务器位于负载均衡器（有时称为“连接代理”或“TS会话代理”）后面，则在连接过程中，该均衡器可能需要其他信息来确定传入连接的路由方式。RDP不规定该信息的格式，它特定于正在使用的均衡器。

如果你正在使用负载均衡器，并且不确定是否需要此类信息，则需要检查均衡器的文档。如果你的均衡器为方便起见提供了.rdp文件，请在这些文件的内容中查找名为loadbalanceinfo的字符串字段，因为该字段将指定所需的information/cookie。

  • load-balance-info

    应提供给连接代理的负载均衡信息或cookie。如果未使用连接代理，则应将其留空。

性能标志

RDP提供了几个标志，用于控制为了美观而降低性能和增加带宽的功能的可用性，例如墙纸、窗口主题、菜单效果和平滑字体。默认情况下，这些功能在Guacamole中都是禁用的，这样可以将带宽使用降至最低，但如果需要，你可以基于每个连接手动重新启用它们。

  • enable-wallpaper

    如果设置为true，则启用桌面墙纸的渲染。默认情况下，墙纸将被禁用，这样就不需要花费不必要的带宽来重新绘制桌面。

  • enable-theming

    如果设置为true，则启用窗口和控件的主题。默认情况下，RDP会话中的主题设置被禁用。

  • enable-font-smoothing

    如果设置为true，文本将以平滑的边缘呈现。默认情况下，RDP上的文本以粗糙边缘呈现，因为这会减少文本使用的颜色数量，从而减少连接所需的带宽。

  • enable-full-window-drag

    ‎如果设置为true，则窗口的内容将在移动窗口时显示。默认情况下，RDP 服务器仅在拖动窗口时绘制窗口边框。‎

  • enable-desktop-composition

    如果设置为true，则启用透明窗口和阴影等图形效果。默认情况下，这些效果（如果可用）将被禁用。

  • enable-menu-animations

    ‎如果设置为true，则启用菜单打开和关闭动画。默认情况下，菜单动画处于禁用状态。‎

  • disable-bitmap-caching

    ‎在某些情况下，特别是对于具有已知错误的 RDP 服务器实现，有必要禁用RDP的内置位图缓存功能。此参数允许在Guacamole会话中对其进行控制。如果设置为true，则不会使用RDP位图缓存。‎

  • disable-bitmap-caching

    RDP通常会维护当前在客户端不可见的屏幕区域的缓存，以便在这些区域进入视图时加速检索。此参数设置为true时，将禁用这些区域的缓存。这通常只在处理RDP服务器实现中的已知错误时有用，并且在大多数情况下应该保持启用状态。

  • disable-glyph-caching

    ‎除了屏幕区域之外，RDP 还维护常用符号或字体（统称为"字形"）的缓存。与位图和屏幕外缓存一样，启用此参数会导致 RDP 实现中的某些已知 bug 出现性能问题，将此参数设置为true将在 RDP 会话中禁用该字形缓存。

    ‎无论此参数的值如何，字形缓存目前都处于普遍禁用状态，因为从 FreeRDP 2.0.0 版本开始，FreeRDP 认为字形缓存支持不稳定。参见：‎‎Guacamole-1191‎‎。‎

RemoteApp

最新版本的Windows提供了一个名为RemoteApp的功能，允许通过RDP使用单个应用程序，而无需访问整个桌面环境。如果你的RDP服务器启用并配置了此功能，则可以配置Guacamole连接使用这些单独的应用程序。

  • remote-app

    指定要在远程桌面上启动的RemoteApp。如果你的远程桌面服务器支持该应用程序，则只有该应用程序对用户可见。

    Windows要求远程应用程序的名称使用特殊的表示法。远程应用程序的名称必须以两个竖线为前缀。例如，如果你在服务器上为notepad.exe创建了一个远程应用程序且将其命名为notepad，则应将该参数设置为||notepad。

  • remote-app-dir

    远程应用程序的工作目录（如果有）。如果RemoteApp未使用，此参数无效。

  • remote-app-args

    远程应用程序的命令行参数（如果有）。如果RemoteApp未使用，此参数无效。

添加一个RDP连接

如果你正在使用内置于Guacamole中的默认身份验证机制，且希望授予特定用户访问RDP连接的权限，则需要在user-mapping.xml中找到该用户的<authorize>部件，并在其中添加如下部件：

<connection name="Unique Name">
    <protocol>rdp</protocol>
    <param name="hostname">localhost</param>
    <param name="port">3389</param>
</connection>

如果完全按照上述方式添加，则与包含该连接的<authorize>部件关联的用户将可以使用名为Unique Name的新连接。该连接将使用RDP协议连接到localhost和3389端口。当然，你可能想要改变其中的某些或所有值。

如果你想在连接时自动登录而不是接收一个登录提示，那么你可以用一个额外的<param>标签指定用户名和密码。其他的选项可用于控制色彩深度，屏幕尺寸等。

其他身份验证方法将提供描述如何配置新连接的文档。如果使用的身份验证方法完全实现了Guacamole的身份验证API的功能，那么你将能够使用Guacamole内置的管理界面轻松直观地添加一个新的RDP连接。你将不需要编辑配置文件。

SSH

与VNC或RDP不同，SSH是一种文本协议。它在Guacamole中的实现实际上是终端模拟器和SSH客户端的组合，因为SSH协议本质上不是图形化的。Guacamole的SSH支持模拟服务器端的终端，并在客户端远程绘制该终端的屏幕。

Guacamole的SSH支持由libguac-client-ssh库提供，如果构建过程中存在所需的依赖项，则该库将作为guacamole-server的一部分进行安装。

！注意：
除了下面SSH特定的参数外，Guacamole的SSH支持还接受Guacamole为多个协议提供的某些功能的参数：
SSH主机验证

默认情况下，在建立SSH连接之前，Guacamole不会对主机身份进行任何验证。虽然这对于专用和受信任的网络可能是安全的，但对于具有未知或不受信任系统的大型网络或跨互联网的SSH连接而言并不完美。连接到这些主机时，存在中间人（MitM）攻击的可能性。

Guacamole包括两种验证SSH（和SFTP）服务器身份的方法，可用于确保你连接的主机是你知道并信任的主机。第一种方法是读取GUACAMOLE_HOME中名为ssh_known_hosts的文件。该文件应该是标准的OpenSSH known_hosts文件格式。如果文件不存在，则不进行验证。如果文件存在，则会在连接时读取该文件，并根据文件中存在的密钥验证远程主机身份。

验证主机身份的第二种方法是传递一个连接参数，该参数包含该特定主机的OpenSSH已知主机条目。host-key参数用于SSH连接，而与RDP和VNC关联的SFTP连接使用sftp-host-key参数。如果这些参数在各自的连接上不存在，则不会执行主机身份验证。如果参数存在，则在建立连接之前，将根据参数中提供的身份验证远程主机的标识。

网络参数

‎SSH 连接需要一个定义目标计算机的主机名或 IP 地址。SSH 被标准化为使用端口22，多数情况下，都是这样。如不使用标准端口，只需指定 SSH 端口即可。

  • hostname ‎

    Guacamole将要连接的SSH服务器的主机名或IP地址

  • port

    SSH服务器监听的端口，通常是22。该参数是可选的。如果没有指定，将使用默认的22端口。

  • host-key

    SSH服务器的已知主机条目。此参数是可选的，如果未提供，则不会执行主机身份验证。如果提供了参数，将根据数据检查服务器的标识。

    该参数的格式是OpenSSH known_hosts文件中单个条目的格式。

    有关更多信息，请参阅SSH主机验证。

  • server-alive-interval

    ‎默认情况下，SSH 客户端不向服务器发送keepalive请求。此参数允许你配置客户端连接向服务器发送keepalive数据包的时间间隔（以秒为单位）。默认值为 0，这将禁用发送数据包。最小值为 2。‎

身份验证

SHH通过密码和公钥认证提供身份验证，并且还支持NONE方法。

SSHNONE身份验证偶尔出现在设备和项目中，如网络或SAN结构交换机。通常，对于这种身份验证方法，你只需要提供用户名。

要让Guacamole使用公钥身份验证，它必须能够访问你的私钥，并且如果私钥需要密码短语，还必须能够访问其密码短语。如果私钥需要密码短语，但没有提供密码短语，则连接时会提示你输入密码短语。

如果没有提供私钥，Guacamole将尝试使用密码进行身份验证，从连接参数（如果提供）读取该密码，或者直接提示用户。‎

  • username

    ‎用于身份验证的用户名（如果有）。此参数是可选的。如果未指定，则在连接时系统将提示你输入用户名。‎

  • password

    ‎尝试身份验证时要使用的密码（如果有）。此参数是可选的。如果未指定，连接时系统将提示你输入密码。‎

  • private-key

    用于公钥身份验证的私钥的全部内容。如果未指定此参数，则不会使用公钥身份验证。私钥必须是OpenSSH格式，就像OpenSSH的ssh-keygen实用程序生成的那样。

  • passphrase

    用于解密用于公钥身份验证的私钥的密码短语。如果私钥不需要密码短语，则不需要此参数。如果私钥需要密码短语，但未提供此参数，则连接时会提示用户输入密码短语。

运行命令（替代shell)

默认情况下，SSH会话将启动一个交互式的shell。要使用的shell由SSH服务器决定，通常是通过读取用户先前用chsh或/etc/passwd设置的默认shell来确定。如果你希望覆盖该命令并运行特定命令，那么可以在Guacamole SSH连接的配置中指定该命令来执行该操作。

  • command

    要在SSH会话上执行的命令（如果有）。此参数是可选的。如果未指定，SSH会话将使用用户的默认shell。

国际化/区域设置

会话的语言通常由SSH服务器设置。如果SSH服务器允许设置相关环境变量，则可以基于每个连接覆盖该语言设置。

  • locale

    请求的SSH会话的具体区域设置。此参数是可选的，可以是SSH服务器的LANG环境变量接受的任何值。如果未指定，将使用SSH服务器的默认区域设置。

    由于该参数是使用LANG环境变量发送到SSH服务器的，因此只有当SSH服务器允许SSH客户端设置LANG环境变量时，该参数才会生效。

  • timezone

    该参数允许你控制通过SSH连接发送到服务器的时区，这将改变服务器上显示本地时间的方式。

    通过SSH连接执行此操作的机制是将SSH连接上的TZ变量设置为该参数指定的时区。这意味着SSH服务器必须允许设置或覆盖TZ变量。默认情况下，许多SSH服务器实现都禁用了该选项。要使其正常工作，可能需要修改SSH服务器的配置，并明确允许设置或覆盖TZ。

    该参数的可用值为标准的IANA时区格式，且该值将以这种格式直接发送给服务器。

SFTP

Guacamole使用SFTP（大多数SSH服务器内置的文件传输协议）通过SSH协议提供文件传输支持。如果在一个Guacamole SSH连接上启用了SFTP，用户将能够按照《使用Guacamole》中的说明那样上传和下载文件。

  • enable-sftp

    是否应启用文件传输。如果设置为true，则允许用户使用SFTP从SSH服务器上传或下载文件。Guacamole包括guacctl实用程序，当用户通过SSH连接在SSH服务器上运行时，它可以控制文件的下载和上传。

  • sftp-root-directory

    ‎通过Guacamole的文件浏览程序‎‎向已连接的用户公开的目录。如果省略，则默认情况下将使用根目录。‎

  • sftp-disable-download

    如果设置为true，则将禁用从远程系统到客户端（浏览器）的下载。默认值为false，这意味着将启用下载。

    如果未启用SFTP，此参数将被忽略。

  • sftp-disable-upload

    如果设置为true，则将禁用从客户端（浏览器）到远程系统的上载。默认值为false，这意味着将启用上传。

    如果未启用SFTP，此参数将被忽略。

添加一个SSH连接

如果你使用Guacamole内置的默认身份验证机制，且希望授予一个特定用户访问一个SSH连接的权限，你需要在user-mapping.xml中找到该用户的<authorize>部件，并向其中添加如下部件：

<connection name="Unique Name">
    <protocol>ssh</protocol>
    <param name="hostname">localhost</param>
    <param name="port">22</param>
</connection>

如果完全按照上述方式添加，则与包含该连接的<authorize>部件关联的用户将可以使用名为Unique Name的新连接。该连接将使用SSH协议连接到localhost和22端口。当然，你可能想要改变其中的某些或所有值。

如果你想在连接时自动登录而不是接收一个登录提示，那么你可以用一个额外的<param>标签指定用户名和密码。其他的选项可用于控制字体。

其他身份验证方法将提供描述如何配置新连接的说明。

Telnet

Telnet是一种文本协议，提供与SSH类似的功能。本质上，它不是加密的，也不支持文件传输。就图形而言，Guacamole的telnet支持与SSH的工作方式相同：它模拟服务器端的终端，并呈现给Guacamole客户端的显示。
libguac-client-telnet库提供了对Guacamole的Telnet支持，如果在构建过程中存在所需的依赖项，该库将作为guacamole-server的一部分安装。

！注意：
除了下面Telnet特定的参数外，Guacamole的Telnet支持还接受Guacamole为多个协议提供的某些功能的参数：
网络参数

Telnet 连接需要一个定义目标计算机的主机名或 IP 地址。 Telnet 被标准化为使用端口23，多数情况下，都是这样。如不使用标准端口，只需指定Telnet端口即可。

  • hostname ‎

    Guacamole将要连接的Telnet服务器的主机名或IP地址

  • port

    Telnet服务器监听的端口，通常是23。该参数是可选的。如果没有指定，将使用默认的23端口。

身份验证

Telnet 实际上不提供任何标准的身份验证方法。通过 Telnet 进行的身份验证完全取决于服务器上运行的登录进程，并且是交互式的。为了解决这个问题，Guacamole提供了非标准机制来自动传递用户名和输入密码。这些机制是否有效取决于 Telnet 服务器使用的特定登录进行。

通过Telnet自动传递用户名的实际方法是通过使用NEW-ENVIRON选项发送的USER环境变量提交用户名。这是大多数Telnet客户端使用的机制，通常通过-l命令行选项。

通常不能自动发送密码，至少不如用户名可靠。没有PASSWORD环境变量（这实际上是一个可怕的想法），也没有任何类似的机制将密码传递给Telnet登录进程，并且大多数Telnet客户端都不提供自动输入密码的内置支持。最好的办法是启发式的检测密码提示，并在提示出现时代表用户键入密码。使用传统的命令行Telnet执行此操作的指定方法是使用expect之类的工具。Guacamole通过使用正则表达式搜索密码提示，提供了类似的功能。

如果Guacamole收到一行与正则表达式匹配的文本，则会自动发送密码。如果从未收到此类行，则不会发送密码，那么用户必须手动键入密码。在此过程中按任意键都会取消启发式的密码提示检测。

如果未正确检测到密码提示，可以尝试使用自己的正则表达式，方法是在在password-regex参数中指定。正则表达式必须使用POSIX ERE方言（通常是egrep使用的方言）编写。

  • username

    用于身份验证的用户名（如果有）。此参数是可选的。如果未指定或 Telnet 服务器不支持，则Telnet服务器上的登录进程将提示你输入你的凭据。要使其工作，Telnet服务器必须支持NEW-ENVIRON选项，Telnet登录进程必须注意USER环境变量。大多数Telnet服务器都满足这一标准。

  • password

    尝试身份验证时要使用的密码（如果有）。此参数是可选的。如果指定，则在检测到密码提示时将代表你键入你的密码。‎

  • username-regex

    等待用户名提示时要使用的正则表达式。此参数是可选的。如果未指定，将使用Guacamole中内置的合理默认值。正则表达式必须使用POSIX ERE方言（通常是egrep使用的方言）编写。

  • password-regex

    等待密码提示时要使用的正则表达式。此参数是可选的。如果未指定，将使用Guacamole中内置的合理默认值。正则表达式必须使用POSIX ERE方言（通常是egrep使用的方言）编写。

  • login-success-regex

    检测到登录尝试已成功时要使用的正则表达式。此参数是可选的。如果指定，则在从Telnet服务器接收到与此正则表达式匹配的文本之前，不会向用户显示终端显示。正则表达式必须使用POSIX ERE方言（通常是egrep使用的方言）编写。

  • login-failure-regex

    检测到登录尝试失败时要使用的正则表达式。此参数是可选的。如果指定，则如果从Telnet服务器接收到与此正则表达式匹配的文本，则连接将关闭，并出现显式登录失败错误。正则表达式必须使用POSIX ERE方言（通常是egrep使用的方言）编写。

添加一个Telnet连接

如果你使用Guacamole内置的默认身份验证机制，且希望授予一个特定用户访问一个Telnet连接的权限，你需要在user-mapping.xml中找到该用户的<authorize>部件，并向其中添加如下部件：

<connection name="Unique Name">
    <protocol>telnet</protocol>
    <param name="hostname">localhost</param>
    <param name="port">23</param>
</connection>

如果完全按照上述方式添加，则与包含该连接的<authorize>部件关联的用户将可以使用名为Unique Name的新连接。该连接将使用Telnet协议连接到localhost和23端口。当然，你可能想要改变其中的某些或所有值。

由于Telnet相对SSH来说本质上是不安全的，所以你应该尽量使用SSH。如果Guacamole被设置为使用HTTPS，则与Guacamole客户端的通信将被加密，但guacd与Telnet服务器之间的通信仍将未加密。除非guacd和Telnet服务器之间的网络受信任，否则不应使用Telnet。

Kubernetes

Kubernetes提供了通过网络连接到容器控制台的API。与SSH和telnet一样，Guacamole的Kubernetes支持模拟服务端的终端以呈现给Guacamole客户端的显示器。

Guacamole通过libguac-client-kubernetes库提供Kubernetes支持，如果在构建期间存在该库所需的依赖，则该库将作为guacamole-server的一部分进行安装。

！注意：
除了下面Kubernetes特定的参数外，Guacamole的Kubernetes支持还接受Guacamole为多个协议提供的某些功能的参数：
网络/容器参数

连接到一个Kubernetes容器需要提供Kubernetes服务器的主机名或IP地址，以及包含相关容器的pod的名称。默认情况下，Guacamole将连接到pod中的第一个容器。如果pod中有多个容器，你可能还希望指定容器名称。

  • hostname

    Guacamole将要连接的Kubernetes服务器的主机名或IP地址。

  • port

    Kubernetes监听的用于API连接的端口。该参数是可选的。如果省略，将默认使用8080端口。

  • namespace

    包含要连接的容器的pod的Kubernetes命名空间的名称。该参数是可选的。如果省略，将使用default命名名称空间

  • pod

    包含要连接的容器的Kubernetes pod的名称。

  • container

    要连接的容器的名称。该参数是可选的。如果省略，则使用pod的第一个容器。

  • exec-command

    要在容器中运行的命令，其输入和输出被附加到该命令的进程上。此参数是可选的。如果省略，则不会运行任何命令，而是将输入/输出附加到容器的主进程上。

    指定此参数后，连接的行为类似于运行**kubectl exec。省略时，该行为类似于运行kubectl attach**。

身份验证以及SSL/TLS

如果启用，Kubernetes将使用SSL/TLS进行加密和身份验证。标准的SSL/TLS客户端身份验证需要客户端证书和客户端密钥，Guacamole将使用它们向Kubernetes服务器标识自己。如果Kubernetes使用的证书是自签名或由非标准证书颁发机构签名的，则还需要证书颁发机构的证书。

  • use-ssl

    如果设置未true，SSL/TLS将被用于连接Kubernetes服务器。该参数是可选的。默认不使用SSL/TLS。

  • client-cert

    ‎在执行 SSL/TLS 客户端身份验证以向 Kubernetes 服务器进行身份验证时要使用的证书，采用 PEM 格式。‎‎此参数是可选的。‎‎如果省略，则不会执行 SSL 客户端身份验证。‎

  • client-key

    ‎在执行 SSL/TLS 客户端身份验证以向 Kubernetes 服务器进行 PEM 格式身份验证时要使用的密钥。‎‎此参数是可选的。‎‎如果省略，则不会执行 SSL 客户端身份验证。‎

  • ca-cert

    签署 Kubernetes 服务器证书的证书颁发机构的证书，采用 PEM 格式。‎‎此参数是可选的。‎‎如果省略，则 Kubernetes 服务器证书的验证将仅使用系统范围的证书颁发机构。‎

  • ignore-cert

    如果设置为true，则Kubernetes服务器使用的SSL/TLS证书的有效性将被忽略，如果无法对其进行证实。此参数是可选的。默认会验证SSL/TLS证书。

添加一个Kubernetes连接

如果你使用Guacamole内置的默认身份验证机制，且希望授予一个特定用户访问一个Kubernetes连接的权限，你需要在user-mapping.xml中找到该用户的<authorize>部件，并向其中添加如下部件：

<connection name="Unique Name">
    <protocol>kubernetes</protocol>
    <param name="hostname">localhost</param>
    <param name="pod">mypod</param>
</connection>

如果完全按照上述方式添加，则与包含该连接的<authorize>部件关联的用户将可以使用名为Unique Name的新连接。该连接将连接到localhost上运行的Kubernetes服务器，并连接到名为mypod的pod的第一个容器。

通用配置选项

禁用剪切板访问

默认情况下，Guacamole为所有受支持的协议提供对剪贴板的双向访问。对于本质上不提供剪贴板的协议，Guacamole实现了自己的剪贴板。可以根据disable-copy和disable-paste参数在每个连接上覆盖该行为。

  • disable-copy

    如果设置为true，则用户将无法在 Guacamole 会话的浏览器端访问在远程桌面会话中复制的文本，并且只能在远程桌面中使用。此参数是可选的。默认情况下，用户将获得对复制文本的访问权限。‎

  • disable-paste

    如果设置为true，则在 Guacamole 会话的浏览器端复制的文本将无法在远程桌面会话中访问。此参数是可选的。默认情况下，用户将能够在远程桌面会话中粘贴浏览器外部的数据。‎

通过SFTP进行文件传输

Guacamole可以通过SFTP提供文件传输，即使远程桌面是通过不同的协议（如VNC或RDP）访问的。如果在Guacamole RDP连接上启用了SFTP，用户将能够按照《使用Guacamole》中的说明那样上传和下载文件。

这种支持独立于所使用的协议可能提供的文件传输，比如RDP自己的“驱动器重定向”（RDPDR），对于不支持文件传输功能的远程桌面服务器特别有用。

  • enable-sftp

    是否应启用文件传输。如果设置为true，则允许用户使用SFTP从指定的服务器上传或下载文件。如果省略，SFTP将被禁用。‎

  • sftp-hostname

    ‎托管 SFTP的服务器的主机名或IP地址。此参数是可选的。如果省略，将使用与连接关联的远程桌面服务器的主机名。‎

  • sftp-port

    提供SFTP的SSH服务器监听的端口，通常为22。此参数是可选的。如果省略，将使用标准的22端口。

  • sftp-host-key

    SFTP服务器的已知主机条目。此参数是可选的，如果未提供，则不会验证SFTP主机标识。如果提供了参数，将根据数据检查服务器的标识。

    此参数的格式是OpenSSH known_hosts文件中单个条目的格式。

    有关详细信息，请参阅 ‎‎SSH 主机验证‎‎。

  • sftp-username

    连接到SFTP的指定SSH服务器时要验证的用户名。如果为远程桌面连接指定了用户名，则此参数是可选的。如果省略，将使用为远程桌面连接指定的用户名。

  • sftp-password

    使用 SFTP 的指定 SSH 服务器进行身份验证时要使用的密码。

  • sftp-private-key

    ‎用于公钥身份验证的私钥的全部内容。如果未指定此参数，则不会使用公钥身份验证。私钥必须采用OpenSSH格式，就像 OpenSSH的‎‎ssh-keygen‎‎工具生成的那样。‎

  • sftp-passphrase

    ‎用于解密私钥以用于公钥身份验证的密码。如果私钥不需要密码，则不需要此参数。‎

  • sftp-directory

    简单地拖放上传文件的目录，因此除此之外缺少特定的上传位置。此参数是可选的。如果省略，将使用提供SFTP的SSH服务器的默认上传位置。

  • sftp-root-directory

    通过Guacamole的文件浏览程序暴露给已连接用户的目录 。如果省略，则将默认使用根目录。

  • sftp-server-alive-interval

    为了保持SFTP连接向SSH服务器发送keepalive数据包的频率（单位秒）。该参数是可选的。如果省略，将默认使用0，表示禁用发送keepalive数据包。最小值是2。

  • sftp-disable-download

    如果设置为true，则将禁用从远程系统到客户端（浏览器）的下载。默认值为false，表示启用下载。

    如果禁用SFTP，该参数将被忽略。

  • sftp-disable-upload

    如果设置未true，从客户端（浏览器）到远程系统的上传将被禁用。默认是false，表示启用上传。

    如果禁用SFTP，该参数将被忽略。

图形会话录制

所有受支持协议的会话都可以以图形方式录制。这些录像采用Guacamole协议形式转储，并自动记录到指定目录。录像随后可以使用guacamole-server提供的guacenc工具转换为普通视频流。

例如，从NAME录像生成一个名为NAME.m4v的录像，你可以运行：

$ guacenc /path/to/recording/NAME

guacaenc工具有用于重载默认行为的附加的选项，包括调整输出格式，详细记录可以在手册页中查看：

$ man guacenc

如果按键事件录像被显示的使用recording-include-keys参数启用，录像还可以使用guaclog工具将会话期间的按键转换为人类可读解释。guaclog的使用类似于guacenc，并最终创建一个包含解释事件的新文本文件：

$ guaclog /path/to/recording/NAME
guaclog: INFO: Guacamole input log interpreter (guaclog) version 1.4.0
guaclog: INFO: 1 input file(s) provided.
guaclog: INFO: Writing input events from "/path/to/recording/NAME" to "/path/to/recording/NAME.txt" ...
guaclog: INFO: All files interpreted successfully.
$


❗重点:
Guacamole永远不会覆盖现有的录像。如有必要，将添加一个数字后缀，如“.1”、“.2”、“.3”等，以避免覆盖现有录像。如果连添加数字后缀都没有帮助，那么会话就不会被录制下来。

  • recording-path

    ‎将在其中创建屏幕录制文件的目录。‎‎如果需要创建图形记录，则需要此参数。‎‎指定此参数将启用图形屏幕录制。如果省略此参数，则不会创建图形记录。‎

  • create-recording-path

    如果设置为true，recording-path参数指定的目录如果不存在，则将自动创建。只有路径中的最后一个目录会被创建，如果路径中的其他目录不存在，自动创建操作将会失败，并记录下一个错误。

    这个参数是可选的。默认情况下，recording-path参数指定的目录不会被自动创建，且在一个不存在的目录下尝试创建录像将会失败并记录一个错误。

    该参数仅在图像录制启用的情况下有效。如果recording-path没有指定，图形会话录像会被禁止，且该参数将被忽略。

  • recording-name

    创建的任意录像的文件名。该参数是可选的。如果忽略，将用recording作为代替值。

    该参数仅在图形录制启用的情况下有效。如果recording-path没有指定，图像会话录像会被禁止，且该参数将被忽略。

  • recording-exclude-output

    ‎如果设置为true，则通常从服务器流式传输到客户端的图形输出和其他数据将从记录中排除，从而生成仅包含用户输入事件的记录。‎‎此参数是可选的。‎‎如果省略，图形输出将包含在录制中。

    该参数仅在图形录制启用的情况下有效。如果recording-path没有指定，图像会话录像会被禁止，且该参数将被忽略。

  • recording-exclude-mouse

    ‎如果设置为true，用户鼠标事件将从录制中排除，从而生成缺少可见鼠标光标的录制文件。‎‎此参数是可选的。‎‎如果省略，鼠标事件将包含在录制中。‎

    该参数仅在图形录制启用的情况下有效。如果recording-path没有指定，图像会话录像会被禁止，且该参数将被忽略。

  • recording-include-keys

    ‎如果设置为true，则用户按键事件将包含在录制中。录像随后可以通过‎‎guaclog‎‎工具传递，以将会话期间按键事件生成人类可读的解释。‎‎此参数是可选的。‎‎如果省略，按键事件将不包括在录制中。‎

    该参数仅在图形录制启用的情况下有效。如果recording-path没有指定，图像会话录像会被禁止，且该参数将被忽略。

文本会话录制（打字稿）

SSH会话中包含时间节点信息的完整的原始文本内容，可以自动地被录制到指定的目录。这种录像也称为"打字稿"，将被写入typescript-path指定目录中的两个文件：NAME，包含原始文本数据，以及NAME.timing，包含时间节点信息，其中NAME是typescript-name参数提供的值。

格式与标准的UNIXscript命令格式兼容，且可以使用scriptreplay（如果已经安装）重播。例如，要重播一个名为NAME的打字稿，你可以运行：

$ scriptreplay NAME.timing NAME


❗重点:
Guacamole永远不会覆盖现有的录像。如有必要，将添加一个数字后缀到`NAME`，如“.1”、“.2”、“.3”等，以避免覆盖现有录像。如果连添加数字后缀都没有帮助，那么会话就不会被录制下来。

  • typescript-path

    可以创建打字稿文件的目录。如果需要录制一份打字稿，该参数是必需的。指定该参数以启用打字稿录像。如果忽略该参数，将不会录制打字稿。

  • create-typescript-path

    如果设置为true，typescript-path参数指定的目录如果不存在将被自动创建。只有路径中的最后一个目录才会被创建，路径中的其他参数如果不存在，自动创建操作会失败，且将记录一个错误。

    该参数是可选的。默认情况下，typescript-path参数指定的目录不会被自动创建，且尝试在不存在的目录下记录打字稿会被记录下一个错误。

    该参数仅在打字稿录像被启用的情况下有效。如果typescript-path没有指定，打字稿录像将被禁用，且该参数会被忽略。

  • typescript-name

    确定打字稿的数据和计时节点文件的名称时使用的基本文件名。此参数是可选的。如果省略，将使用typescript作为替代值。

    每份打字稿都有两个typescript-path参数指定的目录中的文件组成：NAME，包含原始的文本文件，以及NAME.timing，包含计时信息，其中NAME是typescript-name参数提供的值。

    该参数仅在打字稿录像被启用的情况下有效。如果typescript-path没有指定，打字稿录像将被禁用，且该参数会被忽略。

控制终端行为

在大多数情况下，终端的默认行为无需修改即可工作。然而，当连接到某些系统，尤其是Linux以外的操作系统时，可能需要调整终端行为，以允许其正常运行。本节中的设置控制这种行为。

  • backspace

    此参数控制退格键发送到远程系统的ASCII码。在大多数情况下，这不需要调整；但是，如果在按backspace键时，你看到的是控制字符（通常是^?或^H），而不是文本被删除，则可能需要调整此参数。默认情况下，如果未设置该项，终端将发送ASCII码127（Delete）。

  • terminal-type

    此参数设置传递给服务器的终端模拟器类型的字符串。此参数是可选的。如果未指定，默认情况下，linux被用作终端模拟器类型。

直接从JavaScript提供终端输入

如果Guacamole部分用于自动化SSH、telnet或其他终端会话，那么直接从JavaScript以原始数据流的形式提供输入，而不是试图将数据转换为按键，可能会很有用。这可以通过使用Guacamole.Client的createPipeStream()函数在连接中打开名为STDIN的管道流来实现：

var outputStream = client.createPipeStream('text/plain', 'STDIN');

然后，得到的Guacamole.OutputStream可以用于将数据直接流式传输到终端会话的输入端，就像用户键入的那样：

// Wrap output stream in writer
var writer = new Guacamole.StringWriter(outputStream);

// Send text
writer.sendText("hello");

// Send more text
writer.sendText("world");

// Close writer and stream
writer.sendEnd();
终端显示设置

Guacamole的终端模拟器（由SSH、telnet和Kubernetes支持使用）提供了配置所用字体及其大小的选项。在这种情况下，所选字体必须安装在服务器上，因为将字符呈现给终端显示器的是服务器，而不是客户端。

  • color-scheme

    用于终端会话的配色方案。它由一系列以分号分隔的名称-值对组成。每个名称-值对由冒号分隔，并为终端仿真器调色板中的颜色分配一个值。例如，要在默认在白色背景上使用蓝色文本，并将红色改为紫色阴影，可以指定：

    foreground: rgb:00/00/ff;
background: rgb:ff/ff/ff;
color9: rgb:80/00/80

    这种格式与Xterm使用的颜色配置格式类似，因此Xterm颜色配置可以轻松地适用于Guacamole。此参数是可选的。如果未指定，Guacamole将在黑色背景上呈现灰色文本。

    可能的颜色配置项名称有：

    • foreground

      设置默认前景色

    • background

      设置默认背景色

    • colorN

      将颜色设置为Xterm的256调色板上的索引N。例如，color9指的是红色。

    可能的颜色值有：

    • rgb:RR/GG/BB

      使用RDB格式指定的颜色，每个部分都是十六进制数。例如，rbg:ff/00/00表示红色。注意，每个十六进制部分可以是1到4个数字，但有效值总是用0扩展或截断为两个数字的：例如，rgb:f/8/0，rgb:f0/80/00以及rgb:f0f/808/00f都表示相同的有效颜色。

    • colorN

      使用Xterm 256调色板上当前分配给索引N的颜色。例如，color9表示当前颜色为红色。注意，使用的是颜色值，而不是颜色引用，因此，如果后面在配色方案配置中更改了color9，那么新颜色不会显示在该分配方案中。

    为了向后兼容，Guacamole还将接受四个特定值作为配色方案参数：

    • black-white

      白色背景，黑色文本

    • gray-black

      黑色背景，灰色文本。这是默认的配色方案

    • green-black

      黑色背景，绿色文本。

    • white-black

      黑色背景，白色文本。

  • font-name

    使用的字体名字。该参数是可选的。如果没有指定，将使用monospace作为默认替代值。

  • font-size

    使用字体的大小（单位磅）。该参数是可选的。如果没有指定，将使用12作为默认替代值。

  • scrollback

    终端回滚缓冲区中允许的最大行数。此参数是可选的。如果未指定，则回滚缓冲区将限制为最多1000行。

网络唤醒

Guacamole实现了在尝试与主机建立连接之前向远程主机发送magic wake-on-lan packet的支持。以下参数控制此功能的行为，默认情况下禁用此功能。

❗重点:
有几个因素会影响网络唤醒（WoL）正常运行的能力，其中许多因素不在Guacamole配置的范围之内。如果要在Guacamole中配置WoL，则还应熟悉需要配置的其他组件，以便其正常运行。

  • wol-send-packet

    如果设置为true，Guacamole将在建立连接之前尝试发送LAN唤醒数据包。此参数是可选的。默认情况下，Guacamole不会发送WoL数据包。启用此选项需要同时配置wol-mac-addr参数，否则不会发送WoL数据包。

  • wol-mac-addr

    此参数配置Guacamole用在魔术WoL数据包中用于尝试唤醒远程系统的MAC地址。如果启用wol-send-packet，则需要此参数，否则将不发送WoL数据包。

  • wol-broadcast-addr

    此参数配置Guacamole将向其发送WoL数据包以唤醒主机的IPv4广播地址或IPv6多播地址。此参数是可选的。如果未提供任何值，将使用默认的本地IPv4广播地址（255.255.255.255）。

  • wol-udp-port

    此参数配置将在WoL数据包中设置的UDP端口。在大多数情况下，要被唤醒的系统不会处理UDP端口；但在某些情况下，设置端口很有用，例如路由器正在监听数据包并且可以根据所使用的端口做出路由决策的情况下。如果未配置，将使用默认的UDP端口9。

  • wol-wait-time

    默认情况下，WoL数据包发送后，Guacamole会立即尝试连接到远程主机。在某些情况下，可能需要在初始连接之前等待Guacamole，以便给远程系统引导时间。将此参数设置为正值将导致Guacamole在尝试初始连接之前等待指定的秒数。此参数是可选的。

参数令牌

‎连接参数的值可以包含"令牌"，使用时将被Guacamole替换。这些令牌允许连接参数的值被使用连接的用户动态改变，并提供一种转发身份验证信息的简单方法，而无需将该信息存储在连接配置本身中，只要远程桌面连接使用与 Guacamole 相同的凭据即可。‎

每个令牌的形式为${TOKEN_NAME}或${TOKEN_NAME:MODIFIER}，其中TOKEN_NAME是令牌所代表的值的描述性名称，可选的MODIFIER 是下面记录的用于动态修改令牌的修饰符之一。没有相应值的令牌永远不会被替换，但是如果你在连接参数中需要此类文本，并且希望保证不会用令牌值替换此文本，则可以通过添加额外的前导“ ” 来 转 义 令 牌 ， 如 “ ‘ ”来转义令牌，如“` ”来转义令牌，如“‘${TOKEN_NAME}`”。

  • ${GUAC_USERNAME}

    当前Guacamole用户的用户名。当用户访问一个连接时，这个令牌将被动态替换为他们在登录到Guacamole时提供的用户名。

  • ${GUAC_PASSWORD}

    当前Guacamole用户的密码。当用户访问一个连接时，这个令牌将被动态替换为他们登录到Guacamole时使用的密码。

  • ${GUAC_CLIENT_ADDRESS}

    当前Guacamole用户的IPv4或IPv6地址。这将是当前用户登录时连接到Guacamole服务器的HTTP客户端的地址。

  • ${GUAC_CLIENT_HOSTNAME}

    当前Guacamole用户的主机名。这将是当前用户登录时与Guacamole服务器的HTTP连接的客户端的主机名。如果无法确定此类主机名，则将使用IPv4或IPv6地址，此令牌将等效于${GUAC_CLIENT_ADDRESS}。

  • ${GUAC_DATE}

    Guacamole服务器本地时区中的当前日期。将以YYYYMMDD格式编写，其中YYYY是年份，MM是月份，DD是月的第几天，都是用零填充的。当用户访问连接时，该令牌将被动态替换为连接开始的日期。

  • ${GUAC_TIME}

    Guacamole服务器本地时区中的当前时间。这将以HHMMSS格式编写，其中HH是24小时制中的小时，MM是分钟，SS是秒，都是用零填充。当用户访问一个连接时，这个令牌将被动态替换为连接开始的时间。

注意，每次使用连接时，这些令牌都会被动态替换。如果两个不同的用户同时访问同一个连接，则两个用户将使用不同的连接参数集彼此独立地进行连接。

令牌修饰符

有时，使用令牌提供的值很有用，但需要稍加修改。这些修饰符可以在令牌的末尾被随意指定，并用冒号（:）与令牌名分隔，格式为 ${TOKEN_NAME:MODIFIER}。目前支持以下修饰符：

  • LOWER

    将令牌的整个值转换为小写。如果用户使用大小写混合的用户名登录到Guacamole，但远程系统要求用户名为小写，则这一点非常有用。

  • UPPER

    将令牌的整个值转换为大写。

特定扩展的令牌

每个扩展还可以实现自己的任意令牌，这些令牌可以动态填充扩展提供的值。在这些扩展中，属性名被规范化为一种标准格式，由所有用下划线分隔的大写字母组成。

CAS扩展的令牌

‎CAS 扩展将在用户通过身份验证时读取 CAS 服务器提供的属性，并将这些可获取的属性当作是令牌。CAS 服务器必须明确配置以向客户端（Guacamole）释放某些属性，且那些配置超出了本文档的讨论范围。CAS 服务器配置为释放的任何属性都应可供 Guacamole 用作令牌，以便在连接中使用。令牌名称将被附加CAS_前缀。CAS服务器配置的释放属性firstname、lastname、email以及mobile的会生成以下令牌：

  • ${CAS_FIRSTNAME}
  • ${CAS_LASTNAME}
  • ${CAS_EMAIL}
  • ${CAS_MOBILE}
LDAP扩展的令牌

LDAP扩展将会读取由LDAP服务器提供并在guacamole.properties文件中指定的用户属性。为一个用户检索的属性是用ldap-user-attributes 进行配置的。用户必须可用从自己的LDAP对象中读取属性值。令牌名称将被追加LDAP_前缀。例如，向guacamole.properties中配置如下行：

ldap-user-attributes: cn, givenName, sn, mobile, mail

将会产生如下可用在连接参数中的令牌：

  • ${LDAP_CN}
  • ${LDAP_GIVENNAME}
  • ${LDAP_SN}
  • ${LDAP_MOBILE}
  • ${LDAP_MAIL}

参数提示

‎在某些情况下，Guacamole可能会确定需要其他信息才能成功打开或继续连接。在这些情况下，guacd 将向客户端发送一条指令以检索该信息，这会导致提示用户输入这些附加参数。‎

‎目前，将向用户触发此提示的唯一参数是 RDP 和 VNC 协议的身份验证请求，其中身份验证器未作为连接配置的一部分提供。‎

❗重点:
请务必注意，只有在尚未作为连接的一部分提供该信息的情况下，才会生成对参数的请求。绝不会要求用户提供替换或覆盖已提供值的连接参数那种参数，包括身份验证信息。

例如，如果与RDP服务器的连接配置指定了用户名和密码，且该用户名或密码不正确并导致身份验证失败，则 Guacamole 不会提示用户输入其他凭据。对于强制实施NLA的RDP服务器，这将导致连接失败。其他RDP服务器的行为可能有所不同，并允许用户尝试其他凭据，但这超出了Guacamole的控制范围，Guacamole不会使用用户的输入覆盖预配置的身份验证值。

配置guacd

guacd.conf

guacd使用一个名为guacd.conf的配置文件进行配置，默认位于/etc/guacamole目录下。该文件遵循一个简单的，类似于INI的格式：

#
# guacd configuration file
#

[daemon]

pid_file = /var/run/guacd.pid
log_level = info

[server]

bind_host = localhost
bind_port = 4822

#
# The following parameters are valid only if
# guacd was built with SSL support.
#

[ssl]

server_certificate = /etc/ssl/certs/guacd.crt
server_key = /etc/ssl/private/guacd.key

配置项以参数/值对形式给出，其中参数的名字在=的左边，值在右边。每个参数必须出现在一个适当的部分中，用方括号内的部分名称表示。这些部分的名称很重要；它是一个部分名称与一个参数的配对，该参数构成了要设置的完全限定参数。

为了文档的可读性，注释可以在guacd.conf的任意位置使用#符号添加。#后面的整行文本都将被忽略。

如果你需要在参数值中指定特殊字符，比如空格或任何上述符号，可以将参数放在双引号中。

[ssl]

# Whitespace is legal within double quotes ...
server_certificate = "/etc/ssl/my certs/guacd.crt"

# ... as are other special symbols
server_key = "/etc/ssl/#private/guacd.key"

注意，即使在双引号内，某些符号仍然具有特殊含义，比如双引号自身或换行符。如果你需要包含这些字符，则必须用反斜线\进行”转义“。

# Parameter value containing a double quote
parameter = "some\"value"

# Parameter value containing newline characters
parameter2 = "line1\
line2\
line3"

# Parameter value containing backslashes
parameter3 = "c:\\windows\\path\\to\\file.txt"

不要太担心更复杂的格式化示例——它们很少需要，如果配置文件以某种方式无效，guacd会抛出解析错误。为确保正确输入参数值，只需遵循以下准则：

  1. ‎如果值不包含任何特殊字符，则只需按原样包含它‎。
  2. 如果值包含任何特殊符号（空格，换行符，#，\或"），用双引号包含整个值。
  3. 如果双引号内包含想要的换行符\或#，请用反斜线\进行转义。
[daemon]部分

  • pid_file

    主guacd进程的PID写入文件的名称。这主要是启动脚本需要的，启动脚本需要监控guacd的状态，并必要时杀掉进程。如果指定了此参数，则运行guacd的用户必须具有足够的权限来创建或修改指定的文件，否则启动会失败。

  • log_level

    guacd写入系统日志（如果是前台运行，则是控制台）的日志消息的最大级别。如果省略，info将作为默认级别。

    合法值有trace，debug，info，warning和error。

[server]部分

  • bind_host

    guacd监听连接时绑定的主机。如果未指定，guacd将绑定到localhost，并且只有来自托管guacd的服务器内的连接才会成功。

  • bind_port

    guacd监听连接时绑定的端口。如果未指定，使用4822端口。

[ssl]部分

  • server_certificate

    用于SSL加密Guacamole协议的证书名称。如果指定该选项，将会启用SSL加密，且Guacamole web应用程序还需要在guacamole.properties中进行SSL的相关配置。

  • server_key

    用于SSL加密Guacamole协议的私钥名称。如果指定该参数，将会启用SSL加密，且Guacamole web应用程序还需要在guacamole.properties中进行SSL的相关配置。

命令行选项

你还可以使用命令行工具影响guacd的配置。如果提供，这些选项的优先级大于系统范围的配置文件：

  • -b HOST

    改变guacd监听的主机或地址。

    这对应于guacd.conf文件的[server]部分的bind_host参数。

  • -l PORT

    改变guacd监听的端口（默认4822）。

    这对应于guacd.conf文件的[server]部分的bind_port参数。

  • -p PIDFILE

    使guacd将守护进程的PID写入指定的文件。这对于初始化脚本很有用，并且由提供的初始化脚本使用。

    这对应于guacd.conf文件的[daemon]部分的pid_file参数。

  • -L LEVEL

    设置guacd写入系统日志（如果是前台运行，则是控制台）的日志消息的最大级别。合法值有trace，debug，info，warning和error。默认值是info。

    这对应于guacd.conf文件的[daemon]部分的log_level参数。

  • -f

    使guacd在前台运行，而不是自动运行在后台。

如果guacd被构建为支持SLL，且通过如下参数提供了SSL证书和私钥，则通过Guacamole协议发送的数据可以使用SSL进行加密。

  • -C CERTIFICATE

    用于SSL加密Guacamole协议的证书名称。如果指定该选项，将会启用SSL加密，且Guacamole web应用程序还需要在guacamole.properties中进行SSL的相关配置。

    这对应于guacd.conf文件的[ssl]部分的server_certificate参数。

  • -K KEY

    用于SSL加密Guacamole协议的私钥名称。如果指定该参数，将会启用SSL加密，且Guacamole web应用程序还需要在guacamole.properties中进行SSL的相关配置。

    这对应于guacd.conf文件的[ssl]部分的server_key参数。

Logo
华为开发者空间

华为开发者空间，是为全球开发者打造的专属开发空间，汇聚了华为优质开发资源及工具，致力于让每一位开发者拥有一台云主机，基于华为根生态开发、创新。

更多推荐

cover

华为云数据仓库专业级开发者认证重磅发布

avatar 华为开发者空间
cover

KubeEdge 新版本5大特性解读：更完备的节点设备能力，全新的Dashboard体验

avatar 华为开发者空间
cover

一文带你搞懂GaussDB数据库性能调优

avatar 华为开发者空间