aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc/src/ssh.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssh/doc/src/ssh.xml')
-rw-r--r--lib/ssh/doc/src/ssh.xml213
1 files changed, 117 insertions, 96 deletions
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 57f09c0cf0..f57ee13460 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2004</year><year>2012</year>
+ <year>2004</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -22,13 +22,7 @@
</legalnotice>
<title>ssh</title>
- <prepared>Ingela Anderton Andin</prepared>
- <responsible>H&aring;kan Mattsson</responsible>
- <docno></docno>
- <approved>H&aring;kan Mattsson</approved>
- <checked></checked>
<date>2007-10-06</date>
- <rev>PA1</rev>
</header>
<module>ssh</module>
<modulesummary>Main API of the SSH application</modulesummary>
@@ -40,80 +34,85 @@
<title>SSH</title>
<list type="bulleted">
- <item>ssh requires the crypto and public_key applications.</item>
- <item>Supported SSH-version is 2.0 </item>
- <item>Currently supports only a minimum of mac and encryption algorithms i.e.
- hmac-sha1, and aes128-cb and 3des-cbc.</item>
+ <item>SSH requires the crypto and public_key applications.</item>
+ <item>Supported SSH version is 2.0 </item>
+ <item>Supported MAC algorithms: hmac-sha1</item>
+ <item>Supported encryption algorithms: aes128-cb and 3des-cbc</item>
</list>
</section>
<section>
- <title>COMMON DATA TYPES </title>
+ <title>DATA TYPES </title>
<p>Type definitions that are used more than once in
- this module:</p>
+ this module and/or abstractions to indicate the intended use of the data
+ type:</p>
<p><c>boolean() = true | false </c></p>
- <p><c>string() = list of ASCII characters</c></p>
+ <p><c>string() = [byte()]</c></p>
<p><c>ssh_daemon_ref() - opaque to the user
returned by ssh:daemon/[1,2,3]</c></p>
<p><c>ssh_connection_ref() - opaque to the user
returned by ssh:connect/3</c></p>
<p><c>ip_address() - {N1,N2,N3,N4} % IPv4 |
{K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p>
- <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>
+ <p><c>subsystem_spec() = {subsystem_name(),
+ {channel_callback(), channel_init_args()}} </c></p>
<p><c>subsystem_name() = string() </c></p>
<p><c>channel_callback() = atom() - Name of the erlang module
implementing the subsystem using the ssh_channel behavior see</c>
<seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
<p><c>channel_init_args() = list()</c></p>
</section>
-
+
<funcs>
<func>
<name>close(ConnectionRef) -> ok </name>
- <fsummary>Closes a ssh connection</fsummary>
+ <fsummary>Closes an SSH connection</fsummary>
<type>
<v>ConnectionRef = ssh_connection_ref()</v>
</type>
- <desc><p>Closes a ssh connection.</p>
+ <desc><p>Closes an SSH connection.</p>
</desc>
</func>
<func>
<name>connect(Host, Port, Options) -> </name>
- <name>connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()}
- | {error, Reason}</name>
+ <name>connect(Host, Port, Options, Timeout) -> {ok,
+ ssh_connection_ref()} | {error, Reason}</name>
<fsummary>Connect to an ssh server.</fsummary>
<type>
<v>Host = string()</v>
<v>Port = integer()</v>
- <d>The default is <c><![CDATA[22]]></c>, the registered port for SSH.</d>
+ <d>The default is <c><![CDATA[22]]></c>, the assigned well known port
+ number for SSH.</d>
<v>Options = [{Option, Value}]</v>
<v>Timeout = infinity | integer(milliseconds)</v>
</type>
<desc>
- <p>Connects to an SSH server. No channel is started this is done
+ <p>Connects to an SSH server. No channel is started. This is done
by calling ssh_connect:session_channel/2.</p>
<p>Options are:</p>
<taglist>
<tag><c><![CDATA[{user_dir, string()}]]></c></tag>
<item>
- <p>Sets the user directory e.i. the directory containing
+ <p>Sets the user directory i.e. the directory containing
ssh configuration files for the user such as
- <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa, id_dsa]]></c> and
- <c><![CDATA[authorized_key]]></c>. Defaults to the directory normally
- referred to as <c><![CDATA[~/.ssh]]></c> </p>
+ <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
+ id_dsa]]></c> and
+ <c><![CDATA[authorized_key]]></c>. Defaults to the
+ directory normally referred to as
+ <c><![CDATA[~/.ssh]]></c> </p>
</item>
<tag><c><![CDATA[{dsa_pass_phrase, string()}]]></c></tag>
<item>
- <p>If the user dsa key is protected by a pass phrase it can be
+ <p>If the user dsa key is protected by a passphrase it can be
supplied with this option.
</p>
</item>
<tag><c><![CDATA[{rsa_pass_phrase, string()}]]></c></tag>
<item>
- <p>If the user rsa key is protected by a pass phrase it can be
+ <p>If the user rsa key is protected by a passphrase it can be
supplied with this option.
</p>
</item>
@@ -135,25 +134,26 @@
password. Do note that it may not always be desirable to use
those options from a security point of view.</p>
</item>
- <tag><c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></tag>
+ <tag><c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></tag>
<item>
<p>Sets the preferred public key algorithm to use for user
- authentication. If the the preferred algorithm fails of
+ authentication. If the the preferred algorithm fails for
some reason, the other algorithm is tried. The default is
to try <c><![CDATA[ssh_rsa]]></c> first.</p>
</item>
<tag><c><![CDATA[{pref_public_key_algs, list()}]]></c></tag>
<item>
- <p>List of public key algorithms to try to use, ssh_rsa and ssh_dsa available.
- Will override <c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></p>
+ <p>List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available.
+ Will override <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p>
</item>
<tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag>
<item>
- <p>Sets a timeout on the transport layer connection. Defaults to infinity.</p>
+ <p>Sets a timeout on the transport layer
+ connection. Defaults to <c>infinity</c>.</p>
</item>
- <tag><c><![CDATA[{user, String}]]></c></tag>
+ <tag><c><![CDATA[{user, string()}]]></c></tag>
<item>
- <p>Provide a user name. If this option is not given, ssh
+ <p>Provides a user name. If this option is not given, ssh
reads from the environment (<c><![CDATA[LOGNAME]]></c> or
<c><![CDATA[USER]]></c> on unix,
<c><![CDATA[USERNAME]]></c> on Windows).</p>
@@ -165,23 +165,11 @@
password if the password authentication method is
attempted.</p>
</item>
- <tag><c><![CDATA[{user_auth, Fun/3}]]></c></tag>
- <item>
- <p>Provide a fun for password authentication. The fun
- will be called as <c><![CDATA[fun(User, Password, Opts)]]></c> and
- should return <c><![CDATA[true]]></c> or <c><![CDATA[false]]></c>.</p>
- </item>
- <tag><c><![CDATA[{key_cb, atom() = KeyCallbackModule}]]></c></tag>
+ <tag><c><![CDATA[{key_cb, atom()}]]></c></tag>
<item>
- <p>Provide a special call-back module for key handling.
- The call-back module should be modeled after the
- <c><![CDATA[ssh_file]]></c> module. The functions that must
- be exported are:
- <c><![CDATA[private_host_rsa_key/2]]></c>,
- <c><![CDATA[private_host_dsa_key/2]]></c>,
- <c><![CDATA[lookup_host_key/3]]></c> and
- <c><![CDATA[add_host_key/3]]></c>. This is considered
- somewhat experimental and will be better documented later on.</p>
+ <p>Module implementing the behaviour <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>.
+ Can be used to customize the handling of public keys.
+ </p>
</item>
<tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag>
<item>
@@ -189,17 +177,27 @@
</item>
<tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
<item>
- <p>Allow an existing file-descriptor to be used
+ <p>Allow an existing file descriptor to be used
(simply passed on to the transport protocol).</p></item>
- <tag><c><![CDATA[{ip_v6_disabled, boolean()}]]></c></tag>
+ <tag><c><![CDATA[{ipv6_disabled, boolean()}]]></c></tag>
+ <item>
+ <p>Determines if SSH shall use IPv6 or not.</p>
+ </item>
+ <tag><c><![CDATA[{rekey_limit, integer()}]]></c></tag>
+ <item>
+ <p>Provide, in bytes, when rekeying should be initiated,
+ defaults to one time each GB and one time per hour.</p>
+ </item>
+ <tag><c><![CDATA[{idle_time, integer()}]]></c></tag>
<item>
- <p>Determines if SSH shall use IPv6 or not.</p></item>
+ <p>Sets a timeout on connection when no channels are active, default is infinity</p></item>
</taglist>
</desc>
</func>
<func>
- <name>connection_info(ConnectionRef, [Option]) ->[{Option, Value}] </name>
+ <name>connection_info(ConnectionRef, [Option]) ->[{Option,
+ Value}] </name>
<fsummary> Retrieves information about a connection. </fsummary>
<type>
<v>Option = client_version | server_version | peer</v>
@@ -214,7 +212,8 @@
<func>
<name>daemon(Port) -> </name>
<name>daemon(Port, Options) -> </name>
- <name>daemon(HostAddress, Port, Options) -> ssh_daemon_ref()</name>
+ <name>daemon(HostAddress, Port, Options) -> {ok,
+ ssh_daemon_ref()} | {error, atom()}</name>
<fsummary>Starts a server listening for SSH connections
on the given port.</fsummary>
<type>
@@ -225,30 +224,32 @@
<v>Value = term()</v>
</type>
<desc>
- <p>Starts a server listening for SSH connections on the given port.</p>
-
- <p>Options are:</p>
+ <p>Starts a server listening for SSH connections on the given
+ port.</p>
+ <p>Options are:</p>
<taglist>
<tag><c><![CDATA[{subsystems, [subsystem_spec()]]]></c></tag>
<item>
- Provides specifications for handling of subsystems. The
- "sftp" subsystem-spec can be retrieved by calling
- ssh_sftpd:subsystem_spec/1. If the subsystems option in not present
- the value of <c>[ssh_sftpd:subsystem_spec([])]</c> will be used.
- It is of course possible to set the option to the empty list
- if you do not want the daemon to run any subsystems at all.
+ Provides specifications for handling of subsystems. The
+ "sftp" subsystem spec can be retrieved by calling
+ ssh_sftpd:subsystem_spec/1. If the subsystems option in
+ not present the value of
+ <c>[ssh_sftpd:subsystem_spec([])]</c> 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.
</item>
- <tag><c><![CDATA[{shell, {Module, Function, Args} | fun(string() = User) - > pid() |
- fun(string() = User, ip_address() = PeerAddr) -> pid()}]]></c></tag>
+ <tag><c><![CDATA[{shell, {Module, Function, Args} |
+ fun(string() = User) - > pid() | fun(string() = User,
+ ip_address() = PeerAddr) -> pid()}]]></c></tag>
<item>
- Defines the read-eval-print loop used when a shell is requested
- by the client. Example use the
- erlang shell: <c><![CDATA[{shell, start, []}]]></c> which is
- the default behavior.
+ Defines the read-eval-print loop used when a shell is
+ requested by the client. Default is to use the erlang shell:
+ <c><![CDATA[{shell, start, []}]]></c>
</item>
- <tag><c><![CDATA[{ssh_cli,{channel_callback(), channel_init_args()}}]]></c></tag>
+ <tag><c><![CDATA[{ssh_cli,{channel_callback(),
+ channel_init_args()}}]]></c></tag>
<item>
- Provide your own cli implementation, e.i. a channel callback
+ Provides your own cli implementation, i.e. a channel callback
module that implements a shell and command execution. Note
that you may customize the shell read-eval-print loop using the
option <c>shell</c> which is much less work than implementing
@@ -256,27 +257,30 @@
</item>
<tag><c><![CDATA[{user_dir, String}]]></c></tag>
<item>
- <p>Sets the user directory e.i. the directory containing
+ <p>Sets the user directory i.e. the directory containing
ssh configuration files for the user such as
- <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa, id_dsa]]></c> and
- <c><![CDATA[authorized_key]]></c>. Defaults to the directory normally
- referred to as <c><![CDATA[~/.ssh]]></c> </p>
+ <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
+ id_dsa]]></c> and
+ <c><![CDATA[authorized_key]]></c>. Defaults to the
+ directory normally referred to as
+ <c><![CDATA[~/.ssh]]></c> </p>
</item>
<tag><c><![CDATA[{system_dir, string()}]]></c></tag>
<item>
- <p>Sets the system directory, containing the host files
- that identifies the host for ssh. The default is
- <c><![CDATA[/etc/ssh]]></c>, note that SSH normally
- requires the host files there to be readable only by
- root.</p>
+ <p>Sets the system directory, containing the host key files
+ that identifies the host keys for ssh. The default is
+ <c><![CDATA[/etc/ssh]]></c>, note that for security reasons
+ this directory is normally only accessible by the root user.</p>
</item>
<tag><c><![CDATA[{auth_methods, string()}]]></c></tag>
<item>
- <p>Comma separated string that determines which authentication methodes that the server
- should support and in what order they will be tried. Defaults to
- <c><![CDATA["publickey,keyboard_interactive,password"]]></c></p>
+ <p>Comma separated string that determines which
+ authentication methodes that the server should support and
+ in what order they will be tried. Defaults to
+ <c><![CDATA["publickey,keyboard-interactive,password"]]></c></p>
</item>
- <tag><c><![CDATA[{user_passwords, [{string() = User, string() = Password}]}]]></c></tag>
+ <tag><c><![CDATA[{user_passwords, [{string() = User,
+ string() = Password}]}]]></c></tag>
<item>
<p>Provide passwords for password authentication.They will
be used when someone tries to connect to the server and
@@ -290,13 +294,19 @@
user. From a security perspective this option makes
the server very vulnerable.</p>
</item>
- <tag><c><![CDATA[{pwdfun, fun/2}]]></c></tag>
+ <tag><c><![CDATA[{pwdfun, fun(User::string(), password::string() -> boolean()}]]></c></tag>
<item>
<p>Provide a function for password validation. This is called
with user and password as strings, and should return
<c><![CDATA[true]]></c> if the password is valid and
<c><![CDATA[false]]></c> otherwise.</p>
</item>
+ <tag><c><![CDATA[{key_cb, atom()}]]></c></tag>
+ <item>
+ <p>Module implementing the behaviour <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
+ Can be used to customize the handling of public keys.
+ </p>
+ </item>
<tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
<item>
<p>Allow an existing file-descriptor to be used
@@ -305,6 +315,18 @@
<item>
<p>Determines if SSH shall use IPv6 or not (only used when
HostAddress is set to any).</p></item>
+ <tag><c><![CDATA[{failfun, fun()}]]></c></tag>
+ <item>
+ <p>Provide a fun() to implement your own logging when a user fails to authenticate.</p>
+ </item>
+ <tag><c><![CDATA[{connectfun, fun()}]]></c></tag>
+ <item>
+ <p>Provide a fun() to implement your own logging when a user authenticates to the server.</p>
+ </item>
+ <tag><c><![CDATA[{disconnectfun, fun()}]]></c></tag>
+ <item>
+ <p>Provide a fun() to implement your own logging when a user disconnects from the server.</p>
+ </item>
</taglist>
</desc>
</func>
@@ -320,9 +342,9 @@
<v> Options - see ssh:connect/3</v>
</type>
<desc>
- <p>Starts an interactive shell to an SSH server on the
+ <p>Starts an interactive shell via an SSH server on the
given <c>Host</c>. The function waits for user input,
- and will not return until the remote shell is ended (e.g. on
+ and will not return until the remote shell is ended (i.e.
exit from the shell).
</p>
</desc>
@@ -331,25 +353,24 @@
<func>
<name>start() -> </name>
<name>start(Type) -> ok | {error, Reason}</name>
- <fsummary>Starts the Ssh application. </fsummary>
+ <fsummary>Starts the SSH application. </fsummary>
<type>
<v>Type = permanent | transient | temporary</v>
<v>Reason = term() </v>
</type>
<desc>
- <p>Starts the Ssh application. Default type
- is temporary. See also
- <seealso marker="kernel:application">application(3)</seealso>
- Requires that the crypto application has been started.
+ <p>Utility function that starts crypto, public_key and the SSH
+ application. Defult type is temporary.
+ See also <seealso marker="kernel:application">application(3)</seealso>
</p>
</desc>
</func>
<func>
<name>stop() -> ok </name>
- <fsummary>Stops the Ssh application.</fsummary>
+ <fsummary>Stops the SSH application.</fsummary>
<desc>
- <p>Stops the Ssh application. See also
+ <p>Stops the SSH application. See also
<seealso marker="kernel:application">application(3)</seealso></p>
</desc>
</func>