aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc
diff options
context:
space:
mode:
authorHans Nilsson <[email protected]>2018-10-22 16:12:02 +0200
committerHans Nilsson <[email protected]>2018-10-24 10:11:20 +0200
commitd655a343837f4a05ca7a9683d57245734d7482ac (patch)
treee7f1b6c7b2ec86adc163cecdcda0987af1e3d934 /lib/ssh/doc
parent2edaee2a6e134b4792956ad8196833faaa6af43b (diff)
downloadotp-d655a343837f4a05ca7a9683d57245734d7482ac.tar.gz
otp-d655a343837f4a05ca7a9683d57245734d7482ac.tar.bz2
otp-d655a343837f4a05ca7a9683d57245734d7482ac.zip
ssh: Move some option's documentation to ssh_file
user_dir user_dir_fun (missing previously) *_passphrase system_dir
Diffstat (limited to 'lib/ssh/doc')
-rw-r--r--lib/ssh/doc/src/ssh.xml71
-rw-r--r--lib/ssh/doc/src/ssh_app.xml7
-rw-r--r--lib/ssh/doc/src/ssh_file.xml122
-rw-r--r--lib/ssh/doc/src/terminology.xml4
-rw-r--r--lib/ssh/doc/src/using_ssh.xml11
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>