4 |
4 |
.. module:: ncclient.manager
|
5 |
5 |
:synopsis: High-level API
|
6 |
6 |
|
|
7 |
.. data:: CAPABILITIES
|
|
8 |
|
|
9 |
List of URI strings representing the client's capabilities. This is used during the initial
|
|
10 |
capability exchange. Modify this if you need to announce some capability not already included.
|
|
11 |
|
|
12 |
.. data:: OPERATIONS
|
|
13 |
|
|
14 |
Dictionary of method names and corresponding `~ncclient.operations.RPC` classes. `Manager` uses
|
|
15 |
this to lookup operations, e.g. "get_config" is mapped to `ncclient.operations.GetConfig`. It
|
|
16 |
is thus possible to add additional operations to the `Manager` API.
|
|
17 |
|
7 |
18 |
Factory functions
|
8 |
19 |
-----------------
|
9 |
20 |
|
... | ... | |
11 |
22 |
|
12 |
23 |
.. 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])
|
13 |
24 |
|
14 |
|
Initializes a NETCONF session over SSH, and creates a connected `Manager`
|
15 |
|
instance. *host* must be specified, all the other arguments are optional and
|
16 |
|
depend on the kind of host key verification and user authentication you want
|
17 |
|
to complete.
|
|
25 |
Initializes a NETCONF session over SSH, and creates a connected `Manager` instance. *host* must
|
|
26 |
be specified, all the other arguments are optional and depend on the kind of host key
|
|
27 |
verification and user authentication you want to complete.
|
18 |
28 |
|
19 |
|
For the purpose of host key verification, on POSIX systems a user's
|
20 |
|
:file:`~/.ssh/known_hosts` file is automatically considered. The
|
21 |
|
*unknown_host_cb* argument specifies a callback that will be invoked when
|
22 |
|
the server's host key cannot be verified. See
|
|
29 |
For the purpose of host key verification, on -NIX systems a user's :file:`~/.ssh/known_hosts`
|
|
30 |
file is automatically considered. The *unknown_host_cb* argument specifies a callback that will
|
|
31 |
be invoked when the server's host key cannot be verified. See
|
23 |
32 |
:func:`~ncclient.transport.ssh.default_known_host_cb` for function signature.
|
24 |
33 |
|
25 |
|
First, ``publickey`` authentication is attempted. If a specific
|
26 |
|
*key_filename* is specified, it will be loaded and authentication attempted
|
27 |
|
using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys
|
28 |
|
provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in
|
29 |
|
the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an
|
30 |
|
encrypted key file is encountered, the *password* argument will be used as a
|
31 |
|
decryption passphrase.
|
|
34 |
First, ``publickey`` authentication is attempted. If a specific *key_filename* is specified, it
|
|
35 |
will be loaded and authentication attempted using it. If *allow_agent* is :const:`True` and an
|
|
36 |
SSH agent is running, the keys provided by the agent will be tried. If *look_for_keys* is
|
|
37 |
:const:`True`, keys in the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case
|
|
38 |
an encrypted key file is encountered, the *password* argument will be used as a decryption
|
|
39 |
passphrase.
|
32 |
40 |
|
33 |
|
If ``publickey`` authentication fails and the *password* argument has been
|
34 |
|
supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be
|
35 |
|
attempted.
|
|
41 |
If ``publickey`` authentication fails and the *password* argument has been supplied,
|
|
42 |
``password`` / ``keyboard-interactive`` SSH authentication will be attempted.
|
36 |
43 |
|
37 |
44 |
:param host: hostname or address on which to connect
|
38 |
45 |
:type host: `string`
|
... | ... | |
43 |
50 |
:param timeout: timeout for socket connect
|
44 |
51 |
:type timeout: `int`
|
45 |
52 |
|
46 |
|
:param unknown_host_cb: optional; callback that is invoked when host key
|
47 |
|
verification fails
|
|
53 |
:param unknown_host_cb: optional; callback that is invoked when host key verification fails
|
48 |
54 |
:type unknown_host_cb: `function`
|
49 |
55 |
|
50 |
|
:param username: username to authenticate with, if not specified the
|
51 |
|
username of the logged-in user is used
|
|
56 |
:param username: username to authenticate with, if not specified the username of the logged-in
|
|
57 |
user is used
|
52 |
58 |
:type username: `string`
|
53 |
59 |
|
54 |
|
:param password: password for ``password`` authentication or passphrase for
|
55 |
|
decrypting private key files
|
|
60 |
:param password: password for ``password`` authentication or passphrase for decrypting
|
|
61 |
private key files
|
56 |
62 |
:type password: `string`
|
57 |
63 |
|
58 |
64 |
:param key_filename: location of a private key file on the file system
|
... | ... | |
77 |
83 |
Manager
|
78 |
84 |
-------
|
79 |
85 |
|
80 |
|
Exposes an API for RPC operations as method calls. The return type of these
|
81 |
|
methods depends on whether we are is in :attr:`asynchronous or synchronous
|
82 |
|
mode <ncclient.manager.Manager.async_mode>`.
|
|
86 |
Exposes an API for RPC operations as method calls. The return type of these methods depends on
|
|
87 |
whether we are is in :attr:`asynchronous or synchronous mode <ncclient.manager.Manager.async_mode>`.
|
83 |
88 |
|
84 |
|
In synchronous mode replies are awaited and the corresponding
|
85 |
|
`~ncclient.operations.RPCReply` object is returned. Depending on the
|
86 |
|
:attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, an
|
87 |
|
*rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
|
|
89 |
In synchronous mode replies are awaited and the corresponding `~ncclient.operations.RPCReply` object
|
|
90 |
is returned. Depending on the :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`,
|
|
91 |
an *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions.
|
88 |
92 |
|
89 |
|
However in asynchronous mode, operations return immediately with an
|
90 |
|
`~ncclient.operations.RPC` object. Error handling and checking for whether a
|
91 |
|
reply has been received must be dealt with manually. See the
|
92 |
|
`~ncclient.operations.RPC` documentation for details.
|
|
93 |
However in asynchronous mode, operations return immediately with an `~ncclient.operations.RPC`
|
|
94 |
object. Error handling and checking for whether a reply has been received must be dealt with
|
|
95 |
manually. See the `~ncclient.operations.RPC` documentation for details.
|
93 |
96 |
|
94 |
|
Note that in case of the *get* and *get-config* operations, the reply is an
|
95 |
|
instance of `~ncclient.operations.GetReply` which exposes the additional
|
96 |
|
attributes :attr:`~ncclient.operations.GetReply.data`
|
97 |
|
(as `~xml.etree.ElementTree.Element`) and
|
98 |
|
:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary
|
99 |
|
interest in case of these operations.
|
|
97 |
Note that in case of the *get* and *get-config* operations, the reply is an instance of
|
|
98 |
`~ncclient.operations.GetReply` which exposes the additional attributes
|
|
99 |
:attr:`~ncclient.operations.GetReply.data` (as `~xml.etree.ElementTree.Element`) and
|
|
100 |
:attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary interest in case
|
|
101 |
of these operations.
|
100 |
102 |
|
101 |
|
Presence of capabilities is verified to the extent possible, and you can expect
|
102 |
|
a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In
|
103 |
|
case of transport-layer errors, e.g. unexpected session close,
|
104 |
|
:exc:`~ncclient.transport.TransportError` will be raised.
|
|
103 |
Presence of capabilities is verified to the extent possible, and you can expect a
|
|
104 |
:exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In case of transport-layer
|
|
105 |
errors, e.g. unexpected session close, :exc:`~ncclient.transport.TransportError` will be raised.
|
105 |
106 |
|
106 |
107 |
.. class:: Manager
|
107 |
108 |
|
... | ... | |
128 |
129 |
:param source: name of the configuration datastore being queried
|
129 |
130 |
:type source: `string`
|
130 |
131 |
|
131 |
|
:param filter: see :ref:`filter_params`
|
|
132 |
:param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
|
|
133 |
:type filter: :ref:`filter_params`
|
132 |
134 |
|
133 |
135 |
.. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None])
|
134 |
136 |
|
... | ... | |
139 |
141 |
:param target: name of the configuration datastore being edited
|
140 |
142 |
:type target: `string`
|
141 |
143 |
|
|
144 |
:param config: configuration (must be rooted in *<config> .. </config>*)
|
|
145 |
:type config: `string` or `~xml.etree.ElementTree.Element`
|
|
146 |
|
142 |
147 |
:param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` }
|
143 |
148 |
:type default_operation: `string`
|
144 |
149 |
|
... | ... | |
147 |
152 |
|
148 |
153 |
:param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` }
|
149 |
154 |
:type error_option: `string`
|
150 |
|
|
151 |
|
:param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object
|
152 |
155 |
|
153 |
156 |
.. method:: copy_config(source, target)
|
154 |
157 |
|
155 |
|
Create or replace an entire configuration datastore with the contents of
|
156 |
|
another complete configuration datastore.
|
|
158 |
Create or replace an entire configuration datastore with the contents of another complete
|
|
159 |
configuration datastore.
|
157 |
160 |
|
158 |
|
:param source: see :ref:`srctarget_params`
|
|
161 |
:param source: configuration datastore to use as the source of the copy operation or *<config>* element containing the configuration subtree to copy
|
|
162 |
:type source: :ref:`srctarget_params`
|
159 |
163 |
|
160 |
|
:param target: see :ref:`srctarget_params`
|
|
164 |
:param target: configuration datastore to use as the destination of the copy operation
|
|
165 |
:type target: :ref:`srctarget_params`
|
161 |
166 |
|
162 |
167 |
.. method:: delete_config(target)
|
163 |
168 |
|
164 |
169 |
Delete a configuration datastore.
|
165 |
170 |
|
166 |
|
:param target: see :ref:`srctarget_params`
|
|
171 |
:param target: name or URL of configuration datastore to delete
|
|
172 |
:type: :ref:`srctarget_params`
|
167 |
173 |
|
168 |
174 |
.. method:: lock(target)
|
169 |
175 |
|
... | ... | |
195 |
201 |
finally:
|
196 |
202 |
m.unlock("running")
|
197 |
203 |
|
198 |
|
:param target: datastore name. See :ref:`srctarget_params`
|
|
204 |
:param target: name of configuration datastore to lock
|
|
205 |
:type target: `string`
|
199 |
206 |
|
200 |
207 |
:rtype: `~ncclient.operations.LockContext`
|
201 |
208 |
|
... | ... | |
203 |
210 |
|
204 |
211 |
Retrieve running configuration and device state information.
|
205 |
212 |
|
206 |
|
:param filter: see :ref:`filter_params`
|
|
213 |
:param filter: portions of the device configuration to retrieve (by default entire configuration is retrieved)
|
|
214 |
:type filter: :ref:`filter_params`
|
207 |
215 |
|
208 |
216 |
.. method:: close_session()
|
209 |
217 |
|
210 |
|
Request graceful termination of the NETCONF session, and also close the
|
211 |
|
transport.
|
|
218 |
Request graceful termination of the NETCONF session, and also close the transport.
|
212 |
219 |
|
213 |
220 |
.. method:: kill_session(session_id)
|
214 |
221 |
|
215 |
222 |
Force the termination of a NETCONF session (not the current one!).
|
216 |
223 |
|
217 |
|
:param session_id: session identifier of the NETCONF session to be
|
218 |
|
terminated
|
|
224 |
:param session_id: session identifier of the NETCONF session to be terminated
|
219 |
225 |
:type session_id: `string`
|
220 |
226 |
|
|
227 |
.. method:: commit([confirmed=False, timeout=None])
|
|
228 |
|
|
229 |
Commit the candidate configuration as the device's new current configuration. Depends on the
|
|
230 |
*:candidate* capability.
|
|
231 |
|
|
232 |
A confirmed commit (i.e. if *confirmed* is :const:`True`) is reverted if there is no
|
|
233 |
followup commit within the *timeout* interval. If no timeout is specified the confirm
|
|
234 |
timeout defaults to 600 seconds (10 minutes). A confirming commit may have the *confirmed*
|
|
235 |
parameter but this is not required. Depends on the *:confirmed-commit* capability.
|
|
236 |
|
|
237 |
:param confirmed: whether this is a confirmed commit
|
|
238 |
:type confirmed: `bool`
|
|
239 |
|
|
240 |
:param timeout: confirm timeout in seconds
|
|
241 |
:type timeout: `int`
|
|
242 |
|
|
243 |
.. method:: discard_changes()
|
|
244 |
|
|
245 |
Revert the candidate configuration to the currently running configuration. Any uncommitted
|
|
246 |
changes are discarded.
|
|
247 |
|
|
248 |
.. method:: validate(source)
|
|
249 |
|
|
250 |
Validate the contents of the specified configuration.
|
|
251 |
|
|
252 |
:param source: name of the configuration datastore being validated or *<config>* element containing the configuration subtree to be validated
|
|
253 |
:type source: :ref:`srctarget_params`
|
|
254 |
|
221 |
255 |
.. attribute:: async_mode
|
222 |
256 |
|
223 |
257 |
Specify whether operations are executed asynchronously (:const:`True`)
|
... | ... | |
225 |
259 |
|
226 |
260 |
.. attribute:: raise_mode
|
227 |
261 |
|
228 |
|
The raise *mode* affects what errors are raised as
|
229 |
|
:exc:`~ncclient.operations.RPCError` exceptions.
|
|
262 |
Specify which errors are raised as :exc:`~ncclient.operations.RPCError` exceptions.
|
|
263 |
Valid values:
|
230 |
264 |
|
231 |
265 |
* ``"all"`` -- any kind of *rpc-error* (error or warning)
|
232 |
266 |
* ``"errors"`` -- where the *error-type* attribute says it is an error
|
... | ... | |
234 |
268 |
|
235 |
269 |
.. attribute:: client_capabilities
|
236 |
270 |
|
237 |
|
`~ncclient.capabilities.Capabilities` object representing the client's
|
238 |
|
capabilities.
|
|
271 |
`~ncclient.capabilities.Capabilities` object representing the client's capabilities.
|
239 |
272 |
|
240 |
273 |
.. attribute:: server_capabilities
|
241 |
274 |
|
242 |
|
`~ncclient.capabilities.Capabilities` object representing the server's
|
243 |
|
capabilities.
|
|
275 |
`~ncclient.capabilities.Capabilities` object representing the server's capabilities.
|
244 |
276 |
|
245 |
277 |
.. attribute:: session_id
|
246 |
278 |
|
247 |
|
The *session-id* assigned by the NETCONF server.
|
|
279 |
*session-id* assigned by the NETCONF server.
|
248 |
280 |
|
249 |
281 |
.. attribute:: connected
|
250 |
282 |
|
251 |
|
A boolean value indicating whether currently connected to the NETCONF
|
252 |
|
server.
|
|
283 |
Bolean value indicating whether currently connected to the NETCONF server.
|
253 |
284 |
|
254 |
285 |
|
255 |
286 |
Special kinds of parameters
|
256 |
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
287 |
---------------------------
|
257 |
288 |
|
258 |
|
To keep the API clean, some parameters can take on different types.
|
|
289 |
Some parameters can take on different types to keep the interface simple.
|
259 |
290 |
|
260 |
291 |
.. _srctarget_params:
|
261 |
292 |
|
262 |
293 |
Source and target parameters
|
263 |
|
""""""""""""""""""""""""""""
|
|
294 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
264 |
295 |
|
265 |
|
Where an method takes a *source* or *target* argument, usually a datastore name
|
266 |
|
or URL is expected. The latter depends on the ``:url`` capability and on whether
|
267 |
|
the specific URL scheme is supported. Either must be specified as a `string`.
|
268 |
|
For example, ``"running"``, ``"ftp://user:pass@host/config"``.
|
|
296 |
Where an method takes a *source* or *target* argument, usually a datastore name or URL is expected.
|
|
297 |
The latter depends on the ``:url`` capability and on whether the specific URL scheme is supported.
|
|
298 |
Either must be specified as a `string`. For example, ``"running"``,
|
|
299 |
``"ftp://user:pass@host/config"``.
|
269 |
300 |
|
270 |
|
If the source may be a *<config>* element, e.g. as allowed for the *validate*
|
271 |
|
RPC, it can be specified either as an XML string or an
|
272 |
|
`~xml.etree.ElementTree.Element` object rooted in the *<config>* element.
|
|
301 |
If the source may be a *<config>* element, e.g. as allowed for the *validate* RPC, it can also be
|
|
302 |
specified as an XML string or an `~xml.etree.ElementTree.Element` object.
|
273 |
303 |
|
274 |
304 |
.. _filter_params:
|
275 |
305 |
|
276 |
306 |
Filter parameters
|
277 |
|
"""""""""""""""""
|
|
307 |
^^^^^^^^^^^^^^^^^
|
278 |
308 |
|
279 |
309 |
Where a method takes a *filter* argument, it can take on the following types:
|
280 |
310 |
|
... | ... | |
282 |
312 |
|
283 |
313 |
Here *type* has to be one of ``"xpath"`` or ``"subtree"``.
|
284 |
314 |
|
285 |
|
* For ``"xpath"`` the *criteria* should be a `string` containing the XPath
|
286 |
|
expression.
|
|
315 |
* For ``"xpath"`` the *criteria* should be a `string` containing the XPath expression.
|
287 |
316 |
* For ``"subtree"`` the *criteria* should be an XML string or an
|
288 |
317 |
`~xml.etree.ElementTree.Element` object containing the criteria.
|
289 |
318 |
|
290 |
|
* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element`
|
291 |
|
object.
|
|
319 |
* A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` object.
|