Preserving the Client IP address to iPlanet/SunONE/Sun Java System Web Server servers and Applications

When ZXTM load-balances a connection to an iPlanet/SunONE/Sun Java System Web Server server or application, the connection appears to originate from the ZXTM machine. This can be a problem if the server wishes to perform access control based on the client's IP address, or if it wants to log the true source address of the request.

ZXTM has an IP Transparency feature that preserves the client's IP address, but this requires a kernel module (pre-installed on ZXTM appliances and available separately for ZXTM software) and is currently only available under Linux.

As an alternative, Zeus provide several modules for common server applications to work round this issue. This FAQ describes the iPlanet/Sun NSAPI module.

ZXTM automatically inserts a special 'X-Cluster-Client-Ip' header into each request, which identifies the true source address of the request. Zeus' iPlanet/Sun NSAPI module inspects this header and corrects the calculation of the source address. This change is transparent to the web server, and to any applications running on or behind the web server.

Obtaining the Module

Compile the module from source:

• iprewrite.c

First, build the NSAPI examples in your SunONE installation to determine the appropriate compilation options for your platform:

$ cd plugins/nsapi/examples/
$ make
cc -DNET_SSL -DSOLARIS -D_REENTRANT -DMCC_HTTPD -DXP_UNIX -DSPAPI20 \
   -I../../include -I../../include/base -I../../include/frame -c addlog.c
ld -G addlog.o -o example.so

Then, you can build the iprewrite.so module using similar options. Set NSHOME to the installation location for iPlanet:

$ export NSHOME=/opt/iplanet
$ cc -DNET_SSL -DSOLARIS -D_REENTRANT -DMCC_HTTPD -DXP_UNIX -DSPAPI20 \
   -I$NSHOME/plugins/include -I$NSHOME/plugins/include/base \
   -I$NSHOME/plugins/include/frame -c iprewrite.c
$ ld -G iprewrite.o -o iprewrite.so
$ cp iprewrite.so $NSHOME/plugins

Configuring the Module

To configure the module, you will need to edit the magnus.conf and obj.conf files for the virtual server you are using. If the virtual server is named 'test', you'll find these files in the https-test/config directory.

magnus.conf

Add the following lines to the end of the magnus.conf file.

Ensure that the shlib option identifies the full path to the iprewrite.so module, and that you set TrustedIPs to either '*', or the list of ZXTM back-end IP addresses:

Init fn="load-modules" funcs="iprewrite-init,iprewrite-all,iprewrite-func" \
     shlib="/usr/local/iplanet/plugins/iprewrite.so"
Init fn="iprewrite-init" TrustedIPs="10.100.1.68 10.100.1.69"

The TrustedIPs option specifies the back-end addresses of the ZXTM machines. The iprewrite.so module will only trust the 'X-Cluster-Client-Ip' header in connections which originate from these IP addresses. This means that remote users cannot spoof their source addresses by inserting a false header and accessing the iPlanet/Sun servers directly.

obj.conf

Locate the 'default' object in your obj.conf file and add the following line at the start of the directives inside that object:

<Object name=default>
AuthTrans fn="iprewrite-all"
...

Restart your iPlanet/Sun servers, and monitor your servers' error logs (https-name/log/errors). If you have misconfigured the TrustedIPs value, you will see messages like:

Ignoring X-Cluster-Client-Ip '204.17.28.130' from non-Load Balancer machine '10.100.1.31'

The Result

iPlanet/Sun, and applications running on the server will see the correct source IP address for each request. The access log module will log the correct address when you use %a or %h in your log format string.

Alternate Configuration

The 'iprewrite-all' SAF function changes the ip address for the entire duration of the connection. This may be too invasive for some environments, and its possible that a later SAF function may modify the IP address again. You can use the 'iprewrite-func' SAF function to change the ip address for a single NSAPI function.

For example, BEA's NSAPI WebLogic connector ('wl_proxy') is normally configured as follows:

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl_proxy WebLogicHost=localhost WebLogicPort=7001 PathTrim="/weblogic"
</Object>

You can change the IP address just for that function call, using the iprewrite-func SAF function as follows:

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=iprewrite-func func=wl_proxy WebLogicHost=localhost
  WebLogicPort=7001 PathTrim="/weblogic"
</Object>

Licensing

Zeus provide this module without warranty or any guarantees of fitness for purpose. This module is not covered under Zeus' standard terms of support, but Zeus welcomes suggestions for improvement and will make reasonable efforts to support customers who use it.

You are free to distribute this module and create derivative works from it, provided that you honour the revised-BSD license associated with the module:

 * Copyright (c) 2005 Zeus Technology
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of Zeus Technology nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.

Owen Garrett [Zeus Dev Team] 02 December 2005