From 63d63920f3f68f1d3cc62184e9f1a5c51da17088 Mon Sep 17 00:00:00 2001
From: Siri Hansen
Date: Mon, 27 Mar 2017 11:54:07 +0200
Subject: [ct_netconfc] Start multiple sessions per SSH connection
The following new functions are added to ct_netconfc:
* connect/1,2 - open an SSH connection to a netconf server
* disconnect/1 - close the given SSH connectoin
* session/1,2,3 - open an SSH channel on the give connection and send
'hello' to start a netconf session.
This allows running multiple channels on on SSH connection, realizing
one netconf session per channel. The existing ct_netconfc:open will
always run one channel(session) per SSH connection.
---
lib/common_test/src/ct_conn_log_h.erl | 2 +
lib/common_test/src/ct_gen_conn.erl | 15 +-
lib/common_test/src/ct_netconfc.erl | 320 ++++++++++++++++++---
lib/common_test/src/cth_conn_log.erl | 4 +-
lib/common_test/test/ct_netconfc_SUITE.erl | 5 +-
.../ct_netconfc_SUITE_data/netconfc1_SUITE.erl | 73 ++++-
.../netconfc_remote_SUITE.erl | 2 +-
lib/common_test/test/ct_netconfc_SUITE_data/ns.erl | 6 +-
8 files changed, 361 insertions(+), 66 deletions(-)
diff --git a/lib/common_test/src/ct_conn_log_h.erl b/lib/common_test/src/ct_conn_log_h.erl
index 93e64c65fe..6c1e46925f 100644
--- a/lib/common_test/src/ct_conn_log_h.erl
+++ b/lib/common_test/src/ct_conn_log_h.erl
@@ -238,6 +238,8 @@ actionstr(#conn_log{action=cmd}) -> "----->";
actionstr(#conn_log{action=recv}) -> "<-----";
actionstr(#conn_log{action=open}) -> "opened session to";
actionstr(#conn_log{action=close}) -> "closed session to";
+actionstr(#conn_log{action=connect}) -> "connected to";
+actionstr(#conn_log{action=disconnect}) -> "disconnected from";
actionstr(_) -> "<---->".
serverstr(#conn_log{name=undefined,address={undefined,_}}) ->
diff --git a/lib/common_test/src/ct_gen_conn.erl b/lib/common_test/src/ct_gen_conn.erl
index 8b59d3ab23..5046ffade0 100644
--- a/lib/common_test/src/ct_gen_conn.erl
+++ b/lib/common_test/src/ct_gen_conn.erl
@@ -373,8 +373,9 @@ loop(Opts) ->
end;
{stop, From} ->
ct_util:unregister_connection(self()),
- (Opts#gen_opts.callback):terminate(Opts#gen_opts.conn_pid,
- Opts#gen_opts.cb_state),
+ ConnPid = Opts#gen_opts.conn_pid,
+ unlink(ConnPid),
+ (Opts#gen_opts.callback):terminate(ConnPid,Opts#gen_opts.cb_state),
return(From,ok),
ok;
{{retry,{Error,_Name,CPid,_Msg}}, From} when
@@ -411,8 +412,9 @@ loop(Opts) ->
loop(Opts#gen_opts{cb_state=NewState});
{stop,Reply,NewState} ->
ct_util:unregister_connection(self()),
- (Opts#gen_opts.callback):terminate(Opts#gen_opts.conn_pid,
- NewState),
+ ConnPid = Opts#gen_opts.conn_pid,
+ unlink(ConnPid),
+ (Opts#gen_opts.callback):terminate(ConnPid,NewState),
return(From,Reply)
end;
Msg when Opts#gen_opts.forward==true ->
@@ -422,8 +424,9 @@ loop(Opts) ->
loop(Opts#gen_opts{cb_state=NewState});
{stop,NewState} ->
ct_util:unregister_connection(self()),
- (Opts#gen_opts.callback):terminate(Opts#gen_opts.conn_pid,
- NewState)
+ ConnPid = Opts#gen_opts.conn_pid,
+ unlink(ConnPid),
+ (Opts#gen_opts.callback):terminate(ConnPid,NewState)
end
end.
diff --git a/lib/common_test/src/ct_netconfc.erl b/lib/common_test/src/ct_netconfc.erl
index ff45407fe0..28423c2200 100644
--- a/lib/common_test/src/ct_netconfc.erl
+++ b/lib/common_test/src/ct_netconfc.erl
@@ -167,7 +167,13 @@
%%----------------------------------------------------------------------
%% External exports
%%----------------------------------------------------------------------
--export([open/1,
+-export([connect/1,
+ connect/2,
+ disconnect/1,
+ session/1,
+ session/2,
+ session/3,
+ open/1,
open/2,
only_open/1,
only_open/2,
@@ -215,7 +221,9 @@
%%----------------------------------------------------------------------
%% Exported types
%%----------------------------------------------------------------------
--export_type([notification/0]).
+-export_type([client/0,
+ handle/0,
+ notification/0]).
%%----------------------------------------------------------------------
%% Internal exports
@@ -273,13 +281,15 @@
host,
port = ?DEFAULT_PORT,
timeout = ?DEFAULT_TIMEOUT,
- name}).
+ name,
+ type}).
%% Connection reference
-record(connection, {reference, % {CM,Ch}
host,
port,
- name}).
+ name,
+ type}).
%% Pending replies from server
-record(pending, {tref, % timer ref (returned from timer:xxx)
@@ -292,7 +302,7 @@
%% Type declarations
%%----------------------------------------------------------------------
-type client() :: handle() | ct_gen_conn:server_id() | ct_gen_conn:target_name().
--type handle() :: term().
+-opaque handle() :: pid().
%% An opaque reference for a connection (netconf session). See {@link
%% ct} for more information.
@@ -302,7 +312,10 @@
-type option() :: {ssh,host()} | {port,inet:port_number()} | {user,string()} |
{password,string()} | {user_dir,string()} |
{timeout,timeout()}.
+-type session_options() :: [session_option()].
+-type session_option() :: {timeout,timeout()}.
-type host() :: inet:hostname() | inet:ip_address().
+-type start_result() :: {ok,handle()} | {error,error_reason()}.
-type notification() :: {notification, xml_attributes(), notification_content()}.
-type notification_content() :: [event_time()|simple_xml()].
@@ -342,10 +355,144 @@
%% External interface functions
%%----------------------------------------------------------------------
+%%----------------------------------------------------------------------
+-spec connect(Options) -> Result when
+ Options :: options(),
+ Result :: start_result().
+%% Open an SSH connection to a Netconf server.
+%%
+%% One or more netconf sessions can then be opened as SSH channels
+%% over this connection, see session/[1,2,3]
+%% ----------------------------------------------------------------------
+connect(Options) ->
+ do_connect(Options, #options{type=connection},[]).
+
+%%----------------------------------------------------------------------
+-spec connect(KeyOrName,Options) -> Result when
+ KeyOrName :: ct_gen_conn:key_or_name(),
+ Options :: options(),
+ Result :: start_result().
+%% Open an SSH connection to a named Netconf server.
+%%
+%% If `KeyOrName' is a configured `server_id()' or a
+%% `target_name()' associated with such an ID, then the options
+%% for this server will be fetched from the configuration file.
+%%
+%% The `ExtraOptions' argument will be added to the options found in
+%% the configuration file. If the same options are given, the values
+%% from the configuration file will overwrite `ExtraOptions'.
+%%
+%% If the server is not specified in a configuration file, use {@link
+%% connect/1} instead.
+%%
+%% One or more netconf sessions can then be opened as SSH channels over
+%% this connection, see session/[1,2,3]
+%% ----------------------------------------------------------------------
+connect(KeyOrName, ExtraOptions) ->
+ SortedExtra = lists:keysort(1,ExtraOptions),
+ SortedConfig = lists:keysort(1,ct:get_config(KeyOrName,[])),
+ AllOpts = lists:ukeymerge(1,SortedConfig,SortedExtra),
+ do_connect(AllOpts,#options{name=KeyOrName,type=connection},[{name,KeyOrName}]).
+
+do_connect(OptList,InitOptRec,NameOpt) ->
+ case check_options(OptList,InitOptRec) of
+ {Host,Port,Options} ->
+ ct_gen_conn:start({Host,Port},Options,?MODULE,
+ NameOpt ++ [{reconnect,false},
+ {use_existing_connection,false},
+ {forward_messages,false}]);
+ Error ->
+ Error
+ end.
+
+%%----------------------------------------------------------------------
+-spec disconnect(Conn) -> ok | {error,error_reason()} when
+ Conn :: handle().
+%% Close the given SSH connection.
+%%----------------------------------------------------------------------
+disconnect(Conn) ->
+ case call(Conn,get_ssh_connection) of
+ {ok,_} ->
+ ct_gen_conn:stop(Conn);
+ Error ->
+ Error
+ end.
+
+%%----------------------------------------------------------------------
+-spec session(Conn) -> Result when
+ Conn :: handle(),
+ Result :: start_result().
+%% Open a netconf session as a channel on the given SSH connection,
+%% and exchange `hello' messages.
+%%----------------------------------------------------------------------
+session(Conn) ->
+ do_session(Conn,[],#options{type=channel},[]).
+
+%%----------------------------------------------------------------------
+-spec session(Conn,Options) -> Result when
+ Conn :: handle(),
+ Options :: session_options(),
+ Result :: start_result();
+ (KeyOrName,Conn) -> Result when
+ KeyOrName :: ct_gen_conn:key_or_name(),
+ Conn :: handle(),
+ Result :: start_result().
+%% Open a netconf session as a channel on the given SSH connection,
+%% and exchange `hello' messages.
+%%----------------------------------------------------------------------
+session(Conn,Options) when is_list(Options) ->
+ do_session(Conn,Options,#options{type=channel},[]);
+session(KeyOrName,Conn) ->
+ do_session(Conn,[],#options{name=KeyOrName,type=channel},[{name,KeyOrName}]).
+
+
+%%----------------------------------------------------------------------
+-spec session(KeyOrName,Conn,Options) -> Result when
+ Conn :: handle(),
+ Options :: session_options(),
+ KeyOrName :: ct_gen_conn:key_or_name(),
+ Result :: start_result().
+%% Open a netconf session as a channel on the given SSH connection,
+%% and exchange `hello' messages.
+%%----------------------------------------------------------------------
+session(KeyOrName,Conn,ExtraOptions) ->
+ SortedExtra = lists:keysort(1,ExtraOptions),
+ SortedConfig = lists:keysort(1,ct:get_config(KeyOrName,[])),
+ AllOpts = lists:ukeymerge(1,SortedConfig,SortedExtra),
+ do_session(Conn,AllOpts,#options{name=KeyOrName,type=channel},
+ [{name,KeyOrName}]).
+
+do_session(Conn,OptList,InitOptRec,NameOpt) ->
+ case call(Conn,get_ssh_connection) of
+ {ok,SshConn} ->
+ case check_session_options(OptList,InitOptRec) of
+ {ok,Options} ->
+ case ct_gen_conn:start(SshConn,Options,?MODULE,
+ NameOpt ++
+ [{reconnect,false},
+ {use_existing_connection,false},
+ {forward_messages,true}]) of
+ {ok,Client} ->
+ case hello(Client,Options#options.timeout) of
+ ok ->
+ {ok,Client};
+ Error ->
+ Error
+ end;
+ Error ->
+ Error
+ end;
+ Error ->
+ Error
+ end;
+ Error ->
+ Error
+ end.
+
%%----------------------------------------------------------------------
-spec open(Options) -> Result when
Options :: options(),
- Result :: {ok,handle()} | {error,error_reason()}.
+ Result :: start_result().
%% @doc Open a netconf session and exchange `hello' messages.
%%
%% If the server options are specified in a configuration file, or if
@@ -364,13 +511,13 @@
%% @end
%%----------------------------------------------------------------------
open(Options) ->
- open(Options,#options{},[],true).
+ open(Options,#options{type=connection_and_channel},[],true).
%%----------------------------------------------------------------------
-spec open(KeyOrName, ExtraOptions) -> Result when
KeyOrName :: ct_gen_conn:key_or_name(),
ExtraOptions :: options(),
- Result :: {ok,handle()} | {error,error_reason()}.
+ Result :: start_result().
%% @doc Open a named netconf session and exchange `hello' messages.
%%
%% If `KeyOrName' is a configured `server_id()' or a
@@ -406,10 +553,11 @@ open(KeyOrName, ExtraOpts, Hello) ->
SortedExtra = lists:keysort(1,ExtraOpts),
SortedConfig = lists:keysort(1,ct:get_config(KeyOrName,[])),
AllOpts = lists:ukeymerge(1,SortedConfig,SortedExtra),
- open(AllOpts,#options{name=KeyOrName},[{name,KeyOrName}],Hello).
+ open(AllOpts,#options{name=KeyOrName,type=connection_and_channel},
+ [{name,KeyOrName}],Hello).
open(OptList,InitOptRec,NameOpt,Hello) ->
- case check_options(OptList,undefined,undefined,InitOptRec) of
+ case check_options(OptList,InitOptRec) of
{Host,Port,Options} ->
case ct_gen_conn:start({Host,Port},Options,?MODULE,
NameOpt ++ [{reconnect,false},
@@ -433,7 +581,7 @@ open(OptList,InitOptRec,NameOpt,Hello) ->
%%----------------------------------------------------------------------
-spec only_open(Options) -> Result when
Options :: options(),
- Result :: {ok,handle()} | {error,error_reason()}.
+ Result :: start_result().
%% @doc Open a netconf session, but don't send `hello'.
%%
%% As {@link open/1} but does not send a `hello' message.
@@ -441,13 +589,13 @@ open(OptList,InitOptRec,NameOpt,Hello) ->
%% @end
%%----------------------------------------------------------------------
only_open(Options) ->
- open(Options,#options{},[],false).
+ open(Options,#options{type=connection_and_channel},[],false).
%%----------------------------------------------------------------------
-spec only_open(KeyOrName,ExtraOptions) -> Result when
KeyOrName :: ct_gen_conn:key_or_name(),
ExtraOptions :: options(),
- Result :: {ok,handle()} | {error,error_reason()}.
+ Result :: start_result().
%% @doc Open a name netconf session, but don't send `hello'.
%%
%% As {@link open/2} but does not send a `hello' message.
@@ -1072,20 +1220,34 @@ kill_session(Client, SessionId, Timeout) ->
%%----------------------------------------------------------------------
%% @private
+init(_KeyOrName,{CM,{Host,Port}},Options) ->
+ case ssh_channel(#connection{reference=CM,host=Host,port=Port},Options) of
+ {ok,Connection} ->
+ {ok, CM, #state{connection = Connection}};
+ {error,Reason}->
+ {error,Reason}
+ end;
+init(_KeyOrName,{_Host,_Port},Options) when Options#options.type==connection ->
+ case ssh_connect(Options) of
+ {ok, Connection} ->
+ ConnPid = Connection#connection.reference,
+ {ok, ConnPid, #state{connection = Connection}};
+ Error ->
+ Error
+ end;
init(_KeyOrName,{_Host,_Port},Options) ->
case ssh_open(Options) of
{ok, Connection} ->
- log(Connection,open),
{ConnPid,_} = Connection#connection.reference,
{ok, ConnPid, #state{connection = Connection}};
{error,Reason}->
{error,Reason}
end.
+
%% @private
terminate(_, #state{connection=Connection}) ->
ssh_close(Connection),
- log(Connection,close),
ok.
%% @private
@@ -1107,6 +1269,14 @@ handle_msg({hello, Options, Timeout}, From,
Error ->
{stop, Error, State}
end;
+handle_msg(get_ssh_connection, _From, #state{connection=Connection}=State) ->
+ Reply =
+ case Connection#connection.reference of
+ {_,_} -> {error,not_an_ssh_connection};
+ CM -> {ok,{CM,{Connection#connection.host,
+ Connection#connection.port}}}
+ end,
+ {reply, Reply, State};
handle_msg(_, _From, #state{session_id=undefined} = State) ->
%% Hello is not yet excanged - this shall never happen
{reply,{error,waiting_for_hello},State};
@@ -1243,15 +1413,18 @@ get_handle(Client) ->
Error
end.
+check_options(OptList,Options) ->
+ check_options(OptList,undefined,undefined,Options).
+
check_options([], undefined, _Port, _Options) ->
{error, no_host_address};
check_options([], _Host, undefined, _Options) ->
{error, no_port};
check_options([], Host, Port, Options) ->
{Host,Port,Options};
-check_options([{ssh, Host}|T], _, Port, #options{} = Options) ->
+check_options([{ssh, Host}|T], _, Port, Options) ->
check_options(T, Host, Port, Options#options{host=Host});
-check_options([{port,Port}|T], Host, _, #options{} = Options) ->
+check_options([{port,Port}|T], Host, _, Options) ->
check_options(T, Host, Port, Options#options{port=Port});
check_options([{timeout, Timeout}|T], Host, Port, Options)
when is_integer(Timeout); Timeout==infinity ->
@@ -1262,6 +1435,15 @@ check_options([Opt|T], Host, Port, #options{ssh=SshOpts}=Options) ->
%% Option verified by ssh
check_options(T, Host, Port, Options#options{ssh=[Opt|SshOpts]}).
+check_session_options([],Options) ->
+ {ok,Options};
+check_session_options([{timeout, Timeout}|T], Options)
+ when is_integer(Timeout); Timeout==infinity ->
+ check_session_options(T, Options#options{timeout = Timeout});
+check_session_options([Opt|_T], _Options) ->
+ {error, {invalid_option, Opt}}.
+
+
%%%-----------------------------------------------------------------
set_request_timer(infinity) ->
{undefined,undefined};
@@ -1356,7 +1538,6 @@ do_send_rpc(Connection, MsgId, SimpleXml) ->
do_send(Connection, SimpleXml) ->
Xml=to_xml_doc(SimpleXml),
- log(Connection,send,Xml),
ssh_send(Connection, Xml).
to_xml_doc(Simple) ->
@@ -1766,9 +1947,14 @@ decode_streams([]) ->
log(Connection,Action) ->
log(Connection,Action,<<>>).
-log(#connection{host=Host,port=Port,name=Name},Action,Data) ->
+log(#connection{reference=Ref,host=Host,port=Port,name=Name},Action,Data) ->
+ Address =
+ case Ref of
+ {_,Ch} -> {Host,Port,Ch};
+ _ -> {Host,Port}
+ end,
error_logger:info_report(#conn_log{client=self(),
- address={Host,Port},
+ address=Address,
name=Name,
action=Action,
module=?MODULE},
@@ -1915,42 +2101,84 @@ get_tag([]) ->
%%%-----------------------------------------------------------------
%%% SSH stuff
-
-ssh_open(#options{host=Host,timeout=Timeout,port=Port,ssh=SshOpts,name=Name}) ->
+ssh_connect(#options{host=Host,timeout=Timeout,port=Port,
+ ssh=SshOpts,name=Name,type=Type}) ->
case ssh:connect(Host, Port,
[{user_interaction,false},
- {silently_accept_hosts, true}|SshOpts]) of
+ {silently_accept_hosts, true}|SshOpts],
+ Timeout) of
{ok,CM} ->
- case ssh_connection:session_channel(CM, Timeout) of
- {ok,Ch} ->
- case ssh_connection:subsystem(CM, Ch, "netconf", Timeout) of
- success ->
- {ok, #connection{reference = {CM,Ch},
- host = Host,
- port = Port,
- name = Name}};
- failure ->
- ssh:close(CM),
- {error,{ssh,could_not_execute_netconf_subsystem}};
- {error,timeout} ->
- {error,{ssh,could_not_execute_netconf_subsystem,timeout}}
- end;
- {error, Reason} ->
- ssh:close(CM),
- {error,{ssh,could_not_open_channel,Reason}}
- end;
+ Connection = #connection{reference = CM,
+ host = Host,
+ port = Port,
+ name = Name,
+ type = Type},
+ log(Connection,connect),
+ {ok,Connection};
{error,Reason} ->
{error,{ssh,could_not_connect_to_server,Reason}}
end.
-ssh_send(#connection{reference = {CM,Ch}}, Data) ->
+ssh_channel(#connection{reference=CM}=Connection0,
+ #options{timeout=Timeout,name=Name,type=Type}) ->
+ case ssh_connection:session_channel(CM, Timeout) of
+ {ok,Ch} ->
+ case ssh_connection:subsystem(CM, Ch, "netconf", Timeout) of
+ success ->
+ Connection = Connection0#connection{reference = {CM,Ch},
+ name = Name,
+ type = Type},
+ log(Connection,open),
+ {ok, Connection};
+ failure ->
+ ssh_connection:close(CM,Ch),
+ {error,{ssh,could_not_execute_netconf_subsystem}};
+ {error,timeout} ->
+ ssh_connection:close(CM,Ch),
+ {error,{ssh,could_not_execute_netconf_subsystem,timeout}}
+ end;
+ {error, Reason} ->
+ {error,{ssh,could_not_open_channel,Reason}}
+ end.
+
+
+ssh_open(Options) ->
+ case ssh_connect(Options) of
+ {ok,Connection} ->
+ case ssh_channel(Connection,Options) of
+ {ok,_} = Ok ->
+ Ok;
+ Error ->
+ ssh_close(Connection),
+ Error
+ end;
+ Error ->
+ Error
+ end.
+
+ssh_send(#connection{reference = {CM,Ch}}=Connection, Data) ->
case ssh_connection:send(CM, Ch, Data) of
- ok -> ok;
- {error,Reason} -> {error,{ssh,failed_to_send_data,Reason}}
+ ok ->
+ log(Connection,send,Data),
+ ok;
+ {error,Reason} ->
+ {error,{ssh,failed_to_send_data,Reason}}
end.
-ssh_close(#connection{reference = {CM,_Ch}}) ->
- ssh:close(CM).
+ssh_close(Connection=#connection{reference = {CM,Ch}, type = Type}) ->
+ _ = ssh_connection:close(CM,Ch),
+ log(Connection,close),
+ case Type of
+ connection_and_channel ->
+ ssh_close(Connection#connection{reference = CM});
+ _ ->
+ ok
+ end,
+ ok;
+ssh_close(Connection=#connection{reference = CM}) ->
+ _ = ssh:close(CM),
+ log(Connection,disconnect),
+ ok.
%%----------------------------------------------------------------------
diff --git a/lib/common_test/src/cth_conn_log.erl b/lib/common_test/src/cth_conn_log.erl
index ef92532969..a37cc76d32 100644
--- a/lib/common_test/src/cth_conn_log.erl
+++ b/lib/common_test/src/cth_conn_log.erl
@@ -24,11 +24,11 @@
%%
%% suite() ->
%% [{ct_hooks, [{cth_conn_log,
-%% [{ct_netconfc:conn_mod(),ct_netconfc:hook_options()}]}]}].
+%% [{conn_mod(),hook_options()}]}]}].
%%
%% or specified in a configuration file:
%%
-%% {ct_conn_log,[{ct_netconfc:conn_mod(),ct_netconfc:hook_options()}]}.
+%% {ct_conn_log,[{conn_mod(),hook_options()}]}.
%%
%% The conn_mod() is the common test module implementing the protocol,
%% e.g. ct_netconfc, ct_telnet, etc. This module must log by calling
diff --git a/lib/common_test/test/ct_netconfc_SUITE.erl b/lib/common_test/test/ct_netconfc_SUITE.erl
index 8932f930d1..05edb45fe8 100644
--- a/lib/common_test/test/ct_netconfc_SUITE.erl
+++ b/lib/common_test/test/ct_netconfc_SUITE.erl
@@ -52,9 +52,8 @@ init_per_suite(Config) ->
end.
check_crypto_and_ssh() ->
- (catch code:load_file(crypto)),
- case code:is_loaded(crypto) of
- {file,_} ->
+ case code:ensure_loaded(crypto) of
+ {module,_} ->
case catch ssh:start() of
Ok when Ok==ok; Ok=={error,{already_started,ssh}} ->
ct:log("ssh started",[]),
diff --git a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
index 2aa6c4d354..6a41f0a04c 100644
--- a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
+++ b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc1_SUITE.erl
@@ -102,7 +102,9 @@ all() ->
receive_one_event,
receive_multiple_events,
receive_event_and_rpc,
- receive_event_and_rpc_in_chunks
+ receive_event_and_rpc_in_chunks,
+ multiple_channels,
+ kill_session_same_connection
]
end.
@@ -124,7 +126,7 @@ end_per_testcase(_Case, _Config) ->
ok.
init_per_suite(Config) ->
- (catch code:load_file(crypto)),
+ code:ensure_loaded(crypto),
case {ssh:start(),code:is_loaded(crypto)} of
{Ok,{file,_}} when Ok==ok; Ok=={error,{already_started,ssh}} ->
ct:log("ssh started",[]),
@@ -498,10 +500,11 @@ kill_session(Config) ->
?NS:hello(2),
?NS:expect(2,hello),
- {ok,_OtherClient} = open(SshDir),
+ {ok,OtherClient} = open(SshDir),
?NS:expect_do_reply('kill-session',{kill,2},ok),
?ok = ct_netconfc:kill_session(Client,2),
+ {error,_}=ct_netconfc:get(OtherClient,{server,[{xmlns,"myns"}],[]}),
?NS:expect_do_reply('close-session',close,ok),
?ok = ct_netconfc:close_session(Client),
@@ -1179,13 +1182,73 @@ receive_event_and_rpc_in_chunks(Config) ->
?ok = ct_netconfc:close_session(Client),
ok.
+multiple_channels(Config) ->
+ SshDir = ?config(ssh_dir,Config),
+ SshOpts = ?DEFAULT_SSH_OPTS(SshDir),
+ {ok,Conn} = ct_netconfc:connect(SshOpts),
+ ?NS:hello(1),
+ ?NS:expect(hello),
+ {ok,Client1} = ct_netconfc:session(Conn),
+ ?NS:hello(2),
+ ?NS:expect(2,hello),
+ {ok,Client2} = ct_netconfc:session(Conn),
+ ?NS:hello(3),
+ ?NS:expect(3,hello),
+ {ok,Client3} = ct_netconfc:session(Conn),
+
+ Data = [{server,[{xmlns,"myns"}],[{name,[],["myserver"]}]}],
+ ?NS:expect_reply(1,'get',{data,Data}),
+ {ok,Data} = ct_netconfc:get(Client1,{server,[{xmlns,"myns"}],[]}),
+ ?NS:expect_reply(2,'get',{data,Data}),
+ {ok,Data} = ct_netconfc:get(Client2,{server,[{xmlns,"myns"}],[]}),
+ ?NS:expect_reply(3,'get',{data,Data}),
+ {ok,Data} = ct_netconfc:get(Client3,{server,[{xmlns,"myns"}],[]}),
+
+ ?NS:expect_do_reply(2,'close-session',close,ok),
+ ?ok = ct_netconfc:close_session(Client2),
+
+ ?NS:expect_reply(1,'get',{data,Data}),
+ {ok,Data} = ct_netconfc:get(Client1,{server,[{xmlns,"myns"}],[]}),
+ {error,no_such_client}=ct_netconfc:get(Client2,{server,[{xmlns,"myns"}],[]}),
+ ?NS:expect_reply(3,'get',{data,Data}),
+ {ok,Data} = ct_netconfc:get(Client3,{server,[{xmlns,"myns"}],[]}),
+
+ ?NS:expect_do_reply(1,'close-session',close,ok),
+ ?ok = ct_netconfc:close_session(Client1),
+ ?NS:expect_do_reply(3,'close-session',close,ok),
+ ?ok = ct_netconfc:close_session(Client3),
+
+ ?ok = ct_netconfc:disconnect(Conn),
+ ok.
+
+kill_session_same_connection(Config) ->
+ SshDir = ?config(ssh_dir,Config),
+ SshOpts = ?DEFAULT_SSH_OPTS(SshDir),
+ {ok,Conn} = ct_netconfc:connect(SshOpts),
+ ?NS:hello(1),
+ ?NS:expect(hello),
+ {ok,Client1} = ct_netconfc:session(Conn),
+ ?NS:hello(2),
+ ?NS:expect(2,hello),
+ {ok,Client2} = ct_netconfc:session(Conn),
+
+ ?NS:expect_do_reply('kill-session',{kill,2},ok),
+ ?ok = ct_netconfc:kill_session(Client1,2),
+ timer:sleep(1000),
+ {error,no_such_client}=ct_netconfc:get(Client2,{server,[{xmlns,"myns"}],[]}),
+
+ ?NS:expect_do_reply('close-session',close,ok),
+ ?ok = ct_netconfc:close_session(Client1),
+
+ ok.
+
%%%-----------------------------------------------------------------
break(_Config) ->
- test_server:break("break test case").
+ ct:break("break test case").
br() ->
- test_server:break("").
+ ct:break("").
%%%-----------------------------------------------------------------
%% Open a netconf session which is not specified in a config file
diff --git a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc_remote_SUITE.erl b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc_remote_SUITE.erl
index f2580ad8e9..3ce2d18c66 100644
--- a/lib/common_test/test/ct_netconfc_SUITE_data/netconfc_remote_SUITE.erl
+++ b/lib/common_test/test/ct_netconfc_SUITE_data/netconfc_remote_SUITE.erl
@@ -62,7 +62,7 @@ stop_node(Case) ->
init_per_suite(Config) ->
- (catch code:load_file(crypto)),
+ code:ensure_loaded(crypto),
case {ssh:start(),code:is_loaded(crypto)} of
{Ok,{file,_}} when Ok==ok; Ok=={error,{already_started,ssh}} ->
ct:log("SSH started locally",[]),
diff --git a/lib/common_test/test/ct_netconfc_SUITE_data/ns.erl b/lib/common_test/test/ct_netconfc_SUITE_data/ns.erl
index 2412ea6aba..c40bf9e2cc 100644
--- a/lib/common_test/test/ct_netconfc_SUITE_data/ns.erl
+++ b/lib/common_test/test/ct_netconfc_SUITE_data/ns.erl
@@ -254,7 +254,7 @@ data(Data, State = #session{connection = ConnRef,
end.
stop_channel(CM, Ch, State) ->
- ssh:close(CM),
+ ssh_connection:close(CM,Ch),
{stop, Ch, State}.
@@ -290,8 +290,8 @@ send_frag({CM,Ch},Data) ->
%%% Kill ssh connection
-kill({CM,_Ch}) ->
- ssh:close(CM).
+kill({CM,Ch}) ->
+ ssh_connection:close(CM,Ch).
add_expect(SessionId,Add) ->
table_trans(fun do_add_expect/2,[SessionId,Add]).
--
cgit v1.2.3
From fe521f4679ed0caa068f3825869796001b29fc40 Mon Sep 17 00:00:00 2001
From: Siri Hansen
Date: Thu, 4 May 2017 17:28:01 +0200
Subject: [ct_netconfc] Update documentation
* Remove edoc comments in ct_netconfc.erl
* Rewrite ct_netconfc.xml to use specs for functions and types
* Add documentation of new functions in ct_netconfc
---
lib/common_test/doc/specs/.gitignore | 1 +
lib/common_test/doc/src/Makefile | 9 +-
lib/common_test/doc/src/ct.xml | 74 ++-
lib/common_test/doc/src/ct_netconfc.xml | 914 +++++++++++++-------------------
lib/common_test/doc/src/specs.xml | 5 +
lib/common_test/src/ct.erl | 30 ++
lib/common_test/src/ct_gen_conn.erl | 19 -
lib/common_test/src/ct_netconfc.erl | 716 ++++++-------------------
lib/common_test/src/cth_conn_log.erl | 19 +-
9 files changed, 655 insertions(+), 1132 deletions(-)
create mode 100644 lib/common_test/doc/specs/.gitignore
create mode 100644 lib/common_test/doc/src/specs.xml
diff --git a/lib/common_test/doc/specs/.gitignore b/lib/common_test/doc/specs/.gitignore
new file mode 100644
index 0000000000..322eebcb06
--- /dev/null
+++ b/lib/common_test/doc/specs/.gitignore
@@ -0,0 +1 @@
+specs_*.xml
diff --git a/lib/common_test/doc/src/Makefile b/lib/common_test/doc/src/Makefile
index 152ece5d25..e3e478ab7f 100644
--- a/lib/common_test/doc/src/Makefile
+++ b/lib/common_test/doc/src/Makefile
@@ -106,11 +106,17 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
+
+TOP_SPECS_FILE = specs.xml
+
# ----------------------------------------------------
# FLAGS
# ----------------------------------------------------
XML_FLAGS +=
DVIPS_FLAGS +=
+SPECS_FLAGS = -I../../include -I../../../snmp/include \
+ -I../../../kernel/include
# ----------------------------------------------------
# Targets
@@ -119,7 +125,7 @@ DVIPS_FLAGS +=
$(HTMLDIR)/%.gif: %.gif
$(INSTALL_DATA) $< $@
-docs: pdf html man
+docs: man pdf html
$(TOP_PDF_FILE): $(XML_FILES)
@@ -140,6 +146,7 @@ clean clean_docs:
rm -f $(MAN3DIR)/*
rm -f $(MAN6DIR)/*
rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+ rm -f $(SPECDIR)/*
rm -f errs core *~
# ----------------------------------------------------
diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml
index 82fcd80375..1a3cfdb0c5 100644
--- a/lib/common_test/doc/src/ct.xml
+++ b/lib/common_test/doc/src/ct.xml
@@ -70,17 +70,69 @@
- handle() = pid()
- -
-
The identity (handle) of a connection.
-
- target_name() = atom()
- -
-
A name and association to configuration data introduced
- through a require statement, or a call to
- ct:require/2,
- for example,
- ct:require(mynodename,{node,[telnet]}).
+
+
+ handle() = pid()
+
+ -
+
The identity (handle) of a connection.
+
+
+
+
+ config_key() = atom()
+
+ -
+
A configuration key which exists in a configuration file
+
+
+
+ target_name() = atom()
+
+ -
+
A name and association to configuration data introduced
+ through a require statement, or a call to
+ ct:require/2,
+ for example,
+ ct:require(mynodename,{node,[telnet]}).
+
+
+
+
+ key_or_name() = config_key() | target_name()
+
+
+
+
+
+ conn_log_options() = [conn_log_option()]
+
+ -
+
Options that can be given to the cth_conn_log hook,
+ which is used for logging of NETCONF and Telnet
+ connections. See
+ ct_netconfc
+ or ct_telnet
+ for description and examples of how to use this hook.
+
+
+
+
+ conn_log_option() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}
+
+
+
+
+
+ conn_log_type() = raw | pretty | html | silent
+
+
+
+
+
+ conn_log_mod() = ct_netconfc | ct_telnet
+
+
diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml
index e6930b30d5..ab83f50733 100644
--- a/lib/common_test/doc/src/ct_netconfc.xml
+++ b/lib/common_test/doc/src/ct_netconfc.xml
@@ -35,13 +35,35 @@
ct_netconfc
NETCONF client module.
-
+
NETCONF client module.
The NETCONF client is compliant with RFC 4741 NETCONF Configuration
Protocol and RFC 4742 Using the NETCONF Configuration Protocol over
- Secure SHell (SSH)..
+ Secure SHell (SSH).
+
+
+ Connecting to a NETCONF server
+
+ NETCONF sessions can either be opened by a single call
+ to open/1,2 or by a call
+ to connect/1,2 followed
+ by one or more calls to
+ session/1,2,3.
+
+ The properties of the sessions will be exactly the same, except
+ that when
+ using connect/1,2, you
+ may start multiple sessions over the same SSH connection. Each
+ session is implemented as an SSH channel.
+
+ open/1,2 will establish one
+ SSH connection with one SSH channel implementing one NETCONF
+ session. You may start mutiple sessions by
+ calling open/1,2 multiple
+ times, but then a new SSH connection will be established for each
+ session.
For each server to test against, the following entry can be added to a
configuration file:
@@ -49,23 +71,21 @@
{server_id(),options()}.
- The server_id() or an associated target_name() (see
- module ct) must then be used
- in calls to
- ct_netconfc:open/2.
+ The server_id()
+ or an associated
+ ct:target_name()
+ must then be used in calls to
+ connect/2
+ or open/2.
- If no configuration exists for a server, a session can still be
- opened by calling
- ct_netconfc:open/2 with
- all necessary options specified in the call. The first argument to
- ct_netconfc:open/2 can
- then be any atom.
+ If no configuration exists for a server,
+ use connect/1
+ or open/1 instead,
+ and specify all necessary options in the Options parameter.
-
+
+ Logging
-
-
- 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
@@ -73,9 +93,9 @@
suite() ->
- [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
+ [{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(),ct:conn_log_options()}]}]}].
- conn_mod() is the name of the Common Test module
+
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:
@@ -84,7 +104,7 @@
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.
.
+ added to the test case HTML log.
pretty
The sent and received NETCONF data is logged to a separate
@@ -104,7 +124,7 @@
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
- ct_netconfc:open/2.
+ open/2.
Option hosts has no effect if log_type is set to
html or silent.
@@ -113,13 +133,13 @@
configuration variable ct_conn_log:
- {ct_conn_log,[{conn_mod(),hook_options()}]}.
+ {ct_conn_log,[{ct:conn_log_mod(),ct:conn_log_options()}]}.
For example:
{ct_conn_log,[{ct_netconfc,[{log_type,pretty},
- {hosts,[key_or_name()]}]}]}
+ {hosts,[ct:key_or_name()]}]}]}
Hook options specified in a configuration file overwrite the
@@ -164,173 +184,149 @@
The same ct_hooks statement without the configuration file
would cause HTML logging of all NETCONF connections in to the test
case HTML log.
-
-
-
- Notifications
+
+ Notifications
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.
Specific functions to support this are
- ct_netconfc:create_subscription/6
+ create_subscription/1-6
and
- ct_netconfc:get_event_streams/3.
- (The functions also exist with other arities.)
-
-
-
- Data Types
-
-
- client() = handle() | key_or_name()
- -
-
For handle(), see module
- ct.
-
- error_reason() = term()
- -
- event_time() = {eventTime, xml_attributes(), [xs_datetime()]}
- -
-
- handle() = term()
- -
-
Opaque reference for a connection (NETCONF session). For more
- information, see module ct.
-
-
- host() = inet:hostname()
- | inet:ip_address()
-
-
- key_or_name() = server_id() | target_name()
- -
-
For target_name, see module
- ct.
-
- netconf_db() = running | startup | candidate
- -
+ get_event_streams/1-3.
- notification() = {notification, xml_attributes(), notification_content()}
- -
+
+ Default Timeout
- notification_content() = [event_time() | simple_xml()]
- -
+ Most of the functions in this module have one variant with
+ a Timeout parameter, and one without. If nothing else is
+ specified, the default value infinity is used when
+ the Timeout parameter is not given.
- option() = {ssh, host()} | {port,
- inet:port_number()
- } | {timeout, timeout()} | SshConnectOption
- -
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Opaque reference for a connection to a NETCONF server or a
+ NETCONF session.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
SshConnectOption is any valid option to
ssh:connect/3,4.
Common options used are user, password
and user_dir. The SshConnectOptions are
- verfied by the SSH application.
-
- options() = [option()]
- -
-
Options used for setting up an SSH connection to a NETCONF
- server.
-
- server_id() = atom()
- -
+ verfied by the SSH application.
+
+
+
+
+
+
Options used for setting up an SSH connection to a NETCONF
+ server.
+
+
+
+
+
The identity of a server, specified in a configuration
- file.
-
- simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()
- -
-
This type is further described in application
- xmerl.
-
- stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}
- -
-
For details about the data format for the string values, see
- "XML Schema for Event Notifications" in RFC 5277.
-
- stream_name() = string()
- -
-
- streams() = [{stream_name(), [stream_data()]}]
- -
-
- xml_attribute_tag() = atom()
- -
-
- xml_attribute_value() = string()
- -
-
- xml_attributes() = [{xml_attribute_tag(), xml_attribute_value()}]
- -
-
- xml_content() = [simple_xml() | iolist()]
- -
-
- xml_tag() = atom()
- -
-
- xpath() = {xpath, string()}
- -
-
- xs_datetime() = string()
- -
-
This date and time identifier has the same format as the XML type
+ file.
+
+
+
+
+
+ This type is further described in application
+ xmerl.
+
+
+
+
+
+ For details about the data format for the string values, see
+ "XML Schema for Event Notifications" in RFC 5277.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This date and time identifier has the same format as the XML type
dateTime and is compliant with RFC 3339 Date and Time on
the Internet Timestamps. The format is as follows:
-
+
[-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
-
-
-
-
-
-
- action(Client, Action) -> Result
- Equivalent to action(Client, Action, infinity).
-
- Equivalent to
- ct_netconfc:action(Client, Action,
- infinity).
-
+
+
+
- action(Client, Action, Timeout) -> Result
+
+
Executes an action.
-
- 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()]}.
- close_session(Client) -> Result
- Equivalent to close_session(Client, infinity).
-
- Equivalent to
- ct_netconfc:close_session(Client,
- infinity).
-
-
-
-
- close_session(Client, Timeout) -> Result
+
+
Requests graceful termination of the session associated with
the client.
-
- Client = client()
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
+
Requests graceful termination of the session associated with the
client.
@@ -343,115 +339,148 @@
- copy_config(Client, Source, Target) -> Result
- Equivalent to copy_config(Client, Source, Target,
- infinity).
-
- Equivalent to
- ct_netconfc:copy_config(Client,
- Source, Target, infinity).
-
-
+
+ Opens an SSH connection to a NETCONF server.
+
+ Opens an SSH connection to a NETCONF server.
-
- copy_config(Client, Target, Source, Timeout) -> Result
- Copies configuration data.
-
- Client = client()
- Target = netconf_db()
- Source = netconf_db()
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
- Copies configuration data.
+ If the server options are specified in a configuration file, use
+ connect/2
+ instead.
- 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.
+ The opaque handle()
+ reference returned from this
+ function is required as connection identifier when opening
+ sessions over this connection, see
+ session/1,2,3.
+
+ Option timeout (milliseconds) is used when setting up the
+ SSH connection. It is not used for any other purposes during the
+ lifetime of the connection.
- create_subscription(Client) -> term()
- Creates a subscription for event notifications.
-
-
+
+ Opens an SSH connection to a named NETCONF server.
+
+ Open an SSH connection to a named NETCONF server.
-
- create_subscription(Client, Timeout) -> term()
- Creates a subscription for event notifications.
-
-
+ If KeyOrName is a
+ configured server_id() or a
+ target_name() associated with such an Id, then the options
+ for this server are fetched from the configuration file.
-
- create_subscription(Client, Stream, Timeout) -> term()
- Creates a subscription for event notifications.
-
-
+ Argument ExtraOptions is added to the
+ options found in the configuration file. If the same options
+ are specified, the values from the configuration file
+ overwrite ExtraOptions.
-
- create_subscription(Client, StartTime, StopTime, Timeout) -> term()
- Creates a subscription for event notifications.
-
+ If the server is not specified in a configuration file, use
+ connect/1
+ instead.
+
+ The opaque handle()
+ reference returned from this
+ function can be used as connection identifier when opening
+ sessions over this connection, see
+ session/1,2,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().
+
+ Option timeout (milliseconds) is used when setting up the
+ SSH connection. It is not used for any other purposes during the
+ lifetime of the connection.
+
- create_subscription(Client, Stream, StartTime, StopTime, Timeout) -> term()
- Creates a subscription for event notifications.
-
+
+
+ Copies configuration data.
+
+ 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.
+
- create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -> Result
+ create_subscription(Client) -> Result
+ create_subscription(Client, Stream) -> Result
+ create_subscription(Client, Stream, Filter) -> Result
+ create_subscription(Client, Stream, Filter, Timeout) -> Result
+
+
Creates a subscription for event notifications.
-
- Client = client()
- Stream = stream_name()
- Filter = simple_xml() | [simple_xml()]
- StartTime = xs_datetime()
- StopTime = xs_datetime()
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
+
Creates a subscription for event notifications.
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 notification().
+ type notification().
+
+ Only a subset of the function clauses are show above. The
+ full set of valid combinations of input parameters is as
+ follows:
+
+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)
- Stream
+ Stream
Optional parameter that indicates which stream of event
is of interest. If not present, events in the default NETCONF
stream are sent.
- Filter
+ Filter
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.
- StartTime
+ StartTime
Optional parameter 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.
+ 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.
+ 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
+ StopTime
Optional parameter 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.
+ 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.
+ of StopTime in the future are valid. This
+ parameter is of type dateTime and compliant to RFC 3339.
Implementations must support time zones.
@@ -461,25 +490,10 @@
- delete_config(Client, Target) -> Result
- Equivalent to delete_config(Client, Target,
- infinity).
-
- Equivalent to
- ct_netconfc:delete_config(Client, Target, infinity).
-
-
-
-
- delete_config(Client, Target, Timeout) -> Result
+
+
Deletes configuration data.
-
- Client = client()
- Target = startup | candidate
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
+
Deletes configuration data.
The running configuration cannot be deleted and :candidate
@@ -487,54 +501,25 @@
-
- edit_config(Client, Target, Config) -> Result
- Equivalent to edit_config(Client, Target, Config, [],
- infinity).
-
- Equivalent to
- ct_netconfc:edit_config(Client,
- Target, Config, [], infinity).
-
-
+
+
+ Closes the given SSH connection.
+
+ Closes the given SSH connection.
-
- edit_config(Client, Target, Config, OptParamsOrTimeout) -> Result
- If OptParamsOrTimeout is a time-out value, this function is
- equivalent to ct_netconfc:edit_config(Client, Target, Config, [],
- Timeout).
-
- Client = client()
- Target = netconf_db()
- Config = simple_xml()
- OptParamsOrTimeout = [simple_xml()] | timeout()
- Result = ok | {error, error_reason()}
-
-
- If OptParamsOrTimeout is a time-out value, this function is
- equivalent to
- ct_netconfc:edit_config(Client,
- Target, Config, [], Timeout).
-
- If OptParamsOrTimeout is a list of simple XML, this
- function is equivalent to
- ct_netconfc:edit_config(Client,
- Target, Config, OptParams, infinity).
+ 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
- edit_config(Client, Target, Config, OptParams, Timeout) -> Result
+
+
+
+
Edits configuration data.
-
- Client = client()
- Target = netconf_db()
- Config = 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
@@ -550,29 +535,17 @@
[{'default-operation', ["none"]},
{'error-option', ["rollback-on-error"]}]
-
-
-
- get(Client, Filter) -> Result
- Equivalent to get(Client, Filter, infinity).
-
- Equivalent to
- ct_netconfc:get(Client, Filter,
- infinity).
+ If OptParams is not given, the default
+ value [] is used.
- get(Client, Filter, Timeout) -> Result
+
+
Gets data.
-
- 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
@@ -584,24 +557,10 @@
- get_capabilities(Client) -> Result
- Equivalent to get_capabilities(Client, infinity).
-
- Equivalent to
- ct_netconfc:get_capabilities(Client,
- infinity).
-
-
-
-
- get_capabilities(Client, Timeout) -> Result
+
+
Returns the server side capabilities.
-
- Client = client()
- Timeout = timeout()
- Result = [string()] | {error, error_reason()}
-
-
+
Returns the server side capabilities.
The following capability identifiers, defined in RFC 4741 NETCONF
@@ -623,26 +582,10 @@
- get_config(Client, Source, Filter) -> Result
- Equivalent to get_config(Client, Source, Filter,
- infinity).
-
- Equivalent to
- ct_netconfc:get_config(Client, Source, Filter, infinity).
-
-
-
-
- get_config(Client, Source, Filter, Timeout) -> Result
+
+
Gets configuration data.
-
- 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
@@ -654,25 +597,12 @@
- get_event_streams(Client, Timeout) -> Result
- Equivalent to get_event_streams(Client, [], Timeout).
-
- Equivalent to
- ct_netconfc:get_event_streams(Client,
- [], Timeout).
-
-
-
-
- get_event_streams(Client, Streams, Timeout) -> Result
+
+
+
+
Sends a request to get the specified event streams.
-
- 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
@@ -700,67 +630,28 @@
</netconf>
If more complex filtering is needed, use
- ct_netconfc:get/2 or
- ct_netconfc:get/3 and
+ ct_netconfc:get/2,3 and
specify the exact filter according to "XML Schema for Event
Notifications" in RFC 5277.
- get_session_id(Client) -> Result
- Equivalent to get_session_id(Client, infinity).
-
- Equivalent to
- ct_netconfc:get_session_id(Client,
- infinity).
-
-
-
-
- get_session_id(Client, Timeout) -> Result
+
+
Returns the session Id associated with the specified
client.
-
- Client = client()
- Timeout = timeout()
- Result = pos_integer() | {error, error_reason()}
-
-
+
Returns the session Id associated with the specified client.
- hello(Client) -> Result
- Equivalent to hello(Client, [], infinity).
-
- Equivalent to
- ct_netconfc:hello(Client, [],
- infinity).
-
-
-
-
- hello(Client, Timeout) -> Result
- Equivalent to hello(Client, [], Timeout).
-
- Equivalent to
- ct_netconfc:hello(Client, [],
- Timeout).
-
-
-
-
- hello(Client, Options, Timeout) -> Result
+
+
+
Exchanges hello messages with the server.
-
- Client = handle()
- Options = [{capability, [string()]}]
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
+
Exchanges hello messages with the server.
Adds optional capabilities and sends a hello message to the
@@ -769,27 +660,11 @@
- kill_session(Client, SessionId) -> Result
- Equivalent to kill_session(Client, SessionId,
- infinity).
-
- Equivalent to
- ct_netconfc:kill_session(Client,
-SessionId, infinity).
-
-
-
-
- kill_session(Client, SessionId, Timeout) -> Result
+
+
Forces termination of the session associated with the supplied
session Id.
-
- Client = client()
- SessionId = pos_integer()
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
+
Forces termination of the session associated with the supplied
session Id.
@@ -807,26 +682,11 @@ SessionId, infinity).
- lock(Client, Target) -> Result
- Equivalent to lock(Client, Target, infinity).
-
- Equivalent to
- ct_netconfc:lock(Client, Target,
- infinity).
-
-
-
-
- lock(Client, Target, Timeout) -> Result
- Unlocks the configuration target.
-
- Client = client()
- Target = netconf_db()
- Timeout = timeout()
- Result = ok | {error, error_reason()}
-
-
- Unlocks the configuration target.
+
+
+ Locks the configuration target.
+
+ Locks the configuration target.
Which target parameters that can be used depends on if
:candidate and/or :startup are supported by the
@@ -835,9 +695,7 @@ SessionId, infinity).
Locks are intended to be short-lived.
Operation
- ct_netconfc:kill_session/2
- or
- ct_netconfc:kill_session/3
+ 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.
@@ -845,54 +703,41 @@ SessionId, infinity).
- only_open(Options) -> Result
+
Opens a NETCONF session, but does not send hello.
-
- Options = options()
- Result = {ok, handle()} | {error, error_reason()}
-
-
+
Opens a NETCONF session, but does not send hello.
- As ct_netconfc:open/1,
- but does not send a hello message.
+ As open/1, but
+ does not send a hello message.
- only_open(KeyOrName, ExtraOptions) -> Result
- Opens a name NETCONF session, but does not send
- hello.
-
- KeyOrName = key_or_name()
- ExtraOptions = options()
- Result = {ok, handle()} | {error, error_reason()}
-
-
- Opens a name NETCONF session, but does not send hello.
-
- As ct_netconfc:open/2,
- but does not send a hello message.
+
+ Opens a named NETCONF session, but does not send hello.
+
+ Opens a named NETCONF session, but does not send hello.
+
+ As open/2, but
+ does not send a hello message.
- open(Options) -> Result
- Opens a NETCONF session and exchanges hello messages.
-
- Options = options()
- Result = {ok, handle()} | {error, error_reason()}
-
-
+
+ Opens a NETCONF session and exchanges hello messages.
+
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
- ct_netconfc:open/2
+ open/2
instead.
- The opaque handle() reference returned from this
+
The opaque handle()
+ reference returned from this
function is required as client identifier when calling any other
function in this module.
@@ -904,37 +749,36 @@ SessionId, infinity).
- open(KeyOrName, ExtraOptions) -> Result
+
Opens a named NETCONF session and exchanges hello
messages.
-
- KeyOrName = key_or_name()
- ExtraOptions = options()
- Result = {ok, handle()} | {error, error_reason()}
-
-
+
Opens a named NETCONF session and exchanges hello
messages.
- If KeyOrName is a configured server_id() or a
+
If KeyOrName is a
+ configured server_id() or a
target_name() associated with such an Id, then the options
for this server are fetched from the configuration file.
- Argument ExtraOptions is added to the options found in the
- configuration file. If the same options are specified, the values
- from the configuration file overwrite ExtraOptions.
+ Argument ExtraOptions is added to the
+ options found in the configuration file. If the same
+ options are specified, the values from the configuration
+ file overwrite ExtraOptions.
If the server is not specified in a configuration file, use
- ct_netconfc:open/1
+ open/1
instead.
- The opaque handle() reference returned from this
+
The opaque handle()
+ reference returned from this
function can be used as client identifier when calling any other
- function in this module. However, if KeyOrName is a
+ 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().
+ be used instead of
+ handle().
Option timeout (milliseconds) is used when setting up the
SSH connection and when waiting for the hello message from
@@ -947,25 +791,10 @@ SessionId, infinity).
- send(Client, SimpleXml) -> Result
- Equivalent to send(Client, SimpleXml, infinity).
-
- Equivalent to
- ct_netconfc:send(Client, SimpleXml,
- infinity).
-
-
-
-
- send(Client, SimpleXml, Timeout) -> Result
+
+
Sends an XML document to the server.
-
- 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
@@ -975,25 +804,10 @@ SessionId, infinity).
- send_rpc(Client, SimpleXml) -> Result
- Equivalent to send_rpc(Client, SimpleXml, infinity).
-
- Equivalent to
- ct_netconfc:send_rpc(Client,
- SimpleXml, infinity).
-
-
-
-
- send_rpc(Client, SimpleXml, Timeout) -> Result
+
+
Sends a NETCONF rpc request to the server.
-
- 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
@@ -1006,30 +820,42 @@ SessionId, infinity).
- unlock(Client, Target) -> Result
- Equivalent to unlock(Client, Target, infinity).
-
- Equivalent to
- ct_netconfc:unlock(Client, Target,
- infinity).
+
+
+
+
+ Opens a NETCONF session as a channel on the given SSH
+ connection, and exchanges hello messages with the
+ server.
+
+
+
+ Opens a NETCONF session as a channel on the given SSH
+ connection, and exchanges hello messages with the server.
+
+ The opaque handle()
+ 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().
+
- unlock(Client, Target, Timeout) -> Result
+
+
Unlocks the configuration target.
-
- 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
- ct_netconfc:lock/2 or
- ct_netconfc:lock/3, this
+ lock/2,3, this
operation releases the associated lock. To access another target
than running, the server must support :candidate
and/or :startup.
diff --git a/lib/common_test/doc/src/specs.xml b/lib/common_test/doc/src/specs.xml
new file mode 100644
index 0000000000..7e40e8351d
--- /dev/null
+++ b/lib/common_test/doc/src/specs.xml
@@ -0,0 +1,5 @@
+
+
+
+
+
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index 43abb91819..662732d475 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -89,6 +89,36 @@
-export([get_target_name/1]).
-export([parse_table/1, listenv/1]).
+%%----------------------------------------------------------------------
+%% Exported types
+%%----------------------------------------------------------------------
+%% For ct_gen_conn
+-export_type([config_key/0,
+ target_name/0,
+ key_or_name/0]).
+
+%% For cth_conn_log
+-export_type([conn_log_options/0,
+ conn_log_type/0,
+ conn_log_mod/0]).
+
+%%------------------------------------------------------------------
+%% Type declarations
+%% ------------------------------------------------------------------
+-type config_key() :: atom(). % Config key which exists in a config file
+-type target_name() :: atom().% Name associated to a config_key() though 'require'
+-type key_or_name() :: config_key() | target_name().
+
+%% Types used when logging connections with the 'cth_conn_log' hook
+-type conn_log_options() :: [conn_log_option()].
+-type conn_log_option() :: {log_type,conn_log_type()} |
+ {hosts,[key_or_name()]}.
+-type conn_log_type() :: raw | pretty | html | silent.
+-type conn_log_mod() :: ct_netconfc | ct_telnet.
+%%----------------------------------------------------------------------
+
+
+
%%%-----------------------------------------------------------------
%%% @spec install(Opts) -> ok | {error,Reason}
%%% Opts = [Opt]
diff --git a/lib/common_test/src/ct_gen_conn.erl b/lib/common_test/src/ct_gen_conn.erl
index 5046ffade0..88b05cf955 100644
--- a/lib/common_test/src/ct_gen_conn.erl
+++ b/lib/common_test/src/ct_gen_conn.erl
@@ -29,13 +29,6 @@
-export([call/2, call/3, return/2, do_within_time/2]).
-export([log/3, start_log/1, cont_log/2, cont_log_no_timestamp/2, end_log/0]).
-%%----------------------------------------------------------------------
-%% Exported types
-%%----------------------------------------------------------------------
--export_type([server_id/0,
- target_name/0,
- key_or_name/0]).
-
-ifdef(debug).
-define(dbg,true).
-else.
@@ -54,18 +47,6 @@
cb_state,
ct_util_server}).
-%%------------------------------------------------------------------
-%% Type declarations
-%%------------------------------------------------------------------
--type server_id() :: atom().
-%% A `ServerId' which exists in a configuration file.
--type target_name() :: atom().
-%% A name which is associated to a `server_id()' via a
-%% `require' statement or a call to {@link ct:require/2} in the
-%% test suite.
--type key_or_name() :: server_id() | target_name().
-
-
%%%-----------------------------------------------------------------
%%% @spec start(Address,InitData,CallbackMod,Opts) ->
%%% {ok,Handle} | {error,Reason}
diff --git a/lib/common_test/src/ct_netconfc.erl b/lib/common_test/src/ct_netconfc.erl
index 28423c2200..b77570c121 100644
--- a/lib/common_test/src/ct_netconfc.erl
+++ b/lib/common_test/src/ct_netconfc.erl
@@ -23,24 +23,15 @@
%% Description:
%% This file contains the Netconf client interface
%%
-%% @author Support
+%% Netconf servers can be configured by adding the following statement
+%% to a configuration file:
%%
-%% @doc Netconf client module.
+%% {server_id(),options()}.
%%
-%% The Netconf client is compliant with RFC4741 and RFC4742.
+%% The server_id() or an associated ct:target_name() shall then be
+%% used in calls to open/2 connect/2.
%%
-%% For each server to test against, the following entry can be
-%% added to a configuration file:
-%%
-%% `{server_id(),options()}.'
-%%
-%% The `server_id()' or an associated `target_name()' (see
-%% {@link ct}) shall then be used in calls to {@link open/2}.
-%%
-%% If no configuration exists for a server, a session can still be
-%% opened by calling {@link open/2} with all necessary options given
-%% in the call. The first argument to {@link open/2} can then be any
-%% atom.
+%% If no configuration exists for a server, use open/1 and connect/1.
%%
%% == Logging ==
%%
@@ -49,102 +40,15 @@
%% `ct_conn_log_h'. To use this error handler, add the `cth_conn_log'
%% hook in your test suite, e.g.
%%
-%% ```
%% suite() ->
-%% [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
-%%'''
-%%
-%% The `conn_mod()' is the name of the common_test module implementing
-%% the connection protocol, e.g. `ct_netconfc'.
-%%
-%% The hook option `log_type' specifies the type of logging:
-%%
-%%
-%% - `raw'
-%% - The sent and received netconf data is logged to a separate
-%% text file as is without any formatting. A link to the file is
-%% added to the test case HTML log.
-%%
-%% - `pretty'
-%% - The sent and received netconf data is logged to a separate
-%% text file with XML data nicely indented. A link to the file is
-%% added to the test case HTML log.
-%%
-%% - `html (default)'
-%% - The sent and received netconf traffic is pretty printed
-%% directly in the test case HTML log.
-%%
-%% - `silent'
-%% - Netconf traffic is not logged.
-%%
-%%
-%% By default, all netconf traffic is logged in one single log
-%% file. However, it is possible to have different connections logged
-%% in separate files. To do this, use the hook option `hosts' and
-%% list the names of the servers/connections that will be used in the
-%% suite. Note that the connections must be named for this to work,
-%% i.e. they must be opened with {@link open/2}.
-%%
-%% The `hosts' option has no effect if `log_type' is set to `html' or
-%% `silent'.
-%%
-%% The hook options can also be specified in a configuration file with
-%% the configuration variable `ct_conn_log':
-%%
-%% ```
-%% {ct_conn_log,[{conn_mod(),hook_options()}]}.
-%% '''
+%% [{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(),ct:conn_log_options()}]}]}].
%%
%% For example:
%%
-%% ```
-%% {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
-%% {hosts,[key_or_name()]}]}]}
-%% '''
-%%
-%% Note that hook options specified in a configuration file
-%% will overwrite the hardcoded hook options in the test suite.
-%%
-%% === Logging example 1 ===
-%%
-%% The following `ct_hooks' statement will cause pretty printing of
-%% netconf traffic to separate logs for the connections named
-%% `nc_server1' and `nc_server2'. Any other connections will be logged
-%% to default netconf log.
-%%
-%% ```
%% suite() ->
-%% [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
-%% {hosts,[nc_server1,nc_server2]}]}
-%% ]}]}].
-%%'''
-%%
-%% Connections must be opened like this:
-%%
-%% ```
-%% open(nc_server1,[...]),
-%% open(nc_server2,[...]).
-%% '''
-%%
-%% === Logging example 2 ===
-%%
-%% The following configuration file will cause raw logging of all
-%% netconf traffic into one single text file.
-%%
-%% ```
-%% {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.
-%% '''
-%%
-%% The `ct_hooks' statement must look like this:
-%%
-%% ```
-%% suite() ->
-%% [{ct_hooks, [{cth_conn_log, []}]}].
-%% '''
-%%
-%% The same `ct_hooks' statement without the configuration file would
-%% cause HTML logging of all netconf connections into the test case
-%% HTML log.
+%% [{ct_hooks,
+%% [{cth_conn_log,[{ct_netconfc,[{log_type,pretty},
+%% {hosts,[my_configured_server]}]}]}
%%
%% == Notifications ==
%%
@@ -152,11 +56,9 @@
%% Notifications, which defines a mechanism for an asynchronous
%% message notification delivery service for the netconf protocol.
%%
-%% Specific functions to support this are {@link
-%% create_subscription/6} and {@link get_event_streams/3}. (The
-%% functions also exist with other arities.)
+%% Specific functions to support this are create_subscription/6
+%% get_event_streams/3. (The functions also exist with other arities.)
%%
-%% @end
%%----------------------------------------------------------------------
-module(ct_netconfc).
@@ -211,6 +113,7 @@
create_subscription/4,
create_subscription/5,
create_subscription/6,
+ get_event_streams/1,
get_event_streams/2,
get_event_streams/3,
get_capabilities/1,
@@ -301,21 +204,18 @@
%%----------------------------------------------------------------------
%% Type declarations
%%----------------------------------------------------------------------
--type client() :: handle() | ct_gen_conn:server_id() | ct_gen_conn:target_name().
+-type client() :: handle() | server_id() | ct:target_name().
-opaque handle() :: pid().
-%% An opaque reference for a connection (netconf session). See {@link
-%% ct} for more information.
-type options() :: [option()].
-%% Options used for setting up ssh connection to a netconf server.
-
-type option() :: {ssh,host()} | {port,inet:port_number()} | {user,string()} |
{password,string()} | {user_dir,string()} |
{timeout,timeout()}.
+
-type session_options() :: [session_option()].
-type session_option() :: {timeout,timeout()}.
+
-type host() :: inet:hostname() | inet:ip_address().
--type start_result() :: {ok,handle()} | {error,error_reason()}.
-type notification() :: {notification, xml_attributes(), notification_content()}.
-type notification_content() :: [event_time()|simple_xml()].
@@ -330,14 +230,13 @@
%% See XML Schema for Event Notifications found in RFC5277 for further
%% detail about the data format for the string values.
-%-type error_handler() :: module().
-type error_reason() :: term().
+-type server_id() :: atom().
+
-type simple_xml() :: {xml_tag(), xml_attributes(), xml_content()} |
{xml_tag(), xml_content()} |
xml_tag().
-%% This type is further described in the documentation for the
-%% Xmerl application.
-type xml_tag() :: atom().
-type xml_attributes() :: [{xml_attribute_tag(),xml_attribute_value()}].
-type xml_attribute_tag() :: atom().
@@ -349,45 +248,26 @@
-type xs_datetime() :: string().
%% This date and time identifyer has the same format as the XML type
%% dateTime and compliant to RFC3339. The format is
-%% ```[-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]'''
+%% "[-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]"
%%----------------------------------------------------------------------
%% External interface functions
%%----------------------------------------------------------------------
%%----------------------------------------------------------------------
+%% Open an SSH connection to a Netconf server
+%% If the server options are specified in a configuration file, use
+%% open/2.
-spec connect(Options) -> Result when
Options :: options(),
- Result :: start_result().
-%% Open an SSH connection to a Netconf server.
-%%
-%% One or more netconf sessions can then be opened as SSH channels
-%% over this connection, see session/[1,2,3]
-%% ----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
connect(Options) ->
do_connect(Options, #options{type=connection},[]).
-%%----------------------------------------------------------------------
--spec connect(KeyOrName,Options) -> Result when
- KeyOrName :: ct_gen_conn:key_or_name(),
- Options :: options(),
- Result :: start_result().
-%% Open an SSH connection to a named Netconf server.
-%%
-%% If `KeyOrName' is a configured `server_id()' or a
-%% `target_name()' associated with such an ID, then the options
-%% for this server will be fetched from the configuration file.
-%%
-%% The `ExtraOptions' argument will be added to the options found in
-%% the configuration file. If the same options are given, the values
-%% from the configuration file will overwrite `ExtraOptions'.
-%%
-%% If the server is not specified in a configuration file, use {@link
-%% connect/1} instead.
-%%
-%% One or more netconf sessions can then be opened as SSH channels over
-%% this connection, see session/[1,2,3]
-%% ----------------------------------------------------------------------
+-spec connect(KeyOrName,ExtraOptions) -> Result when
+ KeyOrName :: ct:key_or_name(),
+ ExtraOptions :: options(),
+ Result :: {ok,handle()} | {error,error_reason()}.
connect(KeyOrName, ExtraOptions) ->
SortedExtra = lists:keysort(1,ExtraOptions),
SortedConfig = lists:keysort(1,ct:get_config(KeyOrName,[])),
@@ -406,10 +286,9 @@ do_connect(OptList,InitOptRec,NameOpt) ->
end.
%%----------------------------------------------------------------------
+%% Close the given SSH connection.
-spec disconnect(Conn) -> ok | {error,error_reason()} when
Conn :: handle().
-%% Close the given SSH connection.
-%%----------------------------------------------------------------------
disconnect(Conn) ->
case call(Conn,get_ssh_connection) of
{ok,_} ->
@@ -419,42 +298,32 @@ disconnect(Conn) ->
end.
%%----------------------------------------------------------------------
--spec session(Conn) -> Result when
- Conn :: handle(),
- Result :: start_result().
%% Open a netconf session as a channel on the given SSH connection,
%% and exchange `hello' messages.
-%%----------------------------------------------------------------------
+-spec session(Conn) -> Result when
+ Conn :: handle(),
+ Result :: {ok,handle()} | {error,error_reason()}.
session(Conn) ->
do_session(Conn,[],#options{type=channel},[]).
-%%----------------------------------------------------------------------
-spec session(Conn,Options) -> Result when
Conn :: handle(),
Options :: session_options(),
- Result :: start_result();
+ Result :: {ok,handle()} | {error,error_reason()};
(KeyOrName,Conn) -> Result when
- KeyOrName :: ct_gen_conn:key_or_name(),
+ KeyOrName :: ct:key_or_name(),
Conn :: handle(),
- Result :: start_result().
-%% Open a netconf session as a channel on the given SSH connection,
-%% and exchange `hello' messages.
-%%----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
session(Conn,Options) when is_list(Options) ->
do_session(Conn,Options,#options{type=channel},[]);
session(KeyOrName,Conn) ->
do_session(Conn,[],#options{name=KeyOrName,type=channel},[{name,KeyOrName}]).
-
-%%----------------------------------------------------------------------
-spec session(KeyOrName,Conn,Options) -> Result when
Conn :: handle(),
Options :: session_options(),
- KeyOrName :: ct_gen_conn:key_or_name(),
- Result :: start_result().
-%% Open a netconf session as a channel on the given SSH connection,
-%% and exchange `hello' messages.
-%%----------------------------------------------------------------------
+ KeyOrName :: ct:key_or_name(),
+ Result :: {ok,handle()} | {error,error_reason()}.
session(KeyOrName,Conn,ExtraOptions) ->
SortedExtra = lists:keysort(1,ExtraOptions),
SortedConfig = lists:keysort(1,ct:get_config(KeyOrName,[])),
@@ -490,62 +359,19 @@ do_session(Conn,OptList,InitOptRec,NameOpt) ->
end.
%%----------------------------------------------------------------------
+%% Open a netconf session and exchange 'hello' messages.
+%% If the server options are specified in a configuration file, use
+%% open/2.
-spec open(Options) -> Result when
Options :: options(),
- Result :: start_result().
-%% @doc Open a netconf session and exchange `hello' messages.
-%%
-%% If the server options are specified in a configuration file, or if
-%% a named client is needed for logging purposes (see {@section
-%% Logging}) use {@link open/2} instead.
-%%
-%% The opaque `handler()' reference which is returned from this
-%% function is required as client identifier when calling any other
-%% function in this module.
-%%
-%% The `timeout' option (milli seconds) is used when setting up
-%% the ssh connection and when waiting for the hello message from the
-%% server. It is not used for any other purposes during the lifetime
-%% of the connection.
-%%
-%% @end
-%%----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
open(Options) ->
open(Options,#options{type=connection_and_channel},[],true).
-%%----------------------------------------------------------------------
-spec open(KeyOrName, ExtraOptions) -> Result when
- KeyOrName :: ct_gen_conn:key_or_name(),
+ KeyOrName :: ct:key_or_name(),
ExtraOptions :: options(),
- Result :: start_result().
-%% @doc Open a named netconf session and exchange `hello' messages.
-%%
-%% If `KeyOrName' is a configured `server_id()' or a
-%% `target_name()' associated with such an ID, then the options
-%% for this server will be fetched from the configuration file.
-%
-%% The `ExtraOptions' argument will be added to the options found in
-%% the configuration file. If the same options are given, the values
-%% from the configuration file will overwrite `ExtraOptions'.
-%%
-%% If the server is not specified in a configuration file, use {@link
-%% open/1} instead.
-%%
-%% The opaque `handle()' reference which is returned from this
-%% function can be used as client identifier when calling any other
-%% function in this module. However, if `KeyOrName' is a
-%% `target_name()', i.e. if the server is named via a call to
-%% `ct:require/2' or a `require' statement in the test
-%% suite, then this name may be used instead of the `handle()'.
-%%
-%% The `timeout' option (milli seconds) is used when setting up
-%% the ssh connection and when waiting for the hello message from the
-%% server. It is not used for any other purposes during the lifetime
-%% of the connection.
-%%
-%% @see ct:require/2
-%% @end
-%%----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
open(KeyOrName, ExtraOpts) ->
open(KeyOrName, ExtraOpts, true).
@@ -579,296 +405,206 @@ open(OptList,InitOptRec,NameOpt,Hello) ->
%%----------------------------------------------------------------------
+%% As open/1,2, except no 'hello' message is sent.
-spec only_open(Options) -> Result when
Options :: options(),
- Result :: start_result().
-%% @doc Open a netconf session, but don't send `hello'.
-%%
-%% As {@link open/1} but does not send a `hello' message.
-%%
-%% @end
-%%----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
only_open(Options) ->
open(Options,#options{type=connection_and_channel},[],false).
-%%----------------------------------------------------------------------
-spec only_open(KeyOrName,ExtraOptions) -> Result when
- KeyOrName :: ct_gen_conn:key_or_name(),
+ KeyOrName :: ct:key_or_name(),
ExtraOptions :: options(),
- Result :: start_result().
-%% @doc Open a name netconf session, but don't send `hello'.
-%%
-%% As {@link open/2} but does not send a `hello' message.
-%%
-%% @end
-%%----------------------------------------------------------------------
+ Result :: {ok,handle()} | {error,error_reason()}.
only_open(KeyOrName, ExtraOpts) ->
open(KeyOrName, ExtraOpts, false).
%%----------------------------------------------------------------------
-%% @spec hello(Client) -> Result
-%% @equiv hello(Client, [], infinity)
+%% Send a 'hello' message.
+-spec hello(Client) -> Result when
+ Client :: handle(),
+ Result :: ok | {error,error_reason()}.
hello(Client) ->
hello(Client,[],?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec hello(Client,Timeout) -> Result when
Client :: handle(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @spec hello(Client, Timeout) -> Result
-%% @equiv hello(Client, [], Timeout)
hello(Client,Timeout) ->
hello(Client,[],Timeout).
-%%----------------------------------------------------------------------
-spec hello(Client,Options,Timeout) -> Result when
Client :: handle(),
Options :: [{capability, [string()]}],
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Exchange `hello' messages with the server.
-%%
-%% Adds optional capabilities and sends a `hello' message to the
-%% server and waits for the return.
-%% @end
-%%----------------------------------------------------------------------
hello(Client,Options,Timeout) ->
call(Client, {hello, Options, Timeout}).
%%----------------------------------------------------------------------
-%% @spec get_session_id(Client) -> Result
-%% @equiv get_session_id(Client, infinity)
+%% Get the session id for the session specified by Client.
+-spec get_session_id(Client) -> Result when
+ Client :: client(),
+ Result :: pos_integer() | {error,error_reason()}.
get_session_id(Client) ->
get_session_id(Client, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec get_session_id(Client, Timeout) -> Result when
Client :: client(),
Timeout :: timeout(),
Result :: pos_integer() | {error,error_reason()}.
-%% @doc Returns the session id associated with the given client.
-%%
-%% @end
-%%----------------------------------------------------------------------
get_session_id(Client, Timeout) ->
call(Client, get_session_id, Timeout).
%%----------------------------------------------------------------------
-%% @spec get_capabilities(Client) -> Result
-%% @equiv get_capabilities(Client, infinity)
+%% Get the server side capabilities.
+-spec get_capabilities(Client) -> Result when
+ Client :: client(),
+ Result :: [string()] | {error,error_reason()}.
get_capabilities(Client) ->
get_capabilities(Client, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec get_capabilities(Client, Timeout) -> Result when
Client :: client(),
Timeout :: timeout(),
Result :: [string()] | {error,error_reason()}.
-%% @doc Returns the server side capabilities
-%%
-%% The following capability identifiers, defined in RFC 4741, can be returned:
-%%
-%%
-%% - `"urn:ietf:params:netconf:base:1.0"'
-%% - `"urn:ietf:params:netconf:capability:writable-running:1.0"'
-%% - `"urn:ietf:params:netconf:capability:candidate:1.0"'
-%% - `"urn:ietf:params:netconf:capability:confirmed-commit:1.0"'
-%% - `"urn:ietf:params:netconf:capability:rollback-on-error:1.0"'
-%% - `"urn:ietf:params:netconf:capability:startup:1.0"'
-%% - `"urn:ietf:params:netconf:capability:url:1.0"'
-%% - `"urn:ietf:params:netconf:capability:xpath:1.0"'
-%%
-%%
-%% Note, additional identifiers may exist, e.g. server side namespace.
-%%
-%% @end
-%%----------------------------------------------------------------------
get_capabilities(Client, Timeout) ->
call(Client, get_capabilities, Timeout).
%%----------------------------------------------------------------------
-%% @spec send(Client, SimpleXml) -> Result
-%% @equiv send(Client, SimpleXml, infinity)
+%% Send an XML document to the server.
+-spec send(Client, SimpleXml) -> Result when
+ Client :: client(),
+ SimpleXml :: simple_xml(),
+ Result :: simple_xml() | {error,error_reason()}.
send(Client, SimpleXml) ->
send(Client, SimpleXml, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec send(Client, SimpleXml, Timeout) -> Result when
Client :: client(),
SimpleXml :: simple_xml(),
Timeout :: timeout(),
Result :: simple_xml() | {error,error_reason()}.
-%% @doc Send an XML document to the server.
-%%
-%% The given XML document is sent as is to the server. This function
-%% can be used for sending XML documents that can not be expressed by
-%% other interface functions in this module.
send(Client, SimpleXml, Timeout) ->
call(Client,{send, Timeout, SimpleXml}).
%%----------------------------------------------------------------------
-%% @spec send_rpc(Client, SimpleXml) -> Result
-%% @equiv send_rpc(Client, SimpleXml, infinity)
+%% Wrap the given XML document in a valid netconf 'rpc' request and
+%% send to the server.
+-spec send_rpc(Client, SimpleXml) -> Result when
+ Client :: client(),
+ SimpleXml :: simple_xml(),
+ Result :: [simple_xml()] | {error,error_reason()}.
send_rpc(Client, SimpleXml) ->
send_rpc(Client, SimpleXml, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec send_rpc(Client, SimpleXml, Timeout) -> Result when
Client :: client(),
SimpleXml :: simple_xml(),
Timeout :: timeout(),
Result :: [simple_xml()] | {error,error_reason()}.
-%% @doc Send a Netconf rpc
request to the server.
-%%
-%% The given XML document is wrapped in a valid Netconf
-%% rpc
request and sent to the server. The
-%% message-id
and namespace attributes are added to the
-%% rpc
element.
-%%
-%% This function can be used for sending rpc
requests
-%% that can not be expressed by other interface functions in this
-%% module.
send_rpc(Client, SimpleXml, Timeout) ->
call(Client,{send_rpc, SimpleXml, Timeout}).
%%----------------------------------------------------------------------
-%% @spec lock(Client, Target) -> Result
-%% @equiv lock(Client, Target, infinity)
+%% Send a 'lock' request.
+-spec lock(Client, Target) -> Result when
+ Client :: client(),
+ Target :: netconf_db(),
+ Result :: ok | {error,error_reason()}.
lock(Client, Target) ->
lock(Client, Target,?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec lock(Client, Target, Timeout) -> Result when
Client :: client(),
Target :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Unlock configuration target.
-%%
-%% Which target parameters that can be used depends on if
-%% `:candidate' and/or `:startup' are supported by the
-%% server. If successfull, the configuration system of the device is
-%% not available to other clients (Netconf, CORBA, SNMP etc). Locks
-%% are intended to be short-lived.
-%%
-%% The operations {@link kill_session/2} or {@link kill_session/3} can
-%% be used to force the release of a lock owned by another Netconf
-%% session. How this is achieved by the server side is implementation
-%% specific.
-%%
-%% @end
-%%----------------------------------------------------------------------
lock(Client, Target, Timeout) ->
call(Client,{send_rpc_op,lock,[Target],Timeout}).
%%----------------------------------------------------------------------
-%% @spec unlock(Client, Target) -> Result
-%% @equiv unlock(Client, Target, infinity)
+%% Send a 'unlock' request.
+-spec unlock(Client, Target) -> Result when
+ Client :: client(),
+ Target :: netconf_db(),
+ Result :: ok | {error,error_reason()}.
unlock(Client, Target) ->
unlock(Client, Target,?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec unlock(Client, Target, Timeout) -> Result when
Client :: client(),
Target :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Unlock configuration target.
-%%
-%% If the client earlier has aquired a lock, via {@link lock/2} or
-%% {@link lock/3}, this operation release the associated lock. To be
-%% able to access another target than `running', the server must
-%% support `:candidate' and/or `:startup'.
-%%
-%% @end
-%%----------------------------------------------------------------------
unlock(Client, Target, Timeout) ->
call(Client, {send_rpc_op, unlock, [Target], Timeout}).
%%----------------------------------------------------------------------
-%% @spec get(Client, Filter) -> Result
-%% @equiv get(Client, Filter, infinity)
+%% Send a 'get' request.
+-spec get(Client, Filter) -> Result when
+ Client :: client(),
+ Filter :: simple_xml() | xpath(),
+ Result :: {ok,[simple_xml()]} | {error,error_reason()}.
get(Client, Filter) ->
get(Client, Filter, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec get(Client, Filter, Timeout) -> Result when
Client :: client(),
Filter :: simple_xml() | xpath(),
Timeout :: timeout(),
Result :: {ok,[simple_xml()]} | {error,error_reason()}.
-%% @doc Get data.
-%%
-%% This operation returns both configuration and state data from the
-%% server.
-%%
-%% Filter type `xpath' can only be used if the server supports
-%% `:xpath'.
-%%
-%% @end
-%%----------------------------------------------------------------------
get(Client, Filter, Timeout) ->
call(Client,{send_rpc_op, get, [Filter], Timeout}).
%%----------------------------------------------------------------------
-%% @spec get_config(Client, Source, Filter) -> Result
-%% @equiv get_config(Client, Source, Filter, infinity)
+%% Send a 'get-config' request.
+-spec get_config(Client, Source, Filter) -> Result when
+ Client :: client(),
+ Source :: netconf_db(),
+ Filter :: simple_xml() | xpath(),
+ Result :: {ok,[simple_xml()]} | {error,error_reason()}.
get_config(Client, Source, Filter) ->
get_config(Client, Source, Filter, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-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()}.
-%% @doc Get configuration data.
-%%
-%% To be able to access another source than `running', the server
-%% must advertise `:candidate' and/or `:startup'.
-%%
-%% Filter type `xpath' can only be used if the server supports
-%% `:xpath'.
-%%
-%%
-%% @end
-%%----------------------------------------------------------------------
get_config(Client, Source, Filter, Timeout) ->
call(Client, {send_rpc_op, get_config, [Source, Filter], Timeout}).
%%----------------------------------------------------------------------
-%% @spec edit_config(Client, Target, Config) -> Result
-%% @equiv edit_config(Client, Target, Config, [], infinity)
+%% Send a 'edit-config' request.
+-spec edit_config(Client, Target, Config) -> Result when
+ Client :: client(),
+ Target :: netconf_db(),
+ Config :: simple_xml(),
+ Result :: ok | {error,error_reason()}.
edit_config(Client, Target, Config) ->
edit_config(Client, Target, Config, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
--spec edit_config(Client, Target, Config, OptParamsOrTimeout) -> Result when
+-spec edit_config(Client, Target, Config, OptParams) -> Result when
Client :: client(),
Target :: netconf_db(),
Config :: simple_xml(),
- OptParamsOrTimeout :: [simple_xml()] | timeout(),
+ 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()}.
-%% @doc
-%%
-%% If `OptParamsOrTimeout' is a timeout value, then this is
-%% equivalent to {@link edit_config/5. edit_config(Client, Target,
-%% Config, [], Timeout)}.
-%%
-%% If `OptParamsOrTimeout' is a list of simple XML, then this is
-%% equivalent to {@link edit_config/5. edit_config(Client, Target,
-%% Config, OptParams, infinity)}.
-%%
-%% @end
edit_config(Client, Target, Config, Timeout) when ?is_timeout(Timeout) ->
edit_config(Client, Target, Config, [], Timeout);
edit_config(Client, Target, Config, OptParams) when is_list(OptParams) ->
edit_config(Client, Target, Config, OptParams, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec edit_config(Client, Target, Config, OptParams, Timeout) -> Result when
Client :: client(),
Target :: netconf_db(),
@@ -876,99 +612,79 @@ edit_config(Client, Target, Config, OptParams) when is_list(OptParams) ->
OptParams :: [simple_xml()],
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Edit configuration data.
-%%
-%% Per default only the running target is available, unless the server
-%% include `:candidate' or `:startup' in its list of
-%% capabilities.
-%%
-%% `OptParams' can be used for specifying optional parameters
-%% (`default-operation', `test-option' or `error-option') that will 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"]}]
-%%'''
-%%
-%% @end
-%%----------------------------------------------------------------------
edit_config(Client, Target, Config, OptParams, Timeout) ->
call(Client, {send_rpc_op, edit_config, [Target,Config,OptParams], Timeout}).
%%----------------------------------------------------------------------
-%% @spec delete_config(Client, Target) -> Result
-%% @equiv delete_config(Client, Target, infinity)
+%% Send a 'delete-config' request.
+-spec delete_config(Client, Target) -> Result when
+ Client :: client(),
+ Target :: startup | candidate,
+ Result :: ok | {error,error_reason()}.
delete_config(Client, Target) ->
delete_config(Client, Target, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec delete_config(Client, Target, Timeout) -> Result when
Client :: client(),
Target :: startup | candidate,
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Delete configuration data.
-%%
-%% The running configuration cannot be deleted and `:candidate'
-%% or `:startup' must be advertised by the server.
-%%
-%% @end
-%%----------------------------------------------------------------------
delete_config(Client, Target, Timeout) when Target == startup;
Target == candidate ->
call(Client,{send_rpc_op, delete_config, [Target], Timeout}).
%%----------------------------------------------------------------------
-%% @spec copy_config(Client, Source, Target) -> Result
-%% @equiv copy_config(Client, Source, Target, infinity)
+%% Send a 'copy-config' request.
+-spec copy_config(Client, Target, Source) -> Result when
+ Client :: client(),
+ Target :: netconf_db(),
+ Source :: netconf_db(),
+ Result :: ok | {error,error_reason()}.
copy_config(Client, Source, Target) ->
copy_config(Client, Source, Target, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec copy_config(Client, Target, Source, Timeout) -> Result when
Client :: client(),
Target :: netconf_db(),
Source :: netconf_db(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Copy configuration data.
-%%
-%% Which source and target options that can be issued depends on the
-%% capabilities supported by the server. I.e. `:candidate' and/or
-%% `:startup' are required.
-%%
-%% @end
-%%----------------------------------------------------------------------
copy_config(Client, Target, Source, Timeout) ->
call(Client,{send_rpc_op, copy_config, [Target, Source], Timeout}).
%%----------------------------------------------------------------------
-%% @spec action(Client, Action) -> Result
-%% @equiv action(Client, Action, infinity)
+%% Execute an action.
+-spec action(Client, Action) -> Result when
+ Client :: client(),
+ Action :: simple_xml(),
+ Result :: ok | {ok,[simple_xml()]} | {error,error_reason()}.
action(Client,Action) ->
action(Client,Action,?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec action(Client, Action, Timeout) -> Result when
Client :: client(),
Action :: simple_xml(),
Timeout :: timeout(),
Result :: ok | {ok,[simple_xml()]} | {error,error_reason()}.
-%% @doc Execute an action. If the return type is void, ok will
-%% be returned instead of {ok,[simple_xml()]}.
-%%
-%% @end
-%%----------------------------------------------------------------------
action(Client,Action,Timeout) ->
call(Client,{send_rpc_op, action, [Action], Timeout}).
%%----------------------------------------------------------------------
+%% Send a 'create-subscription' request
+%% See RFC5277, NETCONF Event Notifications
+-spec create_subscription(Client) -> Result when
+ Client :: client(),
+ Result :: ok | {error,error_reason()}.
create_subscription(Client) ->
create_subscription(Client,?DEFAULT_STREAM,?DEFAULT_TIMEOUT).
+-spec create_subscription(Client, Stream | Filter | Timeout) -> Result when
+ Client :: client(),
+ Stream :: stream_name(),
+ Filter :: simple_xml() | [simple_xml()],
+ Timeout :: timeout(),
+ Result :: ok | {error,error_reason()}.
create_subscription(Client,Timeout)
when ?is_timeout(Timeout) ->
create_subscription(Client,?DEFAULT_STREAM,Timeout);
@@ -1024,6 +740,22 @@ create_subscription(Client,Stream,Filter,Timeout)
[Stream,Filter,undefined,undefined],
Timeout}).
+-spec create_subscription(Client, Stream, StartTime, StopTime, Timeout) ->
+ Result when
+ Client :: client(),
+ Stream :: stream_name(),
+ StartTime :: xs_datetime(),
+ StopTime :: xs_datetime(),
+ Timeout :: timeout(),
+ Result :: ok | {error,error_reason()};
+ (Client, Stream, Filter,StartTime, StopTime) ->
+ Result when
+ Client :: client(),
+ Stream :: stream_name(),
+ Filter :: simple_xml() | [simple_xml()],
+ StartTime :: xs_datetime(),
+ StopTime :: xs_datetime(),
+ Result :: ok | {error,error_reason()}.
create_subscription(Client,Stream,StartTime,StopTime,Timeout)
when ?is_string(Stream) andalso
?is_string(StartTime) andalso
@@ -1039,7 +771,6 @@ create_subscription(Client,Stream,Filter,StartTime,StopTime)
?is_string(StopTime) ->
create_subscription(Client,Stream,Filter,StartTime,StopTime,?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec create_subscription(Client, Stream, Filter,StartTime, StopTime, Timeout) ->
Result when
Client :: client(),
@@ -1049,168 +780,75 @@ create_subscription(Client,Stream,Filter,StartTime,StopTime)
StopTime :: xs_datetime(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Create a subscription for event notifications.
-%%
-%% This function sets up a subscription for netconf event
-%% notifications of the given stream type, matching the given
-%% filter. The calling process will receive notifications as messages
-%% of type `notification()'.
-%%
-%%
-%% - Stream:
-%% - An optional parameter that indicates which stream of events
-%% is of interest. If not present, events in the default NETCONF
-%% stream will be sent.
-%%
-%% - Filter:
-%% - An optional parameter that indicates which subset of all
-%% possible events is of interest. The format of this parameter is
-%% the same as that of the filter parameter in the NETCONF protocol
-%% operations. If not present, all events not precluded by other
-%% parameters will be sent.
-%%
-%% - StartTime:
-%% - An optional parameter used to trigger the replay feature and
-%% indicate that the replay should start at the time specified. If
-%% `StartTime' is not present, this is not a replay subscription.
-%% It is not valid to specify start times that are later than the
-%% current time. If the `StartTime' specified is earlier than the
-%% log can support, the replay will begin with the earliest
-%% available notification. This parameter is of type dateTime and
-%% compliant to [RFC3339]. Implementations must support time
-%% zones.
-%%
-%% - StopTime:
-%% - An optional parameter used with the optional replay feature
-%% to indicate the newest notifications of interest. If `StopTime'
-%% is not present, the notifications will continue until the
-%% subscription is terminated. Must be used with and be later than
-%% `StartTime'. Values of `StopTime' in the future are valid. This
-%% parameter is of type dateTime and compliant to [RFC3339].
-%% Implementations must support time zones.
-%%
-%%
-%% See RFC5277 for further details about the event notification
-%% mechanism.
-%%
-%% @end
-%%----------------------------------------------------------------------
create_subscription(Client,Stream,Filter,StartTime,StopTime,Timeout) ->
call(Client,{send_rpc_op,{create_subscription, self()},
[Stream,Filter,StartTime,StopTime],
Timeout}).
%%----------------------------------------------------------------------
-%% @spec get_event_streams(Client, Timeout) -> Result
-%% @equiv get_event_streams(Client, [], Timeout)
+%% Send a request to get the given event streams
+%% See RFC5277, NETCONF Event Notifications
+-spec get_event_streams(Client)
+ -> Result when
+ Client :: client(),
+ Result :: {ok,streams()} | {error,error_reason()}.
+get_event_streams(Client) ->
+ get_event_streams(Client,[],?DEFAULT_TIMEOUT).
+
+-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()}.
get_event_streams(Client,Timeout) when is_integer(Timeout); Timeout==infinity ->
get_event_streams(Client,[],Timeout);
-
-%%----------------------------------------------------------------------
-%% @spec get_event_streams(Client, Streams) -> Result
-%% @equiv get_event_streams(Client, Streams, infinity)
get_event_streams(Client,Streams) when is_list(Streams) ->
get_event_streams(Client,Streams,?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec get_event_streams(Client, Streams, Timeout)
-> Result when
Client :: client(),
Streams :: [stream_name()],
Timeout :: timeout(),
Result :: {ok,streams()} | {error,error_reason()}.
-%% @doc Send a request to get the given event streams.
-%%
-%% `Streams' is a list of stream names. The following filter will
-%% be sent to the netconf server in a `get' request:
-%%
-%% ```
-%%
-%%
-%%
-%% StreamName1
-%%
-%%
-%% StreamName2
-%%
-%% ...
-%%
-%%
-%% '''
-%%
-%% If `Streams' is an empty list, ALL streams will be requested
-%% by sending the following filter:
-%%
-%% ```
-%%
-%%
-%%
-%% '''
-%%
-%% If more complex filtering is needed, a use {@link get/2} or {@link
-%% get/3} and specify the exact filter according to XML Schema for
-%% Event Notifications found in RFC5277.
-%%
-%% @end
-%%----------------------------------------------------------------------
get_event_streams(Client,Streams,Timeout) ->
call(Client,{get_event_streams,Streams,Timeout}).
%%----------------------------------------------------------------------
-%% @spec close_session(Client) -> Result
-%% @equiv close_session(Client, infinity)
+%% Send a 'close-session' request
+-spec close_session(Client) -> Result when
+ Client :: client(),
+ Result :: ok | {error,error_reason()}.
close_session(Client) ->
close_session(Client, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec close_session(Client, Timeout) -> Result when
Client :: client(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Request graceful termination of the session associated with the client.
-%%
-%% When a netconf server receives a `close-session' request, it
-%% will gracefully close the session. The server will release any
-%% locks and resources associated with the session and gracefully
-%% close any associated connections. Any NETCONF requests received
-%% after a `close-session' request will be ignored.
-%%
-%% @end
-%%----------------------------------------------------------------------
close_session(Client, Timeout) ->
call(Client,{send_rpc_op, close_session, [], Timeout}, true).
%%----------------------------------------------------------------------
-%% @spec kill_session(Client, SessionId) -> Result
-%% @equiv kill_session(Client, SessionId, infinity)
+%% Send a 'kill-session' request
+-spec kill_session(Client, SessionId) -> Result when
+ Client :: client(),
+ SessionId :: pos_integer(),
+ Result :: ok | {error,error_reason()}.
kill_session(Client, SessionId) ->
kill_session(Client, SessionId, ?DEFAULT_TIMEOUT).
-%%----------------------------------------------------------------------
-spec kill_session(Client, SessionId, Timeout) -> Result when
Client :: client(),
SessionId :: pos_integer(),
Timeout :: timeout(),
Result :: ok | {error,error_reason()}.
-%% @doc Force termination of the session associated with the supplied
-%% session id.
-%%
-%% The server side shall abort any operations currently in process,
-%% release any locks and resources associated with the session, and
-%% close any associated connections.
-%%
-%% Only if the server is in the confirmed commit phase, the
-%% configuration will be restored to its state before entering the
-%% confirmed commit phase. Otherwise, no configuration roll back will
-%% be performed.
-%%
-%% If the given `SessionId' is equal to the current session id,
-%% an error will be returned.
-%%
-%% @end
-%% ----------------------------------------------------------------------
kill_session(Client, SessionId, Timeout) ->
call(Client,{send_rpc_op, kill_session, [SessionId], Timeout}).
@@ -1219,7 +857,6 @@ kill_session(Client, SessionId, Timeout) ->
%% Callback functions
%%----------------------------------------------------------------------
-%% @private
init(_KeyOrName,{CM,{Host,Port}},Options) ->
case ssh_channel(#connection{reference=CM,host=Host,port=Port},Options) of
{ok,Connection} ->
@@ -1245,12 +882,10 @@ init(_KeyOrName,{_Host,_Port},Options) ->
end.
-%% @private
terminate(_, #state{connection=Connection}) ->
ssh_close(Connection),
ok.
-%% @private
handle_msg({hello, Options, Timeout}, From,
#state{connection=Connection,hello_status=HelloStatus} = State) ->
case do_send(Connection, client_hello(Options)) of
@@ -1306,7 +941,6 @@ handle_msg({get_event_streams=Op,Streams,Timeout}, From, State) ->
SimpleXml = encode_rpc_operation(get,[Filter]),
do_send_rpc(Op, SimpleXml, Timeout, From, State).
-%% @private
handle_msg({ssh_cm, CM, {data, Ch, _Type, Data}}, State) ->
ssh_connection:adjust_window(CM,Ch,size(Data)),
handle_data(Data, State);
@@ -1342,7 +976,6 @@ handle_msg({Ref,timeout},#state{pending=Pending} = State) ->
%% the implementation before this patch
{R,State#state{pending=Pending1, no_end_tag_buff= <<>>, buff= <<>>}}.
-%% @private
%% Called by ct_util_server to close registered connections before terminate.
close(Client) ->
case get_handle(Client) of
@@ -1962,7 +1595,6 @@ log(#connection{reference=Ref,host=Host,port=Port,name=Name},Action,Data) ->
%% Log callback - called from the error handler process
-%% @private
format_data(How,Data) ->
%% Assuming that the data is encoded as UTF-8. If it is not, then
%% the printout might be wrong, but the format function will not
diff --git a/lib/common_test/src/cth_conn_log.erl b/lib/common_test/src/cth_conn_log.erl
index a37cc76d32..faff150ac9 100644
--- a/lib/common_test/src/cth_conn_log.erl
+++ b/lib/common_test/src/cth_conn_log.erl
@@ -57,29 +57,18 @@
pre_init_per_testcase/4,
post_end_per_testcase/5]).
-%%----------------------------------------------------------------------
-%% Exported types
-%%----------------------------------------------------------------------
--export_type([hook_options/0,
- log_type/0,
- conn_mod/0]).
-
%%----------------------------------------------------------------------
%% Type declarations
%%----------------------------------------------------------------------
--type hook_options() :: [hook_option()].
-%% Options that can be given to `cth_conn_log' in the `ct_hook' statement.
--type hook_option() :: {log_type,log_type()} |
- {hosts,[ct_gen_conn:key_or_name()]}.
--type log_type() :: raw | pretty | html | silent.
--type conn_mod() :: ct_netconfc | ct_telnet.
+-type hook_options() :: ct:conn_log_options().
+-type log_type() :: ct:conn_log_type().
+-type conn_mod() :: ct:conn_log_mod().
%%----------------------------------------------------------------------
-spec init(Id, HookOpts) -> Result when
Id :: term(),
HookOpts :: hook_options(),
- Result :: {ok,[{conn_mod(),
- {log_type(),[ct_gen_conn:key_or_name()]}}]}.
+ Result :: {ok,[{conn_mod(),{log_type(),[ct:key_or_name()]}}]}.
init(_Id, HookOpts) ->
ConfOpts = ct:get_config(ct_conn_log,[]),
{ok,merge_log_info(ConfOpts,HookOpts)}.
--
cgit v1.2.3