Problem with these instructions? Please send a CFDDFC Support Query.

Command line

Once an instance is launched, the user can access it securely using SSH (Secure Shell). The standard access is remote login from a command line using the OpenSSH client, known as “ssh”. On Linux and macOS systems, ssh is available in the command line “shell” or “terminal”.

MS Windows 10 provides ssh in the following environments. On the native cmd and powershell, ssh may need to be activated.

  • A Linux terminal within the Windows Subsystem for Linux (recommended).
  • cmd command line, which is opened by typing Windows key+R to open the “Run” box, entering “cmd” and then clicking “OK” (or using one of 9 other different ways).
  • Powershell, opened by typing Windows key+R to open the “Run” box, entering “powershell” and then clicking “OK” (or using one of 8 other different ways).

Older versions of MS Windows rely on a separate application PuTTy to provide SSH access, but since older versions are unsupported, we will not document PuTTy here.

SSH authentication

Instances are accessed with SSH with public key authentication using a key pair. A key pair is two keys, stored as files, that are related to one another. One key is public, the other private. Anyone with the public key can encrypt data which can only be read by someone with the private key. As well as providing encryption, possession of the private key can also be used as proof of identity, i.e. authentication.

Each instance is associated with a key pair that controls access to it, selected during the launch process. The public key remains at AWS and is attached to the instance. The private key must be stored by the user to authenticate their access to the instance. The key pair uses the RSA (Rivest–Shamir–Adleman) encryption in the general PEM (Privacy-Enhanced Email) format, so files typically carry a .pem extension, e.g. awskey.pem. Since the private key file provides proof of identity, the ssh client imposes strict rules on file permissions to the private keys it uses. 

Key file permissions

Linux and macOS systems

Linux and macOS systems use UNIX-inspired file systems. SSH key files are generally stored in a “.ssh” directory in the user’s home directory. The user can create the directory if it does not exist by the command (if it exists, it will return a message to confirm):

mkdir ~/.ssh

It is recommended that only the user has permission to access that directory, which can be set by the command:

chmod 700 ~/.ssh

The file permission must be set to read for the user only. For a key pair file named awskey.pem file in a .ssh directory, use the command:

chmod 400 ~/.ssh/awskey.pem
MS Windows systems

Windows 10 can follow the same instructions as above when using WSL (see above). On the Linux subsystem, follow the “mkdir ~/.ssh” and “chmod 700 ~/.ssh” commands to configure the ~/.ssh directory, then copy the key file into it by the command (example uses the file location example above):

cp /mnt/C:/Users/john/azkey.pem ~/.ssh/

Otherwise, ssh can be run from the cmd Command Line. The key file is then stored on the Windows NTFS (New Technology File System) which has more complex access control lists (ACLs) and its Active Directory service. The permissions of the key file must be user-only which can be checked using the Windows file browser. They can be set using icacls in cmd as follows: for user name “john” with a key file azkey.pem stored in the home directory C:/Users/john on the C: drive, enter the commands, in order:

icacls C:/Users/john/awskey.pem /inheritance:r /deny "*S-1-1-0:f"
icacls C:/Users/john/awskey.pem /inheritance:r /grant:r john:f

Remember to replace the user name john and the path and key file name awskey.pem to suit your circumstances. When using ssh on the Windows Subsystem for Linux, it is logical to copy the key file from the Windows filing system to a ~/.ssh directory on the Linux file system. From the terminal within the Linux subsystem, follow the “mkdir ~/.ssh” and “chmod 700 ~/.ssh” commands above to configure the ~/.ssh directory, then copy the key file into it bythe command (using the file location example above):

cp /mnt/C:/Users/john/awskey.pem ~/.ssh/

Terminal login with SSH

To login using ssh you will need:

  • username ubuntu;
  • IP address or hostname of the instance, e.g. 123.45.67.89;
  • path and file name of the key file, e.g. ~/.ssh/awskey.pem on Linux/macOS, or C:\Users\john\awskey.pem on Windows 10.

The login command has the general form:

ssh -i <path_and_key_file> <user>@<ip_host>

For example, on Linux and macOS, or in Windows using the subsystem for Linux using example IP address and key file above, the command is:

ssh -i ~/.ssh/awskey.pem ubuntu@123.45.67.89

The user should see the login screen for CFD Direct From the Cloud, followed by the command prompt. To logout, type “exit”.

In a Linux/UNIX shell, one option to simplify the command is to define shell variables for the key file and IP as shell variables, e.g. key and ip, respectively by the following:

key=~/.ssh/awskey.pem
ip=123.45.67.89

The login command can then be:

ssh -i "$key" ubuntu@$ip

Using SSH agent

The user can avoid supplying the key file in the login command by using the ssh-agent — OpenSSH’s authentication agent. The agent holds private keys which can be automatically used for authentication. It is available for all platforms but documented here only for Linux/UNIX shell.  Alternatively there are instructions for SSH agent from Windows 10 command line.

The user can add their key to the agent by the command:

ssh-add ~/.ssh/awskey.pem

If this command returns a message “unable to start ssh-agent service”, Linux/UNIX shell users should activate the ssh-agent server by typing:

eval $(ssh-agent)

Once the key is added, users can login without providing the key in the command by:

ssh ubuntu@$ip

The stored keys can be listed by the command:

ssh-add -l

Authentications can fail if the number of keys exceeds the limit on authentication attempts set by the SSH server on the instance (typically 6). When this occurs, it is advisable to empty the agent of stored keys by typing:

ssh-add -D

Further Information: connect using Windows Subsystem for Linux.

Next Step → Using OpenFOAM on an Instance