netconf_client API

netconf_client.connect

class netconf_client.connect.CallhomeManager(bind_to='', port=4334, backlog=1)[source]

Listener object for accepting callhome connections (RFC 8071)

Options on the listener socket (e.g. timeout) can be set on the server_socket member.

This object is a context manager, and should generally be used within with statements to ensure the listening socket is properly closed. Note that sessions started from one of the accept functions may outlive the scope of this object and will not be closed automatically.

Example of accepting a call-home connection with TLS:

with CallhomeManager(port=4335) as call_home_mgr:
    session = call_home_mgr.accept_one_tls(keyfile=client_key,
                                           certfile=client_cert,
                                           ca_certs=ca_cert)
with Manager(session) as mgr:
    mgr.get_config(source='running')
accept_one(timeout=120)[source]

Accept a single TCP client and returns it

Parameters:

timeout (int) – Seconds to wait for an incoming connection

accept_one_ssh(*args, **kwds)[source]

Accept a single TCP client and start an SSH session on it

This function takes the same arguments as connect_ssh()

accept_one_tls(*args, **kwds)[source]

Accept a single TCP client and start a TLS session on it

This function takes the same arguments as connect_tls()

netconf_client.connect.connect_ssh(host=None, port=830, username='netconf', password=None, key_filename=None, sock=None, hostkey_b64=None, initial_timeout=None, general_timeout=None)[source]

Connect to a NETCONF server over SSH.

Parameters:

  • host (str) – Hostname or IP address; unused if an already-open socket is provided

  • port (int) – TCP port to initiate the connection; unused if an already-open socket is provided

  • username (str) – Username to login with; always required

  • password (str) – Password to login with; not required if a private key is provided instead

  • key_filename (str) – Path to an SSH private key; not required if a password is provided instead

  • sock – An already-open TCP socket; SSH will be setup on top of it

  • initial_timeout (int) – Seconds to wait when first connecting the socket.

  • general_timeout (int) – Seconds to wait for a response from the server after connecting.

  • hostkey_b64 (str) – base64 encoded hostkey.

Returns:

Session object

Return type:

netconf_client.session.Session

netconf_client.connect.connect_tls(host=None, port=6513, keyfile=None, certfile=None, ca_certs=None, sock=None, initial_timeout=None, general_timeout=None)[source]

Connect to a NETCONF server over TLS.

Parameters:

  • host (str) – Hostname or IP address; unused if an already-open socket is provided

  • port (int) – TCP port to initiate the connection; unused if an already-open socket is provided

  • keyfile – Path to the key file used to identify the client

  • certfile – Path to the certificate used to identify the client

  • ca_certs – Path to a file containing the certificate autority chains for verifying the server identity

  • sock – An already-open TCP socket; TLS will be setup on top of it

  • initial_timeout (int) – Seconds to wait when first connecting the socket.

  • general_timeout (int) – Seconds to wait for a response from the server after connecting.

Return type:

netconf_client.session.Session

netconf_client.ncclient

class netconf_client.ncclient.DataReply(raw, ele)[source]

A response containing a <data> element

Variables:

  • data_xml (str) – The data element in string form (note that this value was handled by lxml)

  • data_ele – The lxml parsed representation of the data

  • raw_reply (bytes) – The raw reply from the server

class netconf_client.ncclient.Manager(session, timeout=120, log_id=None)[source]

A helper class for performing common NETCONF operations with pretty logging.

This class attempts to be API compatible with the manager object from the original ncclient.

This class is also a context manager and can be used with with statements to automatically close the underlying session.

NETCONF requests and responses are logged using the netconf_client.manager scope. The log level is logger.DEBUG.

Each log entry shows a log ID (the peers’ IP addresses as default). Additionally, the round-trip delay between request and its response is computed and displayed.

The Python logger receives a dictionary via extra parameter, whose key is ncclient.Manager.funcname and which contains the name of the API function being logged. This information can be used for user-specific filtering.

Variables:

  • timeout (float) – Duration in seconds to wait for a reply, default is 120 seconds (see DEFAULT_RPC_TIMEOUT)

  • session – The underlying netconf_client.session.Session connected to the server

  • log_id (str) – application-specific log ID (None as default)

cancel_commit(persist_id: Optional[str] = None, timeout=None)[source]

Send a <cancel-commit> request

Parameters:

  • persist_id (str) – A persistent confirmed commit id given in the <commit> request. Can be None (default), if <cancel-commit> is issued on the same session that issued the confirmed commit.

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

close_session(timeout=None)[source]

Send a <close-session> request

Parameters:

(optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

commit(confirmed=False, confirm_timeout=None, persist=None, persist_id=None, timeout=None)[source]

Send a <commit> request

Parameters:

  • confirmed (bool) – Set to True if this is a confirmed-commit

  • confirm_timeout (int) – When confirmed is True, the number of seconds until the commit will be automatically rolled back if no confirmation or extension is received

  • persist (str) – When confirmed is True, sets the persist-id token for the commit and makes the commit a persistent commit

  • persist_id (str) – When confirmed is True and a previous <persist> was given for the current commit, this field must match the corresponding persist-id for the commit

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

copy_config(target, source, with_defaults=None, timeout=None)[source]

Send a <copy-config> request

Parameters:

  • source (str) – The source datastore or the <config> element containing the complete configuration to copy.

  • target (str) – The destination datastore

  • with_defaults (str) – Specify the mode of default reporting. See RFC 6243. Can be None (i.e., omit the with-defaults tag in the request), ‘report-all’, ‘report-all-tagged’, ‘trim’, or ‘explicit’.

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

create_subscription(stream=None, filter=None, start_time=None, stop_time=None, timeout=None)[source]

Send a <create-subscription> request

Received <notification> elements can be retrieved with take_notification()

Parameters:

  • stream (str) – The event stream to subscribe to

  • filter (str) – The filter for notifications to select

  • start_time (str) – When replaying notifications, the earliest notifications to replay

  • stop_time (str) – When replaying notifications, the latest notifications to replay

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

delete_config(target, timeout=None)[source]

Send a <delete-config> request

Parameters:

  • target (str) – The datastore to delete

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

discard_changes(timeout=None)[source]

Send a <discard-changes> request

Parameters:

(optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

dispatch(rpc, timeout=None)[source]

Send an <rpc> request

Parameters:

  • rpc (str) – The RPC to send; it should not include an <rpc> tag (one will be generated for you)

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

Return type:

RPCReply

edit_config(config, target='running', default_operation=None, test_option=None, error_option=None, format='xml', timeout=None)[source]

Send an <edit-config> request

Parameters:

  • config (str) – The <config> node to use in the request

  • target (str) – The datastore to edit

  • default_operation (str) – The default-operation to perform; can be None, ‘merge’, ‘replace’, or ‘none’.

  • test_option (str) – The test-option to use; can be None, ‘test-then-set’, ‘set’, or ‘test-only’

  • error_option (str) – The error-option to use; can be None, ‘stop-on-error’, ‘continue-on-error’, or ‘rollback-on-error’

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

get(filter=None, with_defaults=None, timeout=None)[source]

Send a <get> request

Parameters:

  • filter (str) – The <filter> node to use in the request

  • with_defaults (str) – Specify the mode of default reporting. See RFC 6243. Can be None (i.e., omit the with-defaults tag in the request), ‘report-all’, ‘report-all-tagged’, ‘trim’, or ‘explicit’.

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

Return type:

DataReply

get_config(source='running', filter=None, with_defaults=None, timeout=None)[source]

Send a <get-config> request

Parameters:

  • source (str) – The datastore to retrieve the configuration from

  • filter (str) – The <filter> node to use in the request

  • with_defaults (str) – Specify the mode of default reporting. See RFC 6243. Can be None (i.e., omit the with-defaults tag in the request), ‘report-all’, ‘report-all-tagged’, ‘trim’, or ‘explicit’.

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

Return type:

DataReply

get_data(datastore='ds:operational', filter=None, config_filter=None, origin_filters=[], negate_origin_filters=False, max_depth=None, with_origin=False, with_defaults=None, timeout=None)[source]

Send a <get-data> request

Parameters:

  • datastore (str) – The datastore to retrieve the data from.

  • filter (str) – Either the <subtree-filter> or the xpath-filter node to use in the request.

  • config_filter (bool) – Specifies if only “config true” or only “config false” nodes are returned. Both are returned if unspecified.

  • origin_filters (dict) – A list of origins (e.g., “or:intended”). No origin filters are applied if unspecified.

  • negate_origin_filters (bool) – Specifies if origin_filters are negated.

  • max_depth (int) – A 16-bit unsigned integer. If unspecified, the max-depth is unbounded.

  • with_origin (bool) – Specifies if the ‘origin’ annotation should be returned for nodes having one.

  • with_defaults (str) – Specify the mode of default reporting. See RFC 6243. Can be None (i.e., omit the with-defaults tag in the request), ‘report-all’, ‘report-all-tagged’, ‘trim’, or ‘explicit’.

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

Return type:

DataReply

kill_session(session_id, timeout=None)[source]

Send a <kill-session> request

Parameters:

  • session_id (int) – The session to be killed

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

lock(target, timeout=None)[source]

Send a <lock> request

Parameters:

  • target (str) – The datastore to be locked

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

static logger()[source]

Returns the internally used logger instance (same for all sessions)

property session_id

The session ID given in the <hello> from the server

set_rpc_timeout(timeout=120)[source]

Sets a new RPC timeout value or restores the default.

Parameters:

timeout (float,int) – Duration in seconds to wait for replies (greater zero)

If an invalid value is passed, the default value DEFAULT_RPC_TIMEOUT is set.

take_notification(block=True, timeout=None)[source]

Retrieve a notification from the incoming notification queue.

Parameters:

  • block (bool) – If True, the call will block the current thread until a notification is received or until timeout is exceeded

  • timeout (float) – The number of seconds to wait when block is True; when None, the call can block indefinitely

Return type:

Notification

unlock(target, timeout=None)[source]

Send an <unlock> request

Parameters:

  • target (str) – The datastore to be unlocked

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

validate(source, timeout=None)[source]

Send a <validate> request

Parameters:

  • source (str) – The datastore to validate

  • (optional) (float timeout) – Applies a specific timeout value for this RPC call. If given, this timeout is used instead of the set timeout.

class netconf_client.ncclient.Notification(raw, ele)[source]

A <notification> received from the server

Variables:

  • notification_xml (bytes) – The raw notification as received from the server

  • notification_ele – The lxml parsed representation of the notification

class netconf_client.ncclient.RPCReply(xml)[source]

A non-error response to an <rpc>

Variables:

xml (str) – The raw reply from the server

netconf_client.ncclient.to_ele(maybe_ele)[source]

Convert the given string to an lxml element

Parameters:

maybe_ele – If this is a string, it will be parsed by lxml. If it is already an lxml element the parameter is returned unchanged

netconf_client.session

class netconf_client.session.Session(sock)[source]

A session with a NETCONF server

This class is a context manager, and should always be either used with a with statement or the close() method should be called manually when the object is no longer required.

Variables:

  • server_capabilities – The list of capabilities parsed from the server’s <hello>

  • client_capabilities – The list of capabilities parsed from the client’s <hello>

close()[source]

Closes any associated sockets and frees any other associated resources

send_msg(msg)[source]

Sends a raw byte string to the server

Parameters:

msg (bytes) – The byte string to send

send_rpc(rpc)[source]

Sends a raw RPC to the server

Parameters:

rpc (bytes) – The RPC to send

Return type:

concurrent.futures.Future with a result type of tuple(bytes, lxml.Element)

netconf_client.error

exception netconf_client.error.InvalidSSHHostkey[source]

This exception is raised if the SSH hostkey isn’t valid

exception netconf_client.error.NetconfClientException[source]

Base class for all netconf_client exceptions

exception netconf_client.error.NetconfProtocolError[source]

This exception is raised on any NETCONF protocol error

exception netconf_client.error.RpcError(raw, ele)[source]

This exception is raised on a future from an <rpc> call that returns a corresponding <rpc-error>

Variables:

  • reply_raw – The raw text that was returned by the server

  • reply_ele – The lxml parsed representation of the reply

  • message – If present, the contents of the <error-message> tag

  • tag – If present, the contents of the <error-tag> tag

  • info – If present, the contents of the <error-info> tag

exception netconf_client.error.SessionClosedException[source]

This exception is raised on any futures when the NETCONF connection is closed