Citrix NetScaler XML API User's Guide

Introduction

The example code that accompanies this file uses JAVA to communicate with Netscaler, using XML/SOAP. Here, we describe how to get it up and running.

The full NSConfig.wsdl file is very large - java WSDL to java class generation utility can take time to parse it. You can avoid this by creating a custom subset of the WSDL, containing just the methods used in these examples:

filterwsdl NSConfig.fullwsdl "add service" "set service*" "show service"
                             "bind lbmonitor*" "add lb vserver" "bind lb vserver*"
                             "show lb vserver" "rm service" "rm vserver"
                             "save nsconfig" > NSConfig.wsdl

Note that you need to modify NSConfig.wsdl file at the bottom, where it says location="http://NetScaler/soap/" to location="http://10.100.50.25/soap/", where 10.100.50.25 is assumed to be your Netscaler's IP address.

The setConfig.java example uses the Netscaler API to:

log in to Netscaler
add a service
bind a monitor
add a vserver
bind a service to a vserver
save configuration
remove added vservers and services
log out

The getConfig.java example fetches information about all configured lb vservers, and prints selected information about each one.

The rmConfig.java example removes all of the configuration that was created by setConfig.cs.

The getStat.java example demonstrates usage of statistical api.

Additional documentation is available as inline comments in the java programs.

Requirement

For the examples to work, you need the JSDK 1.4.2 and later, axis 1.1 and later, xerces-2.5.0. or Sun Java Web Service Development Pack: http://java.sun.com/webservices/jwsdp/index.jsp

Compiling samples

Instructions to create Client application using NSConfig.wsdl:

Modify the path of JDK_HOME, JAVA_HOME, AXIS_HOME,XERCES_HOME in build.bat and run.bat
Compiling sample Client application : build.bat
The Client application is compiled with stub sources and generate setConfig.java, setConfig.class, setConfig.class.
Finally, execute the NSConfig to configure the NetScaler box remotely - run.bat/

Usage

The parameters to all of the examples are :

run <protocol>://<NSIP> <username> <password>

Cookie Handling

NetScaler uses the cookies for client authentication purposes. Java client needs to handle the cookies. Please add the following code in client code to handle the cookie.

public static void main(String[] args) {
    ...
    client = new NSStatBindingStub(new URL(<url>),null);
    client.setMaintainSession(true); // This is to handle the cookies.
    ...
}

HTTPS Support

Developer need to use the HTTPS protocol to send the secured API request to NetScaler. NetScaler by default uses the self signed CA certificate. All java client need to handle the self signed certificate if user is sending the https request to the NetScaler.

Please follow the given instruction to use the https protocol in API requests.The JAVA Framework uses the java.security.Provider interface to provide custom security certificate validation for an application.This can be overridden.See the following code to achieve it.

import java.security.AccessController; 
import java.security.InvalidAlgorithmParameterException; 
import java.security.KeyStore; 
import java.security.KeyStoreException; 
import java.security.PrivilegedAction; 
import java.security.Security; 
import java.security.cert.X509Certificate; 
  
import javax.net.ssl.ManagerFactoryParameters; 
import javax.net.ssl.TrustManager; 
import javax.net.ssl.TrustManagerFactorySpi; 
import javax.net.ssl.X509TrustManager; 
  
final class XTrustProvider extends java.security.Provider
{ 
    private final static String NAME = "XTrustJSSE"; 
    private final static String INFO =
        "XTrust JSSE Provider (implements trust factory with truststore validation disabled)"; 
    private final static double VERSION = 1.0D; 
     
    public XTrustProvider()
   { 
       super(NAME, VERSION, INFO); 
        
       AccessController.doPrivileged(new PrivilegedAction()
      { 
         public Object run()
         { 
                 put("TrustManagerFactory." + TrustManagerFactoryImpl.getAlgorithm(),  
                                               TrustManagerFactoryImpl.class.getName()); 
                 return null; 
             } 
       }); 
    } 
     
    public static void install()
   { 
       if(Security.getProvider(NAME) == null)
      { 
          Security.insertProviderAt(new XTrustProvider(), 2); 
          Security.setProperty("ssl.TrustManagerFactory.algorithm",
              TrustManagerFactoryImpl.getAlgorithm()); 
       } 
    } 
     
    public final static class TrustManagerFactoryImpl extends TrustManagerFactorySpi
   { 
       public TrustManagerFactoryImpl() { } 
       public static String getAlgorithm() { return "XTrust509"; } 
       protected void engineInit(KeyStore keystore) throws KeyStoreException { } 
       protected void engineInit(ManagerFactoryParameters mgrparams)
         throws InvalidAlgorithmParameterException
      { 
          throw new InvalidAlgorithmParameterException(
              XTrustProvider.NAME + " does not use ManagerFactoryParameters"); 
       } 
        
       protected TrustManager[] engineGetTrustManagers()
      { 
            return new TrustManager[] { new X509TrustManager()
         { 
             public X509Certificate[] getAcceptedIssuers() { return null; } 
             public void checkClientTrusted(X509Certificate[] certs, String authType) { } 
             public void checkServerTrusted(X509Certificate[] certs, String authType) { } 
            }}; 
        } 
    } 
 }

In application, one needs to call install on XTrustProvider.

				public class getConfig  {
				public static void main(String[] args) {
				XTrustProvider.install();
				...
				}
				}

Now, all SSL based communications in this application will follow the new security policy of allowing all server certificates.

run https://<NSIP> <username> <password>

Disable HREF

Please use following piece of code to disable the href support in Axis java client.

((org.apache.axis.client.Stub)client)._setProperty(
    org.apache.axis.AxisEngine.PROP_DOMULTIREFS, Boolean.FALSE);

Samples

getConfig.java	The getConfig example fetches information about all configured entities and prints selected information about each one.
setConfig.java	The setConfig example uses the Netscaler API to set and bind certain entities in the System.
rmConfig.java	The rmConfig example removes all of the configuration that was created by setConfig.
getStat.java	The getStat example demonstrates usage of statistical api.

Feature configuration samples

acl.java	ACL configuration sample.
cmp.java	Compression configuration sample.
csw.java	Content Switching configuration sample.
lb.java	Load Balancer configuration sample.
rba.java	RBA configuration sample.
rewrite.java	Rewrite configuration sample.
ssl.java	SSL Base configuration sample.
ssl_crl.java	SSL Client-Auth with CRL configuration sample.