Return to mod_ip_forwarding.html CVS log | Up to [Public] / apache-modules / mod_ip_forwarding |
1.1 kahan 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" 2: "http://www.w3.org/TR/REC-html40/loose.dtd"> 3: <html> 4: <head> 1.4 kahan 5: <meta http-equiv="Content-Type" content=""> 6: <title>IP Forwarding Module: Compilation and Configuration</title> 1.1 kahan 7: </head> 1.4 kahan 8: 1.2 kahan 9: <body bgcolor="#ffffff"> 10: <p><code>Created: 24/August/1998</code></p> 1.11 ! kahan 11: ! 12: <p>Latest release: 2/Feb/2006</p> 1.2 kahan 13: <hr> 1.1 kahan 14: 1.2 kahan 15: <h1 style="text-align: center"><span style="color: #E55500">mod_ip_forwarding 1.8 kahan 16: v2.0</span></h1> 1.2 kahan 17: <hr> 18: 19: <h2>Outline of the document</h2> 1.1 kahan 20: <ul> 1.4 kahan 21: <li>1. <a href="#1">Purpose</a></li> 1.9 kahan 22: <li>2. <a href="#2">Compiling the IP Forwarding module into Apache</a> 23: <ul> 24: <li>2.1 <a href="#s2.1">Apache 2.4.x</a></li> 25: <li>2.2 <a href="#s2.2">Debian Sarge package for Apache 2.4.x</a></li> 26: <li>2.3 <a href="#s2.3">Apache 1.3.x</a></li> 27: </ul> 28: </li> 1.4 kahan 29: <li>3. <a href="#3">Configuring the IP Forwarding module</a> 30: <ul> 31: <li>3.1 <a href="#3.1">New directives</a></li> 32: <li>3.2 <a href="#3.2">Example</a></li> 33: </ul> 34: </li> 35: <li>4. <a href="#4.">Security Notes</a></li> 1.1 kahan 36: </ul> 37: 38: <h3>Special considerations</h3> 1.2 kahan 39: 1.4 kahan 40: <p>This module is dependent on the Apache API. If you'd like to use the 1.11 ! kahan 41: module on an Apache version higher than v/2.x / v1.3.x, please <a 1.2 kahan 42: href="mailto:jose@w3.org">mail me</a>.</p> 1.1 kahan 43: 44: <h3>Notation</h3> 45: <dl> 1.4 kahan 46: <dt>apache/</dt> 47: <dd>The apache source directory</dd> 1.1 kahan 48: </dl> 49: 50: <h2><a name="1"></a>1. Purpose<a name="2."></a></h2> 1.2 kahan 51: 52: <p>The motivation for this module was to be able to forward the IP address of 53: the source of a request between a proxy and the final destination server. 54: Under normal circumstances, this information is lost and the server only sees 55: the proxy's IP address. This hampers access control based on IP addresses. 56: This module answers this limitation in a transparent and secure way.</p> 57: 58: <p>Proxies forward the IP address inside a custom HTTP header. A server only 1.1 kahan 59: accepts this new header from a list of user-defined authorized proxies. Once 60: the header is accepted, it's internally substituted with the proxy's IP 61: address, so that this value is used for all access control and CGI modules. 62: This doesn't affect the actual IP address used to answer the proxy (they are 63: stored in different places).</p> 64: 1.9 kahan 65: <h2><a name="s2" id="s2">2.</a> Compiling the IP forwarding module into 66: Apache</h2> 1.2 kahan 67: 1.10 kahan 68: <h3><a name="s2.1" id="s2.1">2.1</a> Apache 2.x</h3> 1.4 kahan 69: 1.10 kahan 70: <p>This is what I do to compile the module under Apache 2.0.54. I compile it 71: as a shared library under Debian Sarge. You don't need to compile apache 72: yourself anymore. Isn't life beautiful? These steps may change or not under 73: newer versions of Apache.</p> 1.1 kahan 74: <ol> 1.5 kahan 75: <li>Copy the latest apache 2 file <a 1.10 kahan 76: href="http://dev.w3.org/cvsweb/~checkout~/apache-modules/mod_ip_forwarding/mod_ip_forwarding.c?content-type=text/plain&only_with_tag=HEAD">mod_ip_forwarding.c</a> 1.5 kahan 77: to a local directory</li> 1.4 kahan 78: <li>Compile and install the module as follows: 79: <p><code># /path/to/this/tool/apxs2 -i -a -c 80: /path/to/mod_ip_forwarding.c</code></p> 81: </li> 82: </ol> 1.2 kahan 83: 1.4 kahan 84: <p>Note that module has to have the highest priority among the access control 85: modules. If you're using other proprietary access control modules, this 86: module should correspond to the last <code>activate-module </code>option. 87: Alternatively, you may use the Apache <code>ClearModuleList</code> and 88: <code>AddModule</code> configuration directives to reorder the modules. Also 89: note that you need to enable the <code>proxy</code> module too, as you want 90: to proxy requests.</p> 1.1 kahan 91: 1.10 kahan 92: <h3><a name="s2.2" id="s2.2">2.2</a> Debian Sarge package for Apache 2.x (or 93: superior)</h3> 1.9 kahan 94: 1.10 kahan 95: <p>This is what I do to make a Debian Sarge package of this module for Apache 96: 2.0.54.</p> 1.9 kahan 97: <ol> 98: <li>Make a cvs checkout of the entire mod_ip_forwarding directory: 99: <p><code>$ cvs -d dev.w3.org:/sources/public co 100: apache-modules/mod_ip_forwarding</code></p> 101: </li> 102: <li><code>$ cd apache-modules/mod_ip_forwarding</code></li> 103: <li>As root, type: 104: <p># <code>dpkg-buildpackage -us -us</code></p> 105: <p><code>(obmit the last two parameters if you want to sign the 106: module)</code></p> 107: </li> 108: <li>Once the module is created, it will be stored on the parent directory, 109: with a name such as 110: <code>libapache2-mod-ip-forward_20051129-1_i386.deb</code>. You can 111: install 112: <p>it using the usual debian command (as root):</p> 113: <p><code># dpkg --install 114: libapache2-mod-ip-forward_20051129-1_i386.deb</code></p> 115: </li> 116: </ol> 117: 118: <h3><a name="s2.3" id="s2.3">2.3</a> Apache 1.3.x</h3> 1.1 kahan 119: 1.7 kahan 120: <p>This is what I do to compile the module under Apache 1.3.4. These steps 121: may change or not under newer versions of Apache.</p> 1.4 kahan 122: <ol> 123: <li>Copy the apache (1) file <a 1.10 kahan 124: href="http://dev.w3.org/cvsweb/~checkout~/apache-modules/mod_ip_forwarding/mod_ip_forwarding.c?rev=1.4">mod_ip_forwarding.c</a> 1.4 kahan 125: to the apache/src/modules/extra directory. 126: <p><em><strong>Note that you must follow this link to get the correct 127: version of this file. The latest version will only compile on apache 128: 2.x..</strong></em></p> 129: </li> 130: <li>Compile the module as follows: 131: <p><code># cd apache</code></p> 132: <p><code># ./configure --prefix=/usr/local/apache \</code></p> 133: <p><code>--enable-module=proxy \</code></p> 134: <p><code>--activate-module=src/modules/extra/mod_ip_forwarding.c</code></p> 135: <p><code># make</code></p> 136: <p><code># make install</code></p> 137: </li> 1.1 kahan 138: </ol> 1.2 kahan 139: Note that module has to have the highest priority among the access control 1.4 kahan 140: modules. If you're using other proprietary access control modules, this 141: module should correspond to the last <code>activate-module </code>option. 1.2 kahan 142: Alternatively, you may use the Apache <code>ClearModuleList</code> and 143: <code>AddModule</code> configuration directives to reorder the modules. Also 1.4 kahan 144: note that you need to enable the <code>proxy</code> module too, as you want 145: to proxy requests. 146: 1.9 kahan 147: <h2><a name="2">3</a>. Configuring the IP forwarding module</h2> 1.1 kahan 148: 149: <h3><a name="2.1"></a>3.1 New directives</h3> 1.2 kahan 150: 151: <p>The IP Forwarding module introduces three directives to Apache:</p> 1.1 kahan 152: <dl> 1.4 kahan 153: <dt>ForwardClientIPAddress [on/off default = off]</dt> 154: <dd>Controls forwarding of the X_Client_Address header</dd> 155: <dt>AcceptForwardedClientIPAddress [on/off default = off]</dt> 156: <dd>Authorizes accepting an X_Client_Address header</dd> 157: <dt>LogUnauthorizedIPForwarding [on/off default = on]</dt> 158: <dd>Logs any unauthorized attemp to forward an IP address</dd> 159: <dt>X_ClientIPAddrHeader string [default = X_Fwd_IP_Addr]</dt> 160: <dd>Customizable header string for sending the client ip _addr</dd> 161: <dt>AuthorizedProxies [space separated list of IP addresses]</dt> 162: <dd>List of authorized proxies who can send an X_Client_Address 163: header</dd> 1.1 kahan 164: </dl> 1.2 kahan 165: 166: <p>Note that you need to set up this module on both the proxy server and the 1.1 kahan 167: final destination server. In addition, both servers must use the same 1.4 kahan 168: <code>X_ClientIPAddrHeader</code> value. Finally, the final destination 169: server must add the address of the proxy server using the 1.1 kahan 170: <code>AuthorizedProxies</code> directive. This protects against intruders 171: spoofing this header (unless they also spoof the IP address).</p> 172: 1.3 kahan 173: <p><em>The following is a tip contributed by Paul Roe. Thanks!</em></p> 174: 1.4 kahan 175: <p>If you're using this module as an Apache precompiled module (dynamic 1.3 kahan 176: modules that are downloaded at runtime), you need to add the following 177: configuration directive:</p> 178: <dl> 1.4 kahan 179: <dt>LoadModule ip_forwarding_module 180: /path_to_apache_modules/mod_ip_forwarding.so</dt> 1.3 kahan 181: </dl> 1.4 kahan 182: 1.3 kahan 183: <p>Note that the Debian apache-common-1.3.12-1 package seems to have renamed 1.4 kahan 184: this module as w3c_ip_forwarding_module. In this case, you need to load the 1.3 kahan 185: precompiled module as follows:</p> 186: <dl> 1.4 kahan 187: <dt>LoadModule w3c_ip_forwarding_module 188: /path_to_apache_modules/mod_ip_forwarding.so</dt> 1.3 kahan 189: </dl> 190: 1.1 kahan 191: <h3><a name="3.2"></a>3.2 Example</h3> 1.2 kahan 192: 193: <p>Let's suppose I have a proxy on 134.129.20.116 and a server on 194: 134.129.20.130. In addition, my client is at 123.123.123.123. Here's a 195: fragment of the proxy and final server's configuration:</p> 196: <pre>## Proxy configuration (may also be setup using mod_rewrite) 197: ProxyPass / http://134.129.20.130/ 1.1 kahan 198: ForwardClientIPAddress On</pre> 199: <pre>## Server Configuration 200: AcceptForwardedClientIPAddress On 201: AuthorizedProxies 132.129.20.116</pre> 1.2 kahan 202: 203: <p>When the proxy contacts the server, it includes the following header:</p> 204: <pre>X_Forward_IP_Addr: 123.123.123.123</pre> 205: 206: <p>When the server calls a CGI-script, it sends the following environment 1.1 kahan 207: variable:</p> 1.2 kahan 208: <pre>REMOTE_ADDR: 123.123.123.123</pre> 209: 210: <p>Note that the value of the REMOTE_ADDR environment variable corresponds to 211: the one in the X_FWD_IP_ADDR header. Also, the X_ header was removed, as the 212: final server is not configured to forward the X_ header. To continue 1.4 kahan 213: forwarding the same header, you need to set the ForwardClientIPAddress in 214: that server too.</p> 1.2 kahan 215: 216: <p>If a non-authorized proxy (say,<code> 132.129.20.116</code>) sends the 217: custom header, the module will remove it from the headers and add the 218: following entry in the error log:</p> 1.1 kahan 219: <pre>[Mon Aug 24 15:57:48 1998] Unauthorized Proxy (132.129.20.116) tried to forward 1.2 kahan 220: a client IP address (123.123.123.123)</pre> 221: 222: <h2><a name="4.">4.</a> Security notes</h2> 223: 224: <p>This module does not implement a full-blown secure ip@ forwarding 225: mechanism. In particular, there are two weak security points:</p> 226: <ul> 1.4 kahan 227: <li><strong>IP spoofing.</strong> There's no protection against an 228: intruder's spoofing of the IP@ of an authorized proxy. Under such an 229: attack, the intruder may send any IP@ he wants in the<code> 230: X_ClientIPAddrHeader</code> heeader. This attack is less important when 231: the authorized proxy is on the border of a firewall and the destination 232: server is behind the firewall.</li> 233: <li><strong>Denial of service</strong>. The module generates a log message 1.9 kahan 234: each time that it detects an an IP@ forwarding by an unauthorized proxy. 235: An intruder may attempt filling up a server's logs with a flood of 1.4 kahan 236: unauthorized IP@ forwarding requests. If this attacks occurs, you can 237: temporarily turn off the logging by means of the module's 238: <code>LogUnauthorizedIPForwarding</code> directive.</li> 1.2 kahan 239: </ul> 240: 241: <p></p> 242: <hr> 1.1 kahan 243: <address> 1.4 kahan 244: <a href="mailto:jose@w3.org">Jose</a> 245: </address> 1.11 ! kahan 246: $Author: kahan $ $Date: Friday 03 February 2006 - 16:59:38$</body> 1.1 kahan 247: </html>