Getting Started Guide Python

User Manual:

Open the PDF directly: View PDF .
Page Count: 11

Download
Open PDF In Browser	View PDF

Citrix NetScaler SDX - NITRO Python Getting Started Guide

Citrix® NetScaler® SDX 10.5

Copyright and Trademark Notice
Copyright © 2014 Citrix Systems, Inc. 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. In no event shall Citrix, its agents,
officers, employees, licensees or affiliates be liable for any damages whatsoever (including, without limitation, damages
for loss of profits, business information, loss of information) arising out of the information or statements contained in the
publication, even if Citrix has been advised of the possibility of such loss or damages. INFORMATION IN THIS
DOCUMENT IS SUBJECT TO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN
EXAMPLES ARE FICTITIOUS UNLESS OTHERWISE NOTED.
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
the user will be required to correct the interference at his or her own expense.
Pursuant to the rules and regulations of the Federal Communications Commission, changes or modifications to this
product not expressly approved by Citrix Systems, Inc., could void your authority to operate the product. Note the FCC
rules and regulations are not included for software products, such as virtual appliances.
AppCache, AppCompress, AppDNA, App-DNA, AppFlow, AppScaler, Apptitude, Citrix, Citrix Access Gateway, Citrix
Application Firewall, Citrix Cloud Center, Citrix Systems, Citrix XenApp, CloudGateway, CloudBridge, CloudPortal,
CloudStack, EdgeSight, Flex Tenancy, HDX, ICA, MPX, nCore, NetScaler, NetScaler App Delivery Controller, NetScaler
Access Gateway, NetScaler App Firewall, NetScaler CloudConnector, NetScaler Gateway, NetScaler SDX, Netviewer,
Network Link, SecureICA, VMLogix LabManager, VMLogix StageManager, VPX, Xen, Xen Source, XenApp,
XenAppliance, XenCenter, XenClient, XenDesktop, XenEnterprise, XenServer, XenSource, Xen Data Center, and
Zenprise are trademarks of Citrix Systems, Inc. and/or one of its subsidiaries, and may be registered in the U.S. Patent
and Trademark Office and other countries. Other product and company names mentioned herein may be trademarks of
their respective companies.
Last Updated: March 2014
Document code: June 15 2014 23:52:35

Contents

NITRO API................................................................................................5
Obtaining the NITRO Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
How NITRO Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
API Categorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
System APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Configuration APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

iii

Contents

iv

NITRO API
The Citrix NetScaler SDX NITRO protocol allows you to configure and monitor the
NetScaler SDX appliance programmatically.
NITRO exposes its functionality through Representational State Transfer (REST)
interfaces. Therefore, NITRO applications can be developed in any programming
language. Additionally, for applications that must be developed in Java or .NET or
Python, the NITRO protocol is exposed as relevant libraries that are packaged as
separate Software Development Kits (SDKs).
Note: You must have a basic understanding of the NetScaler SDX appliance before
using NITRO.
To use the NITRO protocol, the client application needs the following:
w Access to a NetScaler SDX appliance.
w To use REST interfaces, you must have a system to generate HTTP or HTTPS requests
(payload in JSON format) to the NetScaler SDX appliance. You can use any
programming language or tool.
w For Java clients, you must have a system where Java Development Kit (JDK) 1.5 or
above version is available. The JDK can be downloaded from http://
www.oracle.com/technetwork/java/javase/downloads/index.html.
w For .NET clients, you must have a system where .NET framework 3.5 or above
version is available. The .NET framework can be downloaded from http://
www.microsoft.com/downloads/en/default.aspx.
w For Python clients, you must have a system where Python 2.7 or above version and
the Requests library (available in /lib) is installed.

Obtaining the NITRO Package
The NITRO package is available as a tar file on the Downloads page of the NetScaler
SDX appliance's configuration utility. You must download and un-tar the file to a folder
on your local system. This folder is referred to as  in this
documentation.
The folder contains the NITRO libraries in the lib subfolder. The libraries must be
added to the client application classpath to access NITRO functionality. The
 folder also provides samples and documentation that can help
you understand the NITRO SDK.
Note:

5

NITRO API

w The REST package contains only documentation for using the REST interfaces.
w For the Python SDK, the library must be installed on the client path. For
installation instructions, read the /README.txt file.

How NITRO Works
The NITRO infrastructure consists of a client application and the NITRO Web service
running on a NetScaler appliance. The communication between the client application
and the NITRO web service is based on REST architecture using HTTP or HTTPS.
Figure 1-1. NITRO execution flow

As shown in the above figure, a NITRO request is executed as follows:
1. The client application sends REST request message to the NITRO web service.
When using the SDKs, an API call is translated into the appropriate REST request
message.
2. The web service processes the REST request message.
3. The NITRO web service returns the corresponding REST response message to the
client application. When using the SDKs, the REST response message is translated
into the appropriate response for the API call.
To minimize traffic on the network, you retrieve the whole state of a resource from the
server, make modifications to the state of the resource locally, and then upload it back
to the server in one network transaction.
Note: Local operations on a resource (changing its properties) do not affect its state
on the server until the state of the object is explicitly uploaded.
NITRO APIs are synchronous in nature. This means that the client application waits for
a response from the NITRO web service before executing another NITRO API.

API Categorization
NetScaler SDX NITRO APIs are categorized depending on the scope and purpose of the
APIs into system APIs and configuration APIs. You can also troubleshoot NITRO
operations.
6

Citrix NetScaler SDX - NITRO Python - Getting Started Guide

System APIs
The first step towards using NITRO is to establish a session with the NetScaler SDX
appliance and then authenticate the session by using the administrator's credentials.
You must create an object of the nitro_service class by specifying the IP address of
the appliance and the protocol to connect to the appliance (HTTP or HTTPS). You then
use this object and log on to the appliance by specifying the user name and the
password of the administrator.
Note: You must have a user account on that appliance. The configuration operations
that you can perform are limited by the administrative role assigned to your account.
The following sample code connects to a NetScaler SDX appliance with IP address
10.102.31.16 by using HTTPS protocol:
# Specify the IP address of the appliance and service type
nitroservice = nitro_service ("10.102.31.16", "https")
# Specify the login credentials
nitroservice.login("nsroot", "verysecret")
Note: You must use the nitro_service object in all further NITRO operations on
the appliance.
To disconnect from the appliance, invoke the logout() method as follows:
nitroservice.logout()

Configuration APIs
The NITRO protocol can be used to configure resources of the NetScaler SDX appliance.
The APIs to configure a resource are grouped into packages or namespaces that have
the format
sdxsrc.com.citrix.sdx.nitro.resource.config.. Each of
these packages or namespaces contain a class named  that provides
the APIs to configure the resource.
For example, the NetScaler resource has the
sdxsrc.com.citrix.sdx.nitro.resource.config.ns package or namespace.
A resource class provides APIs to perform other operations such as creating a resource,
retrieving resource details and statistics, updating a resource, deleting resources, and
performing bulk operations on resources.
Creating a Resource

7

NITRO API
To create a new resource (for example, a NetScaler instance) on the NetScaler SDX
appliance, do the following:
1. Set the value for the required properties of the resource by using the
corresponding property name. The result is a resource object that contains the
details required for the resource.
Note: These values are set locally on the client. The values are not reflected on
the appliance till the object is uploaded.
2. Upload the resource object to the appliance, using the static add() method.
The following sample code creates a NetScaler instance named "ns_instance" on the
NetScaler SDX appliance:
newns = ns()
# Set the properties of the NetScaler locally
newns.name = "ns_instance"
newns.ip_address = "10.70.136.5"
newns.netmask = "255.255.255.0"
newns.gateway = "10.70.136.1"
newns.image_name = "nsvpx-9.3.45_nc.xva"
newns.profile_name = "ns_nsroot_profile"
newns.vm_memory_total = 2048.0
newns.throughput = 1000.0
newns.pps = 1000000.0
newns.license = "Standard"
newns.username = "admin"
newns.password = "admin"
# Here number_of_interfaces we have considered is 2
interface_array=[]
interface_array = [network_interface() for _ in range(2)]
# Adding 10/1
interface_array[0].port_name = "10/1"
# Adding 10/2
interface_array[1].port_name = "10/2"
newns.network_interfaces = interface_array
# Upload the NetScaler instance
result = ns.add(nitroservice, newns)
Retrieving Resource Details
To retrieve the properties of a resource on the NetScaler SDX appliance, do the
following:
1. Retrieve the configurations from the appliance by using the get() method. The
result is a resource object.
2. Extract the required property from the object by using the corresponding property
name.
8

Citrix NetScaler SDX - NITRO Python - Getting Started Guide
The following sample code retrieves the details of all NetScaler resources:
# Retrieve the resource object from the NetScaler SDX appliance
returned_ns = ns.get(nitroservice)
# Extract the properties of the resource from the object
for i in range(0,len(returned_ns)):
print returned_ns[i].ip_address
print returned_ns[i].netmask
Retrieving Resource Statistics
A NetScaler SDX appliance collects statistics on the usage of its features. You can
retrieve these statistics using NITRO.
The following sample code retrieves statistics of a NetScaler instance with ID 123456a:
obj = ns()
obj.id = "123456a"
stats = ns.get(nitroservice, obj)
print "CPU Usage:" + stats.ns_cpu_usage
print "Memory Usage:" + stats.ns_memory_usage
print "Request rate/sec:" +stats.http_req
Updating a Resource
To update the properties of an existing resource on the appliance, do the following:
1. Set the id property to the ID of the resource to be updated.
2. Set the value for the required properties of the resource by using the
corresponding property name. The result is a resource object.
Note: These values are set locally on the client. The values are not reflected on
the appliance till the object is uploaded.
3. Upload the resource object to the appliance, using the update() method.
The following sample code updates the name of the NetScaler instance with ID 123456a
to 'ns_instance_new':
update_obj = ns()
# Set the ID of the NetScaler to be updated
update_obj.id = "123456a"
# Get existing NetScaler details
update_obj = ns.get(nitroservice, update_obj)
# Update the name of the NetScaler to "ns_instance_new" locally
update_obj.name = "ns_instance_new"
# Upload the updated NetScaler details
result = ns.update(nitroservice, update_obj)

9

NITRO API
Deleting a Resource
To delete an existing resource, invoke the static method delete() on the resource
class, by passing the ID of the resource to be removed, as an argument.
The following sample code deletes a NetScaler instance with ID 1:
obj = ns()
obj.id = "123456a"
ns.delete(nitroservice, obj)
Bulk Operations
You can query or change multiple resources simultaneously and thus minimize network
traffic. For example, you can add multiple NetScaler appliances in the same operation.
Each resource class has methods that take an array of resources for adding, updating,
and removing resources. To perform a bulk operation, specify the details of each
operation locally and then send the details at one time to the server.
To account for the failure of some operations within the bulk operation, NITRO allows
you to configure one of the following behaviors:
w Exit. When the first error is encountered, the execution stops. The commands that
were executed before the error are committed.
w Continue. All the commands in the list are executed even if some commands fail.
Note: You must configure the required behavior while establishing a connection with
the appliance, by setting the onerror param in the nitro_service() method.
The following sample code adds two NetScalers in one operation:
newns=[]
newns = [ns() for _ in range(2)]
# Specify details of first NetScaler
newns[0].name = "ns_instance1"
newns[0].ip_address = "10.70.136.5"
newns[0].netmask = "255.255.255.0"
newns[0].gateway = "10.70.136.1"
# Specify details of second NetScaler
newns[1].name = "ns_instance2"
newns[1].ip_address = "10.70.136.8"
newns[1].netmask = "255.255.255.0"
newns[1].gateway = "10.70.136.1"
# Upload the details of the NetScalers to the NITRO server
result = ns.add(nitroservice, newns)

10

Citrix NetScaler SDX - NITRO Python - Getting Started Guide

Exception Handling
The errorcode field indicates the status of the operation.
w An errorcode of 0 indicates that the operation is successful.
w A non-zero errorcode indicates an error in processing the NITRO request.
The error message field provides a brief explanation and the nature of the failure.
All exceptions in the execution of NITRO APIs are caught by the
sdxsrc.com.citrix.sdx.nitro.exception.nitro_exception class. To get
information about the exception, you can use the getErrorCode() method.
For a more detailed description of the error codes, see the API reference available in
the /doc folder.

11



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Create Date                     : 2014:06:15 23:52:36-05:00
Modify Date                     : 2014:06:15 23:52:36-05:00
Creator                         : AH XSL Formatter V6.0 MR6 for Windows (x64) : 6.0.6.8606 (2013/01/08 18:51JST)
Producer                        : Antenna House PDF Output Library 6.0.362 (Windows (x64))
Trapped                         : False
Page Count                      : 11
Page Mode                       : UseOutlines
Language                        : EN

EXIF Metadata provided by EXIF.tools