Add passphrase provider support (#257)

* Refactor ssh and role options into single options list

Author: rjanja

.credo.exs

@@ -20,7 +20,7 @@
         # You can give explicit globs or simply directories.
         # In the latter case `**/*.{ex,exs}` will be used.
         included: ["config/", "lib/", "test/"],
-        excluded: [~r"/_build/", ~r"/deps/"]
+        excluded: [~r"/_build/", ~r"/deps/", "config/deploy/"]
       },
       #
       # If you create your own checks, you must specify the source files for

config/deploy/dev.exs

@@ -1 +1 @@
-use Mix.Config
+

config/deploy/production.exs

@@ -0,0 +1,98 @@
+# Public key support
+
+Bootleg supports the use of SSH identity files (keys) for passwordless connections.
+
+Please note the difference in terms as used in this document:
+
+* `password` refers to a password-protected user account
+* `passphrase` refers to a passphrase-protected private SSH key
+
+## Private keys
+
+In many cases, private keys are not protected by a passphrase and do not need to be unlocked before use.
+This is ideal for tools like Bootleg which lack a user interface.
+
+When defining your roles and hosts, simply add an `identity` option pointing to your private SSH key.
+
+```elixir
+role :app, "example.com", identity: "~/.ssh/id_rsa"
+```
+
+The SSH private key will be used in remote builds (Git push) and for execution of remote commands.
+
+## Passphrase-protected private keys
+
+Private keys that are protected by a passphrase need to be unlocked before use. This is natively
+supported by the `ssh_client_key_api` package using Bootleg's `passphrase` or `passphrase_provider` options.
+
+However, the remote build scenario uses a Git push, which as an external process **does not** work seamlessly
+with the aforementioned Bootleg options. See "[Remote builds](#remote-builds)" below for solutions.
+
+### Options for protected private keys
+
+#### `passphrase`
+
+When configuring your role, set the `passphrase` option to the string that unlocks your private key.
+
+#### `passphrase_provider`
+
+Instead of setting a `passphrase`, you may set `passphrase_provider` to something that returns the string to unlock your private key. When using a provider, the returned value is then set as the `passphrase` option at time of `SSH.init/3`.
+
+##### Anonymous function
+
+```elixir
+role(:app, "example.com", identity: "protected_id_rsa", passphrase_provider: fn -> "foobar" end)
+```
+
+##### Module and function reference
+
+```elixir
+defmodule Test.Foo do
+  def bar do
+    "foobar"
+  end
+end
+role(:app, "example.com", identity: "protected_id_rsa", passphrase_provider: {Test.Foo, :bar})
+```
+
+##### System command and arguments
+
+```elixir
+role(:app, "example.com", identity: "protected_id_rsa", passphrase_provider: {"/bin/echo", ["foobar"]})
+```
+
+### Local builds
+
+When your build server is the same machine you're running Bootleg on, you may define the passphrase alongside the identity.
+
+```elixir
+role :app, "example.com", identity: "~/.ssh/protected_id_rsa", passphrase: "secretsauce"
+```
+
+### Remote builds
+
+When your build server is another machine, the build process will attempt to do a Git push to it.
+This requires that you unlock your private key in one of two ways:
+
+#### Using the `insecure_agent` Bootleg role option (preferred)
+
+To use this option, set a passphrase options above, but also set `insecure_agent` on the role.
+
+During the build process, the passphrase will be temporarily written to the filesystem in order
+to unlock the key using `ssh-add`. This file is then removed immediately after the Git push operation.
+
+```elixir
+role :build, "example.com", identity: "~/.ssh/protected_id_rsa", passphrase: "secretsauce", insecure_agent: true
+```
+
+#### Using `ssh-agent` (external to Bootleg)
+
+With ssh-agent, the Git push command will succeed but a passphrase is still needed for Bootleg to use your private key during execution of remote commands.
+
+```elixir
+role :build, "example.com", identity: "~/.ssh/protected_id_rsa", passphrase: "secretsauce"
+```
+
+Here you would run `$ ssh-add ~/.ssh/protected_id_rsa` before invoking Bootleg to provide the passphrase that unlocks your private key. After specifying the correct passphrase your key is added to the SSH Agent and Git push operations will succeed as expected.
+
+Then run Bootleg as you would.

config/deploy/test.exs

@@ -42,7 +42,7 @@ defmodule Bootleg.DSL do
 
   `options` is an optional `Keyword` used to provide configuration details about a specific host
   (or collection of hosts). Certain options are passed to SSH directly (see
-  `Bootleg.SSH.supported_options/0`), others are used internally (`user` for example, is used
+  `Bootleg.SSH.ssh_options/0`), others are used internally (`user` for example, is used
   by both SSH and Git), and unknown options are simply stored. In the future `remote/1,2` will
   allow for host filtering based on role options. Some Bootleg extensions may also add support
   for additional options.

docs/public_keys.md

@@ -3,10 +3,10 @@ defmodule Bootleg.Host do
   @enforce_keys [:host, :options]
   defstruct [:host, :options]
 
-  def init(host, ssh_options, role_options) do
+  def init(host, options) do
     %__MODULE__{
-      host: SSHKit.host(host, ssh_options),
-      options: role_options
+      host: SSHKit.host(host),
+      options: options
     }
   end
 
@@ -22,20 +22,12 @@ defmodule Bootleg.Host do
     put_in(host, [Access.key!(:options), option], value)
   end
 
-  def ssh_option(%__MODULE__{} = host, option) when is_atom(option) do
-    get_in(host, [Access.key!(:host), Access.key!(:options), option])
-  end
-
-  def ssh_option(%__MODULE__{} = host, option, value) when is_atom(option) do
-    put_in(host, [Access.key!(:host), Access.key!(:options), option], value)
-  end
-
   def combine_uniq(hosts) do
     do_combine_uniq(hosts, %{}, &host_id/1, [])
   end
 
   defp host_id(host) do
-    {host_name(host), ssh_option(host, :port)}
+    {host_name(host), option(host, :port)}
   end
 
   defp do_combine_uniq([h | t], set, fun, acc) do
@@ -60,11 +52,9 @@ defmodule Bootleg.Host do
   end
 
   defp combine_host_options(host1, host2) do
-    ssh_options = Keyword.merge(host1.host.options, host2.host.options)
     host_options = Keyword.merge(host1.options, host2.options)
 
     host1
-    |> put_in([Access.key!(:host), Access.key!(:options)], ssh_options)
     |> put_in([Access.key!(:options)], host_options)
   end
 end

lib/bootleg/dsl.ex

@@ -3,44 +3,25 @@ defmodule Bootleg.Role do
   @enforce_keys [:name, :hosts, :user]
   defstruct [:name, :hosts, :user, options: []]
 
-  alias Bootleg.{Host, SSH}
+  alias Bootleg.Host
 
   def combine_hosts(%Bootleg.Role{} = role, hosts) do
     %Bootleg.Role{role | hosts: Host.combine_uniq(role.hosts ++ hosts)}
   end
 
   def define(name, hosts, options \\ []) do
-    # user is in the role options for scm
-
-    user = Keyword.get(options, :user, System.get_env("USER"))
-
-    ssh_options =
-      Enum.filter(options, &(Enum.member?(SSH.supported_options(), elem(&1, 0)) == true))
-
-    # identity needs to be present in both options lists
-    role_options =
-      (options -- ssh_options)
-      |> Keyword.put(:user, user)
-      |> Keyword.put(:identity, ssh_options[:identity])
-      |> Keyword.get_and_update(:identity, fn val ->
-        if val || Keyword.has_key?(ssh_options, :identity) do
-          {val, val || ssh_options[:identity]}
-        else
-          :pop
-        end
-      end)
-      |> elem(1)
+    opts = Keyword.merge(default_options(), options)
 
     hosts =
       hosts
       |> List.wrap()
-      |> Enum.map(&Host.init(&1, ssh_options, role_options))
+      |> Enum.map(&Host.init(&1, opts))
 
     new_role = %Bootleg.Role{
       name: name,
-      user: user,
+      user: opts[:user],
       hosts: [],
-      options: role_options
+      options: opts
     }
 
     role =
@@ -56,6 +37,10 @@ defmodule Bootleg.Role do
     )
   end
 
+  def default_options do
+    [user: System.get_env("USER")]
+  end
+
   @doc false
   @spec split_roles_and_filters(atom | keyword) :: {[atom], keyword}
   def split_roles_and_filters(role) do