1ct_ssh(3) Erlang Module Definition ct_ssh(3)
2
6 ct_ssh - SSH/SFTP client module.
7
9 SSH/SFTP client module.
10 This module uses application SSH, which provides detailed information
12 about, for example, functions, types, and options.
13 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 The following options are valid for specifying an SSH/SFTP connection
20 (that is, can be used as configuration elements):
21 [{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 ConnType = ssh | sftp.
32 For other types, see ssh(3).
34 All time-out parameters in ct_ssh functions are values in milliseconds.
36
38 connection() = handle() | target_name()
39 For target_name, see module ct.
41 handle() = handle()
43 Handle for a specific SSH/SFTP connection, see module ct.
45 ssh_sftp_return() = term()
47 Return value from an ssh_sftp function.
49
51 apread(SSH, Handle, Position, Length) -> Result
52 Types:
54 SSH = connection()
56 Result = ssh_sftp_return() | {error, Reason}
57 Reason = term()
58 For information and other types, see ssh_sftp(3).
60 apread(SSH, Server, Handle, Position, Length) -> Result
62 Types:
64 SSH = connection()
66 Result = ssh_sftp_return() | {error, Reason}
67 Reason = term()
68 For information and other types, see ssh_sftp(3).
70 apwrite(SSH, Handle, Position, Data) -> Result
72 Types:
74 SSH = connection()
76 Result = ssh_sftp_return() | {error, Reason}
77 Reason = term()
78 For information and other types, see ssh_sftp(3).
80 apwrite(SSH, Server, Handle, Position, Data) -> Result
82 Types:
84 SSH = connection()
86 Result = ssh_sftp_return() | {error, Reason}
87 Reason = term()
88 For information and other types, see ssh_sftp(3).
90 aread(SSH, Handle, Len) -> Result
92 Types:
94 SSH = connection()
96 Result = ssh_sftp_return() | {error, Reason}
97 Reason = term()
98 For information and other types, see ssh_sftp(3).
100 aread(SSH, Server, Handle, Len) -> Result
102 Types:
104 SSH = connection()
106 Result = ssh_sftp_return() | {error, Reason}
107 Reason = term()
108 For information and other types, see ssh_sftp(3).
110 awrite(SSH, Handle, Data) -> Result
112 Types:
114 SSH = connection()
116 Result = ssh_sftp_return() | {error, Reason}
117 Reason = term()
118 For information and other types, see ssh_sftp(3).
120 awrite(SSH, Server, Handle, Data) -> Result
122 Types:
124 SSH = connection()
126 Result = ssh_sftp_return() | {error, Reason}
127 Reason = term()
128 For information and other types, see ssh_sftp(3).
130 close(SSH, Handle) -> Result
132 Types:
134 SSH = connection()
136 Result = ssh_sftp_return() | {error, Reason}
137 Reason = term()
138 For information and other types, see ssh_sftp(3).
140 close(SSH, Server, Handle) -> Result
142 Types:
144 SSH = connection()
146 Result = ssh_sftp_return() | {error, Reason}
147 Reason = term()
148 For information and other types, see ssh_sftp(3).
150 connect(KeyOrName) -> {ok, Handle} | {error, Reason}
152 Equivalent to ct_ssh:connect(KeyOrName, host, []).
154 connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}
156 Equivalent to ct_ssh:connect(KeyOrName, ConnType, []).
158 connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error, Rea‐
160 son}
161 Types:
163 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 Opens an SSH or SFTP connection using the information associated
173 with KeyOrName.
174 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 For information on how to create a new Name, see ct:require/2.
183 For target_name, see module ct.
185 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 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 del_dir(SSH, Name) -> Result
199 Types:
201 SSH = connection()
203 Result = ssh_sftp_return() | {error, Reason}
204 Reason = term()
205 For information and other types, see ssh_sftp(3).
207 del_dir(SSH, Server, Name) -> Result
209 Types:
211 SSH = connection()
213 Result = ssh_sftp_return() | {error, Reason}
214 Reason = term()
215 For information and other types, see ssh_sftp(3).
217 delete(SSH, Name) -> Result
219 Types:
221 SSH = connection()
223 Result = ssh_sftp_return() | {error, Reason}
224 Reason = term()
225 For information and other types, see ssh_sftp(3).
227 delete(SSH, Server, Name) -> Result
229 Types:
231 SSH = connection()
233 Result = ssh_sftp_return() | {error, Reason}
234 Reason = term()
235 For information and other types, see ssh_sftp(3).
237 disconnect(SSH) -> ok | {error, Reason}
239 Types:
241 SSH = connection()
243 Reason = term()
244 Closes an SSH/SFTP connection.
246 exec(SSH, Command) -> {ok, Data} | {error, Reason}
248 Equivalent to ct_ssh:exec(SSH, Command, DefaultTimeout).
250 exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}
252 Types:
254 SSH = connection()
256 Command = string()
257 Timeout = integer()
258 Data = list()
259 Reason = term()
260 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 exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}
266 Types:
268 SSH = connection()
270 ChannelId = integer()
271 Command = string()
272 Timeout = integer()
273 Data = list()
274 Reason = term()
275 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 get_file_info(SSH, Handle) -> Result
281 Types:
283 SSH = connection()
285 Result = ssh_sftp_return() | {error, Reason}
286 Reason = term()
287 For information and other types, see ssh_sftp(3).
289 get_file_info(SSH, Server, Handle) -> Result
291 Types:
293 SSH = connection()
295 Result = ssh_sftp_return() | {error, Reason}
296 Reason = term()
297 For information and other types, see ssh_sftp(3).
299 list_dir(SSH, Path) -> Result
301 Types:
303 SSH = connection()
305 Result = ssh_sftp_return() | {error, Reason}
306 Reason = term()
307 For information and other types, see ssh_sftp(3).
309 list_dir(SSH, Server, Path) -> Result
311 Types:
313 SSH = connection()
315 Result = ssh_sftp_return() | {error, Reason}
316 Reason = term()
317 For information and other types, see ssh_sftp(3).
319 make_dir(SSH, Name) -> Result
321 Types:
323 SSH = connection()
325 Result = ssh_sftp_return() | {error, Reason}
326 Reason = term()
327 For information and other types, see ssh_sftp(3).
329 make_dir(SSH, Server, Name) -> Result
331 Types:
333 SSH = connection()
335 Result = ssh_sftp_return() | {error, Reason}
336 Reason = term()
337 For information and other types, see ssh_sftp(3).
339 make_symlink(SSH, Name, Target) -> Result
341 Types:
343 SSH = connection()
345 Result = ssh_sftp_return() | {error, Reason}
346 Reason = term()
347 For information and other types, see ssh_sftp(3).
349 make_symlink(SSH, Server, Name, Target) -> Result
351 Types:
353 SSH = connection()
355 Result = ssh_sftp_return() | {error, Reason}
356 Reason = term()
357 For information and other types, see ssh_sftp(3).
359 open(SSH, File, Mode) -> Result
361 Types:
363 SSH = connection()
365 Result = ssh_sftp_return() | {error, Reason}
366 Reason = term()
367 For information and other types, see ssh_sftp(3).
369 open(SSH, Server, File, Mode) -> Result
371 Types:
373 SSH = connection()
375 Result = ssh_sftp_return() | {error, Reason}
376 Reason = term()
377 For information and other types, see ssh_sftp(3).
379 opendir(SSH, Path) -> Result
381 Types:
383 SSH = connection()
385 Result = ssh_sftp_return() | {error, Reason}
386 Reason = term()
387 For information and other types, see ssh_sftp(3).
389 opendir(SSH, Server, Path) -> Result
391 Types:
393 SSH = connection()
395 Result = ssh_sftp_return() | {error, Reason}
396 Reason = term()
397 For information and other types, see ssh_sftp(3).
399 position(SSH, Handle, Location) -> Result
401 Types:
403 SSH = connection()
405 Result = ssh_sftp_return() | {error, Reason}
406 Reason = term()
407 For information and other types, see ssh_sftp(3).
409 position(SSH, Server, Handle, Location) -> Result
411 Types:
413 SSH = connection()
415 Result = ssh_sftp_return() | {error, Reason}
416 Reason = term()
417 For information and other types, see ssh_sftp(3).
419 pread(SSH, Handle, Position, Length) -> Result
421 Types:
423 SSH = connection()
425 Result = ssh_sftp_return() | {error, Reason}
426 Reason = term()
427 For information and other types, see ssh_sftp(3).
429 pread(SSH, Server, Handle, Position, Length) -> Result
431 Types:
433 SSH = connection()
435 Result = ssh_sftp_return() | {error, Reason}
436 Reason = term()
437 For information and other types, see ssh_sftp(3).
439 pwrite(SSH, Handle, Position, Data) -> Result
441 Types:
443 SSH = connection()
445 Result = ssh_sftp_return() | {error, Reason}
446 Reason = term()
447 For information and other types, see ssh_sftp(3).
449 pwrite(SSH, Server, Handle, Position, Data) -> Result
451 Types:
453 SSH = connection()
455 Result = ssh_sftp_return() | {error, Reason}
456 Reason = term()
457 For information and other types, see ssh_sftp(3).
459 read(SSH, Handle, Len) -> Result
461 Types:
463 SSH = connection()
465 Result = ssh_sftp_return() | {error, Reason}
466 Reason = term()
467 For information and other types, see ssh_sftp(3).
469 read(SSH, Server, Handle, Len) -> Result
471 Types:
473 SSH = connection()
475 Result = ssh_sftp_return() | {error, Reason}
476 Reason = term()
477 For information and other types, see ssh_sftp(3).
479 read_file(SSH, File) -> Result
481 Types:
483 SSH = connection()
485 Result = ssh_sftp_return() | {error, Reason}
486 Reason = term()
487 For information and other types, see ssh_sftp(3).
489 read_file(SSH, Server, File) -> Result
491 Types:
493 SSH = connection()
495 Result = ssh_sftp_return() | {error, Reason}
496 Reason = term()
497 For information and other types, see ssh_sftp(3).
499 read_file_info(SSH, Name) -> Result
501 Types:
503 SSH = connection()
505 Result = ssh_sftp_return() | {error, Reason}
506 Reason = term()
507 For information and other types, see ssh_sftp(3).
509 read_file_info(SSH, Server, Name) -> Result
511 Types:
513 SSH = connection()
515 Result = ssh_sftp_return() | {error, Reason}
516 Reason = term()
517 For information and other types, see ssh_sftp(3).
519 read_link(SSH, Name) -> Result
521 Types:
523 SSH = connection()
525 Result = ssh_sftp_return() | {error, Reason}
526 Reason = term()
527 For information and other types, see ssh_sftp(3).
529 read_link(SSH, Server, Name) -> Result
531 Types:
533 SSH = connection()
535 Result = ssh_sftp_return() | {error, Reason}
536 Reason = term()
537 For information and other types, see ssh_sftp(3).
539 read_link_info(SSH, Name) -> Result
541 Types:
543 SSH = connection()
545 Result = ssh_sftp_return() | {error, Reason}
546 Reason = term()
547 For information and other types, see ssh_sftp(3).
549 read_link_info(SSH, Server, Name) -> Result
551 Types:
553 SSH = connection()
555 Result = ssh_sftp_return() | {error, Reason}
556 Reason = term()
557 For information and other types, see ssh_sftp(3).
559 receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}
561 Equivalent to ct_ssh:receive_response(SSH, ChannelId, close).
563 receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}
565 Equivalent to ct_ssh:receive_response(SSH, ChannelId, End, De‐
567 faultTimeout).
568 receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data} | {time‐
570 out, Data} | {error, Reason}
571 Types:
573 SSH = connection()
575 ChannelId = integer()
576 End = Fun | close | timeout
577 Timeout = integer()
578 Data = list()
579 Reason = term()
580 Receives expected data from server on the specified session
582 channel.
583 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 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 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 rename(SSH, OldName, NewName) -> Result
601 Types:
603 SSH = connection()
605 Result = ssh_sftp_return() | {error, Reason}
606 Reason = term()
607 For information and other types, see ssh_sftp(3).
609 rename(SSH, Server, OldName, NewName) -> Result
611 Types:
613 SSH = connection()
615 Result = ssh_sftp_return() | {error, Reason}
616 Reason = term()
617 For information and other types, see ssh_sftp(3).
619 send(SSH, ChannelId, Data) -> ok | {error, Reason}
621 Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data, DefaultTime‐
623 out).
624 send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}
626 Equivalent to ct_ssh:send(SSH, ChannelId, 0, Data, Timeout).
628 send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}
630 Types:
632 SSH = connection()
634 ChannelId = integer()
635 Type = integer()
636 Data = list()
637 Timeout = integer()
638 Reason = term()
639 Sends data to server on specified session channel.
641 send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}
643 Equivalent to ct_ssh:send_and_receive(SSH, ChannelId, Data,
645 close).
646 send_and_receive(SSH, ChannelId, Data, End) -> {ok, Data} | {error,
648 Reason}
649 Equivalent to ct_ssh;send_and_receive(SSH, ChannelId, 0, Data,
651 End, DefaultTimeout).
652 send_and_receive(SSH, ChannelId, Data, End, Timeout) -> {ok, Data} |
654 {error, Reason}
655 Equivalent to ct_ssh:send_and_receive(SSH, ChannelId, 0, Data,
657 End, Timeout).
658 send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -> {ok,
660 Data} | {error, Reason}
661 Types:
663 SSH = connection()
665 ChannelId = integer()
666 Type = integer()
667 Data = list()
668 End = Fun | close | timeout
669 Timeout = integer()
670 Reason = term()
671 Sends data to server on specified session channel and waits to
673 receive the server response.
674 For details on argument End, see ct_ssh:receive_response/4.
676 session_close(SSH, ChannelId) -> ok | {error, Reason}
678 Types:
680 SSH = connection()
682 ChannelId = integer()
683 Reason = term()
684 Closes an SSH session channel.
686 session_open(SSH) -> {ok, ChannelId} | {error, Reason}
688 Equivalent to ct_ssh:session_open(SSH, DefaultTimeout).
690 session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}
692 Types:
694 SSH = connection()
696 Timeout = integer()
697 ChannelId = integer()
698 Reason = term()
699 Opens a channel for an SSH session.
701 sftp_connect(SSH) -> {ok, Server} | {error, Reason}
703 Types:
705 SSH = connection()
707 Server = pid()
708 Reason = term()
709 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 shell(SSH, ChannelId) -> ok | {error, Reason}
715 Equivalent to ct_ssh:shell(SSH, ChannelId, DefaultTimeout).
717 shell(SSH, ChannelId, Timeout) -> ok | {error, Reason}
719 Types:
721 SSH = connection()
723 ChannelId = integer()
724 Timeout = integer()
725 Reason = term()
726 Requests that the user default shell (typically defined in
728 /etc/passwd in Unix systems) is executed at the server end.
729 subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}
731 Equivalent to ct_ssh:subsystem(SSH, ChannelId, Subsystem, De‐
733 faultTimeout).
734 subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error, Rea‐
736 son}
737 Types:
739 SSH = connection()
741 ChannelId = integer()
742 Subsystem = string()
743 Timeout = integer()
744 Status = success | failure
745 Reason = term()
746 Sends a request to execute a predefined subsystem.
748 write(SSH, Handle, Data) -> Result
750 Types:
752 SSH = connection()
754 Result = ssh_sftp_return() | {error, Reason}
755 Reason = term()
756 For information and other types, see ssh_sftp(3).
758 write(SSH, Server, Handle, Data) -> Result
760 Types:
762 SSH = connection()
764 Result = ssh_sftp_return() | {error, Reason}
765 Reason = term()
766 For information and other types, see ssh_sftp(3).
768 write_file(SSH, File, Iolist) -> Result
770 Types:
772 SSH = connection()
774 Result = ssh_sftp_return() | {error, Reason}
775 Reason = term()
776 For information and other types, see ssh_sftp(3).
778 write_file(SSH, Server, File, Iolist) -> Result
780 Types:
782 SSH = connection()
784 Result = ssh_sftp_return() | {error, Reason}
785 Reason = term()
786 For information and other types, see ssh_sftp(3).
788 write_file_info(SSH, Name, Info) -> Result
790 Types:
792 SSH = connection()
794 Result = ssh_sftp_return() | {error, Reason}
795 Reason = term()
796 For information and other types, see ssh_sftp(3).
798 write_file_info(SSH, Server, Name, Info) -> Result
800 Types:
802 SSH = connection()
804 Result = ssh_sftp_return() | {error, Reason}
805 Reason = term()
806 For information and other types, see ssh_sftp(3).
808Ericsson AB common_test 1.25.1 ct_ssh(3)