Scripting: Automating NetScaler configurations using NITRO REST API and PowerShell

Part 1: Introduction and getting started.

Citrix NetScaler provides a powerful API that provides configuration and statistics functionality. In this blog series we’ll talk about leveraging the REST Web Services version of the API coupled with PowerShell to produce some very powerful and easy to consume scripts. Feel free to look at the following documentation that will give you an some background on the API:

In part 1 of this series of blog posts, we’ll discuss how we wrapped the REST API with a PowerShell module and created the initial functions that can be used to get started.

But before we get started, some introductory information

To start with some clarity, in the context of Automation, there are no differences if the NetScaler appliance is Physical or VPX that would affect the work we’re doing. This includes how we interact with the NetScaler appliance while performing the configurations and also means that we can normally reuse a script on both types of appliances. The scripts (or functions) would be executed from an endpoint that can reach the NetScaler’s management address and we recommend that you secure your connection. This implies that you’ve gone through at least the very initial command line configuration on the appliance which sets the management IP address (aka NSIP). This same endpoint on which we execute the scripts must include PowerShell V3 or higher, because in our examples we rely on Cmdlets that were introduced in V3 such as Invoke-RestMethod. The information we are going over in this blog post series are examples that constitute one of many ways to approach the consumption of the NITRO REST API and are not meant to be complete or comprehensive.

Importing the example PowerShell module and setting our communication protocol

Importing the NetScaler Configuration module (NetScalerConfigurationPart1 module example)

In PowerShell, as with many other languages, it is common to save and reutilize functionality. This functionality is normally stored in Modules and in order to use it, we must first import it into our session. This of course requires that we have the module (available below) and that it’s extracted to a known location. We can import our example module as follows (assuming we’ve exported the contents to C:\ and remember that the folder name must match the .psd1 and .psm1 file names):

Import-Module C:\NetScalerConfigurationPart1

Choosing the management protocol for the web sessions (Set-NSMgmtProtocol example)

While we recommend using a secure connection to the API, when the NetScaler is first brought online, this is not possible. For this reason, you can change the protocol to use http rather than https by calling the Set-NSMgmtProtocol function. Once set, this is the protocol that is used for that session (or until changed or the PS module is reloaded). This is called using:

Set-NSMgmtProtocol -Protocol http

Connecting and disconnecting from the NetScaler appliance

Connecting to the NetScaler appliance and establishing a session (Connect-NSAppliance example)

When we connect to the NetScaler appliance, we want to establish a new web request session which we save in addition to the management address. This makes it simpler to pass back and forth this custom session object for all configuration operations. To connect, we must know the management IP address or DNS name, user name, and password. Here we try connecting to our NetScaler appliance at 10.11.12.13:

$myNSSession = Connect-NSAppliance -NSAddress 10.11.12.13 -NSUserName nsroot -NSPassword nsroot

From here on, we can call the different NITRO REST API configuration actions using the wrapper function we detail in the section below.

Disconnecting from the NetScaler appliance (Disconnect-NSAppliance example)

When we are done working with the NetScaler, we can use the Disconnect-NSAppliance function to disconnect from the NetScaler. We simply just need this custom session object and call the logout resource type of the API. This can be called as follows:

Disconnect-NSAppliance -NSSession $myNSSession

Wrapping the NITRO REST API configuration calls (Invoke-NSNitroRestApi example)

The NetScaler NITRO REST API is extremely useful by itself. However, when we wrap it with a general purpose function, we can reuse and derive additional functions for specific configuration actions. These actions can then be combined into tasks that complete the configuration of different use cases. This wrapper function takes care of the connection and data manipulation. Please keep in mind that this wrapper function is just an example and it isn’t meant to take care of absolutely every use case, but can be expanded to accommodate additional API functionality. An example call to this function is as follows:

Invoke-NSNitroRestApi -NSSession $myNSSession -OperationMethod POST -ResourceType nsconfig -Action save

The call above will save the NetScaler configuration on the NetScaler appliance that corresponds to the $myNSSession custom web request session object.

Get the example PowerShell Module (Part 1)

This module is now updated in Scripting: Automating NetScaler configurations using NITRO REST API and PowerShell – Part 2

Coming up next

Keep in mind that this is the first blog post of a series. Next time, we’ll go over example use cases as we build up a PowerShell module and accompanying scripts.

Happy Scripting!

Santiago Cardenas

Citrix Solutions Lab

Disclaimer:

This software / sample code is provided to you “AS IS” with no representations, warranties or conditions of any kind. You may use, modify and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software / sample code may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software / sample code fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software / sample code. In no event should the software / code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE / SAMPLE CODE, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.

Topics

Products