Github user necouchman commented on a diff in the pull request:
https://github.com/apache/guacamole-manual/pull/91#discussion_r203451479
--- Diff: 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
<code>X-Forwarded-For</code> 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 <code>X-Forwarded-For</code> header requires
the configuration of what
+ Tomcat calls a Valve. In this case, it is the
<code>RemoteIpValve</code> and is
+ configured in the <filename>conf/server.xml</filename>
file, in the
+ <code><Host/></code>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 <code>X-Forwarded-For</code>,
but can
+ be configured to any header you like.
The IP address in this
+ header will be available to Java
applications in the
+ <code>request.getRemoteAddr()</code>
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 <code>X-Forwarded-By</code>, 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>
--- End diff --
Reworded.
---
