1ct_netconfc(3) Erlang Module Definition ct_netconfc(3)
2
6 ct_netconfc - NETCONF client module.
7
9 NETCONF client module.
10 The NETCONF client is compliant with RFC 4741 NETCONF Configuration
12 Protocol and RFC 4742 Using the NETCONF Configuration Protocol over
13 Secure SHell (SSH).
14 Connecting to a NETCONF server
16 NETCONF sessions can either be opened by a single call to open/1,2 or
18 by a call to connect/1,2 followed by one or more calls to ses‐
19 sion/1,2,3.
20 The properties of the sessions will be exactly the same, except that
22 when using connect/1,2, you may start multiple sessions over the same
23 SSH connection. Each session is implemented as an SSH channel.
24 open/1,2 will establish one SSH connection with one SSH channel imple‐
26 menting one NETCONF session. You may start mutiple sessions by calling
27 open/1,2 multiple times, but then a new SSH connection will be estab‐
28 lished for each session.
29 For each server to test against, the following entry can be added to a
31 configuration file:
32 {server_id(),options()}.
34 The server_id() or an associated ct:target_name() must then be used in
36 calls to connect/2 or open/2.
37 If no configuration exists for a server, use connect/1 or open/1
39 instead, and specify all necessary options in the Options parameter.
40 Logging
42 The NETCONF server uses error_logger for logging of NETCONF traffic. A
44 special purpose error handler is implemented in ct_conn_log_h. To use
45 this error handler, add the cth_conn_log hook in the test suite, for
46 example:
47 suite() ->
49 [{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(),ct:conn_log_options()}]}]}].
50 conn_log_mod() is the name of the Common Test module implementing the
52 connection protocol, for example, ct_netconfc.
53 Hook option log_type specifies the type of logging:
55 raw:
57 The sent and received NETCONF data is logged to a separate text
58 file "as is" without any formatting. A link to the file is added to
59 the test case HTML log.
60 pretty:
62 The sent and received NETCONF data is logged to a separate text
63 file with XML data nicely indented. A link to the file is added to
64 the test case HTML log.
65 html (default):
67 The sent and received NETCONF traffic is pretty printed directly in
68 the test case HTML log.
69 silent:
71 NETCONF traffic is not logged.
72 By default, all NETCONF traffic is logged in one single log file. How‐
74 ever, different connections can be logged in separate files. To do
75 this, use hook option hosts and list the names of the servers/connec‐
76 tions to be used in the suite. The connections must be named for this
77 to work, that is, they must be opened with open/2.
78 Option hosts has no effect if log_type is set to html or silent.
80 The hook options can also be specified in a configuration file with
82 configuration variable ct_conn_log:
83 {ct_conn_log,[{ct:conn_log_mod(),ct:conn_log_options()}]}.
85 For example:
87 {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
89 {hosts,[ct:key_or_name()]}]}]}
90 Note:
92 Hook options specified in a configuration file overwrite the hard-coded
93 hook options in the test suite.
94 Logging Example 1:
97 The following ct_hooks statement causes pretty printing of NETCONF
99 traffic to separate logs for the connections named nc_server1 and
100 nc_server2. Any other connections are logged to default NETCONF log.
101 suite() ->
103 [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
104 {hosts,[nc_server1,nc_server2]}]}
105 ]}]}].
106 Connections must be opened as follows:
108 open(nc_server1,[...]),
110 open(nc_server2,[...]).
111 Logging Example 2:
113 The following configuration file causes raw logging of all NETCONF
115 traffic in to one single text file:
116 {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.
118 The ct_hooks statement must look as follows:
120 suite() ->
122 [{ct_hooks, [{cth_conn_log, []}]}].
123 The same ct_hooks statement without the configuration file would cause
125 HTML logging of all NETCONF connections in to the test case HTML log.
126 Notifications
128 The NETCONF client is also compliant with RFC 5277 NETCONF Event Noti‐
130 fications, which defines a mechanism for an asynchronous message noti‐
131 fication delivery service for the NETCONF protocol.
132 Specific functions to support this are create_subscription/1-6 and
134 get_event_streams/1-3.
135 Default Timeout
137 Most of the functions in this module have one variant with a Timeout
139 parameter, and one without. If nothing else is specified, the default
140 value infinity is used when the Timeout parameter is not given.
141
143 client() = handle() | server_id() | ct:target_name()
144 error_reason() = term()
146 event_time() = {eventTime, xml_attributes(), [xs_datetime()]}
148 handle()
150 Opaque reference for a connection to a NETCONF server or a NET‐
152 CONF session.
153 host() = inet:hostname() | inet:ip_address()
155 netconf_db() = running | startup | candidate
157 notification() =
159 {notification, xml_attributes(), notification_content()}
160 notification_content() = [event_time() | simple_xml()]
162 option() =
164 {ssh, host()} |
165 {port, inet:port_number()} |
166 {user, string()} |
167 {password, string()} |
168 {user_dir, string()} |
169 {timeout, timeout()}
170 SshConnectOption is any valid option to ssh:connect/3,4. Common
172 options used are user, password and user_dir. The SshConnectOp‐
173 tions are verfied by the SSH application.
174 options() = [option()]
176 Options used for setting up an SSH connection to a NETCONF
178 server.
179 server_id() = atom()
181 The identity of a server, specified in a configuration file.
183 simple_xml() =
185 {xml_tag(), xml_attributes(), xml_content()} |
186 {xml_tag(), xml_content()} |
187 xml_tag()
188 This type is further described in application xmerl.
190 stream_data() =
192 {description, string()} |
193 {replaySupport, string()} |
194 {replayLogCreationTime, string()} |
195 {replayLogAgedTime, string()}
196 For details about the data format for the string values, see
198 "XML Schema for Event Notifications" in RFC 5277.
199 stream_name() = string()
201 streams() = [{stream_name(), [stream_data()]}]
203 xml_attribute_tag() = atom()
205 xml_attribute_value() = string()
207 xml_attributes() =
209 [{xml_attribute_tag(), xml_attribute_value()}]
210 xml_content() = [simple_xml() | iolist()]
212 xml_tag() = atom()
214 xpath() = {xpath, string()}
216 xs_datetime() = string()
218 This date and time identifier has the same format as the XML
220 type dateTime and is compliant with RFC 3339 Date and Time on
221 the Internet Timestamps. The format is as follows:
222 [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
224
226 action(Client, Action) -> Result
227 action(Client, Action, Timeout) -> Result
229 Types:
231 Client = client()
233 Action = simple_xml()
234 Timeout = timeout()
235 Result = ok | {ok, [simple_xml()]} | {error, error_reason()}
236 Executes an action. If the return type is void, ok is returned
238 instead of {ok,[simple_xml()]}.
239 close_session(Client) -> Result
241 close_session(Client, Timeout) -> Result
243 Types:
245 Client = client()
247 Timeout = timeout()
248 Result = ok | {error, error_reason()}
249 Requests graceful termination of the session associated with the
251 client.
252 When a NETCONF server receives a close-session request, it
254 gracefully closes the session. The server releases any locks and
255 resources associated with the session and gracefully closes any
256 associated connections. Any NETCONF requests received after a
257 close-session request are ignored.
258 connect(Options) -> Result
260 Types:
262 Options = options()
264 Result = {ok, handle()} | {error, error_reason()}
265 Opens an SSH connection to a NETCONF server.
267 If the server options are specified in a configuration file, use
269 connect/2 instead.
270 The opaque handle() reference returned from this function is
272 required as connection identifier when opening sessions over
273 this connection, see session/1,2,3.
274 Option timeout (milliseconds) is used when setting up the SSH
276 connection. It is not used for any other purposes during the
277 lifetime of the connection.
278 connect(KeyOrName, ExtraOptions) -> Result
280 Types:
282 KeyOrName = ct:key_or_name()
284 ExtraOptions = options()
285 Result = {ok, handle()} | {error, error_reason()}
286 Open an SSH connection to a named NETCONF server.
288 If KeyOrName is a configured server_id() or a target_name()
290 associated with such an Id, then the options for this server are
291 fetched from the configuration file.
292 Argument ExtraOptions is added to the options found in the con‐
294 figuration file. If the same options are specified, the values
295 from the configuration file overwrite ExtraOptions.
296 If the server is not specified in a configuration file, use con‐
298 nect/1 instead.
299 The opaque handle() reference returned from this function can be
301 used as connection identifier when opening sessions over this
302 connection, see session/1,2,3. However, if KeyOrName is a tar‐
303 get_name(), that is, if the server is named through a call to
304 ct:require/2 or a require statement in the test suite, then this
305 name can be used instead of handle().
306 Option timeout (milliseconds) is used when setting up the SSH
308 connection. It is not used for any other purposes during the
309 lifetime of the connection.
310 copy_config(Client, Target, Source) -> Result
312 copy_config(Client, Target, Source, Timeout) -> Result
314 Types:
316 Client = client()
318 Target = Source = netconf_db()
319 Timeout = timeout()
320 Result = ok | {error, error_reason()}
321 Copies configuration data.
323 Which source and target options that can be issued depends on
325 the capabilities supported by the server. That is, :candidate
326 and/or :startup are required.
327 create_subscription(Client) -> Result
329 create_subscription(Client, Stream) -> Result
330 create_subscription(Client, Stream, Filter) -> Result
331 create_subscription(Client, Stream, Filter, Timeout) -> Result
332 create_subscription(Client, Stream, Filter, StartTime, StopTime) ->
334 Result
335 create_subscription(Client,
337 Stream,
338 Filter,
339 StartTime,
340 StopTime,
341 Timeout) ->
342 Result
343 Types:
345 Client = client()
347 Stream = stream_name()
348 Filter = simple_xml() | [simple_xml()]
349 StartTime = StopTime = xs_datetime()
350 Timeout = timeout()
351 Result = ok | {error, error_reason()}
352 Creates a subscription for event notifications.
354 This function sets up a subscription for NETCONF event notifica‐
356 tions of the specified stream type, matching the specified fil‐
357 ter. The calling process receives notifications as messages of
358 type notification().
359 Only a subset of the function clauses are show above. The full
361 set of valid combinations of input parameters is as follows:
362 create_subscription(Client)
364 create_subscription(Client, Timeout)
366 create_subscription(Client, Stream)
367 create_subscription(Client, Filter)
368 create_subscription(Client, Stream, Timeout)
370 create_subscription(Client, Filter, Timeout)
371 create_subscription(Client, Stream, Filter)
372 create_subscription(Client, StartTime, StopTime)
373 create_subscription(Client, Stream, Filter, Timeout)
375 create_subscription(Client, StartTime, StopTime, Timeout)
376 create_subscription(Client, Stream, StartTime, StopTime)
377 create_subscription(Client, Filter, StartTime, StopTime)
378 create_subscription(Client, Stream, StartTime, StopTime, Timeout)
380 create_subscription(Client, Stream, Filter, StartTime, StopTime)
381 create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout)
382 Stream:
384 Optional parameter that indicates which stream of event is
385 of interest. If not present, events in the default NETCONF
386 stream are sent.
387 Filter:
389 Optional parameter that indicates which subset of all possi‐
390 ble events is of interest. The parameter format is the same
391 as that of the filter parameter in the NETCONF protocol
392 operations. If not present, all events not precluded by
393 other parameters are sent.
394 StartTime:
396 Optional parameter used to trigger the replay feature and
397 indicate that the replay is to start at the time specified.
398 If StartTime is not present, this is not a replay subscrip‐
399 tion.
400 It is not valid to specify start times that are later than
402 the current time. If StartTime is specified earlier than the
403 log can support, the replay begins with the earliest avail‐
404 able notification.
405 This parameter is of type dateTime and compliant to RFC
407 3339. Implementations must support time zones.
408 StopTime:
410 Optional parameter used with the optional replay feature to
411 indicate the newest notifications of interest. If StopTime
412 is not present, the notifications continues until the sub‐
413 scription is terminated.
414 Must be used with and be later than StartTime. Values of
416 StopTime in the future are valid. This parameter is of type
417 dateTime and compliant to RFC 3339. Implementations must
418 support time zones.
419 For more details about the event notification mechanism, see RFC
421 5277.
422 delete_config(Client, Target) -> Result
424 delete_config(Client, Target, Timeout) -> Result
426 Types:
428 Client = client()
430 Target = startup | candidate
431 Timeout = timeout()
432 Result = ok | {error, error_reason()}
433 Deletes configuration data.
435 The running configuration cannot be deleted and :candidate or
437 :startup must be advertised by the server.
438 disconnect(Conn) -> ok | {error, error_reason()}
440 Types:
442 Conn = handle()
444 Closes the given SSH connection.
446 If there are open NETCONF sessions on the connection, these will
448 be brutally aborted. To avoid this, close each session with
449 close_session/1,2
450 edit_config(Client, Target, Config) -> Result
452 edit_config(Client, Target, Config, OptParams) -> Result
454 edit_config(Client, Target, Config, Timeout) -> Result
456 edit_config(Client, Target, Config, OptParams, Timeout) -> Result
458 Types:
460 Client = client()
462 Target = netconf_db()
463 Config = simple_xml()
464 OptParams = [simple_xml()]
465 Timeout = timeout()
466 Result = ok | {error, error_reason()}
467 Edits configuration data.
469 By default only the running target is available, unless the
471 server includes :candidate or :startup in its list of capabili‐
472 ties.
473 OptParams can be used for specifying optional parameters
475 (default-operation, test-option, or error-option) to be added to
476 the edit-config request. The value must be a list containing
477 valid simple XML, for example:
478 [{'default-operation', ["none"]},
480 {'error-option', ["rollback-on-error"]}]
481 If OptParams is not given, the default value [] is used.
483 get(Client, Filter) -> Result
485 get(Client, Filter, Timeout) -> Result
487 Types:
489 Client = client()
491 Filter = simple_xml() | xpath()
492 Timeout = timeout()
493 Result = {ok, [simple_xml()]} | {error, error_reason()}
494 Gets data.
496 This operation returns both configuration and state data from
498 the server.
499 Filter type xpath can be used only if the server supports
501 :xpath.
502 get_capabilities(Client) -> Result
504 get_capabilities(Client, Timeout) -> Result
506 Types:
508 Client = client()
510 Timeout = timeout()
511 Result = [string()] | {error, error_reason()}
512 Returns the server side capabilities.
514 The following capability identifiers, defined in RFC 4741 NET‐
516 CONF Configuration Protocol, can be returned:
517 * "urn:ietf:params:netconf:base:1.0"
519 * "urn:ietf:params:netconf:capability:writable-running:1.0"
521 * "urn:ietf:params:netconf:capability:candidate:1.0"
523 * "urn:ietf:params:netconf:capability:confirmed-commit:1.0"
525 * "urn:ietf:params:netconf:capability:rollback-on-error:1.0"
527 * "urn:ietf:params:netconf:capability:startup:1.0"
529 * "urn:ietf:params:netconf:capability:url:1.0"
531 * "urn:ietf:params:netconf:capability:xpath:1.0"
533 More identifiers can exist, for example, server-side namespace.
535 get_config(Client, Source, Filter) -> Result
537 get_config(Client, Source, Filter, Timeout) -> Result
539 Types:
541 Client = client()
543 Source = netconf_db()
544 Filter = simple_xml() | xpath()
545 Timeout = timeout()
546 Result = {ok, [simple_xml()]} | {error, error_reason()}
547 Gets configuration data.
549 To be able to access another source than running, the server
551 must advertise :candidate and/or :startup.
552 Filter type xpath can be used only if the server supports
554 :xpath.
555 get_event_streams(Client) -> Result
557 get_event_streams(Client, Timeout) -> Result
559 get_event_streams(Client, Streams) -> Result
561 get_event_streams(Client, Streams, Timeout) -> Result
563 Types:
565 Client = client()
567 Streams = [stream_name()]
568 Timeout = timeout()
569 Result = {ok, streams()} | {error, error_reason()}
570 Sends a request to get the specified event streams.
572 Streams is a list of stream names. The following filter is sent
574 to the NETCONF server in a get request:
575 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
577 <streams>
578 <stream>
579 <name>StreamName1</name>
580 </stream>
581 <stream>
582 <name>StreamName2</name>
583 </stream>
584 ...
585 </streams>
586 </netconf>
587 If Streams is an empty list, all streams are requested by send‐
589 ing the following filter:
590 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
592 <streams/>
593 </netconf>
594 If more complex filtering is needed, use ct_netconfc:get/2,3 and
596 specify the exact filter according to "XML Schema for Event
597 Notifications" in RFC 5277.
598 get_session_id(Client) -> Result
600 get_session_id(Client, Timeout) -> Result
602 Types:
604 Client = client()
606 Timeout = timeout()
607 Result = integer() >= 1 | {error, error_reason()}
608 Returns the session Id associated with the specified client.
610 hello(Client) -> Result
612 hello(Client, Timeout) -> Result
614 hello(Client, Options, Timeout) -> Result
616 Types:
618 Client = handle()
620 Options = [{capability, [string()]}]
621 Timeout = timeout()
622 Result = ok | {error, error_reason()}
623 Exchanges hello messages with the server.
625 Adds optional capabilities and sends a hello message to the
627 server and waits for the return.
628 kill_session(Client, SessionId) -> Result
630 kill_session(Client, SessionId, Timeout) -> Result
632 Types:
634 Client = client()
636 SessionId = integer() >= 1
637 Timeout = timeout()
638 Result = ok | {error, error_reason()}
639 Forces termination of the session associated with the supplied
641 session Id.
642 The server side must abort any ongoing operations, release any
644 locks and resources associated with the session, and close any
645 associated connections.
646 Only if the server is in the confirmed commit phase, the config‐
648 uration is restored to its state before entering the confirmed
649 commit phase. Otherwise, no configuration rollback is performed.
650 If the specified SessionId is equal to the current session Id,
652 an error is returned.
653 lock(Client, Target) -> Result
655 lock(Client, Target, Timeout) -> Result
657 Types:
659 Client = client()
661 Target = netconf_db()
662 Timeout = timeout()
663 Result = ok | {error, error_reason()}
664 Locks the configuration target.
666 Which target parameters that can be used depends on if :candi‐
668 date and/or :startup are supported by the server. If success‐
669 full, the configuration system of the device is unavailable to
670 other clients (NETCONF, CORBA, SNMP, and so on). Locks are
671 intended to be short-lived.
672 Operation kill_session/2,3 can be used to force the release of a
674 lock owned by another NETCONF session. How this is achieved by
675 the server side is implementation-specific.
676 only_open(Options) -> Result
678 Types:
680 Options = options()
682 Result = {ok, handle()} | {error, error_reason()}
683 Opens a NETCONF session, but does not send hello.
685 As open/1, but does not send a hello message.
687 only_open(KeyOrName, ExtraOptions) -> Result
689 Types:
691 KeyOrName = ct:key_or_name()
693 ExtraOptions = options()
694 Result = {ok, handle()} | {error, error_reason()}
695 Opens a named NETCONF session, but does not send hello.
697 As open/2, but does not send a hello message.
699 open(Options) -> Result
701 Types:
703 Options = options()
705 Result = {ok, handle()} | {error, error_reason()}
706 Opens a NETCONF session and exchanges hello messages.
708 If the server options are specified in a configuration file, or
710 if a named client is needed for logging purposes (see section
711 Logging in this module), use open/2 instead.
712 The opaque handle() reference returned from this function is
714 required as client identifier when calling any other function in
715 this module.
716 Option timeout (milliseconds) is used when setting up the SSH
718 connection and when waiting for the hello message from the
719 server. It is not used for any other purposes during the life‐
720 time of the connection.
721 open(KeyOrName, ExtraOptions) -> Result
723 Types:
725 KeyOrName = ct:key_or_name()
727 ExtraOptions = options()
728 Result = {ok, handle()} | {error, error_reason()}
729 Opens a named NETCONF session and exchanges hello messages.
731 If KeyOrName is a configured server_id() or a target_name()
733 associated with such an Id, then the options for this server are
734 fetched from the configuration file.
735 Argument ExtraOptions is added to the options found in the con‐
737 figuration file. If the same options are specified, the values
738 from the configuration file overwrite ExtraOptions.
739 If the server is not specified in a configuration file, use
741 open/1 instead.
742 The opaque handle() reference returned from this function can be
744 used as client identifier when calling any other function in
745 this module. However, if KeyOrName is a target_name(), that is,
746 if the server is named through a call to ct:require/2 or a
747 require statement in the test suite, then this name can be used
748 instead of handle().
749 Option timeout (milliseconds) is used when setting up the SSH
751 connection and when waiting for the hello message from the
752 server. It is not used for any other purposes during the life‐
753 time of the connection.
754 See also ct:require/2.
756 send(Client, SimpleXml) -> Result
758 send(Client, SimpleXml, Timeout) -> Result
760 Types:
762 Client = client()
764 SimpleXml = simple_xml()
765 Timeout = timeout()
766 Result = simple_xml() | {error, error_reason()}
767 Sends an XML document to the server.
769 The specified XML document is sent "as is" to the server. This
771 function can be used for sending XML documents that cannot be
772 expressed by other interface functions in this module.
773 send_rpc(Client, SimpleXml) -> Result
775 send_rpc(Client, SimpleXml, Timeout) -> Result
777 Types:
779 Client = client()
781 SimpleXml = simple_xml()
782 Timeout = timeout()
783 Result = [simple_xml()] | {error, error_reason()}
784 Sends a NETCONF rpc request to the server.
786 The specified XML document is wrapped in a valid NETCONF rpc
788 request and sent to the server. The message-id and namespace
789 attributes are added to element rpc.
790 This function can be used for sending rpc requests that cannot
792 be expressed by other interface functions in this module.
793 session(Conn) -> Result
795 session(Conn, Options) -> Result
797 session(KeyOrName, Conn) -> Result
799 session(KeyOrName, Conn, Options) -> Result
801 Types:
803 Conn = handle()
805 Options = session_options()
806 KeyOrName = ct:key_or_name()
807 Result = {ok, handle()} | {error, error_reason()}
808 session_options() = [session_option()]
809 session_option() = {timeout, timeout()}
810 Opens a NETCONF session as a channel on the given SSH connec‐
812 tion, and exchanges hello messages with the server.
813 The opaque handle() reference returned from this function can be
815 used as client identifier when calling any other function in
816 this module. However, if KeyOrName is used and it is a tar‐
817 get_name(), that is, if the server is named through a call to
818 ct:require/2 or a require statement in the test suite, then this
819 name can be used instead of handle().
820 unlock(Client, Target) -> Result
822 unlock(Client, Target, Timeout) -> Result
824 Types:
826 Client = client()
828 Target = netconf_db()
829 Timeout = timeout()
830 Result = ok | {error, error_reason()}
831 Unlocks the configuration target.
833 If the client earlier has acquired a lock through lock/2,3, this
835 operation releases the associated lock. To access another target
836 than running, the server must support :candidate and/or
837 :startup.
838Ericsson AB common_test 1.15.4.2 ct_netconfc(3)