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:
~/.ssh/config. If the file does not exist yet, we will create it.
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.
If you do not yet have a SSH key pair, create a new one with:
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
Those are the default names and location of the private and the public key,
Once this is done add the key to the
ssh-add [-K] [/path/to/key]
/path/to/key can be omitted for the default path, which is
ssh-agent is described in more detail further down this page. The
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
Finally copy the public key to the remote machine you want use Salvus on with
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
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.
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:
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
should suffice in most cases to add the default key to the
Some operating systems require a bit more effort to get the
Please search the internet for appropriate solutions. A simple way to check if
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
for more information.
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
Install it with:
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
USER_NAME by more suitable names):
keyring set SERVICE_NAME USER_NAME
Then check if you can retrieve the password with:
keyring get SERVICE_NAME USER_NAME
Once this works just add the previously chosen service and user name to the
[ssh_passphrase] section in the TOML config file, which
you can access with
[ssh_passphrase] service_name = "SERVICE_NAME" username = "USER_NAME"
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.