.TH ct_netconfc 3erl "common_test 1.16.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ct_netconfc \- NETCONF client module.
.SH DESCRIPTION
.LP
NETCONF client module\&.
.LP
The NETCONF client is compliant with RFC 4741 NETCONF Configuration Protocol and RFC 4742 Using the NETCONF Configuration Protocol over Secure SHell (SSH)\&.
.LP
\fIConnecting to a NETCONF server\fR\&
.LP
NETCONF sessions can either be opened by a single call to \fB\fIopen/1,2\fR\&\fR\& or by a call to \fB\fIconnect/1,2\fR\&\fR\& followed by one or more calls to \fB\fIsession/1,2,3\fR\&\fR\&\&.
.LP
The properties of the sessions will be exactly the same, except that when using \fB\fIconnect/1,2\fR\&\fR\&, you may start multiple sessions over the same SSH connection\&. Each session is implemented as an SSH channel\&.
.LP
\fB\fIopen/1,2\fR\&\fR\& will establish one SSH connection with one SSH channel implementing one NETCONF session\&. You may start mutiple sessions by calling \fB\fIopen/1,2\fR\&\fR\& multiple times, but then a new SSH connection will be established for each session\&.
.LP
For each server to test against, the following entry can be added to a configuration file:
.LP
.nf

 {server_id(),options()}.
.fi
.LP
The \fB\fIserver_id()\fR\&\fR\& or an associated \fB\fIct:target_name()\fR\&\fR\& must then be used in calls to \fB\fIconnect/2\fR\&\fR\& or \fB\fIopen/2\fR\&\fR\&\&.
.LP
If no configuration exists for a server, use \fB\fIconnect/1\fR\&\fR\& or \fB\fIopen/1\fR\&\fR\& instead, and specify all necessary options in the \fIOptions\fR\& parameter\&.
.LP
\fILogging\fR\&
.LP
The NETCONF server uses \fIerror_logger\fR\& for logging of NETCONF traffic\&. A special purpose error handler is implemented in \fIct_conn_log_h\fR\&\&. To use this error handler, add the \fIcth_conn_log\fR\& hook in the test suite, for example:
.LP
.nf

 suite() ->
    [{ct_hooks, [{cth_conn_log, [{\fB\fIct:conn_log_mod()\fR\&\fR\&,\fB\fIct:conn_log_options()\fR\&\fR\&}]}]}].
.fi
.LP
\fIconn_log_mod()\fR\& is the name of the \fICommon Test\fR\& module implementing the connection protocol, for example, \fIct_netconfc\fR\&\&.
.LP
Hook option \fIlog_type\fR\& specifies the type of logging:
.RS 2
.TP 2
.B
\fIraw\fR\&:
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\&.
.TP 2
.B
\fIpretty\fR\&:
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\&.
.TP 2
.B
\fIhtml (default)\fR\&:
The sent and received NETCONF traffic is pretty printed directly in the test case HTML log\&.
.TP 2
.B
\fIsilent\fR\&:
NETCONF traffic is not logged\&.
.RE
.LP
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 \fIhosts\fR\& 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 \fB\fIopen/2\fR\&\fR\&\&.
.LP
Option \fIhosts\fR\& has no effect if \fIlog_type\fR\& is set to \fIhtml\fR\& or \fIsilent\fR\&\&.
.LP
The hook options can also be specified in a configuration file with configuration variable \fIct_conn_log\fR\&:
.LP
.nf

 {ct_conn_log,[{\fB\fIct:conn_log_mod()\fR\&\fR\&,\fB\fIct:conn_log_options()\fR\&\fR\&}]}.
.fi
.LP
For example:
.LP
.nf

 {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
                             {hosts,[\fB\fIct:key_or_name()\fR\&\fR\&]}]}]}
.fi
.LP

.RS -4
.B
Note:
.RE
Hook options specified in a configuration file overwrite the hard-coded hook options in the test suite\&.

.LP
\fILogging Example 1:\fR\&
.LP
The following \fIct_hooks\fR\& statement causes pretty printing of NETCONF traffic to separate logs for the connections named \fInc_server1\fR\& and \fInc_server2\fR\&\&. Any other connections are logged to default NETCONF log\&.
.LP
.nf

 suite() ->
    [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
                                               {hosts,[nc_server1,nc_server2]}]}
                                ]}]}].
.fi
.LP
Connections must be opened as follows:
.LP
.nf

 open(nc_server1,[...]),
 open(nc_server2,[...]).
.fi
.LP
\fILogging Example 2:\fR\&
.LP
The following configuration file causes raw logging of all NETCONF traffic in to one single text file:
.LP
.nf

 {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.
.fi
.LP
The \fIct_hooks\fR\& statement must look as follows:
.LP
.nf

 suite() ->
    [{ct_hooks, [{cth_conn_log, []}]}].
.fi
.LP
The same \fIct_hooks\fR\& statement without the configuration file would cause HTML logging of all NETCONF connections in to the test case HTML log\&.
.LP
\fINotifications\fR\&
.LP
The NETCONF client is also compliant with RFC 5277 NETCONF Event Notifications, which defines a mechanism for an asynchronous message notification delivery service for the NETCONF protocol\&.
.LP
Specific functions to support this are \fB\fIcreate_subscription/1-6\fR\&\fR\& and \fB\fIget_event_streams/1-3\fR\&\fR\&\&.
.LP
\fIDefault Timeout\fR\&
.LP
Most of the functions in this module have one variant with a \fITimeout\fR\& parameter, and one without\&. If nothing else is specified, the default value \fIinfinity\fR\& is used when the \fITimeout\fR\& parameter is not given\&.
.SH DATA TYPES
.nf

\fBclient()\fR\& = \fBhandle()\fR\& | \fBserver_id()\fR\& | \fBct:target_name()\fR\&
.br
.fi
.nf

\fBerror_reason()\fR\& = term()
.br
.fi
.nf

\fBevent_time()\fR\& = {eventTime, \fBxml_attributes()\fR\&, [\fBxs_datetime()\fR\&]}
.br
.fi
.nf

\fBhandle()\fR\&
.br
.fi
.RS
.LP
Opaque reference for a connection to a NETCONF server or a NETCONF session\&.
.RE

.nf

\fBhost()\fR\& = \fBinet:hostname()\fR\& | \fBinet:ip_address()\fR\&
.br
.fi
.nf

\fBnetconf_db()\fR\& = running | startup | candidate
.br
.fi
.nf

\fBnotification()\fR\& = 
.br
    {notification, \fBxml_attributes()\fR\&, \fBnotification_content()\fR\&}
.br
.fi
.nf

\fBnotification_content()\fR\& = [\fBevent_time()\fR\& | \fBsimple_xml()\fR\&]
.br
.fi
.nf

\fBoption()\fR\& = 
.br
    {ssh, \fBhost()\fR\&} |
.br
    {port, \fBinet:port_number()\fR\&} |
.br
    {user, string()} |
.br
    {password, string()} |
.br
    {user_dir, string()} |
.br
    {timeout, timeout()}
.br
.fi
.RS
.LP
\fISshConnectOption\fR\& is any valid option to \fB\fIssh:connect/3,4\fR\&\fR\&\&. Common options used are \fIuser\fR\&, \fIpassword\fR\& and \fIuser_dir\fR\&\&. The \fISshConnectOptions\fR\& are verfied by the SSH application\&.
.RE

.nf

\fBoptions()\fR\& = [\fBoption()\fR\&]
.br
.fi
.RS
.LP
Options used for setting up an SSH connection to a NETCONF server\&.
.RE

.nf

\fBserver_id()\fR\& = atom()
.br
.fi
.RS
.LP
The identity of a server, specified in a configuration file\&.
.RE

.nf

\fBsimple_xml()\fR\& = 
.br
    {\fBxml_tag()\fR\&, \fBxml_attributes()\fR\&, \fBxml_content()\fR\&} |
.br
    {\fBxml_tag()\fR\&, \fBxml_content()\fR\&} |
.br
    \fBxml_tag()\fR\&
.br
.fi
.RS
.LP
This type is further described in application \fB\fIxmerl\fR\&\fR\&\&.
.RE

.nf

\fBstream_data()\fR\& = 
.br
    {description, string()} |
.br
    {replaySupport, string()} |
.br
    {replayLogCreationTime, string()} |
.br
    {replayLogAgedTime, string()}
.br
.fi
.RS
.LP
For details about the data format for the string values, see "XML Schema for Event Notifications" in RFC 5277\&.
.RE

.nf

\fBstream_name()\fR\& = string()
.br
.fi
.nf

\fBstreams()\fR\& = [{\fBstream_name()\fR\&, [\fBstream_data()\fR\&]}]
.br
.fi
.nf

\fBxml_attribute_tag()\fR\& = atom()
.br
.fi
.nf

\fBxml_attribute_value()\fR\& = string()
.br
.fi
.nf

\fBxml_attributes()\fR\& = 
.br
    [{\fBxml_attribute_tag()\fR\&, \fBxml_attribute_value()\fR\&}]
.br
.fi
.nf

\fBxml_content()\fR\& = [\fBsimple_xml()\fR\& | iolist()]
.br
.fi
.nf

\fBxml_tag()\fR\& = atom()
.br
.fi
.nf

\fBxpath()\fR\& = {xpath, string()}
.br
.fi
.nf

\fBxs_datetime()\fR\& = string()
.br
.fi
.RS
.LP
This date and time identifier has the same format as the XML type \fIdateTime\fR\& and is compliant with RFC 3339 Date and Time on the Internet Timestamps\&. The format is as follows:
.LP
.nf

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

.SH EXPORTS
.LP
.nf

.B
action(Client, Action) -> Result
.br
.fi
.br
.nf

.B
action(Client, Action, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Action = \fBsimple_xml()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {ok, [\fBsimple_xml()\fR\&]} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Executes an action\&. If the return type is void, \fIok\fR\& is returned instead of \fI{ok,[simple_xml()]}\fR\&\&.
.RE

.LP
.nf

.B
close_session(Client) -> Result
.br
.fi
.br
.nf

.B
close_session(Client, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Requests graceful termination of the session associated with the client\&.
.LP
When a NETCONF server receives a \fIclose-session\fR\& 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 \fIclose-session\fR\& request are ignored\&.
.RE

.LP
.nf

.B
connect(Options) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Options = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Opens an SSH connection to a NETCONF server\&.
.LP
If the server options are specified in a configuration file, use \fB\fIconnect/2\fR\&\fR\& instead\&.
.LP
The opaque \fB\fIhandle()\fR\&\fR\& reference returned from this function is required as connection identifier when opening sessions over this connection, see \fB\fIsession/1,2,3\fR\&\fR\&\&.
.LP
Option \fItimeout\fR\& (milliseconds) is used when setting up the SSH connection\&. It is not used for any other purposes during the lifetime of the connection\&.
.RE

.LP
.nf

.B
connect(KeyOrName, ExtraOptions) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
KeyOrName = \fBct:key_or_name()\fR\&
.br
ExtraOptions = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Open an SSH connection to a named NETCONF server\&.
.LP
If \fIKeyOrName\fR\& is a configured \fIserver_id()\fR\& or a \fItarget_name()\fR\& associated with such an Id, then the options for this server are fetched from the configuration file\&.
.LP
Argument \fIExtraOptions\fR\& is added to the options found in the configuration file\&. If the same options are specified, the values from the configuration file overwrite \fIExtraOptions\fR\&\&.
.LP
If the server is not specified in a configuration file, use \fB\fIconnect/1\fR\&\fR\& instead\&.
.LP
The opaque \fB\fIhandle()\fR\&\fR\& reference returned from this function can be used as connection identifier when opening sessions over this connection, see \fB\fIsession/1,2,3\fR\&\fR\&\&. However, if \fIKeyOrName\fR\& is a \fItarget_name()\fR\&, that is, if the server is named through a call to \fB\fIct:require/2\fR\&\fR\& or a \fIrequire\fR\& statement in the test suite, then this name can be used instead of \fB\fIhandle()\fR\&\fR\&\&.
.LP
Option \fItimeout\fR\& (milliseconds) is used when setting up the SSH connection\&. It is not used for any other purposes during the lifetime of the connection\&.
.RE

.LP
.nf

.B
copy_config(Client, Target, Source) -> Result
.br
.fi
.br
.nf

.B
copy_config(Client, Target, Source, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Target = Source = \fBnetconf_db()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Copies configuration data\&.
.LP
Which source and target options that can be issued depends on the capabilities supported by the server\&. That is, \fI:candidate\fR\& and/or \fI:startup\fR\& are required\&.
.RE

.LP
.B
create_subscription(Client) -> Result
.br
.B
create_subscription(Client, Stream) -> Result
.br
.B
create_subscription(Client, Stream, Filter) -> Result
.br
.B
create_subscription(Client, Stream, Filter, Timeout) -> Result
.br
.nf

.B
create_subscription(Client, Stream, Filter, StartTime, StopTime) ->
.B
                       Result
.br
.fi
.br
.nf

.B
create_subscription(Client,
.B
                    Stream,
.B
                    Filter,
.B
                    StartTime,
.B
                    StopTime,
.B
                    Timeout) ->
.B
                       Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Stream = \fBstream_name()\fR\&
.br
Filter = \fBsimple_xml()\fR\& | [\fBsimple_xml()\fR\&]
.br
StartTime = StopTime = \fBxs_datetime()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Creates a subscription for event notifications\&.
.LP
This function sets up a subscription for NETCONF event notifications of the specified stream type, matching the specified filter\&. The calling process receives notifications as messages of type \fB\fInotification()\fR\&\fR\&\&.
.LP
Only a subset of the function clauses are show above\&. The full set of valid combinations of input parameters is as follows:
.LP
.nf
create_subscription(Client)

create_subscription(Client, Timeout)
create_subscription(Client, Stream)
create_subscription(Client, Filter)

create_subscription(Client, Stream, Timeout)
create_subscription(Client, Filter, Timeout)
create_subscription(Client, Stream, Filter)
create_subscription(Client, StartTime, StopTime)

create_subscription(Client, Stream, Filter, Timeout)
create_subscription(Client, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, StartTime, StopTime)
create_subscription(Client, Filter, StartTime, StopTime)

create_subscription(Client, Stream, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, Filter, StartTime, StopTime)
create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout)
.fi
.RS 2
.TP 2
.B
\fIStream\fR\&:
Optional parameter that indicates which stream of event is of interest\&. If not present, events in the default NETCONF stream are sent\&.
.TP 2
.B
\fIFilter\fR\&:
Optional parameter that indicates which subset of all possible events is of interest\&. The parameter format is the same as that of the filter parameter in the NETCONF protocol operations\&. If not present, all events not precluded by other parameters are sent\&.
.TP 2
.B
\fIStartTime\fR\&:
Optional parameter used to trigger the replay feature and indicate that the replay is to start at the time specified\&. If \fIStartTime\fR\& is not present, this is not a replay subscription\&.
.RS 2
.LP
It is not valid to specify start times that are later than the current time\&. If \fIStartTime\fR\& is specified earlier than the log can support, the replay begins with the earliest available notification\&.
.RE

.RS 2
.LP
This parameter is of type \fIdateTime\fR\& and compliant to RFC 3339\&. Implementations must support time zones\&.
.RE

.TP 2
.B
\fIStopTime\fR\&:
Optional parameter used with the optional replay feature to indicate the newest notifications of interest\&. If \fIStopTime\fR\& is not present, the notifications continues until the subscription is terminated\&.
.RS 2
.LP
Must be used with and be later than \fIStartTime\fR\&\&. Values of \fIStopTime\fR\& in the future are valid\&. This parameter is of type \fIdateTime\fR\& and compliant to RFC 3339\&. Implementations must support time zones\&.
.RE

.RE
.LP
For more details about the event notification mechanism, see RFC 5277\&.
.RE

.LP
.nf

.B
delete_config(Client, Target) -> Result
.br
.fi
.br
.nf

.B
delete_config(Client, Target, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Target = startup | candidate
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Deletes configuration data\&.
.LP
The running configuration cannot be deleted and \fI:candidate\fR\& or \fI:startup\fR\& must be advertised by the server\&.
.RE

.LP
.nf

.B
disconnect(Conn) -> ok | {error, error_reason()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Conn = \fBhandle()\fR\&
.br
.RE
.RE
.RS
.LP
Closes the given SSH connection\&.
.LP
If there are open NETCONF sessions on the connection, these will be brutally aborted\&. To avoid this, close each session with \fB\fIclose_session/1,2\fR\&\fR\&
.RE

.LP
.nf

.B
edit_config(Client, Target, Config) -> Result
.br
.fi
.br
.nf

.B
edit_config(Client, Target, Config, OptParams) -> Result
.br
.fi
.br
.nf

.B
edit_config(Client, Target, Config, Timeout) -> Result
.br
.fi
.br
.nf

.B
edit_config(Client, Target, Config, OptParams, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Target = \fBnetconf_db()\fR\&
.br
Config = \fBsimple_xml()\fR\&
.br
OptParams = [\fBsimple_xml()\fR\&]
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Edits configuration data\&.
.LP
By default only the running target is available, unless the server includes \fI:candidate\fR\& or \fI:startup\fR\& in its list of capabilities\&.
.LP
\fIOptParams\fR\& can be used for specifying optional parameters (\fIdefault-operation\fR\&, \fItest-option\fR\&, or \fIerror-option\fR\&) to be added to the \fIedit-config\fR\& request\&. The value must be a list containing valid simple XML, for example:
.LP
.nf

 [{'default-operation', ["none"]},
  {'error-option', ["rollback-on-error"]}]
.fi
.LP
If \fIOptParams\fR\& is not given, the default value \fI[]\fR\& is used\&.
.RE

.LP
.nf

.B
get(Client, Filter) -> Result
.br
.fi
.br
.nf

.B
get(Client, Filter, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Filter = \fBsimple_xml()\fR\& | \fBxpath()\fR\&
.br
Timeout = timeout()
.br
Result = {ok, [\fBsimple_xml()\fR\&]} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Gets data\&.
.LP
This operation returns both configuration and state data from the server\&.
.LP
Filter type \fIxpath\fR\& can be used only if the server supports \fI:xpath\fR\&\&.
.RE

.LP
.nf

.B
get_capabilities(Client) -> Result
.br
.fi
.br
.nf

.B
get_capabilities(Client, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Timeout = timeout()
.br
Result = [string()] | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Returns the server side capabilities\&.
.LP
The following capability identifiers, defined in RFC 4741 NETCONF Configuration Protocol, can be returned:
.RS 2
.TP 2
*
\fI"urn:ietf:params:netconf:base:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:writable-running:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:candidate:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:confirmed-commit:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:rollback-on-error:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:startup:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:url:1\&.0"\fR\&
.LP
.TP 2
*
\fI"urn:ietf:params:netconf:capability:xpath:1\&.0"\fR\&
.LP
.RE

.LP
More identifiers can exist, for example, server-side namespace\&.
.RE

.LP
.nf

.B
get_config(Client, Source, Filter) -> Result
.br
.fi
.br
.nf

.B
get_config(Client, Source, Filter, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Source = \fBnetconf_db()\fR\&
.br
Filter = \fBsimple_xml()\fR\& | \fBxpath()\fR\&
.br
Timeout = timeout()
.br
Result = {ok, [\fBsimple_xml()\fR\&]} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Gets configuration data\&.
.LP
To be able to access another source than \fIrunning\fR\&, the server must advertise \fI:candidate\fR\& and/or \fI:startup\fR\&\&.
.LP
Filter type \fIxpath\fR\& can be used only if the server supports \fI:xpath\fR\&\&.
.RE

.LP
.nf

.B
get_event_streams(Client) -> Result
.br
.fi
.br
.nf

.B
get_event_streams(Client, Timeout) -> Result
.br
.fi
.br
.nf

.B
get_event_streams(Client, Streams) -> Result
.br
.fi
.br
.nf

.B
get_event_streams(Client, Streams, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Streams = [\fBstream_name()\fR\&]
.br
Timeout = timeout()
.br
Result = {ok, \fBstreams()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Sends a request to get the specified event streams\&.
.LP
\fIStreams\fR\& is a list of stream names\&. The following filter is sent to the NETCONF server in a \fIget\fR\& request:
.LP
.nf

 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
   <streams>
     <stream>
       <name>StreamName1</name>
     </stream>
     <stream>
       <name>StreamName2</name>
     </stream>
     ...
   </streams>
 </netconf>
.fi
.LP
If \fIStreams\fR\& is an empty list, \fIall\fR\& streams are requested by sending the following filter:
.LP
.nf

 <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
   <streams/>
 </netconf>
.fi
.LP
If more complex filtering is needed, use \fB\fIct_netconfc:get/2,3\fR\&\fR\& and specify the exact filter according to "XML Schema for Event Notifications" in RFC 5277\&.
.RE

.LP
.nf

.B
get_session_id(Client) -> Result
.br
.fi
.br
.nf

.B
get_session_id(Client, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Timeout = timeout()
.br
Result = integer() >= 1 | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Returns the session Id associated with the specified client\&.
.RE

.LP
.nf

.B
hello(Client) -> Result
.br
.fi
.br
.nf

.B
hello(Client, Timeout) -> Result
.br
.fi
.br
.nf

.B
hello(Client, Options, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBhandle()\fR\&
.br
Options = [{capability, [string()]}]
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Exchanges \fIhello\fR\& messages with the server\&.
.LP
Adds optional capabilities and sends a \fIhello\fR\& message to the server and waits for the return\&.
.RE

.LP
.nf

.B
kill_session(Client, SessionId) -> Result
.br
.fi
.br
.nf

.B
kill_session(Client, SessionId, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
SessionId = integer() >= 1
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Forces termination of the session associated with the supplied session Id\&.
.LP
The server side must abort any ongoing operations, release any locks and resources associated with the session, and close any associated connections\&.
.LP
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\&.
.LP
If the specified \fISessionId\fR\& is equal to the current session Id, an error is returned\&.
.RE

.LP
.nf

.B
lock(Client, Target) -> Result
.br
.fi
.br
.nf

.B
lock(Client, Target, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Target = \fBnetconf_db()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Locks the configuration target\&.
.LP
Which target parameters that can be used depends on if \fI:candidate\fR\& and/or \fI:startup\fR\& 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\&.
.LP
Operation \fB\fIkill_session/2,3\fR\&\fR\& 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\&.
.RE

.LP
.nf

.B
only_open(Options) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Options = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Opens a NETCONF session, but does not send \fIhello\fR\&\&.
.LP
As \fB\fIopen/1\fR\&\fR\&, but does not send a \fIhello\fR\& message\&.
.RE

.LP
.nf

.B
only_open(KeyOrName, ExtraOptions) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
KeyOrName = \fBct:key_or_name()\fR\&
.br
ExtraOptions = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Opens a named NETCONF session, but does not send \fIhello\fR\&\&.
.LP
As \fB\fIopen/2\fR\&\fR\&, but does not send a \fIhello\fR\& message\&.
.RE

.LP
.nf

.B
open(Options) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Options = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Opens a NETCONF session and exchanges \fIhello\fR\& messages\&.
.LP
If the server options are specified in a configuration file, or if a named client is needed for logging purposes (see section \fBLogging\fR\& in this module), use \fB\fIopen/2\fR\&\fR\& instead\&.
.LP
The opaque \fB\fIhandle()\fR\&\fR\& reference returned from this function is required as client identifier when calling any other function in this module\&.
.LP
Option \fItimeout\fR\& (milliseconds) is used when setting up the SSH connection and when waiting for the \fIhello\fR\& message from the server\&. It is not used for any other purposes during the lifetime of the connection\&.
.RE

.LP
.nf

.B
open(KeyOrName, ExtraOptions) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
KeyOrName = \fBct:key_or_name()\fR\&
.br
ExtraOptions = \fBoptions()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Opens a named NETCONF session and exchanges \fIhello\fR\& messages\&.
.LP
If \fIKeyOrName\fR\& is a configured \fIserver_id()\fR\& or a \fItarget_name()\fR\& associated with such an Id, then the options for this server are fetched from the configuration file\&.
.LP
Argument \fIExtraOptions\fR\& is added to the options found in the configuration file\&. If the same options are specified, the values from the configuration file overwrite \fIExtraOptions\fR\&\&.
.LP
If the server is not specified in a configuration file, use \fB\fIopen/1\fR\&\fR\& instead\&.
.LP
The opaque \fB\fIhandle()\fR\&\fR\& reference returned from this function can be used as client identifier when calling any other function in this module\&. However, if \fIKeyOrName\fR\& is a \fItarget_name()\fR\&, that is, if the server is named through a call to \fB\fIct:require/2\fR\&\fR\& or a \fIrequire\fR\& statement in the test suite, then this name can be used instead of \fB\fIhandle()\fR\&\fR\&\&.
.LP
Option \fItimeout\fR\& (milliseconds) is used when setting up the SSH connection and when waiting for the \fIhello\fR\& message from the server\&. It is not used for any other purposes during the lifetime of the connection\&.
.LP
See also \fB\fIct:require/2\fR\&\fR\&\&.
.RE

.LP
.nf

.B
send(Client, SimpleXml) -> Result
.br
.fi
.br
.nf

.B
send(Client, SimpleXml, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
SimpleXml = \fBsimple_xml()\fR\&
.br
Timeout = timeout()
.br
Result = \fBsimple_xml()\fR\& | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Sends an XML document to the server\&.
.LP
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\&.
.RE

.LP
.nf

.B
send_rpc(Client, SimpleXml) -> Result
.br
.fi
.br
.nf

.B
send_rpc(Client, SimpleXml, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
SimpleXml = \fBsimple_xml()\fR\&
.br
Timeout = timeout()
.br
Result = [\fBsimple_xml()\fR\&] | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Sends a NETCONF \fIrpc\fR\& request to the server\&.
.LP
The specified XML document is wrapped in a valid NETCONF \fIrpc\fR\& request and sent to the server\&. The \fImessage-id\fR\& and namespace attributes are added to element \fIrpc\fR\&\&.
.LP
This function can be used for sending \fIrpc\fR\& requests that cannot be expressed by other interface functions in this module\&.
.RE

.LP
.nf

.B
session(Conn) -> Result
.br
.fi
.br
.nf

.B
session(Conn, Options) -> Result
.br
.fi
.br
.nf

.B
session(KeyOrName, Conn) -> Result
.br
.fi
.br
.nf

.B
session(KeyOrName, Conn, Options) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Conn = \fBhandle()\fR\&
.br
Options = \fBsession_options()\fR\&
.br
KeyOrName = \fBct:key_or_name()\fR\&
.br
Result = {ok, \fBhandle()\fR\&} | {error, \fBerror_reason()\fR\&}
.br
.nf
\fBsession_options()\fR\& = [\fBsession_option()\fR\&]
.fi
.br
.nf
\fBsession_option()\fR\& = {timeout, timeout()}
.fi
.br
.RE
.RE
.RS
.LP
Opens a NETCONF session as a channel on the given SSH connection, and exchanges hello messages with the server\&.
.LP
The opaque \fB\fIhandle()\fR\&\fR\& reference returned from this function can be used as client identifier when calling any other function in this module\&. However, if \fIKeyOrName\fR\& is used and it is a \fItarget_name()\fR\&, that is, if the server is named through a call to \fB\fIct:require/2\fR\&\fR\& or a \fIrequire\fR\& statement in the test suite, then this name can be used instead of \fB\fIhandle()\fR\&\fR\&\&.
.RE

.LP
.nf

.B
unlock(Client, Target) -> Result
.br
.fi
.br
.nf

.B
unlock(Client, Target, Timeout) -> Result
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Client = \fBclient()\fR\&
.br
Target = \fBnetconf_db()\fR\&
.br
Timeout = timeout()
.br
Result = ok | {error, \fBerror_reason()\fR\&}
.br
.RE
.RE
.RS
.LP
Unlocks the configuration target\&.
.LP
If the client earlier has acquired a lock through \fB\fIlock/2,3\fR\&\fR\&, this operation releases the associated lock\&. To access another target than \fIrunning\fR\&, the server must support \fI:candidate\fR\& and/or \fI:startup\fR\&\&.
.RE