---
name: "ct_ssh"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/ct_ssh"
---

# ct\_ssh(3erl)

SSH/SFTP client module.

## NAME

ct\_ssh - SSH/SFTP client module.

## DESCRIPTION

SSH/SFTP client module.

This module uses application *SSH*, which provides detailed information about, for example, functions, types, and options.

Argument *Server* in the SFTP functions is only to be used for SFTP sessions that have been started on existing SSH connections (that is, when the original connection type is *ssh*). Whenever the connection type is *sftp*, use the SSH connection reference only.

The following options are valid for specifying an SSH/SFTP connection (that is, can be used as configuration elements):

```
 [{ConnType, Addr},
  {port, Port},
  {user, UserName}
  {password, Pwd}
  {user_dir, String}
  {public_key_alg, PubKeyAlg}
  {connect_timeout, Timeout}
  {key_cb, KeyCallbackMod}]
```

*ConnType = ssh \| sftp*.

For other types, see *[ssh(3erl)](/ssh/3erl.md)*.

All time-out parameters in *ct\_ssh* functions are values in milliseconds.

## DATA TYPES

```
connection() = handle() | target_name()
```

For *target\_name*, see module *ct*.

```
handle() = handle()
```

Handle for a specific SSH/SFTP connection, see module *ct*.

```
ssh_sftp_return() = term()
```

Return value from an *ssh\_sftp* function.

## EXPORTS

**apread(SSH, Handle, Position, Length) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**apread(SSH, Server, Handle, Position, Length) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**apwrite(SSH, Handle, Position, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**apwrite(SSH, Server, Handle, Position, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**aread(SSH, Handle, Len) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**aread(SSH, Server, Handle, Len) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**awrite(SSH, Handle, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**awrite(SSH, Server, Handle, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**close(SSH, Handle) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**close(SSH, Server, Handle) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**connect(KeyOrName) -\> {ok, Handle} \| {error, Reason}**\

Equivalent to *ct\_ssh:connect(KeyOrName, host, \[\])*.

**connect(KeyOrName, ConnType) -\> {ok, Handle} \| {error, Reason}**\

Equivalent to *ct\_ssh:connect(KeyOrName, ConnType, \[\])*.

**connect(KeyOrName, ConnType, ExtraOpts) -\> {ok, Handle} \| {error, Reason}**\

Types:

KeyOrName = Key \| Name\
 Key = atom()\
 Name = target\_name()\
 ConnType = ssh \| sftp \| host\
 ExtraOpts = ssh\_connect\_options()\
 Handle = handle()\
 Reason = term()\

Opens an SSH or SFTP connection using the information associated with *KeyOrName*.

If *Name* (an alias name for *Key*) is used to identify the connection, this name can be used as connection reference for subsequent calls. Only one open connection at a time associated with *Name* is possible. If *Key* is used, the returned handle must be used for subsequent calls (multiple connections can be opened using the configuration data specified by *Key*).

For information on how to create a new *Name*, see *ct:require/2*.

For *target\_name*, see module *ct*.

*ConnType* always overrides the type specified in the address tuple in the configuration data (and in *ExtraOpts*). So it is possible to, for example, open an SFTP connection directly using data originally specifying an SSH connection. Value *host* means that the connection type specified by the host option (either in the configuration data or in *ExtraOpts*) is used.

*ExtraOpts* (optional) are extra SSH options to be added to the configuration data for *KeyOrName*. The extra options override any existing options with the same key in the configuration data. For details on valid SSH options, see application *SSH*.

**del\_dir(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**del\_dir(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**delete(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**delete(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**disconnect(SSH) -\> ok \| {error, Reason}**\

Types:

SSH = connection()\
 Reason = term()\

Closes an SSH/SFTP connection.

**exec(SSH, Command) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh:exec(SSH, Command, DefaultTimeout)*.

**exec(SSH, Command, Timeout) -\> {ok, Data} \| {error, Reason}**\

Types:

SSH = connection()\
 Command = string()\
 Timeout = integer()\
 Data = list()\
 Reason = term()\

Requests server to perform *Command*. A session channel is opened automatically for the request. *Data* is received from the server as a result of the command.

**exec(SSH, ChannelId, Command, Timeout) -\> {ok, Data} \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Command = string()\
 Timeout = integer()\
 Data = list()\
 Reason = term()\

Requests server to perform *Command*. A previously opened session channel is used for the request. *Data* is received from the server as a result of the command.

**get\_file\_info(SSH, Handle) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**get\_file\_info(SSH, Server, Handle) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**list\_dir(SSH, Path) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**list\_dir(SSH, Server, Path) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**make\_dir(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**make\_dir(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**make\_symlink(SSH, Name, Target) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**make\_symlink(SSH, Server, Name, Target) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**open(SSH, File, Mode) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**open(SSH, Server, File, Mode) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**opendir(SSH, Path) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**opendir(SSH, Server, Path) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**position(SSH, Handle, Location) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**position(SSH, Server, Handle, Location) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**pread(SSH, Handle, Position, Length) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**pread(SSH, Server, Handle, Position, Length) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**pwrite(SSH, Handle, Position, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**pwrite(SSH, Server, Handle, Position, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read(SSH, Handle, Len) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read(SSH, Server, Handle, Len) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_file(SSH, File) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_file(SSH, Server, File) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_file\_info(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_file\_info(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_link(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_link(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_link\_info(SSH, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**read\_link\_info(SSH, Server, Name) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**receive\_response(SSH, ChannelId) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh:receive\_response(SSH, ChannelId, close)*.

**receive\_response(SSH, ChannelId, End) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh:receive\_response(SSH, ChannelId, End, DefaultTimeout)*.

**receive\_response(SSH, ChannelId, End, Timeout) -\> {ok, Data} \| {timeout, Data} \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 End = Fun \| close \| timeout\
 Timeout = integer()\
 Data = list()\
 Reason = term()\

Receives expected data from server on the specified session channel.

If *End == close*, data is returned to the caller when the channel is closed by the server. If a time-out occurs before this happens, the function returns *{timeout,Data}* (where *Data* is the data received so far).

If *End == timeout*, a time-out is expected and *{ok,Data}* is returned both in the case of a time-out and when the channel is closed.

If *End* is a fun, this fun is called with one argument, the data value in a received *ssh\_cm* message (see *[ssh\_connection(3erl)](/ssh_connection/3erl.md)*. The fun is to return either *true* to end the receiving operation (and have the so far collected data returned) or *false* to wait for more data from the server. Even if a fun is supplied, the function returns immediately if the server closes the channel).

**rename(SSH, OldName, NewName) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**rename(SSH, Server, OldName, NewName) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**send(SSH, ChannelId, Data) -\> ok \| {error, Reason}**\

Equivalent to *ct\_ssh:send(SSH, ChannelId, 0, Data, DefaultTimeout)*.

**send(SSH, ChannelId, Data, Timeout) -\> ok \| {error, Reason}**\

Equivalent to *ct\_ssh:send(SSH, ChannelId, 0, Data, Timeout)*.

**send(SSH, ChannelId, Type, Data, Timeout) -\> ok \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Type = integer()\
 Data = list()\
 Timeout = integer()\
 Reason = term()\

Sends data to server on specified session channel.

**send\_and\_receive(SSH, ChannelId, Data) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh:send\_and\_receive(SSH, ChannelId, Data, close)*.

**send\_and\_receive(SSH, ChannelId, Data, End) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh;send\_and\_receive(SSH, ChannelId, 0, Data, End, DefaultTimeout)*.

**send\_and\_receive(SSH, ChannelId, Data, End, Timeout) -\> {ok, Data} \| {error, Reason}**\

Equivalent to *ct\_ssh:send\_and\_receive(SSH, ChannelId, 0, Data, End, Timeout)*.

**send\_and\_receive(SSH, ChannelId, Type, Data, End, Timeout) -\> {ok, Data} \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Type = integer()\
 Data = list()\
 End = Fun \| close \| timeout\
 Timeout = integer()\
 Reason = term()\

Sends data to server on specified session channel and waits to receive the server response.

For details on argument *End*, see *ct\_ssh:receive\_response/4*.

**session\_close(SSH, ChannelId) -\> ok \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Reason = term()\

Closes an SSH session channel.

**session\_open(SSH) -\> {ok, ChannelId} \| {error, Reason}**\

Equivalent to *ct\_ssh:session\_open(SSH, DefaultTimeout)*.

**session\_open(SSH, Timeout) -\> {ok, ChannelId} \| {error, Reason}**\

Types:

SSH = connection()\
 Timeout = integer()\
 ChannelId = integer()\
 Reason = term()\

Opens a channel for an SSH session.

**sftp\_connect(SSH) -\> {ok, Server} \| {error, Reason}**\

Types:

SSH = connection()\
 Server = pid()\
 Reason = term()\

Starts an SFTP session on an already existing SSH connection. *Server* identifies the new session and must be specified whenever SFTP requests are to be sent.

**shell(SSH, ChannelId) -\> ok \| {error, Reason}**\

Equivalent to *ct\_ssh:shell(SSH, ChannelId, DefaultTimeout)*.

**shell(SSH, ChannelId, Timeout) -\> ok \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Timeout = integer()\
 Reason = term()\

Requests that the user default shell (typically defined in */etc/passwd* in Unix systems) is executed at the server end.

**subsystem(SSH, ChannelId, Subsystem) -\> Status \| {error, Reason}**\

Equivalent to *ct\_ssh:subsystem(SSH, ChannelId, Subsystem, DefaultTimeout)*.

**subsystem(SSH, ChannelId, Subsystem, Timeout) -\> Status \| {error, Reason}**\

Types:

SSH = connection()\
 ChannelId = integer()\
 Subsystem = string()\
 Timeout = integer()\
 Status = success \| failure\
 Reason = term()\

Sends a request to execute a predefined subsystem.

**write(SSH, Handle, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**write(SSH, Server, Handle, Data) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**write\_file(SSH, File, Iolist) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**write\_file(SSH, Server, File, Iolist) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**write\_file\_info(SSH, Name, Info) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.

**write\_file\_info(SSH, Server, Name, Info) -\> Result**\

Types:

SSH = connection()\
 Result = ssh\_sftp\_return() \| {error, Reason}\
 Reason = term()\

For information and other types, see *[ssh\_sftp(3erl)](/ssh_sftp/3erl.md)*.