Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all 
NAME
ct_netconfc - NETCONF client module.
DESCRIPTION
NETCONF client module.
The NETCONF client is compliant with RFC 4741 NETCONF Configuration Protocol and RFC 4742
Using the NETCONF Configuration Protocol over Secure SHell (SSH).
Connecting to a NETCONF server
NETCONF sessions can either be opened by a single call to open/1,2 or by a call to
connect/1,2 followed by one or more calls to session/1,2,3.
The properties of the sessions will be exactly the same, except that when using
connect/1,2, you may start multiple sessions over the same SSH connection. Each session is
implemented as an SSH channel.
open/1,2 will establish one SSH connection with one SSH channel implementing one NETCONF
session. You may start mutiple sessions by calling open/1,2 multiple times, but then a new
SSH connection will be established for each session.
For each server to test against, the following entry can be added to a configuration file:
{server_id(),options()}.
The server_id() or an associated ct:target_name() must then be used in calls to connect/2
or open/2.
If no configuration exists for a server, use connect/1 or open/1 instead, and specify all
necessary options in the Options parameter.
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. 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.
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.
Notifications
The NETCONF client is also compliant with RFC 5277 NETCONF Event Notifications, which
defines a mechanism for an asynchronous message notification delivery service for the
NETCONF protocol.
Specific functions to support this are create_subscription/1-6 and get_event_streams/1-3.
Default Timeout
Most of the functions in this module have one variant with a Timeout parameter, and one
without. If nothing else is specified, the default value infinity is used when the Timeout
parameter is not given.
DATA TYPES
client() = handle() | server_id() | ct:target_name()
error_reason() = term()
event_time() = {eventTime, xml_attributes(), [xs_datetime()]}
handle()
Opaque reference for a connection to a NETCONF server or a NETCONF session.
host() = inet:hostname() | inet:ip_address()
netconf_db() = running | startup | candidate
notification() =
{notification, xml_attributes(), notification_content()}
notification_content() = [event_time() | simple_xml()]
option() =
{ssh, host()} |
{port, inet:port_number()} |
{user, string()} |
{password, string()} |
{user_dir, string()} |
{timeout, timeout()}
SshConnectOption is any valid option to ssh:connect/3,4. Common options used are
user, password and user_dir. The SshConnectOptions are verfied by the SSH
application.
options() = [option()]
Options used for setting up an SSH connection to a NETCONF server.
server_id() = atom()
The identity of a server, specified in a configuration file.
simple_xml() =
{xml_tag(), xml_attributes(), xml_content()} |
{xml_tag(), xml_content()} |
xml_tag()
This type is further described in application xmerl.
stream_data() =
{description, string()} |
{replaySupport, string()} |
{replayLogCreationTime, string()} |
{replayLogAgedTime, string()}
For details about the data format for the string values, see "XML Schema for Event
Notifications" in RFC 5277.
stream_name() = string()
streams() = [{stream_name(), [stream_data()]}]
xml_attribute_tag() = atom()
xml_attribute_value() = string()
xml_attributes() =
[{xml_attribute_tag(), xml_attribute_value()}]
xml_content() = [simple_xml() | iolist()]
xml_tag() = atom()
xpath() = {xpath, string()}
xs_datetime() = string()
This date and time identifier has the same format as the XML type dateTime and is
compliant with RFC 3339 Date and Time on the Internet Timestamps. The format is as
follows:
[-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
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 = options()
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,2,3.
Option timeout (milliseconds) is used when setting up the SSH connection. It is not
used for any other purposes during the lifetime of the connection.
connect(KeyOrName, ExtraOptions) -> Result
Types:
KeyOrName = ct:key_or_name()
ExtraOptions = options()
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.
Argument ExtraOptions is added to the options found in the configuration file. If
the same options are specified, the values from the configuration file overwrite
ExtraOptions.
If the server is not specified in a configuration file, use connect/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,2,3. 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().
Option timeout (milliseconds) is used when setting up the SSH connection. It is not
used for any other purposes during the lifetime of the connection.
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) -> Result
create_subscription(Client, Stream) -> Result
create_subscription(Client, Stream, Filter) -> Result
create_subscription(Client, Stream, Filter, Timeout) -> Result
create_subscription(Client, Stream, Filter, StartTime, StopTime) ->
Result
create_subscription(Client,
Stream,
Filter,
StartTime,
StopTime,
Timeout) ->
Result
Types:
Client = client()
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.
This function sets up a subscription for NETCONF event notifications of the
specified stream type, matching the specified filter. The calling process receives
notifications as messages of type notification().
Only a subset of the function clauses are show above. The full set of valid
combinations of input parameters is as follows:
create_subscription(Client)
create_subscription(Client, Timeout)
create_subscription(Client, Stream)
create_subscription(Client, Filter)
create_subscription(Client, Stream, Timeout)
create_subscription(Client, Filter, Timeout)
create_subscription(Client, Stream, Filter)
create_subscription(Client, StartTime, StopTime)
create_subscription(Client, Stream, Filter, Timeout)
create_subscription(Client, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, StartTime, StopTime)
create_subscription(Client, Filter, StartTime, StopTime)
create_subscription(Client, Stream, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, Filter, StartTime, StopTime)
create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout)
Stream:
Optional parameter that indicates which stream of event is of interest. If not
present, events in the default NETCONF stream are sent.
Filter:
Optional parameter that indicates which subset of all possible events is of
interest. 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:
Optional parameter 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 notification.
This parameter is of type dateTime and compliant to RFC 3339. Implementations
must support time zones.
StopTime:
Optional parameter 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 terminated.
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.
For more details about the event notification mechanism, see RFC 5277.
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()
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.
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 side capabilities.
The following capability identifiers, defined in RFC 4741 NETCONF Configuration
Protocol, can be returned:
* "urn:ietf:params:netconf:base:1.0"
* "urn:ietf:params:netconf:capability:writable-running:1.0"
* "urn:ietf:params:netconf:capability:candidate:1.0"
* "urn:ietf:params:netconf:capability:confirmed-commit:1.0"
* "urn:ietf:params:netconf:capability:rollback-on-error:1.0"
* "urn:ietf:params:netconf:capability:startup:1.0"
* "urn:ietf:params:netconf:capability:url:1.0"
* "urn:ietf:params:netconf:capability:xpath:1.0"
More identifiers can exist, for example, server-side namespace.
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 sending 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.
Adds optional capabilities and sends a hello message to the server and waits for
the return.
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 configuration 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 :candidate and/or :startup
are supported by the server. If successfull, 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 = options()
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 = options()
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 = options()
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.
Option timeout (milliseconds) is used when setting up the SSH connection and when
waiting for the hello message from the server. It is not used for any other
purposes during the lifetime of the connection.
open(KeyOrName, ExtraOptions) -> Result
Types:
KeyOrName = ct:key_or_name()
ExtraOptions = options()
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.
Argument ExtraOptions is added to the options found in the configuration file. If
the same options are specified, the values from the configuration file overwrite
ExtraOptions.
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().
Option timeout (milliseconds) is used when setting up the SSH connection and when
waiting for the hello message from the server. It is not used for any other
purposes during the lifetime of the connection.
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_options()
KeyOrName = ct:key_or_name()
Result = {ok, handle()} | {error, error_reason()}
session_options() = [session_option()]
session_option() = {timeout, timeout()}
Opens a NETCONF session as a channel on the given SSH connection, 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 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().
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.