# `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

ssh.default_unknown_host_cb(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 programmatically.

  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: `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`