diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 71 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_app.xml | 7 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_file.xml | 122 | ||||
| -rw-r--r-- | lib/ssh/doc/src/terminology.xml | 4 | ||||
| -rw-r--r-- | lib/ssh/doc/src/using_ssh.xml | 11 |
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> |