From a8bc26932d46e597fd78e18cbc77fab693c31115 Mon Sep 17 00:00:00 2001 From: Davide Marchegiani Date: Thu, 19 Sep 2024 15:57:54 +1000 Subject: [PATCH] Updated instructions on how to set up automatic login with SSH keys --- docs/getting_started/set_up_nci_account.md | 114 +++++++++++---------- 1 file changed, 62 insertions(+), 52 deletions(-) diff --git a/docs/getting_started/set_up_nci_account.md b/docs/getting_started/set_up_nci_account.md index 26cf35115..389796522 100644 --- a/docs/getting_started/set_up_nci_account.md +++ b/docs/getting_started/set_up_nci_account.md @@ -41,19 +41,30 @@ For tasks supported by ACCESS-NRI (e.g., running a supported model configuration ## Login to Gadi - +
+ + + +
Operations involving model runs and data collections take place on the [_Gadi_ supercomputer](https://nci.org.au/our-systems/hpc-systems). -Before you login to _Gadi_, you need to possess the following prerequisites: - +### Prerequisites - **Internet connection** - **Terminal with built-in SSH**
- Linux, MacOS and Windows 10 (or later) operative systems already have a terminal with built-in SSH.
+ LinuxMacOSWindows 10 (or later) operative system already has a terminal with built-in SSH.
+
Users of Windows 9 (or earlier) can install [Windows Subsystems for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl). !!! tip Alternatively, you can login through the [ARE Gadi Terminal](https://are.nci.org.au/pun/sys/shell/ssh/gadi.nci.org.au).
However, it is recommended that you connect to _Gadi_ from your local machine's terminal without using ARE. +
+
+ +- **git-bash**
+ You can install `git` and `git-bash` at [this link](https://git-scm.com/downloads). +
+ To login to _Gadi_ using [SSH](https://en.wikipedia.org/wiki/Secure_Shell), on your **local machine's terminal** run the following command, replacing `` with your NCI _username_ (e.g., `ab1234`): @@ -85,22 +96,24 @@ You will be prompted to enter your NCI password, and then you will be connected To simplify the login and avoid being prompted every time to enter your NCI password, follow these steps: #### Create an SSH key -To create an SSH key on your **local machine**, run: +To create an SSH key, in your **local machine's `git-bash` terminal** run: ``` -ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi +mkdir -p ~/.ssh +ssh-keygen -t ed25519 -f ~/.ssh/id_gadi ``` You will be prompted to create a passphrase linked to the SSH key, which you will enter twice: - ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_gadi + mkdir -p ~/.ssh + ssh-keygen -t ed25519 -f ~/.ssh/id_gadi Generating public/private rsa key pair. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in <$HOME>/.ssh/id_gadi - Your public key has been saved in /Users/davide/.ssh/id_gadi.pub + Your public key has been saved in <$HOME>/.ssh/id_gadi.pub The key fingerprint is: SHA256:<fingerprint-code> <$USER@hostname> The key's randomart image is: - [RSA 4096-+ + +--[ED25519 256]--+ |xxxxxxxxxxxxxxxxx| |xxxxxxxxxxxxxxxxx| |xxxxxxxxxxxxxxxxx| @@ -109,7 +122,7 @@ You will be prompted to create a passphrase linked to the SSH key, which you wil |xxxxxxxxxxxxxxxxx| |xxxxxxxxxxxxxxxxx| |xxxxxxxxxxxxxxxxx| - -[SHA256--+ + +----[SHA256]-----+ !!! warning @@ -118,74 +131,60 @@ You will be prompted to create a passphrase linked to the SSH key, which you wil #### Add the SSH key to the SSH-agent -
- - -
- An SSH-agent is an SSH key manager that avoids you having to enter your passphrase every time you connect to a server.
-To add the SSH key to the SSH-agent: +To add the SSH key to the SSH-agent, in your **local machine's `git-bash` terminal** run: -1. On your **local machine**, start the SSH-agent by running: - ``` - eval "$(ssh-agent -s)" - ``` - - eval "$(ssh-agent -s)" - Agent pid <agent-PID> - -2. Add your SSH key to the SSH-agent by running: - 
ssh-add --apple-use-keychain ~/.ssh/id_gadi
- - You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: - +
eval "$(ssh-agent -s)"
+ssh-add --apple-use-keychain ~/.ssh/id_gadi
+ +You will be prompted to enter your SSH key passphrase, which will be stored inside the SSH-agent: + + eval "$(ssh-agent -s)" + Agent pid <agent-PID> ssh-add --apple-use-keychain ~/.ssh/id_gadi Enter passphrase for <$HOME>/.ssh/id_gadi: Identity added: <$HOME>/.ssh/id_gadi <$USER@hostname> -
+ +
- !!! warning - If you are using a MacOS version prior to Monterey (12.0), substitute the `--apple-use-keychain` flag with `-K`. -
+!!! warning + If you are using a MacOS version prior to Monterey (12.0), substitute the `--apple-use-keychain` flag with `-K`. +
#### Create/Update the SSH config file The `~/.ssh/config` is a file where you can store labelled SSH configurations for different remote servers you regularly connect to, so you do not have to remember them all.
-To create an SSH config file, run the following command on your **local machine**: -``` -touch ~/.ssh/config -``` - -!!! tip - If you already have an existing `~/.ssh/config` file, the above command will not have any effect. - -The following lines should be added to your `~/.ssh/config` to describe the SSH configuration for _Gadi_ (replace `` with your NCI _username_, e.g., `ab1234`): - -
Host gadi
+To create an SSH config file and add (append) the SSH configuration for _Gadi_, in your **local machine's `git-bash` terminal** run (by replacing `` with your NCI _username_, e.g., `ab1234`):
+
cat >> ~/.ssh/config << EOF
+Host gadi
 Hostname gadi.nci.org.au
-User 
+User <your-NCI-username>
 ForwardX11 true
 ForwardX11Trusted yes
 IdentityFile ~/.ssh/id_gadi
 AddKeysToAgent yes
-UseKeychain yes

+ForwardAgent yes
+UseKeychain yes
EOF
!!! warning - If you already have an existing `~/.ssh/config` file which contains configurations for any `Host` (e.g., by using `Host *`), make sure you delete any of the keywords present in that SSH configuration from the `Gadi` configuration above. + If you have an existing `~/.ssh/config` file which contains hosts with wildcards (`*`) in their names so that `gadi` would be included in the wildcard expansion (e.g., `Host *`), make sure you don't duplicate any of the SSH configuration keywords above. #### Add the SSH key to the authorised keys To enable automatic connection to a server, that server needs to recognise the SSH key as _authorised_. The list of authorised keys for a certain server is stored in the file `~/.ssh/authorized_keys`.
-To add the newly created SSH key as an _authorised_ key for _Gadi_, run the following command from your **local machine**: +To add the newly created SSH key as an _authorised_ key for _Gadi_, in your **local machine's `git-bash` terminal** run the following command: ``` ssh gadi "mkdir -p .ssh && cat >> .ssh/authorized_keys <<< '$(cat ~/.ssh/id_gadi.pub)'" ``` You will be prompted to enter your NCI password. If you did all of the above steps correctly, this should be the last time you need to do so. -Once you complete all the above steps, you should be able to connect to _Gadi_ from your **local machine's terminal** simply by running: -``` -ssh gadi -``` +!!! success + Your automatic _Gadi_ connection is set up! + + Now you should be able to connect to _Gadi_ from your **local machine's terminal** simply by running: + ``` + ssh gadi + ``` ### Change default project on Gadi @@ -234,3 +233,14 @@ For example, if you want to change your default project to `tm70` on _Gadi_: - [https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) - [https://linuxize.com/post/using-the-ssh-config-file](https://linuxize.com/post/using-the-ssh-config-file) + + + \ No newline at end of file