GUACAMOLE-540: Document RemoteIpValve configuration for Tomcat.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/23619cb6 Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/23619cb6 Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/23619cb6 Branch: refs/heads/master Commit: 23619cb6e8c4ecfe4a45d423af851262f05921ac Parents: fbd81b0 Author: Nick Couchman <[email protected]> Authored: Mon Jul 2 16:23:22 2018 -0400 Committer: Nick Couchman <[email protected]> Committed: Mon Jul 2 16:44:50 2018 -0400 ---------------------------------------------------------------------- src/chapters/reverse-proxy.xml | 98 +++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/23619cb6/src/chapters/reverse-proxy.xml ---------------------------------------------------------------------- diff --git a/src/chapters/reverse-proxy.xml b/src/chapters/reverse-proxy.xml index 4614350..6cd96e3 100644 --- a/src/chapters/reverse-proxy.xml +++ b/src/chapters/reverse-proxy.xml @@ -45,6 +45,99 @@ you will be creating connections that have Cyrillic, Chinese, Japanese, or other non-Latin characters in their names or parameter values, this attribute is required.</para> + <section xml:id="tomcat-remote-ip"> + <title>Setting up the Remote IP Valve</title> + <para>By default, when Tomcat is behind a reverse proxy, the remote IP address of the + client that it sees is that of the proxy rather than the original client. In order + to allow applications hosted within Tomcat, like Guacmaole, to see the actual IP + address of the client, you have to configure both the reverse proxy and Tomcat.</para> + <para>Because the remote IP address in Guacamole is used for auditing of user logins and + connections and could potentially be used for authentication, it is important that you + are either in direct control of the proxy server or you explicitly trust it. Passing + the remote IP address is done using the X-Forwarded-For header, and, as with most HTTP + headers, attackers can attempt to spoof this header in order to manipulate the behavior + of the web server, gain unauthorized access to the system, or attempt to disguise the + host or IP address they are coming from.</para> + <para>One final caveat: This may not work as expected if there are other upstream proxy + servers between your reverse proxy and the clients access Guacamole. Other proxies + or firewalls can mask the IP address of the client, and if the configuration of + those is not within your control you may end up with multiple clients appearing to + come from the same IP address or host. Make sure you take this into account when + configuring the system and looking at the data provided.</para> + <para>Configuring Tomcat to pass through the remote IP address provided by the reverse + proxy in the X-Forwarded-For header requires the configuration of what Tomcat calls + a Valve. In this case, it is the <parameter>RemoteIpValve</parameter> and is + configured in the <filename>conf/server.xml</filename> file, in the + <parameter><Host/></parameter>section:</para> + <informalexample> + <programlisting><Valve className="org.apache.catalina.valves.RemoteIpValve" + internalProxies="127.0.0.1" + remoteIpHeader="x-forwarded-for" + remoteIpProxiesHeader="x-forwarded-by" + protocolHeader="x-forwarded-proto" /></programlisting> + </informalexample> + <para>The <parameter>internalProxies</parameter> value should be set to the IP address + or addresses of any and all reverse proxy servers that will be accessing this Tomcat + instance directly. Often it is run on the same system that runs Tomcat, but in other + cases (for example, when running Docker), it may be on a different system/container and + may need to be set to the actual IP address of the reverse proxy system. Only proxy + servers listed in the <parameter>internalProxies</parameter> or + <parameter>trustedProxies</parameter> parameters will be allowed to manipulate the + remote IP address information. The other parameters in this configuration line allow + you to control which headers coming from the proxy server(s) are used for various + remote host information. They are as follows: + </para> + <informaltable frame="all"> + <tgroup cols="2"> + <colspec colname="c1" colnum="1" colwidth="1*"/> + <colspec colname="c2" colnum="2" colwidth="3.55*"/> + <thead> + <row> + <entry>Parameter name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><parameter>remoteIpHeader</parameter></entry> + <entry> + <para>The header that is queried to learn the client IP address + of the client that originated the request. The standard + value is <replaceable>X-Forwarded-For</replaceable>, but can + be configured to any header you like. The IP address in this + header will be available to Java applications in the + HttpServletRequest getRemoteAddr() method.</para> + </entry> + </row> + <row> + <entry><parameter>remoteIpProxiesHeader</parameter></entry> + <entry> + <para>The header that is queried to learn the IP address of the + proxy server that forwarded the request. The default value + is <replaceable>X-Forwarded-By</replaceable>, but can be + configured to any header that fits your environment. This + value will only be allowed by the valve if the proxy used + is listed in the <parameter>trustedProxies</parameter> + parameter. Otherwise this value will be null.</para> + </entry> + </row> + <row> + <entry><parameter>protocolHeader</parameter></entry> + <entry> + <para>The header that is queried to determine the protocol + that the client used to connect to the service. The default + value is <replaceable>X-Forwarded-Proto</replaceable>, but + can be configured to fit your environment.</para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>In addition to configuring Tomcat to properly handle these headers, you also may + need to configure your reverse proxy appropriately to send the headers. You can + find instructions for this in the <xref linkend="nginx"/> - the Apache web server + passes it through by default.</para> + </section> </section> <section xml:id="nginx"> <title>Nginx</title> @@ -83,6 +176,11 @@ machine hosting your servlet container, and <replaceable>8080</replaceable> is the port that servlet container is configured to use. You will need to replace these values with the correct values for your server.</para> + <para>Related to the RemoteIpValve configuration for tomcat, documented in + <xref linked="tomcat-remote-ip"/>, the + <code>proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;</code> line is + important if you want the <code>X-Forwarded-For</code> header to be passed through + to the web application server and available to applications running inside it.</para> <important> <para><emphasis>Do not forget to specify "<code>proxy_buffering off</code>".</emphasis></para>
