root / docs / source / manager.rst @ 09e50473
History | View | Annotate | Download (10.3 kB)
1 | 09e50473 | Shikhar Bhushan | :mod:`~ncclient.manager` -- High-level API |
---|---|---|---|
2 | 09e50473 | Shikhar Bhushan | ========================================== |
3 | 84e0f4f2 | Shikhar Bhushan | |
4 | 09e50473 | Shikhar Bhushan | .. module:: ncclient.manager |
5 | 09e50473 | Shikhar Bhushan | :synopsis: High-level API |
6 | 09e50473 | Shikhar Bhushan | |
7 | 09e50473 | Shikhar Bhushan | Factory functions |
8 | 09e50473 | Shikhar Bhushan | ----------------- |
9 | 09e50473 | Shikhar Bhushan | |
10 | 09e50473 | Shikhar Bhushan | A `Manager` instance is created using a factory function. |
11 | 09e50473 | Shikhar Bhushan | |
12 | 09e50473 | Shikhar Bhushan | .. 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 | 09e50473 | Shikhar Bhushan | |
14 | 09e50473 | Shikhar Bhushan | Initializes a NETCONF session over SSH, and creates a connected `Manager` |
15 | 09e50473 | Shikhar Bhushan | instance. *host* must be specified, all the other arguments are optional and |
16 | 09e50473 | Shikhar Bhushan | depend on the kind of host key verification and user authentication you want |
17 | 09e50473 | Shikhar Bhushan | to complete. |
18 | 09e50473 | Shikhar Bhushan | |
19 | 09e50473 | Shikhar Bhushan | For the purpose of host key verification, on POSIX systems a user's |
20 | 09e50473 | Shikhar Bhushan | :file:`~/.ssh/known_hosts` file is automatically considered. The |
21 | 09e50473 | Shikhar Bhushan | *unknown_host_cb* argument specifies a callback that will be invoked when |
22 | 09e50473 | Shikhar Bhushan | the server's host key cannot be verified. See |
23 | 09e50473 | Shikhar Bhushan | :func:`~ncclient.transport.ssh.default_known_host_cb` for function signature. |
24 | 09e50473 | Shikhar Bhushan | |
25 | 09e50473 | Shikhar Bhushan | First, ``publickey`` authentication is attempted. If a specific |
26 | 09e50473 | Shikhar Bhushan | *key_filename* is specified, it will be loaded and authentication attempted |
27 | 09e50473 | Shikhar Bhushan | using it. If *allow_agent* is :const:`True` and an SSH agent is running, the keys |
28 | 09e50473 | Shikhar Bhushan | provided by the agent will be tried. If *look_for_keys* is :const:`True`, keys in |
29 | 09e50473 | Shikhar Bhushan | the :file:`~/.ssh/id_rsa` and :file:`~.ssh/id_dsa` will be tried. In case an |
30 | 09e50473 | Shikhar Bhushan | encrypted key file is encountered, the *password* argument will be used as a |
31 | 09e50473 | Shikhar Bhushan | decryption passphrase. |
32 | 09e50473 | Shikhar Bhushan | |
33 | 09e50473 | Shikhar Bhushan | If ``publickey`` authentication fails and the *password* argument has been |
34 | 09e50473 | Shikhar Bhushan | supplied, ``password`` / ``keyboard-interactive`` SSH authentication will be |
35 | 09e50473 | Shikhar Bhushan | attempted. |
36 | 09e50473 | Shikhar Bhushan | |
37 | 09e50473 | Shikhar Bhushan | :param host: hostname or address on which to connect |
38 | 09e50473 | Shikhar Bhushan | :type host: `string` |
39 | 09e50473 | Shikhar Bhushan | |
40 | 09e50473 | Shikhar Bhushan | :param port: port on which to connect |
41 | 09e50473 | Shikhar Bhushan | :type port: `int` |
42 | 09e50473 | Shikhar Bhushan | |
43 | 09e50473 | Shikhar Bhushan | :param timeout: timeout for socket connect |
44 | 09e50473 | Shikhar Bhushan | :type timeout: `int` |
45 | 09e50473 | Shikhar Bhushan | |
46 | 09e50473 | Shikhar Bhushan | :param unknown_host_cb: optional; callback that is invoked when host key |
47 | 09e50473 | Shikhar Bhushan | verification fails |
48 | 09e50473 | Shikhar Bhushan | :type unknown_host_cb: `function` |
49 | 09e50473 | Shikhar Bhushan | |
50 | 09e50473 | Shikhar Bhushan | :param username: username to authenticate with, if not specified the |
51 | 09e50473 | Shikhar Bhushan | username of the logged-in user is used |
52 | 09e50473 | Shikhar Bhushan | :type username: `string` |
53 | 09e50473 | Shikhar Bhushan | |
54 | 09e50473 | Shikhar Bhushan | :param password: password for ``password`` authentication or passphrase for |
55 | 09e50473 | Shikhar Bhushan | decrypting private key files |
56 | 09e50473 | Shikhar Bhushan | :type password: `string` |
57 | 09e50473 | Shikhar Bhushan | |
58 | 09e50473 | Shikhar Bhushan | :param key_filename: location of a private key file on the file system |
59 | 09e50473 | Shikhar Bhushan | :type key_filename: `string` |
60 | 09e50473 | Shikhar Bhushan | |
61 | 09e50473 | Shikhar Bhushan | :param allow_agent: whether to try connecting to SSH agent for keys |
62 | 09e50473 | Shikhar Bhushan | :type allow_agent: `bool` |
63 | 09e50473 | Shikhar Bhushan | |
64 | 09e50473 | Shikhar Bhushan | :param look_for_keys: whether to look in usual locations for keys |
65 | 09e50473 | Shikhar Bhushan | :type look_for_keys: `bool` |
66 | 09e50473 | Shikhar Bhushan | |
67 | 09e50473 | Shikhar Bhushan | :raises: :exc:`~ncclient.transport.SSHUnknownHostError` |
68 | 09e50473 | Shikhar Bhushan | :raises: :exc:`~ncclient.transport.AuthenticationError` |
69 | 09e50473 | Shikhar Bhushan | |
70 | 09e50473 | Shikhar Bhushan | :rtype: `Manager` |
71 | 09e50473 | Shikhar Bhushan | |
72 | 09e50473 | Shikhar Bhushan | .. function:: connect() |
73 | 09e50473 | Shikhar Bhushan | |
74 | 09e50473 | Shikhar Bhushan | Same as :func:`connect_ssh`, since SSH is the default (and currently, the |
75 | 09e50473 | Shikhar Bhushan | only) transport. |
76 | 09e50473 | Shikhar Bhushan | |
77 | 09e50473 | Shikhar Bhushan | Manager |
78 | 09e50473 | Shikhar Bhushan | ------- |
79 | 09e50473 | Shikhar Bhushan | |
80 | 09e50473 | Shikhar Bhushan | Exposes an API for RPC operations as method calls. The return type of these |
81 | 09e50473 | Shikhar Bhushan | methods depends on whether we are is in :attr:`asynchronous or synchronous |
82 | 09e50473 | Shikhar Bhushan | mode <ncclient.manager.Manager.async_mode>`. |
83 | 09e50473 | Shikhar Bhushan | |
84 | 09e50473 | Shikhar Bhushan | In synchronous mode replies are awaited and the corresponding |
85 | 09e50473 | Shikhar Bhushan | `~ncclient.operations.RPCReply` object is returned. Depending on the |
86 | 09e50473 | Shikhar Bhushan | :attr:`exception raising mode <ncclient.manager.Manager.raise_mode>`, an |
87 | 09e50473 | Shikhar Bhushan | *rpc-error* in the reply may be raised as :exc:`RPCError` exceptions. |
88 | 09e50473 | Shikhar Bhushan | |
89 | 09e50473 | Shikhar Bhushan | However in asynchronous mode, operations return immediately with an |
90 | 09e50473 | Shikhar Bhushan | `~ncclient.operations.RPC` object. Error handling and checking for whether a |
91 | 09e50473 | Shikhar Bhushan | reply has been received must be dealt with manually. See the |
92 | 09e50473 | Shikhar Bhushan | `~ncclient.operations.RPC` documentation for details. |
93 | 09e50473 | Shikhar Bhushan | |
94 | 09e50473 | Shikhar Bhushan | Note that in case of the *get* and *get-config* operations, the reply is an |
95 | 09e50473 | Shikhar Bhushan | instance of `~ncclient.operations.GetReply` which exposes the additional |
96 | 09e50473 | Shikhar Bhushan | attributes :attr:`~ncclient.operations.GetReply.data` |
97 | 09e50473 | Shikhar Bhushan | (as `~xml.etree.ElementTree.Element`) and |
98 | 09e50473 | Shikhar Bhushan | :attr:`~ncclient.operations.GetReply.data_xml` (as `string`), which are of primary |
99 | 09e50473 | Shikhar Bhushan | interest in case of these operations. |
100 | 09e50473 | Shikhar Bhushan | |
101 | 09e50473 | Shikhar Bhushan | Presence of capabilities is verified to the extent possible, and you can expect |
102 | 09e50473 | Shikhar Bhushan | a :exc:`~ncclient.operations.MissingCapabilityError` if something is amiss. In |
103 | 09e50473 | Shikhar Bhushan | case of transport-layer errors, e.g. unexpected session close, |
104 | 09e50473 | Shikhar Bhushan | :exc:`~ncclient.transport.TransportError` will be raised. |
105 | 09e50473 | Shikhar Bhushan | |
106 | 09e50473 | Shikhar Bhushan | .. class:: Manager |
107 | 09e50473 | Shikhar Bhushan | |
108 | 09e50473 | Shikhar Bhushan | For details on the expected behavior of the operations and their parameters |
109 | 09e50473 | Shikhar Bhushan | refer to :rfc:`4741`. |
110 | 09e50473 | Shikhar Bhushan | |
111 | 09e50473 | Shikhar Bhushan | Manager instances are also context managers so you can use it like this:: |
112 | 09e50473 | Shikhar Bhushan | |
113 | 09e50473 | Shikhar Bhushan | with manager.connect("host") as m: |
114 | 09e50473 | Shikhar Bhushan | # do your stuff |
115 | 09e50473 | Shikhar Bhushan | |
116 | 09e50473 | Shikhar Bhushan | ... or like this:: |
117 | 09e50473 | Shikhar Bhushan | |
118 | 09e50473 | Shikhar Bhushan | m = manager.connect("host") |
119 | 09e50473 | Shikhar Bhushan | try: |
120 | 09e50473 | Shikhar Bhushan | # do your stuff |
121 | 09e50473 | Shikhar Bhushan | finally: |
122 | 09e50473 | Shikhar Bhushan | m.close() |
123 | 09e50473 | Shikhar Bhushan | |
124 | 09e50473 | Shikhar Bhushan | .. method:: get_config(source[, filter=None]) |
125 | 09e50473 | Shikhar Bhushan | |
126 | 09e50473 | Shikhar Bhushan | Retrieve all or part of a specified configuration. |
127 | 09e50473 | Shikhar Bhushan | |
128 | 09e50473 | Shikhar Bhushan | :param source: name of the configuration datastore being queried |
129 | 09e50473 | Shikhar Bhushan | :type source: `string` |
130 | 09e50473 | Shikhar Bhushan | |
131 | 09e50473 | Shikhar Bhushan | :param filter: see :ref:`filter_params` |
132 | 09e50473 | Shikhar Bhushan | |
133 | 09e50473 | Shikhar Bhushan | .. method:: edit_config(target, config[, default_operation=None, test_option=None, error_option=None]) |
134 | 09e50473 | Shikhar Bhushan | |
135 | 09e50473 | Shikhar Bhushan | Loads all or part of a specified configuration to the specified target configuration. |
136 | 09e50473 | Shikhar Bhushan | |
137 | 09e50473 | Shikhar Bhushan | The ``"rollback-on-error"`` *error_option* depends on the ``:rollback-on-error`` capability. |
138 | 09e50473 | Shikhar Bhushan | |
139 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore being edited |
140 | 09e50473 | Shikhar Bhushan | :type target: `string` |
141 | 09e50473 | Shikhar Bhushan | |
142 | 09e50473 | Shikhar Bhushan | :param default_operation: one of { ``"merge"``, ``"replace"``, or ``"none"`` } |
143 | 09e50473 | Shikhar Bhushan | :type default_operation: `string` |
144 | 09e50473 | Shikhar Bhushan | |
145 | 09e50473 | Shikhar Bhushan | :param test_option: one of { ``"test_then_set"``, ``"set"`` } |
146 | 09e50473 | Shikhar Bhushan | :type test_option: `string` |
147 | 09e50473 | Shikhar Bhushan | |
148 | 09e50473 | Shikhar Bhushan | :param error_option: one of { ``"stop-on-error"``, ``"continue-on-error"``, ``"rollback-on-error"`` } |
149 | 09e50473 | Shikhar Bhushan | :type error_option: `string` |
150 | 09e50473 | Shikhar Bhushan | |
151 | 09e50473 | Shikhar Bhushan | :param config: *<config>* element as an XML string or `~xml.etree.ElementTree.Element` object |
152 | 09e50473 | Shikhar Bhushan | |
153 | 09e50473 | Shikhar Bhushan | .. method:: copy_config(source, target) |
154 | 09e50473 | Shikhar Bhushan | |
155 | 09e50473 | Shikhar Bhushan | Create or replace an entire configuration datastore with the contents of |
156 | 09e50473 | Shikhar Bhushan | another complete configuration datastore. |
157 | 09e50473 | Shikhar Bhushan | |
158 | 09e50473 | Shikhar Bhushan | :param source: see :ref:`srctarget_params` |
159 | 09e50473 | Shikhar Bhushan | |
160 | 09e50473 | Shikhar Bhushan | :param target: see :ref:`srctarget_params` |
161 | 09e50473 | Shikhar Bhushan | |
162 | 09e50473 | Shikhar Bhushan | .. method:: delete_config(target) |
163 | 09e50473 | Shikhar Bhushan | |
164 | 09e50473 | Shikhar Bhushan | Delete a configuration datastore. |
165 | 09e50473 | Shikhar Bhushan | |
166 | 09e50473 | Shikhar Bhushan | :param target: see :ref:`srctarget_params` |
167 | 09e50473 | Shikhar Bhushan | |
168 | 09e50473 | Shikhar Bhushan | .. method:: lock(target) |
169 | 09e50473 | Shikhar Bhushan | |
170 | 09e50473 | Shikhar Bhushan | Allows the client to lock the configuration system of a device. |
171 | 09e50473 | Shikhar Bhushan | |
172 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore to lock |
173 | 09e50473 | Shikhar Bhushan | :type target: `string` |
174 | 09e50473 | Shikhar Bhushan | |
175 | 09e50473 | Shikhar Bhushan | .. method:: unlock(target) |
176 | 09e50473 | Shikhar Bhushan | |
177 | 09e50473 | Shikhar Bhushan | Release a configuration lock, previously obtained with the |
178 | 09e50473 | Shikhar Bhushan | :meth:`~ncclient.manager.Manager.lock` operation. |
179 | 09e50473 | Shikhar Bhushan | |
180 | 09e50473 | Shikhar Bhushan | :param target: name of the configuration datastore to unlock |
181 | 09e50473 | Shikhar Bhushan | :type target: `string` |
182 | 09e50473 | Shikhar Bhushan | |
183 | 09e50473 | Shikhar Bhushan | .. method:: locked(target) |
184 | 09e50473 | Shikhar Bhushan | |
185 | 09e50473 | Shikhar Bhushan | Returns a context manager for a lock on a datastore, e.g.:: |
186 | 09e50473 | Shikhar Bhushan | |
187 | 09e50473 | Shikhar Bhushan | with m.locked("running"): |
188 | 09e50473 | Shikhar Bhushan | # do your stuff |
189 | 09e50473 | Shikhar Bhushan | |
190 | 09e50473 | Shikhar Bhushan | ... instead of:: |
191 | 09e50473 | Shikhar Bhushan | |
192 | 09e50473 | Shikhar Bhushan | m.lock("running") |
193 | 09e50473 | Shikhar Bhushan | try: |
194 | 09e50473 | Shikhar Bhushan | # do your stuff |
195 | 09e50473 | Shikhar Bhushan | finally: |
196 | 09e50473 | Shikhar Bhushan | m.unlock("running") |
197 | 09e50473 | Shikhar Bhushan | |
198 | 09e50473 | Shikhar Bhushan | :param target: datastore name. See :ref:`srctarget_params` |
199 | 09e50473 | Shikhar Bhushan | |
200 | 09e50473 | Shikhar Bhushan | :rtype: `~ncclient.operations.LockContext` |
201 | 09e50473 | Shikhar Bhushan | |
202 | 09e50473 | Shikhar Bhushan | .. method:: get([filter=None]) |
203 | 09e50473 | Shikhar Bhushan | |
204 | 09e50473 | Shikhar Bhushan | Retrieve running configuration and device state information. |
205 | 09e50473 | Shikhar Bhushan | |
206 | 09e50473 | Shikhar Bhushan | :param filter: see :ref:`filter_params` |
207 | 09e50473 | Shikhar Bhushan | |
208 | 09e50473 | Shikhar Bhushan | .. method:: close_session() |
209 | 09e50473 | Shikhar Bhushan | |
210 | 09e50473 | Shikhar Bhushan | Request graceful termination of the NETCONF session, and also close the |
211 | 09e50473 | Shikhar Bhushan | transport. |
212 | 09e50473 | Shikhar Bhushan | |
213 | 09e50473 | Shikhar Bhushan | .. method:: kill_session(session_id) |
214 | 09e50473 | Shikhar Bhushan | |
215 | 09e50473 | Shikhar Bhushan | Force the termination of a NETCONF session (not the current one!). |
216 | 09e50473 | Shikhar Bhushan | |
217 | 09e50473 | Shikhar Bhushan | :param session_id: session identifier of the NETCONF session to be |
218 | 09e50473 | Shikhar Bhushan | terminated |
219 | 09e50473 | Shikhar Bhushan | :type session_id: `string` |
220 | 09e50473 | Shikhar Bhushan | |
221 | 09e50473 | Shikhar Bhushan | .. attribute:: async_mode |
222 | 09e50473 | Shikhar Bhushan | |
223 | 09e50473 | Shikhar Bhushan | Specify whether operations are executed asynchronously (:const:`True`) |
224 | 09e50473 | Shikhar Bhushan | or synchronously (:const:`False`) (the default). |
225 | 09e50473 | Shikhar Bhushan | |
226 | 09e50473 | Shikhar Bhushan | .. attribute:: raise_mode |
227 | 09e50473 | Shikhar Bhushan | |
228 | 09e50473 | Shikhar Bhushan | The raise *mode* affects what errors are raised as |
229 | 09e50473 | Shikhar Bhushan | :exc:`~ncclient.operations.RPCError` exceptions. |
230 | 09e50473 | Shikhar Bhushan | |
231 | 09e50473 | Shikhar Bhushan | * ``"all"`` -- any kind of *rpc-error* (error or warning) |
232 | 09e50473 | Shikhar Bhushan | * ``"errors"`` -- where the *error-type* attribute says it is an error |
233 | 09e50473 | Shikhar Bhushan | * ``"none"`` -- neither |
234 | 09e50473 | Shikhar Bhushan | |
235 | 09e50473 | Shikhar Bhushan | .. attribute:: client_capabilities |
236 | 09e50473 | Shikhar Bhushan | |
237 | 09e50473 | Shikhar Bhushan | `~ncclient.capabilities.Capabilities` object representing the client's |
238 | 09e50473 | Shikhar Bhushan | capabilities. |
239 | 09e50473 | Shikhar Bhushan | |
240 | 09e50473 | Shikhar Bhushan | .. attribute:: server_capabilities |
241 | 09e50473 | Shikhar Bhushan | |
242 | 09e50473 | Shikhar Bhushan | `~ncclient.capabilities.Capabilities` object representing the server's |
243 | 09e50473 | Shikhar Bhushan | capabilities. |
244 | 09e50473 | Shikhar Bhushan | |
245 | 09e50473 | Shikhar Bhushan | .. attribute:: session_id |
246 | 09e50473 | Shikhar Bhushan | |
247 | 09e50473 | Shikhar Bhushan | The *session-id* assigned by the NETCONF server. |
248 | 09e50473 | Shikhar Bhushan | |
249 | 09e50473 | Shikhar Bhushan | .. attribute:: connected |
250 | 09e50473 | Shikhar Bhushan | |
251 | 09e50473 | Shikhar Bhushan | A boolean value indicating whether currently connected to the NETCONF |
252 | 09e50473 | Shikhar Bhushan | server. |
253 | 09e50473 | Shikhar Bhushan | |
254 | 09e50473 | Shikhar Bhushan | |
255 | 09e50473 | Shikhar Bhushan | Special kinds of parameters |
256 | 09e50473 | Shikhar Bhushan | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
257 | 09e50473 | Shikhar Bhushan | |
258 | 09e50473 | Shikhar Bhushan | To keep the API clean, some parameters can take on different types. |
259 | 09e50473 | Shikhar Bhushan | |
260 | 09e50473 | Shikhar Bhushan | .. _srctarget_params: |
261 | 09e50473 | Shikhar Bhushan | |
262 | 09e50473 | Shikhar Bhushan | Source and target parameters |
263 | 09e50473 | Shikhar Bhushan | """""""""""""""""""""""""""" |
264 | 09e50473 | Shikhar Bhushan | |
265 | 09e50473 | Shikhar Bhushan | Where an method takes a *source* or *target* argument, usually a datastore name |
266 | 09e50473 | Shikhar Bhushan | or URL is expected. The latter depends on the ``:url`` capability and on whether |
267 | 09e50473 | Shikhar Bhushan | the specific URL scheme is supported. Either must be specified as a `string`. |
268 | 09e50473 | Shikhar Bhushan | For example, ``"running"``, ``"ftp://user:pass@host/config"``. |
269 | 09e50473 | Shikhar Bhushan | |
270 | 09e50473 | Shikhar Bhushan | If the source may be a *<config>* element, e.g. as allowed for the *validate* |
271 | 09e50473 | Shikhar Bhushan | RPC, it can be specified either as an XML string or an |
272 | 09e50473 | Shikhar Bhushan | `~xml.etree.ElementTree.Element` object rooted in the *<config>* element. |
273 | 09e50473 | Shikhar Bhushan | |
274 | 09e50473 | Shikhar Bhushan | .. _filter_params: |
275 | 09e50473 | Shikhar Bhushan | |
276 | 09e50473 | Shikhar Bhushan | Filter parameters |
277 | 09e50473 | Shikhar Bhushan | """"""""""""""""" |
278 | 09e50473 | Shikhar Bhushan | |
279 | 09e50473 | Shikhar Bhushan | Where a method takes a *filter* argument, it can take on the following types: |
280 | 09e50473 | Shikhar Bhushan | |
281 | 09e50473 | Shikhar Bhushan | * A ``tuple`` of *(type, criteria)*. |
282 | 09e50473 | Shikhar Bhushan | |
283 | 09e50473 | Shikhar Bhushan | Here *type* has to be one of ``"xpath"`` or ``"subtree"``. |
284 | 09e50473 | Shikhar Bhushan | |
285 | 09e50473 | Shikhar Bhushan | * For ``"xpath"`` the *criteria* should be a `string` containing the XPath |
286 | 09e50473 | Shikhar Bhushan | expression. |
287 | 09e50473 | Shikhar Bhushan | * For ``"subtree"`` the *criteria* should be an XML string or an |
288 | 09e50473 | Shikhar Bhushan | `~xml.etree.ElementTree.Element` object containing the criteria. |
289 | 09e50473 | Shikhar Bhushan | |
290 | 09e50473 | Shikhar Bhushan | * A *<filter>* element as an XML string or an `~xml.etree.ElementTree.Element` |
291 | 09e50473 | Shikhar Bhushan | object. |