<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2008</year>
<year>2014</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
The Initial Developer of the Original Code is Ericsson AB.
</legalnotice>
<title>ssh_connection</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<module>ssh_connection</module>
<modulesummary>This module provides API functions to send
<url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH Connection Protocol </url>
events to the other side of an SSH channel.
</modulesummary>
<description>
<p>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
<c><![CDATA[{ssh_cm, ssh_connection_ref(), ssh_event_msg()}]]></c>.
If the <seealso marker="ssh_channel">ssh_channel</seealso> behavior is used to
implement the channel process, these messages are handled by
<seealso marker="ssh_channel#Module:handle_ssh_msg-2">handle_ssh_msg/2</seealso>.</p>
</description>
<section>
<title>DATA TYPES</title>
<p>Type definitions that are used more than once in this module,
or abstractions to indicate the intended use of the data
type, or both:</p>
<taglist>
<tag><c>boolean() =</c></tag>
<item><p><c>true | false </c></p></item>
<tag><c>string() =</c></tag>
<item><p>list of ASCII characters</p></item>
<tag><c>timeout() =</c></tag>
<item><p><c>infinity | integer()</c> in milliseconds</p></item>
<tag><c>ssh_connection_ref() =</c></tag>
<item><p>opaque() -as returned by
<c>ssh:connect/3</c> or sent to an SSH channel processes</p></item>
<tag><c>ssh_channel_id() =</c></tag>
<item><p><c>integer()</c></p></item>
<tag><c>ssh_data_type_code() =</c></tag>
<item><p><c>1</c> ("stderr") | <c>0</c> ("normal") are
valid values, see
<url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> Section 5.2.</p></item>
<tag><c>ssh_request_status() =</c></tag>
<item><p> <c>success | failure</c></p></item>
<tag><c>event() =</c></tag>
<item><p><c>{ssh_cm, ssh_connection_ref(), ssh_event_msg()}</c></p></item>
<tag><c>ssh_event_msg() =</c></tag>
<item><p><c>data_events() | status_events() | terminal_events()</c></p></item>
<tag><c>reason() =</c></tag>
<item><p><c>timeout | closed</c></p></item>
</taglist>
<taglist>
<tag><em>data_events()</em></tag>
<item>
<taglist>
<tag><c><![CDATA[{data, ssh_channel_id(), ssh_data_type_code(), Data :: binary()}]]></c></tag>
<item><p>Data has arrived on the channel. This event is sent as a
result of calling <seealso marker="ssh_connection#send-3">
ssh_connection:send/[3,4,5]</seealso>.</p></item>
<tag><c><![CDATA[{eof, ssh_channel_id()}]]></c></tag>
<item><p>Indicates that the other side sends no more data.
This event is sent as a result of calling <seealso
marker="ssh_connection#send_eof-2"> ssh_connection:send_eof/2</seealso>.
</p></item>
</taglist>
</item>
<tag><em>status_events()</em></tag>
<item>
<taglist>
<tag><c><![CDATA[{signal, ssh_channel_id(), ssh_signal()}]]></c></tag>
<item><p>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.</p></item>
<tag><c><![CDATA[{exit_signal, ssh_channel_id(), ExitSignal :: string(), ErrorMsg ::string(),
LanguageString :: string()}]]></c></tag>
<item><p>A remote execution can terminate violently because of a signal.
Then this message can be received. For details on valid string
values, see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>
Section 6.10, which shows a special case of these signals.</p></item>
<tag><c><![CDATA[{exit_status, ssh_channel_id(), ExitStatus :: integer()}]]></c></tag>
<item><p>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 <c>exit_status</c> usually means that the command
terminated successfully. This event is sent as a result of calling
<seealso marker="ssh_connection#exit_status-3">
ssh_connection:exit_status/3</seealso>.</p></item>
<tag><c><![CDATA[{closed, ssh_channel_id()}]]></c></tag>
<item><p>This event is sent as a result of calling
<seealso marker="ssh_connection#close-2">ssh_connection:close/2</seealso>.
Both the handling of this event and sending it are taken care of by the
<seealso marker="ssh_channel">ssh_channel</seealso> behavior.</p></item>
</taglist>
</item>
<tag><em>terminal_events()</em></tag>
<item>
<p>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.</p>
<p>Events that include a <c>WantReply</c> expect the event handling
process to call <seealso marker="ssh_connection#reply_request-4">
ssh_connection:reply_request/4</seealso>
with the boolean value of <c>WantReply</c> as the second argument.</p>
<taglist>
<tag><c><![CDATA[{env, ssh_channel_id(), WantReply :: boolean(),
Var ::string(), Value :: string()}]]></c></tag>
<item><p>Environment variables can be passed to the shell/command
to be started later. This event is sent as a result of calling <seealso
marker="ssh_connection#setenv-5"> ssh_connection:setenv/5</seealso>.
</p></item>
<tag><c><![CDATA[{pty, ssh_channel_id(),
WantReply :: boolean(), {Terminal :: string(), CharWidth :: integer(),
RowHeight :: integer(), PixelWidth :: integer(), PixelHeight :: integer(),
TerminalModes :: [{Opcode :: atom() | integer(),
Value :: integer()}]}}]]></c></tag>
<item><p>A pseudo-terminal has been requested for the
session. <c>Terminal</c> is the value of the TERM environment
variable value, that is, <c>vt100</c>. 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. <c>Opcode</c> in the
<c>TerminalModes</c> list is the mnemonic name, represented
as a lowercase Erlang atom, defined in
<url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>, Section 8.
It can also be an <c>Opcode</c> if the mnemonic name is not listed in the
RFC. Example: <c>OP code: 53, mnemonic name ECHO erlang atom:
echo</c>. This event is sent as a result of calling <seealso
marker="ssh_connection#ptty_alloc/4">ssh_connection:ptty_alloc/4</seealso>.</p></item>
<tag><c><![CDATA[{shell, WantReply :: boolean()}]]></c></tag>
<item><p>This message requests that the user default shell
is started at the other end. This event is sent as a result of calling
<seealso marker="ssh_connection#shell-2"> ssh_connection:shell/2</seealso>.
</p></item>
<tag><c><![CDATA[{window_change, ssh_channel_id(), CharWidth() :: integer(),
RowHeight :: integer(), PixWidth :: integer(), PixHeight :: integer()}]]></c></tag>
<item><p>When the window (terminal) size changes on the client
side, it <em>can</em> send a message to the server side to inform it of
the new dimensions. No API function generates this event.</p></item>
<tag><c><![CDATA[{exec, ssh_channel_id(),
WantReply :: boolean(), Cmd :: string()}]]></c></tag>
<item><p>This message requests that the server starts
execution of the given command. This event is sent as a result of calling <seealso
marker="ssh_connection#exec-4">ssh_connection:exec/4 </seealso>.
</p></item>
</taglist>
</item>
</taglist>
</section>
<funcs>
<func>
<name>adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok</name>
<fsummary>Adjusts the SSH flow control window.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>NumOfBytes = integer()</v>
</type>
<desc>
<p>Adjusts the SSH flow control window. This is to be done by both the
client- and server-side channel processes.</p>
<note><p>Channels implemented with the <seealso marker="ssh_channel"> ssh_channel</seealso>
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 <seealso marker="ssh_channel#Module:handle_ssh_msg-2">
handle_ssh_msg/2</seealso> returns after processing channel data.</p></note>
</desc>
</func>
<func>
<name>close(ConnectionRef, ChannelId) -> ok</name>
<fsummary>Sends a close message on the channel <c>ChannelId</c>.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
</type>
<desc>
<p>A server- or client-channel process can choose to close their session by
sending a close event.
</p>
<note><p>This function is called by the <c>ssh_channel</c>
behavior when the channel is terminated, see <seealso
marker="ssh_channel"> ssh_channel(3)</seealso>. Thus, channels implemented
with the behavior are not to call this function explicitly.</p></note>
</desc>
</func>
<func>
<name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() |
{error, reason()}</name>
<fsummary>Requests that the server starts the execution of the given command.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>Command = string()</v>
<v>Timeout = timeout()</v>
</type>
<desc>
<p>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 <c>exec</c>
request is a one-time execution that closes the channel when it is done.</p>
<taglist>
<tag><c>N x {ssh_cm, ssh_connection_ref(),
{data, ssh_channel_id(), ssh_data_type_code(), Data :: binary()}}</c></tag>
<item><p>The result of executing the command can be only one line
or thousands of lines depending on the command.</p></item>
<tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
<item><p>Indicates that no more data is to be sent.</p></item>
<tag><c>0 or 1 x {ssh_cm,
ssh_connection_ref(), {exit_signal,
ssh_channel_id(), ExitSignal :: string(), ErrorMsg :: string(), LanguageString :: string()}}</c></tag>
<item><p>Not all systems send signals. For details on valid string
values, see RFC 4254, Section 6.10</p></item>
<tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status,
ssh_channel_id(), ExitStatus :: integer()}}</c></tag>
<item><p>It is recommended by the SSH Connection Protocol to send this
message, but that is not always the case.</p></item>
<tag><c>1 x {ssh_cm, ssh_connection_ref(),
{closed, ssh_channel_id()}}</c></tag>
<item><p>Indicates that the <c>ssh_channel</c> started for the
execution of the command has now been shut down.</p></item>
</taglist>
</desc>
</func>
<func>
<name>exit_status(ConnectionRef, ChannelId, Status) -> ok</name>
<fsummary>Sends the exit status of a command to the client.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref() </v>
<v>ChannelId = ssh_channel_id()</v>
<v>Status = integer()</v>
</type>
<desc>
<p>Is to be called by a server-channel process to send the exit status of a command
to the client.</p>
</desc>
</func>
<func>
<name>ptty_alloc(ConnectionRef, ChannelId, Options) -></name>
<name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() |
{error, reason()}</name>
<fsummary>Sends an SSH Connection Protocol <c>pty_req</c>,
to allocate a pseudo-terminal.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>Options = proplists:proplist()</v>
</type>
<desc>
<p>Sends an SSH Connection Protocol <c>pty_req</c>, to allocate a pseudo-terminal.
Is to be called by an SSH client process.</p>
<p>Options:</p>
<taglist>
<tag>{term, string()}</tag>
<item><p>Defaults to <em>os:getenv("TERM")</em> or <em>vt100</em>
if it is undefined.</p></item>
<tag>{width, integer()}</tag>
<item><p>Defaults to 80 if <c>pixel_width</c> is not defined.</p></item>
<tag>{height, integer()}</tag>
<item><p>Defaults to 24 if <c>pixel_height</c> is not defined.</p></item>
<tag>{pixel_width, integer()}</tag>
<item><p>Is disregarded if <c>width</c> is defined.</p></item>
<tag>{pixel_height, integer()}</tag>
<item><p>Is disregarded if <c>height</c> is defined.</p></item>
<tag>{pty_opts, [{posix_atom(), integer()}]}</tag>
<item><p>Option can be an empty list. Otherwise, see possible <em>POSIX</em> names
in Section 8 in <url href="http://www.ietf.org/rfc/rfc4254.txt"> RFC 4254</url>.</p>
</item>
</taglist>
</desc>
</func>
<func>
<name>reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok</name>
<fsummary>Sends status replies to requests that want such replies.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>WantReply = boolean()</v>
<v>Status = ssh_request_status()</v>
<v>ChannelId = ssh_channel_id()</v>
</type>
<desc>
<p>Sends status replies to requests where the requester has
stated that it wants a status report, that is, <c>WantReply = true</c>.
If <c>WantReply</c> is <c>false</c>, calling this function becomes a
"noop". Is to be called while handling an SSH Connection
Protocol message containing a <c>WantReply</c> boolean value.</p>
</desc>
</func>
<func>
<name>send(ConnectionRef, ChannelId, Data) -></name>
<name>send(ConnectionRef, ChannelId, Data, Timeout) -></name>
<name>send(ConnectionRef, ChannelId, Type, Data) -></name>
<name>send(ConnectionRef, ChannelId, Type, Data, TimeOut) ->
ok | {error, timeout} | {error, closed}</name>
<fsummary>Sends channel data.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>Data = binary()</v>
<v>Type = ssh_data_type_code()</v>
<v>Timeout = timeout()</v>
</type>
<desc>
<p>Is to be called by client- and server-channel processes to send data to each other.
</p>
</desc>
</func>
<func>
<name>send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}</name>
<fsummary>Sends EOF on channel <c>ChannelId</c>.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
</type>
<desc>
<p>Sends EOF on channel <c>ChannelId</c>.</p>
</desc>
</func>
<func>
<name>session_channel(ConnectionRef, Timeout) -></name>
<name>session_channel(ConnectionRef, InitialWindowSize,
MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()}</name>
<fsummary>Opens a channel for an SSH session.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>InitialWindowSize = integer()</v>
<v>MaxPacketSize = integer()</v>
<v>Timeout = timeout()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>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.</p>
</desc>
</func>
<func>
<name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() |
{error, reason()}</name>
<fsummary>Environment variables can be passed to the
shell/command to be started later.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>Var = string()</v>
<v>Value = string()</v>
<v>Timeout = timeout()</v>
</type>
<desc>
<p>Environment variables can be passed before starting the
shell/command. Is to be called by a client channel processes.</p>
</desc>
</func>
<func>
<name>shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed}
</name>
<fsummary>Requests that the user default shell (typically defined in
/etc/passwd in Unix systems) is to be executed at the server end.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
</type>
<desc>
<p>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.</p>
</desc>
</func>
<func>
<name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() |
{error, reason()}</name>
<fsummary>Requests to execute a predefined subsystem on the server.</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id()</v>
<v>Subsystem = string()</v>
<v>Timeout = timeout()</v>
</type>
<desc>
<p>Is to be called by a client-channel process for requesting to execute a predefined
subsystem on the server.
</p>
</desc>
</func>
</funcs>
</erlref>
