2 Setup

The connection to Rossinante is made under the Secure Shell Protocol (SSH), a cryptographic network protocol that allows you to securely access a remote server.

Let’s say that:

`laptop`	Your laptop name
`Jane DOE`	Your name
`jane.doe@mail.com`	Your email address
`jane`	Your username on your laptop
`jdoe`	Your username on Rossinante
`92.168.45.3`	The IP address of Rossinante
`22`	The port of the SSH server

N.B. You have to replace these values by the ones provided by the administrator.

2.1 SSH connection

To open an SSH connection, you need to launch a terminal (all modern terminals include an SSH client¹):

¹ On Windows, you don’t need to install Putty anymore.

On Unix-based OS (macOS and GNU/Linux), open the app called Terminal
On Windows, open the Git Bash app² (installed by default with the git software)

² Don’t use PowerShell or RStudio terminal. Git Bash allows you to use GNU/Linux commands on Windows.

# SSH connection to Rossinante ----
ssh -p 22 jdoe@92.168.45.3

When you first connect to Rossinante (and to any remote server), you will be asked if you trust this server:

The authenticity of host '[92.168.45.3]:22' can't be established.
RSA key fingerprint is ...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Just write yes and press Enter. This will add a line in the file ~/.ssh/known_hosts that lists all your trusted servers.

Run the previous command a second time to connect to Rossinante. You’ll be asked to change your password. Enter the old password and set your new password (twice).

Your prompt will look like (a reconnection may be necessary): jdoe@rossinante:~$. This means that you are now connected to Rossinante under the username jdoe.

You can check your current directory with the command pwd:

# Print working (current) directory ----
pwd
## /home/jdoe

To stop the SSH connection, use the command exit:

# Close the SSH connection ----
exit
## Connection to 92.168.45.3 closed.

2.2 SSH config file

It can be painful to remember the IP address and the SSH port of Rossinante, especially if you use several servers. Fortunately you can store Rossinante connection information in a special file located on your laptop (not in the server): config. The file must be stored in the hidden folder .ssh/ located in your personal home directory.

To create this config file, open a terminal (or Git Bash for Windows users):

# Navigate to your home directory ----
cd ~

# Check if the folder .ssh/ exists ----
ls -al

# Create a new hidden folder (if not already existing) ----
mkdir -p ~/.ssh

# Change folder permissions ----
# (only Jane can read, write, and execute this folder)
chmod -R 700 ~/.ssh

# Create an (empty) SSH config file ----
touch ~/.ssh/config

# Change config file permissions ----
# (only Jane can read and write this file)
chmod 600 ~/.ssh/config

# Open the config file with the nano text editor ----
nano ~/.ssh/config

Now add the follow lines in the SSH config file:

Host rossinante
    HostName 92.168.45.3
    Port 22
    User jdoe

Press CTRL + X, then Y and Enter to save changes and exit the nano editor.

You can now connect to Rossinante as follow:

# SSH connection to Rossinante ----
ssh rossinante

2.3 Generating SSH keys

SSH keys are a more secure method of logging into a remote server, because they are not vulnerable to common brute-force password hacking attacks. Generating an SSH keys pair consists in creating two long strings of characters: a public and a private key. You can place the public key on any server, and then connect to the server using a device that has access to the private key.

Let’s create a new SSH keys pair using the cryptosystem ed25519. You will create this SSH keys pair locally (i.e. on your laptop).

# Create a new SSH key pair (on your laptop) ----
ssh-keygen -t ed25519 -f ~/.ssh/id_rossinante -C "jane.doe@mail.com"

If you want, you can add a passphrase to increase the security of your key pair but each time you will connect to Rossinante you will be asked to enter it. It’s up to you.

This SSH keys pair has been stored in ~/.ssh/ under the name id_rossinante.

# Content of the ~/.ssh/ folder ----
ls ~/.ssh
## config       id_rossinante       id_rossinante.pub

The private key is id_rossinante and the public one id_rossinante.pub. Nobody (except you) can have access to the private key. So you need to change the permissions of this file:

# Change private key permissions ----
# (only Jane can only read this file)
chmod 400 ~/.ssh/id_rossinante

As we set a custom key file name (id_rossinante instead of id_ed25519), we will store this file name in the ~/.ssh/config file:

# Add an entry in the config file ----
echo "    IdentityFile ~/.ssh/id_rossinante" >> ~/.ssh/config

The SSH public key can be deployed everywhere. In our case, we must store it on the Rossinante server.

# Create the folder ~/.ssh on Rossinante ----
# (here we send a command via SSH without keeping the connection open)
ssh rossinante 'mkdir -p ~/.ssh'

# Copying the public key to Rossinante ----
scp ~/.ssh/id_rossinante.pub rossinante:~/.ssh/authorized_keys

Now we can connect to Rossinante more securely and without entering any password (except if you have added a passphrase to your SSH keys pair).

# SSH connection using SSH keys ----
ssh rossinante

Our SSH public key on Rossinante has been stored under the name authorized_keys.

# Content of the ~/.ssh folder (on Rossinante) ----
ls ~/.ssh
## authorized_keys

NB – If you lose your private key you will still be able to log in with your password.

2.4 Git credentials

The version control system git is already installed on Rossinante, but you need to store your username and email (required for commits). Run the following lines:

# SSH Connection to Rossinante ----
ssh rossinante

# Set Git credentials on Rossinante (globally) ----
git config --global user.name "Jane Doe"
git config --global user.email jane.doe@mail.com

# Change default branch name ----
git config --global init.defaultBranch main

A ~/.gitconfig file has been created:

# Content of the ~/.gitconfig file ----
cat ~/.gitconfig
## [user]
##          name  = Jane Doe
##          email = jane.doe@mail.com
## [init]
##          defaultBranch = main

You can also define git parameters locally, i.e. specific to a project. For more information.

2.5 GitHub SSH keys

If you want to communicate with GitHub through the SSH protocol (recommended) you need to generate a new SSH keys pair (different from the one used to connect to Rossinante).

Let’s create a new SSH keys pair using the cryptosystem ed25519. But this time, this SSH keys pair will be generated on Rossinante.

# Create a new SSH key pair (on Rossinante) ----
ssh-keygen -f ~/.ssh/id_ed25519 -t ed25519 -C "jane.doe@mail.com"

This new SSH keys pair has been stored in ~/.ssh/.

# Content of the ~/.ssh folder ----
ls ~/.ssh
## authorized_keys       id_ed25519       id_ed25519.pub

Let’s restrict the access to the private key.

# Change private key permissions ----
# (only jdoe can only read this file)
chmod 400 ~/.ssh/id_ed25519

Now we need to store the public key on GitHub server. Visit https://github.com/settings/keys and click on New SSH key.

On Rossinante, print the public SSH key:

# Print the public SSH key ----
cat ~/.ssh/id_ed25519.pub

Copy the content of the public key and go back to GitHub. Give a title to your new SSH key (for example Rossinante key) and paste your public SSH key. Click on Add SSH key.

Congratulations! You can know communicate with GitHub using the SSH protocol from Rossinante. Let’s test the SSH connection between Rossinante and GitHub:

# Test SSH connection between Rossinante and GitHub ----
ssh -T git@github.com
## Hi janedoe! You've successfully authenticated!, but GitHub does not provide shell access.

Important – If you lose your private SSH key you won’t be able to establish a connection with GitHub (from Rossinante). You’ll need to delete your SSH key on GitHub (i.e. Rossinante key) and to create a new one.

NB – You will need to add your private GitHub SSH key on your other devices. Alternatively (recommended) you can create a new GitHub SSH keys pair on each device (if not already done).

2.6 GitHub PAT

If you want to use the GitHub API, essentially with the R package usethis, you need to create a GitHub Personal Access Token (PAT). Visit https://github.com/settings/tokens and click on Generate new token (classic). Choose a name for the token (for example Rossinante token), select an expiration date (or no expiration), and choose the scope (at least): repo and workflow. Copy the GitHub PAT and go back to Rossinante shell.

You will store this token in the file ~/.Renviron (readable by R only).

# Store GitHub PAT on Rossinante (for R only) ----
echo "GITHUB_PAT=ghp_XXX" >> ~/.Renviron

Make sure to replace ghp_XXX by your token value.

Congratulations! Your Rossinante account is successfully set up.

:::