table of contents
other versions
- wheezy-backports 1:17.3-dfsg-4~bpo70+1
- jessie 1:17.3-dfsg-4+deb8u1
- jessie-backports 1:19.2.1+dfsg-2~bpo8+1
- testing 1:19.2.1+dfsg-2
- unstable 1:19.2.1+dfsg-2
- experimental 1:19.3.1+dfsg-1
ct_netconfc(3erl) | Erlang Module Definition | ct_netconfc(3erl) |
NAME¶
ct_netconfc - Netconf client module.DESCRIPTION¶
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.
{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.)
DATA TYPES¶
- 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]
EXPORTS¶
action(Client, Action) -> Result
Equivalent to action(Client, Action, infinity).
Types:
Client = client()
Action = simple_xml()
Timeout = timeout()
Result = {ok, [simple_xml()]} | {error, error_reason()}
Execute an action.
Equivalent to close_session(Client, infinity).
Types:
Client = client()
Timeout = timeout()
Result = ok | {error, error_reason()}
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:
Client = client()
Target = netconf_db()
Source = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
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:
Client = client()
Stream = stream_name()
Filter = simple_xml() | [simple_xml()]
StartTime = xs_datetime()
StopTime = xs_datetime()
Timeout = timeout()
Result = ok | {error, error_reason()}
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().
See RFC5277 for further details about the event notification mechanism.
- 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.
Equivalent to delete_config(Client, Target, infinity).
Types:
Client = client()
Target = startup | candidate
Timeout = timeout()
Result = ok | {error, error_reason()}
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:
Client = client()
Target = netconf_db()
Config = simple_xml()
Timeout = timeout()
Result = ok | {error, error_reason()}
Edit configuration data.
Per default only the running target is available, unless the server include
:candidate or :startup in its list of capabilities.
Equivalent to get(Client, Filter, infinity).
Types:
Client = client()
Filter = simple_xml() | xpath()
Timeout = timeout()
Result = {ok, [simple_xml()]} | {error, error_reason()}
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:
Client = client()
Timeout = timeout()
Result = [string()] | {error, error_reason()}
Returns the server side capabilities
The following capability identifiers, defined in RFC 4741, can be returned:
Note, additional identifiers may exist, e.g. server side namespace.
- *
- "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"
Equivalent to get_config(Client, Source, Filter, infinity).
Types:
Client = client()
Source = netconf_db()
Filter = simple_xml() | xpath()
Timeout = timeout()
Result = {ok, [simple_xml()]} | {error, error_reason()}
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:
Client = client()
Streams = [stream_name()]
Timeout = timeout()
Result = {ok, streams()} | {error, error_reason()}
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:
Client = client()
Timeout = timeout()
Result = pos_integer() | {error, error_reason()}
Returns the session id associated with the given client.
Equivalent to hello(Client, infinity).
Types:
Client = handle()
Timeout = timeout()
Result = ok | {error, error_reason()}
Exchange hello messages with the server.
Sends a hello message to the server and waits for the return.
Equivalent to kill_session(Client, SessionId, infinity).
Types:
Client = client()
SessionId = pos_integer()
Timeout = timeout()
Result = ok | {error, error_reason()}
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:
Client = client()
Target = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
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:
Options = options()
Result = {ok, handle()} | {error, error_reason()}
Open a netconf session, but don't send hello.
As open/1 but does not send a hello message.
Types:
KeyOrName = key_or_name() (see module
ct_gen_conn)
ExtraOptions = options()
Result = {ok, handle()} | {error, error_reason()}
Open a name netconf session, but don't send hello.
As open/2 but does not send a hello message.
Types:
Options = options()
Result = {ok, handle()} | {error, error_reason()}
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:
KeyOrName = key_or_name() (see module
ct_gen_conn)
ExtraOptions = options()
Result = {ok, handle()} | {error, error_reason()}
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:
Client = client()
SimpleXml = simple_xml()
Timeout = timeout()
Result = simple_xml() | {error, error_reason()}
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:
Client = client()
SimpleXml = simple_xml()
Timeout = timeout()
Result = [simple_xml()] | {error, error_reason()}
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:
Client = client()
Target = netconf_db()
Timeout = timeout()
Result = ok | {error, error_reason()}
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.
AUTHORS¶
Support <>common_test 1.8.2 |