ssh: Add Users Guide and enhance man pages

22 files changed, 1040 insertions, 581 deletions

diff --git a/lib/ssh/doc/man6/.gitignore b/lib/ssh/doc/man6/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/ssh/doc/man6/.gitignore
diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile
index bf65a2a60c..fc9600f6cd 100644
--- a/lib/ssh/doc/src/Makefile
+++ b/lib/ssh/doc/src/Makefile
@@ -44,14 +44,18 @@ XML_REF3_FILES = \
 	ssh_sftp.xml \
 	ssh_sftpd.xml \
 
+XML_REF6_FILES = ssh_app.xml
+
 XML_PART_FILES = part_notes.xml \
-	part.xml
+		 usersguide.xml
 XML_CHAPTER_FILES = notes.xml \
-	ssh_ug.xml
+	introduction.xml \
+	ssh_protocol.xml \
+	using_ssh.xml
 
 BOOK_FILES = book.xml
 
-XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \
+XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES)  $(XML_REF6_FILES)\
             $(XML_PART_FILES) $(XML_CHAPTER_FILES) 
 
 IMAGE_FILES = SSH_protocols.png
@@ -66,10 +70,12 @@ EXTRA_FILES = \
 	$(DEFAULT_GIF_FILES) \
 	$(DEFAULT_HTML_FILES) \
 	$(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \
+        $(XML_REF6_FILES:%.xml=$(HTMLDIR)/%.html) \
 	$(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html)
 
 
 MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6)
 
 HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
 
@@ -104,7 +110,7 @@ clean clean_docs:
 	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
 	rm -f errs core *~
 
-man: $(MAN3_FILES)
+man: $(MAN3_FILES) $(MAN6_FILES)
 
 
 debug opt: 
@@ -124,5 +130,8 @@ release_docs_spec: docs
 	$(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)"
 	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man3"
 	$(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3"
+	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man6"
+	$(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6"
+
 
 release_spec:
diff --git a/lib/ssh/doc/src/book.xml b/lib/ssh/doc/src/book.xml
index d33d9faf15..3c2375f96d 100644
--- a/lib/ssh/doc/src/book.xml
+++ b/lib/ssh/doc/src/book.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE book SYSTEM "book.dtd">
 
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
   <header titlestyle="normal">
     <copyright>
-      <year>2005</year><year>2010</year>
+      <year>2005</year><year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -34,8 +34,8 @@
   <preamble>
     <contents level="2"></contents>
   </preamble>
-  <parts>
-    <xi:include href="part.xml"/>
+  <parts lift="yes">
+    <xi:include href="usersguide.xml"/>
   </parts>
   <applications>
     <xi:include href="ref_man.xml"/>
diff --git a/lib/ssh/doc/src/fascicules.xml b/lib/ssh/doc/src/fascicules.xml
index 43090b4aed..069d9002e0 100644
--- a/lib/ssh/doc/src/fascicules.xml
+++ b/lib/ssh/doc/src/fascicules.xml
@@ -1,7 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE fascicules SYSTEM "fascicules.dtd">
 
 <fascicules>
+  <fascicule file="usersguide" href="usersguide_frame.html" entry="no">
+    User's Guide
+  </fascicule>
   <fascicule file="ref_man" href="ref_man_frame.html" entry="yes">
     Reference Manual
   </fascicule>
diff --git a/lib/ssh/doc/src/introduction.xml b/lib/ssh/doc/src/introduction.xml
new file mode 100644
index 0000000000..837644330f
--- /dev/null
+++ b/lib/ssh/doc/src/introduction.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2012</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>Introduction</title>
+    <prepared>OTP team</prepared>
+    <file>introduction.xml</file>
+  </header>
+
+  <section>
+    <title>Purpose</title>
+
+    <p>Secure Shell (SSH) is a protocol for secure remote login and
+    other secure network services over an insecure network. SSH
+    provides a single, full-duplex, byte-oriented connection between
+    client and server. The protocol also provides privacy, integrity,
+    server authentication and man-in-the-middle protection.</p>
+
+    <p>The Erlang SSH application is an implementation of the SSH
+    protocol in Erlang which offers API functions to write customized
+    SSH clients and servers as well as making the Erlang shell
+    available via SSH. Also included in the SSH application are an
+    SFTP (Secret File Transfer Protocol) client <seealso
+    marker="ssh_sftp">ssh_sftp</seealso> and server <seealso
+    marker="ssh_sftp">ssh_sftpd</seealso>.</p>
+  </section>
+
+  <section>
+    <title>Prerequisites</title>
+    <p>It is assumed that the reader is familiar with the concepts of <seealso marker="doc/design_principals:users_guide">OTP</seealso>
+    and has a basic understanding of <url href="http://en.wikipedia.org/wiki/Public-key_cryptography">public keys</url>.</p>
+  </section>
+
+</chapter>
diff --git a/lib/ssh/doc/src/make.dep b/lib/ssh/doc/src/make.dep
deleted file mode 100644
index 9be373481a..0000000000
--- a/lib/ssh/doc/src/make.dep
+++ /dev/null
@@ -1,19 +0,0 @@
-# ----------------------------------------------------
-# >>>> Do not edit this file <<<<
-# This file was automaticly generated by
-# /home/otp/bin/docdepend
-# ----------------------------------------------------
-
-
-# ----------------------------------------------------
-# TeX files that the DVI file depend on
-# ----------------------------------------------------
-
-book.dvi: book.tex ref_man.tex ssh_ug.tex ssh.tex ssh_channel.tex \
-                ssh_connection.tex ssh_sftp.tex ssh_sftpd.tex
-
-# ----------------------------------------------------
-# Source inlined when transforming from source to LaTeX
-# ----------------------------------------------------
-
-book.tex: ref_man.xml
diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml
index d4acb2ef1a..e58d4e2c36 100644
--- a/lib/ssh/doc/src/notes.xml
+++ b/lib/ssh/doc/src/notes.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE chapter SYSTEM "chapter.dtd">
 
 <chapter>
@@ -780,7 +780,7 @@
       <list>
         <item>
           <p>
-            Ssh timeouts will now behave as expected e.i. defaults to
+            Ssh timeouts will now behave as expected i.e. defaults to
             infinity only the user of the ssh application can know of
             a reasonable timeout value for their application.</p>
           <p>
@@ -833,7 +833,7 @@
 	caused the ssh daemon to close the connections to all
 	currently logged in users if one user logged out. Another
 	problem related to the supervision tree caused the closing
-	down of clients to leak processes e.i. all processes was
+	down of clients to leak processes i.e. all processes was
       not shutdown correctly.</p>
       <p>
       Own Id: OTP-7676</p>
@@ -925,7 +925,7 @@
 	slightly changes the options to the API function
 	ssh:daemon/[1,2,3] deprecating all no longer documented
 	options. Note that the new API enforces the "logical way"
-	of using the old API e.i. making the subsystem process
+	of using the old API i.e. making the subsystem process
 	part of the ssh applications supervisor tree, so missuses
       of the old API are not compatible with the new API.</p>
       <p>
diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml
index 9ab56b28ec..0bd8479343 100644
--- a/lib/ssh/doc/src/ref_man.xml
+++ b/lib/ssh/doc/src/ref_man.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE application SYSTEM "application.dtd">
 
 <application xmlns:xi="http://www.w3.org/2001/XInclude">
   <header>
     <copyright>
-      <year>2004</year><year>2010</year>
+      <year>2004</year><year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -22,20 +22,21 @@
     </legalnotice>
 
     <title>SSH Reference Manual</title>
-    <prepared>Jakob Cederlund</prepared>
-    <docno></docno>
+    <prepared>OTP</prepared>
     <date>2007-10-06</date>
     <rev>%VSN%</rev>
-    <file>application.sgml</file>
+    <file>ref_man.xml</file>
   </header>
   <description>
     <p>The SSH application is an erlang implementation of the
-      secure shell protocol.</p>
-  </description>
-  <xi:include href="ssh.xml"/>
-  <xi:include href="ssh_channel.xml"/>
-  <xi:include href="ssh_connection.xml"/>
-  <xi:include href="ssh_sftp.xml"/>
-  <xi:include href="ssh_sftpd.xml"/>
+      secure shell protocol (SSH) as defined by RFC 4250 - 4254</p>
+
+      </description>'
+      <xi:include href="ssh_app.xml"/>
+      <xi:include href="ssh.xml"/>
+      <xi:include href="ssh_channel.xml"/>
+      <xi:include href="ssh_connection.xml"/>
+      <xi:include href="ssh_sftp.xml"/>
+      <xi:include href="ssh_sftpd.xml"/>
 </application>
 
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 9f8efebbf5..907d0efc5c 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -22,13 +22,7 @@
     </legalnotice>
     
     <title>ssh</title>
-    <prepared>Ingela Anderton Andin</prepared>
-    <responsible>H&aring;kan Mattsson</responsible>
-    <docno></docno>
-    <approved>H&aring;kan Mattsson</approved>
-    <checked></checked>
     <date>2007-10-06</date>
-    <rev>PA1</rev>
   </header>
   <module>ssh</module>
   <modulesummary>Main API of the SSH application</modulesummary>
@@ -40,18 +34,19 @@
     <title>SSH</title>
 
     <list type="bulleted">
-      <item>ssh requires the crypto and public_key applications.</item>
-      <item>Supported SSH-version is 2.0 </item>
-      <item>Currently supports only a minimum of mac and encryption algorithms i.e.
-      hmac-sha1, and aes128-cb and 3des-cbc.</item>
+      <item>SSH requires the crypto and public_key applications.</item>
+      <item>Supported SSH version is 2.0 </item>
+      <item>Supported MAC algorithms: hmac-sha1</item>
+      <item>Supported encryption algorithms: aes128-cb and 3des-cbc</item>
     </list>
  
   </section>
   
   <section>
-    <title>COMMON DATA TYPES </title>
+    <title>DATA TYPES </title>
     <p>Type definitions that are used more than once in
-    this module:</p>
+    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>ssh_daemon_ref() - opaque to the user
@@ -60,60 +55,64 @@
     returned by ssh:connect/3</c></p>
     <p><c>ip_address() - {N1,N2,N3,N4} % IPv4 |
     {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p>
-    <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>  
+    <p><c>subsystem_spec() = {subsystem_name(),
+    {channel_callback(), channel_init_args()}} </c></p>
     <p><c>subsystem_name() = string() </c></p>
     <p><c>channel_callback() = atom() - Name of the erlang module
     implementing the subsystem using the ssh_channel behavior see</c>
     <seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
     <p><c>channel_init_args() = list()</c></p>
  </section>
-  
+
  <funcs>
    
    <func>
      <name>close(ConnectionRef) -> ok </name>
-      <fsummary>Closes a ssh connection</fsummary>
+      <fsummary>Closes an SSH connection</fsummary>
       <type>
 	<v>ConnectionRef = ssh_connection_ref()</v>
       </type>
-      <desc><p>Closes a ssh connection.</p> 
+      <desc><p>Closes an SSH connection.</p>
       </desc>
     </func>
     
     <func>
       <name>connect(Host, Port, Options) -> </name>
-      <name>connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()}
-      | {error, Reason}</name>
+      <name>connect(Host, Port, Options, Timeout) -> {ok,
+      ssh_connection_ref()} | {error, Reason}</name>
       <fsummary>Connect to an ssh server.</fsummary>
       <type>
         <v>Host = string()</v>
 	<v>Port = integer()</v>
-	<d>The default is <c><![CDATA[22]]></c>, the registered port for SSH.</d>
+	<d>The default is <c><![CDATA[22]]></c>, the assigned well known port
+	number for SSH.</d>
 	<v>Options = [{Option, Value}]</v>
 	<v>Timeout = infinity | integer(milliseconds)</v>
       </type>
       <desc>
-	<p>Connects to an SSH server. No channel is started this is done
+	<p>Connects to an SSH server. No channel is started. This is done
 	by calling ssh_connect:session_channel/2.</p>
 	<p>Options are:</p>
 	<taglist>
           <tag><c><![CDATA[{user_dir, string()}]]></c></tag>
 	  <item>
-	    <p>Sets the user directory e.i. the directory containing
+	    <p>Sets the user directory i.e. the directory containing
 	    ssh configuration files for the user such as
-	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa, id_dsa]]></c> and
-	    <c><![CDATA[authorized_key]]></c>. Defaults to the directory normally
-	    referred to as <c><![CDATA[~/.ssh]]></c> </p>
+	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
+	    id_dsa]]></c> and
+	    <c><![CDATA[authorized_key]]></c>. Defaults to the
+	    directory normally referred to as
+	    <c><![CDATA[~/.ssh]]></c> </p>
 	  </item>
 	  <tag><c><![CDATA[{dsa_pass_phrase, string()}]]></c></tag>
 	  <item>
-	    <p>If the user dsa key is protected by a pass phrase it can be
+	    <p>If the user dsa key is protected by a passphrase it can be
 	    supplied with this option.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{rsa_pass_phrase, string()}]]></c></tag>
 	  <item>
-	    <p>If the user rsa key is protected by a pass phrase it can be
+	    <p>If the user rsa key is protected by a passphrase it can be
 	    supplied with this option.
 	    </p>
 	  </item>
@@ -138,7 +137,7 @@
 	  <tag><c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></tag>
 	  <item>
             <p>Sets the preferred public key algorithm to use for user
-	    authentication. If the the preferred algorithm fails of
+	    authentication. If the the preferred algorithm fails for
 	    some reason, the other algorithm is tried. The  default is
 	    to try <c><![CDATA[ssh_rsa]]></c> first.</p>
 	  </item>
@@ -149,11 +148,12 @@
 	  </item>
 	  <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag>
 	  <item>
-	    <p>Sets a timeout on the transport layer connection. Defaults to infinity.</p>
+	    <p>Sets a timeout on the transport layer
+	    connection. Defaults to infinity.</p>
 	  </item>
 	  <tag><c><![CDATA[{user, String}]]></c></tag>
           <item>
-	    <p>Provide a user name. If this option is not given, ssh
+	    <p>Provides a user name. If this option is not given, ssh
 	    reads from the environment (<c><![CDATA[LOGNAME]]></c> or
 	    <c><![CDATA[USER]]></c> on unix,
 	    <c><![CDATA[USERNAME]]></c> on Windows).</p>
@@ -165,23 +165,9 @@
 	    password if the password authentication method is
 	    attempted.</p>
           </item>
-          <tag><c><![CDATA[{user_auth, Fun/3}]]></c></tag>
-          <item>
-	    <p>Provide a fun for password authentication. The fun
-	    will be called as <c><![CDATA[fun(User, Password, Opts)]]></c> and
-	    should return <c><![CDATA[true]]></c> or <c><![CDATA[false]]></c>.</p>
-	  </item>
 	  <tag><c><![CDATA[{key_cb, atom() = KeyCallbackModule}]]></c></tag>
 	  <item>
-	    <p>Provide a special call-back module for key handling.
-	    The call-back module should be modeled after the
-	    <c><![CDATA[ssh_file]]></c> module. The functions that must
-	    be exported are:
-	    <c><![CDATA[private_host_rsa_key/2]]></c>,
-	    <c><![CDATA[private_host_dsa_key/2]]></c>,
-	    <c><![CDATA[lookup_host_key/3]]></c> and
-	    <c><![CDATA[add_host_key/3]]></c>. This is considered
-	    somewhat experimental and will be better documented later on.</p>
+	    <p>TODO:</p>
 	  </item>
 	  <tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag>
 	  <item>
@@ -189,7 +175,7 @@
 	  </item>
 	  <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
 	  <item>
-	    <p>Allow an existing file-descriptor to be used
+	    <p>Allow an existing file descriptor to be used
 	  (simply passed on to the transport protocol).</p></item>
 	  <tag><c><![CDATA[{ip_v6_disabled, boolean()}]]></c></tag>
 	  <item>
@@ -202,7 +188,8 @@
     </func>
 
     <func>
-      <name>connection_info(ConnectionRef, [Option]) ->[{Option, Value}] </name>
+      <name>connection_info(ConnectionRef, [Option]) ->[{Option,
+      Value}] </name>
       <fsummary> Retrieves information about a connection. </fsummary>
       <type>
         <v>Option = client_version | server_version | peer</v>
@@ -217,7 +204,8 @@
     <func>
       <name>daemon(Port) -> </name>
       <name>daemon(Port, Options) -> </name>
-      <name>daemon(HostAddress, Port, Options) -> {ok, ssh_daemon_ref()} | {error, atom()}</name>
+      <name>daemon(HostAddress, Port, Options) -> {ok,
+      ssh_daemon_ref()} | {error, atom()}</name>
       <fsummary>Starts a server listening for SSH connections 
       on the given port.</fsummary>
       <type>
@@ -228,30 +216,32 @@
 	<v>Value = term()</v>
       </type>
       <desc>
-        <p>Starts a server listening for SSH connections on the given port.</p>
-      
-        <p>Options are:</p>
+        <p>Starts a server listening for SSH connections on the given
+        port.</p>
+	<p>Options are:</p>
         <taglist>
 	  <tag><c><![CDATA[{subsystems, [subsystem_spec()]]]></c></tag>
 	  <item>
-	    Provides specifications for handling of subsystems.  The
-	    "sftp" subsystem-spec can be retrieved by calling
-	    ssh_sftpd:subsystem_spec/1. If the subsystems option in not present
-	    the value of <c>[ssh_sftpd:subsystem_spec([])]</c> will be used.
-	    It is of course possible to set the option to the empty list
-	    if you do not want the daemon to run any subsystems at all.
+	    Provides specifications for handling of subsystems. The
+	    "sftp" subsystem spec can be retrieved by calling
+	    ssh_sftpd:subsystem_spec/1. If the subsystems option in
+	    not present the value of
+	    <c>[ssh_sftpd:subsystem_spec([])]</c> will be used.  It is
+	    of course possible to set the option to the empty list if
+	    you do not want the daemon to run any subsystems at all.
 	  </item>
-	  <tag><c><![CDATA[{shell, {Module, Function, Args} | fun(string() = User) - > pid() |
-	  fun(string() = User, ip_address() = PeerAddr) -> pid()}]]></c></tag>
+	  <tag><c><![CDATA[{shell, {Module, Function, Args} |
+	  fun(string() = User) - > pid() | fun(string() = User,
+	  ip_address() = PeerAddr) -> pid()}]]></c></tag>
 	  <item>
-	    Defines the read-eval-print loop used when a shell is requested
-	    by the client. Example use the
-	    erlang shell: <c><![CDATA[{shell, start, []}]]></c> which is
-	    the default behavior.
+	    Defines the read-eval-print loop used when a shell is
+	    requested by the client. Default is to use the erlang shell:
+	    <c><![CDATA[{shell, start, []}]]></c>
 	  </item>
-	  <tag><c><![CDATA[{ssh_cli,{channel_callback(), channel_init_args()}}]]></c></tag>
+	  <tag><c><![CDATA[{ssh_cli,{channel_callback(),
+	  channel_init_args()}}]]></c></tag>
 	  <item>
-	    Provide your own cli implementation, e.i. a channel callback
+	    Provides your own cli implementation, i.e. a channel callback
 	    module that implements a shell and command execution. Note
 	    that you may customize the shell read-eval-print loop using the
 	    option <c>shell</c> which is much less work than implementing
@@ -259,27 +249,30 @@
 	  </item>
 	  <tag><c><![CDATA[{user_dir, String}]]></c></tag>
 	  <item>
-	    <p>Sets the user directory e.i. the directory containing
+	    <p>Sets the user directory i.e. the directory containing
 	    ssh configuration files for the user such as
-	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa, id_dsa]]></c> and
-	    <c><![CDATA[authorized_key]]></c>. Defaults to the directory normally
-	    referred to as <c><![CDATA[~/.ssh]]></c> </p>
+	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
+	    id_dsa]]></c> and
+	    <c><![CDATA[authorized_key]]></c>. Defaults to the
+	    directory normally referred to as
+	    <c><![CDATA[~/.ssh]]></c> </p>
 	  </item>
           <tag><c><![CDATA[{system_dir, string()}]]></c></tag>
           <item>
-            <p>Sets the system directory, containing the host files
-            that identifies the host for ssh. The default is
-            <c><![CDATA[/etc/ssh]]></c>, note that SSH normally
-            requires the host files there to be readable only by
-	    root.</p>
+            <p>Sets the system directory, containing the host key files
+            that identifies the host keys for ssh. The default is
+            <c><![CDATA[/etc/ssh]]></c>, note that for security reasons
+            this directory is normally only accessible by the root user.</p>
 	  </item>
 	  <tag><c><![CDATA[{auth_methods, string()}]]></c></tag>
 	  <item>
-	    <p>Comma separated string that determines which authentication methodes that the server
-	    should support and in what order they will be tried. Defaults to
+	    <p>Comma separated string that determines which
+	    authentication methodes that the server should support and
+	    in what order they will be tried. Defaults to
 	    <c><![CDATA["publickey,keyboard-interactive,password"]]></c></p>
           </item>
-	  <tag><c><![CDATA[{user_passwords, [{string() = User, string() = Password}]}]]></c></tag>
+	  <tag><c><![CDATA[{user_passwords, [{string() = User,
+	  string() = Password}]}]]></c></tag>
 	  <item>
             <p>Provide passwords for password authentication.They will
 	    be used when someone tries to connect to the server and
@@ -293,7 +286,7 @@
               user. From a security perspective this option makes
 	      the server very vulnerable.</p>
 	  </item>
-	  <tag><c><![CDATA[{pwdfun, fun/2}]]></c></tag>
+	  <tag><c><![CDATA[{pwdfun, fun(User::string(), password::string() -> boolean()}]]></c></tag>
 	  <item>
 	    <p>Provide a function for password validation. This is called
 	      with user and password as strings, and should return
@@ -335,9 +328,9 @@
 	<v> Options - see ssh:connect/3</v>
       </type>
       <desc>
-        <p>Starts an interactive shell to an SSH server on the
+        <p>Starts an interactive shell via an SSH server on the
 	given <c>Host</c>. The function waits for user input,
-	and will not return until the remote shell is ended (e.g. on
+	and will not return until the remote shell is ended (i.e.
 	exit from the shell).
 	</p>
       </desc>
@@ -346,25 +339,24 @@
     <func>
       <name>start() -> </name>
       <name>start(Type) -> ok | {error, Reason}</name>
-      <fsummary>Starts the Ssh application. </fsummary>
+      <fsummary>Starts the SSH application. </fsummary>
       <type>
         <v>Type =  permanent | transient | temporary</v>
 	<v>Reason = term() </v>
       </type>
       <desc>
-        <p>Starts the Ssh application. Default type
-          is temporary. See also
-          <seealso marker="kernel:application">application(3)</seealso>
-	  Requires that the crypto application has been started.
+        <p>Utility function that starts crypto, public_key and the SSH
+	application. Defult type is temporary.
+	<seealso marker="kernel:application">application(3)</seealso>
 	</p>
       </desc>
     </func>
 
     <func>
       <name>stop() -> ok </name>
-      <fsummary>Stops the Ssh application.</fsummary>
+      <fsummary>Stops the SSH application.</fsummary>
       <desc>
-        <p>Stops the Ssh application. See also
+        <p>Stops the SSH application. See also
           <seealso marker="kernel:application">application(3)</seealso></p>
       </desc>
     </func>
diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml
new file mode 100644
index 0000000000..51544d3890
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_app.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE appref SYSTEM "appref.dtd">
+
+<appref>
+  <header>
+    <copyright>
+      <year>2012</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.
+
+    </legalnotice>
+
+    <title>SSH</title>
+    <file>ssh_app.sgml</file>
+  </header>
+  <app>SSH</app>
+  <appsummary>The ssh application implements the SSH (Secure Shell) protocol and
+  provides an SFTP (SSH File Transfer Protocol) client and server. </appsummary>
+
+  <section>
+    <title>DEPENDENCIES</title>
+    <p>The ssh application uses the Erlang applications public_key and
+    crypto to handle public keys and encryption, hence these
+    applications needs to be loaded for the ssh application to work. In
+    an embedded environment that means they need to be started with
+    application:start/[1,2] before the ssh application is started.
+    </p>
+  </section>
+
+  <section>
+    <title>CONFIGURATION</title>
+
+    <p>The ssh application does not currently have an application
+    specific configuration file as described in application(3),
+    however it will by default use the following configuration files
+    from openssh: known_hosts, authorized_keys, authorized_keys2,
+    id_dsa and id_rsa, ssh_host_dsa_key and ssh_host_rsa_key.  By
+    default Erlang SSH will look for id_dsa, id_rsa, known_hosts
+    and authorized_keys in ~/.ssh, and the host key files in /etc/ssh
+    . These locations may be changed by the options user_dir and
+    system_dir.  Public key handling may also be customized by
+    providing a callback module implementing the behavior ssh_key_api.
+    </p>
+
+    <section>
+      <title>PUBLIC KEYS</title>
+      <p>
+	id_dsa and id_rsa are the users private key files, note that
+	the public key is part of the private key so the ssh
+	application will not use the id_&lt;*>.pub files. These are
+	for the users convenience when he/she needs to convey their
+	public key.
+      </p>
+    </section>
+
+    <section>
+      <title>KNOW HOSTS</title>
+      <p>The known_hosts file contains a list of approved servers and
+      their public keys.  Once a server is listed, it can be verified
+      without user interaction.
+      </p>
+     </section>
+
+     <section>
+      <title>AUTHORIZED KEYS</title>
+      <p>The authorized key file keeps track of the user's authorized
+      public keys. The most common use of this file is to let users
+      log in without entering their password which is supported by the
+      Erlang SSH daemon.
+      </p>
+     </section>
+
+     <section>
+       <title>HOST KEYS</title>
+       <p>Currently rsa and dsa host keys are supported and are
+       expected to be found in files named ssh_host_rsa_key and
+       ssh_host_dsa_key.
+       </p>
+     </section>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>application(3)</p>
+  </section>
+
+</appref>
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>
diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
index a9ae13d556..4480f0a093 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() = 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  <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,9 +269,9 @@
        <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>
@@ -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>
diff --git a/lib/ssh/doc/src/ssh_protocol.xml b/lib/ssh/doc/src/ssh_protocol.xml
new file mode 100644
index 0000000000..529558759e
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_protocol.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+<!-- %EricssonCopyright% -->
+<chapter>
+  <header>
+    <copyright>
+      <year>2012</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The program may be used and/or copied only with the written permission from
+      Ericsson AB, or in accordance with the terms and conditions stipulated in
+      the agreement/contract under which the program has been supplied.
+    </legalnotice>
+    <title>Secure Shell (SSH)</title>
+    <prepared>OTP</prepared>
+    <date></date>
+    <rev>%VSN%</rev>
+    <file>ssh_protocol.xml</file>
+  </header>
+
+  <section>
+    <title>SSH Protocol Overview</title>
+
+    <p> Conceptually the SSH protocol can be partitioned into four
+    layers:</p>
+
+    <image file="SSH_protocols.png">
+      <icaption>SSH Protocol Architecture</icaption>
+    </image>
+
+    <section>
+      <title>Transport Protocol</title>
+
+      <p> The SSH Transport Protocol is a secure, low level transport.
+      It provides strong encryption, cryptographic host
+      authentication and integrity protection. Currently, only a
+      minimum of MAC- (message authentication code, a short piece of
+      information used to authenticate a message) and encryption
+      algorithms see <seealso marker="ssh">ssh(3)</seealso>
+      </p>
+    </section>
+
+    <section>
+      <title>Authentication Protocol</title>
+
+      <p>The SSH authentication protocol is a general-purpose user
+      authentication protocol run over the SSH transport
+      protocol. Erlang SSH supports user authentication using public
+      key technology (RSA and DSA, X509-certificates are currently not
+      supported). It is also possible to use a so called keyboard
+      interactive authentication. This method is suitable for
+      interactive authentication methods that do not need any special
+      software support on the client side. Instead, all authentication
+      data should be entered via the keyboad. It is also possible
+      to use a pure password based authentication scheme, note that in
+      this case the the plain text password will be encrypted befor sent
+      over the network.
+      </p>
+    </section>
+
+    <section>
+      <title>Connection Protocol</title>
+
+      <p>The SSH Connection Protocol provides application-support
+      services over the transport pipe, such as channel multiplexing,
+      flow control, remote program execution, signal propagation,
+      connection forwarding, etc.  Functions for handling the SSH
+      Connection Protocol can be found in the module <seealso
+      marker="ssh_connection">ssh_connection</seealso>.
+      </p>
+    </section>
+
+    <section>
+      <title>Channels</title>
+
+      <p>All terminal sessions, forwarded connections etc., are
+      channels.  Multiple channels are multiplexed into a single
+      connection, and all channels are flow-controlled.  Typically an
+      SSH client will open a channel, send data/commands, receive
+      data/"control information" and when it is done close the
+      channel. The <seealso
+      marker="ssh_channel">ssh_channel</seealso> behaviour makes it easy to
+      write your own SSH client/server processes that use flow
+      control. It handles generic parts of SSH channel managment and
+      lets you focus on the application logic.
+      </p>
+
+      <p>Channels comes in three flavors</p>
+
+      <list type="bulleted">
+	<item><em>Subsystem</em> - named services that can be run as
+	part of an SSH server such as SFTP <seealso
+	marker="ssh_sftp">ssh_sftp</seealso>, that is built in to the
+	SSH daemon (server) by default but may be disabled. The Erlang SSH
+	daemon may be configured to run any Erlang
+	implemented SSH subsystem.
+	</item>
+	<item><em>Shell</em> - interactive shell.  By default the
+	Erlang daemon will run the Erlang shell. It is
+	possible to customize the shell by providing your own
+	read-eval-print loop. It is also possible, but much more work,
+	to provide your own CLI (Command Line Interface) implementation.
+	</item>
+	<item><em>Exec</em> - one-time remote execution (like
+	SCP). See <seealso
+	marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso></item>
+      </list>
+    </section>
+
+    <p>Channels are flow controlled.  No data may be sent to a channel
+    peer until a message is received to indicate that window space is
+    available.  The 'initial window size' specifies how many bytes of
+    channel data that can be sent to the channel peer without adjusting the
+    window.
+    </p>
+
+    <p>
+      For more detailed information about the SSH protocol, see the
+      following RFCs:
+    </p>
+
+    <list type="bulleted">
+      <item><url href="http://www.ietf.org/rfc/rfc4250.txt">RFC 4250</url> -
+      Protocol Assigned Numbers.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4251.txt">RFC 4251</url> -
+      Protocol Architecture.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4252.txt">RFC 4252</url> -
+      Authentication Protocol.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4253.txt">RFC 4253</url> -
+      Transport Layer Protocol.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> -
+      Connection Protocol.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4255.txt">RFC 4255</url> -
+      Key Fingerprints.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4344.txt">RFC 4344</url> -
+      Transport Layer Encryption Modes.</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4716.txt">RFC 4716</url> -
+      Public Key File Format.</item>
+    </list>
+  </section>
+</chapter>
diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index c1f75461b1..28576c9ef0 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
   <header>
     <copyright>
-      <year>2005</year><year>2010</year>
+      <year>2005</year><year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -22,25 +22,20 @@
     </legalnotice>
 
     <title>ssh_sftp</title>
-    <prepared>Jakob Cederlund</prepared>
-    <responsible></responsible>
-    <docno>1</docno>
-    <approved></approved>
-    <checked></checked>
+    <prepared>OTP</prepared>
     <date>2005-09-22</date>
-    <rev>PA1</rev>
     <file>ssh_sftp.sgml</file>
   </header>
   <module>ssh_sftp</module>
   <modulesummary>SFTP client.</modulesummary>
   <description>
     <p>This module implements an SFTP (SSH FTP) client. SFTP is a
-      secure, encrypted file transfer service available for
-      SSH.</p>
+    secure, encrypted file transfer service available for
+    SSH.</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 type:
     </p>
@@ -51,8 +46,8 @@
 
  <section>
     <title>TIMEOUTS </title>
-    <p>If the request functions for the sftp channel return {error, timeout}
-    it does not mean that the request did not reach the server and was
+    <p>If the request functions for the SFTP channel return {error, timeout}
+    it does not guarantee that the request did not reach the server and was
     not performed, it only means that we did not receive an answer from the
     server within the time that was expected.</p>
    </section>
@@ -64,7 +59,7 @@
       <name>start_channel(Host, Options) -></name>
       <name>start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} |
       {error, Reason}</name>
-      <fsummary>Starts a sftp client</fsummary>
+      <fsummary>Starts a SFTP client</fsummary>
       <type>
         <v>Host = string()</v>
         <v>ConnectionRef = ssh_connection_ref()</v>
@@ -73,11 +68,11 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-	<p>If not provided, setups a ssh connection in this case a
-	connection reference will be returned too. A ssh channel
-	process is started to handle the communication with the SFTP
-	server, the returned pid for this process should be used as
-	input to all other API functions in this module.</p>
+	<p>If no connection reference is provided, a connection is set
+	up and the new connection is returned.  An SSH channel process
+	is started to handle the communication with the SFTP server.
+	The returned pid for this process should be used as input to
+	all other API functions in this module.</p>
 
 	<p>Options are:</p>
 	<taglist>
@@ -95,13 +90,13 @@
 
     <func>
       <name>stop_channel(ChannelPid) -> ok</name>
-      <fsummary>Stops the sftp client channel.</fsummary>
+      <fsummary>Stops the SFTP client channel.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
       </type>
       <desc>
-	<p>Stops a sftp channel. If the ssh connection should be closed
-	call <seealso marker="ssh">ssh:close/1</seealso>.</p>
+	<p>Stops an SFTP channel. Does not close the SSH connetion.
+	Use <seealso marker="ssh">ssh:close/1</seealso> to close it.</p>
       </desc>
     </func>
   
@@ -133,8 +128,9 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes a file to the server, like <c><![CDATA[file:write_file/2]]></c>.
-          The file is created if it's not there.</p>
+        <p>Writes a file to the server, like
+        <c><![CDATA[file:write_file/2]]></c>.  The file is created if
+        it does not exist or is owerwritten if it does.</p>
       </desc>
     </func>
     <func>
@@ -169,7 +165,7 @@
       </type>
       <desc>
         <p>Opens a file on the server, and returns a handle that
-          is used for reading or writing.</p>
+          can be used for reading or writing.</p>
       </desc>
     </func>
     <func>
@@ -184,7 +180,7 @@
       </type>
       <desc>
         <p>Opens a handle to a directory on the server, the handle
-          is used for reading directory contents.</p>
+          can be used for reading directory contents.</p>
       </desc>
     </func>
     <func>
@@ -218,7 +214,7 @@
       </type>
       <desc>
         <p>Reads <c><![CDATA[Len]]></c> bytes from the file referenced by
-          <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, or <c><![CDATA[eof]]></c>, or
+          <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, <c><![CDATA[eof]]></c>, or
           <c><![CDATA[{error, Reason}]]></c>. If the file is opened with <c><![CDATA[binary]]></c>,
           <c><![CDATA[Data]]></c> is a binary, otherwise it is a string.</p>
         <p>If the file is read past eof, only the remaining bytes
@@ -267,9 +263,9 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Write <c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
+        <p>Writes<c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
           The file should be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
-          flag. Returns <c><![CDATA[ok]]></c> if successful and <c><![CDATA[{error, Reason}]]></c>
+          flag. Returns <c><![CDATA[ok]]></c> if successful or S<c><![CDATA[{error, Reason}]]></c>
           otherwise.</p>
         <p>Typical error reasons are:</p>
         <taglist>
@@ -317,14 +313,14 @@
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
         <v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
-        <v>Offset = int()</v>
+        <v>Offset = integer()</v>
 	<v>Timeout = timeout()</v>
         <v>NewPosition = integer()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
         <p>Sets the file position of the file referenced by <c><![CDATA[Handle]]></c>.
-          Returns <c><![CDATA[{ok, NewPosition]]></c> (as an absolute offset) if
+          Returns <c><![CDATA[{ok, NewPosition}]]></c> (as an absolute offset) if
           successful, otherwise <c><![CDATA[{error, Reason}]]></c>. <c><![CDATA[Location]]></c> is
           one of the following:</p>
         <taglist>
@@ -413,7 +409,7 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Read the link target from the symbolic link specified
+        <p>Reads the link target from the symbolic link specified
           by <c><![CDATA[name]]></c>, like <c><![CDATA[file:read_link/1]]></c>.</p>
       </desc>
     </func>
diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml
index b3d64e72b4..a4273195b5 100644
--- a/lib/ssh/doc/src/ssh_sftpd.xml
+++ b/lib/ssh/doc/src/ssh_sftpd.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE erlref SYSTEM "erlref.dtd">
 
 <erlref>
   <header>
     <copyright>
-      <year>2005</year><year>2010</year>
+      <year>2005</year><year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -22,23 +22,17 @@
     </legalnotice>
 
     <title>ssh_sftpd</title>
-    <prepared>Ingela Anderton Andin</prepared>
-    <responsible></responsible>
-    <docno>1</docno>
-    <approved></approved>
-    <checked></checked>
     <date>2005-09-22</date>
-    <rev>PA1</rev>
     <file>ssh_sftpd.sgml</file>
   </header>
   <module>ssh_sftpd</module>
-  <modulesummary>Specifies a channel process to handle a sftp subsystem.</modulesummary>
+  <modulesummary>Specifies the channel process to handle an sftp subsystem.</modulesummary>
   <description>
     <p>Specifies a channel process to handle a sftp subsystem.</p>
   </description>
 
   <section>
-    <title>COMMON DATA TYPES </title>
+    <title>DATA TYPES </title>
     <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>
     <p><c>subsystem_name() =  "sftp"</c></p>
     <p><c>channel_callback() = atom()</c> - Name of the erlang module implementing the
@@ -65,28 +59,28 @@
           </item>
           <tag><c><![CDATA[{file_handler, CallbackModule}]]></c></tag>
           <item>
-            <p>Determines which module to call for communicating with
-              the file server. Default value is <c>ssh_sftpd_file</c> that uses the
-              file and filelib API:s to access the standard OTP file
-              server. This option may be used to plug in the use of
-              other file servers.</p>
-          </item>
-          <tag><c><![CDATA[{max_files, Integer}]]></c></tag>
-          <item>
-            <p>The default value is <c>0</c>, which means that there is no upper limit.
-               If supplied, the number of filenames returned to the sftp client per <c>READDIR</c>
-               request, is limited to at most the given value.</p>
-          </item>
+	    <p>Determines which module to call for accessing
+	    the file server. The default value is <c>ssh_sftpd_file</c> that uses the
+	    <seealso marker="kernel#file">file</seealso> and <seealso marker="kernel#filelib">filelib</seealso> API:s to access the standard OTP file
+	    server. This option may be used to plug in
+	    other file servers.</p>
+	  </item>
+	  <tag><c><![CDATA[{max_files, Integer}]]></c></tag>
+	  <item>
+	    <p>The default value is <c>0</c>, which means that there is no upper limit.
+	    If supplied, the number of filenames returned to the sftp client per <c>READDIR</c>
+	    request is limited to at most the given value.</p>
+	  </item>
 	  <tag><c><![CDATA[{root, String}]]></c></tag>
 	  <item>
 	    <p>Sets the sftp root directory. The user will then not be
-	      able to see any files above this root. If for instance
-	      the root is set to <c>/tmp</c> the user will see this
-	      directory as <c>/</c> and if the user does cd <c>/etc</c>
-	      the user will end up in <c>/tmp/etc</c>.
+	    able to see any files above this root. If for instance
+	    the root is set to <c>/tmp</c> the user will see this
+	    directory as <c>/</c> and if the user does cd <c>/etc</c>
+	    the user will end up in <c>/tmp/etc</c>.
 	    </p>
 	  </item>
-        </taglist>
+	</taglist>
       </desc>
     </func>
   </funcs>  
diff --git a/lib/ssh/doc/src/ssh_ug.xml b/lib/ssh/doc/src/ssh_ug.xml
deleted file mode 100644
index 0b040a59fd..0000000000
--- a/lib/ssh/doc/src/ssh_ug.xml
+++ /dev/null
@@ -1,95 +0,0 @@
-<?xml version="1.0" encoding="latin1" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
-<!-- %EricssonCopyright% -->
-<chapter>
-  <header>
-    <copyright>
-      <year>2011</year>
-      <holder>Ericsson AB. All Rights Reserved.</holder>
-    </copyright>
-    <legalnotice>
-      The program may be used and/or copied only with the written permission from
-      Ericsson AB, or in accordance with the terms and conditions stipulated in
-      the agreement/contract under which the program has been supplied.
-    </legalnotice>
-    <title>SSH</title>
-    <prepared>OTP</prepared>
-    <docno></docno>
-    <date></date>
-    <rev>A</rev>
-    <file>ssh_ug.xml</file>
-  </header>
-
-  <section>
-    <title>Introduction</title>
-    <p>The Secure Shell (SSH) is a transport protocol. For more detailed information,
-       see the following RFCs:
-    </p>
-    <list type="bulleted">
-      <item><url href="http://www.ietf.org/rfc/rfc4250.txt">RFC 4250</url> -
-            Protocol Assigned Numbers.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4251.txt">RFC 4251</url> -
-            Protocol Architecture.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4252.txt">RFC 4252</url> -
-            Authentication Protocol.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4253.txt">RFC 4253</url> -
-            Transport Layer Protocol.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> -
-            Connection Protocol.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4255.txt">RFC 4255</url> -
-            Key Fingerprints.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4344.txt">RFC 4344</url> -
-            Transport Layer Encryption Modes.</item>
-      <item><url href="http://www.ietf.org/rfc/rfc4716.txt">RFC 4716</url> -
-            Public Key File Format.</item>
-    </list>
-
-    <p>The SSH application is an implementation of the SSH protocol
-       in Erlang. Conceptually it can be partitioned into four layers:</p>
-
-   <image file="SSH_protocols.png">
-     <icaption>SSH Protocol Dependencies</icaption>
-   </image>
-
-  </section>
-
-  <section>
-    <title>Overview</title>
-    <p>The SSH application supports:</p>
-
-    <list type="bulleted">
-      <item><em>Subsystem</em> - user-named services such as <seealso marker="ssh_sftp">ssh_sftp</seealso>.
-            The user can also add other subsystems (e.g. NETCONF).</item>
-      <item><em>Shell</em> - interactive shell.</item>
-      <item><em>Exec</em> - one-time remote execution (i.e. SCP). See <seealso marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso></item>
-    </list>
-
-
-  </section>
-
-  <section>
-    <title>Configuration and Start</title>
-
-    <p>Before the SSH application can be used, there are two things that must be fulfilled:</p>
-    <list type="bulleted">
-      <item>The <seealso marker="crypto:crypto">Crypto</seealso> application is started before SSH is.</item>
-      <item>The <seealso marker="public_key:public_key">Public_key</seealso> application is loaded when
-        running an embedded system.</item>
-    </list>
-
-    <section>
-      <title>Server Side</title>
-      <marker id="daemon"></marker>
-      <p>When SSH is supposed to run as server, the function <seealso marker="ssh#daemon-3">ssh:daemon/[1, 2, 3]</seealso> needs to
-         be used to start the daemon. </p>
-
-    </section>
-    <section>
-      <title>Client Side</title>
-      <marker id="client"></marker>
-      <p>The client.</p>
-
-    </section>
-  </section>
-
-</chapter>
diff --git a/lib/ssh/doc/src/user_guide.gif b/lib/ssh/doc/src/user_guide.gif
deleted file mode 100644
index e6275a803d..0000000000
--- a/lib/ssh/doc/src/user_guide.gif
+++ /dev/null
diff --git a/lib/ssh/doc/src/part.xml b/lib/ssh/doc/src/usersguide.xml
index cca30182a1..c818003090 100644
--- a/lib/ssh/doc/src/part.xml
+++ b/lib/ssh/doc/src/usersguide.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE part SYSTEM "part.dtd">
 
 <part xmlns:xi="http://www.w3.org/2001/XInclude">
   <header>
     <copyright>
-      <year>2011</year>
+      <year>2012</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -22,14 +22,16 @@
     </legalnotice>
 
     <title>SSH User's Guide</title>
-    <prepared></prepared>
-    <docno></docno>
-    <date></date>
-    <rev></rev>
+    <prepared>OTP Team</prepared>
+    <date>2012-10-11</date>
+    <file>usersguide.xml</file>
   </header>
   <description>
-    <p>The <em>SSH</em> application is an Erlang implementation of the
-      SSH protocol.</p>
+    <p>The <em>SSH</em> application implements the SSH (Secure Shell) protocol and
+    provides an SFTP (Secret File Transfer Protocol) client and server.
+    </p>
   </description>
-  <xi:include href="ssh_ug.xml"/>
+  <xi:include href="introduction.xml"/>
+  <xi:include href="ssh_protocol.xml"/>
+  <xi:include href="using_ssh.xml"/>
 </part>
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
new file mode 100644
index 0000000000..db17c6fd1c
--- /dev/null
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -0,0 +1,288 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2012</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.
+
+    </legalnotice>
+
+    <title>Getting started</title>
+    <file>using_ssh.xml</file>
+  </header>
+
+  <section>
+    <title> General information</title>
+    <p>The examples in the following sections use the utility function
+    <seealso marker="ssh#start"> ssh:start/0 </seealso> that starts
+    all needed applications (crypto, public_key and ssh). All examples
+    are run in an Erlang shell, or in a bash shell using openssh to
+    illustrate how the erlang ssh application can be used.  The
+    exampels are run as the user otptest on a local network where the
+    user is authorized to login in over ssh to the host "tarlop". If
+    nothing else is stated it is persumed that the otptest user has an
+    entry in tarlop's authorized_keys file (may log in via ssh without
+    entering a password).  Also tarlop is a known host in the user
+    otptests known_hosts file so that host verification can be done
+    without user interaction.
+    </p>
+  </section>
+
+  <section>
+    <title>Using the Erlang SSH Terminal Client</title>
+
+    <p>The user otptest, that has bash as default shell, uses the
+    ssh:shell/1 client to connect to the openssh daemon running on a
+    host called tarlop. Note that currently this client is very simple
+    and you should not be expected to be as fancy as the openssh
+    client.</p>
+
+    <code type="erl" >
+      1>  ssh:start().
+      ok
+      2> {ok, S} = ssh:shell("tarlop").
+      >pwd
+      /home/otptest
+      >exit
+      logout
+      3>
+    </code>
+  </section>
+
+  <section>
+    <title>Running an Erlang SSH Daemon </title>
+
+    <p> The option system_dir must be a directory containing a host
+    key file and it defaults to /etc/ssh. For details see section
+    Configuration Files in <seealso
+    marker="ssh_app">ssh(6)</seealso>.
+    </p>
+
+    <note><p>Normaly the /etc/ssh directory is only readable by root. </p>
+    </note>
+
+    <p> The option user_dir defaults to the users ~/.ssh  directory</p>
+
+    <p>In the following exampel we have generate new keys and host keys as
+    to be able to run the example without having root privilages</p>
+
+    <code>
+      $bash> ssh-keygen -t rsa -f /tmp/ssh_daemon/ssh_host_rsa_key
+      [...]
+      $bash> ssh-keygen -t rsa -f /tmp/otptest_user/.ssh/id_rsa
+      [...]
+    </code>
+
+    <p>And add the public hostkey to the known_hosts file of the user otptest. Then we can do</p>
+
+    <code type="erl">
+      1> ssh:start().
+      ok
+      2> {ok, Sshd} = ssh:daemon(8989,  [{system_dir, "/tmp/ssh_daemon/ssh_host_rsa_key"},
+      {user_dir, "/tmp/otptest_user/.ssh"}]).
+      {ok,&lt;0.54.0>}
+      3>
+    </code>
+
+    <p>Use the openssh client from a shell to connect to the Erlang ssh daemon.</p>
+
+    <code>
+      $bash> ssh tarlop -p 8989 -i /tmp/otptest_user/.ssh/id_rsa
+      Eshell V5.10  (abort with ^G)
+      1>
+    </code>
+
+    <p>There is two ways of shuting down an SSH daemon</p>
+
+    <p>1: Stops the listener, but leaves existing connections started by the listener up and running.</p>
+
+    <code type="erl">
+      3> ssh:stop_listener(Sshd).
+      ok
+      4>
+    </code>
+
+    <p>2: Stops the listener and all connections started by the listener.</p>
+
+    <code type="erl">
+      3> ssh:stop_daemon(Sshd)
+      ok
+      4>
+    </code>
+
+  </section>
+
+  <section>
+    <title>One Time Execution</title>
+
+    <p>In the following example the Erlang shell is the client process
+    that receives the channel replies. <note> If you run this example
+    in your environment you may get fewer or more messages back as
+    this depends on the OS and shell on the machine running the ssh
+    daemon. See also <seealso marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso>
+  </note>
+    </p>
+
+    <code type="erl" >
+      1>  ssh:start().
+      ok
+      2> {ok, ConnectionRef} = ssh:connect("tarlop", 22, []).
+      {ok,&lt;0.57.0>}
+      3>{ok, ChannelId} =  ssh_connection:session_channel(ConnectionRef, infinity).
+      {ok,0}
+      4> success = ssh_connection:exec(ConnectionRef, ChannelId, "pwd", infinity).
+      5>  flush().
+      Shell got {ssh_cm,&lt;0.57.0>,{data,0,0,&lt;&lt;"/home/otptest\n">>}}
+      Shell got {ssh_cm,&lt;0.57.0>,{eof,0}}
+      Shell got {ssh_cm,&lt;0.57.0>,{exit_status,0,0}}
+      Shell got {ssh_cm,&lt;0.57.0>,{closed,0}}
+      ok
+      6>
+    </code>
+
+    <p>Note only the channel is closed the connection is still up and can handle other channels</p>
+
+    <code type="erl" >
+      6> {ok, NewChannelId} =  ssh_connection:session_channel(ConnectionRef, infinity).
+        {ok,1}
+	...
+    </code>
+  </section>
+
+  <section>
+    <title>SFTP (SSH File Transport Protocol) server</title>
+
+    <code type="erl" >
+      1> ssh:start().
+      ok
+      2>  ssh:daemon(8989, [{system_dir, "."},
+      {subsystems, [ssh_sftpd:subsystem_spec([{cwd, "/tmp/sftp/example"}])]}]).
+      {ok,&lt;0.54.0>}
+      3>
+    </code>
+
+    <p> Run the openssh sftp client</p>
+
+    <code type="erl">
+      $bash> sftp -oPort=8989 tarlop
+      Connecting to tarlop...
+      sftp> pwd
+      Remote working directory: /tmp/sftp/example
+      sftp>
+    </code>
+  </section>
+
+  <section>
+    <title>SFTP (SSH File Transport Protocol) client</title>
+
+    <code type="erl" >
+      1> ssh:start().
+      ok
+      2> {ok, ChannelPid, Connection} = ssh_sftp:start_channel("tarlop", []).
+      {ok,&lt;0.57.0>,&lt;0.51.0>}
+      3>  ssh_sftp:read_file(ChannelPid, "/home/otptest/test.txt").
+      {ok,&lt;&lt;"This is a test file\n">>}
+    </code>
+  </section>
+
+  <section>
+    <title>Creating a subsystem</title>
+
+    <p>A very small SSH subsystem that echos N bytes could be implemented like this.</p>
+
+    <code type="erl" >
+-module(ssh_echo_server).
+-behaviour(ssh_channel).
+-record(state, {
+	  n,
+	  id,
+	  cm
+	 }).
+-export([init/1, handle_msg/2, handle_ssh_msg/2, terminate/2]).
+
+init([N]) ->
+    {ok, #state{n = N}}.
+
+handle_msg({ssh_channel_up, ChannelId, ConnectionManager}, State) ->
+    {ok, State#state{id = ChannelId,
+		     cm = ConnectionManager}}.
+
+handle_ssh_msg({ssh_cm, CM, {data, ChannelId, 0, Data}}, #state{n = N} = State) ->
+    M = N - size(Data),
+    case M > 0 of
+	true ->
+	   ssh_connection:send(CM, ChannelId, Data),
+	   {ok, State#state{n = M}};
+	false ->
+	   &lt;&lt;SendData:N/binary, _/binary>> = Data,
+           ssh_connection:send(CM, ChannelId, SendData),
+           ssh_connection:send_eof(CM, ChannelId),
+	   {stop, ChannelId, State}
+    end;
+handle_ssh_msg({ssh_cm, _ConnectionManager,
+		{data, _ChannelId, 1, Data}}, State) ->
+    error_logger:format(standard_error, " ~p~n", [binary_to_list(Data)]),
+    {ok, State};
+
+handle_ssh_msg({ssh_cm, _ConnectionManager, {eof, _ChannelId}}, State) ->
+    {ok, State};
+
+handle_ssh_msg({ssh_cm, _, {signal, _, _}}, State) ->
+    %% Ignore signals according to RFC 4254 section 6.9.
+    {ok, State};
+
+handle_ssh_msg({ssh_cm, _, {exit_signal, ChannelId, _, _Error, _}},
+	       State) ->
+    {stop, ChannelId,  State};
+
+handle_ssh_msg({ssh_cm, _, {exit_status, ChannelId, _Status}}, State) ->
+    {stop, ChannelId, State}.
+
+terminate(_Reason, _State) ->
+    ok.
+ </code>
+
+ <p>And run like this on the host tarlop with the keys generated in section 3.3</p>
+
+ <code type="erl" >
+   1> ssh:start().
+   ok
+   2>  ssh:daemon(8989, [{system_dir, "/tmp/ssh_daemon/ssh_host_rsa_key"},
+   {user_dir, "/tmp/otptest_user/.ssh"}
+   {subsystems, [{"echo_n", {ssh_echo_server, [10]}}]}]).
+   {ok,&lt;0.54.0>}
+   3>
+ </code>
+
+ <code type="erl" >
+   1> ssh:start().
+   ok
+   2>{ok, ConnectionRef} = ssh:connect("tarlop", 8989, [{user_dir, "/tmp/otptest_user/.ssh"}]).
+    {ok,&lt;0.57.0>}
+   3>{ok, ChannelId} = ssh_connection:session_channel(ConnectionRef, infinity).
+   4> success = ssh_connection:subsystem(ConnectionRef, ChannelId, "echo_n", infinity).
+   5> ok = ssh_connection:send(ConnectionRef, ChannelId, "0123456789", infinity),
+   6> flush().
+   {ssh_msg, &lt;0.57.0>, {data, 0, 1, "0123456789"}}
+   {ssh_msg, &lt;0.57.0>, {eof, 0}}
+   {ssh_msg, &lt;0.57.0>, {closed, 0}}
+   7> {error, closed} = ssh_connection:send(ConnectionRef, ChannelId, "10", infinity),
+ </code>
+
+</section>
+
+</chapter>
diff --git a/lib/ssh/src/ssh.app.src b/lib/ssh/src/ssh.app.src
index 316c09eb06..a96c1a510c 100644
--- a/lib/ssh/src/ssh.app.src
+++ b/lib/ssh/src/ssh.app.src
@@ -35,7 +35,7 @@
 	     ssh_userreg,
 	     ssh_xfer]},
   {registered, []},
-  {applications, [kernel, stdlib, crypto]},
+  {applications, [kernel, stdlib, crypto, public_key]},
   {env, []},
   {mod, {ssh_app, []}}]}.
 
diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl
index 9ed6fdbcf8..f163539e75 100644
--- a/lib/ssh/src/ssh.erl
+++ b/lib/ssh/src/ssh.erl
@@ -41,19 +41,23 @@
 %%
 %%  Type =  permanent | transient | temporary
 %%
-%% Description: Starts the inets application. Default type
+%% Description: Starts the ssh application. Default type
 %% is temporary. see application(3)
 %%--------------------------------------------------------------------
 start() ->
+    application:start(crypto),
+    application:start(public_key),
     application:start(ssh).
 
 start(Type) ->
+    application:start(crypto, Type),
+    application:start(public_key, Type),
     application:start(ssh, Type).
 
 %%--------------------------------------------------------------------
 %% Function: stop() -> ok
 %%
-%% Description: Stops the inets application.
+%% Description: Stops the ssh application.
 %%--------------------------------------------------------------------
 stop() ->
     application:stop(ssh).
@@ -325,8 +329,6 @@ handle_option([{user_passwords, _} = Opt | Rest], SocketOptions, SshOptions) ->
     handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]);
 handle_option([{pwdfun, _} = Opt | Rest], SocketOptions, SshOptions) ->
     handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]);
-handle_option([{user_auth, _} = Opt | Rest],SocketOptions, SshOptions ) ->
-    handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]);
 handle_option([{key_cb, _} = Opt | Rest], SocketOptions, SshOptions) ->
     handle_option(Rest, SocketOptions, [handle_ssh_option(Opt) | SshOptions]);
 handle_option([{role, _} = Opt | Rest], SocketOptions, SshOptions) ->
@@ -400,8 +402,6 @@ handle_ssh_option({user_passwords, Value} = Opt) when is_list(Value)->
     Opt;
 handle_ssh_option({pwdfun, Value} = Opt) when is_function(Value) ->
     Opt;
-handle_ssh_option({user_auth, Value} = Opt)  when is_function(Value) ->
-    Opt;
 handle_ssh_option({key_cb, Value} = Opt)  when is_atom(Value) ->
     Opt;
 handle_ssh_option({compression, Value} = Opt) when is_atom(Value) ->
diff --git a/lib/ssh/test/ssh_echo_server.erl b/lib/ssh/test/ssh_echo_server.erl
index 739aabe6fb..64686231e2 100644
--- a/lib/ssh/test/ssh_echo_server.erl
+++ b/lib/ssh/test/ssh_echo_server.erl
@@ -50,7 +50,7 @@ handle_ssh_msg({ssh_cm, CM, {data, ChannelId, 0, Data}}, #state{n = N} = State)
     end;
 handle_ssh_msg({ssh_cm, _ConnectionManager,
 		{data, _ChannelId, 1, Data}}, State) ->
-    error_logger:format("ssh: STDERR: ~s\n", [binary_to_list(Data)]),
+    error_logger:format(standard_error, " ~p~n", [binary_to_list(Data)]),
     {ok, State};
 
 handle_ssh_msg({ssh_cm, _ConnectionManager, {eof, _ChannelId}}, State) ->