From ac4107ceea994f028ae67b43dbe6676b9ccf2b3b Mon Sep 17 00:00:00 2001 From: tmanevik Date: Thu, 19 Mar 2015 14:00:43 +0100 Subject: Editorial updates SSH application --- lib/ssh/doc/src/ssh.xml | 319 +++++++++++++++++++++++++++--------------------- 1 file changed, 181 insertions(+), 138 deletions(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index 0e7e3848ad..bb41a317e5 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -22,54 +22,71 @@ ssh + + 2007-10-06 + ssh - Main API of the SSH application + Main API of the ssh application -

Interface module for the SSH application.

+

Interface module for the ssh application.
SSH - SSH requires the crypto and public_key applications. - Supported SSH version is 2.0 - Supported MAC algorithms: hmac-sha2-256 and hmac-sha1 - Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc - Supports unicode filenames if the emulator and the underlaying OS supports it. See the DESCRIPTION section in file for information about this subject - Supports unicode in shell and cli + SSH requires the crypto and public_key applications. + Supported SSH version is 2.0. + Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. + Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. + Supports unicode filenames if the emulator and the underlaying OS support it. + See section DESCRIPTION in the + file manual page in kernel + for information about this subject. + Supports unicode in shell and CLI.
- DATA TYPES + DATA TYPES

Type definitions that are used more than once in - this module and/or abstractions to indicate the intended use of the data - type:

-

boolean() = true | false

-

string() = [byte()]

-

ssh_daemon_ref() - opaque to the user - returned by ssh:daemon/[1,2,3]

-

ssh_connection_ref() - opaque to the user - returned by ssh:connect/3

-

ip_address() - inet::ip_address()

-

subsystem_spec() = {subsystem_name(), - {channel_callback(), channel_init_args()}}

-

subsystem_name() = string()

-

channel_callback() = atom() - Name of the erlang module - implementing the subsystem using the ssh_channel behavior see - ssh_channel(3)

-

channel_init_args() = list()

-
+ this module, or abstractions to indicate the intended use of the data + type, or both:

+ + boolean() +

= true | false

 + string() +

= [byte()]

 + ssh_daemon_ref() +

Opaque to the user, + returned by ssh:daemon/[1,2,3]

 + ssh_connection_ref() +

Opaque to the user, + returned by ssh:connect/3

 + ip_address() +

inet::ip_address

 + subsystem_spec() +

= {subsystem_name(), + {channel_callback(), channel_init_args()}}

 + subsystem_name() +

= string()

 + channel_callback() +

= atom() - Name of the Erlang module + implementing the subsystem using the ssh_channel behavior, see + ssh_channel(3)

 + channel_init_args() +

= list()

 + + close(ConnectionRef) -> ok - Closes an SSH connection + Closes an SSH connection. ConnectionRef = ssh_connection_ref() @@ -81,135 +98,141 @@ connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()} | {error, Reason} - Connect to an ssh server. + Connects to an SSH server. Host = string() Port = integer() - The default is , the assigned well known port + is default, the assigned well-known port number for SSH. Options = [{Option, Value}] Timeout = infinity | integer(milliseconds) - Negotiation timeout, for connection timeout use the option {connect_timeout, timeout()}. + Negotiation time-out. For connection time-out, use option + {connect_timeout, timeout()}.

Connects to an SSH server. No channel is started. This is done by calling - ssh_connection:session_channel/[2, 4].

-

Options are:

+ + ssh_connection:session_channel/[2, 4].

+

Options:

- IP version to use. + +

IP version to use.

+ -

Sets the user directory i.e. the directory containing - ssh configuration files for the user such as +

Sets the user directory, that is, the directory containing + ssh configuration files for the user, such as , and + id_dsa]]>, and . Defaults to the directory normally referred to as -

+ .

 -

If the user dsa key is protected by a passphrase it can be +

If the user DSA key is protected by a passphrase, it can be supplied with this option.

-

If the user rsa key is protected by a passphrase it can be +

If the user RSA key is protected by a passphrase, it can be supplied with this option.

-

When true hosts are added to the +

When true, hosts are added to the file without asking the user. - Defaults to false. + Defaults to false.

-

If false disables the client to connect to the server - if any user interaction is needed such as accepting that - the server will be added to the known_hosts file or - supplying a password. Defaults to true. +

If false, disables the client to connect to the server + if any user interaction is needed, such as accepting + the server to be added to the known_hosts file, or + supplying a password. Defaults to true. Even if user interaction is allowed it can be - suppressed by other options such as silently_accept_hosts and - password. Do note that it may not always be desirable to use - those options from a security point of view.

+ suppressed by other options, such as silently_accept_hosts + and password. However, those optins are not always desirable + to use from a security point of view.

Sets the preferred public key algorithm to use for user - authentication. If the the preferred algorithm fails for - some reason, the other algorithm is tried. The default is + authentication. If the preferred algorithm fails, + the other algorithm is tried. The default is to try first.

 -

List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available. - Will override

+

List of public key algorithms to try to use. + 'ssh-rsa' and 'ssh-dss' are available. + Overrides

-

Sets a timeout on the transport layer +

Sets a time-out on the transport layer connection. Defaults to infinity.

 -

Provides a user name. If this option is not given, ssh +

Provides a username. If this option is not given, ssh reads from the environment ( or - on unix, + on UNIX, on Windows).

 -

Provide a password for password authentication. If - this option is not given, the user will be asked for a - password if the password authentication method is +

Provides a password for password authentication. + If this option is not given, the user is asked for a + password, if the password authentication method is attempted.

 -

Module implementing the behaviour ssh_client_key_api. +

Module implementing the behaviour + ssh_client_key_api. Can be used to customize the handling of public keys.

-

If true, the client will not print out anything on authorization.

+

If true, the client does not print anything on authorization.

 -

Allow an existing file descriptor to be used - (simply passed on to the transport protocol).

 +

Allows an existing file descriptor to be used + (by passing it on to the transport protocol).

-

Provide, in bytes, when rekeying should be initiated, - defaults to one time each GB and one time per hour.

+

Provides, in bytes, when rekeying is to be initiated. + Defaults to once per each GB and once per hour.

 -

Sets a timeout on connection when no channels are active, default is infinity

 +

Sets a time-out on a connection when no channels are active. + Defaults to infinity.

 connection_info(ConnectionRef, [Option]) ->[{Option, - Value}] - Retrieves information about a connection. + Value}] + Retrieves information about a connection. Option = client_version | server_version | user | peer | sockname Value = [option_value()] - option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | User::string() | - Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | + option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | + User::string() | Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} | Sockname::{inet::ip_adress(), inet::port_number()} () -

Retrieves information about a connection. -

+

Retrieves information about a connection.

 @@ -230,111 +253,127 @@

Starts a server listening for SSH connections on the given port.

-

Options are:

+

Options:

- IP version to use when the host address is specified as any. +

IP version to use when the host address is specified as any.

 - Provides specifications for handling of subsystems. The - "sftp" subsystem spec can be retrieved by calling - ssh_sftpd:subsystem_spec/1. If the subsystems option is - not present the value of - [ssh_sftpd:subsystem_spec([])] will be used. It is - of course possible to set the option to the empty list if - you do not want the daemon to run any subsystems at all. +

Provides specifications for handling of subsystems. The + "sftp" subsystem specification is retrieved by calling + ssh_sftpd:subsystem_spec/1. If the subsystems option is + not present, the value of + [ssh_sftpd:subsystem_spec([])] is used. + The option can be set to the empty list if + you do not want the daemon to run any subsystems.

 pid() | fun(string() = User, ip_address() = PeerAddr) -> pid()}]]> - Defines the read-eval-print loop used when a shell is - requested by the client. Default is to use the erlang shell: - +

Defines the read-eval-print loop used when a shell is + requested by the client. The default is to use the Erlang shell: +

- Provides your own CLI implementation, i.e. a channel callback - module that implements a shell and command execution. Note - that you may customize the shell read-eval-print loop using the - option shell which is much less work than implementing - your own CLI channel. If set to no_cli you will disable - CLI channels and only subsystem channels will be allowed. +

Provides your own CLI implementation, that is, a channel callback + module that implements a shell and command execution. The shell + read-eval-print loop can be customized, using the + option shell. This means less work than implementing + an own CLI channel. If set to no_cli, the CLI channels + are disabled and only subsystem channels are allowed.

 -

Sets the user directory i.e. the directory containing - ssh configuration files for the user such as +

Sets the user directory. That is, the directory containing + ssh configuration files for the user, such as , and + id_dsa]]>, and . Defaults to the directory normally referred to as -

+ .

Sets the system directory, containing the host key files - that identifies the host keys for ssh. The default is - , note that for security reasons - this directory is normally only accessible by the root user.

+ that identify the host keys for ssh. Defaults to + . For security reasons, + this directory is normally accessible only to the root user.

 -

Comma separated string that determines which - authentication methodes that the server should support and - in what order they will be tried. Defaults to +

Comma-separated string that determines which + authentication methods that the server is to support and + in what order they are tried. Defaults to

-

Provide passwords for password authentication.They will - be used when someone tries to connect to the server and - public key user authentication fails. The option provides - a list of valid user names and the corresponding password. +

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 + a list of valid usernames and the corresponding passwords.

-

Provide a global password that will authenticate any +

Provides a global password that authenticates any user. From a security perspective this option makes the server very vulnerable.

 boolean()}]]> -

Provide a function for password validation. This is called - with user and password as strings, and should return +

Provides a function for password validation. This function is called + with user and password as strings, and returns if the password is valid and otherwise.

 -

Max time in milliseconds for the authentication negotiation. The default value is 2 minutes. If the client fails to login within this time, the connection is closed. +

Maximum time in milliseconds for the authentication negotiation. + Defaults to 120000 (2 minutes). If the client fails to log in within this time, + the connection is closed.

-

The maximum number of simultaneous sessions that are accepted at any time for this daemon. This includes sessions that are being authorized. So if set to N, and N clients have connected but not started the login process, the N+1 connection attempt will be aborted. If N connections are authenticated and still logged in, no more loggins will be accepted until one of the existing ones log out. +

The maximum number of simultaneous sessions that are accepted at any time + for this daemon. This includes sessions that are being authorized. + Thus, if set to N, and N clients have connected but not started + the login process, connection attempt N+1 is aborted. + If N connections are authenticated and still logged in, no more logins + are accepted until one of the existing ones log out.

-

The counter is per listening port, so if two daemons are started, one with {max_sessions,N} and the other with {max_sessions,M} there will be in total N+M connections accepted for the whole ssh application. +

The counter is per listening port. Thus, if two daemons are started, one with + {max_sessions,N} and the other with {max_sessions,M}, in total + N+M connections are accepted for the whole ssh application.

-

Note that if parallel_login is false, only one client at a time may be in the authentication phase. +

Notice that if parallel_login is false, only one client + at a time can be in the authentication phase.

-

As default, the option is not set. This means that the number is not limited. +

By default, this option is not set. This means that the number is not limited.

-

If set to false (the default value), only one login is handled a time. If set to true, an unlimited number of login attempts will be allowed simultanously. +

If set to false (the default value), only one login is handled at a time. + If set to true, an unlimited number of login attempts are allowed simultaneously.

-

If the max_sessions option is set to N and parallel_login is set to true, the max number of simultaneous login attempts at any time is limited to N-K where K is the number of authenticated connections present at this daemon. +

If the max_sessions option is set to N and parallel_login + is set to true, the maximum number of simultaneous login attempts at any time is + limited to N-K, where K is the number of authenticated connections present + at this daemon.

-

Do not enable parallel_logins without protecting the server by other means, for example the max_sessions option or a firewall configuration. If set to true, there is no protection against DOS attacks.

+

Do not enable parallel_logins without protecting the server by other means, + for example, by the max_sessions option or a firewall configuration. If set to + true, there is no protection against DOS attacks.

 @@ -346,25 +385,28 @@ -

Module implementing the behaviour ssh_server_key_api. +

Module implementing the behaviour + ssh_server_key_api. Can be used to customize the handling of public keys.

-

Allow an existing file-descriptor to be used - (simply passed on to the transport protocol).

 - _}]]> +

Allows an existing file-descriptor to be used + (passed on to the transport protocol).

+ _}]]> -

Provide a fun to implement your own logging when a user fails to authenticate.

+

Provides a fun to implement your own logging when a user fails to authenticate.

 - _}]]> + _}]]> -

Provide a fun to implement your own logging when a user authenticates to the server.

+

Provides a fun to implement your own logging when a user authenticates to the server.

 _}]]> -

Provide a fun to implement your own logging when a user disconnects from the server.

+

Provides a fun to implement your own logging when a user disconnects from the server.

 @@ -375,16 +417,16 @@ shell(Host) -> shell(Host, Option) -> shell(Host, Port, Option) -> _ - + Starts an interactive shell over an SSH server. - Host = string() - Port = integer() - Options - see ssh:connect/3 + Host = string() + Port = integer() + Options - see ssh:connect/3 -

Starts an interactive shell via an SSH server on the +

Starts an interactive shell over an SSH server on the given Host. The function waits for user input, - and will not return until the remote shell is ended (i.e. + and does not return until the remote shell is ended (that is, exit from the shell).

@@ -393,28 +435,29 @@ start() -> start(Type) -> ok | {error, Reason} - Starts the SSH application. + Starts the SSH application. Type = permanent | transient | temporary Reason = term() -

Utility function that starts crypto, public_key and the SSH - application. Defult type is temporary. - See also application(3) -

+

Utility function that starts the applications crypto, public_key, + and ssh. Default type is temporary. + For more information, see the application(3) + manual page in kernel.

 stop() -> ok | {error, Reason} - Stops the SSH application. + Stops the ssh application. Reason = term() -

Stops the SSH application. See also - application(3)

+

Stops the ssh application. + For more information, see the application(3) + manual page in kernel.

 @@ -438,7 +481,7 @@ stop_listener(DaemonRef) -> stop_listener(Address, Port) -> ok Stops the listener, but leaves existing connections started - by the listener up and running. + by the listener operational. DaemonRef = ssh_daemon_ref() Address = ip_address() @@ -446,7 +489,7 @@

Stops the listener, but leaves existing connections started - by the listener up and running.

+ by the listener operational.

 -- cgit v1.2.3 From 0bf8c6a7954055d672c268f08be37596264a78c5 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 16:00:13 +0200 Subject: ssh: Keep dependency info in only one place --- lib/ssh/doc/src/ssh.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index bb41a317e5..284d7febf8 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -37,7 +37,7 @@ SSH - SSH requires the crypto and public_key applications. + For application dependencies see ssh(6) Supported SSH version is 2.0. Supported MAC algorithms: hmac-sha2-256 and hmac-sha1. Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc. -- cgit v1.2.3