transport – Transport / Session layer — ncclient 0.5.3 documentation

# `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 the argument tuple 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: `ncclient.transport.session.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 the argument tuple 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.

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