This is the interface module for the
With the SSH application it is possible to start clients and to start daemons (servers).
Clients are started with
Each channel is an isolated "pipe" between a client-side process and a server-side process. Thoose process pairs could handle for example file transfers (sftp) or remote command execution (shell, exec and/or cli). If a custom shell is implemented, the user of the client could execute the special commands remotely. Note that the user is not necessarily a human but probably a system interfacing the SSH app.
A server-side subssystem (channel) server is requested by the client with
A server (daemon) is started with
To just run a shell on a remote machine, there are functions that bundles the needed
three steps needed into one:
To write your own client channel handler, use the behaviour
Both clients and daemons accepts options that controls the exact behaviour. Some options are common to both.
The three sets are called
The descriptions of the options uses the
The
A number of objects must be present for the SSH application to work.
Thoose objects are per default stored in files.
The default names, paths and file formats are the same as for
The paths could easily be changed by options:
A completly different storage could be interfaced by writing call-back modules
using the behaviours
The keys are by default stored in files:
The host keys directory could be changed with the option
The user keys directory could be changed with the option
The keys and some other data are by default stored in files in the directory
The directory could be changed with the option
The
Options for
List of user (client) public key algorithms to try to use.
The default value is the
If there is no public key of a specified type available, the corresponding entry is ignored. Note that the available set is dependent on the underlying cryptolib and current user's public keys.
See also the option
If the user's DSA, RSA or ECDSA key is protected by a passphrase, it can be supplied with thoose options.
This option guides the
The option can be given in three different forms as seen above:
If
Even if user interaction is allowed it can be
suppressed by other options, such as
Defaults to
If
If
Defaults to
If
Defaults to
Provides the username. If this option is not given,
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.
Sets the three diffie-hellman-group-exchange parameters that guides the connected server in choosing a group.
See
Sets a timeout on the transport layer connect time.
For
See the parameter
Make the client tell the server that the client accepts extension negotiation, that is,
include
Default value is
Options for
Defines a subsystem in the daemon.
The
The
If the subsystems option is not present, the value of
Defines the read-eval-print loop used in a daemon when a shell is requested by the client.
The default is to use the Erlang shell:
See the option
This option changes how the daemon execute exec-requests from clients. The term in the return value is formatted to a string if it is a non-string type. No trailing newline is added in the ok-case but in the error case.
Error texts are returned on channel-type 1 which usually is piped to
The option cooperates with the daemon-option
The exec-option fun is called with the same number of parameters as the arity of the fun, and the result is returned to the client.
The default Erlang evaluator is used and the result is returned to the client.
The exec-request is not evaluated and an error message is returned to the client.
The default Erlang evaluator is used and the result is returned to the client.
If a custom CLI is installed (see the option
The exec-option has existed for a long time but has not previously been documented. The old definition and behaviour are retained but obey the rules 1-4 above if conflicting. The old and undocumented style should not be used in new programs.
Provides your own CLI implementation in a daemon.
It is a channel callback module that implements a shell
and command execution. The shell's read-eval-print loop can be customized, using the
option
Sets the system directory, containing the host key files
that identify the host keys for
For security reasons, this directory is normally accessible only to the root user.
See also the option
Sets the text strings that the daemon sends to the client for presentation to the user when
using
If the fun/3 is used, it is called when the actual authentication occurs and may therefore return dynamic data like time, remote ip etc.
The parameter
The default value is:
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.
Provides a global password that authenticates any user.
Intended to facilitate testing.
From a security perspective this option makes the server very vulnerable.
Provides a function for password validation. This could used for calling an external system or handeling passwords stored as hash values.
This fun can also be used to make delays in authentication tries for example by calling
To facilitate for instance counting of failed tries,
the
The fun should return:
A third usage is to block login attempts from a missbehaving peer. The
Provides a function for password validation. This function is called with user and password as strings, and returns:
This variant is kept for compatibility.
Defines the groups the server may choose among when diffie-hellman-group-exchange is negotiated.
See
The default list is fetched from the
Limits what a client can ask for in diffie-hellman-group-exchange.
The limits will be
The default value is
If
See
Maximum time in milliseconds for the authentication negotiation. Defaults to 120000 ms (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.
Thus, if set to
The counter is per listening port. Thus, if two daemons are started, one with
Notice that if
By default, this option is not set. This means that the number is not limited.
The maximum number of channels with active remote subsystem that are accepted for each connection to this daemon
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 at a time. If set to true, an unlimited number of login attempts are allowed simultaneously.
If the
Do not enable
The least maximum packet size that the daemon will accept in channel open requests from the client. The default value is 0.
Provides 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 fails to authenticate.
Make the server (daemon) tell the client that the server accepts extension negotiation, that is,
include
Default value is
The options above can be used both in clients and in daemons (servers). They are further explained below.
Sets the user directory. That is, the directory containing
See also the option
Used together with
Sets a time-out on a connection when no channels are active. Defaults to
Sets a limit, in bytes, when rekeying is to be initiated. Defaults to once per each GB and once per hour.
Module implementing the behaviour
The
The default value of this option is
A call to the call-back function
Module:F(..., [{key_cb_private,Opts}|UserOptions])
where
Provides a fun to implement your own logging when the peer disconnects.
Provides a fun to implement your own logging or other action when an unexpected message arrives.
If the fun returns
Provide a fun to implement your own logging of the SSH message SSH_MSG_DEBUG.
The last three parameters are from the message, see
The default behaviour is ignore the message.
To get a printout for each message with
The string the daemon will present to a connecting peer initially. The default value is "Erlang/VSN" where VSN is the ssh application version number.
The value
The value
List of algorithms to use in the algorithm negotiation. The default
If an alg_entry() is missing in the algs_list(), the default value is used for that entry.
Here is an example of this option:
{preferred_algorithms,
[{public_key,['ssh-rsa','ssh-dss']},
{cipher,[{client2server,['aes128-ctr']},
{server2client,['aes128-cbc','3des-cbc']}]},
{mac,['hmac-sha2-256','hmac-sha1']},
{compression,[none,zlib]}
]
}
The example specifies different algorithms in the two directions (client2server and server2client), for cipher but specifies the same algorithms for mac and compression in both directions. The kex (key exchange) is implicit but public_key is set explicitly.
For background and more examples see the
If an algorithm name occurs more than once in a list, the behaviour is undefined. The tags in the property lists are also assumed to occur at most one time.
Changing the values can make a connection less secure. Do not change unless you know exactly what you are doing. If you do not understand the values then you are not supposed to change them.
Modifies the list of algorithms to use in the algorithm negotiation. The modifications are
applied after the option
The algoritm for modifications works like this:
Input is the
The head of the
The possible modifications are:
Append or prepend supported but not enabled algorithm(s) to the list of
algorithms. If the wanted algorithms already are in
Remove (rm) one or more algorithms from
Repeat the modification step with the tail of
If an unsupported algorithm is in the
If there are more than one modify_algorithms options, the result is undefined.
Here is an example of this option:
{modify_algorithms,
[{prepend, [{kex, ['diffie-hellman-group1-sha1']}],
{rm, [{compression, [none]}]}
]
}
The example specifies that:
the old key exchange algorithm 'diffie-hellman-group1-sha1' should be the main alternative. It will be the main alternative since it is prepened to the list
The compression algorithm none (= no compression) is removed so compression is enforced
For background and more examples see the
IP version to use when the host address is specified as
Comma-separated string that determines which authentication methods that the client shall
support and in which order they are tried. Defaults to
Note that the client is free to use any order and to exclude methods.
Allows an existing file-descriptor to be used (passed on to the transport protocol).
The socket is supposed to be result of a
Opaque data type representing a daemon.
Returned by the functions
Opaque data type representing a connection between a client and a server (daemon).
Returned by the functions
Opaque data type representing a channel inside a connection.
Returned by the functions
Opaque types that define experimental options that are not to be used in products.
Closes an SSH connection.
Connects to an SSH server at the
As an alternative, an already open TCP socket could be passed to the function in
No channel is started. This is done by calling
The
Retrieves information about a connection. The list
Starts a server listening for SSH connections on the given port. If the
As an alternative, an already open TCP socket could be passed to the function in
For a description of the options, see
Please note that by historical reasons both the
The rules for handling the two address passing options are:
Returns a key-value list with information about the daemon.
Returns a key-value list, where the keys are the different types of algorithms and the values are the algorithms themselves.
See the
Connects to an SSH server at
As an alternative, an already open TCP socket could be passed to the function in
For a description of the options, see
The function waits for user input, and does not return until the remote shell is ended (that is, exit from the shell).
Utility function that starts the applications
Stops the
Stops the listener and all connections started by the listener.
Stops the listener, but leaves existing connections started by the listener operational.