NetScaler Developers Guide

7/21/2019 NetScaler Developers Guide

1/22

Citrix NetScaler 9.1

Citrix NetScalerDevelopers Guide


2/22

Copyright and Trademark Notice

CITRIX SYSTEMS, INC., 2009. ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED ORTRANSMITTED IN ANY FORM OR BY ANY MEANS OR USED TO MAKE DERIVATIVE WORK (SUCH AS TRANSLATION,TRANSFORMATION, OR ADAPTATION) WITHOUT THE EXPRESS WRITTEN PERMISSION OF CITRIX SYSTEMS, INC.

ALTHOUGH THE MATERIAL PRESENTED IN THIS DOCUMENT IS BELIEVED TO BE ACCURATE, IT IS PRESENTEDWITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE ALL RESPONSIBILITY FOR THE USEOR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS MANUAL.

CITRIX SYSTEMS, INC. OR ITS SUPPLIERS DO NOT ASSUME ANY LIABILITY THAT MAY OCCUR DUE TO THE USE ORAPPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS DOCUMENT. INFORMATION IN THIS DOCUMENT IS SUBJECTTO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN EXAMPLES ARE FICTITIOUS UNLESSOTHERWISE NOTED.

The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limitsfor a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection againstharmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio-frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radiocommunications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will berequired to correct the interference at their own expense.

Modifying the equipment without Citrix' written authorization may result in the equipment no longer complying with FCC requirementsfor Class A digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required tocorrect any interference to radio or television communications at your own expense.

You can determine whether your equipment is causing interference by turning it off. If the interference stops, it was probably caused bythe NetScaler Request Switch 9000 Series equipment. If the NetScaler equipment causes interference, try to correct the interference byusing one or more of the following measures:

Move the NetScaler equipment to one side or the other of your equipment.

Move the NetScaler equipment farther away from your equipment.

Plug the NetScaler equipment into an outlet on a different circuit from your equipment. (Make sure the NetScaler equipment and yourequipment are on circuits controlled by different circuit breakers or fuses.)

Modifications to this product not authorized by Citrix Systems, Inc., could void the FCC approval and negate your authority to operate theproduct.

BroadCom is a registered trademark of BroadCom Corporation. Fast Ramp, NetScaler, and NetScaler Request Switch are trademarks ofCitrix Systems, Inc. Linux is a registered trademark of Linus Torvalds. Internet Explorer, Microsoft, PowerPoint, Windows and Windows

product names such as Windows NT are trademarks or registered trademarks of the Microsoft Corporation. NetScape is a registered

trademark of Netscape Communications Corporation. Red Hat is a trademark of Red Hat, Inc. Sun and Sun Microsystems are registeredtrademarks of Sun Microsystems, Inc. Other brand and product names may be registered trademarks or trademarks of their respectiveholders.

Software covered by the following third party copyrights may be included with this product and will also be subject to the software licenseagreement: Copyright 1998 Carnegie Mellon University. All rights reserved. Copyright David L. Mills 1993, 1994. Copyright 1992, 1993, 1994, 1997 Henry Spencer. Copyright Jean-loup Gailly and Mark Adler. Copyright 1999, 2000 by Jef Poskanzer. Allrights reserved. Copyright Markus Friedl, Theo de Raadt, Niels Provos, Dug Song, Aaron Campbell, Damien Miller, Kevin Steves. Allrights reserved. Copyright 1982, 1985, 1986, 1988-1991, 1993 Regents of the University of California. All rights reserved. Copyright 1995 Tatu Ylonen, Espoo, Finland. All rights reserved. Copyright UNIX System Laboratories, Inc. Copyright 2001 Mark R VMurray. Copyright 1995-1998 Eric Young. Copyright 1995,1996,1997,1998. Lars Fenneberg. Copyright 1992. LivingstonEnterprises, Inc. Copyright 1992, 1993, 1994, 1995. The Regents of the University of Michigan and Merit Network, Inc. Copyright 1991-2, RSA Data Security, Inc. Created 1991. Copyright 1998 Juniper Networks, Inc. All rights reserved. Copyright 2001, 2002

Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 1999-2001 The Open LDAP Foundation. All Rights Reserved. Copyright 1999 Andrzej Bialecki. All rights reserved. Copyright 2000The Apache Software Foundation. All rights reserved. Copyright (C) 2001-2003 Robert A. van Engelen, Genivia inc. All Rights

Reserved. Copyright (c) 1997-2004 University of Cambridge. All rights reserved. Copyright (c) 1995. David Greenman. Copyright (c)2001 Jonathan Lemon. All rights reserved. Copyright (c) 1997, 1998, 1999. Bill Paul. All rights reserved. Copyright (c) 1994-1997 MattThomas. All rights reserved. Copyright 2000 Jason L. Wright. Copyright 2000 Theo de Raadt. Copyright 2001 Patrik Lindergren.All rights reserved.

Last Updated: June 2009


3/22

CONTENTS

Contents

Preface

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v

New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viAudience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Formatting Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Knowledge Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Silver and Gold Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Subscription Advantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Education and Training. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x

Chapter 1 API Reference

Introduction to the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Benefits of API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Hardware and Software Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Interface Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

The NSConfig Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Examples of API Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Example: Setting the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Example: Querying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

The Web Service Definition Language (WSDL). . . . . . . . . . . . . . . . . . . . . . . . . . .19Creating Client Applications Using the NSConfig.wsdl File. . . . . . . . . . . . . . .19

Filter WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Securing API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22


4/22

iv Citr ix NetSc aler Dev eloper s Gui de


5/22

PREFACE

Preface

Before you begin to develop actions for the NetScaler, take a few minutes toreview this chapter and learn about related documentation, other support options,

and ways to send us feedback.In This Preface

About This Guide

New in This Release

Audience

Formatting Conventions

Related Documentation

Getting Service and Support

Documentation Feedback

About This GuideThis guide introduces you to the NetScaler developer Application ProgrammingInterface (API). You can use the NetScaler API to program interaction with the

NetScaler into your own custom application.

Every command on the NetScaler has an equivalent function in the API and sothe API provides you with a powerful, extensive tool to script applications with.

This guide provides the following information:

Chapter 1, API Reference. An overview of the Citrix NetScaler API

reference functions and how they are used to create a custom application.


6/22

vi Citr ix NetSc aler Dev eloper s Gui de

New in This ReleaseNetScaler 9.1 nCore Technology is a new software release that uses CPU coresfor packet handling and greatly improves the performance of many NetScalerfeatures. NetScaler 9.1 nCore supports features in this guide unless specifiedotherwise. For a summary of the features that are not supported in NetScaler 9.1nCore, see the Citrix NetScaler 9.1 and NetScaler 9.1 nCore Release Notes.

AudienceThis guide is intended for the following audience:

Network administrators

Application programmers

The concepts and tasks described in this guide require you to have a basicunderstanding of the NetScaler configuration and also a good understanding ofusing an API to develop custom applications or scripts.

Formatting ConventionsThis documentation uses the following formatting conventions.


Convention Meaning

Boldface Information that you type exactly as shown (user input);elements in the user interface.

Italics Placeholders for information or parameters that youprovide. For example, FileNamein a command means youtype the actual name of a file. Also, new terms, and wordsreferred to as words (which would otherwise be enclosed inquotation marks).

%SystemRoot% The Windows system directory, which can be WTSRV,WINNT, WINDOWS, or any other name you specify whenyou install Windows.

Monospace System output or characters in a command line. User inputand placeholders also are formatted using monspace text.

{ braces } A series of items, one of which is required in commandstatements. For example, { yes | no }means you must typeyesor no. Do not type the braces themselves.


7/22

Preface vii

Related DocumentationA complete set of documentation is available on the Documentationtab of your

NetScaler and from http://support.citrix.com/. (Most of the documents requireAdobe Reader, available at http://adobe.com/.)

To view the documentation

1. From a Web browser, log on to the NetScaler.

2. Click the Documentationtab.

3. To view a short description of each document, hover your cursor over thetitle. To open a document, click the title.

Getting Service and SupportCitrix provides technical support primarily through the Citrix Solutions Network(CSN). Our CSN partners are trained and authorized to provide a high level ofsupport to our customers. Contact your supplier for first-line support, or check foryour nearest CSN partner at http://support.citrix.com/.

[ brackets ] Optional items in command statements. For example, inthe following command, [ - r angepositiveInteger] means that you have the option ofentering a range, but it is not required:

add lb vserver nameserviceTypeIPAddress

port[-range positiveInteger]

Do not type the brackets themselves.

| (vertical bar) A separator between options in braces or brackets incommand statements. For example, the following indicatesthat you choose one of the following load balancingmethods:

lbMethod= ( ROUNDROBIN | LEASTCONNECTION | LEASTRESPONSETIME | URLHASH | DOMAINHASH | DESTINATIONIPHASH | SOURCEIPHASH | SRCIPDESTIPHASH | LEASTBANDWIDTH | LEASTPACKETS | TOKEN | SRCIPSRCPORTHASH | LRTM | CALLIDHASH | CUSTOMLOAD )

(ellipsis) You can repeat the previous item or items in commandstatements. For example,/route:DeviceName[,]meansyou can type additionalDeviceNamesseparated bycommas.


Convention Meaning


8/22

v ii i Ci tr ix NetScaler Developer s Gu ide

You can also get support from Citrix Customer Service at http://citrix.com/. Onthe Supportmenu, click Customer Service.

In addition to the CSN program and Citrix Customer Service, Citrix offers thefollowing support options for Citrix NetScaler.

Knowledge CenterThe Knowledge Center offers a variety of self-service, Web-based technicalsupport tools at http://support.citrix.com/.

Knowledge Center features include:

A knowledge base containing thousands of technical solutions to supportyour Citrix environment

An online product documentation library

Interactive support forums for every Citrix product

Access to the latest hotfixes and service packs

Knowledge Center Alerts that notify you when a topic is updated

Note: To set up an alert, sign in at http://support.citrix.com/and, underProducts, select a specific product. In the upper-right section of the screen,under Tools, click Add to your Hotfix Alerts. To remove an alert, go tothe Knowledge Center product and, under Tools, click Remove from yourHotfix Alerts.

Security bulletins

Online problem reporting and tracking (for organizations with valid supportcontracts)

Silver and Gold MaintenanceIn addition to the standard support options, Silver and Gold maintenance optionsare available. If you purchase either of these options, you receive documentationwith special Citrix Technical Support numbers you can call.

Silver Maintenance OptionThe Silver maintenance option provides unlimited system support for one year.This option provides basic coverage hours, one assigned support accountmanager for nontechnical relations management, four named contacts, andadvanced replacement for materials.


9/22

Preface ix

Technical support is available at the following times:

North America, Latin America, and the Caribbean: 8 A.M. to 9 P.M. U.S.Eastern Time, Monday through Friday

Asia (excluding Japan): 8 A.M. to 6 P.M. Hong Kong Time, Mondaythrough Friday

Australia and New Zealand: 8 A.M. to 6 P.M. Australian Eastern StandardTime (AEST), Monday through Friday

Europe, Middle East, and Africa: 8 A.M. to 6 P.M. Coordinated UniversalTime (Greenwich Mean Time), Monday through Friday

Gold Maintenance OptionThe Gold maintenance option provides unlimited system support for one year.Support is available 24 hours a day, 7 days a week. There is one assigned supportaccount manager for nontechnical relations management, and there are six namedcontacts.

Subscription AdvantageYour product includes a one-year membership in the Subscription Advantage

program. The Citrix Subscription Advantage program gives you an easy way tostay current with the latest software version and information for your Citrix

products. Not only do you get automatic access to download the latest featurereleases, software upgrades, and enhancements that become available during the

term of your membership, you also get priority access to important Citrixtechnology information.

You can find more information on the Citrix Web site athttp://www.citrix.com/(on the Supportmenu, click Subscription Advantage).

You can also contact your sales representative, Citrix Customer Care, or amember of the Citrix Solutions Advisors program for more information.

Education and TrainingCitrix offers a variety of instructor-led and Web-based training solutions.Instructor-led courses are offered through Citrix Authorized Learning Centers(CALCs). CALCs provide high-quality classroom learning using professional

courseware developed by Citrix. Many of these courses lead to certification.

Web-based training courses are available through CALCs, resellers, and from theCitrix Web site.

Information about programs and courseware for Citrix training and certification isavailable at http://www.citrixtraining.com .


10/22

x Citrix NetScaler Developers Guide

Documentation FeedbackYou are encouraged to provide feedback and suggestions so that we can enhancethe documentation. You can send email to the following alias or aliases, asappropriate. In the subject line, specify Documentation Feedback. Be sure toinclude the document name, page number, and product release version.

For NetScaler documentation, send email to [email protected].

For Command Center documentation, send email [email protected].

For Access Gateway documentation, send email [email protected].

You can also provide feedback from the Knowledge Center at http://support.citrix.com/.

To provide feedback from the Knowledge Center home page

1. Go to the Knowledge Center home page at http://support.citrix.com/.

2. On the Knowledge Center home page, under Products, expand NetScalerApplication Delivery, and click NetScaler Application DeliverySoftware 9.1.

3. On the Documentationtab, click the guide name, and then click ArticleFeedback.

4. On the Documentation Feedbackpage, complete the form and clickSubmit.


11/22

CHAPTER 1

API Reference

Developers and administrators can use the NetScaler Application ProgrammingInterface (API), nsconfig, to implement customized client applications. The

nsconfig API, which mirrors the NetScaler command line interface (CLI), isbased on the Web Services Description (WSDL) specification. It includes aFilterWSDL command to reduce compilation time and file size. You can secureyour API applications at the NetScaler IP address or at the IP address of the thesubnet on which the NetScaler is deployed.

Introduction to the APIThe NetScaler can be configured using an external Application ProgrammingInterface (API). The API allows programmatic communications between clientapplications and the NetScaler. This interface provides the means for a customclient application to configure and monitor the state of the NetScaler.

The API is based on the Simple Object Access Protocol (SOAP) over HTTP.SOAP is a transport protocol for exchanging information in a decentralized,distributed environment and enables you to write the business logic and schemafor facilitating business-to-business transactions over the Internet.

The NetScaler software contains a number of changes and enhancements to theAPI, including the following:

Add command.In 4.0.1, the addcommand contains only the requiredargument and optional argument. Neither can be modified by the set command.

Set command.In 4.0.1, all set commands take single arguments; these

commands take multiple arguments only in case of dependent arguments.In dependent arguments, the name of the first argument is assumed to be

part of the signature.

Bind and unbind commands.In 4.0.1, the bi ndand unbi ndcommandstreat dependent arguments exactly as set commands do.


12/22

13 Ci tr ix NetScaler Developer s Gu ide

Note: The NetScaler continues to accept and correctly process requests fromclients developed using previous versions of the API.

Benefits of APIThe following are the benefits of the API:

The API provides developers the advantage of controlling the NetScalerfrom a custom application. The API enables the client application toconfigure and monitor the NetScaler.

The interface allows the developers to easily and quickly develop clientapplications using a language and platform with which the developer iscomfortable.

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

Hardware and Software RequirementsTo work with the API, your system needs to meet the following hardware andsoftware setup and requirements:

A client workstation.

Access to a NetScaler (version 5.0 or higher).

A SOAP client tool kit (supporting SOAP version 1.1 and above), and thedevelopment environment for the tool kit. (For example, if you use a VisualBasic tool kit, you must have Visual Basic installed on your system).

Interface DescriptionThe API consists of the NSConfiginterface. The NSConfiginterface includesmethods for setting and querying the configuration. These methods allow theclient application using the NSConfiginterface to perform almost all operations

that an administrator would normally perform with the CLI or GUI.The NetScaler provides an interface description using the Web ServicesDefinition Language (WSDL) that facilitates the development of clientapplications using a language and platform of the developers choice.


13/22

Chapter 1 API Reference 14

API ArchitectureThe API architecture is designed to allow NSConfigclient requests to be routedthrough the HTTP daemon running on the target NetScaler to a SOAP handlerthat translates the SOAP request into a call to the (internal) kernel configurationAPI.

The API Architecture

The order in which the NetScaler processes requests through the API is asfollows:

1. The client formats a request containing XML conforming to the SOAPprotocol and sends it to the NetScaler.

2. The HTTPD server instance on the NetScaler routes this request to a SOAPhandler.

3. The SOAP handler interprets the SOAP headers, and maps the enclosedrequest to an internal configuration function.

4. The kernel acts on the request and returns one or more responses.

5. The SOAP handler then translates the response(s) to a SOAP responsemessage.

6. The XML response is then sent back to the client in an HTTP response.


14/22


The NSConfig InterfaceThe NSConfiginterface closely mirrors the structure of the NetScaler CommandLine Interface (CLI). Administrators and programmers who are familiar with theCLI can easily create and implement custom applications to query or set theconfiguration on their NetScaler. This semantic and syntactic similarity betweenthe API and the CLI helps users to leverage their familiarity and expertise withthe CLI to create applications by using the API.

The NSConfiginterface contains a method for most of the CLI commands. Inmost cases the method and the command name are the same. See the section of the WSDL for a complete list of methods and their names.

For example, you use the add l b vserver CLI command to create a loadbalancing virtual server, as shown below:

add l b vserver [ ]

where:

= A name for the virtual server.= ( HTTP| FTP|TCP| UDP).= The IP address used by the virtual server.= The port that the virtual server listens on.

The corresponding API call, in the C language, is shown below:

i nt ns__addl bvser ver ( voi d *handl e,st r i ng vServerName,st r i ng ser vi ceType,st r i ng I PAddr ess,

unsi gnedShor t por t ,ns__addl bvser verResponse *out ) ;

Note: The exact syntax of the API call depends on the language being used towrite the client program. The above ns__addl bvser ver function prototype issimilar to the one that would be generated by the gSOAP package at ht t p: / /www. cs. f su. edu/ ~engel en/ soap. html .

The result returned for all NSConfig requests consists of:

Rc.An integer return code. The value is zero if the request succeeded; anon-zero value indicates that the request failed.

Message.A string message. Contains meaningful information only if therequest fails (rc is non-zero), for example, Required argument missing.

List.A type-specific list of result entities. This element is present only forrequests that retrieve information from the NetScaler. For example, the API
http://www.cs.fsu.edu/~engelen/soap.htmlhttp://www.cs.fsu.edu/~engelen/soap.htmlhttp://www.cs.fsu.edu/~engelen/soap.htmlhttp://www.cs.fsu.edu/~engelen/soap.html


15/22


method names starting with get , which corresponds to the CLI showcommands, return a list.

For a CLI command listed in the Command Reference (CRG) as , the corresponding API method is named "", with thefollowing exceptions:

1. The CLI showcommand is changed to get in the API, as shown below.

show l b vserver => get l bvser vershow ser vi ce => get ser vi ce

2. The group of commands in the base CLI group have no , and arelisted in the Command Reference Guideas such. For example, showser vi cebecomes get ser vi ce, and add moni t or becomesaddmoni t or .

3. The following commands are, for various reasons, omitted from the API:

All commands in the cli" group.

The batch, pi ng, gr ep, mor e, shel l , and scpcommands.

The show r out er bgpand show r out er mapcommands.

All stat commands.

4. Message "part" names in the API are the same as the corresponding CLIargument names. As in the CLI, case does not matter, and these names can

be abbreviated. See the first chapter of the Command Reference Guideformore information.

5. The result of "get" methods (which correspond to the showcommands inthe CLI) is always an array of a type defined in the WSDL. The elements ofthese complex types generally correspond to arguments to thecorresponding add/set command/method.

6. Authorization must be performed once, by sending a login request; theresponse to this contains a Set-Cookie HTTP header. The cookie must be

passed with each subsequent request. This is addressed in the Perl examplesusing HTTP::Cookies.

7. In some programming languages, such as Perl, it is possible to invoke theprogramming language API without using the WSDL.

Examples of API UsageThis section consists of examples that show how you can develop an API callfrom a standard CLI command, how to generate the SOAP request, and how the

NetScaler responds to that request.


16/22


Example: Setting the ConfigurationThis example shows a CLI command, the corresponding API method, theresulting XML request, and the XML response that is sent back to the client.

Note: The actual API method and the XML SOAP message contents may differfrom the example shown below. The XML shown will be encased in a SOAPenvelope, which will in turn be carried in an HTTP message. For moreinformation on this, see ht t p: / / www. w3. org/ TR/ SOAP.

The following CLI command creates a Load Balancing virtual server:

> add l b vserver vi pLB1 HTTP 10. 100. 101. 1 80

Following is the corresponding API method:> ns__addl bvser ver ( handl e, vi pLB1, HTTP,10. 100. 101. 1, 80, &out ) ;

The XML generated for this request is as follows.

vi pLB1


17/22


Sample output of the show l b vserver scommand is as follows.

> show l b vservers2 conf i gur ed vi r t ual ser ver s:

1) vi pLB1 ( 10. 100. 101. 1: 80) - HTTP Type: ADDRESS Stat e:DOWNMet hod: LEASTCONNECTI ON Mode: I PPer si st ence: NONE

2) vi pLB2 ( 10. 100. 101. 2: 80) - HTTP Type: ADDRESS Stat e:DOWNMet hod: LEASTCONNECTI ON Mode: I PPer si st ence: NONE

Done

Following is the corresponding API method to show the list of Load Balancingvirtual servers.

ns__ get l bvser ver ( handl e, NULL, &out )

The XML generated for this request is as follows.

The XML response to the above request is as follows.

0Done

HTTPvi pLB2

10. 100. 101. 2

80


18/22


The Web Service Definition Language (WSDL)The interface schema provided by the nsconfig interface enables the developmentof client applications that use the API in a language and platform with which thedeveloper is comfortable. This interface schema is based on the WSDLspecification.

The NetScaler provides a WSDL file (NSConf i g. wsdl ) containing theinterface definition. Developers, with the help of a third-party tool (such asgSOAP) can use this WSDL file to generate client stubs. These stubs are thencalled in a custom application to send a request to the NetScaler. The application

can be in any of the languages supported by the third-party tool, such as Perl,Java, C, or C#.

The NSConf i g. wsdl file is available on the NetScaler at:

ht t p: / / / API / NSConf i g. wsdl

where is the IP address of your NetScaler.

Use this WSDL file and the interfaces mentioned in this document to developcustomized applications.

Creating Client Applications Using the

NSConfig.wsdl FileA client application can be created by importing the NSConf i g. wsdl file withthegSOAPWSDL Importer to create a header file with the C/C++ declarationsof the SOAP methods. The gSOAPcompiler is then used to translate this headerfile into stubs for the client application.

To create client stubs using the NSConfig.wsdlfile:

1. Get the NSConf i g. hheader file from the WSDL file.

A. Run the wsdl 2hprogram that comes with gSOAP on the WSDL file.

The wsdl 2hprogram is in the following location.

> . / wsdl 2h NSConf i g. wsdl

The output of wsdl 2his as follows:

** The gSOAP WSDL par ser f or C and C++ 1. 0. 2** Copyr i ght ( C) 2001- 2004 Robert van Engel en,Geni vi a, I nc.


19/22


** Al l Ri ght s Reser ved. Thi s pr oduct i s pr ovi ded"as i s" , wi t hout any war r ant y.

Savi ng NSConf i g. hReadi ng f i l e ' NSConf i g. wsdl 'Cannot open f i l e ' t ypemap. dat 'Probl emr eadi ng t ype map f i l e t ypemap. dat .Usi ng i nt er nal t ype def i ni t i ons f or C i nst ead.

B. Run the soapcpp2 program to compile the header file and completethe process, as shown below.

> soapcpp2 NSConf i g. h

2. Generate the XML files and stubs, as shown below.

> . / soapcpp2 - c - i NSConf i g. h

Sample output for this command is shown below.

** The gSOAP St ub and Skel et on Compi l er f or C and C++2. 4. 1** Copyr i ght ( C) 2001- 2004 Robert van Engel en, Geni vi a,I nc.** Al l Ri ght s Reser ved. Thi s pr oduct i s pr ovi ded "as i s",wi t hout any war r ant y.

Savi ng soapSt ub. hSavi ng soapH. hSavi ng soapC. cSavi ng soapCl i ent . c

Savi ng soapServer . cSavi ng soapCl i ent Li b. cSavi ng soapSer ver Li b. cUsi ng ns1 ser vi ce name: NSConf i gBi ndi ngUsi ng ns1 ser vi ce l ocat i on: ht t p: / / Net Scal er . com/ apiUsi ng ns1 schema namespace: urn: NSConf i gSavi ng soapNSConf i gBi ndi ngProxy. h cl i ent pr oxySavi ng soapNSConf i gBi ndi ngObj ect . h server obj ectSavi ng NSConf i gBi ndi ng. addser ver. r eq. xml sampl e SOAP/ XMLr equestSavi ng NSConf i gBi ndi ng. addser ver. r es. xml sampl e SOAP/ XMLr esponseSavi ng NSConf i gBi ndi ng. di sabl eser ver . r eq. xml sampl e SOAP/

XML r equestSavi ng NSConf i gBi ndi ng. di sabl eser ver . r es. xml sampl e SOAP/XML r esponseSavi ng NSConf i gBi ndi ng. enabl eser ver . r eq. xml sampl e SOAP/XML r equestSavi ng NSConf i gBi ndi ng. enabl eser ver . r es. xml sampl e SOAP/XML r esponse


20/22


[ ... Similar lines clipped ... ]

Savi ng NSConf i gBi ndi ng. nsmap namespace mappi ng tabl eCompi l at i on successf ul

This creates the stub files soapC. c, soapCl i ent . cand st dsoap2. c.

3. Link the stub files you created with your source code to create a stand-alonebinary that invokes the API.

Filter WSDLThe NetScaler WSDL describes services for the entire gamut of NetScalerservices. When you use the NetScaler API in your scripts, link to the WSDL andattempt to compile them, the entire WSDL is included, unnecessarily increasingcompilation time and the size of the program.

Filter WSDL is a method for selecting only those service definitions from theNetScaler WSDL that are relevant to the API calls made in the script.

The NetScaler provides two WSDL files, one for the configuration APIs and theother for statistical APIs. The WSDL file for the configuration API is muchlarger. Therefore, it is important to use filter WSDL when compiling programswritten with the configuration API.

FilterWSDL is a program which works on the Windows, FreeBSD and Linuxplatforms, and it can be run from the CLI.

The syntax for the FilterWSDL command is as follows

f i l t erwsdl

where:

fromwsdl: The wsdl file that you want to filter

pattern: API method names or patterns that should be filtered

For example, if you want to filter all the service definitions for the API method'addlbvserver' from the NetScaler WSDL file, NSConf i g. wsdl , you can use thecommand

> f i l t erwsdl NSConf i g. wsdl "addl bvser ver "

The output of this command is sent to the screen by default but it can beredirected to a file on the NetScaler using the UNIX redirect '>' operator. The

output of the previous command can be saved into a file called 'NSConfig-Custom.wsdl' using the command as follows,

> f i l t erwsdl NSConf i g. wsdl "addl bvserver " > NSConf i g-Custom. wsdl

Consider the files NSConf i g. wsdl and NSConf i g- Cust om. wsdl . Theoriginal WSDL file is 1.58 MB while the filtered WSDL file is 6 KB.


21/22


The pattern used in the filterwsdl command can be used with the '+' and '-'operators and the wildcard '*' operator to create more generic filters.

For example, if you wish to filter the service definitions for all the available loadbalancing methods, you can use the command

> f i l t er wsdl NSConf i g. wsdl "*l b"*

This command will filter all the Load Balancing methods but will also include'GSLB' methods because the pattern l bwill be matched by all GSLBmethodsalso. To include only LB methods and exclude all GSLB methods, use thecommand as follows

> f i l t er wsdl NSConf i g. wsdl +"*l b" - "gl sb"*

Securing API AccessSecure access to CLI objects can be based on the NetScaler IP address or on thesubnet IP address on which the NetScaler is deployed. To provide secured APIaccess based on the NetScaler IP address, you must configure the NetScaler touse transparent SSL mode with clear text port, as described below.

To configure secure API access based on the NetScaler IP:

1. Create a loopback SSL service, and configure it use transparent SSL modewith clear text port.

add servi ce secur e_xml access 127. 0. 0. 1 SSL 443 -cl ear TextPor t 80

2. Add certificate and key.

add cer t key cert1 cert / nsconf i g/ ssl / ssl / cert 1024. pemkey/ nsconf i g/ ssl / ssl / r sakey. pem

Note: You can use an existing certificate and key or use the NetScalerCertificate Authority Tool to create a key and test certificate for secureaccess.

3. Bind the certificate and key to the service.

bi nd cer t key secure_xml access cer t 1 - Ser vi ce

4. Add a custom TCP monitor to monitor the SSL service you have added.

add moni t or ss l _mon TCP - dest por t 80

5. Bind the custom TCP monitor to the SSL service.

bi nd moni t or ss l _mon secure_xml access


22/22


To configure secure API access based on the subnet IP:

1. Create an SSL VIP in the appropriate subnet.

add vserver SSL 443

2. Create a loopback HTTP service.

add ser vi ce 127. 0. 0. 1 HTTP 80

3. Bind the service to the SSL VIP.

bi nd l b vser ver

4. Add the certificate and the key.

add cer t key cer t 1 cer t / nsconf i g/ ssl / ssl / cer t 1024. pem key /nsconf i g/ ssl / ss l / rsakey. pem

Note: You can use an existing certificate and key or use the NetScalerCertificate Authority Tool to create a key and test certificate.

5. Bind the Certificate and the Key to the SSL VIP.

bi nd cer t key cert1

NetScaler Developers Guide

Documents

Transcript of NetScaler Developers Guide