Citrix NetScaler 9.

1
Citrix NetScaler
Developers Guide

Copyright and Trademark Notice
CITRIX SYSTEMS, INC., 2009. ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED OR
TRANSMITTED 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 PRESENTED
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE ALL RESPONSIBILITY FOR THE USE
OR 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 OR
APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS DOCUMENT. INFORMATION IN THIS DOCUMENT IS SUBJ ECT
TO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN EXAMPLES ARE FICTITIOUS UNLESS
OTHERWISE NOTED.
The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits
for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against
harmful 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 radio
communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be
required 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 requirements
for Class A digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required to
correct 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 by
the NetScaler Request Switch 9000 Series equipment. If the NetScaler equipment causes interference, try to correct the interference by
using 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 your
equipment 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 the
product.
BroadCom is a registered trademark of BroadCom Corporation. Fast Ramp, NetScaler, and NetScaler Request Switch are trademarks of
Citrix 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 registered
trademarks of Sun Microsystems, Inc. Other brand and product names may be registered trademarks or trademarks of their respective
holders.
Software covered by the following third party copyrights may be included with this product and will also be subject to the software license
agreement: Copyright 1998 Carnegie Mellon University. All rights reserved. Copyright David L. Mills 1993, 1994. Copyright
1992, 1993, 1994, 1997 Henry Spencer. Copyright J ean-loup Gailly and Mark Adler. Copyright 1999, 2000 by J ef Poskanzer. All
rights reserved. Copyright Markus Friedl, Theo de Raadt, Niels Provos, Dug Song, Aaron Campbell, Damien Miller, Kevin Steves. All
rights 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 V
Murray. Copyright 1995-1998 Eric Young. Copyright 1995,1996,1997,1998. Lars Fenneberg. Copyright 1992. Livingston
Enterprises, 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 J uniper Networks, Inc. All rights reserved. Copyright 2001, 2002
Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 1999-
2001The Open LDAP Foundation. All Rights Reserved. Copyright 1999 Andrzej Bialecki. All rights reserved. Copyright 2000
The 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 J onathan Lemon. All rights reserved. Copyright (c) 1997, 1998, 1999. Bill Paul. All rights reserved. Copyright (c) 1994-1997 Matt
Thomas. All rights reserved. Copyright 2000 J ason L. Wright. Copyright 2000 Theo de Raadt. Copyright 2001 Patrik Lindergren.
All rights reserved.
Last Updated: J une 2009
CONTENTS
Contents
Preface
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
New in This Release. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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). . . . . . . . . . . . . . . . . . . . . . . . . . .19
Creating Client Applications Using the NSConfig.wsdl File. . . . . . . . . . . . . . .19
Filter WSDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Securing API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
iv Citrix NetScaler Developers Guide
PREFACE
Preface
Before you begin to develop actions for the NetScaler, take a few minutes to
review 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 Guide
This guide introduces you to the NetScaler developer Application Programming
Interface (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 so
the 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.
vi Citrix NetScaler Developers Guide
New in This Release
NetScaler 9.1 nCore Technology is a new software release that uses CPU cores
for packet handling and greatly improves the performance of many NetScaler
features. NetScaler 9.1 nCore supports features in this guide unless specified
otherwise. For a summary of the features that are not supported in NetScaler 9.1
nCore, see the Citrix NetScaler 9.1 and NetScaler 9.1 nCore Release Notes.
Audience
This guide is intended for the following audience:
Network administrators
Application programmers
The concepts and tasks described in this guide require you to have a basic
understanding of the NetScaler configuration and also a good understanding of
using an API to develop custom applications or scripts.
Formatting Conventions
This documentation uses the following formatting conventions.
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 you
provide. For example, FileName in a command means you
type the actual name of a file. Also, new terms, and words
referred to as words (which would otherwise be enclosed in
quotation marks).
%SystemRoot% The Windows system directory, which can be WTSRV,
WINNT, WINDOWS, or any other name you specify when
you install Windows.
Monospace System output or characters in a command line. User input
and placeholders also are formatted using monspace text.
{ braces } A series of items, one of which is required in command
statements. For example, { yes | no } means you must type
yes or no. Do not type the braces themselves.
Preface vii
Related Documentation
A complete set of documentation is available on the Documentation tab of your
NetScaler and from http://support.citrix.com/. (Most of the documents require
Adobe Reader, available at http://adobe.com/.)
To view the documentation
1. 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. To open a document, click the title.
Getting Service and Support
Citrix provides technical support primarily through the Citrix Solutions Network
(CSN). Our CSN partners are trained and authorized to provide a high level of
support to our customers. Contact your supplier for first-line support, or check for
your nearest CSN partner at http://support.citrix.com/.
[ brackets ] Optional items in command statements. For example, in
the following command, [ - r ange
positiveInteger] means that you have the option of
entering a range, but it is not required:
add lb vserver name serviceType IPAddress
port [-range positiveInteger]
Do not type the brackets themselves.
| (vertical bar) A separator between options in braces or brackets in
command statements. For example, the following indicates
that you choose one of the following load balancing
methods:
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 command
statements. For example, /route:DeviceName[,] means
you can type additional DeviceNames separated by
commas.
Formatting Conventions
Convention Meaning
viii Citrix NetScaler Developers Guide
You can also get support from Citrix Customer Service at http://citrix.com/. On
the Support menu, click Customer Service.
In addition to the CSN program and Citrix Customer Service, Citrix offers the
following support options for Citrix NetScaler.
Knowledge Center
The Knowledge Center offers a variety of self-service, Web-based technical
support tools at http://support.citrix.com/.
Knowledge Center features include:
A knowledge base containing thousands of technical solutions to support
your 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, under
Products, 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 to
the Knowledge Center product and, under Tools, click Remove from your
Hotfix Alerts.
Security bulletins
Online problem reporting and tracking (for organizations with valid support
contracts)
Silver and Gold Maintenance
In addition to the standard support options, Silver and Gold maintenance options
are available. If you purchase either of these options, you receive documentation
with special Citrix Technical Support numbers you can call.
Silver Maintenance Option
The Silver maintenance option provides unlimited system support for one year.
This option provides basic coverage hours, one assigned support account
manager for nontechnical relations management, four named contacts, and
advanced replacement for materials.
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 J apan): 8 A.M. to 6 P.M. Hong Kong Time, Monday
through Friday
Australia and New Zealand: 8 A.M. to 6 P.M. Australian Eastern Standard
Time (AEST), Monday through Friday
Europe, Middle East, and Africa: 8 A.M. to 6 P.M. Coordinated Universal
Time (Greenwich Mean Time), Monday through Friday
Gold Maintenance Option
The 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 support
account manager for nontechnical relations management, and there are six named
contacts.
Subscription Advantage
Your product includes a one-year membership in the Subscription Advantage
program. The Citrix Subscription Advantage program gives you an easy way to
stay current with the latest software version and information for your Citrix
products. Not only do you get automatic access to download the latest feature
releases, software upgrades, and enhancements that become available during the
term of your membership, you also get priority access to important Citrix
technology information.
You can find more information on the Citrix Web site at http://www.citrix.com/
(on the Support menu, click Subscription Advantage).
You can also contact your sales representative, Citrix Customer Care, or a
member of the Citrix Solutions Advisors program for more information.
Education and Training
Citrix 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 the
Citrix Web site.
Information about programs and courseware for Citrix training and certification is
available at http://www.citrixtraining.com.
x Citrix NetScaler Developers Guide
Documentation Feedback
You are encouraged to provide feedback and suggestions so that we can enhance
the documentation. You can send email to the following alias or aliases, as
appropriate. In the subject line, specify Documentation Feedback. Be sure to
include the document name, page number, and product release version.
For NetScaler documentation, send email to nsdocs_feedback@citrix.com.
For Command Center documentation, send email to
ccdocs_feedback@citrix.com.
For Access Gateway documentation, send email to
agdocs_feedback@citrix.com.
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 NetScaler
Application Delivery, and click NetScaler Application Delivery
Software 9.1.
3. On the Documentation tab, click the guide name, and then click Article
Feedback.
4. On the Documentation Feedback page, complete the form and click
Submit.
CHAPTER 1
API Reference
Developers and administrators can use the NetScaler Application Programming
Interface (API), nsconfig, to implement customized client applications. The
nsconfig API, which mirrors the NetScaler command line interface (CLI), is
based on the Web Services Description (WSDL) specification. It includes a
FilterWSDL command to reduce compilation time and file size. You can secure
your API applications at the NetScaler IP address or at the IP address of the the
subnet on which the NetScaler is deployed.
Introduction to the API
The NetScaler can be configured using an external Application Programming
Interface (API). The API allows programmatic communications between client
applications and the NetScaler. This interface provides the means for a custom
client 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 schema
for facilitating business-to-business transactions over the Internet.
The NetScaler software contains a number of changes and enhancements to the
API, including the following:
Add command. In 4.0.1, the add command contains only the required
argument 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 nd and unbi nd commands
treat dependent arguments exactly as set commands do.
13 Citrix NetScaler Developers Guide
Note: The NetScaler continues to accept and correctly process requests from
clients developed using previous versions of the API.
Benefits of API
The following are the benefits of the API:
The API provides developers the advantage of controlling the NetScaler
from a custom application. The API enables the client application to
configure and monitor the NetScaler.
The interface allows the developers to easily and quickly develop client
applications using a language and platform with which the developer is
comfortable.
The API provides a secure, end-to-end, standards-based framework that
integrates into the existing infrastructure.
Hardware and Software Requirements
To work with the API, your system needs to meet the following hardware and
software 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 the
development environment for the tool kit. (For example, if you use a Visual
Basic tool kit, you must have Visual Basic installed on your system).
Interface Description
The API consists of the NSConfig interface. The NSConfig interface includes
methods for setting and querying the configuration. These methods allow the
client application using the NSConfig interface 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 Services
Definition Language (WSDL) that facilitates the development of client
applications using a language and platform of the developers choice.
Chapter 1 API Reference 14
API Architecture
The API architecture is designed to allow NSConfig client requests to be routed
through the HTTP daemon running on the target NetScaler to a SOAP handler
that translates the SOAP request into a call to the (internal) kernel configuration
API.
The API Architecture
The order in which the NetScaler processes requests through the API is as
follows:
1. The client formats a request containing XML conforming to the SOAP
protocol and sends it to the NetScaler.
2. The HTTPD server instance on the NetScaler routes this request to a SOAP
handler.
3. The SOAP handler interprets the SOAP headers, and maps the enclosed
request 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 response
message.
6. The XML response is then sent back to the client in an HTTP response.
15 Citrix NetScaler Developers Guide
The NSConfig Interface
The NSConfig interface closely mirrors the structure of the NetScaler Command
Line Interface (CLI). Administrators and programmers who are familiar with the
CLI can easily create and implement custom applications to query or set the
configuration on their NetScaler. This semantic and syntactic similarity between
the API and the CLI helps users to leverage their familiarity and expertise with
the CLI to create applications by using the API.
The NSConfig interface contains a method for most of the CLI commands. In
most cases the method and the command name are the same. See the <portType>
section of the WSDL for a complete list of methods and their names.
For example, you use the add l b vser ver CLI command to create a load
balancing virtual server, as shown below:
add l b vser ver <vServerName> <serviceType> [ <IPAddress> <port>]
where:
<vServerName> =A name for the virtual server.
<serviceType> =( HTTP | FTP | TCP | UDP).
<IPAddress> =The IP address used by the virtual server.
<port> =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 vSer ver Name,
st r i ng ser vi ceType,
st r i ng I PAddr ess,
unsi gnedShor t por t ,
ns__addl bvser ver Response *out ) ;
Note: The exact syntax of the API call depends on the language being used to
write the client program. The above ns__addl bvser ver function prototype is
similar to the one that would be generated by the gSOAP package at ht t p: / /
www. cs. f su. edu/ ~engel en/ soap. ht ml .
The result returned for all NSConfig requests consists of:
Rc. An integer return code. The value is zero if the request succeeded; a
non-zero value indicates that the request failed.
Message. A string message. Contains meaningful information only if the
request fails (rc is non-zero), for example, Required argument missing.
List. A type-specific list of result entities. This element is present only for
requests that retrieve information from the NetScaler. For example, the API
Chapter 1 API Reference 16
method names starting with get , which corresponds to the CLI show
commands, return a list.
For a CLI command listed in the Command Reference (CRG) as <op><grp>
<ot>, the corresponding API method is named "<op><grp><ot>", with the
following exceptions:
1. The CLI show command is changed to get in the API, as shown below.
show l b vser ver => get l bvser ver
show ser vi ce => get ser vi ce
2. The group of commands in the base CLI group have no <grp>, and are
listed in the Command Reference Guide as such. For example, show
ser vi ce becomes get ser vi ce, and add moni t or becomes
addmoni t or .
3. The following commands are, for various reasons, omitted from the API:
All commands in the cli" group.
The bat ch, pi ng, gr ep, mor e, shel l , and scp commands.
The show r out er bgp and show r out er map commands.
All st at commands.
4. Message "part" names in the API are the same as the corresponding CLI
argument names. As in the CLI, case does not matter, and these names can
be abbreviated. See the first chapter of the Command Reference Guide for
more information.
5. The result of "get" methods (which correspond to the show commands in
the CLI) is always an array of a type defined in the WSDL. The elements of
these complex types generally correspond to arguments to the
corresponding add/set command/method.
6. Authorization must be performed once, by sending a login request; the
response to this contains a Set-Cookie HTTP header. The cookie must be
passed with each subsequent request. This is addressed in the Perl examples
using HTTP::Cookies.
7. In some programming languages, such as Perl, it is possible to invoke the
programming language API without using the WSDL.
Examples of API Usage
This section consists of examples that show how you can develop an API call
from a standard CLI command, how to generate the SOAP request, and how the
NetScaler responds to that request.
17 Citrix NetScaler Developers Guide
Example: Setting the Configuration
This example shows a CLI command, the corresponding API method, the
resulting 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 differ
from the 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 on this, see ht t p: / / www. w3. or g/ TR/ SOAP.
The following CLI command creates a Load Balancing virtual server:
> add l b vser ver 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.
<ns: addl bvser ver >
<vSer ver Name xsi : t ype=" xsd: st r i ng" >vi pLB1</ vSer ver Name>
<ser vi ceType xsi : t ype=" ns: vser vi cet ypeEnum>HTTP</
ser vi ceType>
<I PAddr ess xsi : t ype=" xsd: st r i ng" >10. 100. 101. 1</ I PAddr ess>
<por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t >
< / ns: addl bvser ver >
The XML response to the above request is as follows.
<ns: addl bvser ver Response>
<r c xsi : t ype=" xsd: unsi gnedI nt " >0</ r c>
<message xsi : t ype=" xsd: st r i ng" >Done</ message>
</ ns: addl bvser ver Response>
Example: Querying the Configuration
This example shows an API request that queries the configuration and receives a
list of entities.
Note: The actual API method and the XML SOAP message contents may differ
from the example shown below.
The following CLI command shows the configured Load Balancing virtual
servers:
> show l b vser ver s
Chapter 1 API Reference 18
Sample output of the show l b vser ver s command is as follows.
> show l b vser ver s
2 conf i gur ed vi r t ual ser ver s:
1) vi pLB1 ( 10. 100. 101. 1: 80) - HTTP Type: ADDRESS St at e:
DOWN
Met hod: LEASTCONNECTI ON Mode: I P
Per si st ence: NONE
2) vi pLB2 ( 10. 100. 101. 2: 80) - HTTP Type: ADDRESS St at e:
DOWN
Met hod: LEASTCONNECTI ON Mode: I P
Per si st ence: NONE
Done
Following is the corresponding API method to show the list of Load Balancing
virtual servers.
ns__get l bvser ver ( handl e, NULL, &out )
The XML generated for this request is as follows.
<ns: get l bvser ver ></ ns: get l bvser ver >
The XML response to the above request is as follows.
<ns: get l bvser ver Response>
<r c xsi : t ype=" xsd: unsi gnedI nt " >0</ r c>
<message xsi : t ype=" xsd: st r i ng" >Done</ message>
<Li st xsi : t ype=" SOAP- ENC: Ar r ay"
SOAP- ENC: ar r ayType=" ns: l bvser ver [ 2] " >
<i t emxsi : t ype=" ns: l bvser ver " >
<vSer ver Name xsi : t ype=" xsd: st r i ng>vi pLB1
</ vSer ver Name>
<ser vi ceType xsi : t ype=" xsd: st r i ng>HTTP</
ser vi ceType>
<I PAddr ess xsi : t ype=" xsd: st r i ng >10. 100. 101. 1
</ I PAddr ess>
<por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t >
</ i t em>
<i t emxsi : t ype=" ns: l bvser ver " >
<vSer ver Name xsi : t ype=" xsd: st r i ng>vi pLB2
</ vSer ver Name>
<ser vi ceType xsi : t ype=" xsd: st r i ng>HTTP</
ser vi ceType>
<I PAddr ess xsi : t ype=" xsd: st r i ng >10. 100. 101. 2
</ I PAddr ess>
<por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t >
</ i t em>
19 Citrix NetScaler Developers Guide
</ Li st >
</ ns: get l bvser ver Response>
The Web Service Definition Language (WSDL)
The interface schema provided by the nsconfig interface enables the development
of client applications that use the API in a language and platform with which the
developer is comfortable. This interface schema is based on the WSDL
specification.
The NetScaler provides a WSDL file (NSConf i g. wsdl ) containing the
interface definition. Developers, with the help of a third-party tool (such as
gSOAP) can use this WSDL file to generate client stubs. These stubs are then
called 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,
J ava, C, or C#.
The NSConf i g. wsdl file is available on the NetScaler at:
ht t p: / / <NSI P>/ API / NSConf i g. wsdl
where <NSIP> is the IP address of your NetScaler.
Use this WSDL file and the interfaces mentioned in this document to develop
customized applications.
Creating Client Applications Using the
NSConfig.wsdl File
A client application can be created by importing the NSConf i g. wsdl file with
thegSOAP WSDL Importer to create a header file with the C/C++declarations
of the SOAP methods. The gSOAP compiler is then used to translate this header
file into stubs for the client application.
To create client stubs using the NSConfig.wsdl file:
1. Get the NSConf i g. h header file from the WSDL file.
A. Run the wsdl 2h program that comes with gSOAP on the WSDL file.
The wsdl 2h program is in the following location.
> . / wsdl 2h NSConf i g. wsdl
The output of wsdl 2h is as follows:
** The gSOAP WSDL par ser f or C and C++ 1. 0. 2
** Copyr i ght ( C) 2001- 2004 Rober t van Engel en,
Geni vi a, I nc.
Chapter 1 API Reference 20
** 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. h
Readi ng f i l e ' NSConf i g. wsdl '
Cannot open f i l e ' t ypemap. dat '
Pr obl 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 complete
the 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 Rober t 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. h
Savi ng soapH. h
Savi ng soapC. c
Savi ng soapCl i ent . c
Savi ng soapSer ver . c
Savi ng soapCl i ent Li b. c
Savi ng soapSer ver Li b. c
Usi ng ns1 ser vi ce name: NSConf i gBi ndi ng
Usi ng ns1 ser vi ce l ocat i on: ht t p: / / Net Scal er . com/ api
Usi ng ns1 schema namespace: ur n: NSConf i g
Savi ng soapNSConf i gBi ndi ngPr oxy. h cl i ent pr oxy
Savi ng soapNSConf i gBi ndi ngObj ect . h ser ver obj ect
Savi ng NSConf i gBi ndi ng. addser ver . r eq. xml sampl e SOAP/ XML
r equest
Savi ng NSConf i gBi ndi ng. addser ver . r es. xml sampl e SOAP/ XML
r esponse
Savi ng NSConf i gBi ndi ng. di sabl eser ver . r eq. xml sampl e SOAP/
XML r equest
Savi ng NSConf i gBi ndi ng. di sabl eser ver . r es. xml sampl e SOAP/
XML r esponse
Savi ng NSConf i gBi ndi ng. enabl eser ver . r eq. xml sampl e SOAP/
XML r equest
Savi ng NSConf i gBi ndi ng. enabl eser ver . r es. xml sampl e SOAP/
XML r esponse
21 Citrix NetScaler Developers Guide
[ ... Similar lines clipped ... ]
Savi ng NSConf i gBi ndi ng. nsmap namespace mappi ng t abl e
Compi l at i on successf ul
This creates the stub files soapC. c, soapCl i ent . c and st dsoap2. c.
3. Link the stub files you created with your source code to create a stand-alone
binary that invokes the API.
Filter WSDL
The NetScaler WSDL describes services for the entire gamut of NetScaler
services. When you use the NetScaler API in your scripts, link to the WSDL and
attempt to compile them, the entire WSDL is included, unnecessarily increasing
compilation time and the size of the program.
Filter WSDL is a method for selecting only those service definitions from the
NetScaler WSDL that are relevant to the API calls made in the script.
The NetScaler provides two WSDL files, one for the configuration APIs and the
other for statistical APIs. The WSDL file for the configuration API is much
larger. Therefore, it is important to use filter WSDL when compiling programs
written with the configuration API.
FilterWSDL is a program which works on the Windows, FreeBSD and Linux
platforms, and it can be run from the CLI.
The syntax for the FilterWSDL command is as follows
f i l t er wsdl <f r omwsdl > <pat t er n>
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 the
command
> f i l t er wsdl NSConf i g. wsdl " addl bvser ver "
The output of this command is sent to the screen by default but it can be
redirected 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 er wsdl NSConf i g. wsdl " addl bvser ver " > NSConf i g- Cust om. wsdl
Consider the files NSConf i g. wsdl and NSConf i g- Cust om. wsdl . The
original WSDL file is 1.58 MB while the filtered WSDL file is 6 KB.
Chapter 1 API Reference 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 load
balancing 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 b will be matched by all GSLB methods
also. To include only LB methods and exclude all GSLB methods, use the
command as follows
> f i l t er wsdl NSConf i g. wsdl +" *l b" - " gl sb" *
Securing API Access
Secure access to CLI objects can be based on the NetScaler IP address or on the
subnet IP address on which the NetScaler is deployed. To provide secured API
access based on the NetScaler IP address, you must configure the NetScaler to
use 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 mode
with clear text port.
add ser vi ce secur e_xml access 127. 0. 0. 1 SSL 443 -
cl ear Text Por t 80
2. Add certificate and key.
add cer t key cer t 1 cer t / nsconf i g/ ssl / ssl / cer t 1024. pemkey
/ nsconf i g/ ssl / ssl / r sakey. pem
Note: You can use an existing certificate and key or use the NetScaler
Certificate Authority Tool to create a key and test certificate for secure
access.
3. Bind the certificate and key to the service.
bi nd cer t key secur e_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 ssl _mon TCP - dest por t 80
5. Bind the custom TCP monitor to the SSL service.
bi nd moni t or ssl _mon secur e_xml access
23 Citrix NetScaler Developers Guide
To configure secure API access based on the subnet IP:
1. Create an SSL VIP in the appropriate subnet.
add vserver <vServerName>SSL <Subnet-IP>443
2. Create a loopback HTTP service.
add ser vi ce <ser vi ceName> 127. 0. 0. 1 HTTP 80
3. Bind the service to the SSL VIP.
bi nd l b vser ver <vSer ver Name> <ser vi ceName>
4. Add the certificate and the key.
add cer t key cer t 1 cer t / nsconf i g/ ssl / ssl / cer t 1024. pemkey /
nsconf i g/ ssl / ssl / r sakey. pem
Note: You can use an existing certificate and key or use the NetScaler
Certificate 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 <vServerName> cer t 1