20102012 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ct_netconfc A ct_netconfc.xml
ct_netconfc 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)..

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 module ct) must then be used in calls to ct_netconfc:open/2.

If no configuration exists for a server, a session can still be opened by calling ct_netconfc:open/2 with all necessary options specified in the call. The first argument to ct_netconfc:open/2 can then be any atom.
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, [{conn_mod(),hook_options()}]}]}].

conn_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 ct_netconfc: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,[{conn_mod(),hook_options()}]}.

For example:

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

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 ct_netconfc:create_subscription/6 and ct_netconfc:get_event_streams/3. (The functions also exist with other arities.)

Data Types client() = handle() | key_or_name()

For handle(), see module ct.

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

Opaque reference for a connection (NETCONF session). For more information, see module ct.

 host() = hostname() | ip_address()

For hostname() and ip_address(), see module kernel:inet

 key_or_name() = server_id() | target_name()

For target_name, see module ct.

 netconf_db() = running | startup | candidate notification() = {notification, xml_attributes(), notification_content()} notification_content() = [event_time() | simple_xml()] option() = {ssh, host()} | {port, port_number()} | {user, string()} | {password, string()} | {user_dir, string()} | {timeout, timeout()}

For port_number(), see module kernel:inet

 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]
action(Client, Action) -> Result Equivalent to action(Client, Action, infinity).

Equivalent to ct_netconfc:action(Client, Action, infinity).

 action(Client, Action, Timeout) -> Result Executes an action. 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 Equivalent to close_session(Client, infinity).

Equivalent to ct_netconfc:close_session(Client, infinity).

 close_session(Client, Timeout) -> Result Requests graceful termination of the session associated with the client. 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.

 copy_config(Client, Source, Target) -> Result Equivalent to copy_config(Client, Source, Target, infinity).

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

 copy_config(Client, Target, Source, Timeout) -> Result Copies configuration data. Client = client() Target = netconf_db() 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) -> term() Creates a subscription for event notifications. create_subscription(Client, Timeout) -> term() Creates a subscription for event notifications. create_subscription(Client, Stream, Timeout) -> term() Creates a subscription for event notifications. create_subscription(Client, StartTime, StopTime, Timeout) -> term() Creates a subscription for event notifications. create_subscription(Client, Stream, StartTime, StopTime, Timeout) -> term() Creates a subscription for event notifications. create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -> Result Creates a subscription for event notifications. Client = client() Stream = stream_name() Filter = simple_xml() | [simple_xml()] StartTime = xs_datetime() 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().

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 Equivalent to delete_config(Client, Target, infinity).

Equivalent to ct_netconfc:delete_config(Client, Target, infinity).

 delete_config(Client, Target, Timeout) -> Result Deletes configuration data. 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.

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

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

 edit_config(Client, Target, Config, OptParamsOrTimeout) -> Result If OptParamsOrTimeout is a time-out value, this function is equivalent to ct_netconfc:edit_config(Client, Target, Config, [], Timeout). Client = client() Target = netconf_db() Config = simple_xml() OptParamsOrTimeout = [simple_xml()] | timeout() Result = ok | {error, error_reason()}

If OptParamsOrTimeout is a time-out value, this function is equivalent to ct_netconfc:edit_config(Client, Target, Config, [], Timeout).

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

 edit_config(Client, Target, Config, OptParams, Timeout) -> Result Edits configuration data. 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"]}]
 get(Client, Filter) -> Result Equivalent to get(Client, Filter, infinity).

Equivalent to ct_netconfc:get(Client, Filter, infinity).

 get(Client, Filter, Timeout) -> Result Gets data. 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 Equivalent to get_capabilities(Client, infinity).

Equivalent to ct_netconfc:get_capabilities(Client, infinity).

 get_capabilities(Client, Timeout) -> Result Returns the server side capabilities. 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 Equivalent to get_config(Client, Source, Filter, infinity).

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

 get_config(Client, Source, Filter, Timeout) -> Result Gets configuration data. 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, Timeout) -> Result Equivalent to get_event_streams(Client, [], Timeout).

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

 get_event_streams(Client, Streams, Timeout) -> Result Sends a request to get the specified event streams. 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 or ct_netconfc:get/3 and specify the exact filter according to "XML Schema for Event Notifications" in RFC 5277.

 get_session_id(Client) -> Result Equivalent to get_session_id(Client, infinity).

Equivalent to ct_netconfc:get_session_id(Client, infinity).

 get_session_id(Client, Timeout) -> Result Returns the session Id associated with the specified client. Client = client() Timeout = timeout() Result = pos_integer() | {error, error_reason()}

Returns the session Id associated with the specified client.

 hello(Client) -> Result Equivalent to hello(Client, [], infinity).

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

 hello(Client, Timeout) -> Result Equivalent to hello(Client, [], Timeout).

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

 hello(Client, Options, Timeout) -> Result Exchanges hello messages with the server. 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 Equivalent to kill_session(Client, SessionId, infinity).

Equivalent to ct_netconfc:kill_session(Client, SessionId, infinity).

 kill_session(Client, SessionId, Timeout) -> Result Forces termination of the session associated with the supplied session Id. Client = client() SessionId = pos_integer() 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 Equivalent to lock(Client, Target, infinity).

Equivalent to ct_netconfc:lock(Client, Target, infinity).

 lock(Client, Target, Timeout) -> Result Unlocks the configuration target. Client = client() Target = netconf_db() Timeout = timeout() Result = ok | {error, error_reason()}

Unlocks 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 ct_netconfc:kill_session/2 or ct_netconfc: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.

 only_open(Options) -> Result Opens a NETCONF session, but does not send hello. Options = options() Result = {ok, handle()} | {error, error_reason()}

Opens a NETCONF session, but does not send hello.

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

 only_open(KeyOrName, ExtraOptions) -> Result Opens a name NETCONF session, but does not send hello. KeyOrName = key_or_name() ExtraOptions = options() Result = {ok, handle()} | {error, error_reason()}

Opens a name NETCONF session, but does not send hello.

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

 open(Options) -> Result Opens a NETCONF session and exchanges hello messages. 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 ct_netconfc:open/2 instead.

The opaque handler() 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 Opens a named NETCONF session and exchanges hello messages. KeyOrName = 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 ct_netconfc: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 Equivalent to send(Client, SimpleXml, infinity).

Equivalent to ct_netconfc:send(Client, SimpleXml, infinity).

 send(Client, SimpleXml, Timeout) -> Result Sends an XML document to the server. 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 Equivalent to send_rpc(Client, SimpleXml, infinity).

Equivalent to ct_netconfc:send_rpc(Client, SimpleXml, infinity).

 send_rpc(Client, SimpleXml, Timeout) -> Result Sends a NETCONF rpc request to the server. 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.

 unlock(Client, Target) -> Result Equivalent to unlock(Client, Target, infinity).

Equivalent to ct_netconfc:unlock(Client, Target, infinity).

 unlock(Client, Target, Timeout) -> Result Unlocks the configuration target. 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 ct_netconfc:lock/2 or ct_netconfc:lock/3, this operation releases the associated lock. To access another target than running, the server must support :candidate and/or :startup.