transport – Transport / Session layer

Base types

class ncclient.transport.Session(capabilities)

Base class for use by transport protocol implementations.

add_listener(listener)

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

client_capabilities

Client’s Capabilities

connected

Connection status of the session.

get_listener_instance(cls)

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

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.

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

ssh.default_unknown_host_cb(host, fingerprint)

An unknown host callback returns True if it finds the key acceptable, and False if not.

This default callback always returns False, which would lead to connect() raising a SSHUnknownHost exception.

Supply another valid callback if you need to verify the host key programatically.

host is the hostname that needs to be verified

fingerprint is a hex string representing the host key fingerprint, colon-delimited e.g. “4b:69:6c:72:6f:79:20:77:61:73:20:68:65:72:65:21”

class ncclient.transport.SSHSession(device_handler)

Bases: ncclient.transport.session.Session

Implements a RFC 4742 NETCONF session over SSH.

connect(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password=None, key_filename=None, allow_agent=True, look_for_keys=True, ssh_config=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, 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

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).

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.

transport

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

Errors

exception ncclient.transport.TransportError

Bases: ncclient.NCClientError

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

Bases: ncclient.transport.errors.TransportError

exception ncclient.transport.SSHError

Bases: ncclient.transport.errors.TransportError

exception ncclient.transport.AuthenticationError

Bases: ncclient.transport.errors.TransportError

exception ncclient.transport.SSHUnknownHostError(host, fingerprint)

Bases: ncclient.transport.errors.SSHError