Update README.md

README.md

@@ -4,6 +4,38 @@ This script can be used to start a batch job on the cluster and then connect Mic
 
 https://medium.com/@isaiah.taylor/use-vs-code-on-a-supercomputer-15e4cbbb1bc2
 
+## Requirements
+
+The script assumes that you have setup SSH keys for passwordless access to the cluster. Please find some instructions on how to create SSH keys on the scicomp wiki:
+
+https://scicomp.ethz.ch/wiki/Accessing_the_clusters#SSH_keys
+
+Currently the script runs on Linux, Mac OS X and Windows (using WSL/WSL2 or git bash). When using a Linux computer, please make sure that xdg-open is installed. This package is used to automatically start your default browser. You can install it with the command
+
+CentOS:
+
+```
+yum install xdg-utils
+```
+
+Ubuntu:
+
+```
+apt-get install xdg-utils
+```
+
+## Using SSH keys with non-default names
+Since the reopening of Euler after the cyber attack in May 2020, we recommend to the cluster users to use SSH keys.
+```
+$HOME/.ssh/id_ed25519_euler
+```
+
+You can either use the -k option of the script to specify the location of the SSH key, or even better use an SSH config file with the IdentityFile option
+
+https://scicomp.ethz.ch/wiki/Accessing_the_clusters#How_to_use_keys_with_non-default_names
+
+I would recommend to use the SSH config file as this works more reliably.
+
 ## Preparation
 
 The preparation steps only need to be executed once. You need to carry out those steps to set up the basic configuration for your ETH account with regards to the code-server.
@@ -53,7 +85,25 @@ This will setup the local configuration (including a password for you) and store
 
 After the server started, terminate it with ctrl+c
 
-## Running the script
+## Usage
+
+### Install
+
+Download the repository with the commnad
+
+```
+git clone https://gitlab.ethz.ch/sfux/VSCode_remote_HPC
+```
+
+Mac OS X:
+
+```
+git clone https://gitlab.ethz.ch/sfux/VSCode_remote_HPC.git
+```
+
+### Run VSCode in a batch job
+
+The start_vscode.sh script needs to be executed on your local computer. Please find below the list of options that can be used with the script:
 
 ```
 $ ./start_vscode.sh --help
@@ -94,3 +144,24 @@ VSC_RUN_TIME="01:00"        # Run time limit for the code-server in hours and mi
 VSC_MEM_PER_CPU_CORE=1024   # Memory limit in MB per core
 VSC_WAITING_INTERVAL=60     # Time interval to check if the job on the cluster already started
 VSC_SSH_KEY_PATH=""         # Path to SSH key with non-standard name
+```
+
+### Reconnect to a code-server session
+When running the script, it creates a local file called reconnect_info in the installation directory, which contains all information regarding the used ports, the remote ip address, the command for the SSH tunnel and the URL for the browser. This information should be sufficient to reconnect to a code-server session if connection was lost.
+
+## Cleanup after the job
+Please note that when you finish working with the code-server, you need to login to the cluster, identify the job with bjobs and then kill it with the bkill command, using the jobid as parameter). Afterwards you also need to clean up the SSH tunnel that is running in the background. Example:
+
+```
+$ ps -u | grep -m1 -- "-L" | grep -- "-N"
+samfux    8729  0.0  0.0  59404  6636 pts/5    S    13:46   0:00 ssh sfux@euler.ethz.ch -L 51339:10.205.4.122:8888 -N
+$ kill 8729
+```
+
+This example is from a Linux computer. If you are using git bash on Windows, then you can find the SSH process with the ps kommand and use kill to stop it.
+
+## Main author
+* Samuel Fux
+
+## Contributions
+* Andreas Lugmayr