Preparation Workshop - dieterich-lab/hbigs_course_2022 GitHub Wiki

Preparation Workshop

Overview

The aim of this workshop is to give you access to the HPC cluster of DieterichLab. For this purpose you need these:

  • WireGuard: A VPN tunnel to access the internal network of DieterichLab
  • SSH: A secure terminal connection to the servers
  • TLS: Dieterich Lab's CA certificate to access the internal web applications

The contact person for this is Harald Wilhelmi [email protected], the system administrator for the Dieterichlab computer cluster.

Setting Up WireGuard

What was done already?

Before the preparation workshop this should have happened already:

$ umask 077
$ wg genkey > secret_key.txt
$ wg pubkey < secret_key.txt
  • Sent the public key to [email protected].
  • Get a IP address and a course account from Harald.

Finish the Setup

Now create WireGuard configuration - either in the GUI or as a text file (your WireGuard Config File). If you don't have a GUI (Linux), you must create a configuration file manually. Otherwise, you may just have to fill in the right parameters for the remote side (peer):

[Interface]
PrivateKey = <your secret key goes here>
Address = <your IP>
ListenPort = 51820

[Peer]
PublicKey = hP45m/EB6vd8kuU9ii1VdyZCrJ5XZ1XPPcT5eVfkHUI=
Endpoint = 129.206.148.250:51820
AllowedIPs = 10.250.135.0/24

--- Start: If you don't have a GUI (mostly Linux) ---

In case of Linux systems, you may omit the "Address" line, because that is actually part of the network setup. Write a small shell script to do this part of the setup, e.g. start_vpn.sh:

#!/bin/bash

ip link add dev wg0 type wireguard
ip address add dev wg0 <your IP>/24
wg setconf wg0 <your WireGuard Config File>
ip link set up dev wg0
ip route add 10.250.135.0/24 dev wg0

In addition, we write another script to shutdown the VPN tunnel, e.g. start_vpn.sh:

#!/bin/bash

ip link delete wg0

--- End: If you don't have a GUI (mostly Linux) ---

Now you can start the tunnel, either via the GUI or by using your script:

$ sudo start_vpn.sh

Using SSH

Linux, Mac-OS or Windows with "Windows Subsystem for Linux" or CygWin

Open a terminal window and connect:

$ ssh <your course user>@cluster.dieterichlab.org

Windows

Get PuTTY, WinSCP and install both:

* https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
* https://winscp.net/eng/index.php

In PuTTY define a session with this parameters:

Hostname: cluster.dieterichlab.org
Port: 22 (Default)
Connection > Data > auto-login: <your course account>

Go back to Sessions an save all that under a nice name, e.g.: DieterichLab. Now you can double-click the saved session to connect as in the CLI case. From there on everything should work like for the Linux users. WinSCP is used for file transfer. Using it should be trivial if you managed to setup PuTTY.

TLS

The Dieterich Lab web services use an internal certificate authority (CA). If you access them, your browser will complain that their certificates are invalid. To smoothly work with them, please install that CA's certificate into your trust store. Here is the certificate:

What needs to be done on your system heavily depends on both your operating system and your web browser. On most systems it done today like this:

  1. Open your preferred browser.
  2. Open the preferences or settings.
  3. Search for "certificate" and open the certificate management window (Firefox: "View Certificate").
  4. Select the "Authorities" tab.
  5. Use "Import" and select a file you saved the above certificate to.
  6. During the import, allow the certificate to be used for web sites.

If you need detailed instructions, just google for "install certificates (your browser) (your OS)". The instructions from the VMWare people seem to be especially well illustrated, e.g. for Firefox:

Testing

Just try it

When connecting for the first time, you will have to accept the host key of the target system:

The authenticity of host 'cluster.dieterichlab.org (10.250.135.120)' can't be established.
ECDSA key fingerprint is SHA256:laxPaiuBytyrm26o5sMzI6XsnGRdA3YXXXrYknILAHk.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

Use the name of your course account as the password. Make sure that you can connect to the cluster as described above with your course account. Try out some simple commands:

course01@atlas:~$ ls -a
.  ..  .bash_history  .bash_logout  .bashrc  .gnupg  .profile  .Xauthority
course01@atlas:~$ uname -a
Linux atlas 4.19.0-18-amd64 #1 SMP Debian 4.19.208-1 (2021-09-29) x86_64 GNU/Linux
course01@atlas:~$ exit
logout
Connection to cluster.dieterichlab.org closed.

Finally direct your browser to one of the internal services of dieterichlab.org:

The login screen of JupyterHub should open without errors and warnings.

If it does not work

If you try from elsewhere a firewall may block the tunnel packages. You may try again from a less restrictive network e.g.:

  • Your Internet access at home
  • Your cell phone's mobile hot spot

If it does not work open a terminal an type:

$ sudo wg

Check the output. It must look like this:

peer: hP45m/EB6vd8kuU9ii1VdyZCrJ5XZ1XPPcT5eVfkHUI=
  endpoint: 129.206.148.250:51820
  allowed ips: 10.250.135.0/24
  latest handshake: 11 seconds ago
  transfer: 5.59 KiB received, 8.81 KiB sent

Important is:

  • 'latest handshake' must be present
  • 'transfer' must show numbers > 0 for both directions
  • The peer public key must be 'hP45m/EB6vd8kuU9ii1VdyZCrJ5XZ1XPPcT5eVfkHUI=' - and not your public key.

If anything is wrong, check first your WireGuard configuration. Next, check the routing. If it looks wrong have a closer at the "ip route" lin in your shell scrip (Linux) and the "AllowedIPs" line in your WireGauard configuration. On Linux that can be done like this:

$ ip route get 10.250.135.120
10.250.135.120 dev wg0 src ...
    cache

On non-Linux systems you will have to inspect the routing table:

netstat -rn

In doubt show it to Harald. In any case it is important that the traffic to 10.250.135.120 is routed via your tunnel interface (wg0, tunX, ...).

⚠️ **GitHub.com Fallback** ⚠️