ssh_connection(3erl) Erlang Module Definition ssh_connection(3erl)
NAME
ssh_connection -
This module provides API functions to send SSH Connection Protocol
events to the other side of an SSH channel.
DESCRIPTION
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 handling the remote channel. The Er-
lang format of thoose messages is (see also below):
{ssh_cm, ssh:connection_ref(), channel_msg()}
If the ssh_client_channel behavior is used to implement the channel
process, these messages are handled by handle_ssh_msg/2.
DATA TYPES
ssh_data_type_code() = integer() >= 0
The valid values are 0 ("normal") and 1 ("stderr"), see RFC
4254, Section 5.2.
result() = req_status() | {error, reason()}
reason() = closed | timeout
The result of a call.
If the request reached the peer, was handled and the response
reached the requesting node the req_status() is the status re-
ported from the peer.
If not, the reason() indicates what went wrong:
closed:
indicates that the channel or connection was closed when
trying to send the request
timeout:
indicates that the operation exceeded a time limit
req_status() = success | failure
The status of a request. Coresponds to the SSH_MSG_CHANNEL_SUC-
CESS and SSH_MSG_CHANNEL_FAILURE values in RFC 4254, Section
5.4.
SSH Connection Protocol: General
event() = {ssh_cm, ssh:connection_ref(), channel_msg()}
channel_msg() =
data_ch_msg() |
eof_ch_msg() |
closed_ch_msg() |
pty_ch_msg() |
env_ch_msg() |
shell_ch_msg() |
exec_ch_msg() |
signal_ch_msg() |
window_change_ch_msg() |
exit_status_ch_msg() |
exit_signal_ch_msg()
As mentioned in the introduction, the SSH Connection Protocol
events are handled as messages. When writing a channel handling
process without using the support by the ssh_client_channel be-
havior the process must handle thoose messages.
want_reply() = boolean()
Messages that include a WantReply expect the channel handling
process to call ssh_connection:reply_request/4 with the boolean
value of WantReply as the second argument.
Data Transfer (RFC 4254, section 5.2)
data_ch_msg() =
{data,
ssh:channel_id(),
ssh_data_type_code(),
Data :: binary()}
Data has arrived on the channel. This event is sent as a result
of calling ssh_connection:send/[3,4,5].
Closing a Channel (RFC 4254, section 5.3)
eof_ch_msg() = {eof, ssh:channel_id()}
Indicates that the other side sends no more data. This event is
sent as a result of calling ssh_connection:send_eof/2.
closed_ch_msg() = {closed, ssh:channel_id()}
This event is sent as a result of calling ssh_connec-
tion:close/2. Both the handling of this event and sending it are
taken care of by the ssh_client_channel behavior.
Requesting a Pseudo-Terminal (RFC 4254, section 6.2)
pty_ch_msg() =
{pty,
ssh:channel_id(),
want_reply(),
{Terminal :: string(),
CharWidth :: integer() >= 0,
RowHeight :: integer() >= 0,
PixelWidth :: integer() >= 0,
PixelHeight :: integer() >= 0,
TerminalModes :: [term_mode()]}}
term_mode() =
{Opcode :: atom() | byte(), Value :: integer() >= 0}
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 charac-
ter/row dimensions override the pixel dimensions (when non-
zero). Pixel dimensions refer to the drawable area of the win-
dow. Opcode in the TerminalModes list is the mnemonic name, rep-
resented as a lowercase Erlang atom, defined in RFC 4254, Sec-
tion 8. It can also be an Opcode if the mnemonic name is not
listed in the RFC. Example: OP code: 53, mnemonic name ECHO er-
lang atom: echo. This event is sent as a result of calling
ssh_connection:ptty_alloc/4.
Environment Variable Passing (RFC 4254, section 6.4)
env_ch_msg() =
{env,
ssh:channel_id(),
want_reply(),
Var :: string(),
Value :: string()}
Environment variables can be passed to the shell/command to be
started later. This event is sent as a result of calling
ssh_connection:setenv/5.
Starting a Shell or Command (RFC 4254, section 6.5)
shell_ch_msg() = {shell, ssh:channel_id(), want_reply()}
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.
exec_ch_msg() =
{exec, ssh:channel_id(), want_reply(), Command :: string()}
This message requests that the server starts execution of the
given command. This event is sent as a result of calling
ssh_connection:exec/4 .
Window Dimension Change Message (RFC 4254, section 6.7)
window_change_ch_msg() =
{window_change,
ssh:channel_id(),
CharWidth :: integer() >= 0,
RowHeight :: integer() >= 0,
PixelWidth :: integer() >= 0,
PixelHeight :: integer() >= 0}
When the window (terminal) size changes on the client side, it
can send a message to the server side to inform it of the new
dimensions. No API function generates this event.
Signals (RFC 4254, section 6.9)
signal_ch_msg() =
{signal, ssh:channel_id(), SignalName :: string()}
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 pro-
gram.
Returning Exit Status (RFC 4254, section 6.10)
exit_status_ch_msg() =
{exit_status,
ssh:channel_id(),
ExitStatus :: integer() >= 0}
When the command running at the other end terminates, the fol-
lowing message can be sent to return the exit status of the com-
mand. A zero exit_status usually means that the command termi-
nated successfully. This event is sent as a result of calling
ssh_connection:exit_status/3.
exit_signal_ch_msg() =
{exit_signal,
ssh:channel_id(),
ExitSignal :: string(),
ErrorMsg :: string(),
LanguageString :: string()}
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.
EXPORTS
adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh: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 han-
dled by the behavior. The behavior adjusts the window every time
the callback handle_ssh_msg/2 returns after processing channel
data.
close(ConnectionRef, ChannelId) -> ok
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh: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(3erl). Thus,
channels implemented with the behavior are not to call this
function explicitly.
exec(ConnectionRef, ChannelId, Command, Timeout) -> result()
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh: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 exe-
cution that closes the channel when it is done.
N x data message(s):
The result of executing the command can be only one line or
thousands of lines depending on the command.
0 or 1 x eof message:
Indicates that no more data is to be sent.
0 or 1 x exit signal message:
Not all systems send signals. For details on valid string
values, see RFC 4254, Section 6.10
0 or 1 x exit status message:
It is recommended by the SSH Connection Protocol to send
this message, but that is not always the case.
1 x closed status message:
Indicates that the ssh_client_channel started for the execu-
tion of the command has now been shut down.
See the User's Guide section on One-Time Execution for examples.
exit_status(ConnectionRef, ChannelId, Status) -> ok
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Status = integer()
Is to be called by a server-channel process to send the exit
status of a command to the client.
ptty_alloc(ConnectionRef, ChannelId, Options) -> result()
ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result()
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Options = proplists:proplist()
Timeout = timeout()
Sends an SSH Connection Protocol pty_req, to allocate a pseudo-
terminal. Is to be called by an SSH client process.
Options:
{term, string()}:
Defaults to os:getenv("TERM") or vt100 if it is undefined.
{width, integer()}:
Defaults to 80 if pixel_width is not defined.
{height, integer()}:
Defaults to 24 if pixel_height is not defined.
{pixel_width, integer()}:
Is disregarded if width is defined.
{pixel_height, integer()}:
Is disregarded if height is defined.
{pty_opts, [{posix_atom(), integer()}]}:
Option can be an empty list. Otherwise, see possible POSIX
names in Section 8 in RFC 4254.
reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
Types:
ConnectionRef = ssh:connection_ref()
WantReply = boolean()
Status = req_status()
ChannelId = ssh: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.
send(ConnectionRef, ChannelId, Data) ->
send(ConnectionRef, ChannelId, Data, Timeout) ->
send(ConnectionRef, ChannelId, Type, Data) ->
send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | Error
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Data = iodata()
Type = ssh_data_type_code()
Timeout = timeout()
Error = {error, reason()}
Is to be called by client- and server-channel processes to send
data to each other.
The function subsystem/4 and subsequent calls of send/3,4,5 must
be executed in the same process.
send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Sends EOF on channel ChannelId.
session_channel(ConnectionRef, Timeout) -> Result
session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize,
Timeout) ->
Result
Types:
ConnectionRef = ssh:connection_ref()
InitialWindowSize = MaxPacketSize = integer() >= 1
Timeout = timeout()
Result = {ok, ssh:channel_id()} | {error, reason()}
Opens a channel for an SSH session. The channel id returned from
this function is the id used as input to the other functions in
this module.
setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> result()
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Var = Value = string()
Timeout = timeout()
Environment variables can be passed before starting the
shell/command. Is to be called by a client channel processes.
shell(ConnectionRef, ChannelId) -> Result
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Result = ok | success | failure | {error, timeout}
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.
subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) ->
result()
Types:
ConnectionRef = ssh:connection_ref()
ChannelId = ssh:channel_id()
Subsystem = string()
Timeout = timeout()
Is to be called by a client-channel process for requesting to
execute a predefined subsystem on the server.
The function subsystem/4 and subsequent calls of send/3,4,5 must
be executed in the same process.
Ericsson AB ssh 4.10 ssh_connection(3erl)