aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc/src/ssh_connection.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssh/doc/src/ssh_connection.xml')
-rw-r--r--lib/ssh/doc/src/ssh_connection.xml256
1 files changed, 177 insertions, 79 deletions
diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
index a9ae13d556..c66622307f 100644
--- a/lib/ssh/doc/src/ssh_connection.xml
+++ b/lib/ssh/doc/src/ssh_connection.xml
@@ -1,11 +1,11 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2008</year>
- <year>2011</year>
+ <year>2012</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
@@ -24,69 +24,178 @@
</legalnotice>
<title>ssh_connection</title>
- <prepared>Ingela Anderton Andin</prepared>
- <responsible></responsible>
- <docno></docno>
- <approved></approved>
- <checked></checked>
<date></date>
- <rev></rev>
</header>
<module>ssh_connection</module>
- <modulesummary>This module provides an API to the ssh connection protocol.
+ <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>This module provides an API to the ssh connection protocol.
- Not all features of the connection protocol are officially supported yet.
- Only the ones supported are documented here.</p>
+ <p>The SSH Connection Protocol is used by clients and servers
+ (i.e. SSH channels) to communicate over the SSH connection. The
+ API functions in this module sends SSH Connection Protocol events
+ that are received as messages by the remote channel.
+ In the case that the receiving channel is an Erlang process the
+ message will be on the following 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 will be handled by
+ <seealso
+ marker="ssh_channel#CallbackModule:handled_ssh_msg-2">handle_ssh_msg/2 </seealso>.</p>
</description>
- <section>
- <title>COMMON DATA TYPES </title>
+ <section>
+ <title>DATA TYPES </title>
+
<p>Type definitions that are used more than once in this module and/or
abstractions to indicate the intended use of the data type:</p>
-
+
<p><c>boolean() = true | false </c></p>
<p><c>string() = list of ASCII characters</c></p>
<p><c>timeout() = infinity | integer() - in milliseconds.</c></p>
<p><c>ssh_connection_ref() - opaque to the user returned by
- ssh:connect/3 or sent to a ssh channel processes</c></p>
+ ssh:connect/3 or sent to an SSH channel processes</c></p>
<p><c>ssh_channel_id() = integer() </c></p>
<p><c>ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are
- currently valid values see RFC 4254 section 5.2.</c></p>
+ currently valid values see</c> <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254 </url> section 5.2.</p>
<p><c>ssh_request_status() = success | failure</c></p>
- </section>
+ <p><c>event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()} </c></p>
+ <p><c>ssh_event_msg() = data_events() | status_events() | terminal_events() </c></p>
+
+ <taglist>
+ <tag><b>data_events()</b></tag>
+ <item>
+ <taglist>
+ <tag><c><![CDATA[{data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}]]></c></tag>
+ <item> Data has arrived on the channel. This event is sent as
+ result of calling <seealso marker="#send-3"> ssh_connection:send/[3,4,5] </seealso></item>
+
+ <tag><c><![CDATA[{eof, ssh_channel_id()}]]></c></tag>
+ <item>Indicates that the other side will not send any more
+ data. This event is sent as result of calling <seealso
+ marker="#send_eof-2"> ssh_connection:send_eof/2</seealso>
+ </item>
+ </taglist>
+ </item>
+
+ <tag><b>status_events()</b></tag>
+ <item>
+
+ <taglist>
+ <tag><c><![CDATA[{signal, ssh_channel_id(), ssh_signal()}]]></c></tag>
+ <item>A signal can be delivered to the remote process/service
+ using the following message. Some systems will not support
+ signals, in which case they should ignore this message. There is
+ currently no funtion to generate this event as the signals
+ refered to are on OS-level and not something generated by an
+ Erlang program.</item>
+
+ <tag><c><![CDATA[{exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg,
+ string() = LanguageString}]]></c></tag>
+
+ <item>A remote execution may terminate violently due to a signal
+ then this message may be received. For details on valid string
+ values see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> section 6.10. Special case of the signals
+ mentioned above.</item>
+
+ <tag><c><![CDATA[{exit_status, ssh_channel_id(), integer() = ExitStatus}]]></c></tag>
+ <item> 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 result of calling
+ <seealso marker="#exit_status">
+ ssh_connection:exit_status/3</seealso></item>
+
+ <tag><c><![CDATA[{closed, ssh_channel_id()}]]></c></tag>
+ <item> This event is sent as result of calling
+ <seealso marker="#close">ssh_connection:close/2</seealso> Both the handling of this
+ event and sending of it will be taken care of by the
+ <seealso marker="ssh_channel">ssh_channel</seealso> behavior.</item>
+
+ </taglist>
+ </item>
- <section>
- <title>MESSAGES SENT TO CHANNEL PROCESSES</title>
+ <tag><b>terminal_events()</b></tag>
+
+ <item>
+ <p> Channels implementing a shell and command execution on the
+ server side should handle the following messages that may be sent by client channel processes. </p>
+
+ <p><note>Events that includes a <c> WantReply</c> expects the event handling
+ process to call <seealso marker="#reply_request">ssh_connection:reply_request/4</seealso>
+ with the boolean value of <c> WantReply</c> as the second
+ argument. </note> </p>
+
+ <taglist>
+ <tag><c><![CDATA[{env, ssh_channel_id(), boolean() = WantReply,
+ string() = Var, string() = Value}]]></c></tag>
+ <item> Environment variables may be passed to the shell/command
+ to be started later. This event is sent as result of calling <seealso
+ marker="#setenv"> ssh_connection:setenv/5</seealso>
+ </item>
+
+ <tag><c><![CDATA[{pty, ssh_channel_id(),
+ boolean() = WantReply, {string() = Terminal, integer() = CharWidth,
+ integer() = RowHeight, integer() = PixelWidth, integer() = PixelHight,
+ [{atom() | integer() = Opcode,
+ integer() = Value}] = TerminalModes}}]]></c></tag>
+ <item>A pseudo-terminal has been requested for the
+ session. Terminal is the value of the TERM environment
+ variable value (e.g., vt100). Zero dimension parameters must
+ be ignored. The character/row dimensions override the pixel
+ dimensions (when nonzero). Pixel dimensions refer to the
+ drawable area of the window. The <c>Opcode</c> in the
+ <c>TerminalModes</c> list is the mnemonic name, represented
+ as an lowercase erlang atom, defined in
+ <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254 </url> section 8,
+ or the opcode if the mnemonic name is not listed in the
+ RFC. Example <c>OP code: 53, mnemonic name ECHO erlang atom:
+ echo</c>. There is currently no API function to generate this
+ event.</item>
+
+ <tag><c><![CDATA[{shell, boolean() = WantReply}]]></c></tag>
+ <item> This message will request that the user's default shell
+ be started at the other end. This event is sent as result of calling <seealso
+ marker="#shell"> ssh_connection:shell/2</seealso>
+ </item>
+
+ <tag><c><![CDATA[{window_change, ssh_channel_id(), integer() = CharWidth,
+ integer() = RowHeight, integer() = PixWidth, integer() = PixHeight}]]></c></tag>
+ <item> When the window (terminal) size changes on the client
+ side, it MAY send a message to the server side to inform it of
+ the new dimensions. There is currently no API function to generate this
+ event.</item>
- <p>As a result of the ssh connection protocol messages on the form
- <c><![CDATA[{ssh_cm, ssh_connection_ref(), term()}]]></c>
- will be sent to a channel process. The term will contain
- information regarding the ssh connection protocol event,
- for details see the ssh channel behavior callback <seealso
- marker="ssh_channel">handle_ssh_msg/2 </seealso> </p>
- </section>
-
- <funcs>
+ <tag><c><![CDATA[{exec, ssh_channel_id(),
+ boolean() = WantReply, string() = Cmd}]]></c></tag>
+ <item> This message will request that the server starts
+ execution of the given command. This event is sent as result of calling <seealso
+ marker="#exec">ssh_connection:exec/4 </seealso>
+ </item>
+ </taglist>
+ </item>
+ </taglist>
+ </section>
+
+ <funcs>
<func>
<name>adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok</name>
- <fsummary>Adjusts the ssh flowcontrol window. </fsummary>
+ <fsummary>Adjusts the SSH flowcontrol 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 flowcontrol window. </p>
+ <p>Adjusts the SSH flowcontrol window. This shall be done by both client and server side channel processes.</p>
- <note><p>This will be taken care of by the ssh_channel
- behavior when the callback <seealso marker="ssh_channel">
- handle_ssh_msg/2 </seealso> has returned after processing a
- {ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
- ssh_data_type_code(), binary()}}
- message, and should normally not be called explicitly.</p></note>
+ <note><p>Channels implemented with the <seealso marker="ssh_channel"> ssh_channel
+ behavior</seealso> will normaly not need to call this function as flow control
+ will be handled by the behavior. The behavior will adjust the window every time
+ the callback <seealso marker="ssh_channel#handled_ssh_msg-2">
+ handle_ssh_msg/2 </seealso> has returned after processing channel data</p> </note>
</desc>
</func>
@@ -98,20 +207,19 @@
<v> ChannelId = ssh_channel_id()</v>
</type>
<desc>
- <p>Sends a close message on the channel <c>ChannelId</c>
+ <p>A server or client channel process can choose to close their session by sending a close event.
</p>
- <note><p>This function will be called by the ssh channel
+ <note><p>This function will be called by the ssh_channel
behavior when the channel is terminated see <seealso
- marker="ssh_channel"> ssh_channel(3) </seealso> and should
- normally not be called explicitly.</p></note>
+ marker="ssh_channel"> ssh_channel(3) </seealso> so channels implemented with the
+ behavior should not call this function explicitly.</p></note>
</desc>
</func>
<func>
<name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() </name>
- <fsummary>Will request that the server start the
- execution of the given command. </fsummary>
+ <fsummary>Request that the server start the execution of the given command. </fsummary>
<type>
<v> ConnectionRef = ssh_connection_ref() </v>
<v> ChannelId = ssh_channel_id()</v>
@@ -119,44 +227,39 @@
<v>Timeout = timeout() </v>
</type>
<desc>
- <p>Will request that the server start the execution of the
- given command, the result will be received as:</p>
+ <p>Should be called by a client channel process to request that the server starts execution of the
+ given command, the result will be several messages according to the following pattern. Note
+ that the last message will be a channel close message, as the exec 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(),
- binary() = Data}} </c></tag>
+ <tag><c> N x {ssh_cm, ssh_connection_ref(),
+ {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} </c></tag>
<item>The result of executing the command may be only one line
or thousands of lines depending on the command.</item>
- <tag><c> 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
+ <tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
<item>Indicates that no more data will be sent.</item>
- <tag><c>0 or 1 X {ssh_cm,
+ <tag><c>0 or 1 x {ssh_cm,
ssh_connection_ref(), {exit_signal,
ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}</c></tag>
<item>Not all systems send signals. For details on valid string
values see RFC 4254 section 6.10 </item>
- <tag><c>0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status,
+ <tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status,
ssh_channel_id(), integer() = ExitStatus}}</c></tag>
<item>It is recommended by the <c>ssh connection protocol</c> that this
message shall be sent, but that may not always be the case.</item>
- <tag><c> 1 X {ssh_cm, ssh_connection_ref(),
+ <tag><c> 1 x {ssh_cm, ssh_connection_ref(),
{closed, ssh_channel_id()}}</c></tag>
<item>Indicates that the ssh channel started for the
execution of the command has now been shutdown.</item>
</taglist>
-
- <p> These message should be handled by the
- client. The <seealso marker="ssh_channel">ssh channel
- behavior</seealso> can be used when writing a client.
- </p>
</desc>
</func>
-
<func>
<name>exit_status(ConnectionRef, ChannelId, Status) -> ok</name>
<fsummary>Sends the exit status of a command to the client.</fsummary>
@@ -166,12 +269,12 @@
<v> Status = integer()</v>
</type>
<desc>
- <p>Sends the exit status of a command to the client.</p>
+ <p>Should be called by a server channel process to sends the exit status of a command to the client.</p>
</desc>
- </func>
+ </func>
<func>
- <name>reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok</name>
+ <name>reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok</name>
<fsummary>Send status replies to requests that want such replies. </fsummary>
<type>
<v> ConnectionRef = ssh_connection_ref() </v>
@@ -183,10 +286,9 @@
<p>Sends status replies to requests where the requester has
stated that they want a status report e.i .<c> WantReply = true</c>,
if <c> WantReply</c> is false calling this function will be a
- "noop". Should be called after handling an ssh connection
+ "noop". Should be called while handling an ssh connection
protocol message containing a <c>WantReply</c> boolean
- value. See the ssh_channel behavior callback <seealso
- marker="ssh_channel"> handle_ssh_msg/2 </seealso>
+ value.
</p>
</desc>
</func>
@@ -206,7 +308,7 @@
<v> Timeout = timeout()</v>
</type>
<desc>
- <p>Sends channel data.
+ <p>Should be called by client- and server channel processes to send data to each other.
</p>
</desc>
</func>
@@ -228,9 +330,7 @@
<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 a ssh session. A session is a
- remote execution of a program. The program may be a shell, an
- application, a system command, or some built-in subsystem. </fsummary>
+ <fsummary>Opens a channel for a ssh session. </fsummary>
<type>
<v> ConnectionRef = ssh_connection_ref()</v>
<v> InitialWindowSize = integer() </v>
@@ -239,9 +339,8 @@
<v> Reason = term() </v>
</type>
<desc>
- <p>Opens a channel for a ssh session. A session is a
- remote execution of a program. The program may be a shell, an
- application, a system command, or some built-in subsystem.
+ <p>Opens a channel for an SSH session. The channel id returned from this function
+ is the id used as input to the other funtions in this module.
</p>
</desc>
</func>
@@ -258,8 +357,8 @@
<v> Timeout = timeout()</v>
</type>
<desc>
- <p> Environment variables may be passed to the shell/command to be
- started later.
+ <p> Environment variables may be passed before starting the
+ shell/command. Should be called by a client channel processes.
</p>
</desc>
</func>
@@ -267,17 +366,16 @@
<func>
<name>shell(ConnectionRef, ChannelId) -> ssh_request_status()
</name>
- <fsummary> Will request that the user's default shell (typically
- defined in /etc/passwd in UNIX systems) be started at the other
+ <fsummary> Requests that the user's default shell (typically
+ defined in /etc/passwd in UNIX systems) shall be executed at the server
end. </fsummary>
<type>
<v> ConnectionRef = ssh_connection_ref() </v>
<v> ChannelId = ssh_channel_id()</v>
</type>
<desc>
- <p> Will request that the user's default shell (typically
- defined in /etc/passwd in UNIX systems) be started at the
- other end.
+ <p> Should be called by a client channel process to request that the user's default shell (typically
+ defined in /etc/passwd in UNIX systems) shall be executed at the server end.
</p>
</desc>
</func>
@@ -292,7 +390,7 @@
<v> Timeout = timeout()</v>
</type>
<desc>
- <p> Sends a request to execute a predefined subsystem.
+ <p> Should be called by a client channel process for requesting to execute a predefined subsystem on the server.
</p>
</desc>
</func>