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 accountpassphrase
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.
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” 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
role(:app, "example.com", identity: "protected_id_rsa", passphrase_provider: fn -> "foobar" end)
Module and function reference
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
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.
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.
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.
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.