ssh: Move some option's documentation to ssh_file

user_dir
user_dir_fun (missing previously)
*_passphrase
system_dir

5 files changed, 112 insertions, 103 deletions

diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index e674991748..b75b4a33c2 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,28 +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>
-	<note>
-	  <p>Those options can only be used if the module in
-	  <seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	  handles that option. That is the case with the default value of the <c>key_cb</c> option.
-	  </p>
-	</note>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="host_accepting_client_options"/>
       <name name="accept_hosts"/>
       <name name="fp_digest_alg"/>
@@ -226,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>
@@ -282,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
@@ -484,24 +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>
-	    <note>
-	      <p>This option can only be used if the module in
-	      <seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	      handles that option. That is the case with the default value of the <c>key_cb</c> option.
-	      </p>
-	    </note>
-	  </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
@@ -741,28 +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> where ~ is the home directory of the user
-	that the Erlang executes as.
-	</p>
-	<p>See also the option 
-	<seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	for the general way to handle keys.
-	</p>
-	<note>
-	  <p>This option can only be used if the module in
-	  <seealso marker="#type-key_cb_common_option">key_cb</seealso>
-	  handles that option. That is the case with the default value of the <c>key_cb</c> option.
-	  </p>
-	</note>
-      </desc>
-    </datatype>
-
-    <datatype>
       <name name="profile_common_option"/>
       <desc>
 	<p>Used together with <c>ip-address</c> and <c>port</c> to
diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml
index e80bb1853d..eb804e67dc 100644
--- a/lib/ssh/doc/src/ssh_app.xml
+++ b/lib/ssh/doc/src/ssh_app.xml
@@ -74,13 +74,18 @@
       <c>id_ecdsa_key</c>,
       <c>known_hosts</c>, and <c>authorized_keys</c> in ~/.ssh,
       and for the host key files in <c>/etc/ssh</c>. These locations can be changed
-      by the options <c>user_dir</c> and <c>system_dir</c>.
+      by the options
+      <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>Public key handling can also be customized through a callback module that
       implements the behaviors
       <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and
       <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
       </p>
+      <p>See also the default callback module documentation in
+      <seealso marker="ssh_file">ssh_file</seealso>.
+      </p>
 
   </section>
   <section>
diff --git a/lib/ssh/doc/src/ssh_file.xml b/lib/ssh/doc/src/ssh_file.xml
index 910c6698fc..20dcb86fd6 100644
--- a/lib/ssh/doc/src/ssh_file.xml
+++ b/lib/ssh/doc/src/ssh_file.xml
@@ -34,37 +34,52 @@
     <p>This module is the default callback handler for the client's and the server's user and host "database" operations.
     </p>
     <p>
-      The intention is to be compatible with the OpenSSH storage in files. Therefore it mimics directories and filenames
-      of OpenSSH.
+      The intention is to be compatible with the
+      <url href="http://www.openssh.com">OpenSSH</url>
+      storage in files. Therefore it mimics directories and filenames of
+      <url href="http://www.openssh.com">OpenSSH</url>.
     </p>
     <note>
       <p>The functions are <i>Callbacks</i> for the SSH app. They are not intended to be called from the user's code!
       </p>
     </note>
   </description>
-    <section>
-      <title>Making your own callback module</title>
-      <p>Ssh_file implements the <seealso marker="ssh:ssh_server_key_api">ssh_server_key_api</seealso> and
-      <seealso marker="ssh:ssh_client_key_api">ssh_client_key_api</seealso>.
-	This enables the user to make an own interface using for example a database handler.
-      </p>
-      <p>Such another callback module could be used by setting the option
-      <seealso marker="ssh:ssh#type-key_cb_common_option"><c>key_cb</c></seealso>
-      when starting a client or a server (with for example
-      <seealso marker="ssh:ssh#connect-3">ssh:connect</seealso>,
-      <seealso marker="ssh:ssh#daemon-2">ssh:daemon</seealso> of
-      <seealso marker="ssh:ssh#shell-1">ssh:shell</seealso>
-      ).
-      </p>
-    </section>
+  <section>
+    <title>Making your own callback module</title>
+    <p>Ssh_file implements the <seealso marker="ssh:ssh_server_key_api">ssh_server_key_api</seealso> and
+    <seealso marker="ssh:ssh_client_key_api">ssh_client_key_api</seealso>.
+    This enables the user to make an own interface using for example a database handler.
+    </p>
+    <p>Such another callback module could be used by setting the option
+    <seealso marker="ssh:ssh#type-key_cb_common_option"><c>key_cb</c></seealso>
+    when starting a client or a server (with for example
+    <seealso marker="ssh:ssh#connect-3">ssh:connect</seealso>,
+    <seealso marker="ssh:ssh#daemon-2">ssh:daemon</seealso> of
+    <seealso marker="ssh:ssh#shell-1">ssh:shell</seealso>
+    ).
+    </p>
+  </section>
+
+  <section>
+    <title>Daemons</title>
+    <p>Daemons uses all files stored in the <seealso marker="#SYSDIR">SYSDIR</seealso> directory and
+    optionaly one or more <i>User's public key</i> in case of <c>publickey</c> authorization.
+    The user's public keys are stored concatenated in the file 
+    <seealso marker="#USERDIR-authorized_keys"><c>authorized_keys</c></seealso>
+    in the
+    <seealso marker="#USERDIR">USERDIR</seealso> directory.
+    </p>
+  </section>
+
+  <section>
+    <title>Clients</title>
+    <p>Clients uses all files stored in the <seealso marker="#USERDIR">USERDIR</seealso> directory.
+    </p>
+  </section>
 
   <section>
     <title>Files, directories and conventions</title>
     <taglist>
-      <!--tag><marker id="REMOTEUSER"/>REMOTEUSER</tag>
-      <item>The user name sent by the client to the server.
-      <p/></item-->
-
       <tag><marker id="LOCALUSER"/>LOCALUSER</tag>
       <item>The user name of the OS process running the Erlang virtual machine (emulator).
       <p/></item>
@@ -78,6 +93,10 @@
       </list>
       <p>At least one host key must be defined. The default value of SYSDIR is <marker id="#/etc/ssh"/><c>/etc/ssh</c>.
       </p>
+      <p>For security reasons, this directory is normally accessible only to the root user.
+      </p>
+      <p>To change the SYSDIR, see the <seealso marker="#type-system_dir_daemon_option">system_dir</seealso> option.
+      </p>
       </item>
 
       <tag><marker id="USERDIR"/>USERDIR</tag>
@@ -91,12 +110,51 @@
 	  <item><marker id="USERDIR-id_ecdsa"/><c>id_ecdsa</c> - private ecdsa user key (optional)</item>
       </list>
       <p>The default value of USERDIR is <c>/home/</c><seealso marker="#LOCALUSER"><c>LOCALUSER</c></seealso><c>/.ssh</c>.
-      See also the <seealso marker="ssh:ssh#type-user_dir_common_option">user_dir</seealso> common option.
-      </p></item>
+      </p>
+      <p>To change the USERDIR, see the <seealso marker="#type-user_dir_common_option">user_dir</seealso> option
+      </p>
+    </item>
       
     </taglist>
   </section>
 
+  <datatypes>
+    <datatype_title>Options for the default ssh_file callback module</datatype_title>
+    <datatype>
+      <name name="user_dir_common_option"/>
+      <desc>
+	<p>Sets the <seealso marker="#USERDIR">user directory</seealso>.</p>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="user_dir_fun_common_option"/>
+      <desc>
+	<p>Sets the <seealso marker="#USERDIR">user directory</seealso> dynamically
+	by evaluating the function
+	</p>
+	<code> fun(RemoteUser) -> USERDIR end </code>
+      </desc>
+    </datatype>
+
+    <datatype>
+      <name name="system_dir_daemon_option"/>
+      <desc>
+        <p>Sets the <seealso marker="#SYSDIR">system directory</seealso>.</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>
+
+  </datatypes>
+
   <funcs>
     <func>
       <name>host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason}</name>
@@ -108,7 +166,7 @@
 	</p>
 	<p><strong>Options</strong></p>
 	<list>
-	  <item><c>{system_dir, </c><seealso marker="#SYSDIR">SYSDIR</seealso><c>}</c></item>
+	  <item><seealso marker="#type-system_dir_daemon_option">system_dir</seealso></item>
 	  <!-- item>dsa_pass_phrase</item -->
 	  <!-- item>rsa_pass_phrase</item -->
 	  <!-- item>ecdsa_pass_phrase</item -->
@@ -133,8 +191,8 @@
 	</p>
 	<p><strong>Options</strong></p>
 	<list>
-	  <item><marker id="user_dir_fun"/><c>{user_dir_fun, fun(RemoteUser) -> USERDIR end}</c></item>
-	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	  <item><seealso marker="#type-user_dir_fun_common_option">user_dir_fun</seealso></item>
+	  <item><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
 	</list>
 	<p><strong>Files</strong></p>
 	<list>
@@ -155,7 +213,7 @@
 	</p>
 	<p><strong>Option</strong></p>
 	<list>
-	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	  <item><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
 	</list>
 	<p><strong>File</strong></p>
 	<list>
@@ -175,7 +233,7 @@
 	</p>
 	<p><strong>Option</strong></p>
 	<list>
-	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
+	  <item><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
 	</list>
 	<p><strong>File</strong></p>
 	<list>
@@ -195,10 +253,10 @@
 	</p>
 	<p><strong>Options</strong></p>
 	<list>
-	  <item><c>{user_dir, </c><seealso marker="#USERDIR"><c>USERDIR</c></seealso><c>}</c></item>
-	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{dsa_pass_phrase, PWD}</c></seealso></item>
-	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{rsa_pass_phrase, PWD}</c></seealso></item>
-	  <item><seealso marker="ssh:ssh#type-pubkey_passphrase_client_options"><c>{ecdsa_pass_phrase, PWD}</c></seealso></item>
+	  <item><seealso marker="#type-user_dir_common_option">user_dir</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">dsa_pass_phrase</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">rsa_pass_phrase</seealso></item>
+	  <item><seealso marker="#type-pubkey_passphrase_client_options">ecdsa_pass_phrase</seealso></item>
 	</list>
 	<p><strong>Files</strong></p>
 	<list>
diff --git a/lib/ssh/doc/src/terminology.xml b/lib/ssh/doc/src/terminology.xml
index 874a03b36e..db1e08970d 100644
--- a/lib/ssh/doc/src/terminology.xml
+++ b/lib/ssh/doc/src/terminology.xml
@@ -147,11 +147,11 @@
 		are searched in a directory found in the following order:
 		<list>
 		  <item>If the option
-		  <seealso marker="ssh:ssh_file#user_dir_fun"><c>user_dir_fun</c></seealso>
+		  <seealso marker="ssh:ssh_file#type-user_dir_fun_common_option"><c>user_dir_fun</c></seealso>
 		  is defined, that fun is called and the returned directory is used,
 		  </item>
 		  <item>Else, If the option 
-		  <seealso marker="ssh:ssh#type-user_dir_common_option"><c>user_dir</c></seealso>
+		  <seealso marker="ssh:ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
 			is defined, that directory is used,
 		  </item>
 		  <item>Else the subdirectory <c>.ssh</c> in the home directory of the user executing
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 80662e9a70..4455d5ecc5 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -74,16 +74,17 @@
     <marker id="Running an Erlang ssh Daemon"></marker>
     <title>Running an Erlang ssh Daemon</title>
 
-    <p>The <c>system_dir</c> option must be a directory containing a host
-    key file and it defaults to <c>/etc/ssh</c>. For details, see Section
-    Configuration Files in <seealso
-    marker="SSH_app">ssh(6)</seealso>.
+    <p>The
+    <seealso marker="ssh_file#type-system_dir_daemon_option"><c>system_dir</c></seealso>
+    option must be a directory containing a host key file and it defaults to <c>/etc/ssh</c>.
+    For details, see Section Configuration Files in <seealso marker="SSH_app">ssh(6)</seealso>.
     </p>
 
     <note><p>Normally, the <c>/etc/ssh</c> directory is only readable by root.</p>
     </note>
 
-    <p>The option <c>user_dir</c> defaults to directory <c>users ~/.ssh</c>.</p>
+    <p>The option <seealso marker="ssh_file#type-user_dir_common_option"><c>user_dir</c></seealso>
+    defaults to directory <c>users ~/.ssh</c>.</p>
 
     <p><em>Step 1.</em> To run the example without root privileges,
     generate new keys and host keys:</p>