.TH ssh_connection 3erl "ssh 4.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ssh_connection \- 
    This module provides API functions to send SSH Connection Protocol 
    events to the other side of an SSH channel.
  
.SH DESCRIPTION
.LP
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 \fI{ssh_cm, ssh_connection_ref(), ssh_event_msg()}\fR\&\&. If the \fBssh_channel\fR\& behavior is used to implement the channel process, these messages are handled by \fBhandle_ssh_msg/2\fR\&\&.
.SH "DATA TYPES"

.LP
Type definitions that are used more than once in this module, or abstractions to indicate the intended use of the data type, or both:
.RS 2
.TP 2
.B
\fIboolean() =\fR\&:
\fItrue | false \fR\&
.TP 2
.B
\fIstring() =\fR\&:
list of ASCII characters
.TP 2
.B
\fItimeout() =\fR\&:
\fIinfinity | integer()\fR\& in milliseconds
.TP 2
.B
\fIssh_connection_ref() =\fR\&:
opaque() -as returned by \fIssh:connect/3\fR\& or sent to an SSH channel processes
.TP 2
.B
\fIssh_channel_id() =\fR\&:
\fIinteger()\fR\&
.TP 2
.B
\fIssh_data_type_code() =\fR\&:
\fI1\fR\& ("stderr") | \fI0\fR\& ("normal") are valid values, see RFC 4254 Section 5\&.2\&.
.TP 2
.B
\fIssh_request_status() =\fR\&:
\fIsuccess | failure\fR\&
.TP 2
.B
\fIevent() =\fR\&:
\fI{ssh_cm, ssh_connection_ref(), ssh_event_msg()}\fR\&
.TP 2
.B
\fIssh_event_msg() =\fR\&:
\fIdata_events() | status_events() | terminal_events()\fR\&
.TP 2
.B
\fIreason() =\fR\&:
\fItimeout | closed\fR\&
.RE
.RS 2
.TP 2
.B
\fIdata_events()\fR\&:

.RS 2
.TP 2
.B
\fI{data, ssh_channel_id(), ssh_data_type_code(), Data :: binary()}\fR\&:
Data has arrived on the channel\&. This event is sent as a result of calling \fB ssh_connection:send/[3,4,5]\fR\&\&.
.TP 2
.B
\fI{eof, ssh_channel_id()}\fR\&:
Indicates that the other side sends no more data\&. This event is sent as a result of calling \fB ssh_connection:send_eof/2\fR\&\&.
.RE
.TP 2
.B
\fIstatus_events()\fR\&:

.RS 2
.TP 2
.B
\fI{signal, ssh_channel_id(), ssh_signal()}\fR\&:
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\&.
.TP 2
.B
\fI{exit_signal, ssh_channel_id(), ExitSignal :: string(), ErrorMsg ::string(), LanguageString :: string()}\fR\&:
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\&.
.TP 2
.B
\fI{exit_status, ssh_channel_id(), ExitStatus :: integer()}\fR\&:
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 \fIexit_status\fR\& usually means that the command terminated successfully\&. This event is sent as a result of calling \fB ssh_connection:exit_status/3\fR\&\&.
.TP 2
.B
\fI{closed, ssh_channel_id()}\fR\&:
This event is sent as a result of calling \fBssh_connection:close/2\fR\&\&. Both the handling of this event and sending it are taken care of by the \fBssh_channel\fR\& behavior\&.
.RE
.TP 2
.B
\fIterminal_events()\fR\&:
Channels implementing a shell and command execution on the server side are to handle the following messages that can be sent by client- channel processes\&.
.RS 2
.LP
Events that include a \fIWantReply\fR\& expect the event handling process to call \fB ssh_connection:reply_request/4\fR\& with the boolean value of \fIWantReply\fR\& as the second argument\&.
.RE

.RS 2
.TP 2
.B
\fI{env, ssh_channel_id(), WantReply :: boolean(), Var ::string(), Value :: string()}\fR\&:
Environment variables can be passed to the shell/command to be started later\&. This event is sent as a result of calling \fB ssh_connection:setenv/5\fR\&\&.
.TP 2
.B
\fI{pty, ssh_channel_id(), WantReply :: boolean(), {Terminal :: string(), CharWidth :: integer(), RowHeight :: integer(), PixelWidth :: integer(), PixelHeight :: integer(), TerminalModes :: [{Opcode :: atom() | integer(), Value :: integer()}]}}\fR\&:
A pseudo-terminal has been requested for the session\&. \fITerminal\fR\& is the value of the TERM environment variable value, that is, \fIvt100\fR\&\&. 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\&. \fIOpcode\fR\& in the \fITerminalModes\fR\& list is the mnemonic name, represented as a lowercase Erlang atom, defined in RFC 4254, Section 8\&. It can also be an \fIOpcode\fR\& if the mnemonic name is not listed in the RFC\&. Example: \fIOP code: 53, mnemonic name ECHO erlang atom: echo\fR\&\&. This event is sent as a result of calling \fBssh_connection:ptty_alloc/4\fR\&\&.
.TP 2
.B
\fI{shell, WantReply :: boolean()}\fR\&:
This message requests that the user default shell is started at the other end\&. This event is sent as a result of calling \fB ssh_connection:shell/2\fR\&\&.
.TP 2
.B
\fI{window_change, ssh_channel_id(), CharWidth() :: integer(), RowHeight :: integer(), PixWidth :: integer(), PixHeight :: integer()}\fR\&:
When the window (terminal) size changes on the client side, it \fIcan\fR\& send a message to the server side to inform it of the new dimensions\&. No API function generates this event\&.
.TP 2
.B
\fI{exec, ssh_channel_id(), WantReply :: boolean(), Cmd :: string()}\fR\&:
This message requests that the server starts execution of the given command\&. This event is sent as a result of calling \fBssh_connection:exec/4 \fR\&\&.
.RE
.RE
.SH EXPORTS
.LP
.B
adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
NumOfBytes = integer()
.br
.RE
.RE
.RS
.LP
Adjusts the SSH flow control window\&. This is to be done by both the client- and server-side channel processes\&.
.LP

.RS -4
.B
Note:
.RE
Channels implemented with the \fB ssh_channel\fR\& 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 \fB handle_ssh_msg/2\fR\& returns after processing channel data\&.

.RE

.LP
.B
close(ConnectionRef, ChannelId) -> ok
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
A server- or client-channel process can choose to close their session by sending a close event\&.
.LP

.RS -4
.B
Note:
.RE
This function is called by the \fIssh_channel\fR\& behavior when the channel is terminated, see \fB ssh_channel(3erl)\fR\&\&. Thus, channels implemented with the behavior are not to call this function explicitly\&.

.RE

.LP
.B
exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | {error, reason()}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
Command = string()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
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 \fIexec\fR\& request is a one-time execution that closes the channel when it is done\&.
.RS 2
.TP 2
.B
\fIN x {ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(), Data :: binary()}}\fR\&:
The result of executing the command can be only one line or thousands of lines depending on the command\&.
.TP 2
.B
\fI0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}\fR\&:
Indicates that no more data is to be sent\&.
.TP 2
.B
\fI0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_signal, ssh_channel_id(), ExitSignal :: string(), ErrorMsg :: string(), LanguageString :: string()}}\fR\&:
Not all systems send signals\&. For details on valid string values, see RFC 4254, Section 6\&.10
.TP 2
.B
\fI0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status, ssh_channel_id(), ExitStatus :: integer()}}\fR\&:
It is recommended by the SSH Connection Protocol to send this message, but that is not always the case\&.
.TP 2
.B
\fI1 x {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}}\fR\&:
Indicates that the \fIssh_channel\fR\& started for the execution of the command has now been shut down\&.
.RE
.RE

.LP
.B
exit_status(ConnectionRef, ChannelId, Status) -> ok
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref() 
.br
ChannelId = ssh_channel_id()
.br
Status = integer()
.br
.RE
.RE
.RS
.LP
Is to be called by a server-channel process to send the exit status of a command to the client\&.
.RE

.LP
.B
ptty_alloc(ConnectionRef, ChannelId, Options) ->
.br
.B
ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | {error, reason()}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
Options = proplists:proplist()
.br
.RE
.RE
.RS
.LP
Sends an SSH Connection Protocol \fIpty_req\fR\&, to allocate a pseudo-terminal\&. Is to be called by an SSH client process\&.
.LP
Options:
.RS 2
.TP 2
.B
{term, string()}:
Defaults to \fIos:getenv("TERM")\fR\& or \fIvt100\fR\& if it is undefined\&.
.TP 2
.B
{width, integer()}:
Defaults to 80 if \fIpixel_width\fR\& is not defined\&.
.TP 2
.B
{height, integer()}:
Defaults to 24 if \fIpixel_height\fR\& is not defined\&.
.TP 2
.B
{pixel_width, integer()}:
Is disregarded if \fIwidth\fR\& is defined\&.
.TP 2
.B
{pixel_height, integer()}:
Is disregarded if \fIheight\fR\& is defined\&.
.TP 2
.B
{pty_opts, [{posix_atom(), integer()}]}:
Option can be an empty list\&. Otherwise, see possible \fIPOSIX\fR\& names in Section 8 in  RFC 4254\&.
.RE
.RE

.LP
.B
reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
WantReply = boolean()
.br
Status = ssh_request_status()
.br
ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Sends status replies to requests where the requester has stated that it wants a status report, that is, \fIWantReply = true\fR\&\&. If \fIWantReply\fR\& is \fIfalse\fR\&, calling this function becomes a "noop"\&. Is to be called while handling an SSH Connection Protocol message containing a \fIWantReply\fR\& boolean value\&.
.RE

.LP
.B
send(ConnectionRef, ChannelId, Data) ->
.br
.B
send(ConnectionRef, ChannelId, Data, Timeout) ->
.br
.B
send(ConnectionRef, ChannelId, Type, Data) ->
.br
.B
send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error, timeout} | {error, closed}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
Data = binary()
.br
Type = ssh_data_type_code()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Is to be called by client- and server-channel processes to send data to each other\&.
.LP
The function \fBsubsystem/4\fR\& and subsequent calls of \fIsend/3,4,5\fR\& must be executed in the same process\&.
.RE

.LP
.B
send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Sends EOF on channel \fIChannelId\fR\&\&.
.RE

.LP
.B
session_channel(ConnectionRef, Timeout) ->
.br
.B
session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
InitialWindowSize = integer()
.br
MaxPacketSize = integer()
.br
Timeout = timeout()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
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\&.
.RE

.LP
.B
setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | {error, reason()}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
Var = string()
.br
Value = string()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Environment variables can be passed before starting the shell/command\&. Is to be called by a client channel processes\&.
.RE

.LP
.B
shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed} 
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
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\&.
.RE

.LP
.B
subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | {error, reason()}
.br
.RS
.LP
Types:

.RS 3
ConnectionRef = ssh_connection_ref()
.br
ChannelId = ssh_channel_id()
.br
Subsystem = string()
.br
Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Is to be called by a client-channel process for requesting to execute a predefined subsystem on the server\&.
.LP
The function \fIsubsystem/4\fR\& and subsequent calls of \fBsend/3,4,5\fR\& must be executed in the same process\&.
.RE