Documentation.md

@@ -9,20 +9,15 @@ the HPC team.
 your account, see [cisco-duo-setup.pdf](uploads/cd518a29f4362a9383c7345a975ed065/cisco-duo-setup.pdf) .
 
 After you have successfully enrolled in Duo and prepared your SSH Key, please 
-send me a short mail to pabel@uni-koeln.de .
-
-**PLEASE NOTE**: putting the key in your home in cheops just makes it possible for 
-me to take this file to ramses. But it doesn't happen automatically, I have to 
-do that. That is why I ask you to send me an email when you have completed SSH 
-and Duo setup, so I know I can create your account on ramses.
+send your key to pabel@uni-koeln.de .
 
 
 ### SSH KEYS
 
 Here is a quick intro to ssh keys: There is always a private and a public key 
-in a key pair. The public key (*.pub) is put into the file ~/.ssh/
-authorized_keys on ramses . When you have the matching private key, this makes 
-the login authentication work. Don't give away the private key and secure it 
+in a key pair. The public key (*.pub) is put into the file `~/.ssh/
+authorized_keys` on ramses . When you have the matching private key, this makes 
+the login authentication work. Do not give away the private key and secure it 
 with a passphrase:
 
 You can create a modern key (ed25519) using
@@ -31,32 +26,32 @@ You can create a modern key (ed25519) using
 ssh-keygen -t ed25519 -C "Your Name"
 ```
 
-and it should be created as ~/.ssh/id_ed25519(.pub)
+and it should be created as `~/.ssh/id_ed25519(.pub)`
 
 Then send us the **id_ed25519.pub** file.
 
-If your ssh on your computer is old, it will not know the key type ed25519.
+If your `ssh` on your computer is old, it will not know the key type ed25519.
 In this case use
 
 ```
 ssh-keygen -t rsa -b 4096 -C "Your Name"
 ```
 
-and send us the file ~/.ssh/id_rsa.pub instead.
+and send us the file `~/.ssh/id_rsa.pub` instead.
 
-Please set a password on the ssh key (it will ask you for one during ssh-
-keygen) and use the ssh-agent to load the file into memory:
+Please set a password on the ssh key (it will ask you for one during `ssh-
+keygen`) and use the `ssh-agent` to load the file into memory:
 
 On most Linux and Macs this is pre-installed, you can check with the command 
 `ssh-add -l`. This should not return an error, but usually
-"This agent has no identities". Then add your key:
+`This agent has no identities`. Then add your key:
 
 ```
 ssh-add [ path to your key file, ~/.ssh/id_rsa or id_ed25519 ]
 ```
 
-You can usually just run ssh-add since ssh-add can find the files on its own.
-ssh-add asks for the password you set in the ssh-keygen step and afterwards 
+You can usually just run `ssh-add` since `ssh-add` can find the files on its own.
+`ssh-add` asks for the password you set in the `ssh-keygen` step and afterwards 
 `ssh-add -l` should list your key like this:
 
 ```
@@ -72,6 +67,8 @@ advise you to create your own SSH key on your local machine/laptop and then
 add the public key to your `.ssh/authorized_keys` file in your home on RAMSES. 
 Any text editor will work for this.
 
+**PLEASE NOTE**: Do no share SSH Keys with other people and do not copy around private keys to other computers. Just create new SSH Key pairs on each computer you use regularly. You can also use SSH Agent Forwarding, where an SSH Key is taken along into a SSH session to a remote computer, eliminating the need to create many keys.
+
 
 ### LOGIN
 
@@ -81,6 +78,7 @@ Do not use ramses2 or ramses3, they are for internal use only for now.
 
 When you log into ramses1, a verification request is automatically 
 pushed to your Duo App on your phone.
+
 On your terminal you should see something like this:
 
 ```
@@ -93,7 +91,7 @@ Success. Logging you in...
 rpabel2@ramses1:~> 
 ```
 
-Even though the message "Autopushing..." appears twice, only one push is 
+Even though the message `Autopushing...` appears twice, only one push is 
 executed and only one verification is needed.
 
 On ramses4, you can choose different Cisco Duo authenticators, if you have 
@@ -118,12 +116,10 @@ Key that triggers Duo Autopush is counted by Duo. If you don't respond in your
 App, your account will be blocked after 10 attempts (and has to be unlocked by 
 an admin).
 
-Regarding 2FA login: If you own (*) a Yubikey ( https://www.yubico.com/de/
+Regarding 2FA login: If you own (*) a Yubikey [Yubico.com](https://www.yubico.com/de/
 product/yubikey-5-series/yubikey-5-nfc/) hardware token, it is now possible 
 to use it (in OTP mode) as the second authentication factor instead of Duo 
-Push. The procedure to make this work is a bit convoluted, so I will not go 
-into detail here right now. If you are interested in using a yubikey, please 
-contact us at hpc-mgr@uni-koeln.de .
+Push. If you are interested in using a yubikey, please contact us at [hpc-mgr](mailto:hpc-mgr@uni-koeln.de) .
 
 (*) We cannot supply yubikeys to users, since these cost about 50€ per piece. 
 Maybe ask your department head if they are willing to order some for your work 
@@ -132,13 +128,13 @@ group. Nitrokeys are not supported yet, sadly.
 
 ### FILESYSTEMS
 
-The filesystem setup is exactly as on Cheops, with /home, /projects and /
-scratch:
+The filesystem setup is exactly as on Cheops, with `/home`, `/projects` and `/
+scratch`:
 - On home the quota is also 100GB and 100.000 files. There is no backup yet.
-- you can use /scratch up to 50TB, the automatic deletion of files will be 
-enabled soon
-- You can create your own projects directory for now under /projects/
-friendly_users/ . These will be deleted after this phase ended.
+- you can use `/scratch` up to 40TB, the automatic deletion of files will be 
+enabled soon.
+- You can create your own projects directory for now under `/projects/
+friendly_users/` . These will be deleted after this phase ended.
 
 There is no automatic mechanism to sync files in Cheops and Ramses. You have to 
 copy your files yourself.