ssh: Add Users Guide and enhance man pages

1 files changed, 98 insertions, 202 deletions

diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml
index c2b7aa94a5..342de97a1b 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,38 @@
 
       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>
   <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>
+
+    <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
+    an SSH subsystem channel that can be plugged into the Erlang ssh
+    daemon see <seealso marker="ssh#daemon-3">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>
   </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,31 +63,31 @@
     <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>
     <func>
       <name>call(ChannelRef, Msg) -></name>
-      <name>call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}</name>
+      <name>call(ChannelRef, Msg, timeout()) -> Reply | {error, Reason}</name>
       <fsummary> Makes a synchronous call to a channel.</fsummary>
       <type>
 	<v>ChannelRef = pid() </v>
 	<d>As returned by start_link/4 </d>
 	<v>Msg = term() </v>
-	<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 =
+	"#CallbackModule:handle_call-3">CallbackModule: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,32 +105,33 @@
 	<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 = "#CallbackModule:handle_cast-3">CallbackModule: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>
     
     <func>
-      <name>init(Options) -> {ok, State} |  {ok, State, Timeout} | {stop, Reason} </name>
+      <name>init(Options) -> {ok, State} |  {ok, State, timeout()} | {stop, Reason} </name>
       <fsummary> Initiates a ssh_channel process.</fsummary>
       <type>
 	<v> Options = [{Option, Value}]</v>
@@ -134,24 +142,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 +178,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 ="#CallbackModule:handle_call-3">CallbackModule: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 +191,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 +205,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,28 +216,13 @@
   </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 timout occurs <seealso marker="#handle_msg">handle_msg/2</seealso>
+    will be called as <c>handle_msg(timeout, State). </c></p>
   </section>
 
   <funcs>
@@ -242,18 +239,19 @@
 	  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.
+	  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
@@ -269,7 +267,7 @@
     </func>
     
     <func>
-      <name>CallbackModule:init(Args) -> {ok, State} | {ok, State, Timeout} |
+      <name>CallbackModule: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 +275,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>
@@ -298,17 +295,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>
@@ -322,10 +318,9 @@
       <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>
@@ -359,14 +354,14 @@
 	<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>
@@ -377,118 +372,19 @@
       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>
@@ -505,12 +401,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>