NETCONF client module.
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.
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]
Functions
action(Client, Action) -> Result
Client = client()
Action = simple_xml()
Result = ok | {ok, [simple_xml()]} | {error, error_reason()}
action(Client, Action, Timeout) -> Result
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
Client = client()
Result = ok | {error, error_reason()}
close_session(Client, Timeout) -> Result
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
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
KeyOrName = ct:key_or_name()
ExtraOptions = options()
Result = {ok, handle()} | {error, error_reason()}
Open an SSH connection to a named NETCONF server.
If
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
is added to the
options found in the configuration file. If the same options
are specified, the values from the configuration file
overwrite
.
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
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
Client = client()
Target = Source = netconf_db()
Result = ok | {error, error_reason()}
copy_config(Client, Target, Source, Timeout) -> Result
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, Stream, Filter, StartTime, StopTime,
Timeout) ->
Result
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
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
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
is not present, the notifications
continues until the subscription is terminated.
Must be used with and be later than StartTime
. Values
of
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
Client = client()
Target = startup | candidate
Result = ok | {error, error_reason()}
delete_config(Client, Target, Timeout) -> Result
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()}
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
Client = client()
Target = netconf_db()
Config = simple_xml() | [simple_xml()]
Result = ok | {error, error_reason()}
edit_config(Client, Target, Config, OptParams, Timeout) -> Result
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.
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
is not given, the default
value []
is used.
get(Client, Filter) -> Result
Client = client()
Filter = simple_xml() | xpath()
Result = {ok, [simple_xml()]} | {error, error_reason()}
get(Client, Filter, Timeout) -> Result
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
Client = client()
Result = [string()] | {error, error_reason()}
get_capabilities(Client, Timeout) -> Result
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
Client = client()
Source = netconf_db()
Filter = simple_xml() | xpath()
Result = {ok, [simple_xml()]} | {error, error_reason()}
get_config(Client, Source, Filter, Timeout) -> Result
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
Client = client()
Result = {ok, streams()} | {error, error_reason()}
get_event_streams(Client, Streams, Timeout) -> Result
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
Client = client()
Result = integer() >= 1 | {error, error_reason()}
get_session_id(Client, Timeout) -> Result
Client = client()
Timeout = timeout()
Result = integer() >= 1 | {error, error_reason()}
Returns the session Id associated with the specified client.
hello(Client) -> Result
Client = handle()
Result = ok | {error, error_reason()}
hello(Client, Timeout) -> Result
Client = handle()
Timeout = timeout()
Result = ok | {error, error_reason()}
hello(Client, Options, Timeout) -> Result
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
Client = client()
SessionId = integer() >= 1
Result = ok | {error, error_reason()}
kill_session(Client, SessionId, Timeout) -> Result
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
Client = client()
Target = netconf_db()
Result = ok | {error, error_reason()}
lock(Client, Target, Timeout) -> Result
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
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
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
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
KeyOrName = ct:key_or_name()
ExtraOptions = options()
Result = {ok, handle()} | {error, error_reason()}
Opens a named NETCONF session and exchanges hello
messages.
If
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
is added to the
options found in the configuration file. If the same
options are specified, the values from the configuration
file overwrite
.
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
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
Client = client()
SimpleXml = simple_xml()
Result = simple_xml() | {error, error_reason()}
send(Client, SimpleXml, Timeout) -> Result
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
Client = client()
SimpleXml = simple_xml()
Result = [simple_xml()] | {error, error_reason()}
send_rpc(Client, SimpleXml, Timeout) -> Result
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
Conn = handle()
Result = {ok, handle()} | {error, error_reason()}
session(KeyOrName, Conn, Options) -> Result
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
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
Client = client()
Target = netconf_db()
Result = ok | {error, error_reason()}
unlock(Client, Target, Timeout) -> Result
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
.