# salt.modules.nxos

Execution module for Cisco NX OS Switches.

Added 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