path: root/lib/common_test/doc/src/ct_netconfc.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd" [
  <!ENTITY create_subscription '<seemfa marker="#create_subscription/2"><c>create_subscription/2,3</c></seemfa>'>
  <!ENTITY send_rpc '<seemfa marker="#send_rpc/2"><c>send_rpc/2,3</c></seemfa>'>
]>

<erlref>
  <header>
    <copyright>
      <year>2010</year><year>2021</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.

    </legalnotice>

    <title>ct_netconfc</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev>A</rev>
    <file>ct_netconfc.xml</file>
  </header>
  <module since="OTP R15B02">ct_netconfc</module>
  <modulesummary>NETCONF client module.</modulesummary>

  <description>

    <p>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.</p>

    <marker id="Connecting"/>
    <p><em>Connecting to a NETCONF server</em></p>

    <p>Call <seemfa marker="#connect/1"><c>connect/1,2</c></seemfa>
    to establish a connection to a server, then pass the returned
    handle to <seemfa marker="#session/1"><c>session/1-3</c></seemfa> to
    establish a NETCONF session on a new SSH channel.
    Each call to
    <seemfa marker="#session/1"><c>session/1-3</c></seemfa> establishes a
    new session on the same connection, and results in a hello message
    to the server.</p>

    <p>Alternately,
    <seemfa marker="#open/1"><c>open/1,2</c></seemfa> can be used to
    establish a single session on a dedicated connection.
    (Or, equivalently,
    <seemfa marker="#only_open/1"><c>only_open/1,2</c></seemfa>
    followed by <seemfa marker="#hello/1"><c>hello/1-3</c></seemfa>.)</p>

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

    <pre>
 {server_id(), [option()]}.</pre>

    <p>The <seetype marker="#server_id"><c>server_id()</c></seetype>
    or an associated
    <seetype marker="ct#target_name"><c>ct:target_name()</c></seetype>
    can then be passed to the aforementioned functions to use the
    referenced configuration.</p>

    <marker id="Signaling"/>
    <p><em>Signaling</em></p>

    <p>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.
    <seemfa marker="#edit_config/3"><c>edit_config/3-5</c></seemfa>
    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;,
    that can be used to send an arbitrary RPC
    not defined in RFC 6241 or RFC 5277.</p>

    <p>All of the signaling functions have one variant with a
    <c>Timeout</c> 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.</p>

    <marker id="Logging"/>
    <p><em>Logging</em></p>

    <p>The NETCONF server uses <c>error_logger</c> for logging of NETCONF
      traffic. A special purpose error handler is implemented in
      <c>ct_conn_log_h</c>. To use this error handler, add the
      <c>cth_conn_log</c> hook in the test suite, for example:</p>

    <pre>
 suite() -&gt;
    [{ct_hooks, [{cth_conn_log, [{<seetype marker="ct#conn_log_mod"><c>ct:conn_log_mod()</c></seetype>, <seetype marker="ct#conn_log_options"><c>ct:conn_log_options()</c></seetype>}]}]}].</pre>

    <p><c>conn_log_mod()</c> is the name of the <c>Common Test</c> module
      implementing the connection protocol, for example, <c>ct_netconfc</c>.</p>

    <p>Hook option <c>log_type</c> specifies the type of logging:</p>

    <taglist>
      <tag><c>raw</c></tag>
      <item><p>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.</p></item>

      <tag><c>pretty</c></tag>
      <item><p>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.</p></item>

      <tag><c>html (default)</c></tag>
      <item><p>The sent and received NETCONF traffic is pretty printed
        directly in the test case HTML log.</p></item>

      <tag><c>silent</c></tag>
      <item><p>NETCONF traffic is not logged.</p></item>
    </taglist>

    <p>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 <c>hosts</c> 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
      <seemfa marker="#open/2"><c>open/2</c></seemfa>.</p>

    <p>Option <c>hosts</c> has no effect if <c>log_type</c> is set to
      <c>html</c> or <c>silent</c>.</p>

    <p>The hook options can also be specified in a configuration file with
      configuration variable <c>ct_conn_log</c>:</p>

    <pre>
 {ct_conn_log,[{<seetype marker="ct#conn_log_mod"><c>ct:conn_log_mod()</c></seetype>, <seetype marker="ct#conn_log_options"><c>ct:conn_log_options()</c></seetype>}]}.</pre>

    <p>For example:</p>

    <pre>
 {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
                             {hosts,[<seetype marker="ct#key_or_name"><c>ct:key_or_name()</c></seetype>]}]}]}</pre>

    <note>
      <p>Hook options specified in a configuration file overwrite the
        hard-coded hook options in the test suite.</p>
    </note>

    <p><em>Logging Example 1:</em></p>
    <marker id="Logging_example_1"/>

    <p>The following <c>ct_hooks</c> statement causes pretty printing of
      NETCONF traffic to separate logs for the connections named
      <c>nc_server1</c> and <c>nc_server2</c>. Any other connections are
      logged to default NETCONF log.</p>

    <pre>
 suite() -&gt;
    [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
                                               {hosts,[nc_server1,nc_server2]}]}
                                ]}]}].</pre>

    <p>Connections must be opened as follows:</p>

    <pre>
 open(nc_server1,[...]),
 open(nc_server2,[...]).</pre>

    <p><em>Logging Example 2:</em></p>
    <marker id="Logging_example_2"/>

    <p>The following configuration file causes raw logging of all NETCONF 
      traffic in to one single text file:</p>

    <pre>
 {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.</pre>

    <p>The <c>ct_hooks</c> statement must look as follows:</p>

    <pre>
 suite() -&gt;
    [{ct_hooks, [{cth_conn_log, []}]}].</pre>

    <p>The same <c>ct_hooks</c> statement without the configuration file
      would cause HTML logging of all NETCONF connections in to the test
      case HTML log.</p>

  </description>

  <!-- ====================================================================== -->

  <datatypes>
    <datatype>
      <name name="client"/>
      <desc>
        <p>Handle to a NETCONF session, as required by signaling
        functions.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="handle"/>
      <desc>
        <p>Handle to a connection to a NETCONF server as
        returned by
        <seemfa marker="#connect/1"><c>connect/1,2</c></seemfa>,
        or to a session as returned by
        <seemfa marker="#session/1"><c>session/1-3</c></seemfa>,
        <seemfa marker="#open/1"><c>open/1,2</c></seemfa>,
        or <seemfa marker="#only_open/1"><c>only_open/1,2</c></seemfa>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="xs_datetime"/>
      <desc>
	<p>Date and time of a startTime/stopTime element in an RFC
        5277 create-subscription request. Of XML primitive type
        <c>dateTime</c>, which has the (informal) form</p>
        <pre>
 [-]YYYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]</pre>
        <p>where <c>T</c> and <c>Z</c> are literal and <c>.s</c> is
        one or more fractional seconds.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="notification"/>
      <desc>
        <p>Event notification messages sent as a result of calls to
        &create_subscription;.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="option"/>
      <desc>
        <p>Options <c>host</c> and <c>port</c> specify the
        server endpoint to which to connect, and are passed directly
        to <seemfa
        marker="ssh:ssh#connect/3"><c>ssh:connect/4</c></seemfa>,
        as are arbitrary ssh options. Common options are <c>user</c>,
        <c>password</c> and <c>user_dir</c>.</p>

        <p>Option <c>timeout</c> 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.</p>

        <p>Option <c>receiver</c> specifies a destination for incoming
        notification messages; a left operand of the send operator
        (<c>!</c>).
        If not specified then a process calling &create_subscription;
        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.</p>

        <p>Receiver options are ignored by connect/1-3.</p>

        <p>Option <c>capability</c> 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.</p>

        <p>Capability options are ignored by connect/1-3 and only_open/1-2,
        which don't result in an outgoing hello message.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="server_id"/>
      <desc>
        <p>Identity of connection or session configuration in a
        configuration file.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="stream_data"/>
    </datatype>
    <datatype>
      <name name="stream_name"/>
    </datatype>
    <datatype>
      <name name="streams"/>
      <desc>
        <p>Stream information as returned by
        <seemfa marker="#get_event_streams/1"><c>get_event_streams/1-3</c></seemfa>.
        See RFC 5277, "XML Schema for Event Notifications", for detail
        on the format of the string values.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="xml_attribute_tag"/>
    </datatype>
    <datatype>
      <name name="xml_attribute_value"/>
    </datatype>
    <datatype>
      <name name="xml_attributes"/>
    </datatype>
    <datatype>
      <name name="xml_content"/>
    </datatype>
    <datatype>
      <name name="xml_tag"/>
    </datatype>
    <datatype>
      <name name="simple_xml"/>
      <desc>
	<p>Representation of XML, as described in application
        <seeapp marker="xmerl:index"><c>xmerl</c></seeapp>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="xpath"/>
    </datatype>
    <datatype>
      <name name="error_reason"/>
    </datatype>
    <datatype>
      <name name="host"/>
    </datatype>
    <datatype>
      <name name="netconf_db"/>
    </datatype>
  </datatypes>

  <!-- ====================================================================== -->

  <funcs>
    <func>
      <name name="action" arity="2" since="OTP R15B02"/>
      <name name="action" arity="3" since="OTP R15B02"/>
      <fsummary>Executes an action.</fsummary>
      <desc>
        <p>Executes an action. If the return type is void, <c>ok</c> is
          returned instead of <c>{ok,[simple_xml()]}</c>.</p>
      </desc>
    </func>

    <func>
      <name name="close_session" arity="1" since="OTP R15B02"/>
      <name name="close_session" arity="2" since="OTP R15B02"/>
      <fsummary>Requests graceful termination of the session associated with
        the client.</fsummary>
      <desc>
        <p>Requests graceful termination of the session associated with the
          client.</p>

        <p>When a NETCONF server receives a <c>close-session</c> 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
          <c>close-session</c> request are ignored.</p>
      </desc>
    </func>

    <func>
      <name name="connect" arity="1" since="OTP 20.0"/>
      <fsummary>Opens an SSH connection to a NETCONF server.</fsummary>
      <desc>
        <p>Opens an SSH connection to a NETCONF server.</p>

        <p>If the server options are specified in a configuration file, use
          <seemfa marker="#connect/2"><c>connect/2</c></seemfa>
          instead.</p>

        <p>The opaque <seetype marker="#handle"><c>handle()</c></seetype>
	  reference returned from this
          function is required as connection identifier when opening
          sessions over this connection, see
          <seemfa marker="#session/1"><c>session/1-3</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="connect" arity="2" since="OTP 20.0"/>
      <fsummary>Opens an SSH connection to a named NETCONF server.</fsummary>
      <desc>
        <p>Open an SSH connection to a named NETCONF server.</p>

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

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

        <p>If the server is not specified in a configuration file, use
          <seemfa marker="#connect/1"><c>connect/1</c></seemfa>
          instead.</p>

        <p>The opaque <seetype marker="#handle"><c>handle()</c></seetype>
	  reference returned from this
          function can be used as connection identifier when opening
          sessions over this connection, see
          <seemfa marker="#session/1"><c>session/1-3</c></seemfa>.
          However, if <c><anno>KeyOrName</anno></c> is a
          <c>target_name()</c>, that is, if the server is named through a
          call to <seemfa marker="ct#require/2"><c>ct:require/2</c></seemfa>
          or a <c>require</c> statement in the test suite, then this name can
          be used instead of
	  <seetype marker="#handle"><c>handle()</c></seetype>.</p>
      </desc>
    </func>

    <func>
      <name name="copy_config" arity="3" since="OTP R15B02"/>
      <name name="copy_config" arity="4" since="OTP R15B02"/>
      <fsummary>Copies configuration data.</fsummary>
      <desc>
        <p>Copies configuration data.</p>

        <p>Which source and target options that can be issued depends on the
          capabilities supported by the server. That is, <c>:candidate</c>
          and/or <c>:startup</c> are required.</p>
      </desc>
    </func>

    <func>
      <name name="create_subscription" arity="2" clause_i="1" since="OTP 22.1"/>
      <name name="create_subscription" arity="3" clause_i="1" since="OTP 22.1"/>
      <fsummary>Creates a subscription for event notifications.</fsummary>
      <desc>
        <p>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 <seetype marker="#notification"><c>notification()</c></seetype>.</p>

	<p>From RFC 5722, 2.1 Subscribing to Receive Event Notifications:</p>

        <taglist>
          <tag><c><anno>Stream</anno></c></tag>
          <item><p>Indicates which stream of event
            is of interest. If not present, events in the default NETCONF
            stream are sent.</p></item>
          <tag><c><anno>Filter</anno></c></tag>
          <item><p>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.</p></item>
          <tag><c><anno>StartTime</anno></c></tag>
          <item><p>Used to trigger the replay feature and
              indicate that the replay is to start at the time specified.
              If <c><anno>StartTime</anno></c> 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 <c><anno>StartTime</anno></c> is specified
	      earlier than the log can support, the replay begins with the
	      earliest available notification.
              This parameter is of type <c>dateTime</c> and compliant to
              RFC 3339. Implementations must support time zones.</p></item>
          <tag><c><anno>StopTime</anno></c></tag>
          <item><p>Used with the optional replay feature
              to indicate the newest notifications of interest. If
              <c><anno>StopTime</anno></c> is not present, the notifications
	      continues until the subscription is terminated.
              Must be used with and be later than <c>StartTime</c>. Values
              of <c><anno>StopTime</anno></c> in the future are valid. This
	      parameter is of type <c>dateTime</c> and compliant to RFC 3339.
              Implementations must support time zones.</p></item>
        </taglist>

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

        <p>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.</p>

        <note>
        <p>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 <c>receiver</c> option at session creation to
        provide a destination for incoming notifications independently
        of a call to &create_subscription;, and use &send_rpc; to send
        establish-subscription and other arbirary RPCs.</p>
        </note>
      </desc>
    </func>

    <func>
      <name name="delete_config" arity="2" since="OTP R15B02"/>
      <name name="delete_config" arity="3" since="OTP R15B02"/>
      <fsummary>Deletes configuration data.</fsummary>
      <desc>
        <p>Deletes configuration data.</p>

        <p>The running configuration cannot be deleted and <c>:candidate</c>
          or <c>:startup</c> must be advertised by the server.</p>
      </desc>
    </func>

     <func>
      <name name="disconnect" arity="1" since="OTP 20.0"/>
      <fsummary>Closes the given SSH connection.</fsummary>
      <desc>
	<p>Closes the given SSH connection.</p>

	<p>If there are open NETCONF sessions on the connection, these
	  will be brutally aborted. To avoid this, close each session
	  with <seemfa marker="#close_session/1"><c>close_session/1,2</c></seemfa></p>
      </desc>
    </func>

    <func>
      <name name="edit_config" arity="3" since="OTP R15B02"/>
      <name name="edit_config" arity="4" clause_i="1" since="OTP 18.0"/>
      <name name="edit_config" arity="4" clause_i="2" since="OTP R15B02"/>
      <name name="edit_config" arity="5" since="OTP 18.0"/>
      <fsummary>Edits configuration data.</fsummary>
      <desc>
        <p>Edits configuration data.</p>

        <p>By default only the running target is available, unless the server
          includes <c>:candidate</c> or <c>:startup</c> in its list of
          capabilities.</p>

        <p><c>OptParams</c> can be used for specifying optional parameters
          (<c>default-operation</c>, <c>test-option</c>, or
          <c>error-option</c>) to be added to the <c>edit-config</c>
          request. The value must be a list containing valid simple XML,
          for example:</p>

        <pre>
 [{'default-operation', ["none"]},
  {'error-option', ["rollback-on-error"]}]</pre>

	<p>If <c><anno>OptParams</anno></c> is not given, the default
	  value <c>[]</c> is used.</p>
      </desc>
    </func>

    <func>
      <name name="get" arity="2" since="OTP R15B02"/>
      <name name="get" arity="3" since="OTP R15B02"/>
      <fsummary>Gets data.</fsummary>
      <desc>
        <p>Gets data.</p>
 
        <p>This operation returns both configuration and state data from the
          server.</p>

        <p>Filter type <c>xpath</c> can be used only if the server supports
          <c>:xpath</c>.</p>
      </desc>
    </func>

    <func>
      <name name="get_capabilities" arity="1" since="OTP R15B02"/>
      <name name="get_capabilities" arity="2" since="OTP R15B02"/>
      <fsummary>Returns the server side capabilities.</fsummary>
      <desc>
        <p>Returns the server capabilities as received in its hello message.</p>
      </desc>
    </func>

    <func>
      <name name="get_config" arity="3" since="OTP R15B02"/>
      <name name="get_config" arity="4" since="OTP R15B02"/>
      <fsummary>Gets configuration data.</fsummary>
      <desc>
        <p>Gets configuration data.</p>

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

        <p>Filter type <c>xpath</c> can be used only if the server supports
          <c>:xpath</c>.</p>
      </desc>
    </func>

    <func>
      <name name="get_event_streams" arity="1" since="OTP 20.0"/>
      <name name="get_event_streams" arity="2" clause_i="1" since="OTP R15B02"/>
      <name name="get_event_streams" arity="2" clause_i="2" since="OTP 20.0"/>
      <name name="get_event_streams" arity="3" since="OTP R15B02"/>
      <fsummary>Sends a request to get the specified event streams.</fsummary>
      <desc>
        <p>Sends a request to get the specified event streams.</p>

        <p><c>Streams</c> is a list of stream names. The following filter is
          sent to the NETCONF server in a <c>get</c> request:</p>

        <pre>
 &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
   &lt;streams&gt;
     &lt;stream&gt;
       &lt;name&gt;StreamName1&lt;/name&gt;
     &lt;/stream&gt;
     &lt;stream&gt;
       &lt;name&gt;StreamName2&lt;/name&gt;
     &lt;/stream&gt;
     ...
   &lt;/streams&gt;
 &lt;/netconf&gt;</pre>

        <p>If <c>Streams</c> is an empty list, <em>all</em> streams are
          requested by sending the following filter:</p>

        <pre>
 &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
   &lt;streams/&gt;
 &lt;/netconf&gt;</pre>

        <p>If more complex filtering is needed, use
          <seemfa marker="#get/2"><c>ct_netconfc:get/2,3</c></seemfa> and
          specify the exact filter according to "XML Schema for Event
          Notifications" in RFC 5277.</p>
      </desc>
    </func>

    <func>
      <name name="get_session_id" arity="1" since="OTP R15B02"/>
      <name name="get_session_id" arity="2" since="OTP R15B02"/>
      <fsummary>Returns the session Id associated with the specified
        client.</fsummary>
      <desc>
        <p>Returns the session Id associated with the specified client.</p>
      </desc>
    </func>

    <func>
      <name name="hello" arity="1" since="OTP R15B02"/>
      <name name="hello" arity="2" since="OTP R15B02"/>
      <name name="hello" arity="3" since="OTP 17.5.3"/>
      <fsummary>Exchanges hello messages with the server.</fsummary>
      <desc>
        <p>Exchanges <c>hello</c> messages with the server. Returns
        when the server hello has been received or after the
        specified timeout.</p>

        <p>Note that capabilities for an outgoing hello can be passed
        directly to <seemfa marker="#open/2"><c>open/2</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="kill_session" arity="2" since="OTP R15B02"/>
      <name name="kill_session" arity="3" since="OTP R15B02"/>
      <fsummary>Forces termination of the session associated with the supplied
        session Id.</fsummary>
      <desc>
        <p>Forces termination of the session associated with the supplied
          session Id.</p>

        <p>The server side must abort any ongoing operations, release any
          locks and resources associated with the session, and close any
          associated connections.</p>

        <p>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.</p>

         <p>If the specified <c>SessionId</c> is equal to the current session
           Id, an error is returned.</p>
      </desc>
    </func>

    <func>
      <name name="lock" arity="2" since="OTP R15B02"/>
      <name name="lock" arity="3" since="OTP R15B02"/>
      <fsummary>Locks the configuration target.</fsummary>
      <desc>
        <p>Locks the configuration target.</p>

        <p>Which target parameters that can be used depends on if
          <c>:candidate</c> and/or <c>:startup</c> 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.</p>

         <p>Operation
           <seemfa marker="#kill_session/2"><c>kill_session/2,3</c></seemfa>
           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.</p>
      </desc>
    </func>

    <func>
      <name name="only_open" arity="1" since="OTP R15B02"/>
      <fsummary>Opens a NETCONF session, but does not send hello.</fsummary>
      <desc>
        <p>Opens a NETCONF session, but does not send <c>hello</c>.</p>

        <p>As <seemfa marker="#open/1"><c>open/1</c></seemfa>, but
          does not send a <c>hello</c> message.</p>
      </desc>
    </func>

    <func>
      <name name="only_open" arity="2" since="OTP R15B02"/>
      <fsummary>Opens a named NETCONF session, but does not send hello.</fsummary>
      <desc>
        <p>Opens a named NETCONF session, but does not send <c>hello</c>.</p>

        <p>As <seemfa marker="#open/2"><c>open/2</c></seemfa>, but
          does not send a <c>hello</c> message.</p>
      </desc>
    </func>

    <func>
      <name name="open" arity="1" since="OTP R15B02"/>
      <fsummary>Opens a NETCONF session and exchanges hello messages.</fsummary>
      <desc>
        <p>Opens a NETCONF session and exchanges <c>hello</c> messages.</p>

        <p>If the server options are specified in a configuration file,
          or if a named client is needed for logging purposes (see section
          <seeerl marker="#Logging">Logging</seeerl> in this module), use
          <seemfa marker="#open/2"><c>open/2</c></seemfa>
          instead.</p>

        <p>The opaque <seetype marker="#handle"><c>handle()</c></seetype>
	  reference returned from this
          function is required as client identifier when calling any other
          function in this module.</p>
      </desc>
    </func>

    <func>
      <name name="open" arity="2" since="OTP R15B02"/>
      <fsummary>Opens a named NETCONF session and exchanges hello
        messages.</fsummary>
      <desc>
        <p>Opens a named NETCONF session and exchanges <c>hello</c>
          messages.</p>

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

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

         <p>If the server is not specified in a configuration file, use
           <seemfa marker="#open/1"><c>open/1</c></seemfa>
           instead.</p>

         <p>The opaque <seetype marker="#handle"><c>handle()</c></seetype>
	   reference returned from this
           function can be used as client identifier when calling any other
           function in this module. However, if <c><anno>KeyOrName</anno></c> is a
           <c>target_name()</c>, that is, if the server is named through a
           call to <seemfa marker="ct#require/2"><c>ct:require/2</c></seemfa>
           or a <c>require</c> statement in the test suite, then this name can
           be used instead of
	   <seetype marker="#handle"><c>handle()</c></seetype>.</p>

         <p>See also
           <seemfa marker="ct#require/2"><c>ct:require/2</c></seemfa>.</p>
      </desc>
    </func>

    <func>
      <name name="send" arity="2" since="OTP R16B02"/>
      <name name="send" arity="3" since="OTP R16B02"/>
      <fsummary>Sends an XML document to the server.</fsummary>
      <desc>
        <p>Sends an XML document to the server.</p>

        <p>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.</p>
      </desc>
    </func>

    <func>
      <name name="send_rpc" arity="2" since="OTP R16B02"/>
      <name name="send_rpc" arity="3" since="OTP R16B02"/>
      <fsummary>Sends a NETCONF rpc request to the server.</fsummary>
      <desc>
        <p>Sends a NETCONF <c>rpc</c> request to the server.</p>

        <p>The specified XML document is wrapped in a valid NETCONF <c>rpc</c>
          request and sent to the server. The <c>message-id</c> and namespace
          attributes are added to element <c>rpc</c>.</p>

        <p>This function can be used for sending <c>rpc</c> requests that
          cannot be expressed by other interface functions in this module.</p>
      </desc>
    </func>

    <func>
      <name name="session" arity="1" since="OTP 20.0"/>
      <name name="session" arity="2" clause_i="1" since="OTP 20.0"/>
      <name name="session" arity="2" clause_i="2" since="OTP 20.0"/>
      <name name="session" arity="3" since="OTP 20.0"/>
      <fsummary>Opens a NETCONF session as a channel on the given SSH
	connection, and exchanges hello messages with the
	server.</fsummary>
      <type name="session_option"/>
      <desc>
	<p>Opens a NETCONF session as a channel on the given SSH
          connection, and exchanges hello messages with the server.</p>

        <p>The opaque <seetype marker="#handle"><c>handle()</c></seetype>
	  reference returned from this
          function can be used as client identifier when calling any
          other function in this module. However, if <c><anno>KeyOrName</anno></c>
          is used and it is a <c>target_name()</c>, that is, if the
          server is named through a call
          to <seemfa marker="ct#require/2"><c>ct:require/2</c></seemfa>
          or a <c>require</c> statement in the test suite, then this
          name can be used instead of
	  <seetype marker="#handle"><c>handle()</c></seetype>.</p>

      </desc>
    </func>

    <func>
      <name name="unlock" arity="2" since="OTP R15B02"/>
      <name name="unlock" arity="3" since="OTP R15B02"/>
      <fsummary>Unlocks the configuration target.</fsummary>
      <desc>
        <p>Unlocks the configuration target.</p>

        <p>If the client earlier has acquired a lock through
          <seemfa marker="#lock/2"><c>lock/2,3</c></seemfa>, this
          operation releases the associated lock. To access another target
          than <c>running</c>, the server must support <c>:candidate</c>
          and/or <c>:startup</c>.</p>
      </desc>
    </func>
  </funcs>

</erlref>