1ct_telnet(3)               Erlang Module Definition               ct_telnet(3)
2
3
4

NAME

6       ct_telnet  - Common Test specific layer on top of Telnet client ct_tel‐
7       net_client.erl
8

DESCRIPTION

10       Common  Test  specific  layer  on  top   of   Telnet   client   ct_tel‐
11       net_client.erl.
12
13       Use  this  module to set up Telnet connections, send commands, and per‐
14       form string matching on the result. For information about  how  to  use
15       ct_telnet  and  configure connections, specifically for UNIX hosts, see
16       the unix_telnet manual page.
17
18       Default values defined in ct_telnet:
19
20         * Connection timeout (time to wait for connection) = 10 seconds
21
22         * Command timeout (time to wait for a command to return) = 10 seconds
23
24         * Max number of reconnection attempts = 3
25
26         * Reconnection  interval  (time  to  wait  in  between   reconnection
27           attempts) = 5 seconds
28
29         * Keep  alive  (sends  NOP to the server every 8 sec if connection is
30           idle) = true
31
32         * Polling limit (max number of times  to  poll  to  get  a  remaining
33           string terminated) = 0
34
35         * Polling interval (sleep time between polls) = 1 second
36
37         * The  TCP_NODELAY  option  for the telnet socket is disabled (set to
38           false) per default
39
40       These parameters can be modified by the user with the following config‐
41       uration term:
42
43        {telnet_settings, [{connect_timeout,Millisec},
44                           {command_timeout,Millisec},
45                           {reconnection_attempts,N},
46                           {reconnection_interval,Millisec},
47                           {keep_alive,Bool},
48                           {poll_limit,N},
49                           {poll_interval,Millisec},
50                           {tcp_nodelay,Bool}]}.
51
52       Millisec = integer(), N = integer()
53
54       Enter  the telnet_settings term in a configuration file included in the
55       test and ct_telnet retrieves the information automatically.
56
57       keep_alive can be specified per connection, if necessary. For  details,
58       see unix_telnet.
59

LOGGING

61       The default logging behavior of ct_telnet is to print information about
62       performed operations, commands, and their corresponding results to  the
63       test  case HTML log. The following is not printed to the HTML log: text
64       strings sent from the Telnet server that are not explicitly received by
65       a  ct_telnet function, such as expect/3. However, ct_telnet can be con‐
66       figured  to  use  a  special  purpose  event  handler,  implemented  in
67       ct_conn_log_h,  for  logging  all  Telnet traffic. To use this handler,
68       install a Common Test hook named cth_conn_log. Example (using the  test
69       suite information function):
70
71        suite() ->
72            [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
73
74       conn_mod()  is the name of the Common Test module implementing the con‐
75       nection protocol, that is, ct_telnet.
76
77       The cth_conn_log hook performs unformatted logging of Telnet data to  a
78       separate  text  file. All Telnet communication is captured and printed,
79       including any data sent from the server. The link to this text file  is
80       located at the top of the test case HTML log.
81
82       By  default,  data  for  all Telnet connections is logged in one common
83       file (named default), which can get messy,  for  example,  if  multiple
84       Telnet  sessions are running in parallel. Therefore a separate log file
85       can be created for each connection. To configure this, use hook  option
86       hosts  and  list the names of the servers/connections to be used in the
87       suite. The connections must be named for  this  to  work  (see  ct_tel‐
88       net:open/1,2,3,4).
89
90       Hook  option  log_type can be used to change the cth_conn_log behavior.
91       The default value of this option is raw, which results in the  behavior
92       described  above. If the value is set to html, all Telnet communication
93       is printed to the test case HTML log instead.
94
95       All cth_conn_log hook options described can also be specified in a con‐
96       figuration file with configuration variable ct_conn_log.
97
98       Example:
99
100        {ct_conn_log, [{ct_telnet,[{log_type,raw},
101                                   {hosts,[key_or_name()]}]}]}
102
103   Note:
104       Hook options specified in a configuration file overwrite any hard-coded
105       hook options in the test suite.
106
107
108       Logging Example:
109
110       The following ct_hooks statement causes printing of Telnet  traffic  to
111       separate  logs for the connections server1 and server2. Traffic for any
112       other connections is logged in the default Telnet log.
113
114        suite() ->
115            [{ct_hooks,
116              [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
117
118       As previously explained, this specification can also be provided by  an
119       entry like the following in a configuration file:
120
121        {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
122
123       In  this case the ct_hooks statement in the test suite can look as fol‐
124       lows:
125
126        suite() ->
127            [{ct_hooks, [{cth_conn_log, []}]}].
128

DATA TYPES

130       connection() = handle() | {target_name(), connection_type()} | target_name()
131
132              For target_name(), see module ct.
133
134       connection_type() = telnet | ts1 | ts2
135
136       handle() = handle()
137
138              Handle for a specific Telnet connection, see module ct.
139
140       prompt_regexp() = string()
141
142              Regular expression matching all possible prompts for a  specific
143              target  type.  regexp  must  not  have any groups, that is, when
144              matching, re:run/3 (in STDLIB) must return a list with one  sin‐
145              gle element.
146

EXPORTS

148       close(Connection) -> ok | {error, Reason}
149
150              Types:
151
152                 Connection = connection()
153                 Reason = term()
154
155              Closes the Telnet connection and stops the process managing it.
156
157              A  connection can be associated with a target name and/or a han‐
158              dle. If Connection has no associated target name, it can only be
159              closed with the handle value (see ct_telnet:open/4).
160
161       cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
162
163              Equivalent to ct_telnet:cmd(Connection, Cmd, []).
164
165       cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
166
167              Types:
168
169                 Connection = connection()
170                 Cmd = string()
171                 Opts = [Opt]
172                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
173                 Data = [string()]
174                 Reason = term()
175
176              Sends a command through Telnet and waits for prompt.
177
178              By  default, this function adds "\n" to the end of the specified
179              command. If this is not  desired,  use  option  {newline,false}.
180              This  is  necessary,  for  example,  when sending Telnet command
181              sequences prefixed with character Interpret  As  Command  (IAC).
182              Option  {newline,string()}  can also be used if a different line
183              end than "\n" is required, for instance {newline,"\r\n"}, to add
184              both carriage return and newline characters.
185
186              Option  timeout  specifies  how  long  the  client must wait for
187              prompt. If the time expires, the function  returns  {error,time‐
188              out}.  For  information  about the default value for the command
189              timeout, see the list of default values in the beginning of this
190              module.
191
192       cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
193
194              Equivalent to ct_telnet:cmdf(Connection, CmdFormat, Args, []).
195
196       cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
197
198              Types:
199
200                 Connection = connection()
201                 CmdFormat = string()
202                 Args = list()
203                 Opts = [Opt]
204                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
205                 Data = [string()]
206                 Reason = term()
207
208              Sends  a  Telnet  command  and  waits  for prompt (uses a format
209              string and a list of arguments to build the command).
210
211              For details, see ct_telnet:cmd/3.
212
213       expect(Connection, Patterns) -> term()
214
215              Equivalent to ct_telnet:expect(Connections, Patterns, []).
216
217       expect(Connection, Patterns, Opts) -> {ok,  Match}  |  {ok,  MatchList,
218       HaltReason} | {error, Reason}
219
220              Types:
221
222                 Connection = connection()
223                 Patterns = Pattern | [Pattern]
224                 Pattern  =  string()  |  {Tag,  string()} | prompt | {prompt,
225                 Prompt}
226                 Prompt = string()
227                 Tag = term()
228                 Opts = [Opt]
229                 Opt = {idle_timeout, IdleTimeout}  |  {total_timeout,  Total‐
230                 Timeout}  | repeat | {repeat, N} | sequence | {halt, HaltPat‐
231                 terns} | ignore_prompt | no_prompt_check | wait_for_prompt  |
232                 {wait_for_prompt, Prompt}
233                 IdleTimeout = infinity | integer()
234                 TotalTimeout = infinity | integer()
235                 N = integer()
236                 HaltPatterns = Patterns
237                 MatchList = [Match]
238                 Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
239                 RxMatch = [string()]
240                 HaltReason = done | Match
241                 Reason = timeout | {prompt, Prompt}
242
243              Gets data from Telnet and waits for the expected pattern.
244
245              Pattern  can be a POSIX regular expression. The function returns
246              when a pattern is successfully matched (at  least  one,  in  the
247              case of multiple patterns).
248
249              RxMatch is a list of matched strings. It looks as follows [Full‐
250              Match, SubMatch1, SubMatch2, ...], where FullMatch is the string
251              matched  by  the  whole regular expression, and SubMatchN is the
252              string that matched subexpression number N.  Subexpressions  are
253              denoted with '(' ')' in the regular expression.
254
255              If  a  Tag  is  specified,  the returned Match also includes the
256              matched Tag. Otherwise, only RxMatch is returned.
257
258              Options:
259
260                idle_timeout:
261                  Indicates that the function must return if the Telnet client
262                  is  idle  (that  is,  if  no data is received) for more than
263                  IdleTimeout milliseconds. Default time-out is 10 seconds.
264
265                total_timeout:
266                  Sets a time limit for the complete expect  operation.  After
267                  TotalTimeout   milliseconds,  {error,timeout}  is  returned.
268                  Default is infinity (that is, no time limit).
269
270                ignore_prompt | no_prompt_check:
271                  >The function returns when a prompt is received, even if  no
272                  pattern has yet been matched, and {error,{prompt,Prompt}} is
273                  returned. However, this behavior can be modified with option
274                  ignore_prompt  or option no_prompt_check, which tells expect
275                  to return only when a match is found or after a time-out.
276
277                ignore_prompt:
278                  ct_telnet ignores any prompt found. This option is useful if
279                  data  sent  by  the  server  can  include a pattern matching
280                  prompt  regexp  (as  returned  by  TargedMod:get_prompt_reg‐
281                  exp/0), but is not to not cause the function to return.
282
283                no_prompt_check:
284                  ct_telnet  does not search for a prompt at all. This is use‐
285                  ful if, for example, Pattern itself matches the prompt.
286
287                wait_for_prompt:
288                  Forces ct_telnet to wait until the prompt string is received
289                  before  returning  (even  if  a  pattern  has  already  been
290                  matched).  This  is  equal  to  calling  expect(Conn,   Pat‐
291                  terns++[{prompt,Prompt}],   [sequence|Opts]).   Notice  that
292                  option idle_timeout and total_timeout can abort  the  opera‐
293                  tion of waiting for prompt.
294
295                repeat | repeat, N:
296                  The pattern(s) must be matched multiple times. If N is spec‐
297                  ified, the pattern(s) are matched N times, and the  function
298                  returns HaltReason = done. This option can be interrupted by
299                  one or more HaltPatterns. MatchList is always returned, that
300                  is, a list of Match instead of only one Match. Also HaltRea‐
301                  son is returned.
302
303                sequence:
304                  All patterns must be matched in a sequence. A match  is  not
305                  concluded until all patterns are matched. This option can be
306                  interrupted by one or more HaltPatterns. MatchList is always
307                  returned,  that  is,  a  list  of  Match instead of only one
308                  Match. Also HaltReason is returned.
309
310              Example 1:
311
312               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])
313
314              First this tries to match "ABC", and then "XYZ",  but  if  "NNN"
315              appears,  the  function  returns  {error,{nnn,["NNN"]}}. If both
316              "ABC" and "XYZ" are  matched,  the  function  returns  {ok,[Abc‐
317              Match,XyzMatch]}.
318
319              Example 2:
320
321               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])
322
323              This  tries to match "ABC" or "XYZ" twice. If "NNN" appears, the
324              function returns HaltReason = {nnn,["NNN"]}.
325
326              Options repeat and sequence can be combined to match a  sequence
327              multiple times.
328
329       get_data(Connection) -> {ok, Data} | {error, Reason}
330
331              Types:
332
333                 Connection = connection()
334                 Data = [string()]
335                 Reason = term()
336
337              Gets  all data received by the Telnet client since the last com‐
338              mand was sent. Only newline-terminated strings are returned.  If
339              the  last  received string has not yet been terminated, the con‐
340              nection can be polled automatically until  the  string  is  com‐
341              plete.
342
343              The  polling  feature  is controlled by the configuration values
344              poll_limit and poll_interval and is by  default  disabled.  This
345              means that the function immediately returns all complete strings
346              received and saves a remaining non-terminated string for a later
347              get_data call.
348
349       open(Name) -> {ok, Handle} | {error, Reason}
350
351              Equivalent to ct_telnet:open(Name, telnet).
352
353       open(Name, ConnType) -> {ok, Handle} | {error, Reason}
354
355              Types:
356
357                 Name = target_name()
358                 ConnType = connection_type()
359                 Handle = handle()
360                 Reason = term()
361
362              Opens a Telnet connection to the specified target host.
363
364       open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
365
366              Equivalent to ct_telnet:ct_telnet:open(KeyOrName, ConnType, Tar‐
367              getMod, []).
368
369       open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle}  |  {error,
370       Reason}
371
372              Types:
373
374                 KeyOrName = Key | Name
375                 Key = atom()
376                 Name = target_name()
377                 ConnType = connection_type()
378                 TargetMod = atom()
379                 Extra = term()
380                 Handle = handle()
381                 Reason = term()
382
383              Opens a Telnet connection to the specified target host.
384
385              The  target data must exist in a configuration file. The connec‐
386              tion can be associated with Name and/or the returned Handle.  To
387              allocate  a name for the target, use one of the following alter‐
388              natives:
389
390                * ct:require/2 in a test case
391
392                * A  require  statement  in  the  suite  information  function
393                  (suite/0)
394
395                * A require statement in a test case information function
396
397              If you want the connection to be associated with Handle only (if
398              you, for example, need to open multiple connections to a  host),
399              use Key, the configuration variable name, to specify the target.
400              Notice that a connection without an associated target  name  can
401              only be closed with the Handle value.
402
403              TargetMod  is  a  module  that exports the functions connect(Ip,
404              Port, KeepAlive, Extra) and get_prompt_regexp() for  the  speci‐
405              fied TargetType (for example, unix_telnet).
406
407              For target_name(), see module ct.
408
409              See also ct:require/2.
410
411       send(Connection, Cmd) -> ok | {error, Reason}
412
413              Equivalent to ct_telnet:send(Connection, Cmd, []).
414
415       send(Connection, Cmd, Opts) -> ok | {error, Reason}
416
417              Types:
418
419                 Connection = connection()
420                 Cmd = string()
421                 Opts = [Opt]
422                 Opt = {newline, boolean() | string()}
423                 Reason = term()
424
425              Sends a Telnet command and returns immediately.
426
427              By  default, this function adds "\n" to the end of the specified
428              command. If this is not desired, option {newline,false}  can  be
429              used.  This  is necessary, for example, when sending Telnet com‐
430              mand sequences prefixed  with  character  Interpret  As  Command
431              (IAC). Option {newline,string()} can also be used if a different
432              line end than "\n" is required, for  instance  {newline,"\r\n"},
433              to add both carriage return and newline characters.
434
435              The  resulting  output from the command can be read with ct_tel‐
436              net:get_data/2 or ct_telnet:expect/2,3.
437
438       sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
439
440              Equivalent to ct_telnet:sendf(Connection, CmdFormat, Args, []).
441
442       sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
443
444              Types:
445
446                 Connection = connection()
447                 CmdFormat = string()
448                 Args = list()
449                 Opts = [Opt]
450                 Opt = {newline, boolean() | string()}
451                 Reason = term()
452
453              Sends a Telnet command and returns immediately  (uses  a  format
454              string and a list of arguments to build the command).
455
456              For details, see ct_telnet:send/3.
457

SEE ALSO

459       unix_telnet
460
461
462
463Ericsson AB                    common_test 1.20                   ct_telnet(3)
Impressum