AiiDA communicates with remote computers via the SSH protocol. There are two ways of setting up an SSH connection for AiiDA:
Using a passwordless SSH key (easier, less safe) Using a password-protected SSH key through ssh-agent (one more step, safer)
Using a passwordless SSH key (easier, less safe)
Using a password-protected SSH key through ssh-agent (one more step, safer)
ssh-agent
There are numerous tutorials on the web, see e.g. here. Very briefly, first create a new private/public keypair (aiida/aiida.pub), leaving passphrase emtpy:
aiida
aiida.pub
$ ssh-keygen -t rsa -b 4096 -f ~/.ssh/aiida
Copy the public key to the remote machine, normally this will add the public key to the rmote machine’s ~/.ssh/authorized_keys:
~/.ssh/authorized_keys
$ ssh-copy-id -i ~/.ssh/aiida YOURUSERNAME@YOURCLUSTERADDRESS
Add the following lines to your ~/.ssh/config file (or create it, if it does not exist):
~/.ssh/config
Host YOURCLUSTERADDRESS User YOURUSERNAME IdentityFile ~/.ssh/aiida
Note
If your cluster needs you to connect to another computer PROXY first, you can use the proxy_command feature of ssh, see Connecting to a remote computer via a proxy server.
proxy_command
You should now be able to access the remote computer (without the need to type a password) via:
$ ssh YOURCLUSTERADDRESS # this connection is used to copy files $ sftp YOURCLUSTERADDRESS
Connection closed failures
If the ssh command works, but the sftp command prints Connection closed, there may be a line in the ~/.bashrc file on the cluster that either produces text output or an error. Remove/comment lines from this file until no output or error is produced: this should make sftp work again.
ssh
sftp
Connection closed
~/.bashrc
Finally, if you are planning to use a batch scheduler on the remote computer, try also:
$ ssh YOURCLUSTERADDRESS QUEUE_VISUALIZATION_COMMAND
replacing QUEUE_VISUALIZATION_COMMAND by squeue (SLURM), qstat (PBSpro) or the equivalent command of your scheduler and check that it prints a list of the job queue without errors.
QUEUE_VISUALIZATION_COMMAND
squeue
qstat
Scheduler errors?
If the previous command errors with command not found, while the same QUEUE_VISUALIZATION_COMMAND works fine after you’ve logged in via SSH, it may be that a guard in the .bashrc file on the cluster prevents necessary modules from being loaded.
command not found
.bashrc
Look for lines like:
[ -z "$PS1" ] && return
or:
case $- in *i*) ;; *) return;; esac
which will prevent any instructions that follow from being executed.
You can either move relevant instructions before these lines or delete the guards entirely. If you are wondering whether the PATH environment variable is set correctly, you can check its value using:
PATH
$ ssh YOURCLUSTERADDRESS 'echo $PATH'
Tools like ssh-agent (available on most Linux distros and MacOS) allow you to enter the passphrase of a protected key once and provide access to the decrypted key for as long as the agent is running. This allows you to use a passphrase-protected key (required by some HPC centres), while making the decrypted key available to AiiDA for automatic SSH operations.
Start by following the instructions above for Using a passwordless SSH key, the only difference being that you enter a passphrase when creating the key (and when logging in to the remote computer).
Now provide the passphrase for your private key to the agent:
ssh-add ~/.ssh/aiida
The private key and the relative passphrase are now recorded in an instance of the agent.
The passphase is stored in the agent only until the next reboot. If you shut down or restart the AiiDA machine, before starting the AiiDA deamon remember to run the ssh-add command again.
ssh-add
On most modern Linux installations, the ssh-agent starts automatically at login (e.g. Ubuntu 16.04 and later or MacOS 10.5 and later). If you received an error Could not open a connection to your authentication agent, you will need to start the agent manually instead.
Could not open a connection to your authentication agent
Check whether you can start an ssh-agent in your current shell:
eval `ssh-agent`
In order to reuse the same agent instance everywhere (including the AiiDA daemon), the environment variables of ssh-agent need to be reused by all shells. Download the script load-singlesshagent.sh and place it e.g. in ~/bin. Then add the following lines to your ~/.bashrc file:
load-singlesshagent.sh
~/bin
if [ -f ~/bin/load-singlesshagent.sh ]; then . ~/bin/load-singlesshagent.sh fi
To check that it works:
Open a new shell (~/.bashrc file is sourced).
Run ssh-add.
Close the shell.
Open a new shell and try logging in to the remote computer.
Try logging in to the remote computer; it should no longer require a passphrase.
The key and its corresponding passphrase are now stored by the agent until it is stopped. After a reboot, remember to run ssh-add ~/.ssh/aiida again before starting the AiiDA daemon.
On OSX Sierra and later, the native ssh-add client allows passphrases to be stored persistently in the OSX keychain. Store the passphrase in the keychain using the OSX-specific -k argument:
-k
ssh-add -k ~/.ssh/aiida
To instruct ssh to look in the OSX keychain for key passphrases, add the following lines to ~/.ssh/config:
Host * UseKeychain yes
When configuring the computer in AiiDA, simply make sure that Allow ssh agent is set to true (default).
Allow ssh agent
true
Some compute clusters require you to connect to an intermediate server PROXY, from which you can then connect to the cluster TARGET on which you run your calculations. This section explains how to use the proxy_command feature of ssh in order to make this jump automatically.
Tip
This method can also be used to automatically tunnel into virtual private networks, if you have an account on a proxy/jumphost server with access to the network.
The netcat tool needs to be present on the PROXY server (executable may be named netcat or nc). netcat simply takes the standard input and redirects it to a given TCP port.
netcat
nc
If neither netcat or nc are available, you will need to install it on your own. You can download a netcat distribution, unzip the downloaded package, cd into the folder and execute something like:
cd
$ ./configure --prefix=. $ make $ make install
This usually creates a subfolder bin, containing the netcat and nc executables. Write down the full path to nc which we will need later.
bin
Edit the ~/.ssh/config file on the computer on which you installed AiiDA (or create it if missing) and add the following lines:
Host SHORTNAME_TARGET Hostname FULLHOSTNAME_TARGET User USER_TARGET IdentityFile ~/.ssh/aiida ProxyCommand ssh USER_PROXY@FULLHOSTNAME_PROXY ABSPATH_NETCAT %h %p
replacing the ..._TARGET and ..._PROXY variables with the host/user names of the respective servers, and replacing ABSPATH_NETCAT with the result of which netcat (or which nc).
..._TARGET
..._PROXY
ABSPATH_NETCAT
which netcat
which nc
If desired/necessary for your netcat implementation, hide warnings and errors that may occur during the proxying/tunneling by redirecting stdout and stderr, e.g. by appending 2> /dev/null to the ProxyCommand.
2> /dev/null
ProxyCommand
This should allow you to directly connect to the TARGET server using
$ ssh SHORTNAME_TARGET
For a passwordless connection, you need to follow the instructions Using a passwordless SSH key twice: once for the connection from your computer to the PROXY server, and once for the connection from the PROXY server to the TARGET server.
Warning
There are occasionally netcat implementations, which keep running after you close your SSH connection, resulting in a growing number of open SSH connections between the PROXY server and the TARGET server. If you suspect an issue, it may be worth connecting to the PROXY server and checking how many netcat processes are running, e.g. via:
$ ps -aux | grep netcat
When configuring the computer in AiiDA, AiiDA will automatically parse the required information from your ~/.ssh/config file.
If, for any reason, you need to specify the proxy_command option of verdi computer configure ssh manually, please note the following:
verdi computer configure ssh
Don’t use placeholders %h and %p (AiiDA replaces them only when parsing from the ~/.ssh/config file) but provide the actual hostname and port. Don’t include stdout/stderr redirection (AiiDA strips it automatically, but only when parsing from the ~/.ssh/config file).
Don’t use placeholders %h and %p (AiiDA replaces them only when parsing from the ~/.ssh/config file) but provide the actual hostname and port.
%h
%p
Don’t include stdout/stderr redirection (AiiDA strips it automatically, but only when parsing from the ~/.ssh/config file).
If the remote machine requires authentication through a Kerberos token (that you need to obtain before using ssh), you typically need to
install libffi (sudo apt-get install libffi-dev under Ubuntu) install the ssh_kerberos extra during the installation of aiida-core (see Setup).
install libffi (sudo apt-get install libffi-dev under Ubuntu)
libffi
sudo apt-get install libffi-dev
install the ssh_kerberos extra during the installation of aiida-core (see Setup).
ssh_kerberos
If you provide all necessary GSSAPI options in your ~/.ssh/config file, verdi computer configure should already pick up the appropriate values for all the gss-related options.
GSSAPI
verdi computer configure