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