mike-jumper commented on a change in pull request #165:
URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642649275
##########
File path: src/troubleshooting.md
##########
@@ -0,0 +1,539 @@
+Troubleshooting
+===============
+
+(not-working)=
+
+It isn't working
+----------------
+
+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).
+
+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.
+
+### No graphics appear
+
+If you *never* 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.
+
+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.
+
+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.
+
+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.
+
+### Connections involving Unicode don't work
+
+If you are using Tomcat, beware that you *must* set the `URIEncoding="UTF-8"`
+attribute on all connectors in your `server.xml`. 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.
+
+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.
+
+syslog
+------
+
+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.
+
+Once you guacd is started, you'll see entries like the following in syslog:
+
+```
+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
+```
+
+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.
+
+### guacd errors
+
+#### Unable to bind socket to any addresses.
+
+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.
+
+If another service is listening on the default port, you can always specify a
+non-standard port for guacd by using the `-l PORT` option (that's a lowercase
+"L", not a number "1"), where <PORT> is the number of the port to listen on.
+Beware that you will likely have to modify `guacamole.properties` so that
+Guacamole knows how to connect to guacd.
+
+#### Unable to start input thread
+
+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.
+
+If it is the output thread that fails to start, the message will instead read:
+"Unable to start output thread".
+
+#### Client finished abnormally
+
+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.
+
+#### Could not fork() parent
+
+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.
+
+This message may also appear as "Could not fork() group leader".
+
+#### Unable to change working directory to /
+
+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.
+
+#### Unable to redirect standard file descriptors to /dev/null
+
+As guacd starts, it also has to redirect STDOUT, STDERR, and STDIN to
+`/dev/null` 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.
+
+If guacd cannot redirect these file descriptors for any reason, this error will
+be logged, along with the cause.
+
+#### Error parsing given address or port: HOSTNAME
+
+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.
+
+#### Error opening socket
+
+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.
+
+#### Unable to resolve host
+
+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.
+
+#### Could not become a daemon
+
+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.
+
+#### Could not write PID file
+
+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.
+
+#### Could not listen on socket
+
+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.
+
+#### Could not accept client connection
+
+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.
+
+#### Error forking child process
+
+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.
+
+#### Error closing daemon reference to child descriptor
+
+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.
+
+#### Error sending "sync" instruction
+
+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.
+
+#### Error flushing output
+
+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.
+
+#### Error handling server messages
+
+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.
+
+#### Error reading instruction
+
+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.
+
+#### Client instruction handler error
+
+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,
Review comment:
Definitely handlers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
