Test Your Installation

Testing Basic Functionality with "user-mapping.xml"

Apache Guacamole comes with a built-in, simplified, XML-driven authentication mechanism for the sake of testing. Accounts and connections can be defined within /etc/guacamole/user-mapping.xml without having to install support for a database. The default file included with Keeper Connection Manager looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!--

  user-mapping.xml:

      Configuration file for Apache Guacamole's built-in, XML-based
      authentication scheme.

  WARNING: user-mapping.xml is meant to provide an easy means of verifying an
  Apache Guacamole install. Production deployments of Guacamole should switch
  to one of the database authentication methods or LDAP when possible.

  Keeper Connection Manager provides packages for these authentication methods,
  which are intended for production use:

      - kcm-guacamole-auth-jdbc-mysql
      - kcm-guacamole-auth-jdbc-postgresql
      - kcm-guacamole-auth-ldap

  Two-factor authentication using Duo is also supported, and can be layered on
  top of any of the above methods:

      - kcm-guacamole-auth-duo

-->
<user-mapping>
    ...
</user-mapping>

As noted at the top of the file, you can leverage this to verify that your Guacamole installation is functional, however the user-mapping.xml file should not be used for production deployments. Production deployments of Guacamole should instead use one of the authentication extensions, such as the database support or LDAP. Unlike the XML, all of these extensions are intended for production use.

Format of user-mapping.xml

The user-mapping.xml file consists of a main, root-level <user-mapping> element:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>
    ...
</user-mapping>

Defining user accounts

This <user-mapping> element may contain any number of <authorize> blocks, each describing a user and their corresponding password:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>

    <!-- First user -->
    <authorize username="user1" password="pass1">
    </authorize>

    <!-- Second user -->
    <authorize username="user2" password="pass2">
    </authorize>

</user-mapping>

Granting access to connections

The <authorize> blocks in turn may contain any number of <connection> blocks, each describing a connection that should be accessible to the user:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>

    <!-- First user -->
    <authorize username="user1" password="pass1">

        <connection name="Example VNC connection">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

    </authorize>

    <!-- Second user -->
    <authorize username="user2" password="pass2">

        <connection name="Example VNC connection">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

        <connection name="Example RDP connection">
            <protocol>rdp</protocol>
            <param name="hostname">otherhost</param>
            <param name="username">RDPUSER</param>
            <param name="password">RDPPASS</param>
        </connection>

    </authorize>

</user-mapping>

This file is automatically reread when modified, so you should be able to immediately log in when you define a new user in this way, however changes to an active user’s connections will not be available to that user until they logout.

Defining connections (protocols and parameters)

Each <connection> contains exactly one <protocol> element (specifying the unique name of the protocol to use to connect to the remote desktop) and any number of <param> elements (specifying the name of a parameter and the value to use for that connection). These protocol and parameter names are standardized and case-sensitive. The names of each supported protocol are defined by Guacamole, and the names of available parameters are defined by the part of Guacamole implementing that support:

Protocol	Unique name	Keeper Connection Manager package
VNC	vnc	kcm-libguac-client-vnc
RDP	rdp	kcm-libguac-client-rdp
SSH	ssh	kcm-libguac-client-ssh
Telnet	telnet	kcm-libguac-client-telnet
Kubernetes	kubernetes	kcm-libguac-client-kubernetes
MySQL	mysql	kcm-libguac-client-mysql

The names of many parameters are predictable and common across the supported protocols, like "hostname" and "port", but please consult the documentation for the relevant protocol for a full list of available parameters and their allowed values, as well as which parameters are absolutely required.

When ready to move to a production deployment leveraging a database, protocol and parameter names will be handled automatically by the web interface enabled by the database. The internal names of protocols and their parameters are mainly useful for authentication methods that require connections to be entered manually (user-mapping.xml, encrypted JSON, connections defined directly within an LDAP directory, or custom extensions leveraging the Guacamole API). They are not visible when using one of the database authentication backends except if manually manipulating data within the database using SQL.

Moving to production

When finished testing, you should prepare to move forward with adding the remaining layers normally required by a production deployment:

1. A supported database: MySQL / MariaDB, PostgreSQL, and SQL Server are supported. If you do not already have a database deployed, or are unfamiliar with deploying databases, instructions are provided for installing a local instance of MariaDB.

2. SSL termination: Apache HTTPD and Nginx are supported for this purpose. If you do not already have a reverse proxy in place, or are unfamiliar with installing and configuring a reverse proxy, instructions are provided for installing Nginx to provide SSL termination.