ssh: Add Users Guide and enhance man pages

1 files changed, 78 insertions, 86 deletions

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>