Showing results for 
Search instead for 
Did you mean: 

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

When Stingray load-balances a connection to an iPlanet/SunONE/Sun Java System Web Server server or application, the connection appears to originate from the Stingray 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, and is well documented in the article IP Transparency: Preserving the Client IP address in Stingray Traffic Manager.


Stingray has an IP Transparency feature that preserves the client's IP address, but this requires a Stingray Kernel Modules for Linux Software (pre-installed on Stingray Virtual Appliances and available separately for Stingray software) and is currently only available under Linux. As an alternative, the mod_remoteip module is a good solution for Apache; this article presents a similar module for iPlanet and related webservers.


How it works


Stingray automatically inserts a special X-Cluster-Client-Ip header into each request, which identifies the true source address of the request. The 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:


To determine the appropriate compilation steps for an NSAPI module for your instance of iPlanet, you can first build the NSAPI examples in your SunONE installation:


$ cd plugins/nsapi/examples/

$ make


-I../../include -I../../include/base -I../../include/frame -c addlog.c

ld -G addlog.o -o


You can build the module using similar options. Set NSHOME to the installation location for iPlanet:


$ export NSHOME=/opt/iplanet


-I$NSHOME/plugins/include -I$NSHOME/plugins/include/base \

-I$NSHOME/plugins/include/frame -c iprewrite.c

$ ld -G iprewrite.o -o

$ cp $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.




Add the following lines to the end of the magnus.conf file. Ensure that the shlib option identifies the full path to the module, and that you set TrustedIPs to either '*', or the list of Stingray back-end IP addresses:


Init fn="load-modules" funcs="iprewrite-init,iprewrite-all,iprewrite-func" \


Init fn="iprewrite-init" TrustedIPs=""


The TrustedIPs option specifies the back-end addresses of the Stingray machines. The 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.




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).


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.


If you have misconfigured the TrustedIPs value, you will see messages like:


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


Add the IP address to the trusted IP list and restart.


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"



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"


Version history
Revision #:
1 of 1
Last update:
‎05-09-2013 03:48:AM
Updated by:
Labels (1)