ct_netconfc - NETCONF client module.
Please see following description for synopsis
ct_netconfc(3) Erlang Module Definition ct_netconfc(3)
NAME
ct_netconfc - NETCONF client module.
DESCRIPTION
NETCONF client module 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 Noti-
fications.
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.
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() or an associated ct:target_name() can then be passed to
the aforementioned functions to use the referenced configuration.
Signaling
Protocol operations in the NETCONF protocol are realized as remote pro-
cedure 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.
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.
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.
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.
html (default):
The sent and received NETCONF traffic is pretty printed directly in
the test case HTML log.
silent:
NETCONF traffic is not logged.
By default, all NETCONF traffic is logged in one single log file. How-
ever, different connections can be logged in separate files. To do
this, use hook option hosts and list the names of the servers/connec-
tions to be used in the suite. The connections must be named for this
to work, that is, they must be opened with open/2.
Option hosts has no effect if log_type is set to html or silent.
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.
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.
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.
DATA TYPES
client() = handle() | server_id() | ct:target_name()
Handle to a NETCONF session, as required by signaling functions.
handle()
Handle to a connection to a NETCONF server as returned by con-
nect/1,2, or to a session as returned by session/1-3, open/1,2,
or only_open/1,2.
xs_datetime() = string()
Date and time of a startTime/stopTime element in an RFC 5277
create-subscription request. Of XML primitive type dateTime,
which has the (informal) form
[-]YYYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
where T and Z are literal and .s is one or more fractional sec-
onds.
notification() =
{notification, xml_attributes(), [simple_xml()]}
Event notification messages sent as a result of calls to cre-
ate_subscription/2,3.
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 arbi-
trary ssh options. Common options are user, password and
user_dir.
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 indepen-
dently; one timeout for connection establishment, another for
hello reception.
Option receiver specifies a destination for incoming notifica-
tion 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 possi-
ble to receive notifications that are not ordered by calling
this function. Multiple receiver options can be specified.
Receiver options are ignored by connect/1-3.
Option capability specifies the content of a corresponding ele-
ment 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 con-
figured. NETCONF capabilities can be specified using the short-
hand notation defined in RFC 6241, any capability string start-
ing with a colon being prefixed by either "urn:ietf:params:net-
conf" or "urn:ietf:params:netconf:capability", as appropriate.
Capability options are ignored by connect/1-3 and only_open/1-2,
which don't result in an outgoing hello message.
server_id() = atom()
Identity of connection or session configuration in a configura-
tion file.
stream_data() =
{description, string()} |
{replaySupport, string()} |
{replayLogCreationTime, string()} |
{replayLogAgedTime, string()}
stream_name() = string()
streams() = [{stream_name(), [stream_data()]}]
Stream information as returned by get_event_streams/1-3. See RFC
5277, "XML Schema for Event Notifications", for detail on the
format of the string values.
xml_attribute_tag() = atom()
xml_attribute_value() = string()
xml_attributes() =
[{xml_attribute_tag(), xml_attribute_value()}]
xml_content() = [simple_xml() | iolist()]
xml_tag() = atom()
simple_xml() =
{xml_tag(), xml_attributes(), xml_content()} |
{xml_tag(), xml_content()} |
xml_tag()
Representation of XML, as described in application xmerl.
xpath() = {xpath, string()}
error_reason() = term()
host() = inet:hostname() | inet:ip_address()
netconf_db() = running | startup | candidate
EXPORTS
action(Client, Action) -> Result
action(Client, Action, Timeout) -> Result
Types:
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()]}.
close_session(Client) -> Result
close_session(Client, Timeout) -> Result
Types:
Client = client()
Timeout = timeout()
Result = ok | {error, error_reason()}
Requests graceful termination of the session associated with the
client.
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.
connect(Options) -> Result
Types:
Options = [option()]
Result = {ok, handle()} | {error, error_reason()}
Opens an SSH connection to a NETCONF server.
If the server options are specified in a configuration file, use
connect/2 instead.
The opaque handle() reference returned from this function is
required as connection identifier when opening sessions over
this connection, see session/1-3.
connect(KeyOrName, ExtraOptions) -> Result
Types:
KeyOrName = ct:key_or_name()
ExtraOptions = [option()]
Result = {ok, handle()} | {error, error_reason()}
Open an SSH connection to a named NETCONF server.
If KeyOrName is a configured server_id() 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
takes precedence.
If the server is not specified in a configuration file, use con-
nect/1 instead.
The opaque handle() reference returned from this function can be
used as connection identifier when opening sessions over this
connection, see session/1-3. However, if KeyOrName is a tar-
get_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().
copy_config(Client, Target, Source) -> Result
copy_config(Client, Target, Source, Timeout) -> Result
Types:
Client = client()
Target = Source = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
Copies configuration data.
Which source and target options that can be issued depends on
the capabilities supported by the server. That is, :candidate
and/or :startup are required.
create_subscription(Client, Values) -> Result
create_subscription(Client, Values, Timeout) -> Result
Types:
Client = client()
Values =
#{stream => Stream,
filter => Filter,
start => StartTime,
stop => StopTime}
Stream = stream_name()
Filter = simple_xml() | [simple_xml()]
StartTime = StopTime = xs_datetime()
Timeout = timeout()
Result = ok | {error, error_reason()}
Creates a subscription for event notifications by sending an RFC
5277 create-subscription RPC to the server. The calling process
receives events as messages of type notification().
From RFC 5722, 2.1 Subscribing to Receive Event Notifications:
Stream:
Indicates which stream of event is of interest. If not
present, events in the default NETCONF stream are sent.
Filter:
Indicates which subset of all possible events is of inter-
est. The parameter format is the same as that of the filter
parameter in the NETCONF protocol operations. If not
present, all events not precluded by other parameters are
sent.
StartTime:
Used to trigger the replay feature and indicate that the
replay is to start at the time specified. If StartTime is
not present, this is not a replay subscription. It is not
valid to specify start times that are later than the current
time. If StartTime is specified earlier than the log can
support, the replay begins with the earliest available noti-
fication. This parameter is of type dateTime and compliant
to RFC 3339. Implementations must support time zones.
StopTime:
Used with the optional replay feature to indicate the newest
notifications of interest. If StopTime is not present, the
notifications continues until the subscription is termi-
nated. Must be used with and be later than StartTime. Values
of StopTime in the future are valid. This parameter is of
type dateTime and compliant to RFC 3339. Implementations
must support time zones.
See RFC 5277 for more details. The requirement that StopTime
must only be used with StartTime is not enforced, to allow an
invalid request to be sent to the server.
Prior to OTP 22.1, this function was documented as having 15
variants in 6 arities. These are still exported for backwards
compatibility, but no longer documented. The map-based variants
documented above provide the same functionality with simpler
arguments.
Note:
create-subscription is no longer the only RPC with which NETCONF
notifications can be ordered: RFC 8639 adds establish-subscrip-
tion and future RFCs may add other methods. Specify a receiver
option at session creation to provide a destination for incoming
notifications independently of a call to create_subscrip-
tion/2,3, and use send_rpc/2,3 to send establish-subscription
and other arbirary RPCs.
delete_config(Client, Target) -> Result
delete_config(Client, Target, Timeout) -> Result
Types:
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.
disconnect(Conn) -> ok | {error, error_reason()}
Types:
Conn = handle()
Closes the given SSH connection.
If there are open NETCONF sessions on the connection, these will
be brutally aborted. To avoid this, close each session with
close_session/1,2
edit_config(Client, Target, Config) -> Result
edit_config(Client, Target, Config, OptParams) -> Result
edit_config(Client, Target, Config, Timeout) -> Result
edit_config(Client, Target, Config, OptParams, Timeout) -> Result
Types:
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 capabili-
ties.
OptParams can be used for specifying optional parameters
(default-operation, test-option, or error-option) to be added to
the edit-config request. The value must be a list containing
valid simple XML, for example:
[{'default-operation', ["none"]},
{'error-option', ["rollback-on-error"]}]
If OptParams is not given, the default value [] is used.
get(Client, Filter) -> Result
get(Client, Filter, Timeout) -> Result
Types:
Client = client()
Filter = simple_xml() | xpath()
Timeout = timeout()
Result = {ok, [simple_xml()]} | {error, error_reason()}
Gets data.
This operation returns both configuration and state data from
the server.
Filter type xpath can be used only if the server supports
:xpath.
get_capabilities(Client) -> Result
get_capabilities(Client, Timeout) -> Result
Types:
Client = client()
Timeout = timeout()
Result = [string()] | {error, error_reason()}
Returns the server capabilities as received in its hello mes-
sage.
get_config(Client, Source, Filter) -> Result
get_config(Client, Source, Filter, Timeout) -> Result
Types:
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 another source than running, the server
must advertise :candidate and/or :startup.
Filter type xpath can be used only if the server supports
:xpath.
get_event_streams(Client) -> Result
get_event_streams(Client, Timeout) -> Result
get_event_streams(Client, Streams) -> Result
get_event_streams(Client, Streams, Timeout) -> Result
Types:
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 is 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 send-
ing the following filter:
<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
<streams/>
</netconf>
If more complex filtering is needed, use ct_netconfc:get/2,3 and
specify the exact filter according to "XML Schema for Event
Notifications" in RFC 5277.
get_session_id(Client) -> Result
get_session_id(Client, Timeout) -> Result
Types:
Client = client()
Timeout = timeout()
Result = integer() >= 1 | {error, error_reason()}
Returns the session Id associated with the specified client.
hello(Client) -> Result
hello(Client, Timeout) -> Result
hello(Client, Options, Timeout) -> Result
Types:
Client = handle()
Options = [{capability, [string()]}]
Timeout = timeout()
Result = ok | {error, error_reason()}
Exchanges hello messages with the server. Returns when the
server hello has been received or after the specified timeout.
Note that capabilities for an outgoing hello can be passed
directly to open/2.
kill_session(Client, SessionId) -> Result
kill_session(Client, SessionId, Timeout) -> Result
Types:
Client = client()
SessionId = integer() >= 1
Timeout = timeout()
Result = ok | {error, error_reason()}
Forces termination of the session associated with the supplied
session Id.
The server side must abort any ongoing operations, release any
locks and resources associated with the session, and close any
associated connections.
Only if the server is in the confirmed commit phase, the config-
uration is restored to its state before entering the confirmed
commit phase. Otherwise, no configuration rollback is performed.
If the specified SessionId is equal to the current session Id,
an error is returned.
lock(Client, Target) -> Result
lock(Client, Target, Timeout) -> Result
Types:
Client = client()
Target = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
Locks the configuration target.
Which target parameters that can be used depends on if :candi-
date and/or :startup are supported by the server. If success-
full, the configuration system of the device is unavailable to
other clients (NETCONF, CORBA, SNMP, and so on). Locks are
intended to be short-lived.
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.
only_open(Options) -> Result
Types:
Options = [option()]
Result = {ok, handle()} | {error, error_reason()}
Opens a NETCONF session, but does not send hello.
As open/1, but does not send a hello message.
only_open(KeyOrName, ExtraOptions) -> Result
Types:
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.
open(Options) -> Result
Types:
Options = [option()]
Result = {ok, handle()} | {error, error_reason()}
Opens a NETCONF session and exchanges hello messages.
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.
The opaque handle() reference returned from this function is
required as client identifier when calling any other function in
this module.
open(KeyOrName, ExtraOption) -> Result
Types:
KeyOrName = ct:key_or_name()
ExtraOption = [option()]
Result = {ok, handle()} | {error, error_reason()}
Opens a named NETCONF session and exchanges hello messages.
If KeyOrName is a configured server_id() 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.
If the server is not specified in a configuration file, use
open/1 instead.
The opaque handle() 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().
See also ct:require/2.
send(Client, SimpleXml) -> Result
send(Client, SimpleXml, Timeout) -> Result
Types:
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.
send_rpc(Client, SimpleXml) -> Result
send_rpc(Client, SimpleXml, Timeout) -> Result
Types:
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.
This function can be used for sending rpc requests that cannot
be expressed by other interface functions in this module.
session(Conn) -> Result
session(Conn, Options) -> Result
session(KeyOrName, Conn) -> Result
session(KeyOrName, Conn, Options) -> Result
Types:
Conn = handle()
Options = [session_option()]
KeyOrName = ct:key_or_name()
Result = {ok, handle()} | {error, error_reason()}
session_option() =
{timeout, timeout()} |
{receiver, term()} |
{capability, string() | [string()]}
Opens a NETCONF session as a channel on the given SSH connec-
tion, and exchanges hello messages with the server.
The opaque handle() 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 tar-
get_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().
unlock(Client, Target) -> Result
unlock(Client, Target, Timeout) -> Result
Types:
Client = client()
Target = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
Unlocks the configuration target.
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.
Ericsson AB common_test 1.22 ct_netconfc(3)