<?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>&lt;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>&lt;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>&lt;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>&lt;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>