Merge branch 'maint'

* maint:
  ssh: Re-phrase and adjust the documentation (ssh_file.xml)
  ssh: Move some option's documentation to ssh_file user_dir user_dir_fun (missing previously) *_passphrase system_dir
  ssh: Clearify a couple of options user_dir, system_dir and *_passphrase are only used in the default callback module ssh_file
  ssh: Links updated in ssh.xml
  ssh: Add reference manual page for the ssh_file module
  ssh: Add new User's Guide chapter about SSH terminology The term "user" means different things in OpenSSH and in Erlang/SSH. This new chapter explains why.

1 files changed, 22 insertions, 50 deletions

diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 3bc62073a2..93e52ce023 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -99,8 +99,8 @@
     </p>
 
     <p>The paths could easily be changed by options:
-    <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso> and
-    <seealso marker="#type-system_dir_daemon_option"><c>system_dir</c></seealso>.
+    <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso> and
+    <seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>.
     </p>
     <p>A completly different storage could be interfaced by writing call-back modules
     using the behaviours
@@ -123,12 +123,12 @@
 	  <item><c>ssh_host_ecdsa_key</c> and <c>ssh_host_ecdsa_key.pub</c></item>
 	</list>
 	<p>The host keys directory could be changed with the option 
-	<seealso marker="#type-system_dir_daemon_option"><c>system_dir</c></seealso>.</p>
+	<seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>.</p>
 	</item>
 	<item>Optional: one or more <i>User's public key</i> in case of <c>publickey</c> authorization.
 	Default is to store them concatenated in the file <c>.ssh/authorized_keys</c> in the user's home directory.
 	<p>The user keys directory could be changed with the option 
-	<seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>.</p>
+	<seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>.</p>
 	</item>
       </list>
     </section>
@@ -138,7 +138,7 @@
       <p>The keys and some other data are by default stored in files in the directory <c>.ssh</c>
       in the user's home directory.</p>
       <p>The directory could be changed with the option 
-      <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>.
+      <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>.
       </p>
       <list>
 	<item>Optional: a list of <i>Host public key(s)</i> for previously connected hosts. This list
@@ -192,22 +192,13 @@
 	<p>If there is no public key of a specified type available, the corresponding entry is ignored.
 	Note that the available set is dependent on the underlying cryptolib and current user's public keys.
 	</p>
-        <p>See also the option <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>
+        <p>See also the option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
         for specifying the path to the user's keys.
 	</p>
       </desc>
     </datatype>
 
     <datatype>
-      <name name="pubkey_passphrase_client_options"/>
-      <desc>
-	<p>If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be
-	supplied with thoose options.
-	</p>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="host_accepting_client_options"/>
       <name name="accept_hosts"/>
       <name name="fp_digest_alg"/>
@@ -220,7 +211,7 @@
             <p>This option guides the <c>connect</c> function on how to act when the connected server presents a Host 
             Key that the client has not seen before. The default is to ask the user with a question on stdio of whether to
             accept or reject the new Host Key.
-            See the option <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso>
+            See the option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
             for specifying the path to the file <c>known_hosts</c> where previously accepted Host Keys are recorded.
 	    See also the option 
 	    <seealso marker="#type-key_cb_common_option">key_cb</seealso>
@@ -276,7 +267,7 @@
 	    accept question the next time the same host is connected. If the option
 	    <seealso marker="#type-key_cb_common_option"><c>key_cb</c></seealso>
 	    is not present, the key is saved in the file "known_hosts". See option
-	    <seealso marker="#type-user_dir_common_option"><c>user_dir</c></seealso> for
+	    <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso> for
 	    the location of that file.
 	    </p>
 	    <p>If <c>false</c>, the key is not saved and the key will still be unknown
@@ -478,18 +469,6 @@
       <name name="pwdfun_4"/>
       <desc>
 	<taglist>
-          <tag><marker id="type-system_dir_daemon_option"/><c>system_dir</c></tag>
-          <item>
-            <p>Sets the system directory, containing the host key files
-            that identify the host keys for <c>ssh</c>. Defaults to
-            <c>/etc/ssh</c>.</p>
-	    <p>For security reasons, this directory is normally accessible only to the root user.</p>
-	    <p>See also the option 
-	    <seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	    for the general way to handle keys.
-	    </p>
-	  </item>
-
 	  <tag><c>auth_method_kb_interactive_data</c></tag>
 	  <item>
 	    <p>Sets the text strings that the daemon sends to the client for presentation to the user when
@@ -502,7 +481,7 @@
 	    </p>
           </item>
 
-	  <tag><c>user_passwords</c></tag>
+	  <tag><marker id="option-user_passwords"/><c>user_passwords</c></tag>
 	  <item>
             <p>Provides passwords for password authentication. The passwords are used when someone tries
 	    to connect to the server and public key user-authentication fails. The option provides
@@ -510,7 +489,7 @@
 	    </p>
           </item>
 
-          <tag><c>password</c></tag>
+          <tag><marker id="option-password"/><c>password</c></tag>
           <item>
             <p>Provides a global password that authenticates any user.</p>
 	    <warning>
@@ -519,7 +498,9 @@
 	    </warning>
 	  </item>
 
-	  <tag><c>pwdfun</c> with <c>pwdfun_4()</c></tag>
+	  <tag><marker id="option-pwdfun"/><c>pwdfun</c> with 
+	  <seealso marker="#type-pwdfun_4"><c>pwdfun_4()</c></seealso>
+	  </tag>
 	  <item>
 	    <p>Provides a function for password validation. This could used for calling an external system or handeling
 	    passwords stored as hash values.
@@ -546,7 +527,9 @@
 	    can be used for this. The return value <c>disconnect</c> is useful for this.</p>
 	  </item>
 
-	  <tag><c>pwdfun</c> with <c>pwdfun_2()</c></tag>
+	  <tag><c>pwdfun</c> with
+	  <seealso marker="#type-pwdfun_2"><c>pwdfun_2()</c></seealso>
+	  </tag>
 	  <item>
 	    <p>Provides a function for password validation. This function is called with user and password
 	    as strings, and returns:</p>
@@ -725,21 +708,6 @@
     </datatype>
 
     <datatype>
-      <name name="user_dir_common_option"/>
-      <desc>
-	<p>Sets the user directory. That is, the directory containing <c>ssh</c> configuration
-	files for the user, such as 
-	<c>known_hosts</c>, <c>id_rsa</c>, <c>id_dsa</c>>, <c>id_ecdsa</c> and <c>authorized_key</c>.
-	Defaults to the directory normally referred to as <c>~/.ssh</c>.
-	</p>
-	<p>See also the option 
-	<seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	for the general way to handle keys.
-	</p>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="profile_common_option"/>
       <desc>
 	<p>Used together with <c>ip-address</c> and <c>port</c> to
@@ -795,7 +763,8 @@
 	</p>
 	<p>The <c>Opts</c> defaults to <c>[]</c> when only the <c>Module</c> is specified.
 	</p>
-	<p>The default value of this option is <c>{ssh_file, []}</c>.
+	<p>The default value of this option is <c>{ssh_file, []}</c>. See also the manpage of
+	<seealso marker="ssh:ssh_file">ssh_file</seealso>.
 	</p>
 	<p>A call to the call-back function <c>F</c> will be</p>
 	<code>
@@ -804,7 +773,10 @@
 	<p>where <c>...</c> are arguments to <c>F</c> as in 
 	<seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and/or
 	<seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
-	The <c>UserOptions</c> are the options given to <c>ssh:connect</c>, <c>ssh:shell</c> or <c>ssh:daemon</c>.
+	The <c>UserOptions</c> are the options given to 
+	<seealso marker="ssh:ssh#connect-3">ssh:connect</seealso>,
+	<seealso marker="ssh:ssh#shell-1">ssh:shell</seealso> or
+	<seealso marker="ssh:ssh#daemon-2">ssh:daemon</seealso>.
 	</p>
 
       </desc>