Citrix SD-WAN has available a powerful NITRO API that enables configuration and monitoring of the product programmatically. NITRO provides its functionality through a Representational State Transfer (REST) interface, enabling NITRO applications to be developed using any programming language. In this blog series, we’ll cover the REST API, available on Citrix SD-WAN Standard and Premium Edition devices, and how it can produce powerful and easy-to-understand scripts to customize our SD-WAN deployments.

You can find additional resources on this topic can be found on Citrix Developer Documentation.

With every release of Citrix SD-WAN software, the available API set grows. You can find the latest CITRIX SD-WAN NITRO API DOC, with detailed description of all NITRO resources in the tar.gz file that’s available for download directly in the SD-WAN devices web interface.

To download it, log in to your SD-WAN device and navigate to Configuration > Appliance Settings > NITRO API and click ‘Download Nitro API Doc’ button (seen below). Unzip the tar.gz file, then open the index.html file in a web browser. Here, you will encounter the Getting Started Guide, which also outlines detail of the NITRO changes across the different software releases.

In part 1 of this series of blog posts, we’ll use Windows PowerShell as our programing tool, and we’ll discuss how we wrapped the REST API with a PowerShell module and created the initial functions that you can use to get started.

Before we get started, some introductory information

In the context of application programing, there’s no difference between a physical Citrix SD-WAN device (e.g. 210-SE) and a virtual (e.g. VPX) appliance. Generally, we can reuse a script on both types of devices. However, be cautious of product nuances that might have an impact on reusage of the script. One example would be a 210-SE appliance’s inability to be an acting Master Control Node (MCN) in an SD-WAN deployment. In this case, a VPX would be allowed.

Additionally, the scripts (or functions) must be executed from an endpoint that has IP connectivity to the management IP address of the SD-WAN device. We recommend that this be a secure connection. The 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 examples in this post are among the many ways to approach the consumption of the NITRO REST API and are not meant to be complete or comprehensive.

Importing an Example PowerShell Module and Setting Up Communication Protocol

In PowerShell, as with many other languages, it’s common to save and reuse functionality. This functionality is normally stored in Modules, and, to use it, we must first import it into our session. This, of course, requires that we have the module built and extracted to a known location.

We have uploaded our example module to PowerShell Gallery for public availability.

Copy and Paste the following command to install this package using PowerShellGet.

Import-Module -Name CitrixSdwanFunctions

Could Not Establish Trust Relationship for SSL/TLS Secure Channel

Citrix SD-WAN devices are shipped with a default CA root certificate for https access. When accessing the web interface of the management interface, you will encounter an ERR_CERT_AUTHORITY_INVALID warning message requiring user acknowledgement before you’re allowed to proceed to the user login page. And when attempting to log in to the device via API, you’ll encounter a similar error about “trust relationship for SSL/TLS secure channel”.

In the imported module example, the following snippets bypass this problem, where there might be trust relationship issues between a host machine and the Citrix SD-WAN being called.

#region: Workaround for SelfSigned Cert and force TLS 1.2
#without this snippet of code, there is a certicate trust relationship error which prevents successful connection to the SDWAN
add-type @”
using System.Net;
using System.Security.Cryptography.X509Certificates;
public class TrustAllCertsPolicy : ICertificatePolicy {
public bool CheckValidationResult(
ServicePoint srvPoint, X509Certificate certificate,
WebRequest request, int certificateProblem) {
return true;
}
}
“@
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy
[System.Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
#endregion

The Management Protocol for the Web Sessions (Module function: Set-SDWMgmtProtocol example)

The NITRO infrastructure consists of a client application (i.e. your host machine running PowerShell) and the NITRO web service running on Citrix SD-WAN system. The communication between the client application and the NITRO web service is based on REST architecture using HTTPS. We can call the module function in the CitrixSdwanFunctions*.psm1 file to set the desired protocol as HTTPS:

Set-SDWMgmtProtocol -Protocol https

Connecting and Disconnecting from the Citrix SD-WAN Appliance

Connecting to the Citrix SD-WAN device and establishing a session (Connect-SDWAppliance example)

When we connect to the Citrix SD-WAN device, we need to first 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 and monitoring operations.

To connect, we must know the management IP address or DNS name, user name, and password. In the example below, we are initiating a login to our Citrix SD-WAN device with management IP 192.168.100.1 using the default admin/password credentials:

$mySDWSession = Connect-SDWAppliance -SDWAddress 172.30.200.192 -SDWUserName admin -SDWPassword password

From here on, we can call the different NITRO REST API configuration actions using the wrapper function we detail in the sections below. However, we should always remember to disconnect our active session when we are done.

Disconnecting from the Citrix SD-WAN device (Disconnect-SDWAppliance example)

When we are done working with the SD-WAN, we can use the Disconnect-SDWAppliance function to disconnect from the device. This custom session object will call the logout resource type of the API:

Disconnect-SDWAppliance -SDWSession $mySDWSession

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

The Citrix SD-WAN NITRO REST API is extremely useful by itself. However, when we wrap it with a general-purpose function, like Invoke-SDWNitroRestAPI, we can reuse and derive additional functions for specific configuration actions. You can then combine these actions into tasks that complete the configuration of different use cases. This wrapper function takes care of the connection and data manipulation.

Please note that this wrapper function is just an example and it isn’t meant to take care of every use case. However, it can be expanded to accommodate additional API functionality. An example call to this function is as follows:

Invoke-SDWNitroRestApi -SDWSession $mySDWSession -OperationMethod GET -ResourceType service

As alluded to in the above example call, this custom function has several input parameters; -SDWSession, -OperationMethod, -ResrouceType, -ResourceName, -Action, -Payload, -GetWarning, and -OnErrorAction.

This custom function also has an output when the operation method is GET. The return object can be manipulated using the ConvertTo-Json cmdlet. This cmdlet coverts any object to a string in JavaScript Object Notation (JSON) format. The properties are converted to field names, the field values are converted to property values, and the methods are removed.

$ServiceStatus = Invoke-SDWNitroRestApi -SDWSession $mySDWSession -OperationMethod GET -ResourceType service

Write-Output "Response:`n$(ConvertTo-Json $ServiceStatus | Out-String)"

Outputs:

Response:
{
"service":  {
"disabled_reason":  "[MISSING_REG]main.reg is missing. No configuration file has been applied to this appliance.",
"service_state":  "disabled"
}
}

You can then use the ConvertFrom-Json cmdlet to convert a JSON-formatted string to a JSON object, which is easily managed in PowerShell.

The GET example above is used to retrieve the “SD-WAN Service Status.” Details about this call, along with many others, can be found in the previously mentioned CITRIX SD-WAN NITRO API DOC found in web interface of any device. See below for where to identify the details of the GET SDWAN Service Status API call.

More to come…

Look for more posts to help you with your scripting endeavors. I’d like to give a special shout-out to Santiago Cardenas for his blog covering the same topic on the Citrix ADC/Gateway product. it helped shape the creation of this blog. Please leave your feedback in the comments below and connect with me on Twitter at @Shoaibys.

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.


Citrix Tech Bytes – Created by Citrix Experts, made for Citrix Technologists! Learn from passionate Citrix Experts and gain technical insights into the latest Citrix Technologies.

Click here for more Tech Bytes and subscribe.

Want specific Tech Bytes? Let us know! tech-content-feedback@citrix.com.