connections

Collection of task plugins to work with Nornir hosts’ connections

Sample usage

Code to invoke connections task plugins:

from nornir import InitNornir

from nornir_salt.plugins.tasks import connections

nr = InitNornir(config_file="config.yaml")

# get a list of connection
connections_active = nr.run(
    task=connections,
    call="ls"
)

# close all connections
conn_close = nr.run(
    task=connections,
    call="close"
)

# connect netmiko connections
connections_connect = nr.run(
    task=connections,
    call="open",
    conn_name="netmiko",
    username="user123",
    password="pass123",
    reconnect=[
        {
            "username": "user321",
            "password": "pass321",
        },
        "local_creds",
    ]
)

API reference

nornir_salt.plugins.tasks.connections.connections(task, call, **kwargs)

Dispatcher function to call one of the functions.

Parameters
  • call – (str) nickname of function to call

  • arg – (list) function arguments

  • kwargs – (dict) function key-word arguments

Returns

call function execution results

Call function nicknames:

  • ls - calls conn_list task

  • close - calls conn_close task

  • open - calls conn_open task

nornir_salt.plugins.tasks.connections.conn_list(task, conn_name: str = 'all') list

Function to list host’s active connections.

Parameters

conn_name – name of connection to list, default is “all”

Returns

list of hosts’ connections

nornir_salt.plugins.tasks.connections.conn_close(task, conn_name: str = 'all') list

Task to close host’s connections.

Parameters

conn_name – name of connection to close, default is “all”

Returns

list of connections closed

nornir_salt.plugins.tasks.connections.conn_open(task, conn_name: str, host: Optional[nornir.core.inventory.Host] = None, hostname: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None, port: Optional[int] = None, platform: Optional[str] = None, extras: Optional[Dict[str, Any]] = None, default_to_host_attributes: bool = True, close_open: bool = False, reconnect: list = None, raise_on_error: bool = False, via: str = None) nornir.core.task.Result

Helper function to open connections to hosts. Supports reconnect logic retrying different connection parameters.

Parameters
  • conn_name – name of configured connection plugin to use to open connection e.g. netmiko, napalm, scrapli

  • hostname – hostname or ip address to connect to

  • username – username to use to open the connection

  • password – password to use to open the connection

  • port – port to use to open the connection

  • platform – platform name connection parameter

  • extras – connection plugin extras parameters

  • default_to_host_attributes – on True host’s open connection method uses inventory data to suppliment not missing arguments like port or platform

  • close_open – if True, closes already open connection and connects again

  • reconnect – list of parameters to use to try connecting to device if primary set of parameters fails. If reconnect item is a dictionary, it is supplied as **kwargs to host open connection call. Alternatively, reconnect item can refer to a name of credentials set from inventory data credentials section within host, groups or defaults inventory.

  • raise_on_error – raises error if not able to establish connection even after trying all reconnect parameters, used to signal exception to parent function e.g. RetryRunner

  • host – Nornir Host object supplied by RetryRunner

  • via – host’s connection_options parameter name to use for opening connection for conn_name, if via parameter provided, close_open always set to True` to re-establish host connection. reconnect not suppported with via. default_to_host_attributes set to True if via argument provided.

Returns

Nornir result object with connection establishment status

Device re-connects

Sample reconnect list content:

[
    {
        "username": "foo123",
        "port": "24",
        "password": "123foo",
    },
    "deprecated_creds",
    "local_account"
]

Where deprecated_creds and local_account could be stored in Nornir inventory default data credentials section:

defaults:
  data:
    credentials:
      deprecated_creds:
        password: foo
        username: bar
        extras:
          optional_args:
            key_file: False
      local_account:
        password: nornir
        username: nornir

Starting with nornir-salt version 0.19.0 support added to reconnect credetntials to specify per-connection parameters using connection_options argument:

default:
  data:
    credentials:
      local_creds:
        # these params will be used with Netmiko conn_name
        username: nornir
        password: nornir
        platform: arista_eos
        port: 22
        extras:
          conn_timeout: 10
          auto_connect: True
          session_timeout: 60
        connection_options:
          # these params will be used with NAPALM conn_name
          napalm:
            username: nornir
            platform: eos
            port: 80
            extras:
              optional_args:
                transport: http
                eos_autoComplete: None
          # these params will be used with Scrapli conn_name
          scrapli:
            password: nornir
            platform: arista_eos
            port: 22
            extras:
              auth_strict_key: False
              ssh_config_file: False
      local_creds_old:
        username: nornir2
        password: nornir2

connection_options parameters are preferred and override higher level parameters.

Device via connections

Specifying via parameter allows to open connection to device using certain connection options. This is useful when device has multiple management IP addresses, for example - inband, out of band or console.

If via parameter provided, connection always closed before proceeding with re-opening it.

Given this host inventory:

hosts:
  ceos1:
    hostname: 10.0.1.3
    platform: arista_eos
    username: nornir
    password: nornir
    connection_options:
      out_of_band:
        hostname: 10.0.1.4
        port: 22

setting via equal to out_of_band will result in connection being open using out_of_band parameters.

Device connection redispatch

Primary use case is to use via to open connection to console server and use Netmiko redispatch functionality to access device console.

Given this host inventory:

hosts:
  ceos1:
    hostname: 10.0.1.3
    platform: arista_eos
    username: nornir
    password: nornir
    connection_options:
      console_port_rp0:
        # console server parameters
        hostname: 10.0.1.4
        port: 1234
        username: nornir123
        password: nornir123
        platform: terminal_server
        extras:
          redispatch:
            # redispatch parameters for device connected to console
            username: nornir321
            password: nornir321
            platform: arista_eos
      console_port_rp1:
        # console server hostname:
        hostname: 10.0.1.5
        extras:
          redispatch: True

If via is equal to console_port_rp0, this task plugin will establish connection to terminal server and will authenticate using console_port_rp0 credentials, next Netmiko connection will be redispatched using platform and credentials from redispacth parameters.

If via is equal to console_port_rp1, this task plugin will establish connection to terminal server hostname and authenticating with host’s credentials, next Netmiko connection will be redispatched using platform and credentials from host’s parameters - nornir username and password and arista_eos as a platform.

For redispatch to work, hostname parameter must always be provided in connection options.