Installing Apache Guacamole on Ubuntu and Debian

Traducciones al Español
Estamos traduciendo nuestros guías y tutoriales al Español. Es posible que usted esté viendo una traducción generada automáticamente. Estamos trabajando con traductores profesionales para verificar las traducciones de nuestro sitio web. Este proyecto es un trabajo en curso.
Create a Linode account to try this guide with a $ credit.
This credit will be applied to any valid services used during your first  days.

Before You Begin

  1. If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.

  2. Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.

This guide is written for a non-root user. Commands that require elevated privileges are prefixed with sudo. If you’re not familiar with the sudo command, you can check our Users and Groups guide.

Install Guacamole Server

  1. Log in to the Compute Instance over SSH or Lish.

  2. Install all required dependencies. For Debian users, replace libjpeg-turbo8-dev with libjpeg62-turbo-dev.

    sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev \
        libpng-dev libtool-bin libossp-uuid-dev libvncserver-dev \
        freerdp2-dev libssh2-1-dev libtelnet-dev libwebsockets-dev \
        libpulse-dev libvorbis-dev libwebp-dev libssl-dev \
        libpango1.0-dev libswscale-dev libavcodec-dev libavutil-dev \
  3. Download the Guacamole source code

  4. Extract the file and navigate to its directory.

    tar -xvf guacamole-server-1.3.0.tar.gz
    cd guacamole-server-1.3.0
  5. Build the Guacamole Server using the downloaded source files.

    sudo ./configure --with-init-dir=/etc/init.d --enable-allow-freerdp-snapshots
    sudo make
    sudo make install
  6. Update installed library cache and reload systemd

    sudo ldconfig
    sudo systemctl daemon-reload
  7. Start guacd

    sudo systemctl start guacd
    sudo systemctl enable guacd
  8. Create a directory to store Guacamole configuration files and extensions. These directories are used in later steps.

    sudo mkdir -p /etc/guacamole/{extensions,lib}

Install Guacamole Web App

  1. Install Apache Tomcat

    sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user
  2. Download the Guacamole Client

  3. Move the client to the Tomcat web directory.

    sudo mv guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war
  4. Restart both Apache Tomcat and Guacd.

    sudo systemctl restart tomcat9 guacd

Setting up Database Authentication

While Apache Guacamole does support basic user authentication via a user-mapping.xml file, it should only be used for testing. For this guide, we will use production-ready database authentication through MySQL/MariaDB.

  1. Install either MySQL or MariaDB on your system.

    sudo apt install mariadb-server
  2. Run the following command to perform the initial security configuration:

    sudo mysql_secure_installation
  3. Before populating the database, install the MySQL Connector/J library and Guacamole JDBC authenticator plugin.

    1. Download the MySQL Connector/J (Java Connector). For this guide, download the platform independent archived file.

    2. Extract the tar file and copy it to /etc/guacamole/lib/.

      tar -xf mysql-connector-java-8.0.26.tar.gz
      sudo cp mysql-connector-java-8.0.26/mysql-connector-java-8.0.26.jar /etc/guacamole/lib/
    3. Download the JDBC auth plugin for Apache Guacamole. This file can be found on by selecting the release version and then locate the “jdbc” file.

    4. Extract the tar file and copy it to /etc/guacamole/extensions/.

      tar -xf guacamole-auth-jdbc-1.3.0.tar.gz
      sudo mv guacamole-auth-jdbc-1.3.0/mysql/guacamole-auth-jdbc-mysql-1.3.0.jar /etc/guacamole/extensions/
  4. Log in to mysql as the root user.

    mysql -u root -p

    The prompt should change again to mysql>.

  5. While in the mysql prompt, change the root password, create a database, and create a new user for that database. When running the below commands, replace any instance of password with a secure password string for the mysql root user and the new user for your database, respectively.

    ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';
    CREATE DATABASE guacamole_db;
    CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'password';
    GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
  6. Exit the MySQL prompt by typing quit.

  7. Locate the scheme files in the extracted directory for the JDBC plugin.

    cd guacamole-auth-jdbc-1.3.0/mysql/schema
  8. Import those sql schema files into the MySQL database.

    cat *.sql | mysql -u root -p guacamole_db
  9. Create the properties file for Guacamole.

    sudo nano /etc/guacamole/
  10. Paste in the following configuration settings, replacing [password] with the password of the new guacamole_user that you created for the database.

    # MySQL properties
    mysql-port: 3306
    mysql-database: guacamole_db
    mysql-username: guacamole_user
    mysql-password: [password]
  11. Restart all related services.

    sudo systemctl restart tomcat9 guacd mysql

Access Guacamole in a Browser

Apache Guacamole should now be accessible through a web browser.

  1. Open your preferred web browser on your local computer.

  2. Navigate to the URL: [ip]:8080/guacamole, replacing *[ip] with the IP address of your Linode. This will display the login prompt.

    Apache Guacamole login prompt

  3. Enter guacadmin as the username and guacadmin as the password. Then click Login.

Create a New Admin User

Before continuing with configuring Guacamole, it’s recommended that you create a new admin account and delete the original.

  1. Click the guacadmin user dropdown menu on the top right and select Settings.

  2. Navigate to the Users tab and click the New User button.

  3. Under the Edit User section, enter your preferred username and a secure password.

  4. Under the Permissions section, check all the permissions.

  5. Click Save to create the new user.

  6. Log out of the current user and log in as the newly created user.

  7. Click your username on the top left and select Settings from the dropdown menu.

  8. Navigate to the Users tab and click the guacadmin user.

  9. At the bottom of the Edit User screen, click Delete to remove the default user.

Create an SSH Connection

To test Guacamole, let’s create an new connection in Guacamole that opens up an SSH connection to the server.

  1. After logging in to Guacamole, click your username on the top left and select Settings from the dropdown menu.

  2. Navigate to the Connections tab and click New Connection.

  3. Under Edit Connection, enter a name for your new connection (such as “Guacamole SSH”) and select SSH as the Protocol.

    The Edit Connection section of the New Connection screen in Guacamole

  4. Under Parameters, enter your IP address as the Hostname, 22 as the Port, your username as the Username and your user’s password as the Password. Other parameters as available if you wish to edit the connection further.

  5. Click Save to create the new connection.

  6. Navigate back to your user’s home screen by clicking your username on the top left and select Home from the dropdown menu.

  7. Click on the new connection under the All Connections list.

    This should open up a terminal in your browser and automatically log you in to the server with the settings that you specified.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

This page was originally published on

Your Feedback Is Important

Let us know if this guide was helpful to you.

Join the conversation.
Read other comments or post your own below. Comments must be respectful, constructive, and relevant to the topic of the guide. Do not post external links or advertisements. Before posting, consider if your comment would be better addressed by contacting our Support team or asking on our Community Site.
The Disqus commenting system for Linode Docs requires the acceptance of Functional Cookies, which allow us to analyze site usage so we can measure and improve performance. To view and create comments for this article, please update your Cookie Preferences on this website and refresh this web page. Please note: You must have JavaScript enabled in your browser.