Citrix NetScaler Developer's Guide - Citrix Knowledge Center

ContentsPreface....................................................................................................7Formatting Conventions for NetScaler Documentation ......................................7Documentation Available on the NetScaler Appliance .......................................8Getting Service and Support ..................................................................9NetScaler Documentation Feedback .........................................................91 Introduction to the API...............................................................................11Hardware and Software Requirements......................................................12API Architecture .............................................................................12The NSConfig Interface ......................................................................13Examples of API Usage .....................................................................14Example: Setting the Configuration ....................................................15Example: Querying the Configuration ..................................................152 The Web Service Definition Language (WSDL) ...................................................17Creating Client Applications with the NSConfig.wsdl File ..................................18Filter WSDL ..................................................................................193 Securing API Access ................................................................................21To configure secure API access based on the NetScaler IP................................22To configure secure API access based on the subnet IP...................................22v

Contentsvi

PrefaceLearn about the Citrix ® NetScaler ® collection of documentation, including informationabout support options and ways to send us feedback.In This Preface:• Formatting Conventions for NetScaler Documentation• Documentation Available on the NetScaler Appliance• Getting Service and Support• NetScaler Documentation FeedbackFor information about new features and enhancements for this release, see the CitrixNetScaler 9.3 Release Notes at http://support.citrix.com/article/CTX128669.Formatting Conventions for NetScalerDocumentationThe NetScaler documentation uses the following formatting conventions.Table 1. Formatting ConventionsConventionBoldfaceMonospaceMeaningIn text paragraphs or steps in aprocedure, information that you typeexactly as shown (user input), or anelement in the user interface.Text that appears in a command-lineinterface. Used for examples ofcommand-line procedures. Also used todistinguish interface terms, such asnames of directories and files, fromordinary text.A term enclosed in angle brackets is avariable placeholder, to be replaced withan appropriate value. Do not enter theangle brackets.[ brackets ] Optional items in command statements.For example, in the following command,[ -range ] means that7

PrefaceConventionMeaningyou have the option of entering a range,but it is not required:add lb vserver [ -range]Do not type the brackets themselves.| (vertical bar) A separator between options in braces orbrackets in command statements. Forexample, the following indicates thatyou choose one of the following loadbalancing methods: = ( ROUNDROBIN |LEASTCONNECTION |LEASTRESPONSETIME | URLHASH |DOMAINHASH | DESTINATIONIPHASH |SOURCEIPHASH | SRCIPDESTIPHASH |LEASTBANDWIDTH | LEASTPACKETS |TOKEN | SRCIPSRCPORTHASH | LRTM |CALLIDHASH | CUSTOMLOAD )… (ellipsis)You can repeat the previous item oritems in command statements. Forexample, /route:[ ,…]means you can type additional separated by commas.Documentation Available on the NetScalerApplianceA complete set of Citrix ® NetScaler ® documentation (PDF format) is available on theDocumentation tab of your NetScaler appliance and from http://support.citrix.com/.(Most of the documents require Adobe Reader, available at http://adobe.com/.)To view the documentation1. From a Web browser, log on to the NetScaler.2. Click the Documentation tab.3. To view a short description of each document, hover your cursor over the title. Toopen a document, click the title.8

Citrix NetScaler Developer's GuideGetting Service and SupportCitrix ® offers a variety of resources for support with your Citrix environment, includingthe following:• The Knowledge Center is a self-service, Web-based technical support database thatcontains thousands of technical solutions, including access to the latest hotfixes,service packs, and security bulletins.• Technical Support Programs for both software support and appliance maintenanceare available at a variety of support levels.• The Subscription Advantage program is a one-year membership that gives you aneasy way to stay current with the latest product version upgrades and enhancements.• Citrix Education provides official training and certification programs on virtually allCitrix products and technologies.For more information about Citrix services and support, see the Citrix Systems SupportWeb site at http://www.citrix.com/lang/English/support.asp.You can also participate in and follow technical discussions offered by the experts onvarious Citrix products at the following sites:• http://community.citrix.com• http://twitter.com/citrixsupportNetScaler Documentation FeedbackYou are encouraged to provide feedback and suggestions so that we can enhance thedocumentation. You can send email to nsdocs_feedback@citrix.com. In the subjectline, specify "Documentation Feedback." Please include the title of the guide and thepage number in the email message.You can also provide feedback through the Knowledge Center at http://support.citrix.com/.To provide feedback at the Knowledge Center home page1. Go to the Knowledge Center home page at http://support.citrix.com/.2. On the Knowledge Center home page, under Products, expand NetScaler, and thenclick the NetScaler release for which you want to provide feedback.3. On the Documentation tab, click the guide name, and then click Article Feedback.4. On the Documentation Feedback page, complete the form, and then click Submit.9

10Preface

Citrix NetScaler Developer's GuideExample: Setting the ConfigurationThis example shows a CLI command, the corresponding API method, the resulting XMLrequest, and the XML response that is sent back to the client.Note: The actual API method and the XML SOAP message contents may differ fromthe example shown below. The XML shown will be encased in a SOAP envelope,which will in turn be carried in an HTTP message. For more information, see the W3Cweb site at http://www.w3.org/TR/SOAP.The following CLI command creates a Load Balancing virtual server:> add lb vserver vipLB1 HTTP 10.100.101.1 80Following is the corresponding API method:> ns__addlbvserver (handle, “vipLB1”, “HTTP”, “10.100.101.1”, 80, &out);The XML generated for this request is as follows.vipLB1

Chapter 1Introduction to the APIPersistence: NONE2) vipLB2 (10.100.101.2:80) - HTTP Type: ADDRESS State:DOWNMethod: LEASTCONNECTION Mode: IPPersistence: NONEDoneFollowing is the corresponding API method to show the list of Load Balancing virtualservers.ns__getlbvserver(handle, NULL, &out)The XML generated for this request is as follows.The XML response to the above request is as follows.0DoneHTTPvipLB210.100.101.28016

Chapter 2The Web Service Definition Language(WSDL)Topics:• Creating Client Applicationswith the NSConfig.wsdl File• Filter WSDLThe NetScaler WSDL describes services for the entire range ofNetScaler services. The NetScaler provides two WSDL files:NSConfig.wsdlConfiguration APIs are defined in this file. TheNSConfig.wsdl file is found on the NetScaler at http:///api/NSConfig.wsdl, where is the IPaddress of your NetScaler. This file is much larger than theNSStat.wsdl file. With the help of a third-party tool (suchas gSOAP), developers can use this file to generate clientstubs. A custom application can then call the stubs to sendrequests to the NetScaler. The application can be in anystandard programming language that is supported by thethird-party tool. Common programming languages for thispurpose include Perl, Java, C, and C#. You can use thefilterwsdl command to select only the service definitionsthat are relevant to the API calls made in your script.NSStat.wsdlStatistical APIs are defined in this file. The NSStat.wsdlfile is found on the NetScaler at http:///api/NSStat.wsdl, where is the IP address of yourNetScaler.17

Chapter 2The Web Service Definition Language (WSDL)Creating Client Applications with theNSConfig.wsdl File18A client application can be created by importing the NSConfig.wsdl file with thegSOAP WSDL Importer to create a header file with C or C++ declarations of the SOAPmethods. The gSOAP compiler is then used to translate this header file into stubs forthe client application.1. Get the NSConfig.h header file from the WSDL file.a. Run the wsdl2h program that comes with gSOAP on the WSDL file.The wsdl2h program is in the following location.> ./wsdl2h NSConfig.wsdlThe output of wsdl2h is as follows:** The gSOAP WSDL parser for C and C++ 1.0.2** Copyright (C) 2001-2004 Robert van Engelen, Genivia,Inc.** All Rights Reserved. This product is provided "as is",without any warranty.Saving NSConfig.hReading file 'NSConfig.wsdl'Cannot open file 'typemap.dat'Problem reading type map file typemap.dat.Using internal type definitions for C instead.b. Run the soapcpp2 program to compile the header file and complete theprocess, as shown below.> soapcpp2 NSConfig.h2. Generate the XML files and stubs as follows:> ./soapcpp2 -c -i NSConfig.hFollowing is sample output for this command:** The gSOAP Stub and Skeleton Compiler for C and C++ 2.4.1** Copyright (C) 2001-2004 Robert van Engelen, Genivia, Inc.** All Rights Reserved. This product is provided "as is",without any warranty.Saving soapStub.hSaving soapH.hSaving soapC.cSaving soapClient.cSaving soapServer.cSaving soapClientLib.cSaving soapServerLib.cUsing ns1 service name: NSConfigBindingUsing ns1 service location: http://NetScaler.com/api Using ns1schema namespace: urn:NSConfigSaving soapNSConfigBindingProxy.h client proxySaving soapNSConfigBindingObject.h server objectSaving NSConfigBinding.addserver.req.xml sample SOAP/XML

Citrix NetScaler Developer's GuideFilter WSDLrequestSaving NSConfigBinding.addserver.res.xml sample SOAP/XMLresponseSaving NSConfigBinding.disableserver.req.xml sample SOAP/ XMLrequestSaving NSConfigBinding.disableserver.res.xml sample SOAP/ XMLresponseSaving NSConfigBinding.enableserver.req.xml sample SOAP/ XMLrequestSaving NSConfigBinding.enableserver.res.xml sample SOAP/ XMLresponse[ ... Similar lines clipped ... ]Saving NSConfigBinding.nsmap namespace mapping tableCompilation successfulThis creates the stub files soapC.c, soapClient.c and stdsoap2.c.3. Link the stub files you created with your source code to create a stand-alonebinary that invokes the API.The NetScaler WSDL describes services for the entire range of NetScaler services. Whenyou use the NetScaler API in your scripts, by linking to the WSDL and attempting tocompile the application, the entire WSDL is included, unnecessarily increasingcompilation time and the size of the program.Filter WSDL is a tool for selecting only those service definitions from the NetScalerWSDL that are relevant to the API calls made in the script. You can use the filter WSDLtool to filter NSConfig.wsdl and NSStat.wsdl files.The NetScaler provides two WSDL files, one for the configuration APIs(NSConfig.wsdl) and the other for statistical APIs (NSStat.wsdl). The WSDL file forthe configuration API is much larger. Therefore, it is important to use filter WSDL whencompiling programs written with the configuration API.Filter WSDL is a program that works on the Windows, FreeBSD and Linux platforms, andit can be run from the CLI.The syntax for running filter WSDL is as follows:filterwsdl where:fromwsdl = The wsdl file that you want to filterpattern = API method names or patterns that should be filteredFor example, if you want to filter all the service definitions for the API methodaddlbvserver from the NetScaler WSDL file, NSConfig.wsdl, you can use the command:> filterwsdl NSConfig.wsdl "addlbvserver"The output of this command is sent to the screen by default, but it can be redirectedto a file on the NetScaler by using the UNIX redirect operator (>). The output of the19

Chapter 2The Web Service Definition Language (WSDL)previous command can be saved into a file called NSConfig-Custom.wsdl by usingthe command as follows:> filterwsdl NSConfig.wsdl "addlbvserver" > NSConfig-Custom.wsdlIn this case, the original WSDL file is 1.58 MB, but the filtered WSDL file is 6 KB.The pattern used in the filterwsdl command can include the + and - operators and thewildcard operator (*) to create more generic filters.For example, if you want to filter the service definitions for all the available loadbalancing methods, you can use the following command:> filterwsdl NSConfig.wsdl "*lb"*This command will filter all the Load Balancing methods but will also include GSLBmethods, because the pattern lb will be matched by all GSLB methods also. To includeonly LB methods and exclude all GSLB methods, use the command as follows:> filterwsdl NSConfig.wsdl +"*lb" -"glsb"*20

Chapter 3Securing API AccessTopics:• To configure secure APIaccess based on theNetScaler IP• To configure secure APIaccess based on the subnet IPSecure access to CLI objects can be based on the NetScaler IPaddress or on the subnet IP address on which the NetScaler isdeployed. To provide secured API access based on theNetScaler IP address, you must configure the NetScaler to usetransparent SSL mode with clear text port.21

Chapter 3Securing API AccessTo configure secure API access based on theNetScaler IP1. Create a loopback SSL service and configure it use transparent SSL mode with cleartext port:add service secure_xmlaccess 127.0.0.1 SSL 443 -clearTextPort 802. Add certificate and key:add certkey cert1 –cert /nsconfig/ssl/ssl/cert1024.pem –key /nsconfig/ssl/ssl/rsakey.pemNote: You can use an existing certificate and key or use the NetScaler CertificateAuthority Tool to create a key and test certificate for secure access.3. Bind the certificate and key to the service:bind certkey secure_xmlaccess cert1 -Service4. Add a custom TCP monitor to monitor the SSL service you have added:add monitor ssl_mon TCP -destport 805. Bind the custom TCP monitor to the SSL service:bind monitor ssl_mon secure_xmlaccessTo configure secure API access based on thesubnet IP1. Create an SSL VIP in the appropriate subnet:add vserver SSL 4432. Create a loopback HTTP service:add service 127.0.0.1 HTTP 803. Bind the service to the SSL VIP:bind lb vserver 4. Add the certificate and the key:22

Citrix NetScaler Developer's Guideadd certkey cert1 –cert /nsconfig/ssl/ssl/cert1024.pem –key /nsconfig/ssl/ssl/rsakey.pemNote: You can use an existing certificate and key or use the NetScaler CertificateAuthority Tool to create a key and test certificate.5. Bind the Certificate and the Key to the SSL VIP:bind certkey cert123