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

NAME

6       ct_ssh - SSH/SFTP client module.
7

DESCRIPTION

9       SSH/SFTP client module.
10
11       This  module  uses application SSH, which provides detailed information
12       about, for example, functions, types, and options.
13
14       Argument Server in the SFTP functions is only to be used for SFTP  ses‐
15       sions that have been started on existing SSH connections (that is, when
16       the original connection type is ssh). Whenever the connection  type  is
17       sftp, use the SSH connection reference only.
18
19       The  following  options are valid for specifying an SSH/SFTP connection
20       (that is, can be used as configuration elements):
21
22        [{ConnType, Addr},
23         {port, Port},
24         {user, UserName}
25         {password, Pwd}
26         {user_dir, String}
27         {public_key_alg, PubKeyAlg}
28         {connect_timeout, Timeout}
29         {key_cb, KeyCallbackMod}]
30
31       ConnType = ssh | sftp.
32
33       For other types, see ssh(3).
34
35       All time-out parameters in ct_ssh functions are values in milliseconds.
36

DATA TYPES

38         connection() = handle() | target_name():
39
40
41           For target_name, see module ct.
42
43         handle() = handle():
44
45
46           Handle for a specific SSH/SFTP connection, see module ct.
47
48         ssh_sftp_return() = term():
49
50
51           Return value from an ssh_sftp function.
52

EXPORTS

54       apread(SSH, Handle, Position, Length) -> Result
55
56              Types:
57
58                 SSH = connection()
59                 Result = ssh_sftp_return() | {error, Reason}
60                 Reason = term()
61
62              For information and other types, see ssh_sftp(3).
63
64       apread(SSH, Server, Handle, Position, Length) -> Result
65
66              Types:
67
68                 SSH = connection()
69                 Result = ssh_sftp_return() | {error, Reason}
70                 Reason = term()
71
72              For information and other types, see ssh_sftp(3).
73
74       apwrite(SSH, Handle, Position, Data) -> Result
75
76              Types:
77
78                 SSH = connection()
79                 Result = ssh_sftp_return() | {error, Reason}
80                 Reason = term()
81
82              For information and other types, see ssh_sftp(3).
83
84       apwrite(SSH, Server, Handle, Position, Data) -> Result
85
86              Types:
87
88                 SSH = connection()
89                 Result = ssh_sftp_return() | {error, Reason}
90                 Reason = term()
91
92              For information and other types, see ssh_sftp(3).
93
94       aread(SSH, Handle, Len) -> Result
95
96              Types:
97
98                 SSH = connection()
99                 Result = ssh_sftp_return() | {error, Reason}
100                 Reason = term()
101
102              For information and other types, see ssh_sftp(3).
103
104       aread(SSH, Server, Handle, Len) -> Result
105
106              Types:
107
108                 SSH = connection()
109                 Result = ssh_sftp_return() | {error, Reason}
110                 Reason = term()
111
112              For information and other types, see ssh_sftp(3).
113
114       awrite(SSH, Handle, Data) -> Result
115
116              Types:
117
118                 SSH = connection()
119                 Result = ssh_sftp_return() | {error, Reason}
120                 Reason = term()
121
122              For information and other types, see ssh_sftp(3).
123
124       awrite(SSH, Server, Handle, Data) -> Result
125
126              Types:
127
128                 SSH = connection()
129                 Result = ssh_sftp_return() | {error, Reason}
130                 Reason = term()
131
132              For information and other types, see ssh_sftp(3).
133
134       close(SSH, Handle) -> Result
135
136              Types:
137
138                 SSH = connection()
139                 Result = ssh_sftp_return() | {error, Reason}
140                 Reason = term()
141
142              For information and other types, see ssh_sftp(3).
143
144       close(SSH, Server, Handle) -> Result
145
146              Types:
147
148                 SSH = connection()
149                 Result = ssh_sftp_return() | {error, Reason}
150                 Reason = term()
151
152              For information and other types, see ssh_sftp(3).
153
154       connect(KeyOrName) -> {ok, Handle} | {error, Reason}
155
156              Equivalent to ct_ssh:connect(KeyOrName, host, []).
157
158       connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}
159
160              Equivalent to ct_ssh:connect(KeyOrName, ConnType, []).
161
162       connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error,  Rea‐
163       son}
164
165              Types:
166
167                 KeyOrName = Key | Name
168                 Key = atom()
169                 Name = target_name()
170                 ConnType = ssh | sftp | host
171                 ExtraOpts = ssh_connect_options()
172                 Handle = handle()
173                 Reason = term()
174
175              Opens an SSH or SFTP connection using the information associated
176              with KeyOrName.
177
178              If Name (an alias name for Key) is used to identify the  connec‐
179              tion,  this  name can be used as connection reference for subse‐
180              quent calls. Only one open connection at a time associated  with
181              Name  is  possible.  If Key is used, the returned handle must be
182              used for subsequent calls (multiple connections  can  be  opened
183              using the configuration data specified by Key).
184
185              For information on how to create a new Name, see ct:require/2.
186
187              For target_name, see module ct.
188
189              ConnType  always  overrides  the  type  specified in the address
190              tuple in the configuration data (and in  ExtraOpts).  So  it  is
191              possible to, for example, open an SFTP connection directly using
192              data originally specifying an SSH connection. Value  host  means
193              that the connection type specified by the host option (either in
194              the configuration data or in ExtraOpts) is used.
195
196              ExtraOpts (optional) are extra SSH options to be  added  to  the
197              configuration data for KeyOrName. The extra options override any
198              existing options with the same key in  the  configuration  data.
199              For details on valid SSH options, see application SSH.
200
201       del_dir(SSH, Name) -> Result
202
203              Types:
204
205                 SSH = connection()
206                 Result = ssh_sftp_return() | {error, Reason}
207                 Reason = term()
208
209              For information and other types, see ssh_sftp(3).
210
211       del_dir(SSH, Server, Name) -> Result
212
213              Types:
214
215                 SSH = connection()
216                 Result = ssh_sftp_return() | {error, Reason}
217                 Reason = term()
218
219              For information and other types, see ssh_sftp(3).
220
221       delete(SSH, Name) -> Result
222
223              Types:
224
225                 SSH = connection()
226                 Result = ssh_sftp_return() | {error, Reason}
227                 Reason = term()
228
229              For information and other types, see ssh_sftp(3).
230
231       delete(SSH, Server, Name) -> Result
232
233              Types:
234
235                 SSH = connection()
236                 Result = ssh_sftp_return() | {error, Reason}
237                 Reason = term()
238
239              For information and other types, see ssh_sftp(3).
240
241       disconnect(SSH) -> ok | {error, Reason}
242
243              Types:
244
245                 SSH = connection()
246                 Reason = term()
247
248              Closes an SSH/SFTP connection.
249
250       exec(SSH, Command) -> {ok, Data} | {error, Reason}
251
252              Equivalent to ct_ssh:exec(SSH, Command, DefaultTimeout).
253
254       exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}
255
256              Types:
257
258                 SSH = connection()
259                 Command = string()
260                 Timeout = integer()
261                 Data = list()
262                 Reason = term()
263
264              Requests  server to perform Command. A session channel is opened
265              automatically for the request. Data is received from the  server
266              as a result of the command.
267
268       exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}
269
270              Types:
271
272                 SSH = connection()
273                 ChannelId = integer()
274                 Command = string()
275                 Timeout = integer()
276                 Data = list()
277                 Reason = term()
278
279              Requests  server to perform Command. A previously opened session
280              channel is used for the  request.  Data  is  received  from  the
281              server as a result of the command.
282
283       get_file_info(SSH, Handle) -> Result
284
285              Types:
286
287                 SSH = connection()
288                 Result = ssh_sftp_return() | {error, Reason}
289                 Reason = term()
290
291              For information and other types, see ssh_sftp(3).
292
293       get_file_info(SSH, Server, Handle) -> Result
294
295              Types:
296
297                 SSH = connection()
298                 Result = ssh_sftp_return() | {error, Reason}
299                 Reason = term()
300
301              For information and other types, see ssh_sftp(3).
302
303       list_dir(SSH, Path) -> Result
304
305              Types:
306
307                 SSH = connection()
308                 Result = ssh_sftp_return() | {error, Reason}
309                 Reason = term()
310
311              For information and other types, see ssh_sftp(3).
312
313       list_dir(SSH, Server, Path) -> Result
314
315              Types:
316
317                 SSH = connection()
318                 Result = ssh_sftp_return() | {error, Reason}
319                 Reason = term()
320
321              For information and other types, see ssh_sftp(3).
322
323       make_dir(SSH, Name) -> Result
324
325              Types:
326
327                 SSH = connection()
328                 Result = ssh_sftp_return() | {error, Reason}
329                 Reason = term()
330
331              For information and other types, see ssh_sftp(3).
332
333       make_dir(SSH, Server, Name) -> Result
334
335              Types:
336
337                 SSH = connection()
338                 Result = ssh_sftp_return() | {error, Reason}
339                 Reason = term()
340
341              For information and other types, see ssh_sftp(3).
342
343       make_symlink(SSH, Name, Target) -> Result
344
345              Types:
346
347                 SSH = connection()
348                 Result = ssh_sftp_return() | {error, Reason}
349                 Reason = term()
350
351              For information and other types, see ssh_sftp(3).
352
353       make_symlink(SSH, Server, Name, Target) -> Result
354
355              Types:
356
357                 SSH = connection()
358                 Result = ssh_sftp_return() | {error, Reason}
359                 Reason = term()
360
361              For information and other types, see ssh_sftp(3).
362
363       open(SSH, File, Mode) -> Result
364
365              Types:
366
367                 SSH = connection()
368                 Result = ssh_sftp_return() | {error, Reason}
369                 Reason = term()
370
371              For information and other types, see ssh_sftp(3).
372
373       open(SSH, Server, File, Mode) -> Result
374
375              Types:
376
377                 SSH = connection()
378                 Result = ssh_sftp_return() | {error, Reason}
379                 Reason = term()
380
381              For information and other types, see ssh_sftp(3).
382
383       opendir(SSH, Path) -> Result
384
385              Types:
386
387                 SSH = connection()
388                 Result = ssh_sftp_return() | {error, Reason}
389                 Reason = term()
390
391              For information and other types, see ssh_sftp(3).
392
393       opendir(SSH, Server, Path) -> Result
394
395              Types:
396
397                 SSH = connection()
398                 Result = ssh_sftp_return() | {error, Reason}
399                 Reason = term()
400
401              For information and other types, see ssh_sftp(3).
402
403       position(SSH, Handle, Location) -> Result
404
405              Types:
406
407                 SSH = connection()
408                 Result = ssh_sftp_return() | {error, Reason}
409                 Reason = term()
410
411              For information and other types, see ssh_sftp(3).
412
413       position(SSH, Server, Handle, Location) -> Result
414
415              Types:
416
417                 SSH = connection()
418                 Result = ssh_sftp_return() | {error, Reason}
419                 Reason = term()
420
421              For information and other types, see ssh_sftp(3).
422
423       pread(SSH, Handle, Position, Length) -> Result
424
425              Types:
426
427                 SSH = connection()
428                 Result = ssh_sftp_return() | {error, Reason}
429                 Reason = term()
430
431              For information and other types, see ssh_sftp(3).
432
433       pread(SSH, Server, Handle, Position, Length) -> Result
434
435              Types:
436
437                 SSH = connection()
438                 Result = ssh_sftp_return() | {error, Reason}
439                 Reason = term()
440
441              For information and other types, see ssh_sftp(3).
442
443       pwrite(SSH, Handle, Position, Data) -> Result
444
445              Types:
446
447                 SSH = connection()
448                 Result = ssh_sftp_return() | {error, Reason}
449                 Reason = term()
450
451              For information and other types, see ssh_sftp(3).
452
453       pwrite(SSH, Server, Handle, Position, Data) -> Result
454
455              Types:
456
457                 SSH = connection()
458                 Result = ssh_sftp_return() | {error, Reason}
459                 Reason = term()
460
461              For information and other types, see ssh_sftp(3).
462
463       read(SSH, Handle, Len) -> Result
464
465              Types:
466
467                 SSH = connection()
468                 Result = ssh_sftp_return() | {error, Reason}
469                 Reason = term()
470
471              For information and other types, see ssh_sftp(3).
472
473       read(SSH, Server, Handle, Len) -> Result
474
475              Types:
476
477                 SSH = connection()
478                 Result = ssh_sftp_return() | {error, Reason}
479                 Reason = term()
480
481              For information and other types, see ssh_sftp(3).
482
483       read_file(SSH, File) -> Result
484
485              Types:
486
487                 SSH = connection()
488                 Result = ssh_sftp_return() | {error, Reason}
489                 Reason = term()
490
491              For information and other types, see ssh_sftp(3).
492
493       read_file(SSH, Server, File) -> Result
494
495              Types:
496
497                 SSH = connection()
498                 Result = ssh_sftp_return() | {error, Reason}
499                 Reason = term()
500
501              For information and other types, see ssh_sftp(3).
502
503       read_file_info(SSH, Name) -> Result
504
505              Types:
506
507                 SSH = connection()
508                 Result = ssh_sftp_return() | {error, Reason}
509                 Reason = term()
510
511              For information and other types, see ssh_sftp(3).
512
513       read_file_info(SSH, Server, Name) -> Result
514
515              Types:
516
517                 SSH = connection()
518                 Result = ssh_sftp_return() | {error, Reason}
519                 Reason = term()
520
521              For information and other types, see ssh_sftp(3).
522
523       read_link(SSH, Name) -> Result
524
525              Types:
526
527                 SSH = connection()
528                 Result = ssh_sftp_return() | {error, Reason}
529                 Reason = term()
530
531              For information and other types, see ssh_sftp(3).
532
533       read_link(SSH, Server, Name) -> Result
534
535              Types:
536
537                 SSH = connection()
538                 Result = ssh_sftp_return() | {error, Reason}
539                 Reason = term()
540
541              For information and other types, see ssh_sftp(3).
542
543       read_link_info(SSH, Name) -> Result
544
545              Types:
546
547                 SSH = connection()
548                 Result = ssh_sftp_return() | {error, Reason}
549                 Reason = term()
550
551              For information and other types, see ssh_sftp(3).
552
553       read_link_info(SSH, Server, Name) -> Result
554
555              Types:
556
557                 SSH = connection()
558                 Result = ssh_sftp_return() | {error, Reason}
559                 Reason = term()
560
561              For information and other types, see ssh_sftp(3).
562
563       receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}
564
565              Equivalent to ct_ssh:receive_response(SSH, ChannelId, close).
566
567       receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}
568
569              Equivalent   to   ct_ssh:receive_response(SSH,  ChannelId,  End,
570              DefaultTimeout).
571
572       receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data}  |  {time‐
573       out, Data} | {error, Reason}
574
575              Types:
576
577                 SSH = connection()
578                 ChannelId = integer()
579                 End = Fun | close | timeout
580                 Timeout = integer()
581                 Data = list()
582                 Reason = term()
583
584              Receives  expected  data  from  server  on the specified session
585              channel.
586
587              If End == close, data is returned to the caller when the channel
588              is  closed  by the server. If a time-out occurs before this hap‐
589              pens, the function returns {timeout,Data}  (where  Data  is  the
590              data received so far).
591
592              If  End  ==  timeout,  a  time-out  is expected and {ok,Data} is
593              returned both in the case of a time-out and when the channel  is
594              closed.
595
596              If  End is a fun, this fun is called with one argument, the data
597              value in a received ssh_cm message (see  ssh_connection(3).  The
598              fun is to return either true to end the receiving operation (and
599              have the so far collected data returned) or false  to  wait  for
600              more  data from the server. Even if a fun is supplied, the func‐
601              tion returns immediately if the server closes the channel).
602
603       rename(SSH, OldName, NewName) -> Result
604
605              Types:
606
607                 SSH = connection()
608                 Result = ssh_sftp_return() | {error, Reason}
609                 Reason = term()
610
611              For information and other types, see ssh_sftp(3).
612
613       rename(SSH, Server, OldName, NewName) -> Result
614
615              Types:
616
617                 SSH = connection()
618                 Result = ssh_sftp_return() | {error, Reason}
619                 Reason = term()
620
621              For information and other types, see ssh_sftp(3).
622
623       send(SSH, ChannelId, Data) -> ok | {error, Reason}
624
625              Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data,  DefaultTime‐
626              out).
627
628       send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}
629
630              Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data, Timeout).
631
632       send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}
633
634              Types:
635
636                 SSH = connection()
637                 ChannelId = integer()
638                 Type = integer()
639                 Data = list()
640                 Timeout = integer()
641                 Reason = term()
642
643              Sends data to server on specified session channel.
644
645       send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}
646
647              Equivalent   to  ct_ssh:send_and_receive(SSH,  ChannelId,  Data,
648              close).
649
650       send_and_receive(SSH, ChannelId, Data, End) ->  {ok,  Data}  |  {error,
651       Reason}
652
653              Equivalent  to  ct_ssh;send_and_receive(SSH, ChannelId, 0, Data,
654              End, DefaultTimeout).
655
656       send_and_receive(SSH, ChannelId, Data, End, Timeout) ->  {ok,  Data}  |
657       {error, Reason}
658
659              Equivalent  to  ct_ssh:send_and_receive(SSH, ChannelId, 0, Data,
660              End, Timeout).
661
662       send_and_receive(SSH, ChannelId, Type,  Data,  End,  Timeout)  ->  {ok,
663       Data} | {error, Reason}
664
665              Types:
666
667                 SSH = connection()
668                 ChannelId = integer()
669                 Type = integer()
670                 Data = list()
671                 End = Fun | close | timeout
672                 Timeout = integer()
673                 Reason = term()
674
675              Sends  data  to server on specified session channel and waits to
676              receive the server response.
677
678              For details on argument End, see ct_ssh:receive_response/4.
679
680       session_close(SSH, ChannelId) -> ok | {error, Reason}
681
682              Types:
683
684                 SSH = connection()
685                 ChannelId = integer()
686                 Reason = term()
687
688              Closes an SSH session channel.
689
690       session_open(SSH) -> {ok, ChannelId} | {error, Reason}
691
692              Equivalent to ct_ssh:session_open(SSH, DefaultTimeout).
693
694       session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}
695
696              Types:
697
698                 SSH = connection()
699                 Timeout = integer()
700                 ChannelId = integer()
701                 Reason = term()
702
703              Opens a channel for an SSH session.
704
705       sftp_connect(SSH) -> {ok, Server} | {error, Reason}
706
707              Types:
708
709                 SSH = connection()
710                 Server = pid()
711                 Reason = term()
712
713              Starts an SFTP session on an already  existing  SSH  connection.
714              Server identifies the new session and must be specified whenever
715              SFTP requests are to be sent.
716
717       shell(SSH, ChannelId) -> ok | {error, Reason}
718
719              Equivalent to ct_ssh:shell(SSH, ChannelId, DefaultTimeout).
720
721       shell(SSH, ChannelId, Timeout) -> ok | {error, Reason}
722
723              Types:
724
725                 SSH = connection()
726                 ChannelId = integer()
727                 Timeout = integer()
728                 Reason = term()
729
730              Requests that the  user  default  shell  (typically  defined  in
731              /etc/passwd in Unix systems) is executed at the server end.
732
733       subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}
734
735              Equivalent   to   ct_ssh:subsystem(SSH,   ChannelId,  Subsystem,
736              DefaultTimeout).
737
738       subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error,  Rea‐
739       son}
740
741              Types:
742
743                 SSH = connection()
744                 ChannelId = integer()
745                 Subsystem = string()
746                 Timeout = integer()
747                 Status = success | failure
748                 Reason = term()
749
750              Sends a request to execute a predefined subsystem.
751
752       write(SSH, Handle, Data) -> Result
753
754              Types:
755
756                 SSH = connection()
757                 Result = ssh_sftp_return() | {error, Reason}
758                 Reason = term()
759
760              For information and other types, see ssh_sftp(3).
761
762       write(SSH, Server, Handle, Data) -> Result
763
764              Types:
765
766                 SSH = connection()
767                 Result = ssh_sftp_return() | {error, Reason}
768                 Reason = term()
769
770              For information and other types, see ssh_sftp(3).
771
772       write_file(SSH, File, Iolist) -> Result
773
774              Types:
775
776                 SSH = connection()
777                 Result = ssh_sftp_return() | {error, Reason}
778                 Reason = term()
779
780              For information and other types, see ssh_sftp(3).
781
782       write_file(SSH, Server, File, Iolist) -> Result
783
784              Types:
785
786                 SSH = connection()
787                 Result = ssh_sftp_return() | {error, Reason}
788                 Reason = term()
789
790              For information and other types, see ssh_sftp(3).
791
792       write_file_info(SSH, Name, Info) -> Result
793
794              Types:
795
796                 SSH = connection()
797                 Result = ssh_sftp_return() | {error, Reason}
798                 Reason = term()
799
800              For information and other types, see ssh_sftp(3).
801
802       write_file_info(SSH, Server, Name, Info) -> Result
803
804              Types:
805
806                 SSH = connection()
807                 Result = ssh_sftp_return() | {error, Reason}
808                 Reason = term()
809
810              For information and other types, see ssh_sftp(3).
811
812
813
814Ericsson AB                   common_test 1.17.2                     ct_ssh(3)
Impressum