salt.modules.nxos

Execution module for Cisco NX OS Switches.

New in version 2016.11.0.

This module supports execution using a Proxy Minion or Native Minion:

1) Proxy Minion: Connect over SSH or NX-API HTTP(S). See salt.proxy.nxos for proxy minion setup details. 2) Native Minion: Connect over NX-API Unix Domain Socket (UDS). Install the minion inside the GuestShell running on the NX-OS device.

maturity:

new

platform:

nxos

Note

To use this module over remote NX-API the feature must be enabled on the NX-OS device by executing feature nxapi in configuration mode.

This is not required for NX-API over UDS.

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

Native minion configuration options:

nxos:
  cookie: 'username'
  save_config: False
cookie

Use the option to override the default cookie 'admin:local' when connecting over UDS and use 'username:local' instead. This is needed when running the salt-minion in the GuestShell using a non-admin user.

This option is ignored for SSH and NX-API Proxy minions.

save_config:

If True, 'copy running-config starting-config' is issues for every configuration command. If False, Running config is not saved to startup config Default: True

The recommended approach is to use the save_running_config function instead of this option to improve performance. The default behavior controlled by this option is preserved for backwards compatibility.

The APIs defined in this execution module can also be executed using salt-call from the GuestShell environment as follows.

salt-call --local nxos.sendline 'show lldp neighbors' raw_text

Note

The functions in this module should be executed like so:

salt '*' nxos.<function> salt '*' nxos.get_user username=admin

For backwards compatibility, the following syntax will be supported until the 3001 release.

salt '*' nxos.cmd <function> salt '*' nxos.cmd get_user username=admin

salt.modules.nxos.add_config(lines, **kwargs)

Add one or more config lines to the NX-OS device running config.

lines

Configuration lines to add

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.add_config 'snmp-server community TESTSTRINGHERE group network-operator'

Note

For more than one config added per command, lines should be a list.

salt.modules.nxos.check_password(username, password, encrypted=False, **kwargs)

Verify user password.

username

Username on which to perform password check

password

Password to check

encrypted

Whether or not the password is encrypted Default: False

salt.modules.nxos.check_role(username, role, **kwargs)

Verify role assignment for user.

salt '*' nxos.check_role username=admin role=network-admin
salt.modules.nxos.cmd(command, *args, **kwargs)

NOTE: This function is preserved for backwards compatibility. This allows commands to be executed using either of the following syntactic forms.

salt '*' nxos.cmd <function>

or

salt '*' nxos.<function>

command

function from salt.modules.nxos to run

args

positional args to pass to command function

kwargs

key word arguments to pass to command function

salt '*' nxos.cmd sendline 'show ver'
salt '*' nxos.cmd show_run
salt '*' nxos.cmd check_password username=admin password='$5$lkjsdfoi$blahblahblah' encrypted=True
salt.modules.nxos.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 to 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.

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

CLI Example:

salt '*' nxos.config commands="['spanning-tree mode mstp']"
salt '*' nxos.config config_file=salt://config.txt
salt '*' nxos.config config_file=https://bit.ly/2LGLcDy context="{'servers': ['1.2.3.4']}"
salt.modules.nxos.delete_config(lines, **kwargs)

Delete one or more config lines to the switch running config.

lines

Configuration lines to remove.

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.delete_config 'snmp-server community TESTSTRINGHERE group network-operator'

Note

For more than one config deleted per command, lines should be a list.

salt.modules.nxos.find(pattern, **kwargs)

Find all instances where the pattern is in the running configuration.

salt '*' nxos.find '^snmp-server.*$'

Note

This uses the re.MULTILINE regex format for python, and runs the regex against the whole show_run output.

salt.modules.nxos.get_roles(username, **kwargs)

Get roles assigned to a username.

salt.modules.nxos.get_user(username, **kwargs)

Get username line from switch.

salt.modules.nxos.grains(**kwargs)

Get grains for minion.

salt.modules.nxos.grains_refresh(**kwargs)

Refresh the grains for the NX-OS device.

salt.modules.nxos.ping(**kwargs)

Ping the device on the other end of the connection.

salt.modules.nxos.remove_user(username, **kwargs)

Remove user from switch.

username

Username to remove

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.remove_user username=daniel
salt.modules.nxos.replace(old_value, new_value, full_match=False, **kwargs)

Replace string or full line matches in switch's running config.

If full_match is set to True, then the whole line will need to be matched as part of the old value.

salt '*' nxos.replace 'TESTSTRINGHERE' 'NEWTESTSTRINGHERE'
salt.modules.nxos.save_running_config(**kwargs)

Save the running configuration to startup configuration.

salt '*' nxos.save_running_config
salt.modules.nxos.sendline(command, method='cli_show_ascii', **kwargs)

Send arbitrary commands to the NX-OS device.

command

The command or list of commands to be sent. ['cmd1', 'cmd2'] is converted to 'cmd1 ; cmd2'.

method:

cli_show_ascii: Return raw test or unstructured output. cli_show: Return structured output. cli_conf: Send configuration commands to the device. Defaults to cli_show_ascii. NOTE: method is ignored for SSH proxy minion. All data is returned unstructured.

error_pattern

Use the option to pass in a regular expression to search for in the returned output of the command that indicates an error has occurred. This option is only used when proxy minion connection type is ssh and otherwise ignored.

salt.modules.nxos.set_password(username, password, encrypted=False, role=None, crypt_salt=None, algorithm='sha256', **kwargs)

Set users password on switch.

username

Username to configure

password

Password to configure for username

encrypted

Whether or not to encrypt the password Default: False

role

Configure role for the username Default: None

crypt_salt

Configure crypt_salt setting Default: None

algorithm

Encryption algorithm Default: sha256

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.set_password admin TestPass
salt '*' nxos.set_password admin \
    password='$5$2fWwO2vK$s7.Hr3YltMNHuhywQQ3nfOd.gAPHgs3SOBYYdGT3E.A' \
    encrypted=True
salt.modules.nxos.set_role(username, role, **kwargs)

Assign role to username.

username

Username for role configuration

role

Configure role for username

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.set_role username=daniel role=vdc-admin.
salt.modules.nxos.show(commands, raw_text=True, **kwargs)

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

commands

The commands to be executed.

raw_text: True

Whether to return raw text or structured data. NOTE: raw_text option is ignored for SSH proxy minion. Data is returned unstructured.

CLI Example:

salt-call --local nxos.show 'show version'
salt '*' nxos.show 'show bgp sessions ; show processes' raw_text=False
salt 'regular-minion' nxos.show 'show interfaces' host=sw01.example.com username=test password=test
salt.modules.nxos.show_run(**kwargs)

Shortcut to run show running-config on the NX-OS device.

salt '*' nxos.show_run
salt.modules.nxos.show_ver(**kwargs)

Shortcut to run show version on the NX-OS device.

salt '*' nxos.show_ver
salt.modules.nxos.system_info(**kwargs)

Return system information for grains of the minion.

salt '*' nxos.system_info
salt.modules.nxos.unset_role(username, role, **kwargs)

Remove role from username.

username

Username for role removal

role

Role to remove

save_config

If False, don't save configuration commands to startup configuration. If True, save configuration to startup configuration. Default: True

salt '*' nxos.unset_role username=daniel role=vdc-admin