Quickstart Guide (CentOS / RHEL 7)

The “Quickstart Guide” is a walkthrough which covers a typical install of Glyptodon Enterprise, and configuring and testing access to a remote desktop. It takes roughly five minutes to run through the guide from start to finish, including time waiting for packages to download.

Step 1: Set up the YUM repository

If you have not already done so, the Glyptodon Enterprise YUM repository needs to be defined, such that the “yum” utility can find the various RPM packages which make up Glyptodon Enterprise.

The necessary repository definition file can be viewed within your account information on the Glyptodon Enterprise website. Copy the contents of the file shown in your account information, and use a text editor to paste the contents into a new file within /etc/yum.repos.d:

$ sudo vi /etc/yum.repos.d/glyptodon.repo

This file should ultimately look like:

[glyptodon]
name=Glyptodon Enterprise
baseurl=https://USERNAME:PASSWORD@enterprise.glyptodon.org/release/1/el7/$basearch/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://enterprise.glyptodon.org/release/RPM-GPG-KEY-glyptodon-release

where “USERNAME” and “PASSWORD” are the repository credentials which were generated for you when your organization’s Glyptodon Enterprise account was created.

Step 2: Install the @glyptodon-guacamole package group

Glyptodon Enterprise provides a @glyptodon-guacamole package group for convenience which installs all of the packages typically required for an Apache Guacamole deployment, and includes support for VNC, RDP, and SSH:

$ sudo yum install @glyptodon-guacamole

This will install the following key packages:

Package name Description
glyptodon-guacamole The Apache Guacamole web application
glyptodon-guacd The Apache Guacamole proxy daemon
glyptodon-libguac-client-vnc VNC support for guacd
glyptodon-libguac-client-rdp RDP support for guacd
glyptodon-libguac-client-ssh SSH support for guacd

Step 3: Deploy Guacamole under Tomcat

Apache Guacamole is a web application which is served through the Apache Tomcat application server. If you have not already installed Tomcat, you must do so prior to deploying Guacamole:

$ sudo yum install tomcat

Once Tomcat is installed, the “tomcat” system user must be added to the “guacamole” group, such that the Guacamole web application running under Tomcat will be able to read its own configuration files:

$ sudo usermod -aG guacamole tomcat

To deploy Guacamole to Tomcat, create a symbolic link from the web application’s “guacamole.war” file, located in /usr/share/guacamole, within “/var/lib/tomcat/webapps”:

$ sudo ln -s /usr/share/guacamole/guacamole.war /var/lib/tomcat/webapps/

Step 4: Start Tomcat and guacd

Apache Guacamole requires its proxy daemon service, “guacd”, in order to connect to remote desktops. This service must be started for Guacamole to function, and should be configured to start automatically on boot:

$ sudo systemctl start guacd 
$ sudo systemctl enable guacd 

The same must be done for Tomcat, such that the web application itself will be running and available:

$ sudo systemctl start tomcat
$ sudo systemctl enable tomcat

At this point, Apache Guacamole should be working, and a login screen should be visible if you visit http://HOSTNAME:8080/guacamole/ with a web browser, where “HOSTNAME” is the hostname or IP address of your server.

Step 5: Add a test user and connection

Apache Guacamole comes with a built-in, simplified, XML-driven authentication mechanism for the sake of testing. You can verify that your Guacamole installation is functional by editing the “user-mapping.xml” configuration file used by this mechanism to add a user and a few connections:

$ sudo vi /etc/guacamole/user-mapping.xml

The “user-mapping.xml” file consists of a main <user-mapping> element and any number of <authorize> blocks describing users, their passwords, and the connections they can access. For example, to add a user named “test-user” with password “test-password” and access to a single SSH connection to the Guacamole server itself, you would add an <authorize> block like:

<authorize username="test-user" password="test-password">
    <connection name="Test Connection">
        <protocol>ssh</protocol>
        <param name="hostname">localhost</param>
    </connection>
</authorize>

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. Changes to an active user’s connections defined within “user-mapping.xml” will not be available to that user until they logout, however.