mike-jumper commented on a change in pull request #165: URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642144617
########## File path: src/reverse-proxy.md ########## @@ -0,0 +1,427 @@ +Proxying Guacamole +================== + +Like most web applications, Guacamole can be placed behind a reverse proxy. For +production deployments of Guacamole, this is *highly recommended*. It provides +flexibility and, if your proxy is properly configured for SSL, encryption. + +Proxying isolates privileged operations within native applications that can +safely drop those privileges when no longer needed, using Java only for +unprivileged tasks. On Linux and UNIX systems, a process must be running with +root privileges to listen on any port under 1024, including the standard HTTP +and HTTPS ports (80 and 443 respectively). If the servlet container instead +listens on a higher port, such as the default port 8080, it can run as a +reduced-privilege user, allowing the reverse proxy to bear the burden of root +privileges. As a native application, the reverse proxy can make system calls to +safely drop root privileges once the port is open; a Java application like +Tomcat cannot do this. + +(preparing-servlet-container)= + +Preparing your servlet container +-------------------------------- + +Your servlet container is most likely already configured to listen for HTTP +connections on port 8080 as this is the default. If this is the case, and you +can already access Guacamole over port 8080 from a web browser, you need not +make any further changes to its configuration. + +If you *have* changed this, perhaps with the intent of proxying Guacamole over +AJP, *change it back*. Using Guacamole over AJP is unsupported as it is known +to cause problems, namely: + +1. WebSocket will not work over AJP, forcing Guacamole to fallback to HTTP, + possibly resulting in reduced performance. + +2. Apache 2.4.3 and older does not support the HTTP PATCH method over AJP, + preventing the Guacamole management interface from functioning properly. + +The connector entry within `conf/server.xml` should look like this: + +```xml +<Connector port="8080" protocol="HTTP/1.1" + connectionTimeout="20000" + URIEncoding="UTF-8" + redirectPort="8443" /> +``` + +Be sure to specify the `URIEncoding="UTF-8"` attribute as above to ensure that +connection names, user names, etc. are properly received by the web +application. If 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. + +(tomcat-remote-ip)= + +### Setting up the Remote IP Valve + +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 Guacamole, to see the +actual IP address of the client, you have to configure both the reverse proxy +and Tomcat. + +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. + +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. + +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 +[`RemoteIpValve`](https://tomcat.apache.org/tomcat-8.5-doc/config/valve.html#Remote_IP_Valve) +and is configured in the `conf/server.xml` file, in the `<Host>` section: + +```xml +<Valve className="org.apache.catalina.valves.RemoteIpValve" + internalProxies="127.0.0.1" + remoteIpHeader="x-forwarded-for" + remoteIpProxiesHeader="x-forwarded-by" + protocolHeader="x-forwarded-proto" /> +``` + +The `internalProxies` 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 `internalProxies` or +`trustedProxies` 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: + +`remoteIpHeader` +: The header that is queried to learn the client IP address of the client + that originated the request. The standard value is `X-Forwarded-For`, but + can be configured to any header you like. The IP address in this header + will be available to Java applications in the `request.getRemoteAddr()` + method. + +`remoteIpProxiesHeader` +: The header that is queried to learn the IP address of the proxy server + that forwarded the request. The default value is `X-Forwarded-By`, 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 + `trustedProxies` parameter. Otherwise this header will not be available. + +`protocolHeader` +: The header that is queried to determine the protocol that the client used + to connect to the service. The default value is `X-Forwarded-Proto`, but + can be configured to fit your environment. + +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 [](nginx) - the Apache web server passes it +through by default. + +(nginx)= + +Nginx +----- + +Nginx can be used as a reverse proxy, and supports WebSocket out-of-the-box +[since version 1.3](http://nginx.com/blog/websocket-nginx/). Both Apache and +Nginx require some additional configuration for proxying of WebSocket to work +properly. + +(proxying-with-nginx)= + +### Proxying Guacamole + +Nginx does support WebSocket for proxying, but requires that the "Connection" +and "Upgrade" HTTP headers are set explicitly due to the nature of the +WebSocket protocol. From the Nginx documentation: + +> NGINX supports WebSocket by allowing a tunnel to be set up between a client +> and a back-end server. For NGINX to send the Upgrade request from the client +> to the back-end server, Upgrade and Connection headers must be set +> explicitly. ... + +The proxy configuration belongs within a dedicated +[`location`](http://nginx.org/en/docs/http/ngx_http_core_module.html#location>) +block, declaring the backend hosting Guacamole and explicitly specifying the +"`Connection`" and "`Upgrade`" headers mentioned earlier: + +```nginx +location /guacamole/ { + proxy_pass http://HOSTNAME:8080; Review comment: It's an intentional simplification (see other comment on `proxy_pass`). For Nginx, the path can be omitted if the original request path does not need to be altered. -- 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: us...@infra.apache.org
