.. module:: ncclient.manager
:synopsis: High-level API
+.. data:: CAPABILITIES
+
+ List of URI strings representing the client's capabilities. This is used during the initial
+ capability exchange. Modify this if you need to announce some capability not already included.
+
+.. data:: OPERATIONS
+
+ Dictionary of method names and corresponding `~ncclient.operations.RPC` classes. `Manager` uses
+ this to lookup operations, e.g. "get_config" is mapped to `ncclient.operations.GetConfig`. It
+ is thus possible to add additional operations to the `Manager` API.
+
Factory functions
-----------------
.. function:: connect_ssh(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password, key_filename=None, allow_agent=True, look_for_keys=True])
- Initializes a NETCONF session over SSH, and creates a connected `Manager`
- instance. *host* must be specified, all the other arguments are optional and
- depend on the kind of host key verification and user authentication you want
- to complete.
+ Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must
+ be specified, all the other arguments are optional and depend on the kind of host key
+ verification and user authentication you want to complete.
- For the purpose of host key verification, on POSIX systems a user's
- :file:`~/.ssh/known_hosts` file is automatically considered. The
- *unknown_host_cb* argument specifies a callback that will be invoked when
- the server's host key cannot be verified. See
+ For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts`
+ file is automatically considered. The *unknown_host_cb* argument specifies a callback that will
+ be invoked when the server's host key cannot be verified. See
:func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
- First, ``publickey`` authentication is attempted. If a specific
- *key_filename* is specified, it will be loaded and authentication attempted
- using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys
- provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in
- the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an
- encrypted key file is encountered, the *password* argument will be used as a
- decryption passphrase.
+ First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it
+ will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an
+ SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is
+ :const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case
+ an encrypted key file is encountered, the *password* argument will be used as a decryption
+ passphrase.
- If ``publickey`` authentication fails and the *password* argument has been
- supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be
- attempted.
+ If ``publickey`` authentication fails and the *password* argument has been supplied,
+ ``password`` / ``keyboard-interactive`` SSH authentication will be attempted.
:param host: hostname or address on which to connect
:type host: `string`
:param timeout: timeout for socket connect
:type timeout: `int`
- :param unknown_host_cb: optional; callback that is invoked when host key
- verification fails
+ :param unknown_host_cb: optional; callback that is invoked when host key verification fails
:type unknown_host_cb: `function`
- :param username: username to authenticate with, if not specified the
- username of the logged-in user is used
+ :param username: username to authenticate with, if not specified the username of the logged-in
+ user is used
:type username: `string`
- :param password: password for ``password`` authentication or passphrase for
- decrypting private key files
+ :param password: password for ``password`` authentication or passphrase for decrypting
+ private key files
:type password: `string`
:param key_filename: location of a private key file on the file system
Manager
-------
-Exposes an API for RPC operations as method calls. The return type of these
-methods depends on whether we are is in :attr:`asynchronous or synchronous
-mode <ncclient.manager.Manager.async_mode>`.
+Exposes an API for RPC operations as method calls. The return type of these methods depends on
+whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`.
-In synchronous mode replies are awaited and the corresponding
-`~ncclient.operations.RPCReply` object is returned. Depending on the
-:attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, an
-*rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
+In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object
+is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`,
+an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
-However in asynchronous mode, operations return immediately with an
-`~ncclient.operations.RPC` object. Error handling and checking for whether a
-reply has been received must be dealt with manually. See the
-`~ncclient.operations.RPC` documentation for details.
+However in asynchronous mode, operations return immediately with an `~ncclient.operations.RPC`
+object. Error handling and checking for whether a reply has been received must be dealt with
+manually. See the `~ncclient.operations.RPC` documentation for details.
-Note that in case of the *get* and *get-config* operations, the reply is an
-instance of `~ncclient.operations.GetReply` which exposes the additional
-attributes :attr:`~ncclient.operations.GetReply.data`
-(as `~xml.etree.ElementTree.Element`) and
-:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary
-interest in case of these operations.
+Note that in case of the *get* and *get-config* operations, the reply is an instance of
+`~ncclient.operations.GetReply` which exposes the additional attributes
+:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
+:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case
+of these operations.
-Presence of capabilities is verified to the extent possible, and you can expect
-a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In
-case of transport-layer errors, e.g. unexpected session close,
-:exc:`~ncclient.transport.TransportError` will be raised.
+Presence of capabilities is verified to the extent possible, and you can expect a
+:exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer
+errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised.
.. class:: Manager
:param source: name of the configuration datastore being queried
:type source: `string`
- :param filter: see :ref:`filter_params`
+ :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
+ :type filter: :ref:`filter_params`
.. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
:param target: name of the configuration datastore being edited
:type target: `string`
+ :param config: configuration (must be rooted in *<config> .. </config>*)
+ :type config: `string` or `~xml.etree.ElementTree.Element`
+
:param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
:type default_operation: `string`
:param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
:type error_option: `string`
-
- :param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object
.. method:: copy_config(source, target)
- Create or replace an entire configuration datastore with the contents of
- another complete configuration datastore.
+ Create or replace an entire configuration datastore with the contents of another complete
+ configuration datastore.
- :param source: see :ref:`srctarget_params`
+ :param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
+ :type source: :ref:`srctarget_params`
- :param target: see :ref:`srctarget_params`
+ :param target: configuration datastore to use as the destination of the copy operation
+ :type target: :ref:`srctarget_params`
.. method:: delete_config(target)
Delete a configuration datastore.
- :param target: see :ref:`srctarget_params`
+ :param target: name or URL of configuration datastore to delete
+ :type: :ref:`srctarget_params`
.. method:: lock(target)
finally:
m.unlock("running")
- :param target: datastore name. See :ref:`srctarget_params`
+ :param target: name of configuration datastore to lock
+ :type target: `string`
:rtype: `~ncclient.operations.LockContext`
Retrieve running configuration and device state information.
- :param filter: see :ref:`filter_params`
+ :param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
+ :type filter: :ref:`filter_params`
.. method:: close_session()
- Request graceful termination of the NETCONF session, and also close the
- transport.
+ Request graceful termination of the NETCONF session, and also close the transport.
.. method:: kill_session(session_id)
Force the termination of a NETCONF session (not the current one!).
- :param session_id: session identifier of the NETCONF session to be
- terminated
+ :param session_id: session identifier of the NETCONF session to be terminated
:type session_id: `string`
+ .. method:: commit([confirmed=False, timeout=None])
+
+ Commit the candidate configuration as the device's new current configuration. Depends on the
+ *:candidate* capability.
+
+ A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
+ followup commit within the *timeout* interval. If no timeout is specified the confirm
+ timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
+ parameter but this is not required. Depends on the *:confirmed-commit* capability.
+
+ :param confirmed: whether this is a confirmed commit
+ :type confirmed: `bool`
+
+ :param timeout: confirm timeout in seconds
+ :type timeout: `int`
+
+ .. method:: discard_changes()
+
+ Revert the candidate configuration to the currently running configuration. Any uncommitted
+ changes are discarded.
+
+ .. method:: validate(source)
+
+ Validate the contents of the specified configuration.
+
+ :param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
+ :type source: :ref:`srctarget_params`
+
.. attribute:: async_mode
Specify whether operations are executed asynchronously (:const:`True`)
.. attribute:: raise_mode
- The raise *mode* affects what errors are raised as
- :exc:`~ncclient.operations.RPCError` exceptions.
+ Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
+ Valid values:
* ``"all"`` -- any kind of *rpc-error* (error or warning)
* ``"errors"`` -- where the *error-type* attribute says it is an error
.. attribute:: client_capabilities
- `~ncclient.capabilities.Capabilities` object representing the client's
- capabilities.
+ `~ncclient.capabilities.Capabilities` object representing the client's capabilities.
.. attribute:: server_capabilities
- `~ncclient.capabilities.Capabilities` object representing the server's
- capabilities.
+ `~ncclient.capabilities.Capabilities` object representing the server's capabilities.
.. attribute:: session_id
- The *session-id* assigned by the NETCONF server.
+ *session-id* assigned by the NETCONF server.
.. attribute:: connected
- A boolean value indicating whether currently connected to the NETCONF
- server.
+ Bolean value indicating whether currently connected to the NETCONF server.
Special kinds of parameters
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
-To keep the API clean, some parameters can take on different types.
+Some parameters can take on different types to keep the interface simple.
.. _srctarget_params:
Source and target parameters
-""""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Where an method takes a *source* or *target* argument, usually a datastore name
-or URL is expected. The latter depends on the ``:url`` capability and on whether
-the specific URL scheme is supported. Either must be specified as a `string`.
-For example, ``"running"``, ``"ftp://user:pass@host/config"``.
+Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected.
+The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported.
+Either must be specified as a `string`. For example, ``"running"``,
+``"ftp://user:pass@host/config"``.
-If the source may be a *<config>* element, e.g. as allowed for the *validate*
-RPC, it can be specified either as an XML string or an
-`~xml.etree.ElementTree.Element` object rooted in the *<config>* element.
+If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be
+specified as an XML string or an `~xml.etree.ElementTree.Element` object.
.. _filter_params:
Filter parameters
-"""""""""""""""""
+^^^^^^^^^^^^^^^^^
Where a method takes a *filter* argument, it can take on the following types:
Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
- * For ``"xpath"`` the *criteria* should be a `string` containing the XPath
- expression.
+ * For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression.
* For ``"subtree"`` the *criteria* should be an XML string or an
`~xml.etree.ElementTree.Element` object containing the criteria.
-* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element`
- object.
+* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` object.
projects / ncclient / commitdiff