transport – Transport / Session layer

Base types

class ncclient.transport.Session(capabilities)

Base class for use by transport protocol implementations.

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is a list or tuple of arguments for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

add_listener(listener)

Register a listener that will be notified of incoming messages and errors.

property client_capabilities

Client’s Capabilities

property connected

Connection status of the session.

get_listener_instance(cls)

If a listener of the specified type is registered, returns the instance.

property id

A string representing the session-id. If the session has not been initialized it will be None

remove_listener(listener)

Unregister some listener; ignore if the listener was never registered.

property server_capabilities

Server’s Capabilities

class ncclient.transport.SessionListener

Base class for Session listeners, which are notified when a new NETCONF message is received or an error occurs.

Note

Avoid time-intensive tasks in a callback’s context.

callback(root, raw)

Called when a new XML document is received. The root argument allows the callback to determine whether it wants to further process the document.

Here, root is a tuple of (tag, attributes) where tag is the qualified name of the root element and attributes is a dictionary of its attributes (also qualified names).

raw will contain the XML document as a string.

errback(ex)

Called when an error occurs.

SSH session implementation

class ncclient.transport.SSHSession(device_handler)

Bases: Session

Implements a RFC 4742 NETCONF session over SSH.

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is a list or tuple of arguments for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

connect(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password=None, key_filename=None, allow_agent=True, hostkey_verify=True, hostkey=None, look_for_keys=True, ssh_config=None, bind_addr=None])

Connect via SSH and initialize the NETCONF session. First attempts the publickey authentication method and then password authentication.

To disable attempting publickey authentication altogether, call with allow_agent and look_for_keys as False.

host is the hostname or IP address to connect to

port is by default 830 (PORT_NETCONF_DEFAULT), but some devices use the default SSH port of 22 so this may need to be specified

timeout is an optional timeout for socket connect

unknown_host_cb is called when the server host key is not recognized. It takes two arguments, the hostname and the fingerprint (see the signature of default_unknown_host_cb())

username is the username to use for SSH authentication

password is the password used if using password authentication, or the passphrase to use for unlocking keys that require it

key_filename is a filename where a the private key to be used can be found

allow_agent enables querying SSH agent (if found) for keys

hostkey_verify enables hostkey verification from ~/.ssh/known_hosts

hostkey_b64 only connect when server presents a public hostkey matching this (obtain from server /etc/ssh/ssh_host_*pub or ssh-keyscan)

look_for_keys enables looking in the usual locations for ssh keys (e.g. ~/.ssh/id_*)

ssh_config enables parsing of an OpenSSH configuration file, if set to its path, e.g. ~/.ssh/config or to True (in this case, use ~/.ssh/config).

sock_fd is an already open socket which shall be used for this connection. Useful for NETCONF outbound ssh. Use host=None together with a valid sock_fd number

bind_addr is a (local) source IP address to use, must be reachable from the remote device.

sock is an already open Python socket to be used for this connection.

keepalive Turn on/off keepalive packets (default is off). If this is set, after interval seconds without sending any data over the connection, a “keepalive” packet will be sent (and ignored by the remote host). This can be useful to keep connections alive over a NAT.

environment a dictionary containing the name and respective values to set

load_known_hosts(filename=None)

Load host keys from an openssh known_hosts-style file. Can be called multiple times.

If filename is not specified, looks in the default locations i.e. ~/.ssh/known_hosts and ~/ssh/known_hosts for Windows.

property transport

Underlying paramiko.Transport object. This makes it possible to call methods like set_keepalive() on it.

Errors

exception ncclient.transport.TransportError

Bases: NCClientError

exception ncclient.transport.SessionCloseError(in_buf, out_buf=None)

Bases: TransportError

exception ncclient.transport.SSHError

Bases: TransportError

exception ncclient.transport.AuthenticationError

Bases: TransportError

exception ncclient.transport.SSHUnknownHostError(host, fingerprint)

Bases: SSHError