rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/proxy.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE document [
   3   <!ENTITY project SYSTEM "project.xml">
   4 ]>
   5 <document url="proxy.html">
   6
   7   &project;
   8 <copyright>
   9    Licensed to the Apache Software Foundation (ASF) under one or more
  10    contributor license agreements.  See the NOTICE file distributed with
  11    this work for additional information regarding copyright ownership.
  12    The ASF licenses this file to You under the Apache License, Version 2.0
  13    (the "License"); you may not use this file except in compliance with
  14    the License.  You may obtain a copy of the License at
  15
  16        http://www.apache.org/licenses/LICENSE-2.0
  17
  18    Unless required by applicable law or agreed to in writing, software
  19    distributed under the License is distributed on an "AS IS" BASIS,
  20    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  21    See the License for the specific language governing permissions and
  22    limitations under the License.
  23 </copyright>
  24 <properties>
  25 <title>Reverse Proxy HowTo</title>
  26 <author email="rjung@apache.org">Rainer Jung</author>
  27 <date>$Date: 2011-03-07 16:17:11 +0100 (Mon, 07 Mar 2011) $</date>
  28 </properties>
  29 <body>
  30 <section name="Introduction">
  31 <br/>
  32 <p>The Apache module mod_jk and its ISAPI and NSAPI variants connect
  33 a web server to a backend (typically Tomcat) using the AJP protocol.
  34 The web server receives an HTTP(S) request and the module forwards
  35 the request to the backend. This function is usually called a gateway
  36 or a proxy, in the context of HTTP it is called a reverse proxy.
  37 </p>
  38 </section>
  39 <section name="Typical Problems">
  40 <br/>
  41 <p>A reverse proxy is not totally transparent to the application on
  42 the backend. For instance the host name and port the original client
  43 (e.g. browser) needs to talk to belong to the web server and not to the
  44 backend, so the reverse proxy talks to a different host name and port.
  45 When the application on the backend returns content including
  46 self-referential URLs using its own backend address and port, the
  47 client will usually not be able to use these URLs.
  48 </p>
  49 <p>Another example is the client IP address, which for the web server is the
  50 source IP of the incoming connection, whereas for the backend the
  51 connection always comes from the web server. This can be a problem, when
  52 the client IP is used by the backend application e.g. for security reasons.
  53 </p>
  54 </section>
  55 <section name="AJP as a Solution">
  56 <br/>
  57 <p>Most of these problems are automatically handled by the AJP protocol
  58 and the AJP connectors of the backend. The AJP protocol transports
  59 this communication metadata and the backend connector presents this
  60 metadata whenever the application asks for it using Servlet API methods.
  61 </p>
  62 <p>The following list contains the communication metadata handled by AJP
  63 and the ServletRequest/HttpServletRequest API calls which can be used to retrieve them:
  64 <ul>
  65 <li>local name: <code>getLocalName()</code> and <code>getLocalAddr</code>.
  66 This is also equal to <code>getServerName()</code>, unless a <code>Host</code> header
  67 is contained in the request. In this case the server name is taken from that header.
  68 </li>
  69 <li>local port: <code>getLocalPort()</code>
  70 This is also equal to <code>getServerPort()</code>, unless a <code>Host</code> header
  71 is contained in the request. In this case the server port is taken from that header
  72 if it contains an explicit port, or is equal to the default port of the scheme used.
  73 </li>
  74 <li>client address: <code>getRemoteAddr()</code>
  75 </li>
  76 <li>client port: <code>getRemotePort()</code>
  77 The remote port was initially not supported. It is available when using mod_jk 1.2.32
  78 with Apache or IIS (not for the NSAPI plugin) together with Tomcat version at least
  79 5.5.28, 6.0.20 or 7.0.0. For older versions, <code>getRemotePort()</code>
  80 will incorrectly return 0 or -1. As a workaround you can forward the remote port by setting
  81 <code>JkEnvVar REMOTE_PORT</code> and then either using
  82 <code>request.getAttribute("REMOTE_PORT")</code> instead of <code>getRemotePort()</code>
  83 or wrapping the request using a filter and overriding <code>getRemotePort()</code> with
  84 <code>request.getAttribute("REMOTE_PORT")</code>.
  85 </li>
  86 <li>client host: <code>getRemoteHost()</code>
  87 </li>
  88 <li>authentication type: <code>getAuthType()</code>
  89 </li>
  90 <li>remote user: <code>getRemoteUser()</code>,
  91 if <code>tomcatAuthentication="false"</code>
  92 </li>
  93 <li>protocol: <code>getProtocol()</code>
  94 </li>
  95 <li>HTTP method: <code>getMethod()</code>
  96 </li>
  97 <li>URI: <code>getRequestURI()</code>
  98 </li>
  99 <li>HTTPS used: <code>isSecure()</code>, <code>getScheme()</code>
 100 </li>
 101 <li>query string: <code>getQueryString()</code>
 102 </li>
 103 </ul>
 104 The following additional SSL-related data will be made available by Apache and forwarded by mod_jk only
 105 if you set <code>SSLOptions +StdEnvVars</code>. For the certificate information you also need
 106 to set <code>SSLOptions +ExportCertData</code>.
 107 <ul>
 108 <li>SSL cipher: <code>getAttribute(javax.servlet.request.cipher_suite)</code>
 109 </li>
 110 <li>SSL key size: <code>getAttribute(javax.servlet.request.key_size)</code>.
 111 Can be disabled using <code>JkOptions -ForwardKeySize</code>.
 112 </li>
 113 <li>SSL client certificate: <code>getAttribute(javax.servlet.request.X509Certificate)</code>.
 114 If you want the whole certificate chain, then you need to also set <code>JkOptions ForwardSSLCertChain</code>.
 115 It is likely, that in this case you also need to adjust the maximal AJP packet size
 116 using the worker attribute <a href="../reference/workers.html">max_packet_size</a>.
 117 </li>
 118 <li>SSL session ID: <code>getAttribute(javax.servlet.request.ssl_session)</code>.
 119 This is for Tomcat, it has not yet been standardized.
 120 </li>
 121 </ul>
 122 </p>
 123 </section>
 124 <section name="Fine Tuning">
 125 <br/>
 126 <p>In some situations this is not enough though. Assume there is another
 127 less clever reverse proxy in front of your web server, for instance an
 128 HTTP load balancer or similar device which also serves as an SSL accelerator.
 129 </p>
 130 <p>Then you are sure that all your clients use HTTPS, but your web server doesn't
 131 know about that. All it can see is requests coming from the accelerator using
 132 plain HTTP.
 133 </p>
 134 <p>Another example would be a simple reverse proxy in front of your web server,
 135 so that the client IP address that your web server sees is always the IP address
 136 of this reverse proxy, and not of the original client. Often such reverse proxies
 137 generate an additional HTTP header, like <code>X-Forwareded-for</code> which
 138 contains the original client IP address (or a list of IP addresses, if there are
 139 more cascading reverse proxies in front). It would be nice, if we could use the
 140 content of such a header as the client IP address to pass to the backend.
 141 </p>
 142 <p>So we might need to manipulate some of the data that AJP sends to the backend.
 143 When using mod_jk inside Apache httpd you can use several httpd environment
 144 variables to let mod_jk know, which data it should forward. These environment variables
 145 can be set by the httpd directives SetEnv or SetEnvIf, but also in a very flexible
 146 way using mod_rewrite (since httpd 2.x it can not only test against environment
 147 variables, but also set them).
 148 </p>
 149 <p>The following list contains all environment variables mod_jk checks, before
 150 sending data to the backend:
 151 <ul>
 152 <li>JK_LOCAL_NAME: the local name
 153 </li>
 154 <li>JK_LOCAL_PORT: the local port
 155 </li>
 156 <li>JK_REMOTE_HOST: the client host
 157 </li>
 158 <li>JK_REMOTE_ADDR: the client address
 159 </li>
 160 <li>JK_AUTH_TYPE: the authentication type
 161 </li>
 162 <li>JK_REMOTE_USER: the remote user
 163 </li>
 164 <li>HTTPS: On (case-insensitive) to indicate, that HTTPS is used
 165 </li>
 166 <li>SSL_CIPHER: the SSL cipher
 167 </li>
 168 <li>SSL_CIPHER_USEKEYSIZE: the SSL key size
 169 </li>
 170 <li>SSL_CLIENT_CERT: the SSL client certificate
 171 </li>
 172 <li>SSL_CLIENT_CERT_CHAIN_: prefix of variable names, containing
 173 the client cerificate chain
 174 </li>
 175 <li>SSL_SESSION_ID: the SSL session ID
 176 </li>
 177 </ul>
 178 </p>
 179 <p>Remember: in general you don't need to set them. The module retrieves the data automatically
 180 from the web server. Only in case you want to change this data, you can overwrite it by
 181 using these variables.
 182 </p>
 183 <p>Some of these variables might also be used by other web server modules. All
 184 variables whose name does not begin with "JK" are set directly by Apache httpd.
 185 If you want to change the data, but do not want to negatively influence the behaviour
 186 of other modules, you can change the names of all variables mod_jk uses to private ones.
 187 For the details see the <a href="../reference/apache.html">Apache reference</a> page.
 188 </p>
 189 <p>All variables, that are not SSL-related have only been introduced in version 1.2.27.
 190 </p>
 191 <p>Finally there is a shortcut to forward the local IP of the web server as the remote IP.
 192 This can be useful, e.g. when using the Tomcat remote address valve for allowing connections
 193 only from registered Apache web servers. This feature is activated by setting
 194 <code>JkOptions ForwardLocalAddress</code>.
 195 </p>
 196 </section>
 197 <section name="Tomcat AJP Connector Settings">
 198 <br/>
 199 <p>As an alternative to using the environment variables described in the previous section
 200 (which do only exist when using Apache httpd), you can also configure Tomcat to overwrite
 201 some of the communications data forwarded by mod_jk. The AJP connector in Tomcat's <code>server.xml</code>
 202 allows to set the <a href="http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html#Attributes">following properties</a>:
 203 <ul>
 204 <li>proxyName: server name as returned by <code>getServerName()</code>
 205 </li>
 206 <li>proxyPort: server port as returned by <code>getServerPort()</code>
 207 </li>
 208 <li>scheme: protocol scheme as returned by <code>getScheme()</code>
 209 </li>
 210 <li>secure: set to "true", if you wish <code>isSecure()</code> to return "true".
 211 </li>
 212 </ul>
 213 Remember: in general you don't need to set those. AJP automatically handles all cases
 214 where the web server running mod_jk knows the right data.
 215 </p>
 216 </section>
 217 <section name="URL Handling">
 218 <br/>
 219 <subsection name="URL Rewriting">
 220 <p>Sometimes one want to change path components of the URLs under which an application
 221 is available. Especially if a web application is deployed as some context, say <code>/myapp</code>,
 222 marketing prefers short URLs, so want the application to be directly available under
 223 <code>http://www.mycompany.com/</code>. Although you can deploy the application as the so-called
 224 ROOT context, which will be directly available at "/", admins often prefer not to use
 225 the ROOT context, e.g. because only one application can be the root context (per host).
 226 </p>
 227 <p>The procedure to change the URLs in the reverse proxy is tedious, because often
 228 an application produces self-referential URLs, which then include the path components
 229 which you tried to hide to the outside world. Nevertheless, if you absolutely need to do it,
 230 here are the steps.
 231 </p>
 232 <p>Case A: You need to make the application available at a simple URL, but it is OK, if
 233 users proceed using the more complex URLs, as long as they don't have to type them in.
 234 That's the easy case, and if this suffices to you, you're lucky. Use a simply RedirectMatch
 235 for Apache httpd:
 236 </p>
 237 <source>
 238 RedirectMatch ^/$ http://www.mycompany.com/myapp/
 239 </source>
 240 <p>Your application will then be available under <code>http://www.mycompany.com/</code>,
 241 and each visitor will be immediately redirected to the real URL
 242 <code>http://www.mycompany.com/myapp/</code>
 243 </p>
 244 <p>Case B: You need to hide path components for all requests going to the application.
 245 Here's the recipe for the case, where you want to hide the first path component
 246 <code>/myapp</code>. More complex manipulations are left as an exercise to the reader.
 247 First the solution for the case of Apache httpd:
 248 </p>
 249 <p>1. Use <a href="http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html"><code>mod_rewrite</code></a>
 250 to add <code>/myapp</code> to all requests before forwarding to the backend:
 251 </p>
 252 <source>
 253 # Don't forget the PT flag! (pass through)
 254 RewriteRule ^/(.*) http://www.mycompany.com/myapp/$1 [PT]
 255 </source>
 256 <p>2. Use <a href="http://httpd.apache.org/docs/2.2/mod/mod_headers.html"><code>mod_headers</code></a>
 257 to rewrite any HTTP redirects your application might return. Such redirects typically contain
 258 the path components you want to hide, because by the HTTP standard, redirects always need to include
 259 the full URL, and your application is not aware of the fact, that your clients talk to it via
 260 some shortened URL. An HTTP redirect is done with a special response header named <code>Location</code>.
 261 We rewrite the Location headers of our responses:
 262 </p>
 263 <source>
 264 # Keep protocol, server and port if present,
 265 # but insert our webapp name before the rest of the URL
 266 Header edit Location ^([^/]*//[^/]*)?/(.*)$ $1/myapp/$2
 267 </source>
 268 <p>3. Use <code>mod_headers</code> again, to rewrite the paths contained in any cookies,
 269 your application might set. Such cookie paths again might contain
 270 the path components you want to hide.
 271 A cookie is set with the HTTP response header named <code>Set-Cookie</code>.
 272 We rewrite the Set-Cookie headers of our responses:
 273 </p>
 274 <source>
 275 # Fix the cookie path
 276 Header edit Set-Cookie "^(.*; Path=/)(.*)" $1/myapp/$2
 277 </source>
 278 <p>3. Some applications might contain hard coded absolute links.
 279 In this case check, whether you find a configuration item for your web framework
 280 to configure the base URL. If not, your only chance is to parse all response
 281 content bodies and do search and replace. This is fragile and very resource intensive.
 282 If you really need to do this, you can use
 283 <a href="http://apache.webthing.com/mod_proxy_html/"><code>mod_proxy_html</code></a>,
 284 <a href="http://httpd.apache.org/docs/2.2/mod/mod_substitute.html"><code>mod_substitute</code></a>
 285 or <a href="http://blogs.sun.com/basant/entry/using_mod_sed_to_filter"><code>mod_sed</code></a>
 286 for this task.
 287 </p>
 288 <p>If you are using Microsoft IIS as a web server, the ISAPI plugin provides a way
 289 of doing the first step with a builtin feature. You define a mapping file for simple prefix
 290 changes like this:
 291 </p>
 292 <source>
 293 # Add a context prefix to all requests ...
 294 /=/myapp/
 295 # ... or change some prefix ...
 296 /oldapp/=/myapp/
 297 </source>
 298 <p>and then put the name of the file in the <code>rewrite_rule_file</code> entry of the registry or your
 299 <code>isapi_redirect.properties</code> file. In you <code>uriworkermap.properties</code> file, you
 300 still need to map the URLs as they are before rewriting!
 301 </p>
 302 <p>More complex rewrites can be done using the same file, but with regular expressions. A leading
 303 tilde sign '<code>~</code>', indicates, that you are using a regular expression:
 304 </p>
 305 <source>
 306 # Use a regular expression rewrite
 307 ~/oldapps([0-9]*)/=/newapps$1/
 308 </source>
 309 <p>There is no support for Steps 2 (rewriting redirect responses) or 3 (rewriting cookie paths).
 310 </p>
 311 </subsection>
 312 <subsection name="URL Encoding">
 313 <p>Some types of problems are triggered by the use of encoded URLs
 314 (see <a href="http://en.wikipedia.org/wiki/Percent-encoding">percent encoding</a>).
 315 For the same location there exist
 316 a lot of different URLs which are equivalent. The reverse proxy needs to inspect the URL in order
 317 to apply its own authentication rules and to decide, to which backend it should send the request
 318 (or whether it should handle it itself). Therefore the request URL first is normalized:
 319 percent encoded characters are decoded, <code>/./</code> is replaced by <code>/</code>,
 320 <code>/XXX/../</code> is replaced by <code>/</code> and similar manipulations of the URL are done.
 321 After that, the web server might apply rewrite rules to further change the URL in less obvious ways.
 322 Finally there is no more way to put the resulting URL in an encoding, which is "similar" to
 323 the one which was used for the original URL.
 324 </p>
 325 <p>
 326 For historical reasons, there have been several alternatives, how mod_jk and the ISAPI
 327 plugin encoded the resulting URL before sending it to the backend. They could be chosen via
 328 <code>JkOptions</code> (Apache httpd) or <code>uri_select</code> (ISAPI). None of those historical
 329 encodings are recommended, because they have either negative functionality implications or
 330 pose a security risk. The default encoding since version 1.2.24 is <code>ForwardURIProxy</code>
 331 (Apache httpd) or <code>proxy</code> (ISAPI) and it is strongly recommended to keep the default
 332 and remove all old explicit settings.
 333 </p>
 334 </subsection>
 335 </section>
 336 <section name="Request Attributes">
 337 <br/>
 338 <p>
 339 You can also add more attributes to any request you are forwarding when using Apache httpd.
 340 For this use the <code>JkEnvVar</code> directive (for details see the
 341 <a href="../reference/apache.html">Apache reference</a> page). Such request attributes can be
 342 retrieved on the Tomcat side via request.getAttribute(attributeName).
 343 Note that their names will not be listed in request.getAttributeNames()!
 344 </p>
 345 </section>
 346 </body>
 347 </document>