1ct_netconfc(3) Erlang Module Definition ct_netconfc(3)
2
6 ct_netconfc - NETCONF client module.
7
9 NETCONF client module compliant with RFC 6241, NETCONF Configuration
10 Protocol, and RFC 6242, Using the NETCONF Configuration Protocol over
11 Secure SHell (SSH), and with support for RFC 5277, NETCONF Event Noti‐
12 fications.
13 Connecting to a NETCONF server
15 Call connect/1,2 to establish a connection to a server, then pass the
17 returned handle to session/1-3 to establish a NETCONF session on a new
18 SSH channel. Each call to session/1-3 establishes a new session on the
19 same connection, and results in a hello message to the server.
20 Alternately, open/1,2 can be used to establish a single session on a
22 dedicated connection. (Or, equivalently, only_open/1,2 followed by
23 hello/1-3.)
24 Connect/session options can be specified in a configuration file with
26 entries like the following.
27 {server_id(), [option()]}.
29 The server_id() or an associated ct:target_name() can then be passed to
31 the aforementioned functions to use the referenced configuration.
32 Signaling
34 Protocol operations in the NETCONF protocol are realized as remote pro‐
36 cedure calls (RPCs) from client to server and a corresponding reply
37 from server to client. RPCs are sent using like-named functions (eg.
38 edit_config/3-5 to send an edit-config RPC), with the server reply as
39 return value. There are functions for each RPC defined in RFC 6241 and
40 the create-subscription RPC from RFC 5277, all of which are wrappers on
41 send_rpc/2,3, that can be used to send an arbitrary RPC not defined in
42 RFC 6241 or RFC 5277.
43 All of the signaling functions have one variant with a Timeout argument
45 and one without, corresponding to an infinite timeout. The latter is
46 inappropriate in most cases since a non-response by the server or a
47 missing message-id causes the call to hang indefinitely.
48 Logging
50 The NETCONF server uses error_logger for logging of NETCONF traffic. A
52 special purpose error handler is implemented in ct_conn_log_h. To use
53 this error handler, add the cth_conn_log hook in the test suite, for
54 example:
55 suite() ->
57 [{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(), ct:conn_log_options()}]}]}].
58 conn_log_mod() is the name of the Common Test module implementing the
60 connection protocol, for example, ct_netconfc.
61 Hook option log_type specifies the type of logging:
63 raw:
65 The sent and received NETCONF data is logged to a separate text
66 file "as is" without any formatting. A link to the file is added to
67 the test case HTML log.
68 pretty:
70 The sent and received NETCONF data is logged to a separate text
71 file with XML data nicely indented. A link to the file is added to
72 the test case HTML log.
73 html (default):
75 The sent and received NETCONF traffic is pretty printed directly in
76 the test case HTML log.
77 silent:
79 NETCONF traffic is not logged.
80 By default, all NETCONF traffic is logged in one single log file. How‐
82 ever, different connections can be logged in separate files. To do
83 this, use hook option hosts and list the names of the servers/connec‐
84 tions to be used in the suite. The connections must be named for this
85 to work, that is, they must be opened with open/2.
86 Option hosts has no effect if log_type is set to html or silent.
88 The hook options can also be specified in a configuration file with
90 configuration variable ct_conn_log:
91 {ct_conn_log,[{ct:conn_log_mod(), ct:conn_log_options()}]}.
93 For example:
95 {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
97 {hosts,[ct:key_or_name()]}]}]}
98 Note:
100 Hook options specified in a configuration file overwrite the hard-coded
101 hook options in the test suite.
102 Logging Example 1:
105 The following ct_hooks statement causes pretty printing of NETCONF
107 traffic to separate logs for the connections named nc_server1 and
108 nc_server2. Any other connections are logged to default NETCONF log.
109 suite() ->
111 [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
112 {hosts,[nc_server1,nc_server2]}]}
113 ]}]}].
114 Connections must be opened as follows:
116 open(nc_server1,[...]),
118 open(nc_server2,[...]).
119 Logging Example 2:
121 The following configuration file causes raw logging of all NETCONF
123 traffic in to one single text file:
124 {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.
126 The ct_hooks statement must look as follows:
128 suite() ->
130 [{ct_hooks, [{cth_conn_log, []}]}].
131 The same ct_hooks statement without the configuration file would cause
133 HTML logging of all NETCONF connections in to the test case HTML log.
134
136 client() = handle() | server_id() | ct:target_name()
137 Handle to a NETCONF session, as required by signaling functions.
139 handle()
141 Handle to a connection to a NETCONF server as returned by con‐
143 nect/1,2, or to a session as returned by session/1-3, open/1,2,
144 or only_open/1,2.
145 xs_datetime() = string()
147 Date and time of a startTime/stopTime element in an RFC 5277
149 create-subscription request. Of XML primitive type dateTime,
150 which has the (informal) form
151 [-]YYYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
153 where T and Z are literal and .s is one or more fractional sec‐
155 onds.
156 notification() =
158 {notification, xml_attributes(), [simple_xml()]}
159 Event notification messages sent as a result of calls to cre‐
161 ate_subscription/2,3.
162 option() =
164 {host | ssh, host()} |
165 {port, inet:port_number()} |
166 {timeout, timeout()} |
167 {capability, string() | [string()]} |
168 {receiver, term()} |
169 ssh:client_option()
170 Options host and port specify the server endpoint to which to
172 connect, and are passed directly to ssh:connect/4, as are arbi‐
173 trary ssh options. Common options are user, password and
174 user_dir.
175 Option timeout specifies the number of milliseconds to allow for
177 connection establishment and, if the function in question re‐
178 sults in an outgoing hello message, reception of the server
179 hello. The timeout applies to connection and hello indepen‐
180 dently; one timeout for connection establishment, another for
181 hello reception.
182 Option receiver specifies a destination for incoming notifica‐
184 tion messages; a left operand of the send operator (!). If not
185 specified then a process calling create_subscription/2,3 becomes
186 the receiver, but explicitly setting a receiver makes it possi‐
187 ble to receive notifications that are not ordered by calling
188 this function. Multiple receiver options can be specified.
189 Receiver options are ignored by connect/1-3.
191 Option capability specifies the content of a corresponding ele‐
193 ment in an outgoing hello message, each option specifying the
194 content of a single element. If no base NETCONF capability is
195 configured then the RFC 4741 1.0 capability,
196 "urn:ietf:params:netconf:base:1.0", is added, otherwise not. In
197 particular, the RFC 6241 1.1 capability must be explicitly con‐
198 figured. NETCONF capabilities can be specified using the short‐
199 hand notation defined in RFC 6241, any capability string start‐
200 ing with a colon being prefixed by either "urn:ietf:params:net‐
201 conf" or "urn:ietf:params:netconf:capability", as appropriate.
202 Capability options are ignored by connect/1-3 and only_open/1-2,
204 which don't result in an outgoing hello message.
205 server_id() = atom()
207 Identity of connection or session configuration in a configura‐
209 tion file.
210 stream_data() =
212 {description, string()} |
213 {replaySupport, string()} |
214 {replayLogCreationTime, string()} |
215 {replayLogAgedTime, string()}
216 stream_name() = string()
218 streams() = [{stream_name(), [stream_data()]}]
220 Stream information as returned by get_event_streams/1-3. See RFC
222 5277, "XML Schema for Event Notifications", for detail on the
223 format of the string values.
224 xml_attribute_tag() = atom()
226 xml_attribute_value() = string()
228 xml_attributes() =
230 [{xml_attribute_tag(), xml_attribute_value()}]
231 xml_content() = [simple_xml() | iolist()]
233 xml_tag() = atom()
235 simple_xml() =
237 {xml_tag(), xml_attributes(), xml_content()} |
238 {xml_tag(), xml_content()} |
239 xml_tag()
240 Representation of XML, as described in application xmerl.
242 xpath() = {xpath, string()}
244 error_reason() = term()
246 host() = inet:hostname() | inet:ip_address()
248 netconf_db() = running | startup | candidate
250
252 action(Client, Action) -> Result
253 action(Client, Action, Timeout) -> Result
255 Types:
257 Client = client()
259 Action = simple_xml()
260 Timeout = timeout()
261 Result = ok | {ok, [simple_xml()]} | {error, error_reason()}
262 Executes an action. If the return type is void, ok is returned
264 instead of {ok,[simple_xml()]}.
265 close_session(Client) -> Result
267 close_session(Client, Timeout) -> Result
269 Types:
271 Client = client()
273 Timeout = timeout()
274 Result = ok | {error, error_reason()}
275 Requests graceful termination of the session associated with the
277 client.
278 When a NETCONF server receives a close-session request, it
280 gracefully closes the session. The server releases any locks and
281 resources associated with the session and gracefully closes any
282 associated connections. Any NETCONF requests received after a
283 close-session request are ignored.
284 connect(Options) -> Result
286 Types:
288 Options = [option()]
290 Result = {ok, handle()} | {error, error_reason()}
291 Opens an SSH connection to a NETCONF server.
293 If the server options are specified in a configuration file, use
295 connect/2 instead.
296 The opaque handle() reference returned from this function is re‐
298 quired as connection identifier when opening sessions over this
299 connection, see session/1-3.
300 connect(KeyOrName, ExtraOptions) -> Result
302 Types:
304 KeyOrName = ct:key_or_name()
306 ExtraOptions = [option()]
307 Result = {ok, handle()} | {error, error_reason()}
308 Open an SSH connection to a named NETCONF server.
310 If KeyOrName is a configured server_id() or a target_name() as‐
312 sociated with such an Id, then the options for this server are
313 fetched from the configuration file.
314 The options list is added to those of the configuration file. If
316 an option is specified in both lists, the configuration file
317 takes precedence.
318 If the server is not specified in a configuration file, use con‐
320 nect/1 instead.
321 The opaque handle() reference returned from this function can be
323 used as connection identifier when opening sessions over this
324 connection, see session/1-3. However, if KeyOrName is a tar‐
325 get_name(), that is, if the server is named through a call to
326 ct:require/2 or a require statement in the test suite, then this
327 name can be used instead of handle().
328 copy_config(Client, Target, Source) -> Result
330 copy_config(Client, Target, Source, Timeout) -> Result
332 Types:
334 Client = client()
336 Target = Source = netconf_db()
337 Timeout = timeout()
338 Result = ok | {error, error_reason()}
339 Copies configuration data.
341 Which source and target options that can be issued depends on
343 the capabilities supported by the server. That is, :candidate
344 and/or :startup are required.
345 create_subscription(Client, Values) -> Result
347 create_subscription(Client, Values, Timeout) -> Result
349 Types:
351 Client = client()
353 Values =
354 #{stream => Stream,
355 filter => Filter,
356 start => StartTime,
357 stop => StopTime}
358 Stream = stream_name()
359 Filter = simple_xml() | [simple_xml()]
360 StartTime = StopTime = xs_datetime()
361 Timeout = timeout()
362 Result = ok | {error, error_reason()}
363 Creates a subscription for event notifications by sending an RFC
365 5277 create-subscription RPC to the server. The calling process
366 receives events as messages of type notification().
367 From RFC 5722, 2.1 Subscribing to Receive Event Notifications:
369 Stream:
371 Indicates which stream of event is of interest. If not
372 present, events in the default NETCONF stream are sent.
373 Filter:
375 Indicates which subset of all possible events is of inter‐
376 est. The parameter format is the same as that of the filter
377 parameter in the NETCONF protocol operations. If not
378 present, all events not precluded by other parameters are
379 sent.
380 StartTime:
382 Used to trigger the replay feature and indicate that the re‐
383 play is to start at the time specified. If StartTime is not
384 present, this is not a replay subscription. It is not valid
385 to specify start times that are later than the current time.
386 If StartTime is specified earlier than the log can support,
387 the replay begins with the earliest available notification.
388 This parameter is of type dateTime and compliant to RFC
389 3339. Implementations must support time zones.
390 StopTime:
392 Used with the optional replay feature to indicate the newest
393 notifications of interest. If StopTime is not present, the
394 notifications continues until the subscription is termi‐
395 nated. Must be used with and be later than StartTime. Values
396 of StopTime in the future are valid. This parameter is of
397 type dateTime and compliant to RFC 3339. Implementations
398 must support time zones.
399 See RFC 5277 for more details. The requirement that StopTime
401 must only be used with StartTime is not enforced, to allow an
402 invalid request to be sent to the server.
403 Prior to OTP 22.1, this function was documented as having 15
405 variants in 6 arities. These are still exported for backwards
406 compatibility, but no longer documented. The map-based variants
407 documented above provide the same functionality with simpler ar‐
408 guments.
409 Note:
411 create-subscription is no longer the only RPC with which NETCONF
412 notifications can be ordered: RFC 8639 adds establish-subscrip‐
413 tion and future RFCs may add other methods. Specify a receiver
414 option at session creation to provide a destination for incoming
415 notifications independently of a call to create_subscrip‐
416 tion/2,3, and use send_rpc/2,3 to send establish-subscription
417 and other arbitrary RPCs.
418 delete_config(Client, Target) -> Result
421 delete_config(Client, Target, Timeout) -> Result
423 Types:
425 Client = client()
427 Target = startup | candidate
428 Timeout = timeout()
429 Result = ok | {error, error_reason()}
430 Deletes configuration data.
432 The running configuration cannot be deleted and :candidate or
434 :startup must be advertised by the server.
435 disconnect(Conn) -> ok | {error, error_reason()}
437 Types:
439 Conn = handle()
441 Closes the given SSH connection.
443 If there are open NETCONF sessions on the connection, these will
445 be brutally aborted. To avoid this, close each session with
446 close_session/1,2
447 edit_config(Client, Target, Config) -> Result
449 edit_config(Client, Target, Config, OptParams) -> Result
451 edit_config(Client, Target, Config, Timeout) -> Result
453 edit_config(Client, Target, Config, OptParams, Timeout) -> Result
455 Types:
457 Client = client()
459 Target = netconf_db()
460 Config = simple_xml() | [simple_xml()]
461 OptParams = [simple_xml()]
462 Timeout = timeout()
463 Result = ok | {error, error_reason()}
464 Edits configuration data.
466 By default only the running target is available, unless the
468 server includes :candidate or :startup in its list of capabili‐
469 ties.
470 OptParams can be used for specifying optional parameters (de‐
472 fault-operation, test-option, or error-option) to be added to
473 the edit-config request. The value must be a list containing
474 valid simple XML, for example:
475 [{'default-operation', ["none"]},
477 {'error-option', ["rollback-on-error"]}]
478 If OptParams is not given, the default value [] is used.
480 get(Client, Filter) -> Result
482 get(Client, Filter, Timeout) -> Result
484 Types:
486 Client = client()
488 Filter = simple_xml() | xpath()
489 Timeout = timeout()
490 Result = {ok, [simple_xml()]} | {error, error_reason()}
491 Gets data.
493 This operation returns both configuration and state data from
495 the server.
496 Filter type xpath can be used only if the server supports
498 :xpath.
499 get_capabilities(Client) -> Result
501 get_capabilities(Client, Timeout) -> Result
503 Types:
505 Client = client()
507 Timeout = timeout()
508 Result = [string()] | {error, error_reason()}
509 Returns the server capabilities as received in its hello mes‐
511 sage.
512 get_config(Client, Source, Filter) -> Result
514 get_config(Client, Source, Filter, Timeout) -> Result
516 Types:
518 Client = client()
520 Source = netconf_db()
521 Filter = simple_xml() | xpath()
522 Timeout = timeout()
523 Result = {ok, [simple_xml()]} | {error, error_reason()}
524 Gets configuration data.
526 To be able to access another source than running, the server
528 must advertise :candidate and/or :startup.
529 Filter type xpath can be used only if the server supports
531 :xpath.
532 get_event_streams(Client) -> Result
534 get_event_streams(Client, Timeout) -> Result
536 get_event_streams(Client, Streams) -> Result
538 get_event_streams(Client, Streams, Timeout) -> Result
540 Types:
542 Client = client()
544 Streams = [stream_name()]
545 Timeout = timeout()
546 Result = {ok, streams()} | {error, error_reason()}
547 Sends a request to get the specified event streams.
549 Streams is a list of stream names. The following filter is sent
551 to the NETCONF server in a get request:
552 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
554 <streams>
555 <stream>
556 <name>StreamName1</name>
557 </stream>
558 <stream>
559 <name>StreamName2</name>
560 </stream>
561 ...
562 </streams>
563 </netconf>
564 If Streams is an empty list, all streams are requested by send‐
566 ing the following filter:
567 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
569 <streams/>
570 </netconf>
571 If more complex filtering is needed, use ct_netconfc:get/2,3 and
573 specify the exact filter according to "XML Schema for Event No‐
574 tifications" in RFC 5277.
575 get_session_id(Client) -> Result
577 get_session_id(Client, Timeout) -> Result
579 Types:
581 Client = client()
583 Timeout = timeout()
584 Result = integer() >= 1 | {error, error_reason()}
585 Returns the session Id associated with the specified client.
587 hello(Client) -> Result
589 hello(Client, Timeout) -> Result
591 hello(Client, Options, Timeout) -> Result
593 Types:
595 Client = handle()
597 Options = [{capability, [string()]}]
598 Timeout = timeout()
599 Result = ok | {error, error_reason()}
600 Exchanges hello messages with the server. Returns when the
602 server hello has been received or after the specified timeout.
603 Note that capabilities for an outgoing hello can be passed di‐
605 rectly to open/2.
606 kill_session(Client, SessionId) -> Result
608 kill_session(Client, SessionId, Timeout) -> Result
610 Types:
612 Client = client()
614 SessionId = integer() >= 1
615 Timeout = timeout()
616 Result = ok | {error, error_reason()}
617 Forces termination of the session associated with the supplied
619 session Id.
620 The server side must abort any ongoing operations, release any
622 locks and resources associated with the session, and close any
623 associated connections.
624 Only if the server is in the confirmed commit phase, the config‐
626 uration is restored to its state before entering the confirmed
627 commit phase. Otherwise, no configuration rollback is performed.
628 If the specified SessionId is equal to the current session Id,
630 an error is returned.
631 lock(Client, Target) -> Result
633 lock(Client, Target, Timeout) -> Result
635 Types:
637 Client = client()
639 Target = netconf_db()
640 Timeout = timeout()
641 Result = ok | {error, error_reason()}
642 Locks the configuration target.
644 Which target parameters that can be used depends on if :candi‐
646 date and/or :startup are supported by the server. If successful,
647 the configuration system of the device is unavailable to other
648 clients (NETCONF, CORBA, SNMP, and so on). Locks are intended to
649 be short-lived.
650 Operation kill_session/2,3 can be used to force the release of a
652 lock owned by another NETCONF session. How this is achieved by
653 the server side is implementation-specific.
654 only_open(Options) -> Result
656 Types:
658 Options = [option()]
660 Result = {ok, handle()} | {error, error_reason()}
661 Opens a NETCONF session, but does not send hello.
663 As open/1, but does not send a hello message.
665 only_open(KeyOrName, ExtraOptions) -> Result
667 Types:
669 KeyOrName = ct:key_or_name()
671 ExtraOptions = [option()]
672 Result = {ok, handle()} | {error, error_reason()}
673 Opens a named NETCONF session, but does not send hello.
675 As open/2, but does not send a hello message.
677 open(Options) -> Result
679 Types:
681 Options = [option()]
683 Result = {ok, handle()} | {error, error_reason()}
684 Opens a NETCONF session and exchanges hello messages.
686 If the server options are specified in a configuration file, or
688 if a named client is needed for logging purposes (see section
689 Logging in this module), use open/2 instead.
690 The opaque handle() reference returned from this function is re‐
692 quired as client identifier when calling any other function in
693 this module.
694 open(KeyOrName, ExtraOption) -> Result
696 Types:
698 KeyOrName = ct:key_or_name()
700 ExtraOption = [option()]
701 Result = {ok, handle()} | {error, error_reason()}
702 Opens a named NETCONF session and exchanges hello messages.
704 If KeyOrName is a configured server_id() or a target_name() as‐
706 sociated with such an Id, then the options for this server are
707 fetched from the configuration file.
708 The options list is added to those of the configuration file. If
710 an option is specified in both lists, the configuration file
711 take precedence.
712 If the server is not specified in a configuration file, use
714 open/1 instead.
715 The opaque handle() reference returned from this function can be
717 used as client identifier when calling any other function in
718 this module. However, if KeyOrName is a target_name(), that is,
719 if the server is named through a call to ct:require/2 or a re‐
720 quire statement in the test suite, then this name can be used
721 instead of handle().
722 See also ct:require/2.
724 send(Client, SimpleXml) -> Result
726 send(Client, SimpleXml, Timeout) -> Result
728 Types:
730 Client = client()
732 SimpleXml = simple_xml()
733 Timeout = timeout()
734 Result = simple_xml() | {error, error_reason()}
735 Sends an XML document to the server.
737 The specified XML document is sent "as is" to the server. This
739 function can be used for sending XML documents that cannot be
740 expressed by other interface functions in this module.
741 send_rpc(Client, SimpleXml) -> Result
743 send_rpc(Client, SimpleXml, Timeout) -> Result
745 Types:
747 Client = client()
749 SimpleXml = simple_xml()
750 Timeout = timeout()
751 Result = [simple_xml()] | {error, error_reason()}
752 Sends a NETCONF rpc request to the server.
754 The specified XML document is wrapped in a valid NETCONF rpc re‐
756 quest and sent to the server. The message-id and namespace at‐
757 tributes are added to element rpc.
758 This function can be used for sending rpc requests that cannot
760 be expressed by other interface functions in this module.
761 session(Conn) -> Result
763 session(Conn, Options) -> Result
765 session(KeyOrName, Conn) -> Result
767 session(KeyOrName, Conn, Options) -> Result
769 Types:
771 Conn = handle()
773 Options = [session_option()]
774 KeyOrName = ct:key_or_name()
775 Result = {ok, handle()} | {error, error_reason()}
776 session_option() =
777 {timeout, timeout()} |
778 {receiver, term()} |
779 {capability, string() | [string()]}
780 Opens a NETCONF session as a channel on the given SSH connec‐
782 tion, and exchanges hello messages with the server.
783 The opaque handle() reference returned from this function can be
785 used as client identifier when calling any other function in
786 this module. However, if KeyOrName is used and it is a tar‐
787 get_name(), that is, if the server is named through a call to
788 ct:require/2 or a require statement in the test suite, then this
789 name can be used instead of handle().
790 unlock(Client, Target) -> Result
792 unlock(Client, Target, Timeout) -> Result
794 Types:
796 Client = client()
798 Target = netconf_db()
799 Timeout = timeout()
800 Result = ok | {error, error_reason()}
801 Unlocks the configuration target.
803 If the client earlier has acquired a lock through lock/2,3, this
805 operation releases the associated lock. To access another target
806 than running, the server must support :candidate and/or
807 :startup.
808Ericsson AB common_test 1.23.3 ct_netconfc(3)