Apache Guacamoleв„ў

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.

We call it clientless because no plugins or client software are required.

Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.

Access your computers from anywhere

Because the Guacamole client is an HTML5 web application, use of your computers is not tied to any one device or location. As long as you have access to a web browser, you have access to your machines.

Keep your desktop in the cloud

Desktops accessed through Guacamole need not physically exist. With both Guacamole and a desktop operating system hosted in the cloud, you can combine the convenience of Guacamole with the resilience and flexibility of cloud computing.

Free and open source

Apache Guacamole is and will always be free and open source software. It is licensed under the Apache License, Version 2.0, and is actively maintained by a community of developers that use Guacamole to access their own development environments.

We feel this sets us apart from other remote desktop solutions, and gives us a distinct advantage.

Built on a well-documented API

Apache Guacamole is built on its own stack of core APIs which are thoroughly documented, including basic tutorials and conceptual overviews in the online manual. These APIs allow Guacamole to be tightly integrated into other applications, whether they be open source or proprietary.

Commercially supported

For enterprises, dedicated commercial support is also available through third party companies.

Copyright © 2020 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. The HTML5 shield logo has been modified from the original work of the World Wide Web Constortium (W3C), which is licensed under the Creative Commons Attribution 3.0 license.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.

Apache Guacamoleв„ў

All recent Guacamole releases are listed here, along with several historical releases. Each release below is listed by the version of the overall software bundle and the date on which it was released. Clicking on the version number will take you to the release notes and downloads for that release, including a pre-built guacamole.war file and all associated source code.

Please be sure to read the installation instructions in the manual thoroughly. If you do not wish to build things from source, you can also install Guacamole using Docker.

If you are looking for the absolute latest unreleased code (or extremely old code not archived here), please check our git repositories on GitHub.

Which version should I download?

Unless you already know that you need a very specific version (your custom or third-party extensions use an older version of the Guacamole API, for example), you should always download the most recent release. Guacamole development is very active, and recent releases will contain bug fixes and performance improvements that will be absent in older releases.

Version	Summary	Release Date
1.3.0	Automatic prompting for remote desktop credentials, user group support for CAS and OpenID, bug fixes.	2021-01-01
1.2.0	Support for SAML 2.0, Wake-on-LAN, and easy switching between active connections, numerous fixes for RDP, improvements to TOTP, database support, and behavior on iOS devices.	2020-06-28
1.1.0	Dynamic image quality, support for Kubernetes, migration to FreeRDP 2.0.0 and Apache Directory API, fixes and improvements to Docker images, terminal behavior, and user groups.	2020-01-29
1.0.0	User groups, improved clipboard integration, TOTP (Google Authenticator), RADIUS, dead keys.	2019-01-08
0.9.14	OpenID Connect single sign-on, SQL Server support, CAS «ClearPass», user login/logout history, fixes and improvements for RDP, clipboard, file transfer, and terminal emulation.	2018-01-18
0.9.13-incubating	CAS single sign-on, fixes for VNC/RDP/SSH/telnet, in-browser playback of screen recordings, automatic connection failover, 256-color console codes.	2017-07-30
0.9.12-incubating	Thumbnails as tab icons, HTTP header authentication, performance improvements, and fixes for printing, file transfer, and terminal emulation.	2017-04-01
0.9.11-incubating	Two-factor authentication, password policies, improvements to Docker and LDAP.	2017-02-02
0.9.10-incubating	Screen sharing, recording, improved file transfer, audio input, Docker support for LDAP.	2016-12-29

Pre-Apache releases

All releases below are from prior to Guacamole’s acceptance into the Incubator. They are not Apache Software Foundation releases, and are licensed under the MIT license.

Version	Summary	Release Date
0.9.9	Dynamic JPEG/WebP, improved LDAP support, central connection history, filterable connection/user lists.	2015-12-18
0.9.8	Multiple auth extensions, file browsing, VNC audio and file transfer, RDP performance flags.	2015-09-09
0.9.7	Simpler installation/configuration, theming support, Docker support, translations, multiple bug fixes.	2015-06-10
0.9.6	PostgreSQL support, database speed improvements, RDP memory fixes, session management.	2015-03-30
0.9.5	Fixes for iOS, regressions from 0.9.4, and printing issues. Scrollbar for SSH and telnet.	2015-02-16
0.9.4	Completely new interface, single-tab layout, WebSockets by default, simultaneous connections.	2015-01-06
0.9.3	Config file for guacd, improved keyboard, HTTP Basic auth, C0 control codes, bug fixes.	2014-09-30
0.9.2	Wide character support, automated telnet login, keyboard-interactive auth, bug fixes.	2014-07-21
0.9.1	Performance enhancements, improved UI, better mobile support, telnet, MySQL auth fixes	2014-05-23
0.8.4	MySQL auth fixes	2014-05-23
0.9.0	Adds support for file transfer, RemoteApp, public key auth, and improved error handling.	2014-03-28
0.8.3	LDAP support, connection grouping and balancing, improved performance, SSL support.	2013-08-28

Copyright © 2020 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. The HTML5 shield logo has been modified from the original work of the World Wide Web Constortium (W3C), which is licensed under the Creative Commons Attribution 3.0 license.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.

Apache Guacamoleв„ў

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.

We call it clientless because no plugins or client software are required.

Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.

Access your computers from anywhere

Because the Guacamole client is an HTML5 web application, use of your computers is not tied to any one device or location. As long as you have access to a web browser, you have access to your machines.

Keep your desktop in the cloud

Desktops accessed through Guacamole need not physically exist. With both Guacamole and a desktop operating system hosted in the cloud, you can combine the convenience of Guacamole with the resilience and flexibility of cloud computing.

Free and open source

Apache Guacamole is and will always be free and open source software. It is licensed under the Apache License, Version 2.0, and is actively maintained by a community of developers that use Guacamole to access their own development environments.

We feel this sets us apart from other remote desktop solutions, and gives us a distinct advantage.

Built on a well-documented API

Apache Guacamole is built on its own stack of core APIs which are thoroughly documented, including basic tutorials and conceptual overviews in the online manual. These APIs allow Guacamole to be tightly integrated into other applications, whether they be open source or proprietary.

Commercially supported

For enterprises, dedicated commercial support is also available through third party companies.

Copyright © 2020 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. The HTML5 shield logo has been modified from the original work of the World Wide Web Constortium (W3C), which is licensed under the Creative Commons Attribution 3.0 license.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.

Apache Guacamoleв„ў

Release documentation

Apache Guacamole is split into two subprojects: «guacamole-client», the HTML5 web application which serves the Guacamole client to users, and «guacamole-server», the remote desktop proxy which the web application communicates with. The source code for each of these may be downloaded below.

You must verify the integrity of any downloaded files using the OpenPGP signatures we provide with each release. The signatures should be verified against the KEYS file, which contains the OpenPGP keys of Apache Guacamole’s Release Managers. Checksums of each released file are also provided.

If you do not wish to build Apache Guacamole entirely from source, pre-built versions of the web application (.war) and all extensions are provided here in binary form for convenience. Please note that guacamole-server must still be built and installed from source.

Release notes

The 1.3.0 release features support for automatically prompting users for their remote desktop credentials, user group support for both CAS and OpenID, and several bug fixes. For a full list of all changes in this release, please see the changelog.

The 1.3.0 release is compatible with older 1.x components. You should upgrade older components to 1.3.0 when possible, however things should continue to work correctly in the interim:

• Extensions written for older 1.x releases can be used by 1.3.0.
• Components written for the version of the Guacamole protocol used by older 1.x releases can be used with components of the 1.3.0 release.

Regardless of inter-component compatibility, there are changes in 1.3.0 which may affect downstream users of Guacamole’s APIs and the Guacamole protocol. Please see the deprecation / compatibility notes section for more information.

Automatic prompting for remote desktop credentials

Historically, Guacamole has required that remote desktop credentials either be stored alongside connection configuration, passed through from web application authentication (typically Active Directory), or retrieved interactively by the remote desktop itself.

In addition to these methods, Guacamole will now automatically prompt the user to enter any credentials not already provided by the administrator if those credentials are required.

User group support for CAS and OpenID

If using a CAS or OpenID identity provider to automatically sign in your users, user groups can now also be retrieved from the identity provider. Similar to the support already present for SAML, this support allows the admininstrator to define how user groups are exposed by the identity provider and allow those user groups to affect the permissions granted to their members within Guacamole.

Changelog

User interface / platform

• Parameter prompting within client interface (GUACAMOLE-221)
• Objects may appear duplicated if access is granted via multiple groups (GUACAMOLE-1021)
• Support automatic conversion of usernames to lowercase/uppercase via parameter tokens (GUACAMOLE-1081)
• Ctrl+Alt+End(Supr) keyboard shortcut only works once (GUACAMOLE-1125)
• Connection group permissions do not correctly determine presence of save/delete buttons (GUACAMOLE-1150)

Docker images

• Add support for TOTP to Guacamole Docker image (GUACAMOLE-753)
• Add support for HTTP header authentication to Guacamole Docker image (GUACAMOLE-857)
• Update base image of Guacamole Docker image (GUACAMOLE-980)
• Add environment variables for ldap-user-attributes property to Guacamole Docker image (GUACAMOLE-987)
• Add support for CAS to Guacamole Docker image (GUACAMOLE-1082)
• Run web application as reduced-privilege user within Guacamole Docker image (GUACAMOLE-1110)
• Add environment variables for ldap-dereference-aliases , ldap-follow-referrals , ldap-max-referral-hops , and ldap-operation-timeout properties to Guacamole Docker image (GUACAMOLE-1147)

Authentication, integration, and storage

• Add support for retrieving user groups from CAS (GUACAMOLE-793)
• Add support for retrieving user groups from OpenID (GUACAMOLE-1172)
• PostgreSQL database connection may unexpectedly fail due to time out (GUACAMOLE-919)
• Login using LDAP fails internally if TOTP is used without automatic user creation (GUACAMOLE-1149)
• CAS module causes app.js download errors (GUACAMOLE-1120)
• Allow server timezone info to be submitted to MySQL / MariaDB (GUACAMOLE-760)
• MySQL SSL truststore path must be a valid URL (GUACAMOLE-1135)
• MySQL SSL client certificate properties incorrectly return truststore property values (GUACAMOLE-1136)
• Query may fail if all connections disconnect while listing active connections (GUACAMOLE-942)
• RFC2865 requires NAS IP address to be submitted for RADIUS (GUACAMOLE-1001)
• Standardize on filtered history query for user and connection management (GUACAMOLE-1123)
• TOTP authentication fails when totp-period is set (GUACAMOLE-1146)
• Enabling skip-if-unavailable breaks expired password change (GUACAMOLE-1152)

Protocol support / guacd

• RDP log message incorrectly refers to “VNC” (GUACAMOLE-982)
• SFTP upload directory ignored for RDP connections (GUACAMOLE-1031)
• RDP disable-copy flag does not work (GUACAMOLE-1158)
• Memory allocated for outbound SVC PDUs may not be freed (GUACAMOLE-1181)
• Memory allocated for outbound RDP clipboard data is not properly freed (GUACAMOLE-1182)
• Thread mutexes within Guacamole’s various supported protocols are not always cleanly destroyed (GUACAMOLE-1114)
• RDP support may fail to build if SSH support is unavailable (GUACAMOLE-1122)

Internationalization

• Update/improve Chinese translation (GUACAMOLE-903)
• Update/improve Russian translation (GUACAMOLE-1054)
• Add support for Catalan language (GUACAMOLE-1078)

Documentation

• Documented Duo secret key length is incorrect (GUACAMOLE-819)
• Guacamole Docker image documentation incorrectly states Docker links are supported for LDAP (GUACAMOLE-912)
• allowed-languages property incorrectly documented as available-languages (GUACAMOLE-1107)

General housekeeping and cleanup

• Remove unused UNIX_TIME macro (GUACAMOLE-949)
• RDP comment incorrectly refers to “VNC” (GUACAMOLE-1103)
• Exclude nbproject/ directory from git via .gitignore (GUACAMOLE-1151)

Deprecation / Compatibility notes

Each 1.x release of Apache Guacamole should be compatible with components of older 1.x releases. This compatibility is intended at the Guacamole protocol level and at the extension level, but not necessarily at the API level. This means:

• Extensions from older 1.x releases should still work in binary form, but may need code changes before their source will build against a newer version of guacamole-ext.
• Software which uses the Guacamole protocol of an older 1.x release should still work.
• Software which uses libguac from an older 1.x release should still work by continuing to use the libguac from that release, as newer versions of libguac may not be API/ABI compatible. In the case of third-party protocol support plugins for guacd, this means that the guacd from that release must also be used. Compatibility with respect to libguac is represented by the soname.
• You should update to newer versions where applicable and when possible.

As of 1.3.0, the following changes have been made which affect compatibility with past releases:

Java API (guacamole-common) changes

Implementations of GuacamoleSocket should now implement getProtocol()

The required and argv instructions both refer to connection parameters by name. As it is the underlying protocol of a connection that determines the semantics of connection parameters, client implementations will commonly need to expose this information in some way. The mainline web application provided by Apache Guacamole is one such implementation.

A new getProtocol() function has been added to GuacamoleSocket to facilitate this, and implementations of GuacamoleSocket should aim to provide implementations of this function with that in mind.

This will happen automatically for ConfiguredGuacamoleSocket .

• GUACAMOLE-221 — Parameter prompting within client interface

Extension API (guacamole-ext) changes

Deprecation of getHistory() for User and Connection interfaces

The User and Connection interfaces have both continued to define a basic getHistory() function for retrieving a raw list of history records. Unlike the getUserHistory() and getConnectionHistory() functions exposed by the UserContext , the getHistory() functions do not support filtering or searching.

The old getHistory() functions have now been deprecated in favor of newer functions that do support filtering. Implementations that provide getHistory() will continue to work, but should migrate to the new functions when possible.

• GUACAMOLE-1123 — Standardize on filtered history query for user and connection management

Guacamole protocol changes

The new required instruction

To allow the server to request that the client provide credentials (or any other parameters), a new required instruction has been added to the Guacamole protocol. This instruction informs the client that one or more connection parameters need to be specified for the connection to continue. If the client indicated support for the required instruction during the initial connection handshake, the client is then expected to supply values for each of these parameters using argv streams.

• GUACAMOLE-221 — Parameter prompting within client interface

libguac API changes

protocol_version added to guac_user_info structure

A new protocol_version member has been added to guac_user_info to allow implementations to make decisions based on the Guacamole protocol version in use, affecting the size of this structure.

Additionally, because guac_user_info forms a part of guac_user , this change also affects the memory offsets of members of the guac_user structure which follow the info member, such as data and various instruction handlers.

Downstream usages of libguac which make use of guac_user or guac_user_info will need to be rebuilt to ensure that the structure sizes and memory offsets used are correct.

• GUACAMOLE-221 — Parameter prompting within client interface

Copyright © 2020 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. The HTML5 shield logo has been modified from the original work of the World Wide Web Constortium (W3C), which is licensed under the Creative Commons Attribution 3.0 license.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.