Cisco SD-WAN - Getting Started

Introduction

SD-WAN is a software-defined approach to managing the WAN. In the past, MPLS networks were used to ensure reliable connectivity between users connecting at the branch to applications running on servers in the datacenter. SD-WAN is a new approach to building out WAN networks. It will help organizations to manage their WAN network from a single pane of glass, ensuring optimized routing paths, ensuring high availability for enterprise applications and easily connect your WAN Network to the cloud.

Documentation

Documentation can be found by logging into the vManage and go to `/apidocs’. So for the SD-WAN Devnet Always On Sandbox, we could use https://sandboxsdwan.cisco.com/apidocs.

Credits

Most of the examples below are making use of Nick Russo’s SD-WAN POSTMAN collection. Find them at Nick’s website (here). Also, Nick has a brilliant course on SD-WAN at Pluralsight. Really worth watching it if you want to explore how to run APIs against Cisco’s SD-WAN solution. Check out Nick’s course Automating Cisco SD-WAN Operations Using APIs here).

Authenticate

First off, we need to authenticate with the SDWAN solution. Therefore we need to send a POST request to https://{{vmanage}}:{{port}}/j_security_check. In the body, we need to specify the username (called j_username) and password (j_password). Have a look here to get acquainted with the API

Get device controllers

With authentication out of the way, we can now focus on retrieving some data. In the next script, we will retrieve a list of device controllers from our SD-WAN setup. Code is pretty easy.

Get edge devices

In the above script, we retrieved the device controllers. With a small variation to the above script we can also retrieve a list of vEdge devices. Just call the /dataservice/system/device/vedges API.

Obviously, the POSTMAN response is also reflected in the

Let’s say we would only be interested to have an overview of the CSR1000v edge devices. Then the API allows us also to ‘filter’ the response by using a query parameters. See below for the relevant POSTMAN example.

As you would expect, the returned list of CSR1000v correspond to the list in the SD-WAN user interface.

Get templates

In order to retrieve templates from vManage, we will use the /dataservice/template/ API.

Checking the templates in the user interface of course gets us back the same list of templates.

Get feature template

SD-WAN works with so called feature templates. Retrieving these feature templates is very similar to retrieving templates. We will use the /dataservice/template/feature API.

Below the UI with the same feature templates.

Add user

Adding users to an existing group is done through sending a POST request to the /dataservice/admin/user API. Note the capital N in userName in the JSON body (if spelled wrong, the user will not be added).

If all works well, the user is added here.

Change Password

Also changing the password through the API is possible. For this, use the /dataservice/admin/user/password/<user> API.

Add Group

Let’s say we wanted to add a new group, we could use the /dataservice/admin/usergroup API. In the JSON body, we can set read/write permissions for specific features. Features include Interface, Routing, Security, System, Policy, Alarms, Audit Log, Device Monitoring, Certificates, Device Inventory, Template Configuration, Template Deploy, Policy Configuration, Security Policy Configuration, Policy Deploy, Cloud OnRamp, Software Upgrade, Device Reboot, Manage Users, Tools, Settings, Cluster, vAnalytics and Events.

Get Auditlog

To retrieve the auditlog, we can use the API endpoint /dataservice/auditlog. The audit log contains security related events

Note: in order to collect auditlogs, we need to be an admin user. To check if a user is an Admin, you could use the dataservice/admin/user/role API.

It will return true if the current user has admin privileges.

Get Certificates

In order to retrieve the certificates, you can use the /dataservices/certificate/vsmart/list API.

Below is a screenshot showing the list of certificates.

Get alarm count

We can also retrieve the alarm counts. Use the /dataservice/alarms/count API` for that.

You’ll see we receive back a response with the alarm count and the amount of cleared alarms.

Get Certificates statistics

In order to retrieve the certificates statistics, you can use the /dataservices/certificate/stats/summary API.

Get Control Count

In order to retrieve the control count, you can use the /dataservices/device/control/count API.

You’ll notice that in the response, we get back a link to more details for that status. This lets us explore which devices are up or down. Let’s explore that further.

Get Tunnel statistics

In order to retrieve the control count, you can use the /dataservices/device/tunnel/statistics API. Note that we need to specify a deviceId parameter (e.g the IP address)

Get Device Control Connections

In order to retrieve the control connections, you can use the /dataservices/device/control/connections API. Note that we need to specify a deviceId parameter (e.g the IP address)

Get CPU stats

In order to retrieve CPU stats, you can use the /dataservices/statistics/system API.

Pay particular attention to the JSON body:

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": [
          "1"
        ],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": [
          "4.4.4.60"
        ],
        "field": "vdevice_name",
        "type": "string",
        "operator": "in"
      }
    ]
  },
  "fields": [
    "entry_time",
    "count",
    "cpu_user_new",
    "mem_util"
  ],
  "sort": [
    {
      "field": "entry_time",
      "type": "date",
      "order": "asc"
    }
  ]
}

Here we have specified two rules:

• Rule 1: the entry time (of type date). As the operator is last_n_hours and the value equals 1, it means we want to check the last 1 hour.
• Rule 2: the vdevice_name (of type string) must contain the value 4.4.4.60.

The query condition is AND which means that both above rules must be TRUE

The fields (optional) ensures we collect only a few fields, in our example we are interested in the entry_time, the cpu_user_new and the mem_util. Other attributes could have been statcycletime, system-ip, device_model, host_name, runningp (running processes), totalp(total processes), cpu_system_new, cpu_idle, mem_free, mem_buffers, mem_cached, disk_used, disk_avail, min1_avg (CPU), min5_avg (CPU), min15_avg (CPU).

Last, we will want to sort the date on entry_time in ascending order.

The intention of this post was mainly to provide a short overview of some relevant SD-WAN APIs, nothing really more. In a next post, I will provide some Python scripts that implement these API calls.