nxos

README

go-nxos

go-nxos is a Go client library for Cisco NX-OS devices. It is based on Nathan's excellent goaci module and features a simple, extensible API and advanced JSON manipulation.

Getting Started

Installing

To start using go-nxos, install Go and go get:

$ go get -u github.com/netascode/go-nxos

Basic Usage

package main

import "github.com/netascode/go-nxos"

func main() {
    client, _ := nxos.NewClient("1.1.1.1", "user", "pwd", true)

    res, _ := client.Get("/api/mo/sys/intf/phys-[eth1/1]")
    println(res.Get("imdata.0.*.attributes.id").String())
}

This will print:

eth1/1

Result manipulation

nxos.Result uses GJSON to simplify handling JSON results. See the GJSON documentation for more detail.

res, _ := client.GetClass("l1PhysIf")
println(res.Get("0.l1PhysIf.attributes.name").String()) // name of first physical interface

for _, int := range res.Array() {
    println(int.Get("*.attributes|@pretty")) // pretty print physical interface attributes
}

for _, attr := range res.Get("#.l1PhysIf.attributes").Array() {
    println(attr.Get("@pretty")) // pretty print BD attributes
}

Helpers for common patterns

res, _ := client.GetDn("sys/intf/phys-[eth1/1]")
res, _ := client.GetClass("l1PhysIf")
res, _ := client.DeleteDn("sys/userext/user-[testuser]")

Query parameters

Pass the nxos.Query object to the Get request to add query parameters:

queryInfra := nxos.Query("query-target-filter", `eq(l1PhysIf.id,"eth1/1")`)
res, _ := client.GetClass("l1PhysIf", queryInfra)

Pass as many parameters as needed:

res, _ := client.GetClass("interfaceEntity",
    nxos.Query("rsp-subtree-include", "l1PhysIf"),
    nxos.Query("query-target-filter", `eq(l1PhysIf.id,"eth1/1")`)
)

POST data creation

nxos.Body is a wrapper for SJSON. SJSON supports a path syntax simplifying JSON creation.

exampleInt := nxos.Body{}.Set("l1PhysIf.attributes.id", "eth1/1").Str
client.Post("/api/mo/sys/intf/phys-[eth1/1]", exampleInt)

These can be chained:

int1 := nxos.Body{}.
    Set("l1PhysIf.attributes.id", "eth1/1").
    Set("l1PhysIf.attributes.mode", "trunk")

...or nested:

attrs := nxos.Body{}.
    Set("id", "eth1/1").
    Set("mode", "trunk").
    Str
int1 := nxos.Body{}.SetRaw("l1PhysIf.attributes", attrs).Str

Token refresh

Token refresh is handled automatically. The client keeps a timer and checks elapsed time on each request, refreshing the token every 8 minutes. This can be handled manually if desired:

res, _ := client.Get("/api/...", nxos.NoRefresh)
client.Refresh()

Documentation

See the documentation for more details.

Documentation

Overview

Package nxos is a a Cisco NXOS NX-API REST client library for Go.

Index

• Constants
• func BackoffDelayFactor(x float64) func(*Client)
• func BackoffMaxDelay(x int) func(*Client)
• func BackoffMinDelay(x int) func(*Client)
• func MaxRetries(x int) func(*Client)
• func NoLogPayload(req *Req)
• func NoRefresh(req *Req)
• func Query(k, v string) func(req *Req)
• func RequestTimeout(x time.Duration) func(*Client)
• type Body
  • func (body Body) Delete(path string) Body
  • func (body Body) Res() Res
  • func (body Body) Set(path, value string) Body
  • func (body Body) SetRaw(path, rawValue string) Body
• type Client
  • func NewClient(url, usr, pwd string, insecure bool, mods ...func(*Client)) (Client, error)
  • func (client *Client) Authenticate() error
  • func (client *Client) Backoff(attempts int) bool
  • func (client *Client) DeleteDn(dn string, mods ...func(*Req)) (Res, error)
  • func (client *Client) Do(req Req) (Res, error)
  • func (client *Client) Get(path string, mods ...func(*Req)) (Res, error)
  • func (client *Client) GetClass(class string, mods ...func(*Req)) (Res, error)
  • func (client *Client) GetDn(dn string, mods ...func(*Req)) (Res, error)
  • func (client *Client) JsonRpc(command string, mods ...func(*Req)) (Res, error)
  • func (client *Client) Login() error
  • func (client Client) NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req
  • func (client *Client) Post(dn, data string, mods ...func(*Req)) (Res, error)
  • func (client *Client) Put(dn, data string, mods ...func(*Req)) (Res, error)
  • func (client *Client) Refresh() error
• type Req
• type Res

Constants

const DefaultBackoffDelayFactor float64 = 3

const DefaultBackoffMaxDelay int = 60

const DefaultBackoffMinDelay int = 4

const DefaultMaxRetries int = 3

Functions

func BackoffDelayFactor

func BackoffDelayFactor(x float64) func(*Client)

BackoffDelayFactor modifies the backoff delay factor from the default of 3.

func BackoffMaxDelay

func BackoffMaxDelay(x int) func(*Client)

BackoffMaxDelay modifies the maximum delay between two retries from the default of 60.

func BackoffMinDelay

func BackoffMinDelay(x int) func(*Client)

BackoffMinDelay modifies the minimum delay between two retries from the default of 4.

func MaxRetries

func MaxRetries(x int) func(*Client)

MaxRetries modifies the maximum number of retries from the default of 3.

func NoLogPayload

func NoLogPayload(req *Req)

NoLogPayload prevents logging of payloads. Primarily used by the Login and Refresh methods where this could expose secrets.

func NoRefresh

func NoRefresh(req *Req)

NoRefresh prevents token refresh check. Primarily used by the Login and Refresh methods where this would be redundant.

func Query

func Query(k, v string) func(req *Req)

Query sets an HTTP query parameter.

client.GetClass("bgpInst", nxos.Query("query-target-filter", `eq(bgpInst.asn,"100")`))

Or set multiple parameters:

client.GetClass("bgpInst",
  nxos.Query("rsp-subtree-include", "faults"),
  nxos.Query("query-target-filter", `eq(bgpInst.asn,"100")`))

func RequestTimeout

func RequestTimeout(x time.Duration) func(*Client)

RequestTimeout modifies the HTTP request timeout from the default of 60 seconds.

Types

type Body

type Body struct {
	Str string
}

Body wraps SJSON for building JSON body strings. Usage example:

Body{}.Set("bgpInst.attributes.asn", "100").Str

func (Body) Delete

func (body Body) Delete(path string) Body

Delete deletes a JSON path.

func (Body) Res

func (body Body) Res() Res

Res creates a Res object, i.e. a GJSON result object.

func (Body) Set

func (body Body) Set(path, value string) Body

Set sets a JSON path to a value.

func (Body) SetRaw

func (body Body) SetRaw(path, rawValue string) Body

SetRaw sets a JSON path to a raw string value. This is primarily used for building up nested structures, e.g.:

Body{}.SetRaw("bgpInst.attributes", Body{}.Set("asn", "100").Str).Str

type Client

type Client struct {
	// HttpClient is the *http.Client used for API requests.
	HttpClient *http.Client
	// List of URLs.
	Url string
	// LastRefresh is the timestamp of the last token refresh interval.
	LastRefresh time.Time
	// Token is the current authentication token
	Token string
	// Usr is the NXOS device username.
	Usr string
	// Pwd is the NXOS device password.
	Pwd string
	// Insecure determines if insecure https connections are allowed.
	Insecure bool
	// Maximum number of retries
	MaxRetries int
	// Minimum delay between two retries
	BackoffMinDelay int
	// Maximum delay between two retries
	BackoffMaxDelay int
	// Backoff delay factor
	BackoffDelayFactor float64
}

Client is an HTTP NXOS NX-API client. Use nxos.NewClient to initiate a client. This will ensure proper cookie handling and processing of modifiers.

func NewClient

func NewClient(url, usr, pwd string, insecure bool, mods ...func(*Client)) (Client, error)

NewClient creates a new NXOS HTTP client. Pass modifiers in to modify the behavior of the client, e.g.

client, _ := NewClient("apic", "user", "password", true, RequestTimeout(120))

func (*Client) Authenticate

func (client *Client) Authenticate() error

Login if no token available or refresh the token if older than 480 seconds.

func (*Client) Backoff

func (client *Client) Backoff(attempts int) bool

Backoff waits following an exponential backoff algorithm

func (*Client) DeleteDn

func (client *Client) DeleteDn(dn string, mods ...func(*Req)) (Res, error)

DeleteDn makes a DELETE request by DN.

func (*Client) Do

func (client *Client) Do(req Req) (Res, error)

Do makes a request. Requests for Do are built ouside of the client, e.g.

req := client.NewReq("GET", "/api/mo/sys/bgp", nil)
res, _ := client.Do(req)

func (*Client) Get

func (client *Client) Get(path string, mods ...func(*Req)) (Res, error)

Get makes a GET request and returns a GJSON result. Results will be the raw data structure as returned by the NXOS device, wrapped in imdata, e.g.

{
  "totalCount": "1",
  "imdata": [
    {
      "bgpEntity": {
        "attributes": {
          "adminSt": "enabled",
          "dn": "sys/bgp",
          "name": "bgp"
        }
      }
    }
  ]
}

func (*Client) GetClass

func (client *Client) GetClass(class string, mods ...func(*Req)) (Res, error)

GetClass makes a GET request by class and unwraps the results. Result is removed from imdata, but still wrapped in Class.attributes, e.g.

[
  {
    "bgpEntity": {
      "attributes": {
        "dn": "sys/bgp",
        "name": "bgp",
      }
    }
  }
]

func (*Client) GetDn

func (client *Client) GetDn(dn string, mods ...func(*Req)) (Res, error)

GetDn makes a GET request by DN. Result is removed from imdata and first result is removed from the list, e.g.

{
  "bgpEntity": {
    "attributes": {
      "dn": "sys/bgp",
      "name": "bgp",
    }
  }
}

func (*Client) JsonRpc

func (client *Client) JsonRpc(command string, mods ...func(*Req)) (Res, error)

JsonRpc makes a JSON-RPC request and returns a GJSON result.

func (*Client) Login

func (client *Client) Login() error

Login authenticates to the NXOS device.

func (Client) NewReq

func (client Client) NewReq(method, uri string, body io.Reader, mods ...func(*Req)) Req

NewReq creates a new Req request for this client.

func (*Client) Post

func (client *Client) Post(dn, data string, mods ...func(*Req)) (Res, error)

Post makes a POST request and returns a GJSON result. Hint: Use the Body struct to easily create POST body data.

func (*Client) Put

func (client *Client) Put(dn, data string, mods ...func(*Req)) (Res, error)

Put makes a PUT request and returns a GJSON result. Hint: Use the Body struct to easily create PUT body data.

func (*Client) Refresh

func (client *Client) Refresh() error

Refresh refreshes the authentication token. Note that this will be handled automatically be default. Refresh will be checked every request and the token will be refreshed after 8 minutes. Pass nxos.NoRefresh to prevent automatic refresh handling and handle it directly instead.

type Req

type Req struct {
	// HttpReq is the *http.Request obejct.
	HttpReq *http.Request
	// Refresh indicates whether token refresh should be checked for this request.
	// Pass NoRefresh to disable Refresh check.
	Refresh bool
	// LogPayload indicates whether logging of payloads should be enabled.
	LogPayload bool
	// OverrideUrl indicates a URL to use instead
	OverrideUrl string
}

Req wraps http.Request for API requests.

type Res

type Res = gjson.Result

Res is an API response returned by client requests. This is a GJSON result, which offers advanced and safe parsing capabilities. https://github.com/tidwall/gjson