From 2084f7e079c951fdadebe23dcff5ec247c6e0158 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 10 Oct 2012 15:27:10 +0200 Subject: ssh: Add Users Guide and enhance man pages --- lib/ssh/doc/src/ssh.xml | 164 +++++++++++++++++++++++------------------------- 1 file changed, 78 insertions(+), 86 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 9f8efebbf5..907d0efc5c 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -22,13 +22,7 @@ ssh - Ingela Anderton Andin - Håkan Mattsson - - Håkan Mattsson - 2007-10-06 - PA1 ssh Main API of the SSH application @@ -40,18 +34,19 @@ SSH - ssh requires the crypto and public_key applications. - Supported SSH-version is 2.0 - Currently supports only a minimum of mac and encryption algorithms i.e. - hmac-sha1, and aes128-cb and 3des-cbc. + SSH requires the crypto and public_key applications. + Supported SSH version is 2.0 + Supported MAC algorithms: hmac-sha1 + Supported encryption algorithms: aes128-cb and 3des-cbc
- COMMON DATA TYPES + DATA TYPES

Type definitions that are used more than once in - this module:

+ this module and/or abstractions to indicate the intended use of the data + type:

boolean() = true | false

string() = list of ASCII characters

ssh_daemon_ref() - opaque to the user @@ -60,60 +55,64 @@ returned by ssh:connect/3

ip_address() - {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

-

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

+

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 a ssh connection + Closes an SSH connection ConnectionRef = ssh_connection_ref() -

Closes a ssh connection.

+

Closes an SSH connection.

 connect(Host, Port, Options) -> - connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()} - | {error, Reason} + connect(Host, Port, Options, Timeout) -> {ok, + ssh_connection_ref()} | {error, Reason} Connect to an ssh server. Host = string() Port = integer() - The default is , the registered port for SSH. + The default is , the assigned well known port + number for SSH. Options = [{Option, Value}] Timeout = infinity | integer(milliseconds) -

Connects to an SSH server. No channel is started this is done +

Connects to an SSH server. No channel is started. This is done by calling ssh_connect:session_channel/2.

Options are:

-

Sets the user directory e.i. the directory containing +

Sets the user directory i.e. the directory containing ssh configuration files for the user such as - , and - . Defaults to the directory normally - referred to as

+ , and + . Defaults to the + directory normally referred to as +

-

If the user dsa key is protected by a pass phrase 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 pass phrase it can be +

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

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

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

 @@ -149,11 +148,12 @@ -

Sets a timeout on the transport layer connection. Defaults to infinity.

+

Sets a timeout on the transport layer + connection. Defaults to infinity.

 -

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

Provides a user name. If this option is not given, ssh reads from the environment ( or on unix, on Windows).

@@ -165,23 +165,9 @@ password if the password authentication method is attempted.

 - - -

Provide a fun for password authentication. The fun - will be called as and - should return or .

- -

Provide a special call-back module for key handling. - The call-back module should be modeled after the - module. The functions that must - be exported are: - , - , - and - . This is considered - somewhat experimental and will be better documented later on.

+

TODO:

 @@ -189,7 +175,7 @@ -

Allow an existing file-descriptor to be used +

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

 @@ -202,7 +188,8 @@ - connection_info(ConnectionRef, [Option]) ->[{Option, Value}] + connection_info(ConnectionRef, [Option]) ->[{Option, + Value}] Retrieves information about a connection. Option = client_version | server_version | peer @@ -217,7 +204,8 @@ daemon(Port) -> daemon(Port, Options) -> - daemon(HostAddress, Port, Options) -> {ok, ssh_daemon_ref()} | {error, atom()} + daemon(HostAddress, Port, Options) -> {ok, + ssh_daemon_ref()} | {error, atom()} Starts a server listening for SSH connections on the given port. @@ -228,30 +216,32 @@ Value = term() -

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

- -

Options are:

+

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

+

Options are:

- Provides specifications for handling of subsystems. The - "sftp" subsystem-spec can be retrieved by calling - ssh_sftpd:subsystem_spec/1. If the subsystems option in 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 spec can be retrieved by calling + ssh_sftpd:subsystem_spec/1. If the subsystems option in + 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. - pid() | - fun(string() = User, ip_address() = PeerAddr) -> pid()}]]> + pid() | fun(string() = User, + ip_address() = PeerAddr) -> pid()}]]> - Defines the read-eval-print loop used when a shell is requested - by the client. Example use the - erlang shell: which is - the default behavior. + Defines the read-eval-print loop used when a shell is + requested by the client. Default is to use the erlang shell: + - + - Provide your own cli implementation, e.i. a channel callback + 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 @@ -259,27 +249,30 @@ -

Sets the user directory e.i. the directory containing +

Sets the user directory i.e. the directory containing ssh configuration files for the user such as - , and - . Defaults to the directory normally - referred to as

+ , and + . Defaults to the + directory normally referred to as +

-

Sets the system directory, containing the host files - that identifies the host for ssh. The default is - , note that SSH normally - requires the host files there to be readable only by - root.

+

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.

 -

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 methodes that the server should support and + in what order they will be tried. Defaults to

- +

Provide passwords for password authentication.They will be used when someone tries to connect to the server and @@ -293,7 +286,7 @@ 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 @@ -335,9 +328,9 @@ Options - see ssh:connect/3 -

Starts an interactive shell to an SSH server on the +

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

@@ -346,25 +339,24 @@ start() -> start(Type) -> ok | {error, Reason} - Starts the Ssh application. + Starts the SSH application. Type = permanent | transient | temporary Reason = term() -

Starts the Ssh application. Default type - is temporary. See also - application(3) - Requires that the crypto application has been started. +

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

stop() -> ok - Stops the Ssh application. + Stops the SSH application. -

Stops the Ssh application. See also +

Stops the SSH application. See also application(3)

 -- cgit v1.2.3