Citrix NetScaler XML API User's Guide

Introduction

The example code that accompanies this file uses c# 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 - WSDL to C# 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.cs 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.cs example fetches information about all configured lb vservers, and prints selected information about each one.

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

The getStat.cs example demonstrates usage of statistical api.

Additional documentation is available as inline comments in the C# programs.

Requirement

For the examples to work, you need the .Net Framework 1.0 and later.

Compiling samples

Instructions to create Client application using NSConfig.wsdl;

Invoke the .Net Framework Command prompt.
Create the client service class from wsdl by using wsdl utility .

C:\<c # sample path>>wsdl NSConfig.wsdl

Microsoft (R) Web Services Description Language Utility
[Microsoft (R) .NET Framework, Version 1.0.3705.0]
Copyright (C) Microsoft Corporation 1998-2001. All rights reserved.
Writing file '<c# sample path>\NSConfigService.cs'.

It will generate the client class to create the client class.

Compiliing and Executing the Client application:

run the build.bat
The Client application is compiled with stub sources and generate set.exe get.exe rm.exe executable.

Finally, execute the NSConfig to configure the NetScaler box remotely.

setConfig <protocol>://<NSIP> <username> <password>
getConfig <protocol>://<NSIP> <username> <password>
rmConfig <protocol>://<NSIP> <username> <password>

Usage

The parameters to all of the examples are:

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

Cookie Handling

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

/*
 * Inherit the generated class from wsdl NSConfigServer and override
 * the method GetWebRequest and GetWebResponse method.
 */
public class ClientService : NSConfigService {

    private string cookie = null;

    /* override the getWebRequest to send cookie */
    protected override System.Net.WebRequest GetWebRequest(Uri uri) {
        System.Net.HttpWebRequest req =
            (System.Net.HttpWebRequest) base.GetWebRequest(uri);
        if (cookie != null) {
            req.Headers.Add("Set-Cookie", cookie);
        }
        return req;
    }

    /* override the getWebResponse to get the cookie */
    protected override System.Net.WebResponse GetWebResponse(System.Net.WebRequest req) {
        System.Net.HttpWebResponserep =
            (System.Net.HttpWebResponse) base.GetWebResponse(req);
        if (rep.Headers["Set-Cookie"] != null) {
            cookie = rep.Headers["Set-Cookie"];
        }
        return rep;
    }
}

HTTPS Support

Developers need to use the HTTPS protocol to send the secured API request to NetScaler. NetScaler by default uses the self signed CA certificate. All C# 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 .NET Framework uses the System.NET.ICertificatePolicy interface to provide custom security certificate validation for an application.This can be overridden.See the following code to achieve it.

using System;
using System.Net;
using System.Security;
using System.Security.Cryptography.X509Certificates;

namespace NSConfig {
    public class trustedCertificatePolicy : System.Net.ICertificatePolicy {
        public trustedCertificatePolicy() {}
        public bool CheckValidationResult(
            System.Net.ServicePoint sp,
            System.Security.Cryptography.X509Certificates.X509Certificate certificate,
            System.Net.WebRequest request, int problem) {
            return true;
        }
    }
}

In application, the default Certificate Policy needs to be overridden with the new trustedCertificatePolicy class.

class NSConfig {
    static void Main(string[] args) {
        System.Net.ServicePointManager.CertificatePolicy = new trustedCertificatePolicy();
        ...
    }
};

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

setconfig https://<NSIP> <username> <password>
getconfig https://<NSIP> <username> <password>
rmconfig https://<NSIP> <username> <password>

Samples

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

Feature configuration samples

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