SSH Credentials

The MLeRP platform does not use passwords in any way. This means that if you want to connect to the cluster in any way other than the Strudel2, such as through your favourite terminal application or IDE, you will need some SSH credentials.

This YouTube video does a good job of explaining why ssh keys are more secure than passwords, even if it is designed for an AWS user.

Strudel2 Integration

Rather than requiring users to create and manage SSH keys themselves, users are able to download their SSH credentials right from within Strudel2. The ‘Download SSH Credentials’ button can be found at the bottom of your ‘Account Info’ page, below the dashboards.

This will give you an SSH key as well as a corresponding SSH certificate. These credentials will be valid for a period before expiring. When they expire, requiring you to redownload your credentials periodically. Only the path to the key needs to be specified in the SSH command, but the corresponding certificate will need to be placed in the same directory so that the tool can find.

You will need to rename the files you download to remove any extra numbers that may have been added if you’ve downloaded the files more than once, for example: strudel2_ssh_key (1) -> strudel2_ssh_key.

You will also need to set the permissions of the key and certificate to 600 with chmod before connecting.

chmod 600 /path/to/strudel2_ssh_key*

Note that there is a known bug where this button breaks if Strudel2 has been refreshed. If this happens reopen the app in a new tab or log out and back in before redownloading your credentials.

SSH config

To use these credentials, you will need to initialise your SSH config so knows to use them. Add these entries to your ~/.ssh/config file:

Host <User>_MLeRP_monash
    HostName monash-mlerp-login0.mlerp.cloud.edu.au
    User <User>
    IdentityFile </path/to/ssh/key>

Host <User>_MLeRP_monash_job
    HostName VSCode
    User <User>
    IdentityFile </path/to/ssh/key>
    ProxyCommand <ProxyCommand>

The ProxyCommand you should use will be different between Windows and Mac/Linux:

# Linux and Mac
ProxyCommand ssh -i </path/to/ssh/key> <username>@monash-mlerp-login0.mlerp.cloud.edu.au /apps/strudel2/strudel_apps/sshnc.sh

# Windows
ProxyCommand ssh.exe -i </path/to/ssh/key> <username>@monash-mlerp-login0.mlerp.cloud.edu.au /apps/strudel2/strudel_apps/sshnc.sh

This will give you two configurations:

<User>_MLeRP_Monash
For connecting directly to the login node for simple administrative tasks
<User>_MLeRP_Monash_job
For connecting to a ‘Jupyter Lab’ or ‘Terminal’ job that you launch from Strudel2. If it can’t find one, it will create a 12 hour Panther QoS job with 4 VCPUs and 16 GB RAM.

ssh <User>_MLeRP_Monash
ssh <User>_MLeRP_Monash_job

SSOSSH

SSOSSH is a command line tool that brings single sign on to MLeRP. You can use it as an alternative to downloading your SSH credentials from Strudel2 if you are familiar with using a terminal.

Just like the Strudel2 method, the tool generates an SSH Certificate. This is more secure than a permanent key since the certificate will only be valid for 24 hours, requiring you to go through your organisation’s single sign on again to renew the certificate.

1. Setting up the configuration file

SSOSSH uses a configuration file in your user’s home directory named ~/.authservers.json. This file should be a list of configs for the clusters you wish to connect to.

[
    {
        "authorise": "https://sshauthz.cloud.cvl.org.au/pysshauthz/oauth2/oauth/authorize/choose",
        "base": "https://sshauthz.cloud.cvl.org.au/pysshauthz/oauth2/",
        "cafingerprint": "SHA256:ywDDZvIbx7B2AxujVIsW433fd4Sl1aZ0wl4FFsCRX/E",
        "client_id": "Q96kt2Vtw6S78dpORktM81DH",
        "desc": "<div>MLeRP</div>",
        "icon": null,
        "login": "monash-mlerp-login0.mlerp.cloud.edu.au",
        "logout": "https://sshauthz.cloud.cvl.org.au/pysshauthz/oauth2/logout",
        "name": "MLeRP_Monash",
        "proxy": "/apps/strudel2/strudel_apps/sshnc.sh",
        "scope": "user:email",
        "sign": "https://sshauthz.cloud.cvl.org.au/pysshauthz/sign/mlerp_users/api/v1/sign_key"
    }
]

2. Installing SSOSSH

You can pip install SSOSSH with:

pip install git+https://github.com/HecticHPCSolutions/ssossh

or if you want to test an experimental feature:

pip install git+https://github.com/HecticHPCSolutions/ssossh@branch-name

After installation you should be able to run ssossh in your favourite terminal to run the program. By default it will create the SSH keys and certificates in your .ssh folder, but you can optionally change this path or have it add direct to your SSH Agent which you may find to be neater.

3. Generating your SSH Config

Before connecting to the cluster you will need to initialise your SSH config. We recommend using the --setssh flag the first time you use SSOSSH to set up some default SSH configurations to connect to the login node and start up a Jupyter session. This will generate the config described in the section above.

Open up your ssh config file to confirm everything is as it should be. If you have accidentally run this command multiple times or with an improperly configured ~/.authservers.json file there may be duplicate or malformed entries that you will need to correct.

4. Connecting to the cluster

Now, each time you want to connect to the cluster you can simply rerun the ssossh program to refresh your certificates then use your SSH or VS Code remote session as per normal.

ssossh
ssh <User>_MLeRP_Monash
ssh <User>_MLeRP_Monash_job

You can read more about SSOSSH at its GitHub Repo.

Enabling SSH on Windows

If you’re working in Windows, you will need OpenSSH to be installed and enabled:

Check OpenSSH installation:
- Navigate to Setting > System > Optional Features
- Select Optional Features.
- Check if OpenSSH Client is in the list. If it is, go to step 2.
- If it isn’t, select the Add a feature button at the top of the page, then select OpenSSH Client, and Install. This will install the OpenSSH Client.
Start the OpenSSH Client:
- Use the Windows search bar to search for and open Services.
- Scroll through the list to find OpenSSH Authentication Agent
- Double click OpenSSH Authentication Agent. Change the Startup type to Automatic and select OK.
- Double click on OpenSSH Authentication Agent again and select Start.

The OpenSSH Agent will now start automatically in future.

Adding your key to the SSH Agent

Rather than specifying the key path in your config, you could opt to load the SSH key into your agent. This is useful if you’ve added an SSH key to MLeRP manually with a password attached to it. This way you will only be prompted for the password once per reboot. You can do this with:

ssh-add </path/to/ssh/key>

If you do, then your config will look and ProxyCommand will look like this:

Host <User>_MLeRP_monash
    HostName monash-mlerp-login0.mlerp.cloud.edu.au
    User <User>

Host <User>_MLeRP_monash_job
    HostName VSCode
    User <User>
    ProxyCommand <ProxyCommand>

# Linux and Mac
ProxyCommand ssh -i </path/to/ssh/key> <username>@monash-mlerp-login0.mlerp.cloud.edu.au /apps/strudel2/strudel_apps/sshnc.sh

# Windows
ProxyCommand ssh.exe -i </path/to/ssh/key> <username>@monash-mlerp-login0.mlerp.cloud.edu.au /apps/strudel2/strudel_apps/sshnc.sh