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 event_time() = {eventTime, xml_attributes(), [xs_datetime()]}
158 notification_content() = [event_time() | simple_xml()]
160 notification() =
162 {notification, xml_attributes(), notification_content()}
163 Event notification messages sent as a result of calls to cre‐
165 ate_subscription/2,3.
166 option() =
168 {host | ssh, host()} |
169 {port, inet:port_number()} |
170 {timeout, timeout()} |
171 {capability, string() | [string()]} |
172 ssh:client_option()
173 Options host and port specify the server endpoint to which to
175 connect, and are passed directly to ssh:connect/4, as are arbi‐
176 trary ssh options. Common options are user, password and
177 user_dir.
178 Option timeout specifies the number of milliseconds to allow for
180 connection establishment and, if the function in question
181 results in an outgoing hello message, reception of the server
182 hello. The timeout applies to connection and hello indepen‐
183 dently; one timeout for connection establishment, another for
184 hello reception.
185 Option capability specifies the content of a corresponding ele‐
187 ment in an outgoing hello message, each option specifying the
188 content of a single element. If no base NETCONF capability is
189 configured then the RFC 4741 1.0 capability,
190 "urn:ietf:params:netconf:base:1.0", is added, otherwise not. In
191 particular, the RFC 6241 1.1 capability must be explicitly con‐
192 figured. NETCONF capabilities can be specified using the short‐
193 hand notation defined in RFC 6241, any capability string start‐
194 ing with a colon being prefixed by either "urn:ietf:params:net‐
195 conf" or "urn:ietf:params:netconf:capability", as appropriate.
196 Capability options are ignored by connect/1-3 and only_open/1-2,
198 which don't result in an outgoing hello message.
199 server_id() = atom()
201 Identity of connection or session configuration in a configura‐
203 tion file.
204 stream_data() =
206 {description, string()} |
207 {replaySupport, string()} |
208 {replayLogCreationTime, string()} |
209 {replayLogAgedTime, string()}
210 stream_name() = string()
212 streams() = [{stream_name(), [stream_data()]}]
214 Stream information as returned by get_event_streams/1-3. See RFC
216 5277, "XML Schema for Event Notifications", for detail on the
217 format of the string values.
218 xml_attribute_tag() = atom()
220 xml_attribute_value() = string()
222 xml_attributes() =
224 [{xml_attribute_tag(), xml_attribute_value()}]
225 xml_content() = [simple_xml() | iolist()]
227 xml_tag() = atom()
229 simple_xml() =
231 {xml_tag(), xml_attributes(), xml_content()} |
232 {xml_tag(), xml_content()} |
233 xml_tag()
234 Representation of XML, as described in application xmerl.
236 xpath() = {xpath, string()}
238 error_reason() = term()
240 host() = inet:hostname() | inet:ip_address()
242 netconf_db() = running | startup | candidate
244
246 action(Client, Action) -> Result
247 action(Client, Action, Timeout) -> Result
249 Types:
251 Client = client()
253 Action = simple_xml()
254 Timeout = timeout()
255 Result = ok | {ok, [simple_xml()]} | {error, error_reason()}
256 Executes an action. If the return type is void, ok is returned
258 instead of {ok,[simple_xml()]}.
259 close_session(Client) -> Result
261 close_session(Client, Timeout) -> Result
263 Types:
265 Client = client()
267 Timeout = timeout()
268 Result = ok | {error, error_reason()}
269 Requests graceful termination of the session associated with the
271 client.
272 When a NETCONF server receives a close-session request, it
274 gracefully closes the session. The server releases any locks and
275 resources associated with the session and gracefully closes any
276 associated connections. Any NETCONF requests received after a
277 close-session request are ignored.
278 connect(Options) -> Result
280 Types:
282 Options = [option()]
284 Result = {ok, handle()} | {error, error_reason()}
285 Opens an SSH connection to a NETCONF server.
287 If the server options are specified in a configuration file, use
289 connect/2 instead.
290 The opaque handle() reference returned from this function is
292 required as connection identifier when opening sessions over
293 this connection, see session/1-3.
294 connect(KeyOrName, ExtraOptions) -> Result
296 Types:
298 KeyOrName = ct:key_or_name()
300 ExtraOptions = [option()]
301 Result = {ok, handle()} | {error, error_reason()}
302 Open an SSH connection to a named NETCONF server.
304 If KeyOrName is a configured server_id() or a target_name()
306 associated with such an Id, then the options for this server are
307 fetched from the configuration file.
308 The options list is added to those of the configuration file. If
310 an option is specified in both lists, the configuration file
311 takes precedence.
312 If the server is not specified in a configuration file, use con‐
314 nect/1 instead.
315 The opaque handle() reference returned from this function can be
317 used as connection identifier when opening sessions over this
318 connection, see session/1-3. However, if KeyOrName is a tar‐
319 get_name(), that is, if the server is named through a call to
320 ct:require/2 or a require statement in the test suite, then this
321 name can be used instead of handle().
322 copy_config(Client, Target, Source) -> Result
324 copy_config(Client, Target, Source, Timeout) -> Result
326 Types:
328 Client = client()
330 Target = Source = netconf_db()
331 Timeout = timeout()
332 Result = ok | {error, error_reason()}
333 Copies configuration data.
335 Which source and target options that can be issued depends on
337 the capabilities supported by the server. That is, :candidate
338 and/or :startup are required.
339 create_subscription(Client, Values) -> Result
341 create_subscription(Client, Values, Timeout) -> Result
343 Types:
345 Client = client()
347 Values =
348 #{stream => Stream,
349 filter => Filter,
350 start => StartTime,
351 stop => StopTime}
352 Stream = stream_name()
353 Filter = simple_xml() | [simple_xml()]
354 StartTime = StopTime = xs_datetime()
355 Timeout = timeout()
356 Result = ok | {error, error_reason()}
357 Creates a subscription for event notifications by sending an RFC
359 5277 create-subscription RPC to the server. The calling process
360 receives events as messages of type notification().
361 From RFC 5722, 2.1 Subscribing to Receive Event Notifications:
363 Stream:
365 Indicates which stream of event is of interest. If not
366 present, events in the default NETCONF stream are sent.
367 Filter:
369 Indicates which subset of all possible events is of inter‐
370 est. The parameter format is the same as that of the filter
371 parameter in the NETCONF protocol operations. If not
372 present, all events not precluded by other parameters are
373 sent.
374 StartTime:
376 Used to trigger the replay feature and indicate that the
377 replay is to start at the time specified. If StartTime is
378 not present, this is not a replay subscription. It is not
379 valid to specify start times that are later than the current
380 time. If StartTime is specified earlier than the log can
381 support, the replay begins with the earliest available noti‐
382 fication. This parameter is of type dateTime and compliant
383 to RFC 3339. Implementations must support time zones.
384 StopTime:
386 Used with the optional replay feature to indicate the newest
387 notifications of interest. If StopTime is not present, the
388 notifications continues until the subscription is termi‐
389 nated. Must be used with and be later than StartTime. Values
390 of StopTime in the future are valid. This parameter is of
391 type dateTime and compliant to RFC 3339. Implementations
392 must support time zones.
393 See RFC 5277 for more details. The requirement that StopTime
395 must only be used with StartTime is not enforced, to allow an
396 invalid request to be sent to the server.
397 Prior to OTP 22.1, this function was documented as having 15
399 variants in 6 arities. These are still exported for backwards
400 compatibility, but no longer documented. The map-based variants
401 documented above provide the same functionality with simpler
402 arguments.
403 delete_config(Client, Target) -> Result
405 delete_config(Client, Target, Timeout) -> Result
407 Types:
409 Client = client()
411 Target = startup | candidate
412 Timeout = timeout()
413 Result = ok | {error, error_reason()}
414 Deletes configuration data.
416 The running configuration cannot be deleted and :candidate or
418 :startup must be advertised by the server.
419 disconnect(Conn) -> ok | {error, error_reason()}
421 Types:
423 Conn = handle()
425 Closes the given SSH connection.
427 If there are open NETCONF sessions on the connection, these will
429 be brutally aborted. To avoid this, close each session with
430 close_session/1,2
431 edit_config(Client, Target, Config) -> Result
433 edit_config(Client, Target, Config, OptParams) -> Result
435 edit_config(Client, Target, Config, Timeout) -> Result
437 edit_config(Client, Target, Config, OptParams, Timeout) -> Result
439 Types:
441 Client = client()
443 Target = netconf_db()
444 Config = simple_xml() | [simple_xml()]
445 OptParams = [simple_xml()]
446 Timeout = timeout()
447 Result = ok | {error, error_reason()}
448 Edits configuration data.
450 By default only the running target is available, unless the
452 server includes :candidate or :startup in its list of capabili‐
453 ties.
454 OptParams can be used for specifying optional parameters
456 (default-operation, test-option, or error-option) to be added to
457 the edit-config request. The value must be a list containing
458 valid simple XML, for example:
459 [{'default-operation', ["none"]},
461 {'error-option', ["rollback-on-error"]}]
462 If OptParams is not given, the default value [] is used.
464 get(Client, Filter) -> Result
466 get(Client, Filter, Timeout) -> Result
468 Types:
470 Client = client()
472 Filter = simple_xml() | xpath()
473 Timeout = timeout()
474 Result = {ok, [simple_xml()]} | {error, error_reason()}
475 Gets data.
477 This operation returns both configuration and state data from
479 the server.
480 Filter type xpath can be used only if the server supports
482 :xpath.
483 get_capabilities(Client) -> Result
485 get_capabilities(Client, Timeout) -> Result
487 Types:
489 Client = client()
491 Timeout = timeout()
492 Result = [string()] | {error, error_reason()}
493 Returns the server capabilities as received in its hello mes‐
495 sage.
496 get_config(Client, Source, Filter) -> Result
498 get_config(Client, Source, Filter, Timeout) -> Result
500 Types:
502 Client = client()
504 Source = netconf_db()
505 Filter = simple_xml() | xpath()
506 Timeout = timeout()
507 Result = {ok, [simple_xml()]} | {error, error_reason()}
508 Gets configuration data.
510 To be able to access another source than running, the server
512 must advertise :candidate and/or :startup.
513 Filter type xpath can be used only if the server supports
515 :xpath.
516 get_event_streams(Client) -> Result
518 get_event_streams(Client, Timeout) -> Result
520 get_event_streams(Client, Streams) -> Result
522 get_event_streams(Client, Streams, Timeout) -> Result
524 Types:
526 Client = client()
528 Streams = [stream_name()]
529 Timeout = timeout()
530 Result = {ok, streams()} | {error, error_reason()}
531 Sends a request to get the specified event streams.
533 Streams is a list of stream names. The following filter is sent
535 to the NETCONF server in a get request:
536 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
538 <streams>
539 <stream>
540 <name>StreamName1</name>
541 </stream>
542 <stream>
543 <name>StreamName2</name>
544 </stream>
545 ...
546 </streams>
547 </netconf>
548 If Streams is an empty list, all streams are requested by send‐
550 ing the following filter:
551 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
553 <streams/>
554 </netconf>
555 If more complex filtering is needed, use ct_netconfc:get/2,3 and
557 specify the exact filter according to "XML Schema for Event
558 Notifications" in RFC 5277.
559 get_session_id(Client) -> Result
561 get_session_id(Client, Timeout) -> Result
563 Types:
565 Client = client()
567 Timeout = timeout()
568 Result = integer() >= 1 | {error, error_reason()}
569 Returns the session Id associated with the specified client.
571 hello(Client) -> Result
573 hello(Client, Timeout) -> Result
575 hello(Client, Options, Timeout) -> Result
577 Types:
579 Client = handle()
581 Options = [{capability, [string()]}]
582 Timeout = timeout()
583 Result = ok | {error, error_reason()}
584 Exchanges hello messages with the server. Returns when the
586 server hello has been received or after the specified timeout.
587 Note that capabilities for an outgoing hello can be passed
589 directly to open/2.
590 kill_session(Client, SessionId) -> Result
592 kill_session(Client, SessionId, Timeout) -> Result
594 Types:
596 Client = client()
598 SessionId = integer() >= 1
599 Timeout = timeout()
600 Result = ok | {error, error_reason()}
601 Forces termination of the session associated with the supplied
603 session Id.
604 The server side must abort any ongoing operations, release any
606 locks and resources associated with the session, and close any
607 associated connections.
608 Only if the server is in the confirmed commit phase, the config‐
610 uration is restored to its state before entering the confirmed
611 commit phase. Otherwise, no configuration rollback is performed.
612 If the specified SessionId is equal to the current session Id,
614 an error is returned.
615 lock(Client, Target) -> Result
617 lock(Client, Target, Timeout) -> Result
619 Types:
621 Client = client()
623 Target = netconf_db()
624 Timeout = timeout()
625 Result = ok | {error, error_reason()}
626 Locks the configuration target.
628 Which target parameters that can be used depends on if :candi‐
630 date and/or :startup are supported by the server. If success‐
631 full, the configuration system of the device is unavailable to
632 other clients (NETCONF, CORBA, SNMP, and so on). Locks are
633 intended to be short-lived.
634 Operation kill_session/2,3 can be used to force the release of a
636 lock owned by another NETCONF session. How this is achieved by
637 the server side is implementation-specific.
638 only_open(Options) -> Result
640 Types:
642 Options = [option()]
644 Result = {ok, handle()} | {error, error_reason()}
645 Opens a NETCONF session, but does not send hello.
647 As open/1, but does not send a hello message.
649 only_open(KeyOrName, ExtraOptions) -> Result
651 Types:
653 KeyOrName = ct:key_or_name()
655 ExtraOptions = [option()]
656 Result = {ok, handle()} | {error, error_reason()}
657 Opens a named NETCONF session, but does not send hello.
659 As open/2, but does not send a hello message.
661 open(Options) -> Result
663 Types:
665 Options = [option()]
667 Result = {ok, handle()} | {error, error_reason()}
668 Opens a NETCONF session and exchanges hello messages.
670 If the server options are specified in a configuration file, or
672 if a named client is needed for logging purposes (see section
673 Logging in this module), use open/2 instead.
674 The opaque handle() reference returned from this function is
676 required as client identifier when calling any other function in
677 this module.
678 open(KeyOrName, ExtraOption) -> Result
680 Types:
682 KeyOrName = ct:key_or_name()
684 ExtraOption = [option()]
685 Result = {ok, handle()} | {error, error_reason()}
686 Opens a named NETCONF session and exchanges hello messages.
688 If KeyOrName is a configured server_id() or a target_name()
690 associated with such an Id, then the options for this server are
691 fetched from the configuration file.
692 The options list is added to those of the configuration file. If
694 an option is specified in both lists, the configuration file
695 take precedence.
696 If the server is not specified in a configuration file, use
698 open/1 instead.
699 The opaque handle() reference returned from this function can be
701 used as client identifier when calling any other function in
702 this module. However, if KeyOrName is a target_name(), that is,
703 if the server is named through a call to ct:require/2 or a
704 require statement in the test suite, then this name can be used
705 instead of handle().
706 See also ct:require/2.
708 send(Client, SimpleXml) -> Result
710 send(Client, SimpleXml, Timeout) -> Result
712 Types:
714 Client = client()
716 SimpleXml = simple_xml()
717 Timeout = timeout()
718 Result = simple_xml() | {error, error_reason()}
719 Sends an XML document to the server.
721 The specified XML document is sent "as is" to the server. This
723 function can be used for sending XML documents that cannot be
724 expressed by other interface functions in this module.
725 send_rpc(Client, SimpleXml) -> Result
727 send_rpc(Client, SimpleXml, Timeout) -> Result
729 Types:
731 Client = client()
733 SimpleXml = simple_xml()
734 Timeout = timeout()
735 Result = [simple_xml()] | {error, error_reason()}
736 Sends a NETCONF rpc request to the server.
738 The specified XML document is wrapped in a valid NETCONF rpc
740 request and sent to the server. The message-id and namespace
741 attributes are added to element rpc.
742 This function can be used for sending rpc requests that cannot
744 be expressed by other interface functions in this module.
745 session(Conn) -> Result
747 session(Conn, Options) -> Result
749 session(KeyOrName, Conn) -> Result
751 session(KeyOrName, Conn, Options) -> Result
753 Types:
755 Conn = handle()
757 Options = [session_option()]
758 KeyOrName = ct:key_or_name()
759 Result = {ok, handle()} | {error, error_reason()}
760 session_option() =
761 {timeout, timeout()} | {capability, string() | [string()]}
762 Opens a NETCONF session as a channel on the given SSH connec‐
764 tion, and exchanges hello messages with the server.
765 The opaque handle() reference returned from this function can be
767 used as client identifier when calling any other function in
768 this module. However, if KeyOrName is used and it is a tar‐
769 get_name(), that is, if the server is named through a call to
770 ct:require/2 or a require statement in the test suite, then this
771 name can be used instead of handle().
772 unlock(Client, Target) -> Result
774 unlock(Client, Target, Timeout) -> Result
776 Types:
778 Client = client()
780 Target = netconf_db()
781 Timeout = timeout()
782 Result = ok | {error, error_reason()}
783 Unlocks the configuration target.
785 If the client earlier has acquired a lock through lock/2,3, this
787 operation releases the associated lock. To access another target
788 than running, the server must support :candidate and/or
789 :startup.
790Ericsson AB common_test 1.18 ct_netconfc(3)