Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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.

       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.)

DATA TYPES

         client() = handle() | server_id() | target_name():

         conn_mod() = ct_netconfc:

         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.

         hook_option() = {log_type, log_type()} | {hosts, [key_or_name()]}:

         hook_options() = [hook_option()]:

           Options that can be given to cth_conn_log in the ct_hook statement.

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

         key_or_name() = server_id() | target_name():

         log_type() = raw | pretty | html | silent:

           -type error_handler() :: module().

         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.

         server_id() = atom():

           A ServerId which exists in a configuration file.

         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()]}]:

         target_name() = atom():

           A name which is associated to a server_id() via a  require  statement  or  a  call  to
           ct:require/2 in the test suite.

         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).

       action(Client, Action, Timeout) -> Result

              Types:

                 Client = client()
                 Action = simple_xml()
                 Timeout = timeout()
                 Result = {ok, simple_xml()} | {error, error_reason()}

              Execute an action.

       close_session(Client) -> Result

              Equivalent to close_session(Client, infinity).

       close_session(Client, Timeout) -> Result

              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.

       copy_config(Client, Source, Target) -> Result

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

       copy_config(Client, Target, Source, Timeout) -> Result

              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.

       create_subscription(Client) -> term()

       create_subscription(Client, Timeout) -> term()

       create_subscription(Client, Stream, Timeout) -> term()

       create_subscription(Client, StartTime, StopTime, Timeout) -> term()

       create_subscription(Client, Stream, StartTime, StopTime, Timeout) -> term()

       create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -> Result

              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().

                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.

       delete_config(Client, Target) -> Result

              Equivalent to delete_config(Client, Target, infinity).

       delete_config(Client, Target, Timeout) -> Result

              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.

       edit_config(Client, Target, Config) -> Result

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

       edit_config(Client, Target, Config, Timeout) -> Result

              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.

       format_data(How, Data) -> term()

       get(Client, Filter) -> Result

              Equivalent to get(Client, Filter, infinity).

       get(Client, Filter, Timeout) -> Result

              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.

       get_capabilities(Client) -> Result

              Equivalent to get_capabilities(Client, infinity).

       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, 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.

       get_config(Client, Source, Filter) -> Result

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

       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()}

              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.

       get_event_streams(Client, Timeout) -> Result

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

       get_event_streams(Client, Streams, Timeout) -> Result

              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.

       get_session_id(Client) -> Result

              Equivalent to get_session_id(Client, infinity).

       get_session_id(Client, Timeout) -> Result

              Types:

                 Client = client()
                 Timeout = timeout()
                 Result = pos_integer() | {error, error_reason()}

              Returns the session id associated with the given client.

       handle_msg(X1, State) -> term()

       hello(Client) -> Result

              Equivalent to hello(Client, infinity).

       hello(Client, Timeout) -> Result

              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.

       kill_session(Client, SessionId) -> Result

              Equivalent to kill_session(Client, SessionId, infinity).

       kill_session(Client, SessionId, Timeout) -> Result

              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.

       lock(Client, Target) -> Result

              Equivalent to lock(Client, Target, infinity).

       lock(Client, Target, Timeout) -> Result

              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.

       only_open(Options) -> Result

              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.

       only_open(KeyOrName, ExtraOptions) -> Result

              Types:

                 KeyOrName = key_or_name()
                 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.

       open(Options) -> Result

              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.

       open(KeyOrName, ExtraOptions) -> Result

              Types:

                 KeyOrName = key_or_name()
                 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.

       send(Client, SimpleXml) -> Result

              Equivalent to send(Client, SimpleXml, infinity).

       send(Client, SimpleXml, Timeout) -> Result

              Types:

                 Client = client()
                 SimpleXml = simple_xml()
                 Timeout = timeout()
                 Result = ok | {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.

       send_rpc(Client, SimpleXml) -> Result

              Equivalent to send_rpc(Client, SimpleXml, infinity).

       send_rpc(Client, SimpleXml, Timeout) -> Result

              Types:

                 Client = client()
                 SimpleXml = simple_xml()
                 Timeout = timeout()
                 Result = ok | {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.

       unlock(Client, Target) -> Result

              Equivalent to unlock(Client, Target, infinity).

       unlock(Client, Target, Timeout) -> Result

              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.7.4                       ct_netconfc(3erl)