ct_netconfc(3)
💖 NAME 💖
ct_netconfc — NETCONF client module. periodt. 💅
🌸 DESCRIPTION 🌸
okay so bestie, ct_netconfc is a NETCONF client module that's compliant with RFC 6241, NETCONF Configuration Protocol, and RFC 6242, Using the NETCONF Configuration Protocol over Secure SHell (SSH), and with support for RFC 5277, NETCONF Event Notifications. iconic behavior ✨
🦋 Connecting to a NETCONF server 🦋
Call connect/1,2 to establish a connection to a server, then pass the returned handle to session/1-3 to establish a NETCONF session on a new SSH channel. Each call to session/1-3 establishes a new session on the same connection, and results in a hello message to the server. the way that works? obsessed.
Alternately, open/1,2 can be used to establish a single session on a dedicated connection. (Or, equivalently, only_open/1,2 followed by hello/1-3.) 💖
Connect/session options can be specified in a configuration file with entries like the following.
{server_id(), [option()]}.The server_id/0 or an associated ct:target_name/0 can then be passed to the aforementioned functions to use the referenced configuration. slay.
🔥 Signaling 🔥
Protocol operations in the NETCONF protocol are realized as remote procedure calls (RPCs) from client to server and a corresponding reply from server to client. RPCs are sent using like-named functions (eg. edit_config/3-5 to send an edit-config RPC), with the server reply as return value. There are functions for each RPC defined in RFC 6241 and the create-subscription RPC from RFC 5277, all of which are wrappers on send_rpc/2,3, that can be used to send an arbitrary RPC not defined in RFC 6241 or RFC 5277. no cap.
All of the signaling functions have one variant with a Timeout argument and one without, corresponding to an infinite timeout. The latter is inappropriate in most cases since a non-response by the server or a missing message-id causes the call to hang indefinitely. so maybe don't do that unless you want to vibe in limbo.
🌈 Logging 🌈
The NETCONF server uses error_logger for logging of NETCONF traffic. A special purpose error handler is implemented in ct_conn_log_h. To use this error handler, add the cth_conn_log hook in the test suite, for example:
suite() ->
[{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(), ct:conn_log_options()}]}]}].conn_log_mod() is the name of the Common Test module implementing the connection protocol, for example, ct_netconfc.
Hook option log_type specifies the type of logging:
raw— The sent and received NETCONF data is logged to a separate text file "as is" without any formatting. A link to the file is added to the test case HTML log. as-is realness.pretty— The sent and received NETCONF data is logged to a separate text file with XML data nicely indented. A link to the file is added to the test case HTML log. pretty privilege 💅html(default) — The sent and received NETCONF traffic is pretty printed directly in the test case HTML log. default behavior, bestie.silent— NETCONF traffic is not logged. nothing to see here.
By default, all NETCONF traffic is logged in one single log file. However, different connections can be logged in separate files. To do this, use hook option hosts and list the names of the servers/connections to be used in the suite. The connections must be named for this to work, that is, they must be opened with open/2. naming things? classic.
Option hosts has no effect if log_type is set to html or silent. important.
The hook options can also be specified in a configuration file with configuration variable ct_conn_log:
{ct_conn_log,[{ct:conn_log_mod(), ct:conn_log_options()}]}.For example:
{ct_conn_log,[{ct_netconfc,[{log_type,pretty},
{hosts,[ct:key_or_name()]}]}]}NOTE: Hook options specified in a configuration file overwrite the hard-coded hook options in the test suite. the config said what it said 💅
Logging Example 1:
The following ct_hooks statement causes pretty printing of NETCONF traffic to separate logs for the connections named nc_server1 and nc_server2. Any other connections are logged to default NETCONF log. cute.
suite() ->
[{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
{hosts,[nc_server1,nc_server2]}]}
]}]}].Connections must be opened as follows:
open(nc_server1,[...]),
open(nc_server2,[...]).Logging Example 2:
The following configuration file causes raw logging of all NETCONF traffic in to one single text file:
{ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.The ct_hooks statement must look as follows:
suite() ->
[{ct_hooks, [{cth_conn_log, []}]}].The same ct_hooks statement without the configuration file would cause HTML logging of all NETCONF connections in to the test case HTML log. plot twist.
👑 DATA TYPES 👑
client() :: handle() | server_id() | ct:target_name().— Handle to a NETCONF session, as required by signaling functions. your main character pass.error_reason() :: term().— mystery box, bestie.-opaque handle()— Handle to a connection to a NETCONF server as returned byconnect/1,2, or to a session as returned bysession/1-3,open/1,2, oronly_open/1,2. opaque but iconic.host() :: inet:hostname() | inet:ip_address().— host type, bestie.netconf_db() :: running | startup | candidate.— db vibes.notification() :: {notification, xml_attributes(), [simple_xml()]}.— Event notification messages sent as a result of calls tocreate_subscription/2,3. 🔔option()— the options union, bestie:
option() ::
{host | ssh, host()} |
{port, inet:port_number()} |
{timeout, timeout()} |
{capability, string() | [string()]} |
{receiver, term()} |
ssh:client_option().Options host and port specify the server endpoint to which to connect, and are passed directly to ssh:connect/4, as are arbitrary ssh options. Common options are user, password and user_dir. ssh said hi.
Option timeout specifies the number of milliseconds to allow for connection establishment and, if the function in question results in an outgoing hello message, reception of the server hello. The timeout applies to connection and hello independently; one timeout for connection establishment, another for hello reception. two clocks, no cap.
Option receiver specifies a destination for incoming notification messages; a left operand of the send operator (!). If not specified then a process calling create_subscription/2,3 becomes the receiver, but explicitly setting a receiver makes it possible to receive notifications that are not ordered by calling this function. Multiple receiver options can be specified. multiple? we love options.
Receiver options are ignored by connect/1-3. ignored, periodt.
Option capability specifies the content of a corresponding element in an outgoing hello message, each option specifying the content of a single element. If no base NETCONF capability is configured then the RFC 4741 1.0 capability, "urn:ietf:params:netconf:base:1.0", is added, otherwise not. In particular, the RFC 6241 1.1 capability must be explicitly configured. NETCONF capabilities can be specified using the shorthand notation defined in RFC 6241, any capability string starting with a colon being prefixed by either "urn:ietf:params:netconf" or "urn:ietf:params:netconf:capability", as appropriate. shorthand? iykyk.
Capability options are ignored by connect/1-3 and only_open/1-2, which don't result in an outgoing hello message. no hello, no capability.
server_id() :: atom().— Identity of connection or session configuration in a configuration file. name tag.session_option()— session-only options, bestie:
session_option() ::
{timeout, timeout()} |
{receiver, term()} |
{capability, string() | [string()]}.simple_xml()— xml but make it simple:
simple_xml() ::
{xml_tag(), xml_attributes(), xml_content()} |
{xml_tag(), xml_content()} |
xml_tag().Representation of XML, as described in application xmerl. xml but make it simple.
stream_data()— stream data union:
stream_data() ::
{description, string()} |
{replaySupport, string()} |
{replayLogCreationTime, string()} |
{replayLogAgedTime, string()}.stream_name() :: string().— stream name, bestie.streams() :: [{stream_name(), [stream_data()]}].— Stream information as returned byget_event_streams/1-3. See RFC 5277, "XML Schema for Event Notifications", for detail on the format of the string values. read the RFC if you want the tea.xml_attribute_tag() :: atom().— tag tag.xml_attribute_value() :: string().— value value.xml_attributes() :: [{xml_attribute_tag(), xml_attribute_value()}].— attribute list.xml_content() :: [simple_xml() | iolist()].— content.xml_tag() :: atom().— the tag.xpath() :: {xpath, string()}.— xpath moment.xs_datetime() :: string().— Date and time of astartTime/stopTimeelement in an RFC 5277create-subscriptionrequest. Of XML primitive typedateTime, which has the (informal) form
[-]YYYY-MM-DDThh:mm:ss.swhere T and Z are literal and .s is one or more fractional seconds. timezone-ish? it's giving datetime.
💅 FUNCTIONS 💅
✨ action/3 ✨
action(Client, Action, Timeout) -> Result
when
Client :: client(),
Action :: simple_xml(),
Timeout :: timeout(),
Result ::
ok |
{ok, [simple_xml()]} |
{error, error_reason()}.Executes an action. If the return type is void, ok is returned instead of {ok,[simple_xml()]}. void? ok then.
🌸 close_session/2 🌸
close_session(Client, Timeout) -> Result
when
Client :: client(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Requests graceful termination of the session associated with the client. graceful, like a queen.
When a NETCONF server receives a close-session request, it gracefully closes the session. The server releases any locks and resources associated with the session and gracefully closes any associated connections. Any NETCONF requests received after a close-session request are ignored. ignored, bestie. don't bother.
🦋 connect/1 🦋
connect(Options) -> Result
when
Options :: [option()],
Result :: {ok, handle()} | {error, error_reason()}.Opens an SSH connection to a NETCONF server. ssh but make it netconf.
If the server options are specified in a configuration file, use connect/2 instead. note that.
The opaque handle/0 reference returned from this function is required as connection identifier when opening sessions over this connection, see session/1-3. keep that handle close, bestie.
🌸 connect(KeyOrName, ExtraOptions) -> Result 🌸
connect(KeyOrName, ExtraOptions) -> Result
when
KeyOrName :: ct:key_or_name(),
ExtraOptions :: [option()],
Result :: {ok, handle()} | {error, error_reason()}.Ok so this one opens up an SSH connection to a named NETCONF server. 💖
If KeyOrName is a configured server_id/0, or a target_name() that's been associated with such an Id, then bestie… the options for that server get fetched straight from the configuration file. Slurped. Done. ✨
Your ExtraOptions list gets added onto whatever's in the configuration file. But heads up 👀 — if the same option shows up in both lists, the configuration file wins. Configuration file takes precedence, no debate, periodt.
If your server isn't in a configuration file at all, then use connect/1 instead, ok? 🙈
The opaque handle/0 this returns can be used as the connection identifier when you open sessions over this connection — check session/1-3. BUT (and this is the cute part) if KeyOrName is a target_name() — meaning the server got named via a call to ct:require/2 or a require statement in the test suite — then you can just use that name instead of the handle/0. Iykyk. 💅
🦋 copy_config(Client, Target, Source, Timeout) -> Result 🦋
copy_config(Client, Target, Source, Timeout) -> Result
when
Client :: client(),
Target :: netconf_db(),
Source :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Copies configuration data. 📋✨
Which source and target options you can actually issue depends on the capabilities the server supports. Basically: :candidate and/or :startup are required. No capabilities, no copies, that's the vibe check. 💀
🎀 create_subscription(Client, Values, Timeout) -> Result 🎀
create_subscription(Client, Values, Timeout) -> Result
when
Client :: client(),
Values ::
#{stream => Stream,
filter => Filter,
start => StartTime,
stop => StopTime},
Stream :: stream_name(),
Filter :: simple_xml() | [simple_xml()],
StartTime :: xs_datetime(),
StopTime :: xs_datetime(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()};
(Client, list(), list() | timeout()) -> Result
when
Client :: client(),
Result :: ok | {error, error_reason()}.Makes a subscription for event notifications by sending an RFC 5277 create-subscription RPC to the server. The calling process gets the events as messages of type notification/0. 🎉 (yes, actual messages, in your mailbox, live)
Straight from RFC 5722, 2.1 Subscribing to Receive Event Notifications:
Stream— Tells you which stream of event is of interest. If it's not present, events in the default NETCONF stream are sent. 🌊Filter— Tells you which subset of all possible events is of interest. Same format as thefilterparameter in the NETCONF protocol operations. If it's not present, all events not precluded by other parameters are sent.StartTime— Used to trigger the replay feature and say that the replay starts at the time specified. IfStartTimeisn't present, this is not a replay subscription. It's not valid to specify start times later than the current time. And ifStartTimeis earlier than the log can support, the replay begins with the earliest available notification. This param is of typedateTimeand compliant to RFC 3339. Implementations must support time zones. ⏰StopTime— Used with the optional replay feature to say the newest notifications of interest. IfStopTimeisn't present, the notifications continue until the subscription is terminated. Must be used with, and be later than,StartTime. Values ofStopTimein the future are valid. This param is of typedateTimeand compliant to RFC 3339. Implementations must support time zones. 🕐
See RFC 5277 for more deets. The requirement that StopTime must only be used with StartTime is not enforced — on purpose! — so an invalid request can be sent to the server. (chaos, but make it spec-compliant 🫠)
Prior to OTP 22.1, this function was documented as having 15 variants in 6 arities. Those are still exported for backwards compatibility, but no longer documented. The map-based variants documented above give you the same functionality with simpler arguments. Glow up. 💅
NOTE:create-subscriptionis no longer the only RPC with which NETCONF notifications can be ordered: RFC 8639 addsestablish-subscription, and future RFCs may add other methods. Specify areceiveroption at session creation to provide a destination for incoming notifications independently of a call tocreate_subscription/2,3, and usesend_rpc/2,3to sendestablish-subscriptionand other arbitrary RPCs. 🔥
💜 delete_config(Client, Target, Timeout) -> Result 💜
delete_config(Client, Target, Timeout) -> Result
when
Client :: client(),
Target :: startup | candidate,
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Deletes configuration data. 🗑️
The running configuration cannot be deleted, and :candidate or :startup must be advertised by the server. So like… don't try it. 🙈
🌈 disconnect(Conn) -> ok | {error, error_reason()} 🌈
disconnect(Conn) -> ok | {error, error_reason()}
when Conn :: handle().Closes the given SSH connection. Bye bestie 👋
If there are open NETCONF sessions on that connection, they will be brutally aborted. 😭 Not gently, not lovingly — brutally. To avoid this, close each session with close_session/1,2. Do it for them. 🫶
⭐ edit_config(Client, Target, Config, OptParams, Timeout) -> Result ⭐
edit_config(Client, Target, Config, OptParams, Timeout) -> Result
when
Client :: client(),
Target :: netconf_db(),
Config :: simple_xml() | [simple_xml()],
OptParams :: [simple_xml()],
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Edits configuration data. ✏️✨
By default only the running target is available — unless the server includes :candidate or :startup in its list of capabilities. Then the options open up.
OptParams is for specifying optional parameters (default-operation, test-option, or error-option) to add to the edit-config request. The value must be a list containing valid simple XML, like… for example:
[{'default-operation', ["none"]},
{'error-option', ["rollback-on-error"]}]If OptParams isn't given, the default value [] is used. Easy. 🎀
🧚 get(Client, Filter, Timeout) -> Result 🧚
get(Client, Filter, Timeout) -> Result
when
Client :: client(),
Filter :: simple_xml() | xpath(),
Timeout :: timeout(),
Result ::
{ok, [simple_xml()]} | {error, error_reason()}.Gets data. 🫴✨
This operation returns both configuration data and state data from the server. Two for one, we love that.
Filter type xpath can only be used if the server supports :xpath. No :xpath, no xpath filter, that's the deal. 💅
💖 get_capabilities(Client, Timeout) -> Result 💖
get_capabilities(Client, Timeout) -> Result
when
Client :: client(),
Timeout :: timeout(),
Result ::
[string()] | {error, error_reason()}.Returns the server capabilities exactly as received in its hello message. 👑 Literally just handing you the receipts.
🍓 get_config(Client, Source, Filter, Timeout) -> Result 🍓
get_config(Client, Source, Filter, Timeout) -> Result
when
Client :: client(),
Source :: netconf_db(),
Filter :: simple_xml() | xpath(),
Timeout :: timeout(),
Result ::
{ok, [simple_xml()]} |
{error, error_reason()}.Gets configuration data. 📥
To be able to access a source other than running, the server must advertise :candidate and/or :startup. (same rules as always, the server's gotta say it first ✨)
Filter type xpath can only be used if the server supports :xpath. Periodt.
🌸 get_event_streams(Client, Streams, Timeout) -> Result 🌸
get_event_streams(Client, Streams, Timeout) -> Result
when
Client :: client(),
Streams :: [stream_name()],
Timeout :: timeout(),
Result ::
{ok, streams()} |
{error, error_reason()}.Sends a request to get the specified event streams. 🌊
Streams is a list of stream names. The following filter gets sent to the NETCONF server in a get request:
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams>
<stream>
<name>StreamName1</name>
</stream>
<stream>
<name>StreamName2</name>
</stream>
...
</streams>
</netconf>If Streams is an empty list, all streams are requested by sending this filter instead:
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams/>
</netconf>And if you need more complex filtering than that? Use ct_netconfc:get/2,3 and specify the exact filter according to "XML Schema for Event Notifications" in RFC 5277. Go wild bestie. 🦋
💅 get_session_id(Client, Timeout) -> Result 💅
get_session_id(Client, Timeout) -> Result
when
Client :: client(),
Timeout :: timeout(),
Result ::
pos_integer() | {error, error_reason()}.Returns the session Id associated with the specified client. Your session's little name tag 🏷️✨
🔥 hello(Client, Options, Timeout) -> Result 🔥
hello(Client, Options, Timeout) -> Result
when
Client :: handle(),
Options :: [{capability, [string()]}],
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.okay so hello (the /2,/3 flavor) is literally exchanging hello messages with the server, and it comes back to you when the server hello has been received or after the timeout you specified. ✨
note bestie: capabilities for an outgoing hello can be passed directly to open/2, so you don't have to do a separate hello dance. 💅
💀 kill_session(Client, SessionId, Timeout) -> Result
kill_session(Client, SessionId, Timeout) -> Result
when
Client :: client(),
SessionId :: pos_integer(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Forces termination of the session associated with the supplied session Id. Like, bye bestie. 👋
The server side must abort any ongoing operations, release any locks and resources associated with the session, and close any associated connections. That's not optional, it's giving required. 🫡
Only if the server is in the confirmed commit phase, the configuration is restored to its state before entering the confirmed commit phase. Otherwise, no configuration rollback is performed. So if you were hoping for a rollback outside confirmed commit — nope, not happening. 🙈
If the specified SessionId is equal to the current session Id, an error is returned. So you can't ghost yourself. 💀
🔒 lock(Client, Target, Timeout) -> Result
lock(Client, Target, Timeout) -> Result
when
Client :: client(),
Target :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Locks the configuration target. Periodt. 🔐
Which target parameters that can be used depends on if :candidate and/or :startup are supported by the server. If successful, the configuration system of the device is unavailable to other clients (NETCONF, CORBA, SNMP, and so on). Locks are intended to be short-lived. So don't hold it forever, bestie, it's not a forever lock. ⏳
Operation kill_session/2,3 can be used to force the release of a lock owned by another NETCONF session. How this is achieved by the server side is implementation-specific. So the server does its own thing, iykyk. 🌈
✨ only_open(Options) -> Result
only_open(Options) -> Result
when
Options :: [option()],
Result ::
{ok, handle()} | {error, error_reason()}.Opens a NETCONF session, but does not send hello. It's like open/1 but with no hello message. Lowkey introvert energy. 🙈
🌸 only_open(KeyOrName, ExtraOptions) -> Result
only_open(KeyOrName, ExtraOptions) -> Result
when
KeyOrName :: ct:key_or_name(),
ExtraOptions :: [option()],
Result ::
{ok, handle()} | {error, error_reason()}.Opens a named NETCONF session, but does not send hello. As open/2, but does not send a hello message. So named, but still no hello. 💅
👑 open(Options) -> Result
open(Options) -> Result
when
Options :: [option()],
Result :: {ok, handle()} | {error, error_reason()}.Opens a NETCONF session and exchanges hello messages. The full main character entrance. ✨
If the server options are specified in a configuration file, or if a named client is needed for logging purposes (see section Logging in this module), use open/2 instead. So if you need config file or named client logging, go to open/2, bestie. 📝
The opaque handle/0 reference returned from this function is required as client identifier when calling any other function in this module. Don't lose it. It's your VIP pass. 🎟️
💖 open(KeyOrName, ExtraOption) -> Result
open(KeyOrName, ExtraOption) -> Result
when
KeyOrName :: ct:key_or_name(),
ExtraOption :: [option()],
Result :: {ok, handle()} | {error, error_reason()}.Opens a named NETCONF session and exchanges hello messages. Named + hello = slay. 🦋
If KeyOrName is a configured server_id/0 or a target_name() associated with such an Id, then the options for this server are fetched from the configuration file. 📂
The options list is added to those of the configuration file. If an option is specified in both lists, the configuration file take precedence. So config file wins, no cap. 👑
If the server is not specified in a configuration file, use open/1 instead. Okay so don't use this one if there's no config entry. 💅
The opaque handle/0 reference returned from this function can be used as client identifier when calling any other function in this module. However, if KeyOrName is a target_name(), that is, if the server is named through a call to ct:require/2 or a require statement in the test suite, then this name can be used instead of handle/0. So sometimes the name is enough, periodt. ✨
See also ct:require/2. 🫶
📨 send(Client, SimpleXml, Timeout) -> Result
send(Client, SimpleXml, Timeout) -> Result
when
Client :: client(),
SimpleXml :: simple_xml(),
Timeout :: timeout(),
Result :: simple_xml() | {error, error_reason()}.Sends an XML document to the server. The specified XML document is sent "as is" to the server. This function can be used for sending XML documents that cannot be expressed by other interface functions in this module. So it's the "I got this weird XML, just send it" option. 🔥
🚀 send_rpc(Client, SimpleXml, Timeout) -> Result
send_rpc(Client, SimpleXml, Timeout) -> Result
when
Client :: client(),
SimpleXml :: simple_xml(),
Timeout :: timeout(),
Result :: [simple_xml()] | {error,
error_reason()}.Sends a NETCONF rpc request to the server. The specified XML document is wrapped in a valid NETCONF rpc request and sent to the server. The message-id and namespace attributes are added to element rpc. So it's like a little rpc glow-up. ✨
This function can be used for sending rpc requests that cannot be expressed by other interface functions in this module. Custom rpc? Say less. 💅
🌈 session(KeyOrName, Conn, Options) -> Result
session(KeyOrName, Conn, Options) -> Result
when
Conn :: handle(),
Options :: [session_option()],
KeyOrName :: ct:key_or_name(),
Result :: {ok, handle()} | {error, error_reason()}.Opens a NETCONF session as a channel on the given SSH connection, and exchanges hello messages with the server. Channel on SSH? Iconic. 🧚
The opaque handle/0 reference returned from this function can be used as client identifier when calling any other function in this module. However, if KeyOrName is used and it is a target_name(), that is, if the server is named through a call to ct:require/2 or a require statement in the test suite, then this name can be used instead of handle/0. Same energy as open/2. 🫶
🔓 unlock(Client, Target, Timeout) -> Result
unlock(Client, Target, Timeout) -> Result
when
Client :: client(),
Target :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error, error_reason()}.Unlocks the configuration target. The release we love to see. 🕊️
If the client earlier has acquired a lock through lock/2,3, this operation releases the associated lock. To access another target than running, the server must support :candidate and/or :startup. So keep that in mind, bestie. 🌟
💌 and that's a wrap on ct_netconfc(3)! This page is brought to you by Ericsson AB, common_test 1.31.1, and the manual page itself is ct_netconfc(3). No date on this footer, just vibes and version numbers. Stay locked in (but release your locks, short-lived remember 😉). Bye bestie! 💖✨
📦 where this page comes from
- ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms