# ssh_cm

### MODULE

ssh_cm

### MODULE SUMMARY

SSH connection layer.

### DESCRIPTION

This module implements the SSH connection layer.

### EXPORTS

`connect(Host) -> {ok, Pid} | {error, Error}`
`connect(Host, Options) -> {ok, Pid} | {error, Error}`
`connect(Host, Port, Options) -> {ok, Pid} | {error, Error}`

Types:

`Host = string()`
`Port = integer()`
`Options = [{Option, Value}]`

Connects to an SSH server. A `gen_server` is started and returned if connection is successful, but no channel is started, that is done with `session_open/2`. The `Host` is a string with the address of a host running an SSH server. The `Port` is an integer, the port to connect to. The default is `22`, the registered port for SSH.

Options are:

`{user_dir, String}`
  Sets the user directory, normally `~/.ssh` (containing the files `known_hosts`, `id_rsa<c>, <c>id_dsa`, `authorized_keys`).
`{silently_accept_hosts, Boolean}`
  When true, (default is false), hosts are added to the file `known_hosts` without asking the user.
`{user_interaction, Boolean}`
  If true, which is the default, password questions and adding hosts to `known_hosts` will be asked interactively to the user. (This is done during connection to an SSH server.) If false, both these interactions will throw and the server will not start.
`{public_key_alg, ssh_rsa | ssh_dsa}`
  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 `ssh_rsa` first.
`{connect_timeout, Milliseconds | infinity}`
  Sets the default timeout when trying to connect to an SSH server. This timeout will also affect calls later when using the SSH connection.
`{user, String}`
  Provide a username. If this option is not given, ssh reads from the environment (`LOGNAME` or `USER` on unix, `USERNAME` on Windows).
`{password, String}`
  Provide a password for password authentication. If this option is not given, the user will be asked for a password.
`{user_auth, Fun/3}`
  Provide a fun for password authentication. The fun will be called as `fun(User, Password, Opts)` and should return `true` or `false`.
`{key_cb, KeyCallbackModule}`
  Provide a special call-back module for key handling. The call-back module should be modeled after the `ssh_file` module. The function that must be exported are: `private_host_rsa_key/2`, `private_host_dsa_key/2`, `lookup_host_key/3` and `add_host_key/3`.

As usual, boolean options that should be `true` can be given as an atom instead of a tuple, e.g. `silently_accept_hosts` instead of `{silently_accept_hosts, true}`.

`listen(UserFun, Options) -> ok`
`listen(UserFun, Port, Options) -> ok`
`listen(UserFun, Addr, Port, Options) -> ok`

Types:

`UserFun = fun() -> Pid`
`Port = integer()`
`Addr = string() | any`
`Options = [{Option, Value}]`
`Option = atom()`
`Value = term()`

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

`UserFun` is a function that should spawn and return a server upon incoming connections on the given port (and address).

`Port` is the port that the server should listen on. Everytime a connection is made on that port, the `UserFun` is called, and the returned process is used as a user process for the server.

Options are:

`{system_dir, String}`
  Sets the system directory, containing the host files that identifies the host for ssh. The default is `/etc/ssh`, but note that SSH normally requires the host files there to be readable only by root.
`{user_passwords, [{User, Password}]}`
  Provide passwords for password authentication.They will be used when someone tries to connect to the server and public key user autentication fails. The option provides a list of valid user names and the corresponding password. `User` and `Password` are strings.
`{password, String}`
  Provide a global password that will authenticate any user (use with caution!).
  If neither of these options is given, the server will be unable to authenticate with password.

`stop_listener(Pid) -> ok | {error, Reason}`

Types:

`Pid = pid()`
`Reason = atom()`

Stops the listener, given by `Pid`, existing connections will stay open.

### AUTHORS

Jakob Cederlund - support@erlang.ericsson.se

ssh 0.9.5
Copyright © 1991-2006 Ericsson AB