| <?xml version="1.0" encoding="UTF-8"?> |
| <chapter xml:id="troubleshooting" xmlns="http://docbook.org/ns/docbook" |
| version="5.0" xml:lang="en" xmlns:xl="http://www.w3.org/1999/xlink" |
| xmlns:xi="http://www.w3.org/2001/XInclude"> |
| <title>Troubleshooting</title> |
| <indexterm> |
| <primary>troubleshooting</primary> |
| </indexterm> |
| <indexterm> |
| <primary>errors</primary> |
| </indexterm> |
| <section xml:id="not-working"> |
| <title>It isn't working</title> |
| <para>If Guacamole isn't working, chances are something isn't configured |
| properly, or something is wrong with the network. Thankfully, |
| Guacamole and all its components log errors thoroughly, so the |
| problem can usually be traced down fairly easily if you know where |
| to look. Troubleshooting Guacamole usually boils down to checking |
| either syslog or your servlet container's logs (likely |
| Tomcat).</para> |
| <para>Failing all that, you can always post a question in the forums, or |
| if you truly feel you've discovered a bug, you can create a new |
| ticket in Trac. Beware that if something isn't working, and there |
| are errors in the logs describing the problem, it is usually not a |
| bug, and the best place to handle such things is through consulting |
| this guide or the forums.</para> |
| <section> |
| <title>No graphics appear</title> |
| <indexterm> |
| <primary>Connecting, waiting for first update...</primary> |
| </indexterm> |
| <indexterm> |
| <primary>proxies</primary> |
| </indexterm> |
| <para>If you <emphasis>never</emphasis> see any graphics appear, or you see "Connecting, |
| waiting for first update..." for a while and then are disconnected, the most likely |
| cause is a proxy.</para> |
| <para>Guacamole relies on streaming data to you over a persistent connection. If |
| software between Guacamole and your browser is buffering all incoming data, such as |
| a proxy, this data never makes it to your browser, and you will just see it wait |
| indefinitely. Eventually, thinking the client has disconnected, Guacamole closes the |
| connection, at which point the proxy finally flushes its buffer and you see |
| graphics! ... just in time to see it disconnect.</para> |
| <para>The solution here is to either modify your proxy settings to flush packets |
| immediately as they are received, or to use HTTPS. Proxies are required to pass |
| HTTPS through untouched, and this usually solves the problem.</para> |
| <para>Even if you aren't aware of any proxy, there may be one in place. Corporate |
| firewalls very often incorporate proxies. Antivirus software may buffer incoming |
| data until the connection is closed and the data is scanned for viruses. |
| Virtualization software may detect HTTP data and buffer the connection just like a |
| proxy. If all else fails, try HTTPS - it's the only secure way to do this |
| anyway.</para> |
| </section> |
| <section> |
| <title>Connections involving Unicode don't work</title> |
| <indexterm> |
| <primary>Unicode</primary> |
| </indexterm> |
| <indexterm> |
| <primary>UTF-8</primary> |
| </indexterm> |
| <indexterm> |
| <primary><code>URIEncoding</code></primary> |
| </indexterm> |
| <para>If you are using Tomcat, beware that you <emphasis>must</emphasis> set the |
| <code>URIEncoding="UTF-8"</code> attribute on all connectors in your |
| <filename>server.xml</filename>. If you are using a different servlet container, |
| you need to find out whether it requires special options to support UTF-8 in URIs, |
| and change the required settings to enable such support.</para> |
| <para>Without UTF-8 support enabled for URIs, Unicode characters in connection names |
| will not be received properly when connecting, and Guacamole will thing the |
| connection you requested does not exist. Similarly, if you are using the built-in |
| administration interface, parameters involving Unicode characters will not save |
| properly without these options enabled.</para> |
| </section> |
| </section> |
| <section xml:id="syslog"> |
| <title>syslog</title> |
| <indexterm> |
| <primary>syslog</primary> |
| </indexterm> |
| <para>guacd and libguac-based programs (such as all client plugins) log |
| informational messages and errors to syslog. Specifically, guacd |
| uses syslog, and it exposes this logging facility to everything it |
| loads (client plugins), thus if the VNC or RDP support plugins |
| encounter errors, they log those errors over the logging facilities |
| exposed by guacd, in this case syslog.</para> |
| <para>Once you guacd is started, you'll see entries like the following |
| in syslog:</para> |
| <informalexample> |
| <screen>guacd[19663]: Guacamole proxy daemon (guacd) version 0.7.0 |
| guacd[19663]: Unable to bind socket to host ::1, port 4823: Address family |
| not supported by protocol |
| guacd[19663]: Successfully bound socket to host 127.0.0.1, port 4823 |
| guacd[19663]: Exiting and passing control to PID 19665 |
| guacd[19665]: Exiting and passing control to PID 19666 |
| guacd[19666]: Listening on host 127.0.0.1, port 4823</screen> |
| </informalexample> |
| <para>Each entry relevant to Guacamole has the prefix "guacd", denoting |
| the program that produced the entry, followed by the process ID, |
| followed by the message. The entries above show guacamole starting |
| successfully and listening on a non-default port 4823.</para> |
| <section xml:id="guacd-errors"> |
| <title>guacd errors</title> |
| <indexterm> |
| <primary>errors</primary> |
| <secondary>guacd</secondary> |
| </indexterm> |
| <indexterm> |
| <primary>guacd</primary> |
| <secondary>errors</secondary> |
| </indexterm> |
| <section> |
| <title>Unable to bind socket to any addresses.</title> |
| <para>This means that guacd failed to start up at all because |
| the port it wants to listen on is already taken at all |
| addresses attempted. The details of what guacd tried will be |
| listed in the log entries above this. To solve the problem, |
| find what port guacd was trying to listen on (the default is |
| 4822) and check if any other service is listening on that |
| port.</para> |
| <para>If another service is listening on the default port, you |
| can always specify a non-standard port for guacd by using |
| the <option>-l<replaceable> PORT</replaceable></option> |
| option (that's a lowercase "L", not a number "1"), where |
| <replaceable>PORT</replaceable> is the number of the |
| port to listen on. Beware that you will likely have to |
| modify <filename>guacamole.properties</filename> so that |
| Guacamole knows how to connect to guacd.</para> |
| </section> |
| <section> |
| <title>Unable to start <replaceable>input</replaceable> |
| thread</title> |
| <para>guacd creates two threads for each connection: one that |
| receives input from the connected client, and the other that |
| produces output for the client. If either of these fails to |
| start, the above error will be logged along with the |
| cause.</para> |
| <para>If it is the output thread that fails to start, the |
| message will instead read: "Unable to start output |
| thread".</para> |
| </section> |
| <section> |
| <title>Client finished abnormally</title> |
| <para>If the client plugin ever returns an error code, this will |
| cause the connection to immediately terminate, with the |
| cause of the error specific to the plugin in use. The cause |
| should be detailed in the log messages above the error. If |
| those log messages don't make sense, you may have found a |
| bug.</para> |
| </section> |
| <section> |
| <title>Could not fork() |
| <replaceable>parent</replaceable></title> |
| <para>When guacd starts up, it immediately attempts to "fork" |
| into the background (unless instructed otherwise). The word |
| "fork()" above is a reference to the C function call that |
| does this. There are several calls to this function, each of |
| which might fail if system resources are lacking or |
| something went wrong at a low level. If you see this |
| message, it is probably not a bug in Guacamole, but rather a |
| problem with the load level of your system.</para> |
| <para>This message may also appear as "Could not fork() group |
| leader".</para> |
| </section> |
| <section> |
| <title>Unable to change working directory to /</title> |
| <para>One of the duties of guacd as it starts up is to change |
| its working directory to the root directory. This is to |
| prevent locking the current directory in case it needs to be |
| unmounted, etc. If guacd cannot do this, this error will be |
| logged, along with the cause.</para> |
| </section> |
| <section> |
| <title>Unable to redirect standard file descriptors to |
| /dev/null</title> |
| <para>As guacd starts, it also has to redirect STDOUT, STDERR, |
| and STDIN to <filename>/dev/null</filename> such that |
| attempts to use these output mechanisms do not pollute the |
| active console. Though guacd and client plugins will use the |
| exposed logging facilities (and thus syslog) rather than |
| STDOUT or STDERR, libraries used by client plugins are often |
| written only from the mindset of a typical client, and use |
| standard output mechanisms for debug logging. Not |
| redirecting these would result in undesired output to the |
| console.</para> |
| <para>If guacd cannot redirect these file descriptors for any |
| reason, this error will be logged, along with the |
| cause.</para> |
| </section> |
| <section> |
| <title>Error parsing given address or port: |
| <replaceable>HOSTNAME</replaceable></title> |
| <para>If you specified a host or port to listen on via |
| commandline options, and that host or port is actually |
| invalid, you will see this error. Fix the corresponding |
| option and try again.</para> |
| </section> |
| <section> |
| <title>Error opening socket</title> |
| <para>When guacd starts up, it needs to open a socket and then |
| listen on that socket. If it can't even open the socket, |
| this error will be logged, and guacd will exit. The cause is |
| most likely related to permissions, and is logged along with |
| the error.</para> |
| </section> |
| <section> |
| <title>Unable to resolve host</title> |
| <para>If the hostname you specified on the commandline cannot be |
| found, you will see this error. Note that this error is from |
| guacd, and does not relate to whatever remote desktop |
| servers you may be trying to use; it relates only to the |
| host guacd is trying to listen on. Check the hostname or IP |
| address specified on the commandline. If that checks out, |
| there may be a problem with your DNS or your network.</para> |
| </section> |
| <section> |
| <title>Could not become a daemon</title> |
| <para>In order to become a "daemon" (that is, in order to run in |
| the background as a system process), guacd must create and |
| exit from several processes, redirect file descriptors, etc. |
| If any of these steps fails, guacd will not become a daemon, |
| and it will log this message and exit. The reason guacd |
| could not become a daemon will be in the previous error |
| message in the logs.</para> |
| </section> |
| <section> |
| <title>Could not write PID file</title> |
| <para>guacd offers a commandline option that lets you specify a |
| file that it should write its process ID into, which is |
| useful for init scripts. If you see this error, it likely |
| means the user guacd is running as does not have permission |
| to write this file. The true cause of the error will be |
| logged in the same entry. Check which user guacd is running |
| as, and then check that it has write permission to the file |
| in question.</para> |
| </section> |
| <section> |
| <title>Could not listen on socket</title> |
| <para>When guacd starts up, it needs to listen on the socket it |
| just opened in order to accept connections. If it cannot |
| listen on the socket, clients will be unable to connect. If, |
| for any reason, guacd is unable to listen on the socket, |
| guacd will exit and log this message along with the cause, |
| which is most likely a low-level system resource |
| problem.</para> |
| </section> |
| <section> |
| <title>Could not accept client connection</title> |
| <para>When a client connects to guacd, it must accept the |
| connection in order for communication to ensue. If it cannot |
| even accept the connection, no communication between server |
| and client will happen, and this error will be logged. The |
| cause of the error will be logged in the same entry. |
| Possible causes include permissions problems, or lack of |
| server resources.</para> |
| </section> |
| <section> |
| <title>Error forking child process</title> |
| <para>When a client connects to guacd, it must create a new |
| process to handle the connection while the old guacd process |
| continues to listen for new connections. If, for any reason, |
| guacd cannot create this process, the connection from that |
| client will be denied, and the cause of the error will be |
| logged. Possible causes include permissions problems, or |
| lack of server resources.</para> |
| </section> |
| <section> |
| <title>Error closing daemon reference to child |
| descriptor</title> |
| <para>When guacd receives a connection, and it creates a new |
| process to handle that connection, it gains a copy of the |
| file descriptor that the client will use for communication. |
| As this connection can never be closed unless all references |
| to the descriptor are closed, the server must close its copy |
| such that the client is the only remaining holder of the |
| file descriptor. If the server cannot close the descriptor, |
| it will log this error message along with the cause.</para> |
| </section> |
| <section> |
| <title>Error sending "sync" instruction</title> |
| <para>During the course of a Guacamole session, guacd must |
| occasionally "ping" the client to make sure it is still |
| alive. This ping takes the form of a "sync" instruction, |
| which the client is obligated to respond to as soon as it is |
| received. If guacd cannot send this instruction, this error |
| will be logged, along with the cause. Chances are the |
| connection has simply been closed, and this error can be |
| ignored.</para> |
| </section> |
| <section> |
| <title>Error flushing output</title> |
| <para>After the client plugin is finished (for the time being) |
| with handling server messages, the socket is automatically |
| flushed. If the server cannot flush this socket for some |
| reason, such as the connection already being closed, you |
| will see this error. Normally, this error does not indicate |
| a problem, but rather that the client has simply closed the |
| connection.</para> |
| </section> |
| <section> |
| <title>Error handling server messages</title> |
| <para>While the client plugin is running, guacd will |
| occasionally ask the plugin to check and handle any messages |
| that it may have received from the server it connected to. |
| If the client plugin fails for some reason while doing this, |
| this error will be logged, and the cause of the error will |
| likely be logged in previous log entries by the client |
| plugin.</para> |
| </section> |
| <section> |
| <title>Error reading instruction</title> |
| <para>During the course of a Guacamole session, instructions are |
| sent from client to server which are to be handled by the |
| client plugin. If an instruction cannot be read, this error |
| will be logged. Usually this means simply that the |
| connection was closed, but it could also indicate that the |
| version of the client in use is so old that it doesn't |
| support the current Guacamole protocol at all. If the cause |
| looks like the connection was closed (end of stream reached, |
| etc.), this log entry can be ignored. Otherwise, if the |
| first two numbers of the version numbers of all Guacamole |
| components match, you have probably found a bug.</para> |
| </section> |
| <section> |
| <title>Client instruction handler error</title> |
| <para>This error indicates that a client plugin failed inside |
| the handler for a specific instruction. When the server |
| receives instructions from the client, it then invokes |
| specific instruction handles within the client plugin. In |
| general, this error is not useful to a user or system |
| administrator. If the cause looks benign, such as reaching |
| the end of a stream (the connection closed), it can be |
| ignored as normal. Otherwise, this error can indicate a bug |
| either in the client plugin or in a library used by the |
| client plugin.</para> |
| <para>It can also indicate a problem in the remote desktop |
| server which is causing the client plugin to fail while |
| communicating with it.</para> |
| </section> |
| <section> |
| <title>Error reading "<replaceable>OPCODE</replaceable>"</title> |
| <para>During the handshake of the Guacamole protocol, the server |
| expects a very specific sequence of instructions to be |
| received. If the wrong instructions are received, or the |
| connection is abruptly closed during the handshake, the |
| above error will occur.</para> |
| <para>In the case that the cause is the connection closing, this |
| is normal, and probably just means that the client |
| disconnected before the initial handshake completed.</para> |
| <para>If the connection was not closed abruptly, but instead the |
| wrong instruction was received, this could mean either that |
| the connecting client is from an incompatible version of |
| Guacamole (and thus does not know the proper handshake |
| procedure) or you have found a bug. Check whether all |
| installed components came from the same upstream release |
| bundle.</para> |
| </section> |
| <section> |
| <title>Error sending "args"</title> |
| <para>During the handshake of the Guacamole protocol, the server |
| must expose all parameters used by the client plugin via the |
| args instruction. If this cannot be sent, you will see this |
| error in the logs. The cause will be included in the error |
| message, and usually just indicates that the connection was |
| closed during the handshake, and thus the handshake cannot |
| continue.</para> |
| </section> |
| <section> |
| <title>Error loading client plugin</title> |
| <para>When the client connects, it sends an instruction to guacd |
| informing it what protocol it wishes to use. If the |
| corresponding client plugin cannot be found or used for any |
| reason, this message will appear in the logs. Normally this |
| indicates that the corresponding client plugin is not |
| actually installed. The cause listed after the error message |
| will indicate whether this is the case.</para> |
| </section> |
| <section> |
| <title>Error instantiating client</title> |
| <para>After the client plugin is loaded, an initialization |
| function provided by the client plugin is invoked. If this |
| function fails, then the client itself cannot be created, |
| and this error will be logged. Usually this indicates that |
| one or more of the parameters given to the client plugin are |
| incorrect or malformed. Check the configuration of the |
| connection in use at the time.</para> |
| </section> |
| </section> |
| <section xml:id="libguac-client-vnc-errors"> |
| <title>libguac-client-vnc errors</title> |
| <section> |
| <title>Error waiting for VNC message</title> |
| <para>The VNC client plugin must wait for messages sent by the |
| VNC server, and handle them when they arrive. If there was |
| an error while waiting for a message from the VNC server, |
| this error message will be displayed. Usually this means |
| that the VNC server closed the connection, or there is a |
| problem with the VNC server itself, but the true cause of |
| the error will be logged.</para> |
| </section> |
| <section> |
| <title>Error handling VNC server message</title> |
| <para>When messages are received from the VNC server, |
| libvncclient must handle them and then invoke the functions |
| of libguac-client-vnc as necessary. If libvncclient fails |
| during the handling of a received message, this error will |
| be logged, along with (hopefully) the cause. This may |
| indicate a problem with the VNC server, or a lack of support |
| within libvncclient.</para> |
| </section> |
| <section> |
| <title>Wrong argument count received</title> |
| <para>The connecting client is required to send exactly the same |
| number of arguments as requested by the client plugin. If |
| you see this message, it means there is a bug in the client |
| connecting to guacd, most likely the web application.</para> |
| </section> |
| </section> |
| <section xml:id="libguac-client-rdp-errors"> |
| <title>libguac-client-rdp errors</title> |
| <section> |
| <title>Invalid <replaceable>parameter</replaceable></title> |
| <para>If one of the parameters given, such as "width", "height", |
| or "color-depth", is invalid (not an integer, for example), |
| you will receive this error. Check the parameters of the |
| connection in use and try again.</para> |
| </section> |
| <section> |
| <title>Support for the CLIPRDR channel (clipboard redirection) could not be |
| loaded</title> |
| <para>FreeRDP provides a plugin which provides clipboard support for RDP. This |
| plugin is typically built into FreeRDP, but some distributions may bundle this |
| separately. libguac-client-rdp loads this plugin in order to support clipboard, |
| as well. If this plugin could not be loaded, then clipboard support will not be |
| available, and the reason will be logged.</para> |
| </section> |
| <section> |
| <title>Cannot create static channel "<replaceable>name</replaceable>": failed to |
| load "guac-common-svc" plugin for FreeRDP</title> |
| <para>RDP provides support for much of its feature set through static virtual |
| channels. Sound support, for example is provided through the "RDPSND" channel. |
| Device redirection for printers and drives is provided through "RDPDR". To |
| support these and other static virtual channels, libguac-client-rdp builds a |
| plugin for FreeRDP called "guac-common-svc" which allows Guacamole to hook into |
| the parts of FreeRDP that support virtual channels.</para> |
| <para>If libguac-client-rdp cannot load this plugin, support for any features which |
| leverage static virtual channels will not work, and the reason will be logged. A |
| likely explanation is that libguac-client-rdp was built from source, and the |
| directory specified for FreeRDP's installation location was incorrect. For |
| FreeRDP to be able to find plugins, those plugins must be placed in the |
| <filename>freerdp2/</filename> subdirectory of whichever directory contains |
| the <filename>libfreerdp2.so</filename> library.</para> |
| </section> |
| <section> |
| <title>Server requested unsupported clipboard data type</title> |
| <para>When clipboard support is loaded, libguac-client-rdp |
| informs the RDP server of all supported clipboard data |
| types. The RDP server is required to send only those types |
| supported by the client. If the server decides to send an |
| unsupported type anyway, libguac-client-rdp ignores the data |
| sent, and logs this message.</para> |
| </section> |
| <section> |
| <title>Clipboard data missing null terminator</title> |
| <para>When text is sent via a clipboard message, it is required |
| to have a terminating null byte. If this is not the case, |
| the clipboard data is invalid, and libguac-client-rdp |
| ignores it, logging this error message.</para> |
| </section> |
| </section> |
| </section> |
| <section xml:id="servlet-container-logs"> |
| <title>Servlet container logs</title> |
| <para>Your servlet container will have logs which the web application |
| side of Guacamole will log errors to. In the case of Tomcat, this is |
| usually <filename>catalina.out</filename> or |
| <filename><replaceable>HOSTNAME</replaceable>.log</filename> |
| (for example, <filename>localhost.log</filename>).</para> |
| <section xml:id="user-mapping-xml-errors"> |
| <title><filename>user-mapping.xml</filename> errors</title> |
| <para>Errors in the relating to the |
| <filename>user-mapping.xml</filename> file usually indicate |
| that either the XML is malformed, or the file itself cannot be |
| found.</para> |
| <section> |
| <title>Attribute "name" required for connection tag</title> |
| <para>If you specify a connection with a |
| <code><connection></code> tag, it must have a |
| corresponding name set via the <code>name</code> attribute. |
| If it does not, then the XML is malformed, and this error |
| will be logged. No users will be able to login.</para> |
| </section> |
| <section> |
| <title>Attribute "name" required for param tag</title> |
| <para>Each parameter specified with a <code><param></code> |
| tag must have a corresponding name set via the |
| <code>name</code> attribute. If it does not, then the |
| XML is malformed, and this error will be logged. No users |
| will be able to login.</para> |
| </section> |
| <section> |
| <title>Unexpected character data</title> |
| <para>Character data (text not within angle brackets) can only |
| exist within the <code><param></code> tag. If it exists |
| elsewhere, then the XML is malformed, and this error will be |
| logged. No users will be able to login.</para> |
| </section> |
| <section> |
| <title>Invalid encoding type</title> |
| <para>There are only two legal values for the |
| <code>encoding</code> attribute of the |
| <code><authorize></code> tag: <code>plain</code> |
| (indicating plain text) and <code>md5</code> (indicating a |
| value hashed with the MD5 digest). If any other value is |
| used, then the XML is malformed, and this error will be |
| logged. No users will be able to login.</para> |
| </section> |
| <section> |
| <title>User mapping could not be read</title> |
| <para>If for any reason the user mapping file cannot be read |
| (the servlet container lacks read permission for the file, |
| the file does not exist, etc.), this error will be logged. |
| Check <filename>guacamole.properties</filename> to see where |
| the user mapping file is specified to exist, and then check |
| that is both exists and is readable by your servlet |
| container.</para> |
| </section> |
| </section> |
| <section xml:id="guacamole-properties-errors"> |
| <title><filename>guacamole.properties</filename> errors</title> |
| <para>If a property is malformed or a required property is missing, |
| an error describing the problem will be logged.</para> |
| <section> |
| <title>Property <replaceable>PROPERTY</replaceable> is |
| required</title> |
| <para>If Guacamole or an extension of Guacamole requires a |
| specific property in |
| <filename>guacamole.properties</filename>, but this |
| property is not defined, this error will be logged. Check |
| which properties are required by the authentication provider |
| (or other extensions) in use, and then compare that against |
| the properties within |
| <filename>guacamole.properties</filename>.</para> |
| </section> |
| <section> |
| <title>Specified authentication provider class is not a |
| AuthenticationProvider</title> |
| <para>The <code>auth-provider</code> property allows you to |
| specify a custom authentication provider class which will |
| handle all authentication, but these classes must implement |
| the <classname>AuthenticationProvider</classname> interface. |
| If the class specified does not, this error will be logged. |
| Check that your authentication provider class implements |
| <classname>AuthenticationProvider</classname> (if you |
| implemented it yourself), and verify that you are specifying |
| the correct class.</para> |
| <para>If you are certain that the class specified is correct, |
| you may have placed the .jar file for your authentication |
| provider in the wrong directory. Make sure the .jar file is |
| in the directory specified by the <code>lib-directory</code> |
| parameter in guacamole.properties.</para> |
| </section> |
| <section> |
| <title>Resource /guacamole.properties not found</title> |
| <para>Guacamole requires that the |
| <filename>guacamole.properties</filename> file is in the |
| classpath of your servlet container. If it is not, this |
| error will be logged. Check that |
| <filename>guacamole.properties</filename> is in the |
| proper location, and then restart your servlet |
| container.</para> |
| </section> |
| <section> |
| <title>Missing "basic-user-mapping" parameter required for basic |
| login</title> |
| <para>If you are using the authentication provider included with |
| Guacamole, it requires the <code>basic-user-mapping</code> |
| property to be set. If this property is missing, you will |
| see this error. Add the missing property to |
| <filename>guacamole.properties</filename>, restart your |
| servlet container, and try again.</para> |
| </section> |
| </section> |
| <section xml:id="guacamole-auth-errors"> |
| <title>Authentication errors</title> |
| <para>If someone attempts to login with invalid credentials, or |
| someone attempts to access a resource or connection that does |
| not exist or they do not have access to, errors regarding the |
| invalid attempt will be logged.</para> |
| <section> |
| <title>Cannot connect - user not logged in</title> |
| <para>A user attempted to connect using the HTTP tunnel, and |
| while the tunnel does exist and is attached to their |
| session, they are not actually logged in. Normally, this |
| isn't strictly possible, as a user has to have logged in for |
| a tunnel to be attached to their session, but as it isn't an |
| impossibility, this error does exist. If you see this error, |
| it could mean that the user logged out at the same time that |
| they made a connection attempt.</para> |
| </section> |
| <section> |
| <title>Requested configuration is not authorized</title> |
| <para>A user attempted to connect to a configuration with a |
| given ID, and while that configuration does exist, they are |
| not authorized to use it. This could mean that the user is |
| trying to access things they have no privileges for, or that |
| they are trying to access configurations they legitimately |
| should, but are actually logged out.</para> |
| </section> |
| <section> |
| <title>User has no session</title> |
| <para>A user attempted to access a page that needs data from |
| their session, but their session does not actually exist. |
| This usually means the user has not logged in, as sessions |
| are created through the login process.</para> |
| </section> |
| </section> |
| <section xml:id="guacamole-tunnel-errors"> |
| <title>Tunnel errors</title> |
| <para>The tunnel frequently returns errors if guacd is killed, the |
| connection is closed, or the client abruptly closes the |
| connection.</para> |
| <section> |
| <title>No such tunnel</title> |
| <para>An attempt was made to use a tunnel which does not |
| actually exist. This is usually just the JavaScript client |
| sending a leftover message or two while it hasn't realized |
| that the server has disconnected. If this error happens |
| consistently and is associated with Guacamole generally not |
| working, it could be a bug.</para> |
| </section> |
| <section> |
| <title>No tunnel created</title> |
| <para>A connection attempt for a specific configuration was |
| made, but the connection failed, and no tunnel was created. |
| This is usually because the user was not authorized to use |
| that connection, and thus no tunnel was created for access |
| to that connection.</para> |
| </section> |
| <section> |
| <title>No query string provided</title> |
| <para>When the JavaScript client is communicating with the HTTP |
| tunnel, it <emphasis>must</emphasis> provide data in the |
| query string describing whether it wants to connect, read, |
| or write. If this data is missing as the error indicates, |
| there is a bug in the HTTP tunnel.</para> |
| </section> |
| <section> |
| <title>Tunnel reached end of stream</title> |
| <para>An attempt to read from the tunnel was made, but the |
| tunnel in question has already reached the end of stream |
| (the connection is closed). This is mostly an informative |
| error, and can be ignored.</para> |
| </section> |
| <section> |
| <title>Tunnel is closed</title> |
| <para>An attempt to read from the tunnel was made, but the |
| tunnel in question is already closed. This can happen if the |
| client or guacd have closed the connection, but the client |
| has not yet settled down and is still making read attempts. |
| As there can be lags between when connections close and when |
| the client realizes it, this can be safely ignored.</para> |
| </section> |
| <section> |
| <title>End of stream during initial handshake</title> |
| <para>If guacd closes the connection suddenly without allowing |
| the client to complete the initial handshake required by the |
| Guacamole protocol, this error will appear in the logs. If |
| you see this error, you should check syslog for any errors |
| logged by guacd to determine why it closed the connection so |
| early.</para> |
| </section> |
| <section> |
| <title>Element terminator of instruction was not ';' nor |
| ','</title> |
| <para>The Guacamole protocol imposes a strict format which |
| requires individual parts of instructions (called |
| "elements") to end with either a ";" or "," character. If |
| they do not, then something has gone wrong during |
| transmission. This usually indicates a bug in the client |
| plugin in use, guacd, or libguac.</para> |
| </section> |
| <section> |
| <title>Non-numeric character in element length</title> |
| <para>The Guacamole protocol imposes a strict format which |
| requires each element of an instruction to have a length |
| prefix, which must be composed entirely of numeric |
| characters (digits 0 through 9). If a non-numeric character |
| is read, then something has gone wrong during transmission. |
| This usually indicates a bug in the client plugin in use, |
| guacd, or libguac.</para> |
| </section> |
| </section> |
| </section> |
| </chapter> |