ct_netconfc

Netconf client module.

The Netconf client is compliant with RFC4741 and RFC4742.

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 target_name() (see ct) shall then be used in calls to open/2.

If no configuration exists for a server, a session can still be opened by calling open/2 with all necessary options given in the call. The first argument to open/2 can then be any atom.

Logging

The netconf server uses the 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 your test suite, e.g.

  suite() ->
     [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].

The conn_mod() is the name of the common_test module implementing the connection protocol, e.g. ct_netconfc.

The 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, it is possible to have different connections logged in separate files. To do this, use the hook option hosts and list the names of the servers/connections that will be used in the suite. Note that the connections must be named for this to work, i.e. they must be opened with open/2.

The hosts option has no effect if log_type is set to html or silent.

The hook options can also be specified in a configuration file with the configuration variable ct_conn_log:

  {ct_conn_log,[{conn_mod(),hook_options()}]}.

For example:

  {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
                              {hosts,[key_or_name()]}]}]}

Note that hook options specified in a configuration file will overwrite the hardcoded hook options in the test suite.

Logging example 1

The following ct_hooks statement will cause pretty printing of netconf traffic to separate logs for the connections named nc_server1 and nc_server2. Any other connections will be 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 like this:

  open(nc_server1,[...]),
  open(nc_server2,[...]).

Logging example 2

The following configuration file will cause raw logging of all netconf traffic into one single text file.

  {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.

The ct_hooks statement must look like this:

  suite() ->
     [{ct_hooks, [{cth_conn_log, []}]}].

The same ct_hooks statement without the configuration file would cause HTML logging of all netconf connections into the test case HTML log.

Notifications

The netconf client is also compliant with RFC5277 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/6 and get_event_streams/3. (The functions also exist with other arities.)

client() = handle() | server_id() (see module ct_gen_conn) | target_name() (see module ct_gen_conn)

error_reason() = term()

event_time() = {eventTime, xml_attributes(), [xs_datetime()]}

handle() = term()

An opaque reference for a connection (netconf session). See ct for more information.

host() = hostname() (see module inet) | ip_address() (see module inet)

netconf_db() = running | startup | candidate

notification() = {notification, xml_attributes(), notification_content()}

notification_content() = [event_time() | simple_xml()]

option() = {ssh, host()} | {port, port_number() (see module inet)} | {user, string()} | {password, string()} | {user_dir, string()} | {timeout, timeout()}

options() = [option()]

Options used for setting up ssh connection to a netconf server.

simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()

This type is further described in the documentation for the Xmerl application.

stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}

See XML Schema for Event Notifications found in RFC5277 for further detail about the data format for the string values.

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 identifyer has the same format as the XML type dateTime and compliant to RFC3339. The format is

     [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]

Equivalent to action(Client, Action, infinity).

Types:

Execute an action. If the return type is void, ok will be returned instead of {ok,[simple_xml()]}.

Equivalent to close_session(Client, infinity).

Types:

Request graceful termination of the session associated with the client.

When a netconf server receives a close-session request, it will gracefully close the session. The server will release any locks and resources associated with the session and gracefully close any associated connections. Any NETCONF requests received after a close-session request will be ignored.

Equivalent to copy_config(Client, Source, Target, infinity).

Types:

Copy configuration data.

Which source and target options that can be issued depends on the capabilities supported by the server. I.e. :candidate and/or :startup are required.

Types:

Create a subscription for event notifications.

This function sets up a subscription for netconf event notifications of the given stream type, matching the given filter. The calling process will receive notifications as messages of type notification().

Stream:

An optional parameter that indicates which stream of events is of interest. If not present, events in the default NETCONF stream will be sent.

Filter:

An optional parameter that indicates which subset of all possible events is of interest. The format of this parameter is the same as that of the filter parameter in the NETCONF protocol operations. If not present, all events not precluded by other parameters will be sent.

StartTime:

An optional parameter used to trigger the replay feature and indicate that the replay should 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 the StartTime specified is earlier than the log can support, the replay will begin with the earliest available notification. This parameter is of type dateTime and compliant to [RFC3339]. Implementations must support time zones.

StopTime:

An optional parameter used with the optional replay feature to indicate the newest notifications of interest. If StopTime is not present, the notifications will continue 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 [RFC3339]. Implementations must support time zones.

See RFC5277 for further details about the event notification mechanism.

Equivalent to delete_config(Client, Target, infinity).

Types:

Delete configuration data.

The running configuration cannot be deleted and :candidate or :startup must be advertised by the server.

Equivalent to edit_config(Client, Target, Config, [], infinity).

Types:

If OptParamsOrTimeout is a timeout value, then this is equivalent to edit_config(Client, Target, Config, [], Timeout).

If OptParamsOrTimeout is a list of simple XML, then this is equivalent to edit_config(Client, Target, Config, OptParams, infinity).

Types:

Edit configuration data.

Per default only the running target is available, unless the server include :candidate or :startup in its list of capabilities.

OptParams can be used for specifying optional parameters (default-operation, test-option or error-option) that will 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"]}]

Equivalent to get(Client, Filter, infinity).

Types:

Get data.

This operation returns both configuration and state data from the server.

Filter type xpath can only be used if the server supports :xpath.

Equivalent to get_capabilities(Client, infinity).

Types:

Returns the server side capabilities

The following capability identifiers, defined in RFC 4741, 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"

Note, additional identifiers may exist, e.g. server side namespace.

Equivalent to get_config(Client, Source, Filter, infinity).

Types:

Get configuration data.

To be able to access another source than running, the server must advertise :candidate and/or :startup.

Filter type xpath can only be used if the server supports :xpath.

Equivalent to get_event_streams(Client, [], Timeout).

Types:

Send a request to get the given event streams.

Streams is a list of stream names. The following filter will be 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 will be requested by sending the following filter:

  <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
    <streams/>
  </netconf>

If more complex filtering is needed, a use get/2 or get/3 and specify the exact filter according to XML Schema for Event Notifications found in RFC5277.

Equivalent to get_session_id(Client, infinity).

Types:

Returns the session id associated with the given client.

Equivalent to hello(Client, [], infinity).

Equivalent to hello(Client, [], Timeout).

Types:

Exchange hello messages with the server.

Adds optional capabilities and sends a hello message to the server and waits for the return.

Equivalent to kill_session(Client, SessionId, infinity).

Types:

Force termination of the session associated with the supplied session id.

The server side shall abort any operations currently in process, 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 will be restored to its state before entering the confirmed commit phase. Otherwise, no configuration roll back will be performed.

If the given SessionId is equal to the current session id, an error will be returned.

Equivalent to lock(Client, Target, infinity).

Types:

Unlock 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 not available to other clients (Netconf, CORBA, SNMP etc). Locks are intended to be short-lived.

The operations kill_session/2 or kill_session/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.

Types:

Open a netconf session, but don't send hello.

As open/1 but does not send a hello message.

Types:

Open a name netconf session, but don't send hello.

As open/2 but does not send a hello message.

Types:

Open a netconf session and exchange hello messages.

If the server options are specified in a configuration file, or if a named client is needed for logging purposes (see Logging) use open/2 instead.

The opaque handler() reference which is returned from this function is required as client identifier when calling any other function in this module.

The timeout option (milli seconds) 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.

Types:

Open a named netconf session and exchange hello messages.

If KeyOrName is a configured server_id() or a target_name() associated with such an ID, then the options for this server will be fetched from the configuration file.

The ExtraOptions argument will be added to the options found in the configuration file. If the same options are given, the values from the configuration file will overwrite ExtraOptions.

If the server is not specified in a configuration file, use open/1 instead.

The opaque handle() reference which is 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(), i.e. if the server is named via a call to ct:require/2 or a require statement in the test suite, then this name may be used instead of the handle().

The timeout option (milli seconds) 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.

Equivalent to send(Client, SimpleXml, infinity).

Types:

Send an XML document to the server.

The given XML document is sent as is to the server. This function can be used for sending XML documents that can not be expressed by other interface functions in this module.

Equivalent to send_rpc(Client, SimpleXml, infinity).

Types:

Send a Netconf rpc request to the server.

The given XML document is wrapped in a valid Netconf rpc request and sent to the server. The message-id and namespace attributes are added to the rpc element.

This function can be used for sending rpc requests that can not be expressed by other interface functions in this module.

Equivalent to unlock(Client, Target, infinity).

Types:

Unlock configuration target.

If the client earlier has aquired a lock, via lock/2 or lock/3, this operation release the associated lock. To be able to access another target than running, the server must support :candidate and/or :startup.