salt.modules.nxos_api¶

Execution module to manage Cisco Nexus Switches (NX-OS) over the NX-API

New in version 2019.2.0.

Execution module used to interface the interaction with a remote or local Nexus switch whether we're running in a Proxy Minion or regular Minion (or regular Minion running directly on the Nexus switch).

codeauthor:: Mircea Ulinic <ping@mirceaulinic.net>
maturity:: new
platform:: any

Note

To be able to use this module you need to enable to NX-API on your switch, by executing feature nxapi in configuration mode.

Configuration example:

switch# conf t
switch(config)# feature nxapi

To check that NX-API is properly enabled, execute show nxapi.

Output example:

switch# show nxapi
nxapi enabled
HTTPS Listen on port 443

Note

NX-API requires modern NXOS distributions, typically at least 7.0 depending on the hardware. Due to reliability reasons it is recommended to run the most recent version.

Check https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus7000/sw/programmability/guide/b_Cisco_Nexus_7000_Series_NX-OS_Programmability_Guide/b_Cisco_Nexus_7000_Series_NX-OS_Programmability_Guide_chapter_0101.html for more details.

Usage¶

This module can equally be used via the nxos_api Proxy module or directly from an arbitrary (Proxy) Minion that is running on a machine having access to the network device API. Given that there are no external dependencies, this module can very well used when using the regular Salt Minion directly installed on the switch.

When running outside of the nxos_api Proxy (i.e., from another Proxy Minion type, or regular Minion), the NX-API connection arguments can be either specified from the CLI when executing the command, or in a configuration block under the nxos_api key in the configuration opts (i.e., (Proxy) Minion configuration file), or Pillar. The module supports these simultaneously. These fields are the exact same supported by the nxos_api Proxy Module:

transport: https

Specifies the type of connection transport to use. Valid values for the connection are http, and https.

host: localhost

The IP address or DNS host name of the connection device.

username: admin

The username to pass to the device to authenticate the NX-API connection.

password

The password to pass to the device to authenticate the NX-API connection.

port

The TCP port of the endpoint for the NX-API connection. If this keyword is not specified, the default value is automatically determined by the transport type (80 for http, or 443 for https).

timeout: 60

Time in seconds to wait for the device to respond. Default: 60 seconds.

verify: True

Either a boolean, in which case it controls whether we verify the NX-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.

When there is no certificate configuration on the device and this option is set as True (default), the commands will fail with the following error: SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581). In this case, you either need to configure a proper certificate on the device (recommended), or bypass the checks setting this argument as False with all the security risks considered.

Check https://www.cisco.com/c/en/us/td/docs/switches/datacenter/nexus3000/sw/programmability/6_x/b_Cisco_Nexus_3000_Series_NX-OS_Programmability_Guide/b_Cisco_Nexus_3000_Series_NX-OS_Programmability_Guide_chapter_01.html to see how to properly configure the certificate.

Example (when not running in a nxos_api Proxy Minion):

nxos_api:
  username: test
  password: test

In case the username and password are the same on any device you are targeting, the block above (besides other parameters specific to your environment you might need) should suffice to be able to execute commands from outside a nxos_api Proxy, e.g.:

salt-call --local nxos_api.show 'show lldp neighbors' raw_text
# The command above is available when running in a regular Minion where Salt is installed

salt '*' nxos_api.show 'show version' raw_text=False

Note

Remember that the above applies only when not running in a nxos_api Proxy Minion. If you want to use the nxos_api Proxy, please follow the documentation notes for a proper setup.

salt.modules.nxos_api.config(commands=None, config_file=None, template_engine='jinja', context=None, defaults=None, saltenv='base', **kwargs)¶

Configures the Nexus switch with the specified commands.

This method is used to send configuration commands to the switch. It will take either a string or a list and prepend the necessary commands to put the session into config mode.

Warning

All the commands will be applied directly into the running-config.

config_file

The source file with the configuration commands to be sent to the device.

The file can also be a template that can be rendered using the template engine of choice.

This can be specified using the absolute path to the file, or using one of the following URL schemes:

salt://, to fetch the file from the Salt fileserver.
http:// or https://
ftp://
s3://
swift://

commands

The commands to send to the switch in config mode. If the commands argument is a string it will be cast to a list. The list of commands will also be prepended with the necessary commands to put the session in config mode.

Note

This argument is ignored when config_file is specified.

template_engine: jinja

The template engine to use when rendering the source file. Default: jinja. To simply fetch the file without attempting to render, set this argument to None.

context

Variables to add to the template context.

defaults

Default values of the context_dict.

transport: https

Specifies the type of connection transport to use. Valid values for the connection are http, and https.

host: localhost

The IP address or DNS host name of the connection device.

username: admin

The username to pass to the device to authenticate the NX-API connection.

password

The password to pass to the device to authenticate the NX-API connection.

port

The TCP port of the endpoint for the NX-API connection. If this keyword is not specified, the default value is automatically determined by the transport type (80 for http, or 443 for https).

timeout: 60

Time in seconds to wait for the device to respond. Default: 60 seconds.

verify: True

Either a boolean, in which case it controls whether we verify the NX-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.

CLI Example:

salt '*' nxos_api.config commands="['spanning-tree mode mstp']"
salt '*' nxos_api.config config_file=salt://config.txt
salt '*' nxos_api.config config_file=https://bit.ly/2LGLcDy context="{'servers': ['1.2.3.4']}"

salt.modules.nxos_api.rpc(commands, method='cli', **kwargs)¶

Execute an arbitrary RPC request via the Nexus API.

commands: The commands to be executed.
method: cli: The type of the response, i.e., raw text (cli_ascii) or structured document (cli). Defaults to cli (structured data).
transport: https: Specifies the type of connection transport to use. Valid values for the connection are http, and https.
host: localhost: The IP address or DNS host name of the connection device.
username: admin: The username to pass to the device to authenticate the NX-API connection.
password: The password to pass to the device to authenticate the NX-API connection.
port: The TCP port of the endpoint for the NX-API connection. If this keyword is not specified, the default value is automatically determined by the transport type (80 for http, or 443 for https).
timeout: 60: Time in seconds to wait for the device to respond. Default: 60 seconds.
verify: True: Either a boolean, in which case it controls whether we verify the NX-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.

CLI Example:

salt-call --local nxos_api.rpc 'show version'

salt.modules.nxos_api.show(commands, raw_text=True, **kwargs)¶

Execute one or more show (non-configuration) commands.

commands: The commands to be executed. Multiple commands should be specified as a list.
raw_text: True: Whether to return raw text or structured data.
transport: https: Specifies the type of connection transport to use. Valid values for the connection are http, and https.
host: localhost: The IP address or DNS host name of the connection device.
username: admin: The username to pass to the device to authenticate the NX-API connection.
password: The password to pass to the device to authenticate the NX-API connection.
port: The TCP port of the endpoint for the NX-API connection. If this keyword is not specified, the default value is automatically determined by the transport type (80 for http, or 443 for https).
timeout: 60: Time in seconds to wait for the device to respond. Default: 60 seconds.
verify: True: Either a boolean, in which case it controls whether we verify the NX-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True.

CLI Example:

salt-call --local nxos_api.show 'show version'
salt '*' nxos_api.show "['show bgp sessions','show processes']" raw_text=False
salt 'regular-minion' nxos_api.show 'show interfaces' host=sw01.example.com username=test password=test