---
name: "ssh_cm"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:12.b.3-1"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/ssh_cm"
---

# ssh\_cm(3erl)

SSH connection layer.

## NAME

ssh\_cm - 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*.

- ***{fd, FD}*:**

  Allow an existing file-descriptor to be used, given in FD. (Simply passed on to gen\_tcp:listen.)

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.

- ***{pwdfun, fun/2}*:**

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

- ***{fd, FD}*:**

  Allow an existing file-descriptor to be used, given in FD. (Simply passed on to gen\_tcp:listen.)

**stop\_listener(Pid) -\> ok \| {error, Reason}**\

- Types

  Pid = pid()\
   Reason = atom()\

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