sshex v2.2.0 SSHEx

Module to deal with SSH connections. It uses low level erlang ssh library.

:ssh.start # just in case {:ok, conn} = SSHEx.connect ip: ‘123.123.123.123’, user: ‘myuser’

Summary

Functions

Convenience function to run run/3 and get output string straight from it, like :os.cmd/1

Establish a connection with given options. Uses :ssh.connect/4 for that

Gets an open SSH connection reference (as returned by :ssh.connect/4), and a command to execute

Gets an open SSH connection reference (as returned by :ssh.connect/4), and a command to execute

Functions

cmd!(conn, cmd, opts \\ [])

Convenience function to run run/3 and get output string straight from it, like :os.cmd/1.

See run/3 for options.

Returns response only if run/3 return value matches {:ok, response, _}, or returns {stdout, stderr} if run/3 returns {:ok, stdout, stderr, _}. Raises any {:error, details} returned by run/3. Note return status from cmd is also ignored.

Ex:

      SSHEx.cmd! conn, 'mkdir -p /path/to/newdir'
      res = SSHEx.cmd! conn, 'ls /some/path'
connect(opts)

Establish a connection with given options. Uses :ssh.connect/4 for that.

Recognised options are ip (mandatory), port and negotiation_timeout. Any other option is passed to :ssh.connect/4 as is (so be careful if you use binaries and :ssh expects char lists…). See its reference for available options.

Default values exist for some options, which are:

  • port: 22
  • negotiation_timeout: 5000
  • silently_accept_hosts: true

    Returns {:ok, connection}, or {:error, reason}.

run(conn, cmd, opts \\ [])

Gets an open SSH connection reference (as returned by :ssh.connect/4), and a command to execute.

Optionally it gets a channel_timeout for the underlying SSH channel opening, and an exec_timeout for the execution itself. Both default to 5000ms.

Returns {:ok,data,status} on success. Otherwise {:error, details}.

If :separate_streams is true then the response on success looks like {:ok,stdout,stderr,status}.

Ex:

  {:ok, _, 0} = SSHEx.run conn, 'rm -fr /something/to/delete'
  {:ok, res, 0} = SSHEx.run conn, 'ls /some/path'
  {:error, reason} = SSHEx.run failing_conn, 'ls /some/path'
  {:ok, stdout, stderr, 2} = SSHEx.run conn, 'ls /nonexisting/path', separate_streams: true
stream(conn, cmd, opts \\ [])

Gets an open SSH connection reference (as returned by :ssh.connect/4), and a command to execute.

See run/3 for options.

Returns a Stream that you can use to lazily retrieve each line of output for the given command.

Each iteration of the stream will read from the underlying connection and return one of these:

  • {:stdout,row}
  • {:stderr,row}
  • {:status,status}
  • {:error,reason}

    Keep in mind that rows may not be received in order.

    Ex:

    {:ok, conn} = :ssh.connect('123.123.123.123', 22,
                  [ {:user,'myuser'}, {:silently_accept_hosts, true} ], 5000)

    str = SSHEx.stream conn, 'somecommand'

    Stream.each(str, fn(x)->
      case x do
        {:stdout,row}    -> process_stdout(row)
        {:stderr,row}    -> process_stderr(row)
        {:status,status} -> process_exit_status(status)
        {:error,reason}  -> process_error(row)
      end
    end)