Please remember that Guacamole is used by many others without issue, and the more fundamental a problem is, the less likely it’s a bug. Before assuming that you have found a bug, perform basic troubleshooting steps to confirm that Guacamole itself is the only factor affecting whether things work correctly:
/var/log/tomcat/catalina.out or within the
systemd journal (accessed via journalctl)./var/log/syslog, /var/log/messages, or within the systemd journal
(accessed via journalctl).We cannot look into issues which have not actually been reproduced in the latest version of our code. If the problem you’re experiencing has only been reproduced in an older or modified version of Guacamole, the chance is high that the problem has either already been addressed (even if you cannot find a bug report which specifically covers the issue) or that the problem is due to the difference between your code and upstream (even if you are absolutely positive this is impossible).
Before reporting an issue upstream, please confirm that the issue exists within the latest version of the upstream code.
We use JIRA to track all known issues and feature requests. If you have found a bug, please open a new issue in the ASF’s JIRA against the “GUACAMOLE” project:
https://issues.apache.org/jira/browse/GUACAMOLE/
If you have found an issue which may have security implications, please follow responsible disclosure practices:
Both the mailing lists and JIRA are public forums and should not be used for issues with potential security implications. If in doubt, please err on the side of caution and report the issue privately.
If you can access Guacamole but cannot connect to your remote desktop, the relevant log messages will be from guacd - the component of the Guacamole stack which actually handles the low-level connections to remote desktops. Check guacd’s logs for errors or warnings and verify that guacd is actually running.
Messages from guacd are logged to syslog, which is commonly located at
/var/log/syslog, /var/log/messages, or within the systemd journal (accessed
via journalctl). You should also verify that your remote desktop server is
actually accessible from the Guacamole server (using a different remote desktop
client), and that the configuration parameters given for the remote desktop
connection are correct (even if you are positive that you typed them
correctly).
No, Guacamole cannot affect your application in this way. The fact that you are using Guacamole to access the remote desktop has no bearing on whether applications running under that remote desktop function correctly. If an application within the remote desktop is malfunctioning, the problem lies within that application.
RDP inherently only supports changing screen size when initially connecting. In most cases, the screen size of the remote desktop cannot be altered except when the connection is established, and changing the screen size requires reconnecting.
VNC only supports changing the screen size from within the remote desktop, as the screen size is dictated by the VNC server. The client side of a VNC connection cannot dictate the size of the session.
If your VNC server supports changing the screen size of an an active session, you should be able to do so using standard configuration tools within the remote desktop, such as the display settings of your desktop environment or the “xrandr” utility.
Guacamole actually already attempts to do this leveraging the Clipboard API defined by the W3C, with support for the asynchronous version of this API added via GUACAMOLE-559. Browsers vary in their level of support for this API, and some only provide access to the clipboard under very strict circumstances.
The following browsers are known to support clipboard access:
This can be expected to change as the asynchronous version of the clipboard API gains wider adoption.
As much as this might seem like a good idea at first, it is extremely problematic. In practice, doing so does not work, and actually causes even more confusion:
The “copy” and “paste” events can only be relied upon in response to the keyboard shortcuts which cause copy/paste actions on the local machine. Even assuming these keyboard shortcuts can be reliably recognized (regardless of platform-specific differences in what keys are used to copy/paste), allowed to turn into clipboard events, and finally sent through to the remote desktop, this is still tied to the keyboard. Attempts to copy/paste using the mouse will fail.
Different platforms use different keyboard shortcuts for copy/paste, as do different applications within those platforms. The keyboard shortcut required to use the clipboard within the remote desktop cannot be guaranteed to match the shortcut which would result in clipboard events locally, nor can the necessary shortcut be reliably predicted and translated.
The copy operation does not occur instantaneously, but the browser “copy” event requires that clipboard data be set only while the event is being handled (within the main thread). Even assuming that the other problems above are not an issue, there is no stable, non-deprecated means of blocking the main thread such that the clipboard can still be set once the data does become available.
While the “copy” and “paste” events can be useful for traditional web applications, the above issues make them useless for a web application implementing remote desktop like Guacamole. Instead, we use the Clipboard API defined by the W3C, and rely on the browser to provide its own method of granting access to the clipboard.
Guacamole actually already attempts to handle all keyboard events. However, if your browser or operating system reserve some keyboard shortcuts for their own use. Keyboard events propagate from the operating system level, to the browser level, and finally into JavaScript where Guacamole resides. Guacamole can only take control of a keyboard event if each level above Guacamole allows it to do so.
Most browsers now provide a means of bookmarking a web application as a shortcut on the desktop or home screen such that it behaves more like a native application, lacks the normal URL bar, etc. In these cases, the browser will often allow the application to take control of additional keyboard shortcuts which would normally be reserved for the browser. If you are running into this problem, or simply want to use Guacamole as if it were a native application, this is definitely worth a try.
Guacamole is actually independent of keyboard layout, and will send the true local identity of the key pressed. The behavior of each key within the remote desktop should identically match the local behavior of that key.
This holds true for most of Guacamole’s supported protocols, but things get more complex for RDP. Unlike Guacamole, RDP uses scancodes to represent each key, which are a numeric representation of that key’s location, not its identity. To translate the identity of the key into the scancode required by your RDP server, Guacamole must know the keyboard layout of your RDP server, and must have explicit support for that keyboard layout.
This does not mean that your RDP server must have the same keyboard layout as the client machine. It only means that Guacamole must have a keyboard layout definition for the layout used by the RDP server. If a user attempts to use a keyboard with a different layout, Guacamole will translate pressed keys as necessary to match the layout of the RDP server. If the user attempts to press keys which are not present in the keyboard layout of the RDP server, Guacamole will send those keys in the form of Unicode events.
If you are using an RDP server which does not support Unicode events (such as XRDP), locally-pressed keys must have matching keys within the RDP server’s keyboard layout, or they cannot be typed.
Unfortunately, this is not possible. JavaScript cannot access local files directly. You can still share local files, but they must be manually uploaded using Guacamole’s file transfer support.
This is not possible, as JavaScript cannot access local printers. While it is technically possible to cause the PDF to automatically open a print dialog, and on some browsers it is also possible to automatically open the PDF, this does not currently work reliably across all platforms, and whether it will work cannot be detected/predicted. The only reliable mechanism is the one already implemented by Guacamole: file transfer of a standard format like PDF.
No. Because of the complexity involved in implementing an X11 server, this wouldn’t actually work well in practice, however a graphics driver for the X.Org X11 server is currently being written. This driver functions as a display and set of input devices which implement the Guacamole protocol, and should be quite fast.
No. Adding support for NX to Guacamole is not actually as straightforward as it sounds. Unlike remote desktop protocols like VNC and RDP, the protocol referred to as “NX” or “NXv3” is actually a method of compressing yet another protocol: X11. As discussed above, implementing support for X11 does not actually make sense for Guacamole, but there is an X.Org driver which achieves the same goal.
“NXv4”, on the other hand, is proprietary and not publicly documented. No open source implementations of this protocol exist. Unless it becomes publicly documented, or an open source implementation is created, it is not feasible for support for NXv4 to be added to Guacamole.
No. X2Go is actually an implementation of NX, which is actually a compression method for X11, which is too complex. This is not necessary, though - as far as performance is concerned, there is an X.Org driver for Guacamole currently under development which achieves the same goal (see above).
<iframe> but keyboard doesn’t work correctly.It is generally not recommended to rely on <iframe> to integrate Guacamole
for precisely this reason. Browser keyboard focus is problematic if an
<iframe> is used, as once focus has been lost, clicking within the <iframe>
will not necessarily return keyboard focus to Guacamole.
Rather than use an <iframe>, you should instead look into leveraging
Guacamole’s JavaScript API,
guacamole-common-js, thus integrating
Guacamole into your page directly. You might even consider building your own
web application from Guacamole’s core Java API,
guacamole-common, if that would provide a
better experience.
If an <iframe> is really the only feasible solution, you can work around
keyboard focus issues by automatically refocusing the <iframe> whenever focus
is not explicitly on some other part of the page. For example, assuming the
variable iframe points to the DOM element of the <iframe> containing
Guacamole, you could refocus Guacamole by default with something like:
/**
* Refocuses the iframe containing Guacamole if the user is not already
* focusing another non-body element on the page.
*/
var refocusGuacamole = function refocusGuacamole() {
// Do not refocus if focus is on an input field
var focused = document.activeElement;
if (focused && focused !== document.body)
return;
// Ensure iframe is focused
iframe.focus();
};
// Attempt to refocus iframe upon click or keydown
document.addEventListener('click', refocusGuacamole);
document.addEventListener('keydown', refocusGuacamole);
There is no need to do this. While dynamically updating the XML or database contents may seem invitingly simple, it is rarely the best approach. Guacamole provides an API for integrating itself with other authentication systems and sources of data: guacamole-ext. Rather than attempt to keep an independent, Guacamole-specific source of data updated with respect to your application, it is better to pull or derive that data directly within an extension built specifically to integrate Guacamole with your application.
The manual provides a basic example for implementing your own Guacamole extension, and the various extensions included as part of guacamole-client are well-commented and can serve as more in-depth demonstrations of what is possible with this API.
If the ultimate goal is to tightly integrate Guacamole within your application, and Guacamole’s authentication model and interface don’t quite match what you intend, you should also consider building your own web application. Guacamole’s is built on a set of APIs which are maintained independently from the web application of the same name specifically so that other applications, like yours, can be built from the same underlying technology.
DO NOT DISABLE GUACAMOLE’S AUTHENTICATION! There are no use cases where this is a good idea. Even if you are absolutely positive that users cannot access Guacamole without first being authenticated elsewhere, validating each user’s authenticated state is the only safe choice. You don’t need to force users to log in multiple times, but you do need to verify that they are actually logged in.
If you have an application which already handles authentication, the correct and safe way to integrate Guacamole with that application is to write a Guacamole extension which validates each user. If the connections available to each user will vary depending on that existing system, your extension can dynamically derive those connections by querying your existing system, as well.