SSH Configuration

All communication in Salvus with remote sites (that is for all site types except local) happens via SSH, thus a proper SSH configuration is necessary. We explain some basics in this document, with a large amount of additional information available on the web.

If this is the first time you are dealing with SSH the process may appear a bit involved. Keep in mind that it only has to be done once and is in general useful for connecting to other remote machines.

There are two files which you might have to edit with information gained from this document here:

• Salvus' site config file which can be edited by calling

Copy
salvus-cli edit-config

• The SSH config file usually located at ~/.ssh/config. If the file does not exist yet, we will create it.

Key-Based Authentication

Instead of authenticating via username and password, Salvus only supports the much safer key-based authentication method of SSH. In a nutshell, it works by storing a cryptographic key pair in your home directory split into a public key and a private key. After copying the public key to other machines, the private key is then used to prove to the remote machine that you are who you claim you are. This is very safe and also more convenient as one no longer has to enter a password when connecting via SSH.

Creating a SSH Key Pair

If you do not yet have a SSH key pair, create a new one with:

Copy
ssh-keygen -t rsa -b 4096 -C "[email protected]"

Make sure to enter a password. Otherwise security is degraded.

In case you are unsure if you already have one, check the contents of the ~/.ssh directory and watch out for id_rsa and id_rsa.pub. Those are the default names and location of the private and the public key, respectively.

Once this is done add the key to the ssh-agent with

Copy
ssh-add [-K] [/path/to/key]

/path/to/key can be omitted for the default path, which is ~/.ssh/id_rsa. The ssh-agent is described in more detail further down this page. The -K is necessary if you want to add/later retrieve the key to a FIDO authenticator which you likely want to do.

Make sure the key is part of the ssh-agent by calling

Copy
ssh-add -l

Finally copy the public key to the remote machine you want use Salvus on with

Copy
ssh-copy-id USERNAME@HOSTNAME

you will have to enter the password to the remote machine once, but afterwards you should be able to log-in to the remote machine with

Copy
ssh USERNAME@HOSTNAME

This might be all the set-up you require for using Salvus on the remote site. The rest of this document goes into more detail and explains a few edge-cases.

Encrypted SSH Keys

We strongly recommend to only use encrypted SSH keys!

When creating an SSH key pair you are asked for a passphrase. If you give one it will be used to locally encrypt the SSH keys. This adds another layer of security as the password will be required to use the SSH key. This decreases the attack surface in the case of data theft.

Salvus supports two ways of decrypting said SSH keys:

Decrypting SSH Keys using ssh-agent

This is the recommended way. ssh-agent is a helper tool that ships with most operating systems. Once a key-pair has been added, the agent can decrypt it for applications requiring it. This means that it only has to be entered once. Using

Copy
ssh-add -K

should suffice in most cases to add the default key to the ssh-agent.

Some operating systems require a bit more effort to get the ssh-agent started. Please search the internet for appropriate solutions. A simple way to check if the ssh-agent is set-up correctly is trying to log-in to a remote machine without having to enter a password.

To prevent having to add the key to the ssh-agent in every new shell it can be added to system wide authenticators. We recommend keychain on both macOS and Linux although both confusingly are different programs. Please see here and here for more information.

Decrypting SSH Keys using the keyring library

If the ssh-agent solution is for some reason not feasible for you, Salvus supports decrypting it using the keyring library. It works by storing your SSH key passphrase in whatever safe storage option your operating system provides.

Install it with:

Copy
pip install keyring

# Optional if you later get a message that you might have to install
# alternative back-ends:
pip install keyrings.alt

You now have to add the SSH passphrase to keyring by calling (replace SERVICE_NAME and USER_NAME by more suitable names):

Copy
keyring set SERVICE_NAME USER_NAME

Then check if you can retrieve the password with:

Copy
keyring get SERVICE_NAME USER_NAME

Once this works just add the previously chosen service and user name to the usually commented [ssh_passphrase] section in the TOML config file, which you can access with

Copy
salvus-cli edit-config

Copy
[ssh_passphrase]
    service_name = "SERVICE_NAME"
    username = "USER_NAME"

FAQ

How Can I Check My SSH Key Passphrase?

Entering the following command on the shell will ask you for the passphrase of your local SSH key and raise an error if it is wrong. In the case of an unencrypted key it will not ask for a password.

Copy
ssh-keygen -y