add tentative readme

1 files changed, 66 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5df464c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# Lumerical license SSH proxy
+
+## Disclaimer
+
+I don't know yet if this is authorized. Technically if we have access 
+using this script, then we would have access on-site or through the VPN.
+Only the transport medium changes, and it's at least as secure as a VPN
+(and anything you can do with this access, you can do with the VPN).
+
+I will ask Laurent soon just to be sure.
+
+## Requirements
+
+Make sure `bash` and an `ssh` client capable of TCP forwarding through a
+proxy are installed (all modern `ssh` clients should be able to do this?).
+
+I only tested the script on
+[WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) for now. I
+don't see any reason for it not to work on a \*nix host (including cygwin &
+cie).
+
+To use `close_tunnels.sh` should you need it, you may need some more utilities
+which are commonly available on \*nix systems.
+
+## Access to the servers
+
+This goes without saying, but you need access to `sshgate`. You
+can request access by sending a mail to
+[dsi.support@listes.ec-lyon.fr](mailto:dsi.support@listes.ec-lyon.fr). Click
+[here for a template (in french)][mail-template].
+
+## First time set-up
+
+**First**, you need to modify your ssh config by adding (and adapting) the contents
+of [`ssh_config`](ssh_config) to your `~/.ssh/config`.
+
+**Then** you need to push your public key to the server (after generating one if
+needed). The following snippet demonstrates this:
+
+```bash
+# Generate an ssh key pair with an empty password
+# CAREFUL: Don't overwrite your existing key!!!
+ssh-keygen -N ""
+
+# Push the key to sshgate
+# You need to enter your ECL password
+# Replace $pubkeyfile with the actual location (e.g. ~/.ssh/id_rsa.pub)
+ssh-copy-id -i $keyfile sshgate
+
+# You can also push the key to callisto through sshgate
+# You need to enter your INL password
+ssh-copy-id -i $keyfile callisto_sshgate
+```
+
+## Usage
+
+Using the script is pretty straight forward. Running
+`./proxy_lumerical_license.sh` starts the background jobs which start the
+tunnels and automatically restart them.
+
+By default the script does not fork to the background, so that you can close
+the tunnels using CTRL-C. If you want to fork it, just append `&` to your
+command line (i.e. run `./proxy_lumerical_license.sh &`). You can then
+close the tunnel either manually or by running `./close_proxy.sh`.
+
+[mail-template]: mailto:dsi.support@listes.ec-lyon.fr?Subject=Demande%20accès%20sshgate&Body=Bonjour%2C%0A%0AJe%20travaille%20%C3%A0%20l%27INL%20et%20j%27aurais%20besoin%20d%27avoir%20acc%C3%A8s%20%C3%A0%20SSH%20gate.%20Mon%20identifiant%20ECL%20est%20%60XXXXX%60.%0A%0ACordialement%2C%0AXXXXXX