View Source ct_netconfc (common_test v1.27)

NETCONF client module.

NETCONF client module compliant with RFC 6241, NETCONF Configuration Protocol, and RFC 6242, Using the NETCONF Configuration Protocol over Secure SHell (SSH), and with support for RFC 5277, NETCONF Event Notifications.

Connecting to a NETCONF server

Call connect/1,2 to establish a connection to a server, then pass the returned handle to session/1-3 to establish a NETCONF session on a new SSH channel. Each call to session/1-3 establishes a new session on the same connection, and results in a hello message to the server.

Alternately, open/1,2 can be used to establish a single session on a dedicated connection. (Or, equivalently, only_open/1,2 followed by hello/1-3.)

Connect/session options can be specified in a configuration file with entries like the following.

 {server_id(), [option()]}.

The server_id/0 or an associated ct:target_name/0 can then be passed to the aforementioned functions to use the referenced configuration.

Signaling

Protocol operations in the NETCONF protocol are realized as remote procedure calls (RPCs) from client to server and a corresponding reply from server to client. RPCs are sent using like-named functions (eg. edit_config/3-5 to send an edit-config RPC), with the server reply as return value. There are functions for each RPC defined in RFC 6241 and the create-subscription RPC from RFC 5277, all of which are wrappers on send_rpc/2,3, that can be used to send an arbitrary RPC not defined in RFC 6241 or RFC 5277.

All of the signaling functions have one variant with a Timeout argument and one without, corresponding to an infinite timeout. The latter is inappropriate in most cases since a non-response by the server or a missing message-id causes the call to hang indefinitely.

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.

Summary

Types

Handle to a NETCONF session, as required by signaling functions.

Handle to a connection to a NETCONF server as returned by connect/1,2, or to a session as returned by session/1-3, open/1,2, or only_open/1,2.

Event notification messages sent as a result of calls to create_subscription/2,3.

Options host and port specify the server endpoint to which to connect, and are passed directly to ssh:connect/4, as are arbitrary ssh options. Common options are user, password and user_dir.

Identity of connection or session configuration in a configuration file.

Representation of XML, as described in application xmerl.

Stream information as returned by get_event_streams/1-3. See RFC 5277, "XML Schema for Event Notifications", for detail on the format of the string values.

Date and time of a startTime/stopTime element in an RFC 5277 create-subscription request. Of XML primitive type dateTime, which has the (informal) form

Functions

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

Requests graceful termination of the session associated with the client.

Opens an SSH connection to a NETCONF server.

Open an SSH connection to a named NETCONF server.

Creates a subscription for event notifications by sending an RFC 5277 create-subscription RPC to the server. The calling process receives events as messages of type notification/0.

Deletes configuration data.

Closes the given SSH connection.

Equivalent to get/3

Returns the server capabilities as received in its hello message.

Sends a request to get the specified event streams.

Returns the session Id associated with the specified client.

Equivalent to hello/3

Exchanges hello messages with the server. Returns when the server hello has been received or after the specified timeout.

Forces termination of the session associated with the supplied session Id.

Locks the configuration target.

Opens a NETCONF session, but does not send hello.

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

Opens a NETCONF session and exchanges hello messages.

Opens a named NETCONF session and exchanges hello messages.

Sends an XML document to the server.

Sends a NETCONF rpc request to the server.

Equivalent to session/3

Equivalent to session/3

Opens a NETCONF session as a channel on the given SSH connection, and exchanges hello messages with the server.

Unlocks the configuration target.

Types

Link to this type

client()

View Source (since OTP R15B02)
-type client() :: handle() | server_id() | ct:target_name().

Handle to a NETCONF session, as required by signaling functions.

Link to this type

error_reason()

View Source (not exported) (since OTP R15B02)
-type error_reason() :: term().
Link to this opaque

handle()

View Source (opaque) (since OTP R15B02)
-opaque handle()

Handle to a connection to a NETCONF server as returned by connect/1,2, or to a session as returned by session/1-3, open/1,2, or only_open/1,2.

Link to this type

host()

View Source (not exported) (since OTP R15B02)
-type host() :: inet:hostname() | inet:ip_address().
Link to this type

netconf_db()

View Source (not exported) (since OTP R15B02)
-type netconf_db() :: running | startup | candidate.
Link to this type

notification()

View Source (since OTP R15B02)
-type notification() :: {notification, xml_attributes(), [simple_xml()]}.

Event notification messages sent as a result of calls to create_subscription/2,3.

Link to this type

option()

View Source (not exported) (since OTP R15B02)
-type option() ::
    {host | ssh, host()} |
    {port, inet:port_number()} |
    {timeout, timeout()} |
    {capability, string() | [string()]} |
    {receiver, term()} |
    ssh:client_option().

Options host and port specify the server endpoint to which to connect, and are passed directly to ssh:connect/4, as are arbitrary ssh options. Common options are user, password and user_dir.

Option timeout specifies the number of milliseconds to allow for connection establishment and, if the function in question results in an outgoing hello message, reception of the server hello. The timeout applies to connection and hello independently; one timeout for connection establishment, another for hello reception.

Option receiver specifies a destination for incoming notification messages; a left operand of the send operator (!). If not specified then a process calling create_subscription/2,3 becomes the receiver, but explicitly setting a receiver makes it possible to receive notifications that are not ordered by calling this function. Multiple receiver options can be specified.

Receiver options are ignored by connect/1-3.

Option capability specifies the content of a corresponding element in an outgoing hello message, each option specifying the content of a single element. If no base NETCONF capability is configured then the RFC 4741 1.0 capability, "urn:ietf:params:netconf:base:1.0", is added, otherwise not. In particular, the RFC 6241 1.1 capability must be explicitly configured. NETCONF capabilities can be specified using the shorthand notation defined in RFC 6241, any capability string starting with a colon being prefixed by either "urn:ietf:params:netconf" or "urn:ietf:params:netconf:capability", as appropriate.

Capability options are ignored by connect/1-3 and only_open/1-2, which don't result in an outgoing hello message.

Link to this type

server_id()

View Source (not exported) (since OTP R15B02)
-type server_id() :: atom().

Identity of connection or session configuration in a configuration file.

Link to this type

session_option()

View Source (not exported) (since OTP R15B02)
-type session_option() ::
    {timeout, timeout()} | {receiver, term()} | {capability, string() | [string()]}.
Link to this type

simple_xml()

View Source (not exported) (since OTP R15B02)
-type simple_xml() ::
    {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag().

Representation of XML, as described in application xmerl.

Link to this type

stream_data()

View Source (not exported) (since OTP R15B02)
-type stream_data() ::
    {description, string()} |
    {replaySupport, string()} |
    {replayLogCreationTime, string()} |
    {replayLogAgedTime, string()}.
Link to this type

stream_name()

View Source (not exported) (since OTP R15B02)
-type stream_name() :: string().
Link to this type

streams()

View Source (not exported) (since OTP R15B02)
-type streams() :: [{stream_name(), [stream_data()]}].

Stream information as returned by get_event_streams/1-3. See RFC 5277, "XML Schema for Event Notifications", for detail on the format of the string values.

Link to this type

xml_attribute_tag()

View Source (not exported) (since OTP R15B02)
-type xml_attribute_tag() :: atom().
Link to this type

xml_attribute_value()

View Source (not exported) (since OTP R15B02)
-type xml_attribute_value() :: string().
Link to this type

xml_attributes()

View Source (not exported) (since OTP R15B02)
-type xml_attributes() :: [{xml_attribute_tag(), xml_attribute_value()}].
Link to this type

xml_content()

View Source (not exported) (since OTP R15B02)
-type xml_content() :: [simple_xml() | iolist()].
Link to this type

xml_tag()

View Source (not exported) (since OTP R15B02)
-type xml_tag() :: atom().
Link to this type

xpath()

View Source (not exported) (since OTP R15B02)
-type xpath() :: {xpath, string()}.
Link to this type

xs_datetime()

View Source (not exported) (since OTP R15B02)
-type xs_datetime() :: string().

Date and time of a startTime/stopTime element in an RFC 5277 create-subscription request. Of XML primitive type dateTime, which has the (informal) form

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

where T and Z are literal and .s is one or more fractional seconds.

Functions

Link to this function

action(Client, Action)

View Source (since OTP R15B02)
-spec action(Client, Action) -> Result
          when
              Client :: client(),
              Action :: simple_xml(),
              Result :: ok | {ok, [simple_xml()]} | {error, error_reason()}.

Equivalent to action/3

Link to this function

action(Client, Action, Timeout)

View Source (since OTP R15B02)
-spec action(Client, Action, Timeout) -> Result
          when
              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()]}.

Link to this function

close_session(Client)

View Source (since OTP R15B02)
-spec close_session(Client) -> Result when Client :: client(), Result :: ok | {error, error_reason()}.

Equivalent to close_session/2

Link to this function

close_session(Client, Timeout)

View Source (since OTP R15B02)
-spec close_session(Client, Timeout) -> Result
                 when
                     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.

Link to this function

connect(Options)

View Source (since OTP 20.0)
-spec connect(Options) -> Result
           when Options :: [option()], 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/0 reference returned from this function is required as connection identifier when opening sessions over this connection, see session/1-3.

Link to this function

connect(KeyOrName, ExtraOptions)

View Source (since OTP 20.0)
-spec connect(KeyOrName, ExtraOptions) -> Result
           when
               KeyOrName :: ct:key_or_name(),
               ExtraOptions :: [option()],
               Result :: {ok, handle()} | {error, error_reason()}.

Open an SSH connection to a named NETCONF server.

If KeyOrName is a configured server_id/0 or a target_name() associated with such an Id, then the options for this server are fetched from the configuration file.

The options list is added to those of the configuration file. If an option is specified in both lists, the configuration file takes precedence.

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

The opaque handle/0 reference returned from this function can be used as connection identifier when opening sessions over this connection, see session/1-3. 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/0.

Link to this function

copy_config(Client, Target, Source)

View Source (since OTP R15B02)
-spec copy_config(Client, Target, Source) -> Result
               when
                   Client :: client(),
                   Target :: netconf_db(),
                   Source :: netconf_db(),
                   Result :: ok | {error, error_reason()}.

Equivalent to copy_config/4

Link to this function

copy_config(Client, Target, Source, Timeout)

View Source (since OTP R15B02)
-spec copy_config(Client, Target, Source, Timeout) -> Result
               when
                   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.

Link to this function

create_subscription/2

View Source (since OTP 22.1)
-spec create_subscription(Client, Values) -> Result
                       when
                           Client :: client(),
                           Values ::
                               #{stream => Stream,
                                 filter => Filter,
                                 start => StartTime,
                                 stop => StopTime},
                           Stream :: stream_name(),
                           Filter :: simple_xml() | [simple_xml()],
                           StartTime :: xs_datetime(),
                           StopTime :: xs_datetime(),
                           Result :: ok | {error, error_reason()};
                   (Client, list() | timeout()) -> Result
                       when Client :: client(), Result :: ok | {error, error_reason()}.

Equivalent to create_subscription/3

Link to this function

create_subscription/3

View Source (since OTP 22.1)
-spec create_subscription(Client, Values, Timeout) -> Result
                       when
                           Client :: client(),
                           Values ::
                               #{stream => Stream,
                                 filter => Filter,
                                 start => StartTime,
                                 stop => StopTime},
                           Stream :: stream_name(),
                           Filter :: simple_xml() | [simple_xml()],
                           StartTime :: xs_datetime(),
                           StopTime :: xs_datetime(),
                           Timeout :: timeout(),
                           Result :: ok | {error, error_reason()};
                   (Client, list(), list() | timeout()) -> Result
                       when Client :: client(), Result :: ok | {error, error_reason()}.

Creates a subscription for event notifications by sending an RFC 5277 create-subscription RPC to the server. The calling process receives events as messages of type notification/0.

From RFC 5722, 2.1 Subscribing to Receive Event Notifications:

  • Stream - Indicates which stream of event is of interest. If not present, events in the default NETCONF stream are sent.

  • Filter - 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 - 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 - 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.

See RFC 5277 for more details. The requirement that StopTime must only be used with StartTime is not enforced, to allow an invalid request to be sent to the server.

Prior to OTP 22.1, this function was documented as having 15 variants in 6 arities. These are still exported for backwards compatibility, but no longer documented. The map-based variants documented above provide the same functionality with simpler arguments.

Note

create-subscription is no longer the only RPC with which NETCONF notifications can be ordered: RFC 8639 adds establish-subscription and future RFCs may add other methods. Specify a receiver option at session creation to provide a destination for incoming notifications independently of a call to create_subscription/2,3, and use send_rpc/2,3 to send establish-subscription and other arbitrary RPCs.

Link to this function

delete_config(Client, Target)

View Source (since OTP R15B02)
-spec delete_config(Client, Target) -> Result
                 when
                     Client :: client(),
                     Target :: startup | candidate,
                     Result :: ok | {error, error_reason()}.

Equivalent to delete_config/3

Link to this function

delete_config(Client, Target, Timeout)

View Source (since OTP R15B02)
-spec delete_config(Client, Target, Timeout) -> Result
                 when
                     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.

Link to this function

disconnect(Conn)

View Source (since OTP 20.0)
-spec disconnect(Conn) -> ok | {error, error_reason()} when 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

Link to this function

edit_config(Client, Target, Config)

View Source (since OTP 18.0,OTP R15B02)
-spec edit_config(Client, Target, Config) -> Result
               when
                   Client :: client(),
                   Target :: netconf_db(),
                   Config :: simple_xml() | [simple_xml()],
                   Result :: ok | {error, error_reason()}.

Equivalent to edit_config/5

Link to this function

edit_config/4

View Source (since OTP 18.0,OTP R15B02)
-spec edit_config(Client, Target, Config, OptParams) -> Result
               when
                   Client :: client(),
                   Target :: netconf_db(),
                   Config :: simple_xml() | [simple_xml()],
                   OptParams :: [simple_xml()],
                   Result :: ok | {error, error_reason()};
           (Client, Target, Config, Timeout) -> Result
               when
                   Client :: client(),
                   Target :: netconf_db(),
                   Config :: simple_xml(),
                   Timeout :: timeout(),
                   Result :: ok | {error, error_reason()}.

Equivalent to edit_config/5

Link to this function

edit_config(Client, Target, Config, OptParams, Timeout)

View Source (since OTP 18.0,OTP R15B02)
-spec edit_config(Client, Target, Config, OptParams, Timeout) -> Result
               when
                   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 OptParams is not given, the default value [] is used.

Link to this function

get(Client, Filter)

View Source (since OTP R15B02)
-spec get(Client, Filter) -> Result
       when
           Client :: client(),
           Filter :: simple_xml() | xpath(),
           Result :: {ok, [simple_xml()]} | {error, error_reason()}.

Equivalent to get/3

Link to this function

get(Client, Filter, Timeout)

View Source (since OTP R15B02)
-spec get(Client, Filter, Timeout) -> Result
       when
           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.

Link to this function

get_capabilities(Client)

View Source (since OTP R15B02)
-spec get_capabilities(Client) -> Result
                    when Client :: client(), Result :: [string()] | {error, error_reason()}.

Equivalent to get_capabilities/2

Link to this function

get_capabilities(Client, Timeout)

View Source (since OTP R15B02)
-spec get_capabilities(Client, Timeout) -> Result
                    when
                        Client :: client(),
                        Timeout :: timeout(),
                        Result :: [string()] | {error, error_reason()}.

Returns the server capabilities as received in its hello message.

Link to this function

get_config(Client, Source, Filter)

View Source (since OTP R15B02)
-spec get_config(Client, Source, Filter) -> Result
              when
                  Client :: client(),
                  Source :: netconf_db(),
                  Filter :: simple_xml() | xpath(),
                  Result :: {ok, [simple_xml()]} | {error, error_reason()}.

Equivalent to get_config/4

Link to this function

get_config(Client, Source, Filter, Timeout)

View Source (since OTP R15B02)
-spec get_config(Client, Source, Filter, Timeout) -> Result
              when
                  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.

Link to this function

get_event_streams(Client)

View Source (since OTP 20.0,OTP R15B02)
-spec get_event_streams(Client) -> Result
                     when Client :: client(), Result :: {ok, streams()} | {error, error_reason()}.

Equivalent to get_event_streams/3

Link to this function

get_event_streams/2

View Source (since OTP 20.0,OTP R15B02)
-spec get_event_streams(Client, Timeout) -> Result
                     when
                         Client :: client(),
                         Timeout :: timeout(),
                         Result :: {ok, streams()} | {error, error_reason()};
                 (Client, Streams) -> Result
                     when
                         Client :: client(),
                         Streams :: [stream_name()],
                         Result :: {ok, streams()} | {error, error_reason()}.

Equivalent to get_event_streams/3

Link to this function

get_event_streams(Client, Streams, Timeout)

View Source (since OTP 20.0,OTP R15B02)
-spec get_event_streams(Client, Streams, Timeout) -> Result
                     when
                         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.

Link to this function

get_session_id(Client)

View Source (since OTP R15B02)
-spec get_session_id(Client) -> Result
                  when Client :: client(), Result :: pos_integer() | {error, error_reason()}.

Equivalent to get_session_id/2

Link to this function

get_session_id(Client, Timeout)

View Source (since OTP R15B02)
-spec get_session_id(Client, Timeout) -> Result
                  when
                      Client :: client(),
                      Timeout :: timeout(),
                      Result :: pos_integer() | {error, error_reason()}.

Returns the session Id associated with the specified client.

Link to this function

hello(Client)

View Source (since OTP 17.5.3,OTP R15B02)
-spec hello(Client) -> Result when Client :: handle(), Result :: ok | {error, error_reason()}.

Equivalent to hello/3

Link to this function

hello(Client, Timeout)

View Source (since OTP 17.5.3,OTP R15B02)
-spec hello(Client, Timeout) -> Result
         when Client :: handle(), Timeout :: timeout(), Result :: ok | {error, error_reason()}.

Equivalent to hello/3

Link to this function

hello(Client, Options, Timeout)

View Source (since OTP 17.5.3,OTP R15B02)
-spec hello(Client, Options, Timeout) -> Result
         when
             Client :: handle(),
             Options :: [{capability, [string()]}],
             Timeout :: timeout(),
             Result :: ok | {error, error_reason()}.

Exchanges hello messages with the server. Returns when the server hello has been received or after the specified timeout.

Note that capabilities for an outgoing hello can be passed directly to open/2.

Link to this function

kill_session(Client, SessionId)

View Source (since OTP R15B02)
-spec kill_session(Client, SessionId) -> Result
                when
                    Client :: client(),
                    SessionId :: pos_integer(),
                    Result :: ok | {error, error_reason()}.

Equivalent to kill_session/3

Link to this function

kill_session(Client, SessionId, Timeout)

View Source (since OTP R15B02)
-spec kill_session(Client, SessionId, Timeout) -> Result
                when
                    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.

Link to this function

lock(Client, Target)

View Source (since OTP R15B02)
-spec lock(Client, Target) -> Result
        when Client :: client(), Target :: netconf_db(), Result :: ok | {error, error_reason()}.

Equivalent to lock/3

Link to this function

lock(Client, Target, Timeout)

View Source (since OTP R15B02)
-spec lock(Client, Target, Timeout) -> Result
        when
            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 successful, 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.

Link to this function

only_open(Options)

View Source (since OTP R15B02)
-spec only_open(Options) -> Result
             when Options :: [option()], 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.

Link to this function

only_open(KeyOrName, ExtraOptions)

View Source (since OTP R15B02)
-spec only_open(KeyOrName, ExtraOptions) -> Result
             when
                 KeyOrName :: ct:key_or_name(),
                 ExtraOptions :: [option()],
                 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.

Link to this function

open(Options)

View Source (since OTP R15B02)
-spec open(Options) -> Result
        when Options :: [option()], 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/0 reference returned from this function is required as client identifier when calling any other function in this module.

Link to this function

open(KeyOrName, ExtraOption)

View Source (since OTP R15B02)
-spec open(KeyOrName, ExtraOption) -> Result
        when
            KeyOrName :: ct:key_or_name(),
            ExtraOption :: [option()],
            Result :: {ok, handle()} | {error, error_reason()}.

Opens a named NETCONF session and exchanges hello messages.

If KeyOrName is a configured server_id/0 or a target_name() associated with such an Id, then the options for this server are fetched from the configuration file.

The options list is added to those of the configuration file. If an option is specified in both lists, the configuration file take precedence.

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

The opaque handle/0 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/0.

See also ct:require/2.

Link to this function

send(Client, SimpleXml)

View Source (since OTP R16B02)
-spec send(Client, SimpleXml) -> Result
        when
            Client :: client(),
            SimpleXml :: simple_xml(),
            Result :: simple_xml() | {error, error_reason()}.

Equivalent to send/3

Link to this function

send(Client, SimpleXml, Timeout)

View Source (since OTP R16B02)
-spec send(Client, SimpleXml, Timeout) -> Result
        when
            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.

Link to this function

send_rpc(Client, SimpleXml)

View Source (since OTP R16B02)
-spec send_rpc(Client, SimpleXml) -> Result
            when
                Client :: client(),
                SimpleXml :: simple_xml(),
                Result :: [simple_xml()] | {error, error_reason()}.

Equivalent to send_rpc/3

Link to this function

send_rpc(Client, SimpleXml, Timeout)

View Source (since OTP R16B02)
-spec send_rpc(Client, SimpleXml, Timeout) -> Result
            when
                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.

Link to this function

session(Conn)

View Source (since OTP 20.0)
-spec session(Conn) -> Result when Conn :: handle(), Result :: {ok, handle()} | {error, error_reason()}.

Equivalent to session/3

Link to this function

session/2

View Source (since OTP 20.0)
-spec session(Conn, Options) -> Result
           when
               Conn :: handle(),
               Options :: [session_option()],
               Result :: {ok, handle()} | {error, error_reason()};
       (KeyOrName, Conn) -> Result
           when
               KeyOrName :: ct:key_or_name(),
               Conn :: handle(),
               Result :: {ok, handle()} | {error, error_reason()}.

Equivalent to session/3

Link to this function

session(KeyOrName, Conn, Options)

View Source (since OTP 20.0)
-spec session(KeyOrName, Conn, Options) -> Result
           when
               Conn :: handle(),
               Options :: [session_option()],
               KeyOrName :: ct:key_or_name(),
               Result :: {ok, handle()} | {error, error_reason()}.

Opens a NETCONF session as a channel on the given SSH connection, and exchanges hello messages with the server.

The opaque handle/0 reference returned from this function can be used as client identifier when calling any other function in this module. However, if KeyOrName 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/0.

Link to this function

unlock(Client, Target)

View Source (since OTP R15B02)
-spec unlock(Client, Target) -> Result
          when Client :: client(), Target :: netconf_db(), Result :: ok | {error, error_reason()}.

Equivalent to unlock/3

Link to this function

unlock(Client, Target, Timeout)

View Source (since OTP R15B02)
-spec unlock(Client, Target, Timeout) -> Result
          when
              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.