Getting-Started.md

+# 1. Set up the Two Factor Authentication
+
+*TODO*
+
+# 2. Set up your SSH client
+
+In order to enforce security policies and properly monitor who is logging in to Cineca systems,
+all the SSH connections are mediated by a *[bastion host](https://en.wikipedia.org/wiki/Bastion_host)*.
+Good news is, when properly configured on your side, its existence could be practically transparent.
+
+Firstly, add the following lines to your SSH configuration file:
+
+```
+Host login*.cineca.it
+    ProxyCommand ssh -W %h:%p jump.hpc.cineca.it
+```
+
+<p>
+<details>
+<summary>Linux/macOS</summary>
+
+The SSH configuration file can be found at `~/.ssh/config`. To access full documentation about its meaning and options, go to your shell and: `$ man ssh-config`.
+
+</details>
+</p>
+
+<p>
+<details>
+<summary>Windows</summary>
+
+*TODO*
+
+</details>
+</p>
+
+# 3. Connect
+
+```
+$ ssh <your username>@login.m100.cineca.it
+```
+
+*TODO*
+
+# Optional steps
+
+We know, having to bring up your favorite 2FA app every time you spin up a new connection can be
+cumbersome. Below you can find additional methods to make this a little bit more convenient.
+
+## Enter 2FA code once per multiple SSH connections
+
+It's possible to tell SSH to keep alive a single socket and then use it to support all subsequent
+SSH sessions: this way, you can enter your 2FA code once and then open any number of new SSH sessions without having to enter it again. In order to enable it, slap the following lines into your SSH configuration file:
+
+```
+Host login*.cineca.it
+    ControlMaster auto
+    ControlPersist 1
+    ControlPath ~/.ssh/sockets/ssh_mux_%h_%p_%r
+```
+
+Please note that this mode, based on the [`ControlMaster`](https://linux.die.net/man/5/ssh_config) feature, keeps alive the connection socket as long as it is phisically possible, so if your internet connection is flaky or your laptop goes to sleep, the 2FA code would be required again.
+
+<p>
+<details>
+<summary>Windows</summary>
+
+This option is not supported on Windows, unless you're using SSH inside WSL.
+
+</details>
+</p>
+
+## Enter 2FA code once per client machine
+
+### Linux
+
+*TODO*
+
+### Windows
+
+*TODO*
+
+### macOS
+
+The Kerberos implementation shipped by macOS isn't suitable due to its lack of armored token cache, so the instructions provided here rely on [Homebrew](https://brew.sh) to install the correctly functioning version of Kerberos needed to make this procedure work.
+
+1. Install the MIT flavor of Kerberos: `brew install krb5`
+2. Donwload the provided Kerberos configuration file `<URL to Cineca config file here>`
+3. Tell Kerberos to use the downloaded configuration file: `export KRB5_CONFIG=<config file location>`
+4. Run the following script ti obtain the Kerberos ticket. Please note that after `<duration of the ticket lease>` you should run this again to obtain a new ticket:
+```bash
+/usr/local/opt/krb5/bin/kinit -n
+ARMOR_CCACHE=$(/usr/local/opt/krb5/bin/klist|grep cache:|cut -d' ' -f3-)
+/usr/local/opt/krb5/bin/kinit -T $ARMOR_CCACHE <USERNAME>@HPC.CINECA.IT
+```
+5. Add the following configuration to your `~/.ssh/config`:
+```
+Host *.cineca
+    GSSAPIAuthentication yes
+    GSSAPIDelegateCredentials yes
+    PreferredAuthentications gssapi-with-mic
+```
+6. Connect without passwords or 2FA for the duration of the lease:
+```bash
+$ ssh m100.cineca
+```
+