ssh_connection

The SSH Connection Protocol
is used by clients and servers, that is, SSH channels, to communicate over the
SSH connection. The API functions in this module send SSH Connection Protocol events,
which are received as messages by the remote channel.
If the receiving channel is an Erlang process, the
messages have the format
{ssh_cm, connection_ref(), ssh_event_msg()}.
If the ssh_client_channel behavior is used to
implement the channel process, these messages are handled by
handle_ssh_msg/2.

A signal can be delivered to the remote process/service
using the following message. Some systems do not support
signals, in which case they are to ignore this message. There is
currently no function to generate this event as the signals
referred to are on OS-level and not something generated by an
Erlang program.

A remote execution can terminate violently because of a signal.
Then this message can be received. For details on valid string
values, see RFC 4254
Section 6.10, which shows a special case of these signals.

{exit_status, channel_id(), ExitStatus :: integer()}

When the command running at the other end terminates, the
following message can be sent to return the exit status of the
command. A zero exit_status usually means that the command
terminated successfully. This event is sent as a result of calling
ssh_connection:exit_status/3.

A pseudo-terminal has been requested for the
session. Terminal is the value of the TERM environment
variable value, that is, vt100. Zero dimension parameters must
be ignored. The character/row dimensions override the pixel
dimensions (when non-zero). Pixel dimensions refer to the
drawable area of the window. Opcode in the
TerminalModes list is the mnemonic name, represented
as a lowercase Erlang atom, defined in
RFC 4254, Section 8.
It can also be an Opcode if the mnemonic name is not listed in the
RFC. Example: OP code: 53, mnemonic name ECHO erlang atom:
echo. This event is sent as a result of calling ssh_connection:ptty_alloc/4.

{shell, WantReply :: boolean()}

This message requests that the user default shell
is started at the other end. This event is sent as a result of calling
ssh_connection:shell/2.

Types

ConnectionRef = connection_ref()

ChannelId = channel_id()

NumOfBytes = integer()

Adjusts the SSH flow control window. This is to be done by both the
client- and server-side channel processes.

Note

Channels implemented with the ssh_client_channel
behavior do not normally need to call this function as flow control
is handled by the behavior. The behavior adjusts the window every time
the callback handle_ssh_msg/2 returns after processing channel data.

Types

ConnectionRef = connection_ref()

ChannelId = channel_id()

A server- or client-channel process can choose to close their session by
sending a close event.

Note

This function is called by the ssh_client_channel
behavior when the channel is terminated, see ssh_client_channel(3). Thus, channels implemented
with the behavior are not to call this function explicitly.

Types

ConnectionRef = connection_ref()

ChannelId = channel_id()

Command = string()

Timeout = timeout()

Is to be called by a client-channel process to request that the server starts
executing the given command. The result is several messages according to the
following pattern. The last message is a channel close message, as the exec
request is a one-time execution that closes the channel when it is done.

Types

ConnectionRef = connection_ref()

WantReply = boolean()

Status = ssh_request_status()

ChannelId = channel_id()

Sends status replies to requests where the requester has
stated that it wants a status report, that is, WantReply = true.
If WantReply is false, calling this function becomes a
"noop". Is to be called while handling an SSH Connection
Protocol message containing a WantReply boolean value.

Types

Is to be called by a client channel process to request that the user default
shell (typically defined in /etc/passwd in Unix systems) is executed
at the server end.

Note: the return value is ok instead of success unlike in other
functions in this module. This is a fault that was introduced so long ago that
any change would break a large number of existing software.