src/appendices/faq.xml

<?xml version="1.0" encoding="UTF-8"?>

<appendix xml:id="faq" 
    xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
    xmlns:xi="http://www.w3.org/2001/XInclude">

    <title>FAQ</title>

    <qandaset>

        <qandaentry>
            <question>

                <para>Where does the name "Guacamole" come from? </para>

            </question>
            <answer>

                <para>The name was chosen arbitrarily from a random utterance in a conversation with
                    a member of the project. </para>

                <para>When the project reached the point where it was growing out of the
                    proof-of-concept phase, and needed a real home on the internet, we needed to
                    think of a name to register the project under. </para>

                <para>Several acronyms were toyed with and discarded. We tried anagrams, but all
                    were too wordy and complex. We considered naming the project after a fish or an
                    animal, and after suggesting the guanaco, James Muehlner, a developer of the
                    project, suggested (randomly): "guacamole". </para>

                <para>The name had a nice ring, we weren't embarrassed to use it, and it stuck. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>What does "clientless" mean? </para>

            </question>
            <answer>

                <para>The term "clientless" means that no specific client is needed. A Guacamole
                    user needs only have an HTML5 web browser installed, which is exceedingly
                    common; virtually all modern computers and mobile devices have such a browser
                    installed by default. </para>

                <para>In this sense, Guacamole is "clientless" in that it does not require any
                    additional software to be installed beyond what is considered standard for any
                    computer. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>Does Guacamole use WebSocket? </para>

            </question>
            <answer>
                <para>Guacamole uses either WebSocket or plain HTTP, whichever is supported by both
                    the browser and your servlet container. If WebSocket cannot be used for any
                    reason, Guacamole will fall back to using HTTP.</para>

                <para>Historically, Guacamole had no WebSocket support at all. This was due to a
                    lack of browser support and lack of a true standard. Overall, it didn't matter
                    as there really wasn't any need: the tunnel used by Guacamole when WebSocket is
                    not available is largely equivalent to WebSocket in terms of efficiency and
                    latency, and is more compatible with proxies and existing browsers.</para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>I have Tomcat (or some other servlet container) set up behind a proxy (like
                    mod_proxy) and cannot connect to Guacamole. Why? How do I solve this? </para>

            </question>
            <answer>

                <para>You need to enable automatic flushing of the proxy's buffer as it receives
                    packets. </para>

                <para>Most proxies, including mod_proxy, buffer data received from the server, and
                    will not flush this data in real-time. Each proxy has an option to force
                    flushing of each packet automatically, as this is necessary for streaming
                    applications like Guacamole, but this is usually not enabled by default. </para>

                <para>Because Guacamole depends on streaming to function, a proxy configured to not
                    automatically flush packets will disrupt the stream to the point that the
                    connection seems unreasonably slow, or just fails to establish altogether. </para>

                <para>In the case of mod_proxy, this option is <code>flushpackets=on</code>. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>I connect to the internet through a web proxy, and cannot connect to
                    Guacamole. I cannot reconfigure the proxy. How do I solve this? </para>

            </question>
            <answer>

                <para>You need to enable automatic flushing of your proxy's buffer to avoid
                    disrupting the stream used by Guacamole. </para>

                <para>If you cannot change the settings of your proxy, using HTTPS instead of HTTP
                    should solve the problem. Proxies are required to stream HTTPS because of the
                    nature of SSL. Using HTTPS will allow Guacamole traffic to stream through
                    proxies unencumbered, even if you cannot access the proxy settings directly. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>Can I buy special licensing of the Guacamole code base, such that I can use it
                    in my own product, without providing the source to my users, without
                    contributing back, and without acknowledging the project? </para>

            </question>
            <answer>

                <para>Usually, no. Previous requests for such licensing have been very one-sided and
                    there would be no direct or indirect benefit to the community and the project.
                    That said, we handle requests for licensing on a case-by-case basis. In general,
                    any special licensing has to somehow provide for the community and the
                    open-source project.</para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>Can I pay for custom Guacamole work, or for help integrating Guacamole into my
                    product, if the open source nature and licenses are preserved?</para>

            </question>
            <answer>

                <para>Yes. We love to be paid to work on Guacamole, especially if that work remains
                    open source. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>How can I contribute to the project? </para>

            </question>
            <answer>

                <para>If you are a programmer and want to contribute code, Guacamole is open-source
                    and you are welcome to do so! Just send us your patches. There is no guarantee
                    that your patch will be added to the upstream source, and all changes are
                    carefully reviewed. </para>

                <para>If you are not a programmer, but want to help out, feel free to look through
                    the documentation or try installing Guacamole and test it out. General editing,
                    documentation contributions, and testing are always helpful. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>How can I become an official member of the project? </para>

            </question>
            <answer>

                <para>The short answer is: "by being asked." </para>

                <para>People are only added as official members of the Guacamole project after their
                    work has been proven. This usually means you will have contributed code in the
                    form of patches before, or we know you from extensive testing work, or you
                    frequently help with documentation, and we are impressed enough that we want you
                    as part of the project. </para>

                <para>All that said, you do not need to be a member of the project to help out. Feel
                    free to contribute anything. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>I think I've found a bug. How do I report it? </para>

            </question>
            <answer>

                <para>The project hosts a bug tracking tool called Trac at
                    http://guac-dev.org/trac/. All bugs should be reported there as new tickets.
                    This is also where you would request a new feature. </para>

                <para>If the bug you found is security-related, we would prefer to be contacted
                    personally via email, such that the bug can be fixed before becoming dangerously
                    widely known. </para>

            </answer>
        </qandaentry>

        <qandaentry>
            <question>

                <para>I need help! Where can I find some? </para>

            </question>
            <answer>

                <para>The project hosts forums at http://sourceforge.net/projects/guacamole/forums.
                    If you have a SourceForge username (or don't mind registering one), this is a
                    good place to start. </para>

                <para>Otherwise, there are Guacamole-specific official IRC channels on freenode.net:
                    #guacamole, #guacamole-dev, and #guacamole-help. </para>

                <para>If none of those options suffice, you can always email any of the project
                    members directly. You will usually get a personal response, time permitting. </para>

            </answer>
        </qandaentry>

    </qandaset>

</appendix>