aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc/src/ssh_channel.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssh/doc/src/ssh_channel.xml')
-rw-r--r--lib/ssh/doc/src/ssh_channel.xml349
1 files changed, 125 insertions, 224 deletions
diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml
index c2b7aa94a5..f0083ae8d1 100644
--- a/lib/ssh/doc/src/ssh_channel.xml
+++ b/lib/ssh/doc/src/ssh_channel.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>2009</year>
- <year>2009</year>
+ <year>2012</year>
<holder>Ericsson AB, All Rights Reserved</holder>
</copyright>
<legalnotice>
@@ -22,31 +22,35 @@
The Initial Developer of the Original Code is Ericsson AB.
</legalnotice>
-
<title>ssh_channel</title>
- <prepared>Ingela Anderton Andin</prepared>
- <responsible></responsible>
- <docno></docno>
- <approved></approved>
- <checked></checked>
- <date></date>
- <rev></rev>
</header>
<module>ssh_channel</module>
- <modulesummary>Generic Ssh Channel Behavior
+ <modulesummary>-behaviour(ssh_channel).
</modulesummary>
<description>
- <p>Ssh services are implemented as channels that are multiplexed
- over an ssh connection and communicates via the ssh connection
- protocol. This module provides a callback API that takes care of
- generic channel aspects such as flow control and close messages
- and lets the callback functions take care of the service specific
- parts.
+ <p>SSH services (clients and servers) are implemented as channels
+ that are multiplexed over an SSH connection and communicates via
+ the <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH
+ Connection Protocol </url>. This module provides a callback API
+ that takes care of generic channel aspects such as flow control
+ and close messages and lets the callback functions take care of
+ the service (application) specific parts. This behavior also ensures
+ that the channel process honors the principal of an OTP-process so
+ that it can be part of a supervisor tree. This is a requirement of
+ channel processes implementing a subsystem that will be added to
+ the SSH applications supervisor tree.
</p>
+
+ <note> When implementing a SSH subsystem use the
+ <c>-behaviour(ssh_subsystem).</c> instead of <c>-behaviour(ssh_channel).</c>
+ as the only relevant callback functions for subsystems are
+ init/1, handle_ssh_msg/2, handle_msg/2 and terminate/2, so the ssh_subsystem
+ behaviour is limited version of the ssh_channel behaviour.
+ </note>
</description>
<section>
- <title>COMMON DATA TYPES </title>
+ <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
@@ -56,10 +60,10 @@
<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 process</c></p>
+ ssh:connect/3 or sent to an SSH channel process</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 <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254 </url> section 5.2.</c></p>
</section>
<funcs>
@@ -74,13 +78,15 @@
<v>Timeout = timeout() </v>
<v>Reply = term() </v>
<v>Reason = closed | timeout </v>
+
</type>
<desc>
<p>Makes a synchronous call to the channel process by sending
a message and waiting until a reply arrives or a timeout
- occurs. The channel will call
- <c>CallbackModule:handle_call/3</c> to handle the message.
- If the channel process does not exist <c>{error, closed}</c> is returned.
+ occurs. The channel will call <seealso mark =
+ "#Module:handle_call-3">Module:handle_call/3</seealso>
+ to handle the message. If the channel process does not exist
+ <c>{error, closed}</c> is returned.
</p>
</desc>
</func>
@@ -98,26 +104,27 @@
<p>Sends an asynchronous message to the channel process and
returns ok immediately, ignoring if the destination node or
channel process does not exist. The channel will call
- <c>CallbackModule:handle_cast/2</c> to handle the message.
+ <seealso mark = "#Module:handle_cast-3">Module:handle_cast/2</seealso>
+ to handle the message.
</p>
</desc>
</func>
<func>
<name>enter_loop(State) -> _ </name>
- <fsummary> Makes an existing process into a ssh_channel process. </fsummary>
+ <fsummary> Makes an existing process an ssh_channel process. </fsummary>
<type>
- <v> State = term() - as returned by ssh_channel:init/1</v>
+ <v> State = term() - as returned by <seealso mark = "#init-1">ssh_channel:init/1</seealso></v>
</type>
<desc>
- <p> Makes an existing process into a <c>ssh_channel</c>
+ <p> Makes an existing process an <c>ssh_channel</c>
process. Does not return, instead the calling process will
- enter the <c>ssh_channel</c> process receive loop and become a
+ enter the <c>ssh_channel</c> process receive loop and become an
<c>ssh_channel process.</c> The process must have been started using
one of the start functions in proc_lib, see <seealso
marker="stdlib:proc_lib">proc_lib(3)</seealso>. The
user is responsible for any initialization of the process
- and needs to call ssh_channel:init/1.
+ and needs to call <seealso mark = "#init-1">ssh_channel:init/1</seealso>
</p>
</desc>
</func>
@@ -126,7 +133,10 @@
<name>init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} </name>
<fsummary> Initiates a ssh_channel process.</fsummary>
<type>
- <v> Options = [{Option, Value}]</v>
+ <v>Options = [{Option, Value}]</v>
+ <v>State = term()</v>
+ <v>Timeout = timeout() </v>
+ <v>Reason = term() </v>
</type>
<desc>
<p>
@@ -134,24 +144,27 @@
</p>
<taglist>
<tag><c><![CDATA[{channel_cb, atom()}]]></c></tag>
- <item>The module that implements the channel behavior.</item>
+ <item>The module that implements the channel behaviour.</item>
<tag><c><![CDATA[{init_args(), list()}]]></c></tag>
- <item> The list of arguments to the callback modules
+ <item> The list of arguments to the callback module's
init function.</item>
<tag><c><![CDATA[{cm, connection_ref()}]]></c></tag>
- <item> Reference to the ssh connection.</item>
+ <item> Reference to the ssh connection as returned by <seealso
+ marker="ssh#connect-3">ssh:connect/3</seealso></item>
<tag><c><![CDATA[{channel_id, channel_id()}]]></c></tag>
<item> Id of the ssh channel.</item>
</taglist>
- <note><p>This function is normally not called by the user, it is
- only needed if for some reason the channel process needs
- to be started with help of <c>proc_lib</c> instead calling
- <c>ssh_channel:start/4</c> or <c>ssh_channel:start_link/4</c> </p>
+ <note><p>This function is normally not called by the
+ user. The user only needs to call if for some reason the
+ channel process needs to be started with help of
+ <c>proc_lib</c> instead of calling
+ <c>ssh_channel:start/4</c> or
+ <c>ssh_channel:start_link/4</c> </p>
</note>
</desc>
</func>
@@ -167,12 +180,12 @@
<p>This function can be used by a channel to explicitly send a
reply to a client that called <c>call/[2,3]</c> when the reply
cannot be defined in the return value of
- <c>CallbackModule:handle_call/3</c>.</p>
+ <seealso marker ="#Module:handle_call-3">Module:handle_call/3</seealso>.</p>
<p><c>Client</c> must be the <c>From</c> argument provided to
the callback function <c>handle_call/3</c>.
<c>Reply</c> is an arbitrary term,
- which will be given back to the client as the return value of
- <c>ssh_channel:call/[2,3].</c></p>
+ which will be given back to the client as the return value of
+ <seealso marker="#call-2">ssh_channel:call/[2,3].</seealso>></p>
</desc>
</func>
@@ -180,11 +193,12 @@
<name>start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> </name>
<name>start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) ->
{ok, ChannelRef} | {error, Reason}</name>
- <fsummary> Starts a processes that handles a ssh channel. </fsummary>
+ <fsummary> Starts a processes that handles a SSH channel. </fsummary>
<type>
<v>SshConnection = ssh_connection_ref()</v>
<v>ChannelId = ssh_channel_id() </v>
- <d> As returned by ssh_connection:session_channel/[2,4]</d>
+ <d> As returned by cannot be defined in the return value of
+ <seealso marker ="ssh_connection#session_channel/2">ssh_connection:session_channel/[2,4]</seealso></d>
<v>ChannelCb = atom()</v>
<d> The name of the module implementing the service specific parts
of the channel.</d>
@@ -193,10 +207,10 @@
<v>ChannelRef = pid()</v>
</type>
<desc>
- <p>Starts a processes that handles a ssh channel. Will be
- called internally by the ssh daemon or explicitly by the ssh
- client implementations. A channel process traps exit signals
- by default.
+ <p>Starts a processes that handles an SSH channel. It will be
+ called internally by the SSH daemon or explicitly by the SSH
+ client implementations. The behavior will set the
+ <c>trap_exit</c> flag to true.
</p>
</desc>
</func>
@@ -204,72 +218,61 @@
</funcs>
<section>
- <title>CALLBACK FUNCTIONS</title>
-
- <p>The functions init/1, terminate/2, handle_ssh_msg/2 and
- handle_msg/2 are the functions that are required to provide the
- implementation for a server side channel, such as a ssh subsystem
- channel that can be plugged into the erlang ssh daemon see
- <seealso marker="ssh">ssh:daemon/[2, 3]</seealso>. The
- handle_call/3, handle_cast/2 code_change/3 and enter_loop/1
- functions are only relevant when implementing a client side
- channel.</p>
- </section>
-
- <section>
<marker id="cb_timeouts"></marker>
<title> CALLBACK TIMEOUTS</title>
- <p> If an integer timeout value is provided in a return value of
- one of the callback functions, a timeout will occur unless a
- message is received within <c>Timeout</c> milliseconds. A timeout
- is represented by the atom <c>timeout</c> which should be handled
- by the <seealso marker="#handle_msg">handle_msg/2</seealso>
- callback function. The atom infinity can be used to wait
- indefinitely, this is the default value. </p>
+
+ <p>The timeout values that may be returned by the callback functions
+ has the same semantics as in a <seealso marker="stdlib#gen_server">gen_server</seealso>
+ If the timeout occurs <seealso marker="#handle_msg">handle_msg/2</seealso>
+ will be called as <c>handle_msg(timeout, State). </c></p>
</section>
<funcs>
<func>
- <name>CallbackModule:code_change(OldVsn, State, Extra) -> {ok,
+ <name>Module:code_change(OldVsn, State, Extra) -> {ok,
NewState}</name>
<fsummary> Converts process state when code is changed.</fsummary>
<type>
- <v> Converts process state when code is changed.</v>
+ <v>OldVsn = term()</v>
+ <d>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
+ in the case of a downgrade, <c>OldVsn</c> is
+ <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
+ attribute(s) of the old version of the callback module
+ <c>Module</c>. If no such attribute is defined, the version is
+ the checksum of the BEAM file.</d>
+ <v>State = term()</v>
+ <d>The internal state of the channel.</d>
+ <v>Extra = term()</v>
+ <d>Passed as-is from the <c>{advanced,Extra}</c>
+ part of the update instruction.</d>
</type>
<desc>
- <p>This function is called by a client side channel when it
- should update its internal state during a release
- upgrade/downgrade, i.e. when the instruction
- <c>{update,Module,Change,...}</c> where
- <c>Change={advanced,Extra}</c> is given in the <c>appup</c>
- file. See <seealso
- marker="doc/design_principles:release_handling#instr">OTP
- Design Principles</seealso> for more information. Any new
- connection will benefit from a server side upgrade but
- already started connections on the server side will not be
- affected.
- </p>
+ <p> Converts process state when code is changed.</p>
+
+ <p>This function is called by a client side channel when it
+ should update its internal state during a release
+ upgrade/downgrade, i.e. when the instruction
+ <c>{update,Module,Change,...}</c> where
+ <c>Change={advanced,Extra}</c> is given in the <c>appup</c>
+ file. See <seealso marker="doc/design_principles:release_handling#instr">OTP
+ Design Principles</seealso> for more information.
+ </p>
- <note><p>If there are long lived ssh connections and more
- than one upgrade in a short time this may cause the old
- connections to fail as only two versions of the code may
- be loaded simultaneously.</p></note>
+ <note><p>Soft upgrade according to the OTP release concept
+ is not straight forward for the server side, as subsystem
+ channel processes are spawned by the SSH application and
+ hence added to its supervisor tree. It could be possible to
+ upgrade the subsystem channels, when upgrading the user
+ application, if the callback functions can handle two
+ versions of the state, but this function can not be used in
+ the normal way.</p>
+ </note>
- <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
- in the case of a downgrade, <c>OldVsn</c> is
- <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
- attribute(s) of the old version of the callback module
- <c>Module</c>. If no such attribute is defined, the version
- is the checksum of the BEAM file.</p>
- <p><c>State</c> is the internal state of the channel.</p>
- <p><c>Extra</c> is passed as-is from the <c>{advanced,Extra}</c>
- part of the update instruction.</p>
- <p>The function should return the updated internal state.</p>
</desc>
</func>
<func>
- <name>CallbackModule:init(Args) -> {ok, State} | {ok, State, Timeout} |
+ <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} |
{stop, Reason}</name>
<fsummary> Makes necessary initializations and returns the
initial channel state if the initializations succeed.</fsummary>
@@ -277,7 +280,6 @@
<v> Args = term() </v>
<d> Last argument to ssh_channel:start_link/4.</d>
<v> State = term() </v>
- <v>Timeout = timeout() </v>
<v> Reason = term() </v>
</type>
<desc>
@@ -290,7 +292,7 @@
</func>
<func>
- <name>CallbackModule:handle_call(Msg, From, State) -> Result</name>
+ <name>Module:handle_call(Msg, From, State) -> Result</name>
<fsummary> Handles messages sent by calling
<c>ssh_channel:call/[2,3]</c></fsummary>
<type>
@@ -298,17 +300,16 @@
<v>From = opaque to the user should be used as argument to
ssh_channel:reply/2</v>
<v>State = term()</v>
- <v>Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout}
- | {noreply, NewState} | {noreply , NewState, Timeout}
+ <v>Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()}
+ | {noreply, NewState} | {noreply , NewState, timeout()}
| {stop, Reason, Reply, NewState} | {stop, Reason, NewState} </v>
<v>Reply = term() - will be the return value of ssh_channel:call/[2,3]</v>
- <v>Timeout = timeout() </v>
- <v>NewState = term() - a possible updated version of State</v>
+ <v>NewState = term()</v>
<v>Reason = term()</v>
</type>
<desc>
<p>Handles messages sent by calling
- <c>ssh_channel:call/[2,3]</c>
+ <seealso marker="#call-2">ssh_channel:call/[2,3]</seealso>
</p>
<p>For more detailed information on timeouts see the section
<seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
@@ -316,16 +317,15 @@
</func>
<func>
- <name>CallbackModule:handle_cast(Msg, State) -> Result</name>
+ <name>Module:handle_cast(Msg, State) -> Result</name>
<fsummary> Handles messages sent by calling
<c>ssh_channel:cact/2</c></fsummary>
<type>
<v>Msg = term()</v>
<v>State = term()</v>
- <v>Result = {noreply, NewState} | {noreply, NewState, Timeout}
+ <v>Result = {noreply, NewState} | {noreply, NewState, timeout()}
| {stop, Reason, NewState}</v>
- <v>NewState = term() - a possible updated version of State</v>
- <v>Timeout = timeout() </v>
+ <v>NewState = term() </v>
<v>Reason = term()</v>
</type>
<desc>
@@ -339,7 +339,7 @@
</func>
<func>
- <name>CallbackModule:handle_msg(Msg, State) -> {ok, State} |
+ <name>Module:handle_msg(Msg, State) -> {ok, State} |
{stop, ChannelId, State}</name>
<fsummary> Handle other messages than ssh connection protocol,
@@ -359,136 +359,37 @@
<taglist>
<tag><c><![CDATA[{ssh_channel_up, ssh_channel_id(),
ssh_connection_ref()}]]></c></tag>
- <item>This is the first messages that will be received
- by the channel, it is sent just before
- the ssh_channel:init/1 function returns successfully.
- This is especially useful if the server wants
- to send a message to the client without first receiving
- a message from the client. If the message is not useful
- for your particular problem just ignore it by immediately
- returning {ok, State}.
+ <item>This is the first messages that will be received by
+ the channel, it is sent just before the <seealso
+ marker="#init-2">ssh_channel:init/1</seealso> function
+ returns successfully. This is especially useful if the
+ server wants to send a message to the client without first
+ receiving a message from it. If the message is not
+ useful for your particular scenario just ignore it by
+ immediately returning {ok, State}.
</item>
</taglist>
</desc>
</func>
<func>
- <name>CallbackModule:handle_ssh_msg(Msg, State) -> {ok, State} | {stop,
+ <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop,
ssh_channel_id(), State}</name>
<fsummary> Handles ssh connection protocol messages. </fsummary>
<type>
- <v>Msg = {ssh_cm, ssh_connection_ref(), SshMsg}</v>
- <v> SshMsg = tuple() - see message list below</v>
+ <v>Msg = <seealso marker="ssh_connection"> ssh_connection:event() </seealso> </v>
<v>State = term()</v>
</type>
<desc>
<p> Handles ssh connection protocol messages that may need
service specific attention.
</p>
-
- <p> All channels should handle the following messages. For
- channels implementing subsystems the handle_ssh_msg-callback
- will not be called for any other messages. </p>
-
- <taglist>
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
- ssh_data_type_code(), binary() = Data}}]]></c></tag>
- <item> Data has arrived on the channel. When the callback
- for this message returns the channel behavior will adjust
- the ssh flow control window.</item>
-
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {eof,
- ssh_channel_id()}}]]></c></tag>
- <item>Indicteas that the other side will not send any more
- data.</item>
-
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {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
- may not implement signals, in which case they should ignore
- this message.</item>
-
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(),
- {exit_signal, ssh_channel_id(), string() = exit_signal,
- 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 RFC 4254 section 6.10</item>
-
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {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.</item>
- </taglist>
-
- <p> Channels implementing a shell and command execution on the server side
- should also handle the following messages. </p>
-
- <taglist>
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {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. Note that before the
- callback returns it should call the function
- ssh_connection:reply_request/4 with the boolean value of <c>
- WantReply</c> as the second argument.
- </item>
-
- <tag><c><![CDATA[{ssh_cm, ConnectionRef, {exec, ssh_channel_id(),
- boolean() = WantReply, string() = Cmd}}]]></c></tag>
- <item> This message will request that the server start the
- execution of the given command. Note that before the
- callback returns it should call the function
- ssh_connection:reply_request/4 with the boolean value of <c>
- WantReply</c> as the second argument.</item>
-
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {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 RFC 4254 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>. Note that before the callback returns it should
- call the function ssh_connection:reply_request/4 with the
- boolean value of <c> WantReply</c> as the second
- argument.</item>
-
- <tag><c><![CDATA[{ssh_cm, ConnectionRef, {shell, boolean() =
- WantReply}}]]></c></tag>
- <item> This message will request that the user's default
- shell be started at the other end. Note that before the
- callback returns it should call the function
- ssh_connection:reply_request/4 with the value of <c>
- WantReply</c> as the second argument.
- </item>
-
- <tag><c><![CDATA[ {ssh_cm, ssh_connection_ref(), {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 other side to inform it
- of the new dimensions.</item>
- </taglist>
<p> The following message is completely taken care of by the
ssh channel behavior</p>
<taglist>
- <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {closed,
- ssh_channel_id()}}]]></c></tag>
+ <tag><c><![CDATA[{closed, ssh_channel_id()}]]></c></tag>
<item> The channel behavior will send a close message to the
other side if such a message has not already been sent and
then terminate the channel with reason normal.</item>
@@ -497,7 +398,7 @@
</func>
<func>
- <name>CallbackModule:terminate(Reason, State) -> _</name>
+ <name>Module:terminate(Reason, State) -> _</name>
<fsummary> </fsummary>
<type>
<v>Reason = term()</v>
@@ -505,12 +406,12 @@
</type>
<desc>
<p>This function is called by a channel process when it is
- about to terminate. Before this function is called ssh_connection:close/2
- will be called if it has not been called earlier.
- This function should be the opposite of <c>CallbackModule:init/1</c>
- and do any necessary cleaning up. When it returns, the
- channel process terminates with reason <c>Reason</c>. The return value is
- ignored.
+ about to terminate. Before this function is called <seealso
+ marker="ssh_connection#close-2"> ssh_connection:close/2
+ </seealso> will be called if it has not been called earlier.
+ This function should do any necessary cleaning
+ up. When it returns, the channel process terminates with
+ reason <c>Reason</c>. The return value is ignored.
</p>
</desc>
</func>