NetScaler XML-API

consciousflickΛογισμικό & κατασκευή λογ/κού

11 Νοε 2012 (πριν από 4 χρόνια και 11 μήνες)

1.052 εμφανίσεις

NetScaler XML
-
API

-

Prakash Mana (09/28/2007)

2

© 2007 Citrix Systems, Inc.


All rights reserved

XML
-
API : A Programmatic Interface to NS


XML
-
API is the programmatic interface to configure and monitor
the NetScaler devices


Advantages of API


The API provides developers the advantage of controlling the system
from custom applications.


The interface allows the developers to easily and quickly develop client
applications using a language and platform with which the developer is
most comfortable.


The API provides a secure, end
-
to
-
end, standards
-
based framework that
integrates into the existing management infrastructure.


APIs are provided for


Add commands


Set / Unset commands


Bind / Unbind commands


Remove commands

3

© 2007 Citrix Systems, Inc.


All rights reserved

What is an API?



set of routines that an application uses to request and
carry out lower
-
level services performed by a computer's
operating system


+


set of calling conventions in programming that define how a
service is invoked through the application


Practically, an API is any interface that enables one
program to use facilities provided by another, whether by
calling that program, or by being called by it. At a higher
level still, an API is a set of functionality delivered by a
programming system, and as such the mix of APIs in a
particular system tells you what that system can do.

4

© 2007 Citrix Systems, Inc.


All rights reserved

Methods of Accessing Services


The services provided by a system may be accessible
locally or remotely through Inter Process Communication
mechanisms such as Sockets / RPC or Web Services.


Non
-
web services based mechanisms have proprietary
communication protocols and payload descriptions


A Web service is any piece of software that makes itself
available over the Internet and uses a standardized XML
messaging system. There should be some simple
mechanism for interested parties to locate the service and
locate its public interface

5

© 2007 Citrix Systems, Inc.


All rights reserved

WSDL


WSDL


W
eb
S
ervices
D
efinition
L
anguage


WSDL is the XML language for describing the web services and their
public interface


NetScaler exposes two web services


Configuration Services via
NSConfig.WSDL


Statistics Services via
NSStat.WSDL


The WSDL files are located on the NetScaler and are accessible from


/
netscaler/api



http://<
nsip
>/
api


The interface for configuration and retrieval of statistics is exposed
through the WSDL files.

6

© 2007 Citrix Systems, Inc.


All rights reserved

SOAP


Web services are implemented using SOAP
(Simple Object Access Protocol) over HTTP /
HTTPs.


SOAP is the wire protocol


HTTP / HTTPS is the transport protocol


Advantages of SOAP


A W3C recommended standard


An XML based serialization format


Cross
-
platform integration, It is supported by a variety of platforms and
programming languages.


Open Standard (Non proprietary)

7

© 2007 Citrix Systems, Inc.


All rights reserved

Data Flow

8

© 2007 Citrix Systems, Inc.


All rights reserved

Data Flow


Soap client sends the request to Apache running on NetScaler


Apache has soap handler


Apache listens on port 80 for http soap requests


Apache listens on port 443 for https soap requests


Apache soap handler parses the soap requests and passes the
requests to the configuration engine (nsnetsvc)


Config engine performs RBA and forwards the request to kernel for
processing and sends back the result to the soap handler


Soap hander converts the response in soap format and returns back
to the soap client

9

© 2007 Citrix Systems, Inc.


All rights reserved

Supported Platforms


By definition SOAP is cross platform, However
NetScaler has tested the API implementation on
the following platforms


Java and C# on Windows


Perl and C on Windows, FreeBSD and Linux.

10

© 2007 Citrix Systems, Inc.


All rights reserved

API Basic


Any API call is basically built up of three things:

1.
Return (return value)

2.
Method Name (message tag)

3.
Signature (value return {input/output})


11

© 2007 Citrix Systems, Inc.


All rights reserved

Understanding WSDL


Method Definition is specified with <message> tag


Input arguments are specified with <part> tag


Enumerations are defined with <simpleType> tag


Result or return structures are specified with <ComplexType> tag


The <operation> tag links the method with the return structure


simpleResult is the generic return structure for all non
-
get commands


simpleResult returns the numeric return code (rc field), Zero if the call is
successful, error code in case of failures


simpleResult returns “Done” in message field if the call is successful, descriptive
error message in case of failures


In case of get and stat methods, call specific structures are returned.

12

© 2007 Citrix Systems, Inc.


All rights reserved

NetScaler API


Config : Simple result, RC (return code) and
Message.


Get : RC, Message and Object of List


13

© 2007 Citrix Systems, Inc.


All rights reserved

Method Name i.e. message tag

14

© 2007 Citrix Systems, Inc.


All rights reserved

Method name =

Message name + Part name

<
message name
="
addserver
">


<
part name
="name" type="
xsd:string
"/>


<part name="
ipaddress
" type="
xsd:string
"/>


<part name="domain" type="
xsd:string
"/>


<part name="state" type="
ns:
enabledisabledEnum
"/>

</message>



Usually these values (in part name) are specified as string, when ever there is “ns:”
present then that will be of type
enum
.


Enums

are defined at the top of the
wsdl

file.


Ex : <
xsd:simpleType

name="
enabledisabledEnum
">


<
xsd:restriction

base="
xsd:string
">


<
xsd:enumeration

value="ENABLED"/>


<
xsd:enumeration

value="DISABLED"/>


<
xsd:enumeration

value="VALNOTSET"/>


</
xsd:restriction
>


</
xsd:simpleType
>



15

© 2007 Citrix Systems, Inc.


All rights reserved

Signature =

Operation name + Input/Output














<
operation name
="addservice">


<documentation>


</documentation>


<
input message
="ns:addservice"/>


<
output message
="ns:addserviceResponse"/>


</operation>


16

© 2007 Citrix Systems, Inc.


All rights reserved

Non
-
Get Commands


Command definition.


<message name="
addlbvserver
">


<part name="name" type="
xsd:string
"/>


<part name="
servicetype
" type="
ns:vservicetypeEnum
"/>


<part name="
ipaddress
" type="
xsd:string
"/>


<part name="port" type="
xsd:unsignedInt
"/>


<part name="range" type="
xsd:unsignedInt
"/>


<part name="state" type="
ns:enabledisabledEnum
"/>


</message>


Enumeration definition


<
xsd:simpleType

name="
vservicetypeEnum
">



<
xsd:restriction

base="
xsd:string
">


<
xsd:enumeration

value="HTTP"/>


<
xsd:enumeration

value="FTP"/>





<
xsd:enumeration

value="VALNOTSET"/>



</
xsd:restriction
>


</
xsd:simpleType
>


Return (Response)
Strcuture
.


<
xsd:complexType

name="
simpleResult
">



<
xsd:all
>


<
xsd:element

name="
rc
" type="
xsd:unsignedInt
"/>


<
xsd:element

name="message" type="
xsd:string
"/>



</
xsd:all
>


</
xsd:complexType
>

17

© 2007 Citrix Systems, Inc.


All rights reserved

Get/Stat Commands


Command definition.


<message name=“
getlbvserver
">


<part name="name" type="
xsd:string
"/>


</message>


Return (Response) structure


<
xsd:complexType

name="
getlbvserverResult
">


<
xsd:all
>


<
xsd:element

name="
rc
" type="
xsd:unsignedInt
"/>


<
xsd:element

name="message" type="
xsd:string
"/>


<
xsd:element

name="List" type="
ns:lbvserverList
"
minOccurs
="0"/>


</
xsd:all
>


</
xsd:complexType
>



<
xsd:complexType

name="
lbvserverList
">



<
xsd:complexContent
>




<
xsd:restriction

base="
soapenc:Array
"> <
xsd:attribute

ref="
soapenc:arrayType
"
wsdl:arrayType
="
ns:lbvserver
[]"/>


</
xsd:restriction
>



</
xsd:complexContent
>


</
xsd:complexType
>



<
xsd:complexType

name="
lbvserver
">


<
xsd:sequence
>


<
xsd:element

name="name" type="
xsd:string
"/>


<
xsd:element

name="
ipaddress
" type="
xsd:string
"/>


<
xsd:element

name="status" type="
xsd:int
"/>







<
xsd:element

name="
dospolicyname
" type="
ns:stringList
"/>


<
xsd:element

name="
dospolicypriority
" type="
ns:unsignedIntList
"/>


</
xsd:sequence
>


</
xsd:complexType
>

18

© 2007 Citrix Systems, Inc.


All rights reserved

API Vs CLI Mapping


The CLI commands have corresponding API calls


It has same input arguments as commands


It has same return attributes as commands (get commands)


All API names are same as command names joined together


“add lb vserver” is “addlbvserver”


All show commands are get API


“show lb vserver” is “getlbvserver”


Add commands have arguments that are required to create entity


addlbvserver(string name, vservicetypeEnum servicetype, string ipaddress, System.UInt32
port, System.UInt32 range, enabledisabledEnum state)


Set/Bind/unbind command has different API to set individual arguments but all
dependent argument are in the same api.


setlbvserver_pq(string name, onoffEnum pq)


bindlbvserver_policy(string name, string policyname, System.UInt32 priority)


bindlbvserver_service(string name, string servicename, System.UInt32 weight)


setlbvserver_lbmethod(string name, lbmethodEnum lbmethod, System.UInt32 hashlength,
string netmask)

19

© 2007 Citrix Systems, Inc.


All rights reserved

Unsupported Operations in API


Shutdown


Create SSL certificate


Ping, tracert etc.

SOAP Client Development

21

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Setup the development environment with soap tool kit.


Download the WSDL


Consume and generate the client stub in specific language by
using tool.


Write the client application


Login


We use cookie based authentication. Find out how to handle the cookie
for authentication in the development environment.


Commands


Logout


Compile and run

22

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Development environment should be as specified in the
documentation


Authentication cookie should be handled in client code


URL should be : http://<NS
-
IP>/soap or https://<NS
-
IP>/soap for secure communication


Login is required before executing any command


Client side handling is required for self signed certificate in
case of https


On apache log rotation, re
-
login is required.

SOAP Client Development

With C

24

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Download the
NSConfig.wsdl

and
NSStat.wsdl

from NetScaler


Use
wsdl

tool to generate the client stub for C#


C:>
wsdl

NSConfig.wsdl


This will generate
NSConfigService.cs


Write the client application (see the sample)


Login


Commands


logout


Compile the client Application


csc

/
t:exe

/r:System.dll,System.Web.dll,System.XML.dll,System.Web.Services.dll
<sample>.
cs

NSConfigService.cs


The above command will generate the <sample>.exe


Run <sample>.exe with appropriate parameters







OR


Copy the tar
bol

“ns
-
gsoap
-
sample
-
freebsd.tar
” from NS CD, that contains different
samples.


Untar

the file and do “make all”, that will create all the necessary stubs and .exe files.


.exe files can, then, be used to make API calls to NetScaler.




25

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach

26

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.

SOAP Client Development

With .NET

28

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Download and install the .NET Framework 1.0 redistribution package or above from Microsoft site
(Developer Tools) and install the same.


Download .NET framework SDK 1.0 or above** from Microsoft site (Developer Tools) and Install


OR


Install Visual Studio.NET which contains both of the above components


Invoke the SDK Command Prompt if using VS.NET


OR


Invoke command prompt and run the
sdkvars.bat

or equivalent from the “C:
\
Program
Files
\
Microsoft.NET
\
SDK
\
<Version>
\
Bin” folder


Download the
NSConfig.wsdl

and
NSStat.wsdl

from NetScaler


Use
wsdl

tool to generate the client stub for C#


C:>
wsdl

NSConfig.wsdl


This will generate
NSConfigService.cs


Write the client application (see the sample)


Login


Commands


logout


Compile the client Application


csc

/
t:exe

/r:System.dll,System.Web.dll,System.XML.dll,System.Web.Services.dll <sample>.
cs

NSConfigService.cs


The above command will generate the <sample>.exe


Run <sample>.exe with appropriate parameters


** But not 2.0 as NS doesn’t work properly with 2.0.

29

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach


Launch the SDK command prompt


Make the necessary changes in your
makesamp.bat

file to point towards the correct
location of
sdkvars
. In this case it is



set
sdkvars
="C:
\
Program Files
\
Microsoft Visual Studio 8
\
SDK
\
v2.0
\
Bin
\
sdkvars.bat“





30

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.


Run and compile
makesamp.bat

file
that will create the
executables for
making API calls:


C:
\
Documents
and
Settings
\
prakashm
a
\
Desktop
\
apidoc
\
d
ocs
\
samples
\
cshar
p
>
makesamp.bat


31

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.

32

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.


Use the .exe files to make api calls:


C:
\
Documents and
Settings
\
prakashma
\
Desktop
\
apidoc
\
docs
\
samples
\
csharp>getConfig

.exe 10.102.12.120 nsroot nsroot


Connecting to server 10.102.12.120 ............


login : Done

getlbvserver : Done

vs1 : :80() UP

getlbvserver vip_1 : No such resource [name, vip_1]

getlbvserver(nonesuch) : No such resource [name, nonesuch]

logout : EOF


C:
\
Documents and Settings
\
prakashma
\
Desktop
\
apidoc
\
docs
\
samples
\
csharp>


33

© 2007 Citrix Systems, Inc.


All rights reserved

Handling Authentication


Override the generated C# class for handling cookie based authentication


public class
ClientService

:
NSConfigService



{



private static string cookie = null;






// send authentication cookie for the request



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
;



}



// Remember the authentication cookie
recieved

in the response




protected override
System.Net.WebResponse

GetWebResponse
(
System.Net.WebRequest

req
)



{




System.Net.HttpWebResponse

rep = (
System.Net.HttpWebResponse
)
base.GetWebResponse
(
req
);




if (
rep.Headers
["Set
-
Cookie"] != null)




{





cookie =
rep.Headers
["Set
-
Cookie"];




}




return rep;



}



public
ClientService
(string
servername
)



{




this.Url

=
http://

+
servername

+ "/soap";



}


}


34

© 2007 Citrix Systems, Inc.


All rights reserved

Login and Sample Command


Here are the sample of login and executing command




client = new
ClientService
(
servername
);




// This line is required for handling authentication cookie.





client.CookieContainer

= new
System.Net.CookieContainer
();




// Login request




result =
client.login
(
username,password
) ;




Console.WriteLine
("login : “ +
result.message
);




if (
result.rc.ToString
() == "0")




{





//Add service






result =
client.addservice
("s1",null,"10.101.0.1",servicetypeEnum.HTTP,80,








0xFFFFFFFF,cachtypeEnum.VALNOTSET,








enabledisabledEnum.VALNOTSET
);





Console.WriteLine
("add service s1 : " +
result.message
);





// Modify service s1





result =
client.setservice_maxreq
("s1",50);





Console.WriteLine
("set service
maxReq

: " +
result.message
);






result =
client.bindlbmonitor_service
("http","s1",enabledisabledEnum.ENABLED,50);





Console.WriteLine
("bind monitor s1 : "+
result.message
);





result =
client.logout
();





Console.WriteLine
("logout : " +
result.message
);




}

SOAP Client Development

With Java

36

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Download Sun JDK 1.4.2 (
j2sdk1.4.2_04
) or above from Sun site



Download Axis.1.3 (
axis
-
1_3
) or above from
http://ws.apache.org/axis/java/releases.html



Download xerces
-
2.5.0 (
xerces
-
2_5_0
) or above from
http://xerces.apache.org/



Download axis and
xerces

under j2sdk:


C:
\
j2sdk1.4.2_04


C:
\
j2sdk1.4.2_04
\
axis
-
1_3


C:
\
j2sdk1.4.2_04
\
xerces
-
2_5_0


Download the
NSConfig.wsdl

and
NSStat.wsdl

from NetScaler


37

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach


Use the makesamp.bat file


Modify the JDK_HOME,AXIS_HOME and XERCES_HOME.


Change the application name. see setConfig.java


C:> makesamp.bat


This will generate client stub and compile the application



38

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.


Use run.bat to run client Application


Modify the JDK_HOME,AXIS_HOME and XERCES_HOME.


Change in the application name and IP address


C:> run.bat


39

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.

40

© 2007 Citrix Systems, Inc.


All rights reserved

Step
-
by
-
Step approach, cont.


Some times there are issues that can be resoled by making
sure that what we are passing is the correct variable while
making API call to NS.


If you get some error while compiling the java
config

files,
look for that variable’s
requiremnets

under
..
\
apidoc
\
docs
\
samples
\
java
\
NSConfig
\
Service.java
. For ex,
to find the error while calling service names, look in
samples
\
java
\
NSConfig
\
Service.java


Download new
wsdl

file for any build above 7.0_50. There
is major change between before and after 7.0_50.

41

© 2007 Citrix Systems, Inc.


All rights reserved

makesamp.bat

@echo off

set JAVA_HOME=C:
\
j2sdk1.4.2_08

set JDK_HOME=C:
\
j2sdk1.4.2_08

set AXIS_HOME=C:
\
j2sdk1.4.2_08
\
axis
-
1_3

set XERCES_HOME=C:
\
j2sdk1.4.2_08
\
xerces
-
2_5_0

set CP=%CLASSPATH%;.;%AXIS_HOME%
\
lib
\
axis
-
ant.jar;%AXIS_HOME%
\
lib
\
axis.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
commons
-
discovery
-
0.2.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
commons
-
logging
-
1.0.4.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
jaxrpc.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
log4j
-
1.2.8.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
saaj.jar

set CP=%CP%;%AXIS_HOME%
\
lib
\
wsdl4j
-
1.5.1.jar


set CP=%CP%;%XERCES_HOME%
\
xercesImpl.jar

set CP=%CP%;%XERCES_HOME%
\
xercesSamples.jar

set CP=%CP%;%XERCES_HOME%
\
xml
-
apis.jar

set CP=%CP%;%XERCES_HOME%
\
xmlParserAPIs.jar


rem

Generate the java class files from
wsdl

file.

rm

-
rf

NSConfig

java
-
cp %CP% org.apache.axis.wsdl.WSDL2Java
NSConfig.wsdl

rem

java
-
cp %CP% org.apache.axis.wsdl.WSDL2Java
NSStat.wsdl


rem

Compile the java files.

cp
setConfig.java

NSConfig

cp
rmConfig.java

NSConfig

cp
getConfig.java

NSConfig

rem

cp
getStat.java

NSConfig

%JDK_HOME%
\
bin
\
javac

-
classpath

%CP%
NSConfig
\
*.java



42

© 2007 Citrix Systems, Inc.


All rights reserved

Make file tricks


javac compiler has limitation on the number of files
that can be specified in one go


javac NSConfig
\
*.java command may give an “out
of memory” error


To overcome this specify the files in multiple
commands. e.g. compile all files starting with a
letter in one command


javac NSConfig
\
A*.java


javac NSConfig
\
B*.java


etc.


Developers using tools like JBuilder, NetBeans etc.
wont run into this issue

43

© 2007 Citrix Systems, Inc.


All rights reserved

Java Sample Code

public class
setConfig


{


public static void main(String[]
args
)


{


String
soap_server
;


String username;


String password ;


NSConfigBindingStub

client ;


SimpleResult

result;


NSConfig.Service

svr
;


UnsignedInt

NULL_UINT=null;


soap_server

=
args
[0];


username =
args
[1];


password =
args
[2];



try {



// Initialized the client stub



soap_server

=
soap_server

+ "/soap";



System.out.println
("Connecting to “ +
soap_server

+ " ........");



client = new
NSConfigBindingStub
(new URL(
soap_server
), null);



// This line is required to handle the authentication cookie.



client.setMaintainSession
(true);



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

44

© 2007 Citrix Systems, Inc.


All rights reserved

Java Sample Code


//Login


result =
client.login
(username, password);


System.out.println
("Login : “ +
result.getMessage
());


// add service s1


result =
client.addservice
("s1",null,"10.101.0.1",(
ServicetypeEnum
)
ServicetypeEnum.HTTP,new

UnsignedInt
(80),





null, (
CachtypeEnum
)
CachtypeEnum.
VALNOTSET
,




(
EnabledisabledEnum
)
EnabledisabledEnum.VALNOTSET
);



System.out.println
("add service s1 : " +
result.getMessage
());


// set service


result =
client.setservice_maxreq
("s1", new
UnsignedInt
(50));


System.out.println
("set service
maxReq

: " +
result.getMessage
());



result =
client.bindlbmonitor_service
("http", "s1", (
EnabledisabledEnum
)
EnabledisabledEnum.ENABLED,new

UnsignedInt
(10));


System.out.println
("bind monitor s1 : "+
result.getMessage
());


// Logout


result =
client.logout
();


System.out.println
("logout : " +
result.getMessage
());



}


catch (Exception ex)


{



ex.printStackTrace
();


}


}

}

SOAP Client Development

With Perl

46

© 2007 Citrix Systems, Inc.


All rights reserved

Soap Client Development


Download and install Perl 5.6 or above


Install Soap::Lite


Use the perl shell or PPM (It will install the all
dependency also)


Write the client application (see the sample )


Login


Commands


Logout


Run the client Application

47

© 2007 Citrix Systems, Inc.


All rights reserved

48

© 2007 Citrix Systems, Inc.


All rights reserved

Perl Sample Code

use SOAP::Lite;




import SOAP::Data 'name';

use HTTP::Cookies;

// This line is for handling cookie based authentication

my $cookies = HTTP::Cookies
-
>new(ignore_discard => 1, hide_cookie2 => 1);

my $soap = SOAP::Lite


# service URI and cookie object


-
> proxy("${NS}/soap", cookie_jar=>$cookies) ;


my $result = $soap
-
>login( name('username'=>$username),





name('password'=>$password) )
-
>result;

print $result
-
>{'message'} . "
\
n";


# Add some services

print "add service s1: ";

$result = $soap
-
>addservice( name('name' => 's1'), name('IP' => '10.1.1.11'), name('servicetype' => 'http'),


name('port' => '80
') )


-
>result;

print $result
-
>{'message'} . "
\
n";


print "set service s1: ";

$result = $soap
-
>setservice( name('name' => 's1'), name('cacheable' => 'YES') )


-
>result;

print $result
-
>{'message'} . "
\
n";


# Logout

print "logout: ";

$result = $soap
-
>logout()
-
>result;

print $result
-
>{'message'} . "
\
n";


exit;


49

© 2007 Citrix Systems, Inc.


All rights reserved

Filtering WSDL


The full configuration WSDL contains over 1200 method
descriptions and growing with every release


The time taken to load the generated client stubs can be
substantial in some languages like C#


genAPI / filterwsdl tool can be used to generate a smaller WSDL
containing only the methods used in the client applications.


genAPI will be deprecated soon as it is tightly coupled with the
NetScaler release


genAPI for windows is not available from 7.0 onwards


FilterWSDL


the replacement tool for genAPI will be available for
FreeBSD and Windows across NetScaler releases


Questions