NetScaler XML API

1. NetScaler XML API Module 22-00 Citrix NetScaler Basic Operations and Administration NS-BOA Citrix Technical Product Training

2. Topics Overview Communications Perl WSDL Files Building a Script Considerations Extras Samples

3. Overview - Description Description The XML API provides a framework for building custom interfaces for configuring & monitoring a CNAS The API supports custom applications built within C, C#, Java and Perl Relies upon Simple Object Access Protocol (SOAP) to communicate over HTTP with the CNAS Corresponds closely to the NetScaler CLI syntax

4. Overview - Communications Communication with the CNAS; The message path 1. XML API based client application generates an XML formatted config or stat command and sends to the CNAS via HTTP after encapsulating in a SOAP envelope.. 3. HTTP daemon with a SOAP handler receives the SOAP envelope. 2. SOAP handler pulls out the XML formatted command and passes it to the NetScaler kernel. 3. Kernel receives command, processes it, and formats an XML response. 4. Kernel then passes the XML response to the SOAP handler. 5. After re-encapsulating the XML response, the SOAP handler passes it back out and it is returned to client via HTTP. 6. Client application receives response, strips the XML response from the SOAP envelope and acts upon it.1. XML API based client application generates an XML formatted config or stat command and sends to the CNAS via HTTP after encapsulating in a SOAP envelope.. 3. HTTP daemon with a SOAP handler receives the SOAP envelope. 2. SOAP handler pulls out the XML formatted command and passes it to the NetScaler kernel. 3. Kernel receives command, processes it, and formats an XML response. 4. Kernel then passes the XML response to the SOAP handler. 5. After re-encapsulating the XML response, the SOAP handler passes it back out and it is returned to client via HTTP. 6. Client application receives response, strips the XML response from the SOAP envelope and acts upon it.

5. Overview - Pieces Two different system interfaces System commands -> NSConfig.wsdl Covers all system configuration possibilities Very large file � can take 5 minutes or more to parse into your app Can be trimmed according to need using genAPI* System statistics -> NSStat.wsdl (new with 6.1) Allows access to all of the system statistic counters Much smaller, time to parse is minimal What�s a WSDL? Web Service Description Language Simplistically in the NS case, it defines the functions that the NetScaler interfaces have *More on genAPI coming�.. Note that the NS WSDLs are rebuilt with every new build. Usually the changes are insignificant, but be aware and watch for changes. Major system revs will impart substantially more changes to the WSDLs. New features = new commands & new stats!*More on genAPI coming�.. Note that the NS WSDLs are rebuilt with every new build. Usually the changes are insignificant, but be aware and watch for changes. Major system revs will impart substantially more changes to the WSDLs. New features = new commands & new stats!

6. Using XML API with Perl What you�ll need: A workstation (Windows, Linux, or FreeBSD) Perl (of course!), version 5.8 recommended v6 not validated yet A few Perl modules SOAP::Lite � for SOAP support HTTP::Cookies � for cookie authentication req�d by the CNAS NetScaler WSDLs NSConfig.wsdl: http://yourNSIP/api/NSConfig.wsdl NSStat.wsdl: http://yourNSIP/api/NSStat.wsdl (6.1 only) NetScaler example scripts Can be downloaded from ftp.netscaler.com or netssure.netscaler.com genAPI Provided with the NS example scripts

7. Prepping the WSDLs Using genAPI Pick the elements from the WSDL that will be used by the script(s) Run genAPI on the full WSDL file locally, outputting over the WSDL (make a copy of it first) genapi.exe NSConfig �add lb vserver� �show lb vserver� �rm lb vserver� �save ns config� Edit the new NSConfig.wsdl with the NSIP address of your CNAS per the instructions in the readme Put the WSDL in the script/app working directory The WSDL file doesn�t have to be local to the script/app. If you want to access it over HTTP, FTP, SSH, etc, you�ll need to use the appropriate perl modules genAPI comes with the ns-gsoap-sample-xxx tar/zip files. Technically these are the C example bundles but you can use genAPI regardless of language you are working in.genAPI comes with the ns-gsoap-sample-xxx tar/zip files. Technically these are the C example bundles but you can use genAPI regardless of language you are working in.

8. Building a script A basic script outline � what the samples do Define needed modules � SOAP::Lite & HTTP::Cookies Define the WSDL to use Capture the login parameters Setup the cookie auth event Setup the SOAP object Login Run CNAS commands Logout skel.pl can be used as a starting point if desired. It�s perl, so there�s always more than one way to do it BUT you�ll always need to include these steps, however you script it

9. Using the WSDL Objects Every nscli command equivalent is issued much like a function call Pass in the command parameters accordingly login (name (�username� => �nsroot�), name (�password� => �nsroot�) );

10. Other Considerations Dealing with CNAS feedback Be sure to allow for both expected output and (unexpected) error messages When issuing any changes, don�t forget to issue save config habitually savensconfig() Selecting a user for XML API access Want to use nsroot? Use another specific system user? Be sure to apply an RBA policy accordingly

11. Extras Secure communication based on NSIP Set up a loopback ssl service with certificate and a monitor > add service secure_xmlaccess 127.0.0.1 SSL 443 -clearTextPort 80 > add certkey cert1 �cert /nsconfig/ssl/ssl/cert1024.pem �key /nsconfig/ssl/ssl/rsakey.pem > bind certkey secure_xmlaccess cert1 -service > add monitor ssl_mon TCP -destport 80 > bind monitor ssl_mon secure_xmlaccess You will still access the CNAS in your app/script via the NSIP

12. Extras Secure access via a different IP Create an SSL vserver with an IP on another subnet the CNAS can reach > add vserver XMLAPI_VIP SSL 10.250.1.5 443 > add service XMLAPI_SVC 127.0.0.1 HTTP 80 > bind lb vserver XMLAPI_VIP XMLAPI_SVC > add certkey cert1 �cert /nsconfig/ssl/ssl/cert1024.pem �key /nsconfig/ssl/ssl/rsakey.pem > bind certkey XMLAPI_VIP cert1 Access the CNAS in this case though the vserver�s IP address rather than the NSIP May be more amenable to certain configs

13. Sample - skel.pl - 1 of 4 #usr/bin/perl -w use SOAP::Lite; # troubleshoot: append: +trace=>"debug"; import SOAP::Data 'name'; # to set data values (q.v.) use HTTP::Cookies; # server uses client cookie for auth ## BEGIN CONFIGURATION. ######################################################################## # YOU NEED TO MODIFY THE WSDL FILE AT THE BOTTOM WHERE IT SAYS: # location="http://$NetScaler/soap/" # TO: # location="http://10.10.10.10/soap/" # SUBSTITUTE YOUR NS IP ADDRESS FOR 10.10.10.10. ######################################################################## # Point to the WSDL file my $WSDL = "file:./NSConfig.wsdl"; ## END CONFIGURATION. Code starts.

14. Sample - skel.pl - 2 of 4 # Command-line parameters: <NS IP> <username> <password> my $NS = shift @ARGV; $NS = "localhost" if (!$NS); my $username = shift @ARGV; $username = "nsroot" if (!$username); my $password = shift @ARGV; $password = "nsroot" if (!$password); # Cookie object. Server sends cookie for client authentication. my $cookies = HTTP::Cookies->new(ignore_discard => 1, hide_cookie2 => 1); # Create the soap object my $soap = SOAP::Lite # wsdl location (can be fs, http, ftp, etc.) -> service($WSDL) # service URI and cookie object -> proxy("http://${NS}/soap", cookie_jar=>$cookies) ;

15. Sample - skel.pl - 3 of 4 # Log on print "login: "; my $result = $soap->login( name('username'=>$username), name('password'=>$password) ) ; print $result->{'message'} . "\n"; ## Put your actions here ## ## End your actions ## # Logout print "logout: "; $result = $soap->logout(); print $result->{'message'} . "\n"; exit;

16. Sample - skel.pl - 3 of 4 ##### ##### Pre-builts: Copy into program before logout action & remove comment ##### delimiters ##### save config action #### # print "save ns config: "; # $result = $soap->savensconfig(); # print $result->{'message'} . "\n";