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/introduction.xml | 182 +++++++++++-- lib/ssh/doc/src/ref_man.xml | 4 +- lib/ssh/doc/src/ssh.xml | 319 +++++++++++++---------- lib/ssh/doc/src/ssh_app.xml | 120 +++++---- lib/ssh/doc/src/ssh_channel.xml | 288 +++++++++++---------- lib/ssh/doc/src/ssh_client_key_api.xml | 96 +++---- lib/ssh/doc/src/ssh_connection.xml | 454 +++++++++++++++++---------------- lib/ssh/doc/src/ssh_server_key_api.xml | 75 +++--- lib/ssh/doc/src/ssh_sftp.xml | 224 ++++++++-------- lib/ssh/doc/src/ssh_sftpd.xml | 56 ++-- lib/ssh/doc/src/usersguide.xml | 7 +- lib/ssh/doc/src/using_ssh.xml | 122 +++++---- 12 files changed, 1128 insertions(+), 819 deletions(-) diff --git a/lib/ssh/doc/src/introduction.xml b/lib/ssh/doc/src/introduction.xml index b42910cb34..70c6fb2ee1 100644 --- a/lib/ssh/doc/src/introduction.xml +++ b/lib/ssh/doc/src/introduction.xml @@ -25,31 +25,181 @@ Introduction OTP team + + + + + + introduction.xml - +

SSH is a protocol for secure remote logon and + other secure network services over an insecure network.

- Purpose + Scope and Purpose -

Secure Shell (SSH) is a protocol for secure remote login and - other secure network services over an insecure network. SSH - provides a single, full-duplex, byte-oriented connection between +

SSH provides a single, full-duplex, and byte-oriented connection between client and server. The protocol also provides privacy, integrity, - server authentication and man-in-the-middle protection.

- -

The Erlang SSH application is an implementation of the SSH - protocol in Erlang which offers API functions to write customized - SSH clients and servers as well as making the Erlang shell - available via SSH. Also included in the SSH application are an - SFTP (SSH File Transfer Protocol) client ssh_sftp and server ssh_sftpd.

+ server authentication, and man-in-the-middle protection.

+ +

The ssh application is an implementation of the SSH Transport + Layer Protocol in Erlang. It provides the following:

+ + API functions to write customized SSH clients and servers + The Erlang shell available through SSH + An SFTP client (ssh_sftp) + and server (ssh_sftpd) +
Prerequisites -

It is assumed that the reader is familiar with the concepts of OTP - and has a basic understanding of public keys.

+

It is assumed that the reader is familiar with the Erlang programming language, + concepts of OTP, and has a basic understanding of public keys.

+
+ +
+ SSH Protocol Overview + +

Conceptually, the SSH protocol can be partitioned into four + layers:

+ + + SSH Protocol Architecture + + +
+ Transport Protocol + +

The SSH Transport Protocol is a secure, low-level transport. + It provides strong encryption, cryptographic host + authentication, and integrity protection. A minimum of + Message Authentication Code (MAC) and encryption + algorithms are supported. For details, see the + ssh(3) manual page in ssh.

+
+ +
+ Authentication Protocol + +

The SSH Authentication Protocol is a general-purpose user + authentication protocol run over the SSH Transport Layer + Protocol. The ssh application supports user authentication as follows: +

+ + + Using public key technology. RSA and DSA, X509-certificates + are not supported. + + + Using keyboard-interactive authentication. + This is suitable for interactive authentication methods + that do not need any special software support on the client side. + Instead, all authentication data is entered from the keyboard. + + + Using a pure password-based authentication scheme. + Here, the plain text password is encrypted before sent + over the network. + + +

Several configuration options for + authentication handling are available in + ssh:connect/[3,4] + and ssh:daemon/[2,3].

+

+ The public key handling can be customized by implementing + the following behaviours from ssh:

+ + Module + ssh_client_key_api. + + Module + ssh_server_key_api. + + +
+ +
+ Connection Protocol + +

The SSH Connection Protocol provides application-support + services over the transport pipe, for example, channel multiplexing, + flow control, remote program execution, signal propagation, and + connection forwarding. Functions for handling the SSH + Connection Protocol can be found in the module ssh_connection in ssh. +

+
+ +
+ Channels + +

All terminal sessions, forwarded connections, and so on, are + channels. Multiple channels are multiplexed into a single + connection. All channels are flow-controlled. This means that no + data is sent to a channel peer until a message is received to + indicate that window space is available. + The initial window size specifies how many bytes of channel + data that can be sent to the channel peer without adjusting the + window. Typically, an SSH client opens a channel, sends data (commands), + receives data (control information), and then closes the channel. + The ssh_channel behaviour + handles generic parts of SSH channel management. This makes it easy + to write your own SSH client/server processes that use flow-control + and thus opens for more focus on the application logic. +

+ +

Channels come in the following three flavors:

+ + + Subsystem - Named services that can be run as + part of an SSH server, such as SFTP (ssh_sftpd), that is built into the + SSH daemon (server) by default, but it can be disabled. The Erlang ssh + daemon can be configured to run any Erlang- + implemented SSH subsystem. + + Shell - Interactive shell. By default the + Erlang daemon runs the Erlang shell. The shell can be customized by + providing your own read-eval-print loop. You can also provide your + own Command-Line Interface (CLI) implementation, + but that is much more work. + + Exec - One-time remote execution of commands. See function + ssh_connection:exec/4 + for more information. + +
+ + +
+
+ Where to Find More Information +

+ For detailed information about the SSH protocol, refer to the + following Request for Comments(RFCs): +

+ + + RFC 4250 - + Protocol Assigned Numbers + RFC 4251 - + Protocol Architecture + RFC 4252 - + Authentication Protocol + RFC 4253 - + Transport Layer Protocol + RFC 4254 - + Connection Protocol + RFC 4255 - + Key Fingerprints + RFC 4344 - + Transport Layer Encryption Modes + RFC 4716 - + Public Key File Format + +
diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml index 55339298e8..afe3f2ddf9 100644 --- a/lib/ssh/doc/src/ref_man.xml +++ b/lib/ssh/doc/src/ref_man.xml @@ -28,8 +28,8 @@ ref_man.xml -

The SSH application is an erlang implementation of the - secure shell protocol (SSH) as defined by RFC 4250 - 4254

+

The ssh application is an Erlang implementation of the + Secure Shell Protocol (SSH) as defined by RFC 4250 - 4254.

 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.

 diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index a1d2402790..498565057f 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -18,78 +18,98 @@ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - SSH + + + + + ssh_app.xml SSH - The ssh application implements the SSH (Secure Shell) protocol and - provides an SFTP (SSH File Transfer Protocol) client and server. + The ssh application implements the Secure Shell (SSH) protocol and + provides an SSH File Transfer Protocol (SFTP) client and server. + +

The ssh application is an implementation of the SSH protocol in Erlang. + ssh offers API functions to write customized SSH clients and servers as well as + making the Erlang shell available over SSH. An SFTP client, ssh_sftp, and server, + ssh_sftpd, are also included.

+ -
+
DEPENDENCIES -

The ssh application uses the Erlang applications public_key and - crypto to handle public keys and encryption, hence these - applications needs to be loaded for the ssh application to work. In - an embedded environment that means they need to be started with - application:start/[1,2] before the ssh application is started. +

The ssh application uses the applications public_key and + crypto to handle public keys and encryption. Hence, these + applications must be loaded for the ssh application to work. In + an embedded environment this means that they must be started with + application:start/[1,2] before the ssh application is started.

CONFIGURATION -

The ssh application does not currently have an application - specific configuration file as described in application(3), - however it will by default use the following configuration files - from openssh: known_hosts, authorized_keys, authorized_keys2, - id_dsa and id_rsa, ssh_host_dsa_key and ssh_host_rsa_key. By - default Erlang SSH will look for id_dsa, id_rsa, known_hosts - and authorized_keys in ~/.ssh, and the host key files in /etc/ssh - . These locations may be changed by the options user_dir and - system_dir. Public key handling may also be customized by - providing a callback module implementing the behaviors - ssh_client_key_api and - ssh_server_key_api. -

+

The ssh application does not have an application- + specific configuration file, as described in application(3). + However, by default it use the following configuration files + from OpenSSH:

+ + known_hosts + authorized_keys + authorized_keys2 + id_dsa + id_rsa + ssh_host_dsa_key + ssh_host_rsa_key + +

By default, ssh looks for id_dsa, id_rsa, + 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. +

+

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

-
- PUBLIC KEYS -

- id_dsa and id_rsa are the users private key files, note that - the public key is part of the private key so the ssh - application will not use the id_<*>.pub files. These are - for the users convenience when he/she needs to convey their +

+
+ Public Keys +

id_dsa and id_rsa are the users private key files. + Notice that the public key is part of the private key so the ssh + application does not use the id_<*>.pub files. These are + for the user's convenience when it is needed to convey the user's public key.

-
- -
- KNOW HOSTS -

The known_hosts file contains a list of approved servers and - their public keys. Once a server is listed, it can be verified +

+
+ Known Hosts +

The known_hosts file contains a list of approved servers and + their public keys. Once a server is listed, it can be verified without user interaction.

-
- -
- AUTHORIZED KEYS -

The authorized key file keeps track of the user's authorized +

+
+ Authorized Keys +

The authorized_key file keeps track of the user's authorized public keys. The most common use of this file is to let users - log in without entering their password which is supported by the - Erlang SSH daemon. + log in without entering their password, which is supported by the + Erlang ssh daemon.

-
- -
- HOST KEYS -

Currently rsa and dsa host keys are supported and are - expected to be found in files named ssh_host_rsa_key and - ssh_host_dsa_key. +

+
+ Host Keys +

RSA and DSA host keys are supported and are + expected to be found in files named ssh_host_rsa_key and + ssh_host_dsa_key.

-
+
+
+ ERROR LOGGER AND EVENT HANDLERS +

The ssh application has no error logger or event handlers.

diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index a52a6a115e..429ef3c849 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -23,69 +23,84 @@ The Initial Developer of the Original Code is Ericsson AB. ssh_channel + + + + ssh_channel -behaviour(ssh_channel).

SSH services (clients and servers) are implemented as channels - that are multiplexed over an SSH connection and communicates via + that are multiplexed over an SSH connection and communicates over the SSH Connection Protocol. This module provides a callback API - that takes care of generic channel aspects such as flow control - and close messages and lets the callback functions take care of + that takes care of generic channel aspects, such as flow control + and close messages. It lets the callback functions take care of the service (application) specific parts. This behavior also ensures that the channel process honors the principal of an OTP-process so that it can be part of a supervisor tree. This is a requirement of channel processes implementing a subsystem that will be added to - the SSH applications supervisor tree. + the ssh applications supervisor tree.

-

When implementing a SSH subsystem use the - -behaviour(ssh_daemon_channel). instead of -behaviour(ssh_channel). - as the only relevant callback functions for subsystems are - init/1, handle_ssh_msg/2, handle_msg/2 and terminate/2, so the ssh_daemon_channel - behaviour is limited version of the ssh_channel behaviour. -

+

When implementing an ssh subsystem, use + -behaviour(ssh_daemon_channel) instead of -behaviour(ssh_channel). + The reason is that the only relevant callback functions for subsystems are + init/1, handle_ssh_msg/2, handle_msg/2, and terminate/2. + So, the ssh_daemon_channel behaviour is a limited version of the + ssh_channel behaviour. +

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

+

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data + type, or both:

-

boolean() = true | false

-

string() = list of ASCII characters

-

timeout() = infinity | integer() - in milliseconds.

-

ssh_connection_ref() - opaque to the user returned by - ssh:connect/3 or sent to an SSH channel process

-

ssh_channel_id() = integer()

-

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are - currently valid values see RFC 4254 section 5.2.

+ + boolean() +

= true | false

 + string() +

= list of ASCII characters

 + timeout() +

= infinity | integer() in milliseconds

 + ssh_connection_ref() +

Opaque to the user, returned by + ssh:connect/3 or sent to an SSH channel process

 + ssh_channel_id() +

= integer()

 + ssh_data_type_code() +

= 1 ("stderr") | 0 ("normal") are + the valid values, + see RFC 4254 + Section 5.2

 +
call(ChannelRef, Msg) -> call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason} - Makes a synchronous call to a channel. + Makes a synchronous call to a channel. ChannelRef = pid() - As returned by start_link/4 - Msg = term() - Timeout = timeout() - Reply = term() - Reason = closed | timeout + As returned by start_link/4 + Msg = term() + Timeout = timeout() + Reply = term() + Reason = closed | timeout

Makes a synchronous call to the channel process by sending - a message and waiting until a reply arrives or a timeout - occurs. The channel will call Module:handle_call/3 - to handle the message. If the channel process does not exist + to handle the message. If the channel process does not exist, {error, closed} is returned.

@@ -96,14 +111,14 @@ Sends an asynchronous message to the channel ChannelRef and returns ok. - ChannelRef = pid() - As returned by start_link/4 - Msg = term() + ChannelRef = pid() + As returned by start_link/4 + Msg = term()

Sends an asynchronous message to the channel process and returns ok immediately, ignoring if the destination node or - channel process does not exist. The channel will call + channel process does not exist. The channel calls Module:handle_cast/2 to handle the message.

@@ -112,31 +127,32 @@ enter_loop(State) -> _ - Makes an existing process an ssh_channel process. + Makes an existing process an ssh_channel process. - State = term() - as returned by ssh_channel:init/1 + State = term() - as returned by + ssh_channel:init/1 -

Makes an existing process an ssh_channel - process. Does not return, instead the calling process will - enter the ssh_channel process receive loop and become an - ssh_channel process. The process must have been started using - one of the start functions in proc_lib, see proc_lib(3). The - user is responsible for any initialization of the process - and needs to call ssh_channel:init/1 +

Makes an existing process an ssh_channel + process. Does not return, instead the calling process + enters the ssh_channel process receive loop and become an + ssh_channel process. The process must have been started using + one of the start functions in proc_lib, see the proc_lib(3) manual page in stdlib. + The user is responsible for any initialization of the process + and must call ssh_channel:init/1.

init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} - Initiates a ssh_channel process. + Initiates an ssh_channel process. Options = [{Option, Value}] State = term() - Timeout = timeout() - Reason = term() + Timeout = timeout() + Reason = term()

@@ -144,48 +160,47 @@

- The module that implements the channel behaviour. +

The module that implements the channel behaviour.

 - The list of arguments to the callback module's - init function. +

The list of arguments to the init function of the callback module.

 - Reference to the ssh connection as returned by ssh:connect/3 +

Reference to the ssh connection as returned by ssh:connect/3

 - Id of the SSH channel. +

Id of the ssh channel.

This function is normally not called by the - user. The user only needs to call if for some reason the + user. The user only needs to call if the channel process needs to be started with help of proc_lib instead of calling ssh_channel:start/4 or - ssh_channel:start_link/4

+ ssh_channel:start_link/4.

 reply(Client, Reply) -> _ - Send a reply to a client. + Sends a reply to a client. Client - opaque to the user, see explanation below Reply = term() -

This function can be used by a channel to explicitly send a +

This function can be used by a channel to send a reply to a client that called call/[2,3] when the reply cannot be defined in the return value of Module:handle_call/3.

Client must be the From argument provided to the callback function handle_call/3. Reply is an arbitrary term, - which will be given back to the client as the return value of - ssh_channel:call/[2,3].>

+ which is given back to the client as the return value of + ssh_channel:call/[2,3].

 @@ -193,24 +208,25 @@ start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> {ok, ChannelRef} | {error, Reason} - Starts a processes that handles a SSH channel. + Starts a process that handles an SSH channel. SshConnection = ssh_connection_ref() - ChannelId = ssh_channel_id() - As returned by cannot be defined in the return value of - ssh_connection:session_channel/[2,4] + ChannelId = ssh_channel_id() + As returned by + + ssh_connection:session_channel/[2,4]. ChannelCb = atom() - The name of the module implementing the service specific parts + Name of the module implementing the service-specific parts of the channel. CbInitArgs = [term()] - Argument list for the init function in the callback module. + Argument list for the init function in the callback module. ChannelRef = pid() -

Starts a processes that handles an SSH channel. It will be - called internally by the SSH daemon or explicitly by the SSH - client implementations. The behavior will set the - trap_exit flag to true. +

Starts a process that handles an SSH channel. It is + called internally, by the ssh daemon, or explicitly by the ssh + client implementations. The behavior sets the + trap_exit flag to true.

@@ -219,19 +235,19 @@
- CALLBACK TIMEOUTS + CALLBACK TIME-OUTS -

The timeout values that may be returned by the callback functions - has the same semantics as in a gen_server - If the timeout occurs handle_msg/2 - will be called as handle_msg(timeout, State).

+

The time-out values that can be returned by the callback functions + have the same semantics as in a gen_server. + If the time-out occurs, handle_msg/2 + is called as handle_msg(timeout, State).

Module:code_change(OldVsn, State, Extra) -> {ok, NewState} - Converts process state when code is changed. + Converts process state when code is changed. OldVsn = term() In the case of an upgrade, OldVsn is Vsn, and @@ -241,31 +257,31 @@ Module. If no such attribute is defined, the version is the checksum of the BEAM file. State = term() - The internal state of the channel. + Internal state of the channel. Extra = term() - Passed as-is from the {advanced,Extra} + Passed “as-is” from the {advanced,Extra} part of the update instruction. -

Converts process state when code is changed.

+

Converts process state when code is changed.

-

This function is called by a client side channel when it - should update its internal state during a release - upgrade/downgrade, i.e. when the instruction - {update,Module,Change,...} where - Change={advanced,Extra} is given in the appup - file. See OTP - Design Principles for more information. +

This function is called by a client-side channel when it + is to update its internal state during a release + upgrade or downgrade, that is, when the instruction + {update,Module,Change,...}, where + Change={advanced,Extra}, is given in the appup + file. For more information, refer to Section 9.11.6 + Release Handling Instructions in the + System Documentation.

Soft upgrade according to the OTP release concept is not straight forward for the server side, as subsystem - channel processes are spawned by the SSH application and - hence added to its supervisor tree. It could be possible to - upgrade the subsystem channels, when upgrading the user - application, if the callback functions can handle two - versions of the state, but this function can not be used in - the normal way.

+ channel processes are spawned by the ssh application and + hence added to its supervisor tree. The subsystem channels can + be upgraded when upgrading the user application, if the callback + functions can handle two versions of the state, but this function + cannot be used in the normal way.

 @@ -274,30 +290,30 @@ Module:init(Args) -> {ok, State} | {ok, State, timeout()} | {stop, Reason} - Makes necessary initializations and returns the + Makes necessary initializations and returns the initial channel state if the initializations succeed. - Args = term() - Last argument to ssh_channel:start_link/4. - State = term() - Reason = term() + Args = term() + Last argument to ssh_channel:start_link/4. + State = term() + Reason = term() -

Makes necessary initializations and returns the initial channel +

Makes necessary initializations and returns the initial channel state if the initializations succeed.

-

For more detailed information on timeouts see the section - CALLBACK TIMEOUTS.

+

For more detailed information on time-outs, see Section + CALLBACK TIME-OUTS.

Module:handle_call(Msg, From, State) -> Result - Handles messages sent by calling - ssh_channel:call/[2,3] + Handles messages sent by calling + ssh_channel:call/[2,3]. Msg = term() - From = opaque to the user should be used as argument to + From = Opaque to the user, is to be used as argument to ssh_channel:reply/2 State = term() Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()} @@ -311,15 +327,15 @@

Handles messages sent by calling ssh_channel:call/[2,3]

-

For more detailed information on timeouts see the section - CALLBACK TIMEOUTS.

+

For more detailed information on time-outs,, see Section + CALLBACK TIME-OUTS.

 Module:handle_cast(Msg, State) -> Result - Handles messages sent by calling - ssh_channel:cact/2 + Handles messages sent by calling + ssh_channel:cact/2. Msg = term() State = term() @@ -329,11 +345,11 @@ Reason = term() -

Handles messages sent by calling - ssh_channel:cast/2 +

Handles messages sent by calling + ssh_channel:cast/2.

-

For more detailed information on timeouts see the section - CALLBACK TIMEOUTS.

+

For more detailed information on time-outs, see Section + CALLBACK TIME-OUTS.

 @@ -341,33 +357,33 @@ Module:handle_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State} - Handle other messages than SSH connection protocol, - call or cast messages sent to the channel. + Handles other messages than SSH connection protocol, + call, or cast messages sent to the channel. Msg = timeout | term() ChannelId = ssh_channel_id() State = term() -

Handle other messages than ssh connection protocol, call or +

Handles other messages than SSH Connection Protocol, call, or cast messages sent to the channel.

-

Possible erlang 'EXIT'-messages should be handled by this - function and all channels should handle the following message.

+

Possible Erlang 'EXIT' messages is to be handled by this + function and all channels are to handle the following message.

- This is the first messages that will be received by - the channel, it is sent just before the

This is the first message that the channel receives. + It is sent just before the ssh_channel:init/1 function - returns successfully. This is especially useful if the + returns successfully. This is especially useful if the server wants to send a message to the client without first receiving a message from it. If the message is not - useful for your particular scenario just ignore it by - immediately returning {ok, State}. - + useful for your particular scenario, ignore it by + immediately returning {ok, State}. +

@@ -375,42 +391,44 @@ Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, ChannelId, State} - Handles ssh connection protocol messages. + Handles ssh connection protocol messages. - Msg = ssh_connection:event() + Msg = ssh_connection:event() ChannelId = ssh_channel_id() State = term() -

Handles SSH connection protocol messages that may need - service specific attention. +

Handles SSH Connection Protocol messages that may need + service-specific attention. For details, + see ssh_connection:event().

-

The following message is completely taken care of by the - SSH channel behavior

+

The following message is taken care of by the + ssh_channel behavior.

- The channel behavior will send a close message to the - other side if such a message has not already been sent and - then terminate the channel with reason normal. +

The channel behavior sends a close message to the + other side, if such a message has not already been sent. + Then it terminates the channel with reason normal.

 Module:terminate(Reason, State) -> _ - + Does cleaning up before channel process termination. + Reason = term() State = term()

This function is called by a channel process when it is - about to terminate. Before this function is called ssh_connection:close/2 - will be called if it has not been called earlier. - This function should do any necessary cleaning + is called, if it has not been called earlier. + This function does any necessary cleaning up. When it returns, the channel process terminates with reason Reason. The return value is ignored.

diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml index f3d05a8980..c3c005c58c 100644 --- a/lib/ssh/doc/src/ssh_client_key_api.xml +++ b/lib/ssh/doc/src/ssh_client_key_api.xml @@ -23,102 +23,112 @@ The Initial Developer of the Original Code is Ericsson AB. ssh_client_key_api + + + + ssh_client_key_api -behaviour(ssh_client_key_api). -

Behavior describing the API for an SSH client's public key handling. - By implementing the callbacks defined. - in this behavior it is possible to customize the SSH client's public key - handling. By default the SSH application implements this behavior - with help of the standard openssh files, see ssh(6).

+

Behavior describing the API for public key handling of an SSH client. By implementing + the callbacks defined in this behavior, the public key handling of an SSH client can + be customized. By default the ssh application implements this behavior + with help of the standard OpenSSH files, + see the ssh(6) application.
- 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. For more details on public key data types - see the public_key user's guide. +

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data + type, or both. For more details on public key data types, + refer to Section 2 Public Key Records in the + public_key user's guide:

- -

boolean() = true | false

-

string() = [byte()]

-

public_key() = #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()

-

private_key() = #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()

-

public_key_algorithm() = 'ssh-rsa'| 'ssh-dss' | atom()

- + + boolean() +

= true | false

 + string() +

= [byte()]

 + public_key() +

= #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()

 + private_key() +

= #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()

 + public_key_algorithm() +

= 'ssh-rsa'| 'ssh-dss' | atom()

 +
Module:add_host_key(HostNames, Key, ConnectOptions) -> ok | {error, Reason} - Adds a host key to the set of trusted host keys + Adds a host key to the set of trusted host keys. HostNames = string() - Description of the host that owns the PublicKey + Description of the host that owns the PublicKey. - Key = public_key() - Normally an RSA or DSA public key but handling of other public keys can be added + Key = public_key() + Normally an RSA or DSA public key, but handling of other public keys can be added. - ConnectOptions = proplists:proplist() - Options provided to ssh:connect/[3,4] - Reason = term() + ConnectOptions = proplists:proplist() + Options provided to ssh:connect/[3,4] + Reason = term(). -

Adds a host key to the set of trusted host keys

+

Adds a host key to the set of trusted host keys.

 Module:is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result - Checks if a host key is trusted + Checks if a host key is trusted. Key = public_key() - Normally an RSA or DSA public key but handling of other public keys can be added + Normally an RSA or DSA public key, but handling of other public keys can be added. Host = string() - Description of the host + Description of the host. Algorithm = public_key_algorithm() - Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms + Host key algorithm. Is to support 'ssh-rsa'| 'ssh-dss', but more algorithms can be handled. - ConnectOptions = proplists:proplist() - Options provided to ssh:connect/[3,4] + ConnectOptions = proplists:proplist() + Options provided to ssh:connect/[3,4]. - Result = boolean() + Result = boolean() -

Checks if a host key is trusted

+

Checks if a host key is trusted.

 Module:user_key(Algorithm, ConnectOptions) -> {ok, PrivateKey} | {error, Reason} - Fetches the users "public key" matching the Algorithm. + Fetches the users public key matching the Algorithm. Algorithm = public_key_algorithm() - Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms + Host key algorithm. Is to support 'ssh-rsa'| 'ssh-dss' but more algorithms can be handled. - ConnectOptions = proplists:proplist() - Options provided to ssh:connect/[3,4] + ConnectOptions = proplists:proplist() + Options provided to ssh:connect/[3,4] - PrivateKey = private_key() - The private key of the user matching the Algorithm + PrivateKey = private_key() + Private key of the user matching the Algorithm. - Reason = term() + Reason = term() -

Fetches the users "public key" matching the Algorithm. -

The private key contains the public key

-

+

Fetches the users public key matching the Algorithm.

+

The private key contains the public key.

 + diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 5e2926dfa6..2ca1060e9e 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -24,156 +24,174 @@ ssh_connection + + + ssh_connection - This module provides API functions to send SSH Connection Protocol + This module provides API functions to send + SSH Connection Protocol events to the other side of an SSH channel. -

The SSH Connection Protocol is used by clients and servers - (i.e. SSH channels) to communicate over the SSH connection. The - API functions in this module sends SSH Connection Protocol events - that are received as messages by the remote channel. - In the case that the receiving channel is an Erlang process the - message will be on the following format - . If the ssh_channel behavior is used to - implement the channel process these will be handled by - handle_ssh_msg/2 .

+

The SSH Connection Protocol is used by clients and servers, + that is, SSH channels, to communicate over the SSH connection. The + API functions in this module send SSH Connection Protocol events, + which are received as messages by the remote channel. + If the receiving channel is an Erlang process, the + messages have the format + . + If the ssh_channel behavior is used to + implement the channel process, these messages are handled by + handle_ssh_msg/2.
- 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() = list of ASCII characters

-

timeout() = infinity | integer() - in milliseconds.

-

ssh_connection_ref() - opaque to the user returned by - ssh:connect/3 or sent to an SSH channel processes

-

ssh_channel_id() = integer()

-

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are - currently valid values see RFC 4254 section 5.2.

-

ssh_request_status() = success | failure

-

event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()}

-

ssh_event_msg() = data_events() | status_events() | terminal_events()

-

reason() = timeout | closed

+ DATA TYPES + +

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data + type, or both:

+ + + boolean() +

= true | false

+ string() +

= list of ASCII characters

 + timeout() +

= infinity | integer() in milliseconds

 + ssh_connection_ref() +

Opaque to the user, returned by + ssh:connect/3 or sent to an SSH channel processes

 + ssh_channel_id() +

= integer()

 + ssh_data_type_code() +

= 1 ("stderr") | 0 ("normal") are + valid values, see + RFC 4254 Section 5.2.

 + ssh_request_status() ssh_request_status() +

= success | failure

 + event() +

= {ssh_cm, ssh_connection_ref(), ssh_event_msg()}

 + ssh_event_msg() +

= data_events() | status_events() | terminal_events()

 + reason() +

= timeout | closed

 + - data_events() + data_events() - Data has arrived on the channel. This event is sent as - result of calling ssh_connection:send/[3,4,5] +

Data has arrived on the channel. This event is sent as a + result of calling + ssh_connection:send/[3,4,5].

 - Indicates that the other side will not send any more - data. This event is sent as result of calling ssh_connection:send_eof/2 - +

Indicates that the other side sends no more data. + This event is sent as a result of calling ssh_connection:send_eof/2. +

- status_events() + status_events() - A signal can be delivered to the remote process/service - using the following message. Some systems will not support - signals, in which case they should ignore this message. There is - currently no funtion to generate this event as the signals - refered to are on OS-level and not something generated by an - Erlang program. +

A signal can be delivered to the remote process/service + using the following message. Some systems do not support + signals, in which case they are to ignore this message. There is + currently no function to generate this event as the signals + referred to are on OS-level and not something generated by an + Erlang program.

 - A remote execution may terminate violently due to a signal - then this message may be received. For details on valid string - values see RFC 4254 section 6.10. Special case of the signals - mentioned above. +

A remote execution can terminate violently because of a signal. + Then this message can be received. For details on valid string + values, see RFC 4254 + Section 6.10, which shows a special case of these signals.

 - When the command running at the other end terminates, the +

When the command running at the other end terminates, the following message can be sent to return the exit status of the - command. A zero 'exit_status' usually means that the command - terminated successfully. This event is sent as result of calling + command. A zero exit_status usually means that the command + terminated successfully. This event is sent as a result of calling - ssh_connection:exit_status/3 + ssh_connection:exit_status/3.

 - This event is sent as result of calling - ssh_connection:close/2 Both the handling of this - event and sending of it will be taken care of by the - ssh_channel behavior. +

This event is sent as a result of calling + ssh_connection:close/2. + Both the handling of this event and sending it are taken care of by the + ssh_channel behavior.

 - terminal_events() + terminal_events() -

Channels implementing a shell and command execution on the - server side should handle the following messages that may be sent by client channel processes.

+

Channels implementing a shell and command execution on the + server side are to handle the following messages that can be sent by client- + channel processes.

-

Events that includes a WantReply expects the event handling - process to call ssh_connection:reply_request/4 - with the boolean value of WantReply as the second - argument.

+

Events that include a WantReply expect the event handling + process to call + ssh_connection:reply_request/4 + with the boolean value of WantReply as the second argument.

- Environment variables may be passed to the shell/command - to be started later. This event is sent as result of calling ssh_connection:setenv/5 - +

Environment variables can be passed to the shell/command + to be started later. This event is sent as a result of calling ssh_connection:setenv/5. +

- A pseudo-terminal has been requested for the - session. Terminal is the value of the TERM environment - variable value (e.g., vt100). Zero dimension parameters must - be ignored. The character/row dimensions override the pixel - dimensions (when nonzero). Pixel dimensions refer to the - drawable area of the window. The Opcode in the +

A pseudo-terminal has been requested for the + session. Terminal is the value of the TERM environment + variable value, that is, vt100. Zero dimension parameters must + be ignored. The character/row dimensions override the pixel + dimensions (when non-zero). Pixel dimensions refer to the + drawable area of the window. Opcode in the TerminalModes list is the mnemonic name, represented - as an lowercase erlang atom, defined in - RFC 4254 section 8. - It may also be an opcode if the mnemonic name is not listed in the - RFC. Example OP code: 53, mnemonic name ECHO erlang atom: - echo.This event is sent as result of calling ssh_connection:ptty_alloc/4 + as a lowercase Erlang atom, defined in + RFC 4254, Section 8. + It can also be an Opcode if the mnemonic name is not listed in the + RFC. Example: OP code: 53, mnemonic name ECHO erlang atom: + echo. This event is sent as a result of calling ssh_connection:ptty_alloc/4.

 - This message will request that the user's default shell - be started at the other end. This event is sent as result of calling ssh_connection:shell/2 - +

This message requests that the user default shell + is started at the other end. This event is sent as a result of calling + ssh_connection:shell/2. +

- When the window (terminal) size changes on the client - side, it MAY send a message to the server side to inform it of - the new dimensions. There is currently no API function to generate this - event. +

When the window (terminal) size changes on the client + side, it can send a message to the server side to inform it of + the new dimensions. No API function generates this event.

 - This message will request that the server starts - execution of the given command. This event is sent as result of calling ssh_connection:exec/4 - +

This message requests that the server starts + execution of the given command. This event is sent as a result of calling ssh_connection:exec/4 . +

@@ -183,80 +201,83 @@ adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok - Adjusts the SSH flowcontrol window. + Adjusts the SSH flow control window. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - NumOfBytes = integer() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + NumOfBytes = integer() -

Adjusts the SSH flowcontrol window. This shall be done by both client and server side channel processes.

+

Adjusts the SSH flow control window. This is to be done by both the + client- and server-side channel processes.

-

Channels implemented with the ssh_channel - behavior will normaly not need to call this function as flow control - will be handled by the behavior. The behavior will adjust the window every time +

Channels implemented with the ssh_channel + behavior do not normally need to call this function as flow control + is handled by the behavior. The behavior adjusts the window every time the callback - handle_ssh_msg/2 has returned after processing channel data

 + handle_ssh_msg/2 returns after processing channel data.

 close(ConnectionRef, ChannelId) -> ok - Sends a close message on the channel ChannelId. + Sends a close message on the channel ChannelId. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

A server or client channel process can choose to close their session by sending a close event. +

A server- or client-channel process can choose to close their session by + sending a close event.

-

This function will be called by the ssh_channel - behavior when the channel is terminated see ssh_channel(3) so channels implemented with the - behavior should not call this function explicitly.

 +

This function is called by the ssh_channel + behavior when the channel is terminated, see ssh_channel(3) . Thus, channels implemented + with the behavior are not to call this function explicitly.

 - exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | {error, reason()} - Request that the server start the execution of the given command. + exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | + {error, reason()} + Requests that the server starts the execution of the given command. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Command = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Command = string() + Timeout = timeout() -

Should be called by a client channel process to request that the server starts execution of the - given command, the result will be several messages according to the following pattern. Note - that the last message will be a channel close message, as the exec request is a one time - execution that closes the channel when it is done.

+

Is to be called by a client-channel process to request that the server starts + executing the given command. The result is several messages according to the + following pattern. The last message is a channel close message, as the exec + request is a one-time execution that closes the channel when it is done.

- N x {ssh_cm, ssh_connection_ref(), - {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} - The result of executing the command may be only one line - or thousands of lines depending on the command. + N x {ssh_cm, ssh_connection_ref(), + {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} +

The result of executing the command can be only one line + or thousands of lines depending on the command.

 0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}} - Indicates that no more data will be sent. +

Indicates that no more data is to be sent.

 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}} - Not all systems send signals. For details on valid string - values see RFC 4254 section 6.10 +

Not all systems send signals. For details on valid string + values, see RFC 4254, Section 6.10

 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status, ssh_channel_id(), integer() = ExitStatus}} - It is recommended by the ssh connection protocol that this - message shall be sent, but that may not always be the case. +

It is recommended by the SSH Connection Protocol to send this + message, but that is not always the case.

 - 1 x {ssh_cm, ssh_connection_ref(), + 1 x {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}} - Indicates that the ssh channel started for the - execution of the command has now been shutdown. +

Indicates that the ssh_channel started for the + execution of the command has now been shut down.

 @@ -265,78 +286,72 @@ exit_status(ConnectionRef, ChannelId, Status) -> ok Sends the exit status of a command to the client. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Status = integer() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Status = integer() -

Should be called by a server channel process to sends the exit status of a command to the client.

+

Is to be called by a server-channel process to send the exit status of a command + to the client.

 - ptty_alloc(ConnectionRef, ChannelId, Options) -> - ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | {error, reason()} - Send status replies to requests that want such replies. + ptty_alloc(ConnectionRef, ChannelId, Options) -> + ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | + {error, reason()} + Sends an SSH Connection Protocol pty_req, + to allocate a pseudo-terminal. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Options = proplists:proplist() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Options = proplists:proplist() -

Sends a SSH Connection Protocol pty_req, to allocate a pseudo tty. - Should be called by a SSH client process. - Options are: -

+

Sends an SSH Connection Protocol pty_req, to allocate a pseudo-terminal. + Is to be called by an SSH client process.

+

Options:

{term, string()} - - Defaults to os:getenv("TERM") or "vt100" if it is undefined. - +

Defaults to os:getenv("TERM") or vt100 + if it is undefined.

 + {width, integer()} - - Defaults to 80 if pixel_width is not defined. - +

Defaults to 80 if pixel_width is not defined.

 + {height, integer()} - - Defaults to 24 if pixel_height is not defined. - +

Defaults to 24 if pixel_height is not defined.

 + {pixel_width, integer()} - - Is disregarded if width is defined. - +

Is disregarded if width is defined.

 + {pixel_height, integer()} - - Is disregarded if height is defined. - +

Is disregarded if height is defined.

 + {pty_opts, [{posix_atom(), integer()}]} - - Option may be an empty list, otherwise - see possible POSIX names in section 8 in RFC 4254. +

Option can be an empty list. Otherwise, see possible POSIX names + in Section 8 in RFC 4254.

 - - + reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok - Send status replies to requests that want such replies. + Sends status replies to requests that want such replies. - ConnectionRef = ssh_connection_ref() - WantReply = boolean() - Status = ssh_request_status() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + WantReply = boolean() + Status = ssh_request_status() + ChannelId = ssh_channel_id()

Sends status replies to requests where the requester has - stated that they want a status report e.i . WantReply = true, - if WantReply is false calling this function will be a - "noop". Should be called while handling an ssh connection - protocol message containing a WantReply boolean - value. -

+ stated that it wants a status report, that is, WantReply = true. + If WantReply is false, calling this function becomes a + "noop". Is to be called while handling an SSH Connection + Protocol message containing a WantReply boolean value.

 @@ -346,98 +361,97 @@ send(ConnectionRef, ChannelId, Type, Data) -> send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error, timeout} | {error, closed} - Sends channel data + Sends channel data. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Data = binary() - Type = ssh_data_type_code() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Data = binary() + Type = ssh_data_type_code() + Timeout = timeout() -

Should be called by client- and server channel processes to send data to each other. +

Is to be called by client- and server-channel processes to send data to each other.

send_eof(ConnectionRef, ChannelId) -> ok | {error, closed} - Sends eof on the channel ChannelId. + Sends EOF on channel ChannelId. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

Sends eof on the channel ChannelId. -

+

Sends EOF on channel ChannelId.

 - session_channel(ConnectionRef, Timeout) -> + session_channel(ConnectionRef, Timeout) -> session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()} - Opens a channel for a ssh session. + Opens a channel for an SSH session. - ConnectionRef = ssh_connection_ref() - InitialWindowSize = integer() - MaxPacketSize = integer() - Timeout = timeout() - Reason = term() + ConnectionRef = ssh_connection_ref() + InitialWindowSize = integer() + MaxPacketSize = integer() + Timeout = timeout() + Reason = term()

Opens a channel for an SSH session. The channel id returned from this function - is the id used as input to the other funtions in this module. -

+ is the id used as input to the other functions in this module.

 - setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | {error, reason()} - Environment variables may be passed to the + setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | + {error, reason()} + Environment variables can be passed to the shell/command to be started later. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Var = string() - Value = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Var = string() + Value = string() + Timeout = timeout() -

Environment variables may be passed before starting the - shell/command. Should be called by a client channel processes. -

+

Environment variables can be passed before starting the + shell/command. Is to be called by a client channel processes.

 shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed} - Requests that the user's default shell (typically - defined in /etc/passwd in UNIX systems) shall be executed at the server - end. + Requests that the user default shell (typically defined in + /etc/passwd in Unix systems) is to be executed at the server end. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

Should be called by a client channel process to request that the user's default shell (typically - defined in /etc/passwd in UNIX systems) shall be executed at the server end. -

+

Is to be called by a client channel process to request that the user default + shell (typically defined in /etc/passwd in Unix systems) is executed + at the server end.

 - subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | {error, reason()} - + subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | + {error, reason()} + Requests to execute a predefined subsystem on the server. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Subsystem = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Subsystem = string() + Timeout = timeout() -

Should be called by a client channel process for requesting to execute a predefined subsystem on the server. +

Is to be called by a client-channel process for requesting to execute a predefined + subsystem on the server.

diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml index f7133e4ba5..9e1f4e908d 100644 --- a/lib/ssh/doc/src/ssh_server_key_api.xml +++ b/lib/ssh/doc/src/ssh_server_key_api.xml @@ -23,68 +23,81 @@ The Initial Developer of the Original Code is Ericsson AB. ssh_server_key_api + + + + ssh_server_key_api -behaviour(ssh_server_key_api). -

Behaviour describing the API for an SSH server's public key handling. By implementing the callbacks defined - in this behavior it is possible to customize the SSH server's public key - handling. By default the SSH application implements this behavior - with help of the standard openssh files, see ssh(6).

+

Behaviour describing the API for public key handling of an SSH server. By implementing + the callbacks defined in this behavior, the public key handling of an SSH server can + be customized. By default the SSH application implements this behavior + with help of the standard OpenSSH files, + see the ssh(6) application.
- 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. For more details on public key data types - see the public_key user's guide. +

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data + type, or both. For more details on public key data types, + refer to Section 2 Public Key Records in the + public_key user's guide.

-

boolean() = true | false

-

string() = [byte()]

-

public_key() = #'RSAPublicKey'{} | {integer(), #'Dss-Parms'{}} | term()

-

private_key() = #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()

-

public_key_algorithm() = 'ssh-rsa' | 'ssh-dss' | atom()

+ + boolean() +

= true | false

 + string() +

= [byte()]

 + public_key() +

= #'RSAPublicKey'{}| {integer(), #'Dss-Parms'{}}| term()

 + private_key() +

= #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()

 + public_key_algorithm() +

= 'ssh-rsa'| 'ssh-dss' | atom()

 +
Module:host_key(Algorithm, DaemonOptions) -> {ok, Key} | {error, Reason} - Fetches the hosts private key + Fetches the host’s private key. Algorithm = public_key_algorithm() - Host key algorithm. Should support 'ssh-rsa' | 'ssh-dss' but additional algorithms + Host key algorithm. Is to support 'ssh-rsa' | 'ssh-dss', but more algorithms can be handled. - DaemonOptions = proplists:proplist() - Options provided to ssh:daemon/[2,3] - Key = private_key() - The private key of the host matching the Algorithm - Reason = term() + DaemonOptions = proplists:proplist() + Options provided to ssh:daemon/[2,3]. + Key = private_key() + Private key of the host matching the Algorithm. + Reason = term() -

Fetches the hosts private key

+

Fetches the private key of the host.

 Module:is_auth_key(Key, User, DaemonOptions) -> Result - Checks if the user key is authorized + Checks if the user key is authorized. - Key = public_key() - Normally an RSA or DSA public key but handling of other public keys can be added - User = string() - The user owning the public key - DaemonOptions = proplists:proplist() - Options provided to ssh:daemon/[2,3] - Result = boolean() + Key = public_key() + Normally an RSA or DSA public key, but handling of other public keys can be added + User = string() + User owning the public key. + DaemonOptions = proplists:proplist() + Options provided to ssh:daemon/[2,3]. + Result = boolean() -

Checks if the user key is authorized

+

Checks if the user key is authorized.

 diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index ab111562f9..95869befb8 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -23,43 +23,49 @@ ssh_sftp OTP + 2005-09-22 + ssh_sftp.sgml ssh_sftp SFTP client. -

This module implements an SFTP (SSH FTP) client. SFTP is a +

This module implements an SSH FTP (SFTP) client. SFTP is a secure, encrypted file transfer service available for SSH.
- 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: + DATA TYPES +

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data type, or both:

-

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

-

timeout() = infinity | integer() - in milliseconds.

+ + + ssh_connection_ref() +

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

 + timeout() +

= infinity | integer() in milliseconds

 +
- TIMEOUTS -

If the request functions for the SFTP channel return {error, timeout} - it does not guarantee that the request did not reach the server and was - not performed, it only means that we did not receive an answer from the - server within the time that was expected.

+ Time-outs +

If the request functions for the SFTP channel return {error, timeout}, + it does not guarantee that the request never reached the server and was + not performed. It only means that no answer was received from the + server within the expected time.

- start_channel(ConnectionRef) -> - start_channel(ConnectionRef, Options) -> + start_channel(ConnectionRef) -> + start_channel(ConnectionRef, Options) -> start_channel(Host, Options) -> start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | {error, Reason} - Starts a SFTP client + Starts an SFTP client. Host = string() ConnectionRef = ssh_connection_ref() @@ -69,33 +75,33 @@

If no connection reference is provided, a connection is set - up and the new connection is returned. An SSH channel process + up, and the new connection is returned. An SSH channel process is started to handle the communication with the SFTP server. - The returned pid for this process should be used as input to + The returned pid for this process is to be used as input to all other API functions in this module.

-

Options are:

+

Options:

-

The timeout is passed to the ssh_channel start function, - and defaults to infinity.

+

The time-out is passed to the ssh_channel start function, + and defaults to infinity.

 -

+

Desired SFTP protocol version. - The actual version will be the minimum of + The actual version is the minimum of the desired version and the maximum supported versions by the SFTP server.

-

All other options are directly passed to +

All other options are directly passed to ssh:connect/3 or ignored if a - connection is already provided.

+ connection is already provided.

 @@ -106,15 +112,15 @@ ChannelPid = pid() -

Stops an SFTP channel. Does not close the SSH connetion. +

Stops an SFTP channel. Does not close the SSH connection. Use ssh:close/1 to close it.

 - read_file(ChannelPid, File) -> + read_file(ChannelPid, File) -> read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} - Read a file + Reads a file. ChannelPid = pid() File = string() @@ -128,9 +134,9 @@ - write_file(ChannelPid, File, Iolist) -> + write_file(ChannelPid, File, Iolist) -> write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} - Write a file + Writes a file. ChannelPid = pid() File = string() @@ -140,14 +146,14 @@

Writes a file to the server, like - . The file is created if - it does not exist or is owerwritten if it does.

+ . The file is created if + it does not exist. The file is overwritten if it exists.

 - list_dir(ChannelPid, Path) -> + list_dir(ChannelPid, Path) -> list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} - List directory + Lists the directory. ChannelPid = pid() Path = string() @@ -162,9 +168,9 @@ - open(ChannelPid, File, Mode) -> + open(ChannelPid, File, Mode) -> open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} - Open a file and return a handle + Opens a file and returns a handle. ChannelPid = pid() File = string() @@ -175,14 +181,14 @@ Reason = term() -

Opens a file on the server, and returns a handle that +

Opens a file on the server and returns a handle, which can be used for reading or writing.

 - opendir(ChannelPid, Path) -> + opendir(ChannelPid, Path) -> opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason} - Open a directory and return a handle + Opens a directory and returns a handle. ChannelPid = pid() Path = string() @@ -190,7 +196,7 @@ Reason = term() -

Opens a handle to a directory on the server, the handle +

Opens a handle to a directory on the server. The handle can be used for reading directory contents.

 @@ -198,14 +204,15 @@ open_tar(ChannelPid, Path, Mode) -> open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, Reason} - Opens a tar file on the server to which ChannelPid is connected and returns a handle + Opens a tar file on the server to which ChannelPid + is connected and returns a handle. ChannelPid = pid() Path = string() - Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt] + Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt] EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}} DecryptOpt = {crypto,{InitFun,DecryptFun}} - InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize}) + InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize}) CryptoState = any() ChunkSize = undefined | pos_integer() EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult) @@ -219,11 +226,11 @@ Reason = term() -

Opens a handle to a tar file on the server associated with ChannelPid. The handle - can be used for remote tar creation and extraction as defined by the +

Opens a handle to a tar file on the server, associated with ChannelPid. + The handle can be used for remote tar creation and extraction, as defined by the erl_tar:init/3 function.

-

An example of writing and then reading a tar file:

+

Example of writing and then reading a tar file follows:

{ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), ok = erl_tar:add(HandleWrite, .... ), @@ -238,25 +245,24 @@ ok = erl_tar:close(HandleRead), -

The crypto mode option is applied to the generated stream of bytes just prior to sending - them to the sftp server. This is intended for encryption but could of course be used for other +

The crypto mode option is applied to the generated stream of bytes prior to sending + them to the SFTP server. This is intended for encryption but can be used for other purposes.

The InitFun is applied once - prior to any other crypto operation. The returned CryptoState is then folded into - repeated applications of the EncryptFun or DecryptFun. The binary returned - from those Funs are sent further to the remote sftp server. Finally - if doing encryption - - the CloseFun is applied to the last piece of data. The CloseFun is + prior to any other crypto operation. The returned CryptoState is then folded into + repeated applications of the EncryptFun or DecryptFun. The binary returned + from those funs are sent further to the remote SFTP server. Finally, if doing encryption, + the CloseFun is applied to the last piece of data. The CloseFun is responsible for padding (if needed) and encryption of that last piece.

The ChunkSize defines the size of the PlainBins that EncodeFun is applied - to. If the ChunkSize is undefined the size of the PlainBins varies because - this is inteded for stream crypto while a fixed ChunkSize is intended for block crypto. It - is possible to change the ChunkSizes in the return from the EncryptFun or - DecryptFun. It is in fact possible to change the value between pos_integer() and - undefined. + to. If the ChunkSize is undefined, the size of the PlainBins varies, + because this is intended for stream crypto, whereas a fixed ChunkSize is intended for block crypto. + ChunkSizes can be changed in the return from the EncryptFun or + DecryptFun. The value can be changed between pos_integer() and undefined.

-

The write and read example above can be extended with encryption and decryption:

+

The previous write and read example can be extended with encryption and decryption as follows:

%% First three parameters depending on which crypto type we select: Key = <<"This is a 256 bit key. abcdefghi">>, @@ -307,9 +313,9 @@ - close(ChannelPid, Handle) -> + close(ChannelPid, Handle) -> close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} - Close an open handle + Closes an open handle. ChannelPid = pid() Handle = term() @@ -321,11 +327,11 @@ - read(ChannelPid, Handle, Len) -> + read(ChannelPid, Handle, Len) -> read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} - pread(ChannelPid, Handle, Position, Len) -> + pread(ChannelPid, Handle, Position, Len) -> pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error} - Read from an open file + Reads from an open file. ChannelPid = pid() Handle = term() @@ -340,8 +346,8 @@ . Returns , , or . If the file is opened with , is a binary, otherwise it is a string.

-

If the file is read past eof, only the remaining bytes - will be read and returned. If no bytes are read, +

If the file is read past eof, only the remaining bytes + are read and returned. If no bytes are read, is returned.

The function reads from a specified position, combining the and functions.

@@ -350,7 +356,7 @@ aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} - Read asynchronously from an open file + Reads asynchronously from an open file. ChannelPid = pid() Handle = term() @@ -361,12 +367,12 @@

Reads from an open file, without waiting for the result. If the - handle is valid, the function returns , where N + handle is valid, the function returns , where N is a term guaranteed to be unique between calls of . The actual data is sent as a message to the calling process. This message has the form , where is the result from the read, either , - or , or .

+ , or .

The function reads from a specified position, combining the and functions.

 @@ -374,9 +380,9 @@ write(ChannelPid, Handle, Data) -> write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} - pwrite(ChannelPid, Handle, Position, Data) -> ok + pwrite(ChannelPid, Handle, Position, Data) -> ok pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error} - Write to an open file + Writes to an open file. ChannelPid = pid() Handle = term() @@ -386,27 +392,27 @@ Reason = term() -

Writes to the file referenced by . - The file should be opened with or - flag. Returns if successful or S +

Writes to the file referenced by . + The file is to be opened with or + flag. Returns if successful or otherwise.

-

Typical error reasons are:

+

Typical error reasons:

-

The file is not opened for writing.

+

File is not opened for writing.

 -

There is a no space left on the device.

+

No space is left on the device.

 - awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} - Write asynchronously to an open file + Writes asynchronously to an open file. ChannelPid = pid() Handle = term() @@ -418,24 +424,25 @@

Writes to an open file, without waiting for the result. If the - handle is valid, the function returns , where N + handle is valid, the function returns , where N is a term guaranteed to be unique between calls of . The result of the operation is sent as a message to the calling process. This message has the form , where is the result from the write, either , or .

-

The writes on a specified position, combining +

writes on a specified position, combining the and operations.

 - position(ChannelPid, Handle, Location) -> + position(ChannelPid, Handle, Location) -> position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} - Seek position in open file + Sets the file position of a file. ChannelPid = pid() Handle = term() - Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof + Location = Offset + | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof Offset = integer() Timeout = timeout() NewPosition = integer() @@ -465,15 +472,17 @@ -

The same as above with 0.

+

The same as eariler with 0, + that is, . +

- read_file_info(ChannelPid, Name) -> + read_file_info(ChannelPid, Name) -> read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} - Get information about a file + Gets information about a file. ChannelPid = pid() Name = string() @@ -484,13 +493,14 @@

Returns a record from the file specified by - or , like .

+ or , + like .

 read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} - Get information about a symbolic link + Gets information about a symbolic link. ChannelPid = pid() Name = string() @@ -506,9 +516,9 @@ - write_file_info(ChannelPid, Name, Info) -> + write_file_info(ChannelPid, Name, Info) -> write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} - Write information for a file + Writes information for a file. ChannelPid = pid() Name = string() @@ -522,9 +532,9 @@ - read_link(ChannelPid, Name) -> + read_link(ChannelPid, Name) -> read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} - Read symbolic link + Reads symbolic link. ChannelPid = pid() Name = string() @@ -537,9 +547,9 @@ - make_symlink(ChannelPid, Name, Target) -> + make_symlink(ChannelPid, Name, Target) -> make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} - Create symbolic link + Creates a symbolic link. ChannelPid = pid() Name = string() @@ -552,9 +562,9 @@ - rename(ChannelPid, OldName, NewName) -> + rename(ChannelPid, OldName, NewName) -> rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} - Rename a file + Renames a file. ChannelPid = pid() OldName = string() @@ -563,14 +573,14 @@ Reason = term() -

Renames a file named , and gives it the name - , like

+

Renames a file named and gives it the name + , like .

 - delete(ChannelPid, Name) -> + delete(ChannelPid, Name) -> delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Delete a file + Deletes a file. ChannelPid = pid() Name = string() @@ -579,13 +589,13 @@

Deletes the file specified by , like -

+ .

 - make_dir(ChannelPid, Name) -> + make_dir(ChannelPid, Name) -> make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Create a directory + Creates a directory. ChannelPid = pid() Name = string() @@ -593,15 +603,15 @@ Reason = term() -

Creates a directory specified by . should - be a full path to a new directory. The directory can only be +

Creates a directory specified by . + must be a full path to a new directory. The directory can only be created in an existing directory.

 - del_dir(ChannelPid, Name) -> + del_dir(ChannelPid, Name) -> del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Delete an empty directory + Deletes an empty directory. ChannelPid = pid() Name = string() @@ -610,7 +620,7 @@

Deletes a directory specified by . - Note that the directory must be empty before it can be successfully deleted + The directory must be empty before it can be successfully deleted.

diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml index 81c2acc575..bc2660f595 100644 --- a/lib/ssh/doc/src/ssh_sftpd.xml +++ b/lib/ssh/doc/src/ssh_sftpd.xml @@ -22,67 +22,73 @@ ssh_sftpd + + 2005-09-22 + ssh_sftpd.sgml ssh_sftpd - Specifies the channel process to handle an sftp subsystem. + Specifies the channel process to handle an SFTP subsystem. -

Specifies a channel process to handle a sftp subsystem.

+

Specifies a channel process to handle an SFTP subsystem.
- DATA TYPES -

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

-

subsystem_name() = "sftp"

-

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

-

channel_init_args() = list() - The one given as argument to function - subsystem_spec/1.

+ DATA TYPES + + subsystem_spec() +

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

 + subsystem_name() +

= "sftp"

 + channel_callback() +

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

 + channel_init_args() +

= list() - The one given as argument to function subsystem_spec/1.

 +
subsystem_spec(Options) -> subsystem_spec() - Returns the subsystem specification that allows an ssh daemon to handle the subsystem "sftp". + Returns the subsystem specification that allows an SSH daemon to handle the subsystem "sftp". Options = [{Option, Value}] -

Should be used together with ssh:daemon/[1,2,3]

-

Options are:

+

Is to be used together with ssh:daemon/[1,2,3]

+

Options:

-

Sets the initial current working directory for the - server.

+

Sets the initial current working directory for the server.

Determines which module to call for accessing - the file server. The default value is ssh_sftpd_file that uses the - file and filelib API:s to access the standard OTP file - server. This option may be used to plug in + the file server. The default value is ssh_sftpd_file, which uses the + file and filelib + APIs to access the standard OTP file server. This option can be used to plug in other file servers.

The default value is 0, which means that there is no upper limit. - If supplied, the number of filenames returned to the sftp client per READDIR + If supplied, the number of filenames returned to the SFTP client per READDIR request is limited to at most the given value.

 -

Sets the sftp root directory. The user will then not be - able to see any files above this root. If for instance - the root is set to /tmp the user will see this - directory as / and if the user does cd /etc - the user will end up in /tmp/etc. +

Sets the SFTP root directory. Then the user cannot see any files + above this root. If, for example, the root directory is set to /tmp, + then the user sees this directory as /. If the user then writes + cd /etc, the user moves to /tmp/etc.

-

Sets the sftp version to use, defaults to 5. Version 6 is under +

Sets the SFTP version to use. Defaults to 5. Version 6 is under development and limited.

 diff --git a/lib/ssh/doc/src/usersguide.xml b/lib/ssh/doc/src/usersguide.xml index 8ab14c2945..a9ed5fe21e 100644 --- a/lib/ssh/doc/src/usersguide.xml +++ b/lib/ssh/doc/src/usersguide.xml @@ -23,15 +23,16 @@ SSH User's Guide OTP Team + 2012-10-11 + usersguide.xml -

The SSH application implements the SSH (Secure Shell) protocol and - provides an SFTP (Secret File Transfer Protocol) client and server. +

The Erlang Secure Shell (SSH) application, ssh, implements the SSH Transport Layer Protocol and + provides SSH File Transfer Protocol (SFTP) clients and servers.

- diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index 46178d4018..5873e03f23 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -22,35 +22,40 @@ - Getting started + Getting Started + + + + + using_ssh.xml
- General information -

The examples in the following sections use the utility function - ssh:start/0 that starts - all needed applications (crypto, public_key and ssh). All examples - are run in an Erlang shell, or in a bash shell using openssh to - illustrate how the erlang ssh application can be used. The - examples are run as the user otptest on a local network where the - user is authorized to login in over ssh to the host "tarlop". If - nothing else is stated it is persumed that the otptest user has an - entry in tarlop's authorized_keys file (may log in via ssh without - entering a password). Also tarlop is a known host in the user - otptest's known_hosts file so that host verification can be done - without user interaction. + General Information +

The following examples use the utility function + ssh:start/0 to start + all needed applications (crypto, public_key, and ssh). + All examples are run in an Erlang shell, or in a bash shell, using openssh + to illustrate how the ssh application can be used. The + examples are run as the user otptest on a local network where the + user is authorized to log in over ssh to the host tarlop. +

+

If nothing else is stated, it is presumed that the otptest user + has an entry in the authorized_keys file of tarlop + (allowed to log in over ssh without entering a password). + Also, tarlop is a known host in the known_hosts + file of the user otptest. This means that host-verification + can be done without user-interaction.

- Using the Erlang SSH Terminal Client + Using the Erlang ssh Terminal Client -

The user otptest, that has bash as default shell, uses the - ssh:shell/1 client to connect to the openssh daemon running on a - host called tarlop. Note that currently this client is very simple - and you should not be expected to be as fancy as the openssh - client.

+

The user otptest, which has bash as default shell, uses the + ssh:shell/1 client to connect to the openssh daemon running on a + host called tarlop:

1> ssh:start(). @@ -62,24 +67,27 @@ logout 3> +

Notice that this is a simple client that is not expected to be as + fancy as the openssh client.

- Running an Erlang SSH Daemon + + Running an Erlang ssh Daemon -

The option system_dir must be a directory containing a host - key file and it defaults to /etc/ssh. For details see section +

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.

+

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

 -

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

+

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

-

In the following example we generate new keys and host keys as - to be able to run the example without having root privileges

+

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

$bash> ssh-keygen -t rsa -f /tmp/ssh_daemon/ssh_host_rsa_key @@ -88,8 +96,10 @@ [...] -

Create the file /tmp/otptest_user/.ssh/authorized_keys and add the content - of /tmp/otptest_user/.ssh/id_rsa.pub Now we can do

+

Step 2. Create the file /tmp/otptest_user/.ssh/authorized_keys + and add the content of /tmp/otptest_user/.ssh/id_rsa.pub.

+ +

Step 3. Start the Erlang ssh daemon:

1> ssh:start(). @@ -100,7 +110,8 @@ 3> -

Use the openssh client from a shell to connect to the Erlang ssh daemon.

+

Step 4. Use the openssh client from a shell to connect + to the Erlang ssh daemon:

$bash> ssh tarlop -p 8989 -i /tmp/otptest_user/.ssh/id_rsa\ @@ -113,9 +124,12 @@ 1> -

There are two ways of shutting down an SSH daemon

+

There are two ways of shutting down an ssh daemon, + see Step 5a and Step 5b.

-

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

+

Step 5a. Shut down the Erlang ssh daemon so that it + stops the listener but leaves existing connections, started by the listener, + operational:

3> ssh:stop_listener(Sshd). @@ -123,7 +137,8 @@ 4> -

2: Stops the listener and all connections started by the listener.

+

Step 5b. Shut down the Erlang ssh daemon so that it + stops the listener and all connections started by the listener:

3> ssh:stop_daemon(Sshd) @@ -134,16 +149,17 @@
- One Time Execution + One-Time Execution + +

In the following example, the Erlang shell is the client process + that receives the channel replies.

-

In the following example the Erlang shell is the client process - that receives the channel replies.

+

The number of received messages in this example depends on which OS + and which shell that is used on the machine running the ssh daemon. + See also ssh_connection:exec/4 +

. -

If you run this example - in your environment you may get fewer or more messages back as - this depends on the OS and shell on the machine running the ssh - daemon. See also ssh_connection:exec/4 -

+

Do a one-time execution of a remote command over ssh:

1> ssh:start(). @@ -162,7 +178,8 @@ 6> -

Note only the channel is closed the connection is still up and can handle other channels

+

Notice that only the channel is closed. The connection is still up and can + handle other channels:

6> {ok, NewChannelId} = ssh_connection:session_channel(ConnectionRef, infinity). @@ -172,7 +189,9 @@
- SFTP (SSH File Transport Protocol) server + SFTP Server + +

Start the Erlang ssh daemon with the SFTP subsystem:

1> ssh:start(). @@ -184,7 +203,7 @@ 3> -

Run the openssh sftp client

+

Run the OpenSSH SFTP client:

$bash> sftp -oPort=8989 -o IdentityFile=/tmp/otptest_user/.ssh/id_rsa\ @@ -197,7 +216,9 @@
- SFTP (SSH File Transport Protocol) client + SFTP Client + +

Fetch a file with the Erlang SFTP client:

1> ssh:start(). @@ -210,10 +231,10 @@
- Creating a subsystem + Creating a Subsystem -

A very small SSH subsystem that echos N bytes could be implemented like this. - See also ssh_channel(3)

+

A small ssh subsystem that echoes N bytes can be implemented as shown + in the following example:

-module(ssh_echo_server). @@ -267,7 +288,9 @@ terminate(_Reason, _State) -> ok. -

And run like this on the host tarlop with the keys generated in section 3.3

+

The subsystem can be run on the host tarlop with the generated keys, + as described in Section + Running an Erlang ssh Daemon:

1> ssh:start(). @@ -293,6 +316,7 @@ terminate(_Reason, _State) -> {ssh_msg, <0.57.0>, {closed, 0}} 7> {error, closed} = ssh_connection:send(ConnectionRef, ChannelId, "10", infinity). +

See also ssh_channel(3).

-- cgit v1.2.3 From b2bac6ce7b0746a0643c638b6b33085de9aab9a6 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 20 Apr 2015 13:21:19 +0200 Subject: ssh: Technically correct description --- lib/ssh/doc/src/introduction.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/ssh/doc/src/introduction.xml b/lib/ssh/doc/src/introduction.xml index 70c6fb2ee1..1efbc16016 100644 --- a/lib/ssh/doc/src/introduction.xml +++ b/lib/ssh/doc/src/introduction.xml @@ -42,11 +42,11 @@ client and server. The protocol also provides privacy, integrity, server authentication, and man-in-the-middle protection.

-

The ssh application is an implementation of the SSH Transport - Layer Protocol in Erlang. It provides the following:

+

The ssh application is an implementation of the SSH Transport, Connection and Authentication + Layer Protocols in Erlang. It provides the following:

- API functions to write customized SSH clients and servers - The Erlang shell available through SSH + API functions to write customized SSH clients and servers applications + The Erlang shell available over SSH An SFTP client (ssh_sftp) and server (ssh_sftpd) -- cgit v1.2.3 From 9afc4b632975b89b5ac772d2e6bf23679c1e8626 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 20 Apr 2015 13:41:18 +0200 Subject: ssh: Remove legacy statement --- lib/ssh/doc/src/using_ssh.xml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index 5873e03f23..64477cb493 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -61,14 +61,12 @@ 1> ssh:start(). ok 2> {ok, S} = ssh:shell("tarlop"). - >pwd + otptest@tarlop:> pwd /home/otptest - >exit + otptest@tarlop:> exit logout 3> -

Notice that this is a simple client that is not expected to be as - fancy as the openssh client.

-- cgit v1.2.3 From de3ec242ef34cef763a6e3a8462b81a972e9af7f Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Mon, 20 Apr 2015 16:42:06 +0200 Subject: ssh: Corrected information about error and event logging Also added some links --- lib/ssh/doc/src/ssh_app.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml index 498565057f..1dfe68b17d 100644 --- a/lib/ssh/doc/src/ssh_app.xml +++ b/lib/ssh/doc/src/ssh_app.xml @@ -52,7 +52,7 @@ CONFIGURATION

The ssh application does not have an application- - specific configuration file, as described in application(3). + specific configuration file, as described in application(3). However, by default it use the following configuration files from OpenSSH:

@@ -109,12 +109,12 @@
ERROR LOGGER AND EVENT HANDLERS -

The ssh application has no error logger or event handlers.

+

The ssh application uses the default OTP error logger to log unexpected errors or print information about special events.

SEE ALSO -

application(3)

+

application(3)

-- cgit v1.2.3 From ea648fd889cf519a947af9b2c73e0b3fc5346486 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 21 Apr 2015 15:48:13 +0200 Subject: ssh: Remove extra whitespace --- lib/ssh/doc/src/ssh_connection.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 2ca1060e9e..669a361db9 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -233,7 +233,7 @@

This function is called by the ssh_channel behavior when the channel is terminated, see ssh_channel(3) . Thus, channels implemented + marker="ssh_channel"> ssh_channel(3). Thus, channels implemented with the behavior are not to call this function explicitly.

 -- cgit v1.2.3 From 3ac3d047903bc7770afcc2b842959fd296f4e9ea Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 21 Apr 2015 15:58:20 +0200 Subject: ssh: Change wording to become accurate --- lib/ssh/doc/src/ssh_client_key_api.xml | 2 +- lib/ssh/doc/src/ssh_server_key_api.xml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml index c3c005c58c..a8dda042c9 100644 --- a/lib/ssh/doc/src/ssh_client_key_api.xml +++ b/lib/ssh/doc/src/ssh_client_key_api.xml @@ -37,7 +37,7 @@ the callbacks defined in this behavior, the public key handling of an SSH client can be customized. By default the ssh application implements this behavior with help of the standard OpenSSH files, - see the ssh(6) application.

+ see the ssh(6) application manual.

diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml index 9e1f4e908d..34ce7f7660 100644 --- a/lib/ssh/doc/src/ssh_server_key_api.xml +++ b/lib/ssh/doc/src/ssh_server_key_api.xml @@ -37,7 +37,7 @@ the callbacks defined in this behavior, the public key handling of an SSH server can be customized. By default the SSH application implements this behavior with help of the standard OpenSSH files, - see the ssh(6) application.

+ see the ssh(6) application manual.

-- cgit v1.2.3 From cc4996c9b3ad5294d3c3e6bb2435baaabec3f319 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 14:51:34 +0200 Subject: ssh: Align to alphabetic order --- lib/ssh/doc/src/ssh_sftp.xml | 545 ++++++++++++++++++++++++------------------- 1 file changed, 311 insertions(+), 234 deletions(-) diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 95869befb8..c2a86f3821 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -59,98 +59,132 @@
+ + apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + N = term() + Reason = term() + +

The function reads from a specified position, + combining the and functions.

+

ssh_sftp:apread/3

 + + + + aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} + Reads asynchronously from an open file. + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + N = term() + Reason = term() + + +

Reads from an open file, without waiting for the result. If the + handle is valid, the function returns , where N + is a term guaranteed to be unique between calls of . + The actual data is sent as a message to the calling process. This + message has the form , where + is the result from the read, either , + , or .

+ + + - start_channel(ConnectionRef) -> - start_channel(ConnectionRef, Options) -> - start_channel(Host, Options) -> - start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | - {error, Reason} - Starts an SFTP client. + apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} + Writes asynchronously to an open file. - Host = string() - ConnectionRef = ssh_connection_ref() - Port = integer() - Options = [{Option, Value}] + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Data = binary() + Timeout = timeout() Reason = term() -

If no connection reference is provided, a connection is set - up, and the new connection is returned. An SSH channel process - is started to handle the communication with the SFTP server. - The returned pid for this process is to be used as input to - all other API functions in this module.

+

writes on a specified position, combining + the and operations.

+

ssh_sftp:awrite/3

+ -

Options:

- - - -

The time-out is passed to the ssh_channel start function, - and defaults to infinity.

- - - - - -

- Desired SFTP protocol version. - The actual version is the minimum of - the desired version and the maximum supported - versions by the SFTP server. -

- - -

All other options are directly passed to - ssh:connect/3 or ignored if a - connection is already provided.

+ + awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + Writes asynchronously to an open file. + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Data = binary() + Timeout = timeout() + Reason = term() + + +

Writes to an open file, without waiting for the result. If the + handle is valid, the function returns , where N + is a term guaranteed to be unique between calls of + . The result of the operation is sent + as a message to the calling process. This message has the form + , where is the result + from the write, either , or .

 - stop_channel(ChannelPid) -> ok - Stops the SFTP client channel. + close(ChannelPid, Handle) -> + close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} + Closes an open handle. ChannelPid = pid() + Handle = term() + Timeout = timeout() + Reason = term() -

Stops an SFTP channel. Does not close the SSH connection. - Use ssh:close/1 to close it.

+

Closes a handle to an open file or directory on the server.

 - + - read_file(ChannelPid, File) -> - read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} - Reads a file. + delete(ChannelPid, Name) -> + delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Deletes a file. - ChannelPid = pid() - File = string() - Data = binary() + ChannelPid = pid() + Name = string() Timeout = timeout() - Reason = term() + Reason = term() -

Reads a file from the server, and returns the data in a binary, - like .

+

Deletes the file specified by , like + .

 + - write_file(ChannelPid, File, Iolist) -> - write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} - Writes a file. + del_dir(ChannelPid, Name) -> + del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Deletes an empty directory. ChannelPid = pid() - File = string() - Iolist = iolist() + Name = string() Timeout = timeout() Reason = term() -

Writes a file to the server, like - . The file is created if - it does not exist. The file is overwritten if it exists.

+

Deletes a directory specified by . + The directory must be empty before it can be successfully deleted. +

- + + list_dir(ChannelPid, Path) -> list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} Lists the directory. @@ -167,7 +201,41 @@ filenames as a list of strings.

 + + make_dir(ChannelPid, Name) -> + make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Creates a directory. + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Creates a directory specified by . + must be a full path to a new directory. The directory can only be + created in an existing directory.

+ + + + + make_symlink(ChannelPid, Name, Target) -> + make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} + Creates a symbolic link. + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Creates a symbolic link pointing to with the + name , like .

+ + + + open(ChannelPid, File, Mode) -> open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} Opens a file and returns a handle. @@ -228,10 +296,11 @@

Opens a handle to a tar file on the server, associated with ChannelPid. The handle can be used for remote tar creation and extraction, as defined by the - erl_tar:init/3 function. + erl_tar:init/3 function.

+

Example of writing and then reading a tar file follows:

- + {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), ok = erl_tar:add(HandleWrite, .... ), ok = erl_tar:add(HandleWrite, .... ), @@ -263,7 +332,7 @@ DecryptFun. The value can be changed between pos_integer() and undefined.

The previous write and read example can be extended with encryption and decryption as follows:

- + %% First three parameters depending on which crypto type we select: Key = <<"This is a 256 bit key. abcdefghi">>, Ivec0 = crypto:rand_bytes(16), @@ -313,22 +382,52 @@ - close(ChannelPid, Handle) -> - close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} - Closes an open handle. + position(ChannelPid, Handle, Location) -> + position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} + Sets the file position of a file. ChannelPid = pid() Handle = term() + Location = Offset + | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof + Offset = integer() Timeout = timeout() + NewPosition = integer() Reason = term() -

Closes a handle to an open file or directory on the server.

+

Sets the file position of the file referenced by . + Returns (as an absolute offset) if + successful, otherwise . is + one of the following:

+ + + +

The same as .

+ + + +

Absolute offset.

+ + + +

Offset from the current position.

+ + + +

Offset from the end of file.

+ + + +

The same as eariler with 0, + that is, . +

+ + + - read(ChannelPid, Handle, Len) -> - read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} pread(ChannelPid, Handle, Position, Len) -> pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error} Reads from an open file. @@ -342,44 +441,13 @@ Reason = term() -

Reads bytes from the file referenced by - . Returns , , or - . If the file is opened with , - is a binary, otherwise it is a string.

-

If the file is read past eof, only the remaining bytes - are read and returned. If no bytes are read, - is returned.

-

The function reads from a specified position, - combining the and functions.

- - - - aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} - apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} - Reads asynchronously from an open file. - - ChannelPid = pid() - Handle = term() - Position = integer() - Len = integer() - N = term() - Reason = term() - - -

Reads from an open file, without waiting for the result. If the - handle is valid, the function returns , where N - is a term guaranteed to be unique between calls of . - The actual data is sent as a message to the calling process. This - message has the form , where - is the result from the read, either , - , or .

-

The function reads from a specified position, - combining the and functions.

+

The function reads from a specified position, + combining the and functions.

+

ssh_sftp:read/4

 + - write(ChannelPid, Handle, Data) -> - write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} pwrite(ChannelPid, Handle, Position, Data) -> ok pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error} Writes to an open file. @@ -392,94 +460,55 @@ Reason = term() -

Writes to the file referenced by . - The file is to be opened with or - flag. Returns if successful or - otherwise.

-

Typical error reasons:

- - - -

File is not opened for writing.

- - - -

No space is left on the device.

- - +

The function writes to a specified position, + combining the and functions.

+

ssh_sftp:write/3

 - - awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} - apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} - Writes asynchronously to an open file. + + + + read(ChannelPid, Handle, Len) -> + read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} + Reads from an open file. ChannelPid = pid() Handle = term() Position = integer() Len = integer() - Data = binary() Timeout = timeout() + Data = string() | binary() Reason = term() -

Writes to an open file, without waiting for the result. If the - handle is valid, the function returns , where N - is a term guaranteed to be unique between calls of - . The result of the operation is sent - as a message to the calling process. This message has the form - , where is the result - from the write, either , or .

-

writes on a specified position, combining - the and operations.

+

Reads bytes from the file referenced by + . Returns , , or + . If the file is opened with , + is a binary, otherwise it is a string.

+

If the file is read past eof, only the remaining bytes + are read and returned. If no bytes are read, + is returned.

 - - position(ChannelPid, Handle, Location) -> - position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} - Sets the file position of a file. + + + read_file(ChannelPid, File) -> + read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} + Reads a file. - ChannelPid = pid() - Handle = term() - Location = Offset - | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof - Offset = integer() + ChannelPid = pid() + File = string() + Data = binary() Timeout = timeout() - NewPosition = integer() - Reason = term() + Reason = term() -

Sets the file position of the file referenced by . - Returns (as an absolute offset) if - successful, otherwise . is - one of the following:

- - - -

The same as .

- - - -

Absolute offset.

- - - -

Offset from the current position.

- - - -

Offset from the end of file.

- - - -

The same as eariler with 0, - that is, . -

- - +

Reads a file from the server, and returns the data in a binary, + like .

 - + + read_file_info(ChannelPid, Name) -> read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} Gets information about a file. @@ -497,7 +526,24 @@ like .

 - + + + read_link(ChannelPid, Name) -> + read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} + Reads symbolic link. + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Reads the link target from the symbolic link specified + by , like .

+ + + + read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} Gets information about a symbolic link. @@ -515,116 +561,147 @@ .

 + - write_file_info(ChannelPid, Name, Info) -> - write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} - Writes information for a file. + rename(ChannelPid, OldName, NewName) -> + rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} + Renames a file. ChannelPid = pid() - Name = string() - Info = record() + OldName = string() + NewName = string() Timeout = timeout() Reason = term() -

Writes file information from a record to the - file specified by , like .

- - - - read_link(ChannelPid, Name) -> - read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} - Reads symbolic link. - - ChannelPid = pid() - Name = string() - Target = string() - Reason = term() - - -

Reads the link target from the symbolic link specified - by , like .

+

Renames a file named and gives it the name + , like .

 + - make_symlink(ChannelPid, Name, Target) -> - make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} - Creates a symbolic link. + start_channel(ConnectionRef) -> + start_channel(ConnectionRef, Options) -> + start_channel(Host, Options) -> + start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | + {error, Reason} + Starts an SFTP client. - ChannelPid = pid() - Name = string() - Target = string() + Host = string() + ConnectionRef = ssh_connection_ref() + Port = integer() + Options = [{Option, Value}] Reason = term() -

Creates a symbolic link pointing to with the - name , like .

+

If no connection reference is provided, a connection is set + up, and the new connection is returned. An SSH channel process + is started to handle the communication with the SFTP server. + The returned pid for this process is to be used as input to + all other API functions in this module.

+ +

Options:

+ + + +

The time-out is passed to the ssh_channel start function, + and defaults to infinity.

+ + + + + +

+ Desired SFTP protocol version. + The actual version is the minimum of + the desired version and the maximum supported + versions by the SFTP server. +

+ + +

All other options are directly passed to + ssh:connect/3 or ignored if a + connection is already provided.

 - - rename(ChannelPid, OldName, NewName) -> - rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} - Renames a file. + + + stop_channel(ChannelPid) -> ok + Stops the SFTP client channel. ChannelPid = pid() - OldName = string() - NewName = string() - Timeout = timeout() - Reason = term() -

Renames a file named and gives it the name - , like .

+

Stops an SFTP channel. Does not close the SSH connection. + Use ssh:close/1 to close it.

 + - delete(ChannelPid, Name) -> - delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Deletes a file. + write_file(ChannelPid, File, Iolist) -> + write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} + Writes a file. ChannelPid = pid() - Name = string() + File = string() + Iolist = iolist() Timeout = timeout() Reason = term() -

Deletes the file specified by , like - .

+

Writes a file to the server, like + . The file is created if + it does not exist. The file is overwritten if it exists.

 + - make_dir(ChannelPid, Name) -> - make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Creates a directory. + write(ChannelPid, Handle, Data) -> + write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} + Writes to an open file. ChannelPid = pid() - Name = string() + Handle = term() + Position = integer() + Data = iolist() Timeout = timeout() Reason = term() -

Creates a directory specified by . - must be a full path to a new directory. The directory can only be - created in an existing directory.

+

Writes to the file referenced by . + The file is to be opened with or + flag. Returns if successful or + otherwise.

+

Typical error reasons:

+ + + +

File is not opened for writing.

+ + + +

No space is left on the device.

+ + + - del_dir(ChannelPid, Name) -> - del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Deletes an empty directory. + write_file_info(ChannelPid, Name, Info) -> + write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} + Writes information for a file. ChannelPid = pid() Name = string() + Info = record() Timeout = timeout() Reason = term() -

Deletes a directory specified by . - The directory must be empty before it can be successfully deleted. -

+

Writes file information from a record to the + file specified by , like .

 - -- cgit v1.2.3 From f84db1b6f16075fdd91e456170615cbfebd7979b Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 15:52:21 +0200 Subject: ssh: Add links --- lib/ssh/doc/src/ssh_sftp.xml | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index c2a86f3821..d52613c6bc 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -163,7 +163,7 @@

Deletes the file specified by , like - .

+ file:delete/1

 @@ -231,7 +231,8 @@

Creates a symbolic link pointing to with the - name , like .

+ name , like + file:make_symlink/2

 @@ -504,7 +505,8 @@

Reads a file from the server, and returns the data in a binary, - like .

+ like + file:read_file/1

 @@ -523,7 +525,7 @@

Returns a record from the file specified by or , - like .

+ like file:read_file_info/2

 @@ -539,7 +541,8 @@

Reads the link target from the symbolic link specified - by , like .

+ by , like + file:read_link/1

 @@ -558,7 +561,7 @@

Returns a record from the symbolic link specified by or , like - .

+ file:read_link_info/2

 @@ -575,7 +578,8 @@

Renames a file named and gives it the name - , like .

+ , like + file:rename/2

 @@ -649,9 +653,10 @@ Reason = term() -

Writes a file to the server, like - . The file is created if - it does not exist. The file is overwritten if it exists.

+

Writes a file to the server, like file:write_file/2 The + file is created if it does not exist. The file is overwritten + if it exists.

 @@ -699,7 +704,8 @@

Writes file information from a record to the - file specified by , like .

+ file specified by , like + file:write_file_info/[2,3]

 -- 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(-) 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 From 6cedde4ae59a6e8505d7fc8ac22111a7a8b15e4c Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 16:17:50 +0200 Subject: ssh: Move code example to Users Guide --- lib/ssh/doc/src/ssh_sftp.xml | 65 +++-------------------------------------- lib/ssh/doc/src/using_ssh.xml | 67 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 61 deletions(-) diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index d52613c6bc..4ed5a38de4 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -300,20 +300,9 @@ erl_tar:init/3 function.

-

Example of writing and then reading a tar file follows:

- - {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), - ok = erl_tar:add(HandleWrite, .... ), - ok = erl_tar:add(HandleWrite, .... ), - ... - ok = erl_tar:add(HandleWrite, .... ), - ok = erl_tar:close(HandleWrite), - - %% And for reading - {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read]), - {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]), - ok = erl_tar:close(HandleRead), - +

For code exampel see Section + SFTP Client with TAR Compression and Encryption in + the ssh Users Guide.

The crypto mode option is applied to the generated stream of bytes prior to sending them to the SFTP server. This is intended for encryption but can be used for other @@ -332,53 +321,7 @@ ChunkSizes can be changed in the return from the EncryptFun or DecryptFun. The value can be changed between pos_integer() and undefined.

-

The previous write and read example can be extended with encryption and decryption as follows:

- - %% First three parameters depending on which crypto type we select: - Key = <<"This is a 256 bit key. abcdefghi">>, - Ivec0 = crypto:rand_bytes(16), - DataSize = 1024, % DataSize rem 16 = 0 for aes_cbc - - %% Initialization of the CryptoState, in this case it is the Ivector. - InitFun = fun() -> {ok, Ivec0, DataSize} end, - - %% How to encrypt: - EncryptFun = - fun(PlainBin,Ivec) -> - EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, PlainBin), - {ok, EncryptedBin, crypto:next_iv(aes_cbc,EncryptedBin)} - end, - - %% What to do with the very last block: - CloseFun = - fun(PlainBin, Ivec) -> - EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, - pad(16,PlainBin) %% Last chunk - ), - {ok, EncryptedBin} - end, - - Cw = {InitFun,EncryptFun,CloseFun}, - {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write,{crypto,Cw}]), - ok = erl_tar:add(HandleWrite, .... ), - ok = erl_tar:add(HandleWrite, .... ), - ... - ok = erl_tar:add(HandleWrite, .... ), - ok = erl_tar:close(HandleWrite), - - %% And for decryption (in this crypto example we could use the same InitFun - %% as for encryption): - DecryptFun = - fun(EncryptedBin,Ivec) -> - PlainBin = crypto:block_decrypt(aes_cbc256, Key, Ivec, EncryptedBin), - {ok, PlainBin, crypto:next_iv(aes_cbc,EncryptedBin)} - end, - - Cr = {InitFun,DecryptFun}, - {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]), - {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]), - ok = erl_tar:close(HandleRead), - + diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index 64477cb493..9da839d072 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -228,6 +228,73 @@
+
+ SFTP Client with TAR Compression and Encryption + +

Example of writing and then reading a tar file follows:

+ + {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), + ok = erl_tar:add(HandleWrite, .... ), + ok = erl_tar:add(HandleWrite, .... ), + ... + ok = erl_tar:add(HandleWrite, .... ), + ok = erl_tar:close(HandleWrite), + + %% And for reading + {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read]), + {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]), + ok = erl_tar:close(HandleRead), + + +

The previous write and read example can be extended with encryption and decryption as follows:

+ + %% First three parameters depending on which crypto type we select: + Key = <<"This is a 256 bit key. abcdefghi">>, + Ivec0 = crypto:rand_bytes(16), + DataSize = 1024, % DataSize rem 16 = 0 for aes_cbc + + %% Initialization of the CryptoState, in this case it is the Ivector. + InitFun = fun() -> {ok, Ivec0, DataSize} end, + + %% How to encrypt: + EncryptFun = + fun(PlainBin,Ivec) -> + EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, PlainBin), + {ok, EncryptedBin, crypto:next_iv(aes_cbc,EncryptedBin)} + end, + + %% What to do with the very last block: + CloseFun = + fun(PlainBin, Ivec) -> + EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, + pad(16,PlainBin) %% Last chunk + ), + {ok, EncryptedBin} + end, + + Cw = {InitFun,EncryptFun,CloseFun}, + {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write,{crypto,Cw}]), + ok = erl_tar:add(HandleWrite, .... ), + ok = erl_tar:add(HandleWrite, .... ), + ... + ok = erl_tar:add(HandleWrite, .... ), + ok = erl_tar:close(HandleWrite), + + %% And for decryption (in this crypto example we could use the same InitFun + %% as for encryption): + DecryptFun = + fun(EncryptedBin,Ivec) -> + PlainBin = crypto:block_decrypt(aes_cbc256, Key, Ivec, EncryptedBin), + {ok, PlainBin, crypto:next_iv(aes_cbc,EncryptedBin)} + end, + + Cr = {InitFun,DecryptFun}, + {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]), + {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]), + ok = erl_tar:close(HandleRead), + +
+
Creating a Subsystem -- cgit v1.2.3