Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       ssh - Main API of the SSH application

DESCRIPTION

       Interface module for the SSH application.

SSH

         * SSH requires the crypto and public_key applications.

         * Supported SSH version is 2.0

         * Supported MAC algorithms: hmac-sha1

         * Supported encryption algorithms: aes128-cb and 3des-cbc

DATA TYPES

       Type  definitions  that  are  used  more  than  once in this module and/or abstractions to
       indicate the intended use of the data type:

       boolean() = true | false

       string() = [byte()]

       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() - inet::ip_address()

       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(3erl)

       channel_init_args() = list()

EXPORTS

       close(ConnectionRef) -> ok

              Types:

                 ConnectionRef = ssh_connection_ref()

              Closes an SSH connection.

       connect(Host, Port, Options) ->
       connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()} | {error, Reason}

              Types:

                 Host = string()
                 Port = integer()
                   The default is 22, the assigned well known port number for SSH.
                 Options = [{Option, Value}]
                 Timeout = infinity | integer(milliseconds)
                   Negotiation  timeout,  for connection timeout use the option {connect_timeout,
                   timeout()}.

              Connects to an SSH  server.  No  channel  is  started.  This  is  done  by  calling
              ssh_connection:session_channel/[2, 4].

              Options are:

                {user_dir, string()}:
                  Sets  the  user directory i.e. the directory containing ssh configuration files
                  for the user such as known_hosts, id_rsa, id_dsa and  authorized_key.  Defaults
                  to the directory normally referred to as ~/.ssh

                {dsa_pass_phrase, string()}:
                  If  the  user dsa key is protected by a passphrase it can be supplied with this
                  option.

                {rsa_pass_phrase, string()}:
                  If the user rsa key is protected by a passphrase it can be supplied  with  this
                  option.

                {silently_accept_hosts, boolean()}:
                  When  true  hosts  are  added  to the file known_hosts without asking the user.
                  Defaults to false.

                {user_interaction, boolean()}:
                  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.

                {public_key_alg, 'ssh-rsa' | 'ssh-dss'}:
                  Sets  the preferred public key algorithm to use for user authentication. If the
                  the preferred algorithm fails for some reason, the other  algorithm  is  tried.
                  The default is to try 'ssh-rsa' first.

                {pref_public_key_algs, list()}:
                  List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available.
                  Will override {public_key_alg, 'ssh-rsa' | 'ssh-dss'}

                {connect_timeout, timeout()}:
                  Sets a timeout on the transport layer connection. Defaults to infinity.

                {user, string()}:
                  Provides a user name.  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 if the password authentication method  is
                  attempted.

                {key_cb, atom()}:
                  Module  implementing the behaviour ssh_client_key_api. Can be used to customize
                  the handling of public keys.

                {quiet_mode, atom() = boolean()}:
                  If true, the client will not print out anything on authorization.

                {fd, file_descriptor()}:
                  Allow an existing file descriptor to be used (simply passed on to the transport
                  protocol).

                {rekey_limit, integer()}:
                  Provide, in bytes, when rekeying should be initiated, defaults to one time each
                  GB and one time per hour.

                {idle_time, integer()}:
                  Sets a timeout on connection when no channels are active, default is infinity

       connection_info(ConnectionRef, [Option]) ->[{Option, Value}]

              Types:

                 Option = client_version | server_version | user | peer | sockname
                 Value = [option_value()]
                 option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()}
                 |      User::string()      |     Peer::{inet:hostname(),     {inet::ip_adress(),
                 inet::port_number()}} | Sockname::{inet::ip_adress(), inet::port_number()} ()

              Retrieves information about a connection.

       daemon(Port) ->
       daemon(Port, Options) ->
       daemon(HostAddress, Port, Options) -> {ok, ssh_daemon_ref()} | {error, atom()}

              Types:

                 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:

                {subsystems, [subsystem_spec()]:
                   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 [ssh_sftpd: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.

                {shell, {Module, Function, Args} | fun(string() = User) - > pid() |  fun(string()
                = User, ip_address() = PeerAddr) -> pid()}:
                   Defines the read-eval-print loop used when a shell is requested by the client.
                  Default is to use the erlang shell: {shell, start, []}

                {ssh_cli, {channel_callback(), channel_init_args()} | no_cli}:
                   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  shell  which  is  much  less  work  than
                  implementing  your  own  CLI  channel.  If  set  to no_cli you will disable CLI
                  channels and only subsystem channels will be allowed.

                {user_dir, String}:
                  Sets the user directory i.e. the directory containing ssh  configuration  files
                  for  the  user such as known_hosts, id_rsa, id_dsa and authorized_key. Defaults
                  to the directory normally referred to as ~/.ssh

                {system_dir, string()}:
                  Sets the system directory, containing the host key files  that  identifies  the
                  host keys for ssh. The default is /etc/ssh, note that for security reasons this
                  directory is normally only accessible by the root user.

                {auth_methods, string()}:
                  Comma separated string that determines which authentication methodes  that  the
                  server  should  support  and  in  what  order  they  will be tried. Defaults to
                  "publickey,keyboard-interactive,password"

                {user_passwords, [{string() = User, string() = Password}]}:
                  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.

                {password, string()}:
                  Provide a global password that will authenticate  any  user.  From  a  security
                  perspective this option makes the server very vulnerable.

                {pwdfun, fun(User::string(), password::string()) -> boolean()}:
                  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.

                {key_cb, atom()}:
                  Module  implementing the behaviour ssh_server_key_api. Can be used to customize
                  the handling of public keys.

                {fd, file_descriptor()}:
                  Allow an existing file-descriptor to be used (simply passed on to the transport
                  protocol).

                {failfun, fun(User::string(), PeerAddress::ip_address(), Reason::term()) -> _}:
                  Provide a fun to implement your own logging when a user fails to authenticate.

                {connectfun,   fun(User::string(),  PeerAddress::ip_address(),  Method::string())
                ->_}:
                  Provide a fun to implement your own logging when a user  authenticates  to  the
                  server.

                {disconnectfun, fun(Reason:term()) -> _}:
                  Provide  a  fun  to implement your own logging when a user disconnects from the
                  server.

       shell(Host) ->
       shell(Host, Option) ->
       shell(Host, Port, Option) -> _

              Types:

                  Host = string()
                  Port = integer()
                  Options - see ssh:connect/3

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

       start() ->
       start(Type) -> ok | {error, Reason}

              Types:

                 Type = permanent | transient | temporary
                 Reason = term()

              Utility function that starts crypto, public_key and  the  SSH  application.  Defult
              type is temporary. See also application(3erl)

       stop() -> ok

              Stops the SSH application. See also application(3erl)

       stop_daemon(DaemonRef) ->
       stop_daemon(Address, Port) -> ok

              Types:

                 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

              Types:

                 DaemonRef = ssh_daemon_ref()
                 Address = ip_address()
                 Port = integer()

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