SSHKit

SSHKit is an Elixir toolkit for performing tasks on one or more servers, built on top of Erlang’s SSH application.

Documentation for SSHKit is available online.

Usage

SSHKit is designed to enable server task automation in a structured and repeatable way, e.g. in the context of deployment tools:

hosts = ["1.eg.io", {"2.eg.io", port: 2222}]

context =
  SSHKit.context(hosts)
  |> SSHKit.path("/var/www/phx")
  |> SSHKit.user("deploy")
  |> SSHKit.group("deploy")
  |> SSHKit.umask("022")
  |> SSHKit.env(%{"NODE_ENV" => "production"})

:ok = SSHKit.upload(context, ".", recursive: true)
:ok = SSHKit.run(context, "yarn install")

The SSHKit module documentation has more guidance and examples for the DSL.

If you need more control, take a look at the SSHKit.SSH and SSHKit.SCP modules.

Installation

Just add sshkit to your list of dependencies in mix.exs:

def deps do
  [{:sshkit, "~> 0.1"}]
end

SSHKit should be automatically started unless the :applications key is set inside def application in your mix.exs. In such cases, you need to remove the :applications key in favor of :extra_applications.

Modules

SSHKit consists of three core modules:

+--------------------+
| SSHKit             |
+--------------------+
|       | SSHKit.SCP |
|       +------------+
| SSHKit.SSH         |
+--------------------+

1. SSHKit.SSH provides convenience functions for working with SSH connections and for executing commands on remote hosts.

2. SSHKit.SCP provides convenience functions for transferring files or entire directory trees to or from a remote host via SCP. It is built on top of SSHKit.SSH.

3. SSHKit provides the main API for automating tasks on remote hosts in a structured way. It uses both SSH and SCP to implement its functionality.

Additional modules, e.g. for custom client key handling, are available as separate packages:

• ssh_client_key_api: An Elixir implementation for the Erlang ssh_client_key_api behavior, to make it easier to specify SSH keys and known_hosts files independently of any particular user's home directory.

Testing

As usual, to run all tests, use:

mix test

Apart from unit tests, we also have functional tests. These check SSHKit functionality against real SSH server implementations running inside Docker containers. Therefore, you need to have Docker installed.

All functional tests are tagged as such. Hence, if you wish to skip them:

mix test --exclude functional

Hint: We've found functional tests to run significantly faster with Docker Machine compared to Docker for Mac on OS X.

Contributing

We welcome everyone to contribute to SSHKit and help us tackle existing issues!

Use the issue tracker for bug reports or feature requests. Open a pull request when you are ready to contribute.

If you are planning to contribute documentation, please check the best practices for writing documentation.

License

SSHKit source code is released under the MIT License. Check the LICENSE file for more information.