From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/ssh/doc/src/ssh.xml | 337 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 lib/ssh/doc/src/ssh.xml (limited to 'lib/ssh/doc/src/ssh.xml') diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml new file mode 100644 index 0000000000..aca5c9cdc4 --- /dev/null +++ b/lib/ssh/doc/src/ssh.xml @@ -0,0 +1,337 @@ + + + + +
+ + 20042009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + 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 + Ingela Anderton Andin + Håkan Mattsson + + Håkan Mattsson + + 2007-10-06 + PA1 +
+ ssh + Main API of the SSH application + +

Interface module for the SSH application

+ + + +
+ COMMON DATA TYPES +

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

+

boolean() = true | false

+

string() = list of ASCII characters

+

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() - {N1,N2,N3,N4} % IPv4 | + {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

+

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

+

subsystem_name() = string()

+

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

+

channel_init_args() = list()

+
+ + + + + close(ConnectionRef) -> ok + Closes a ssh connection + + ConnectionRef = ssh_connection_ref() + +

Closes a ssh connection.

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

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

+

Options are:

+ + + +

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

+ + + +

When true hosts are added to the + file without asking the user. + 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. + 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.

+ + + +

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

+ + + +

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

+ + + +

Provide a user name. If this option is not given, ssh + reads from the environment ( or + 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 + attempted.

+ + + +

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

+ + + +

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

+ + + +

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

 + + + + + + connection_info(ConnectionRef, [Option]) ->[{Option, Value}] + Retrieves information about a connection. + + Option = client_version | server_version | peer + Value = term() + + +

Retrieves information about a connection. +

+ + + + + daemon(Port) -> + daemon(Port, Options) -> + daemon(HostAddress, Port, Options) -> ssh_daemon_ref() + Starts a server listening for SSH connections + on the given port. + + Port = integer() + HostAddress = ip_address() | any + Options = [{Option, Value}] + Option = atom() + Value = term() + + +

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

+ +

Options are:

+ + + + Provides specifications for handling of subsystems. The + "sftp" subsystem-spec can be retrieved by calling + ssh_sftd:subsystem_spec/1. If the subsystems option in not present + the value of [ssh_sftd:subsystem_spec([])] will be used. + It is of course possible to set the option to the empty list + if you do not want the daemon to run any subsystems at all. + + pid() | + fun(string() = User, ip_address() = PeerAddr) -> pid()}]]> + + Defines the read-eval-print loop used when a shell is requested + by the client. Example use the + erlang shell: which is + the default behavior. + + + + Provide your own cli implementation, e.i. 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. + + + +

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

+ + + +

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. +

+ + + +

Provide a global password that will authenticate any + user. From a security perspective this option makes + the server very vulnerable.

+ + + +

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

+ + + +

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

 + + + + + + shell(Host) -> + shell(Host, Option) -> + shell(Host, Port, Option) -> _ + + + Host = string() + Port = integer() + Options - see ssh:connect/3 + + +

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

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

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

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

Stops the Ssh application. See also + application(3)

+ + + + + stop_daemon(DaemonRef) -> + stop_daemon(Address, Port) -> ok + Stops the listener and all connections started by + the listener. + + DaemonRef = ssh_daemon_ref() + Address = ip_address() + Port = integer() + + +

Stops the listener and all connections started by + the listener.

+ + + + + stop_listener(DaemonRef) -> + stop_listener(Address, Port) -> ok + Stops the listener, but leaves existing connections started + by the listener up and running. + + DaemonRef = ssh_daemon_ref() + Address = ip_address() + Port = integer() + + +

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

+ + + + + -- cgit v1.2.3