Annotation of apache-modules/mod_ip_forwarding/mod_ip_forwarding.html, revision 1.2
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:
144: <h3><a name="3.2"></a>3.2 Example</h3>
1.2 ! kahan 145:
! 146: <p>Let's suppose I have a proxy on 134.129.20.116 and a server on
! 147: 134.129.20.130. In addition, my client is at 123.123.123.123. Here's a
! 148: fragment of the proxy and final server's configuration:</p>
! 149: <pre>## Proxy configuration (may also be setup using mod_rewrite)
! 150: ProxyPass / http://134.129.20.130/
1.1 kahan 151: ForwardClientIPAddress On</pre>
152: <pre>## Server Configuration
153: AcceptForwardedClientIPAddress On
154: AuthorizedProxies 132.129.20.116</pre>
1.2 ! kahan 155:
! 156: <p>When the proxy contacts the server, it includes the following header:</p>
! 157: <pre>X_Forward_IP_Addr: 123.123.123.123</pre>
! 158:
! 159: <p>When the server calls a CGI-script, it sends the following environment
1.1 kahan 160: variable:</p>
1.2 ! kahan 161: <pre>REMOTE_ADDR: 123.123.123.123</pre>
! 162:
! 163: <p>Note that the value of the REMOTE_ADDR environment variable corresponds to
! 164: the one in the X_FWD_IP_ADDR header. Also, the X_ header was removed, as the
! 165: final server is not configured to forward the X_ header. To continue
! 166: forwarding the same header, you need to set the ForwardClientIPAddress in that
! 167: server too.</p>
! 168:
! 169: <p>If a non-authorized proxy (say,<code> 132.129.20.116</code>) sends the
! 170: custom header, the module will remove it from the headers and add the
! 171: following entry in the error log:</p>
1.1 kahan 172: <pre>[Mon Aug 24 15:57:48 1998] Unauthorized Proxy (132.129.20.116) tried to forward
1.2 ! kahan 173: a client IP address (123.123.123.123)</pre>
! 174:
! 175: <h2><a name="4.">4.</a> Security notes</h2>
! 176:
! 177: <p>This module does not implement a full-blown secure ip@ forwarding
! 178: mechanism. In particular, there are two weak security points:</p>
! 179: <ul>
! 180: <li>
! 181: <strong>IP spoofing.</strong> There's no protection against an intruder's
! 182: spoofing of the IP@ of an authorized proxy. Under such an attack, the intruder
! 183: may send any IP@ he wants in the<code> X_ClientIPAddrHeader</code> heeader.
! 184: This attack is less important when the authorized proxy is on the border of a
! 185: firewall and the destination server is behind the firewall.
! 186: </li>
! 187: <li>
! 188: <strong>Denial of service</strong>. The module generates a log message each
! 189: time that it detects an an IP@ forwarding by an unauthorized proxy. An
! 190: intruder may attempt filling up a server's logs with a flood of unauthorized
! 191: IP@ forwarding requests. If this attacks occurs, you can temporarily turn off
! 192: the logging by means of the module's <code>LogUnauthorizedIPForwarding</code>
! 193: directive.
! 194: </li>
! 195: </ul>
! 196:
! 197: <p></p>
! 198: <hr>
! 199:
1.1 kahan 200: <address>
201: <a href="mailto:jose@w3.org">Jose</a></address>
202:
1.2 ! kahan 203: $Author: kahan $ $Date: 1999/03/05 23:00:55 $
1.1 kahan 204: </body>
205: </html>
Webmaster