sshkit v0.3.0 SSHKit.SSH behaviour View Source

Provides convenience functions for working with SSH connections and executing commands on remote hosts.

Examples

{:ok, conn} = SSHKit.SSH.connect("eg.io", user: "me")
{:ok, output, status} = SSHKit.SSH.run(conn, "uptime")
:ok = SSHKit.SSH.close(conn)

Enum.each(output, fn
  {:stdout, data} -> IO.write(data)
  {:stderr, data} -> IO.write([IO.ANSI.red, data, IO.ANSI.reset])
end)

IO.puts("$?: #{status}")

Link to this section Summary

Functions

close(connection)

connect(host, options_or_function \\ [])

connect(host, options, function)

Similar to connect/2 but expects a function as its last argument.

run(connection, command, options \\ [])

Callbacks

close(arg1)

Closes an SSH connection.

connect(binary, arg2)

Establishes a connection to an SSH server.

run(arg1, binary, keyword)

Executes a command on the remote and aggregates incoming messages.

Link to this section Functions

close(connection)

connect(host, options_or_function \\ [])

connect(host, options, function)

Similar to connect/2 but expects a function as its last argument.

The connection is opened, given to the function as an argument and automatically closed after the function returns, regardless of any errors raised while executing the function.

Returns {:ok, function_result} in case of success, {:error, reason} otherwise.

Examples

SSH.connect("eg.io", port: 2222, user: "me", fn conn ->
  SCP.upload(conn, "list.txt")
end)

See SSHKit.SSH.Connection.open/2 for the list of available options.

run(connection, command, options \\ [])

Link to this section Callbacks

close(arg1)

close(SSHKit.SSH.Connection.t()) :: :ok

Closes an SSH connection.

Uses SSHKit.SSH.Connection.close/1 to close the connection.

Example

:ok = SSHKit.SSH.close(conn)

connect(binary, arg2)

connect(binary(), keyword() | (... -> any())) ::
  {:ok, SSHKit.SSH.Connection.t()} | {:error, any()}

Establishes a connection to an SSH server.

Uses SSHKit.SSH.Connection.open/2 to open a connection.

options_or_function can either be a list of options or a function. If it is a list, it is considered to be a list of options as described in SSHKit.SSH.Connection.open/2. If it is a function, then it is equivalent to calling connect(host, [], options_or_function).

See the documentation for connect/3 for more information on this function.

Example

{:ok, conn} = SSHKit.SSH.connect("eg.io", port: 2222, user: "me", timeout: 1000)

run(arg1, binary, keyword)

run(SSHKit.SSH.Connection.t(), binary(), keyword()) :: any()

Executes a command on the remote and aggregates incoming messages.

Using the default handler, returns {:ok, output, status} or {:error, reason}. By default, command output is captured into a list of tuples of the form {:stdout, data} or {:stderr, data}.

A custom handler function can be provided to handle channel messages.

For further details on handling incoming messages, see SSHKit.SSH.Channel.loop/4.

Options

:timeout - maximum wait time between messages, defaults to :infinity
:fun - handler function passed to SSHKit.SSH.Channel.loop/4
:acc - initial accumulator value used in the loop

Any other options will be passed on to SSHKit.SSH.Channel.open/2 when creating the channel for executing the command.

Example

{:ok, output, status} = SSHKit.SSH.run(conn, "uptime")
IO.inspect(output)