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
- type Client
- 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) 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
Variables ¶
This section is empty.
Functions ¶
func BackoffDelayFactor ¶ added in v0.2.0
BackoffDelayFactor modifies the backoff delay factor from the default of 3.
func BackoffMaxDelay ¶ added in v0.2.0
BackoffMaxDelay modifies the maximum delay between two retries from the default of 60.
func BackoffMinDelay ¶ added in v0.2.0
BackoffMinDelay modifies the minimum delay between two retries from the default of 4.
func MaxRetries ¶ added in v0.2.0
MaxRetries modifies the maximum number of retries from the default of 3.
func NoLogPayload ¶ added in v0.2.0
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 ¶
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 ¶
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
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 ¶
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 ¶
Login if no token available or refresh the token if older than 480 seconds.
func (*Client) Do ¶
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 ¶
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 ¶
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 ¶
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) Post ¶
Post makes a POST request and returns a GJSON result. Hint: Use the Body struct to easily create POST body data.
func (*Client) Put ¶ added in v0.1.1
Put makes a PUT request and returns a GJSON result. Hint: Use the Body struct to easily create PUT body data.
func (*Client) Refresh ¶
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 ¶
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
Source Files