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 datacredentials
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. RetryRunnerhost – Nornir Host object supplied by RetryRunner
via – host’s
connection_options
parameter name to use for opening connection forconn_name
, ifvia
parameter provided,close_open
always set to True` to re-establish host connection.reconnect
not suppported withvia
.default_to_host_attributes
set toTrue
ifvia
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
andlocal_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 toout_of_band
will result in connection being open usingout_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 toconsole_port_rp0
, this task plugin will establish connection to terminal server and will authenticate usingconsole_port_rp0
credentials, next Netmiko connection will be redispatched using platform and credentials fromredispacth
parameters.If
via
is equal toconsole_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 andarista_eos
as a platform.For redispatch to work,
hostname
parameter must always be provided in connection options.