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