GenericNbiClient sends a query to the GraphQL-based API provided by the Northbound Interface (NBI) of Extreme Management Center (XMC; formerly known as NetSight) and prints the raw JSON response to stdout.
This project uses two defined branches:
masteris the primary development branch. Code withinmastermay be broken at any time.stableis reserved for code that compiles without errors and is tested. Trackstableif you just want to use the software.
Other branches, for example for developing specific features, may be created and deleted at any time.
This tool uses Go modules to handle dependencies.
Use go run ./... to run the tool directly or go build -o GenericNbiClient ./... to compile a binary. Prebuilt binaries may be available as artifacts from the GitLab CI/CD pipeline for tagged releases.
Tested with go1.15.
GenericNbiClient --help:
Usage: ./GenericNbiClient [options] query
Available options:
-h, --host string XMC Hostname / IP
--port uint HTTP port where XMC is listening (default 8443)
--path string Path where XMC is reachable
--timeout uint Timeout for HTTP(S) connections (default 5)
--nohttps Use HTTP instead of HTTPS
--insecurehttps Do not validate HTTPS certificates
-u, --userid string Client ID (OAuth) or username (Basic Auth) for authentication
-s, --secret string Client Secret (OAuth) or password (Basic Auth) for authentication
--basicauth Use HTTP Basic Auth instead of OAuth
--version Print version information and exit
If not provided, query will default to:
query { network { devices { up ip sysName nickName } } }
All options that take a value can be set via environment variables:
XMCHOST --> --host
XMCPORT --> --port
XMCPATH --> --path
XMCTIMEOUT --> --timeout
XMCNOHTTPS --> --nohttps
XMCINSECUREHTTPS --> --insecurehttps
XMCUSERID --> --userid
XMCSECRET --> --secret
XMCBASICAUTH --> --basicauth
Environment variables can also be configured via a file called .xmcenv, located in the current directory or in the home directory of the current user.
GenericNbiClient supports two methods of authentication: OAuth2 and HTTP Basic Auth.
- OAuth2: To use OAuth2, provide the parameters
useridandsecret. GenericNbiClient will attempt to obtain an OAuth2 token from XMC with the supplied credentials and, if successful, submit only that token with each API request as part of the HTTP header. - HTTP Basic Auth: To use HTTP Basic Auth, provide the parameters
useridandsecretas well asbasicauth. GenericNbiClient will transmit the supplied credentials with each API request as part of the HTTP request header.
As all interactions between GenericNbiClient and XMC are secured with HTTPS by default both methods should be safe for transmission over networks. It is strongly recommended to use OAuth2 though. Should the credentials ever be compromised, for example when using them on the CLI on a shared workstation, remediation will be much easier with OAuth2. When using unencrypted HTTP transfer (nohttps), Basic Auth should never be used.
In order to use OAuth2 you will need to create a Client API Access client. To create such a client, visit the Administration -> Client API Access tab within XMC and click on Add. Make sure to note the returned credentials, as they will never be shown again.
Any user or API client who wants to access the Northbound Interface needs the appropriate access rights. In general, checking the full Northbound API section within rights management will suffice. Depending on the use case, it may be feasible to go into detail and restrict the rights to the bare minimum required.
For API clients (OAuth2) the rights are defined when creating an API client and can later be adjusted in the same tab. For regular users (HTTP Basic Auth) the rights are managed via Authorization Groups found in the Administration -> Users tab within XMC.
The original project is hosted at GitLab, with a copy over at GitHub for the folks over there. Additionally, there is a project at GitLab which collects all available clients.