From d655a343837f4a05ca7a9683d57245734d7482ac Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 22 Oct 2018 16:12:02 +0200 Subject: ssh: Move some option's documentation to ssh_file user_dir user_dir_fun (missing previously) *_passphrase system_dir --- lib/ssh/doc/src/ssh.xml | 71 +++-------------------- lib/ssh/doc/src/ssh_app.xml | 7 ++- lib/ssh/doc/src/ssh_file.xml | 122 +++++++++++++++++++++++++++++----------- lib/ssh/doc/src/terminology.xml | 4 +- lib/ssh/doc/src/using_ssh.xml | 11 ++-- 5 files changed, 112 insertions(+), 103 deletions(-) (limited to 'lib/ssh/doc') 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 @@

The paths could easily be changed by options: - user_dir and - system_dir. + user_dir and + system_dir.

A completly different storage could be interfaced by writing call-back modules using the behaviours @@ -123,12 +123,12 @@ ssh_host_ecdsa_key and ssh_host_ecdsa_key.pub

The host keys directory could be changed with the option - system_dir.

+ system_dir.

Optional: one or more User's public key in case of publickey authorization. Default is to store them concatenated in the file .ssh/authorized_keys in the user's home directory.

The user keys directory could be changed with the option - user_dir.

+ user_dir.

 @@ -138,7 +138,7 @@

The keys and some other data are by default stored in files in the directory .ssh in the user's home directory.

The directory could be changed with the option - user_dir. + user_dir.

Optional: a list of Host public key(s) for previously connected hosts. This list @@ -192,27 +192,12 @@

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.

-

See also the option user_dir +

See also the option user_dir for specifying the path to the user's keys.

- - - -

If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be - supplied with thoose options. -

- -

Those options can only be used if the module in - key_cb - handles that option. That is the case with the default value of the key_cb option. -

- - - - @@ -226,7 +211,7 @@

This option guides the connect 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 user_dir + See the option user_dir for specifying the path to the file known_hosts where previously accepted Host Keys are recorded. See also the option key_cb @@ -282,7 +267,7 @@ accept question the next time the same host is connected. If the option key_cb is not present, the key is saved in the file "known_hosts". See option - user_dir for + user_dir for the location of that file.

If false, the key is not saved and the key will still be unknown @@ -484,24 +469,6 @@ - system_dir - -

Sets the system directory, containing the host key files - that identify the host keys for ssh. Defaults to - /etc/ssh.

-

For security reasons, this directory is normally accessible only to the root user.

-

See also the option - key_cb - for the general way to handle keys. -

- -

This option can only be used if the module in - key_cb - handles that option. That is the case with the default value of the key_cb option. -

- - - auth_method_kb_interactive_data

Sets the text strings that the daemon sends to the client for presentation to the user when @@ -740,28 +707,6 @@ - - - -

Sets the user directory. That is, the directory containing ssh configuration - files for the user, such as - known_hosts, id_rsa, id_dsa>, id_ecdsa and authorized_key. - Defaults to the directory normally referred to as ~/.ssh where ~ is the home directory of the user - that the Erlang executes as. -

-

See also the option - key_cb - for the general way to handle keys. -

- -

This option can only be used if the module in - key_cb - handles that option. That is the case with the default value of the key_cb option. -

- - - - 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 @@ id_ecdsa_key, known_hosts, and authorized_keys in ~/.ssh, and for the host key files in /etc/ssh. These locations can be changed - by the options user_dir and system_dir. + by the options + user_dir and + system_dir.

Public key handling can also be customized through a callback module that implements the behaviors ssh_client_key_api and ssh_server_key_api.

+

See also the default callback module documentation in + ssh_file. +

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 @@

This module is the default callback handler for the client's and the server's user and host "database" operations.

- 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 + OpenSSH + storage in files. Therefore it mimics directories and filenames of + OpenSSH.

The functions are Callbacks for the SSH app. They are not intended to be called from the user's code!

-
- Making your own callback module -

Ssh_file implements the ssh_server_key_api and - ssh_client_key_api. - This enables the user to make an own interface using for example a database handler. -

-

Such another callback module could be used by setting the option - key_cb - when starting a client or a server (with for example - ssh:connect, - ssh:daemon of - ssh:shell - ). -

-
+
+ Making your own callback module +

Ssh_file implements the ssh_server_key_api and + ssh_client_key_api. + This enables the user to make an own interface using for example a database handler. +

+

Such another callback module could be used by setting the option + key_cb + when starting a client or a server (with for example + ssh:connect, + ssh:daemon of + ssh:shell + ). +

+
+ +
+ Daemons +

Daemons uses all files stored in the SYSDIR directory and + optionaly one or more User's public key in case of publickey authorization. + The user's public keys are stored concatenated in the file + authorized_keys + in the + USERDIR directory. +

+
+ +
+ Clients +

Clients uses all files stored in the USERDIR directory. +

+
Files, directories and conventions - - LOCALUSER The user name of the OS process running the Erlang virtual machine (emulator).

@@ -78,6 +93,10 @@

At least one host key must be defined. The default value of SYSDIR is /etc/ssh.

+

For security reasons, this directory is normally accessible only to the root user. +

+

To change the SYSDIR, see the system_dir option. +

USERDIR @@ -91,12 +110,51 @@ id_ecdsa - private ecdsa user key (optional)

The default value of USERDIR is /home/LOCALUSER/.ssh. - See also the user_dir common option. -

+

+

To change the USERDIR, see the user_dir option +

+
+ + Options for the default ssh_file callback module + + + +

Sets the user directory.

+ + + + + + +

Sets the user directory dynamically + by evaluating the function +

+ fun(RemoteUser) -> USERDIR end + + + + + + +

Sets the system directory.

+ + + + + + +

If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be + supplied with thoose options. +

+ + + + + host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason} @@ -108,7 +166,7 @@

Options

- {system_dir, SYSDIR} + system_dir @@ -133,8 +191,8 @@

Options

- {user_dir_fun, fun(RemoteUser) -> USERDIR end} - {user_dir, USERDIR} + user_dir_fun + user_dir

Files

@@ -155,7 +213,7 @@

Option

- {user_dir, USERDIR} + user_dir

File

@@ -175,7 +233,7 @@

Option

- {user_dir, USERDIR} + user_dir

File

@@ -195,10 +253,10 @@

Options

- {user_dir, USERDIR} - {dsa_pass_phrase, PWD} - {rsa_pass_phrase, PWD} - {ecdsa_pass_phrase, PWD} + user_dir + dsa_pass_phrase + rsa_pass_phrase + ecdsa_pass_phrase

Files

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: If the option - user_dir_fun + user_dir_fun is defined, that fun is called and the returned directory is used, Else, If the option - user_dir + user_dir is defined, that directory is used, Else the subdirectory .ssh 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 @@ Running an Erlang ssh Daemon -

The system_dir option must be a directory containing a host - key file and it defaults to /etc/ssh. For details, see Section - Configuration Files in ssh(6). +

The + system_dir + option must be a directory containing a host key file and it defaults to /etc/ssh. + For details, see Section Configuration Files in ssh(6).

Normally, the /etc/ssh directory is only readable by root.

 -

The option user_dir defaults to directory users ~/.ssh.

+

The option user_dir + defaults to directory users ~/.ssh.

Step 1. To run the example without root privileges, generate new keys and host keys:

-- cgit v1.2.3