Specs

close(conn() | term()) :: :ok | {:error, String.t()}

closes the ssh connection.

Typically you will pass the connection reference to this function. If your connection is contained to its own transient task process, you may not need to call this function as the ssh client library will detect that the process has ended and clean up after you.

In some cases, you may want to be able to close a connection out-of-band. In this case, you may label your connection and use the label to perform the close operation. See labels

Specs

connect(remote(), keyword()) :: connect_result()

initiates an ssh connection with a remote server.

options:

• :use_ssh_config see SSH.Config, defaults to false.
• :global_config_path see SSH.Config.
• :user_config_path see SSH.Config.
• :user username to log in as.
• :port port to use to ssh, defaults to 22.
• :label see labels
• :link if true, links the connection with the calling process. Note the calling process will not die if the SSH connection is closed using close/1.

and other SSH options. Some conversions between ssh options and SSH.connect options:

also consult documentation on client options in the erlang docs

labels:

You can label your ssh connection to provide a side-channel for correctly closing the connection pid. This is most useful in the context of with/1 blocks. As an example, the following code works:

def run_ssh_tasks do
  with {:ok, conn} <- SSH.connect("some_host", label: :this_task),
       {:ok, _result1, 0} <- SSH.run(conn, "some_command"),
       {:ok, result2, 0} <- SSH.run(conn, "some other command") do
    {:ok, result1}
  end
after
  SSH.close(:this_task)
end

Some important points:

• If you are wrangling multiple SSH sessions, please use unique connection labels.
• The ssh connection label is stored in the process dictionary, so the label will not be valid across process boundaries.
• If the ssh connection failed in the first place, the tagged close will return an error tuple. In the example, this will be silent.

Specs

connect!(remote(), keyword()) :: conn() | no_return()

like connect/2 but raises with a ConnectionError instead of emitting an error tuple.

Specs

fetch(conn(), Path.t(), keyword()) :: fetch_result()

retrieves a binary file from the remote host.

Under the hood, this uses the scp protocol to transfer files.

The SCP protocol is as follows:

• execute scp remotely in the undocumented -f <source> mode
• send a single zero byte to initiate the conversation
• wait for a control string "C0<perms> <size> <filename>"
• send a single zero byte
• wait for the binary data + terminating zero
• send a single zero byte

The perms term should be in octal, and the filename should be rootless.

Example:

SSH.fetch(conn, "path/to/desired/file")

Specs

fetch!(conn(), Path.t(), keyword()) :: binary() | no_return()

like fetch/3 except raises instead of emitting an error tuple.

Specs

run(conn(), String.t(), keyword()) :: run_result()

runs a command on the remote host. Typically returns {:ok, result, retval} where retval is the unix return value from the range 0..255.

the result value is governed by the passed options, but defaults to a string. of the run value.

Options

• {iostream, redirect}: iostream may be either :stdout or :stderr. redirect may be one of the following:
  • :stream sends the data to the stream.
  • :stdout sends the data to the group_leader stdout.
  • :stderr sends the data to the standard error io stream.
  • :silent deletes all of the data.
  • :raw sends the data to the stream tagged with source information as either {:stdout, data} or {:stderr, data}, as appropriate.
  • {:file, path} sends the data to a new or existing file at the provided path.
  • fun/1 processes the data via the function, with the output flat-mapped into the stream. this means that the results of fun/1 should be lists, with an empty list sending nothing into the stream.
  • fun/2 is like fun/1 except the stream struct is passed as the second parameter. The output of fun/2 should take the shape {flat_map_results, modified_stream}. You may use the :data field of the stream struct to store arbitrary data; and a value of nil indicates that it has been unused.
• {:tty, true | <options>}: register the connection as a tty connection. Note this changes the default behavior to send the output to group leader stdout instead of to the result, but this is overridable with the iostream redirect above. For options, see :ssh_client_connection.ptty_alloc/4
• {:env, <env list>}: a list of environment variables to be passed. NB: typically environment variables are filtered by the host environment.
• {:dir, path}: changes directory to path and then runs the command
• {:as, :binary} (default): outputs result as a binary
• {:as, :iolist}: outputs result as an iolist
• {:as, :tuple}: result takes the shape of the tuple {stdout_binary, stderr_binary} note that this mode will override any other redirection selected.

Example:

SSH.run(conn, "hostname")  # ==> {:ok, "hostname_of_remote\n", 0}

SSH.run(conn, "some_program", stderr: :silent) # ==> similar to running "some_program 2>/dev/null"

SSH.run(conn, "some_program", stderr: :stream) # ==> similar to running "some_program 2>&1"

SSH.run(conn, "some_program", stdout: :silent, stderr: :stream) # ==> only capture standard error

Specs

run!(conn(), String.t(), keyword()) :: run_content() | no_return()

like run/3 except raises on errors instead of returning an error tuple.

Note that by default this raises in the case that the SSH connection fails AND in the case that the remote command returns non-zero.

Specs

send(conn(), iodata() | filestreams(), Path.t(), keyword()) :: send_result()

sends binary content to the remote host.

Under the hood, this uses the scp protocol to transfer files.

Protocol is as follows:

• execute scp remotely in the undocumented -t <destination> mode
• send a control string "C0<perms> <size> <filename>"
• wait for single zero byte
• send the binary data + terminating zero
• wait for single zero byte
• send EOF

The perms term should be in octal, and the filename should be rootless.

options:

• :permissions - sets unix-style permissions on the file. Defaults to 0o644

Example:

SSH.send(conn, "foo", "path/to/desired/file")

Specs

send!(conn(), iodata(), Path.t(), keyword()) :: :ok | no_return()

like send/4, except raises on errors, instead of returning an error tuple.

Specs

stream(conn(), String.t(), keyword()) ::
  {:ok, SSH.Stream.t()} | {:error, String.t()}

creates an SSH stream struct as an ok tuple or error tuple.

Options

• {iostream, redirect}: iostream may be either :stdout or :stderr. redirect may be one of the following:
  • :stream sends the data to the stream.
  • :stdout sends the data to the group_leader stdout.
  • :stderr sends the data to the standard error io stream.
  • :silent deletes all of the data.
  • :raw sends the data to the stream tagged with source information as either {:stdout, data} or {:stderr, data}, as appropriate.
  • {:file, path} sends the data to a new or existing file at the provided path.
  • fun/1 processes the data via the function, with the output flat-mapped into the stream. this means that the results of fun/1 should be lists, with an empty list sending nothing into the stream.
  • fun/2 is like fun/1 except the stream struct is passed as the second parameter. The output of fun/2 should take the shape {flat_map_results, modified_stream}. You may use the :data field of the stream struct to store arbitrary data; and a value of nil indicates that it has been unused.
• {:stream_control_messages, boolean}: should the stream control messages :eof, or {:retval, integer} be sent to the stream?
• module: {mod, init}, The stream is operated using an module with behaviour SSH.ModuleApi
• data_timeout: timeout, how long to wait between packets till we send a timeout event.

Specs

stream!(conn(), String.t(), keyword()) :: SSH.Stream.t() | no_return()

like stream/2, except raises on an error instead of an error tuple.