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              For target_name, see module ct.
41
42       handle() = handle()
43
44              Handle for a specific SSH/SFTP connection, see module ct.
45
46       ssh_sftp_return() = term()
47
48              Return value from an ssh_sftp function.
49

EXPORTS

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