System: SSH Agent

The ssh-agent service allows adding multiple keys (including the ones protected with a passphrase) to a single pool of ssh keys, which can be shared across multiple projects.

The default ssh keys (~/.ssh/id_rsa, ~/.ssh/id_dsa, ~/.ssh/id_ecdsa) are loaded into the agent automatically.
On macOS and Windows this happens when the Docksal VM is (re)started, on Linux - whenever fin project start is used.

Project Setup

To start using the ssh-agent service, add the following configuration option under the volumes section of the cli service in the project’s .docksal/docksal.yml file:

cli:
  ...
  volumes:
  ...
  # Shared ssh-agent socket
  - docksal_ssh_agent:/.ssh-agent:ro
  ...

Reset the cli container fin project reset cli.

Command Line Reference

See fin help ssh-key for more information and usage guidelines.

$ fin help ssh-key
Manage SSH keys loaded into Docksal

  Private SSH keys loaded into the secure docksal-ssh-agent service are accessible to all project containers.	
  This allows containers to connect to the external SSH servers that require SSH keys	
  without a need to copy over the key into the container every time.	
  Default keys id_rsa/id_dsa/id_ecdsa are loaded automatically on every project start.	

Usage: fin ssh-key <command> [params]

Commands:
  add [key-name]           	Add a private SSH key from $HOME/.ssh by file name
                           	Adds all default keys (id_rsa/id_dsa/id_ecdsa) if no file name is given.
  ls                       	List SSH keys loaded in the docksal-ssh-agent
  rm                       	Remove all keys from the docksal-ssh-agent
  new [key-name]           	Generate a new SSH key pair

Examples:
  fin ssh-key add          	Loads all SSH keys with default names: id_rsa/id_dsa/id_ecdsa from $HOME/.ssh/
  fin ssh-key server_rsa   	Loads the key stored in $HOME/.ssh/server_id_rsa into the agent
  fin ssh-key new server2_rsa	Generates a new SSH key pair in ~/.ssh/server2_id_rsa

Automatically Add Keys

Adding SSH keys automatically whenever Docksal project is started can be done by defining special variable(s) within the $HOME/.docksal/docksal.env file. All variables should be prefixed with SECRET_SSH_KEY_ plus the identifier of the SSH key. After that has been done, restart your project with fin project restart, and the keys will be added.

For example, assuming you have a private SSH key $HOME/.ssh/acquia_key, you would define a variable:

SECRET_SSH_KEY_ACQUIA='acquia_key'

When creating the variable use the file name within $HOME/.ssh/ directory as the variable value. NOTE: the private key should be referenced, not the public one.

Manually Add Keys

To add a key manually, run fin ssh-key add <key_filename> and it will be manually loaded. NOTE: this key will only be be available to the containers until the next docksal-ssh-agent restart.