From 1008abdc444960dc73f2eb1c0221c78a6fe80aab Mon Sep 17 00:00:00 2001
From: Anders Pitman <tapitman11@gmail.com>
Date: Wed, 23 Sep 2020 10:28:18 -0600
Subject: [PATCH] Write first draft of readme

---
 README.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 71 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 3ba51b9..90554c9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,71 @@
-# SirTunnel
-Minimal, self-hosted, 0-config alternative to ngrok. Caddy+OpenSSH+50 lines of Python.
+# What is it?
+
+If you have a webserver running on one computer (say your development laptop),
+and you want to expose it securely (ie HTTPS) via a public URL, SirTunnel
+allows you to easily do that.
+
+# How do you use it?
+
+If you have:
+
+* A SirTunnel server instance listening on port 443 of `example.com`.
+* A copy of the sirtunnel.py script available on the PATH of the server.
+* An SSH server running on port 22 of `example.com`.
+* A webserver running on port 8080 of your laptop.
+
+And you run the following command on your laptop:
+
+```bash
+ssh -tR 9001:localhost:8080 example.com sirtunnel.py sub1.example.com:9001
+```
+
+Now any requests to `https://sub.example.com` will be proxied to your local
+webserver.
+
+
+# How does it work?
+
+The command above does 2 things:
+
+1. It starts a standard [remote SSH tunnel][2] from the server port 9001 to
+   local port 8080.
+2. It runs the command `sirtunnel.py sub1.example.com:9001` on the server.
+   The python script parses `sub1.example.com:9001` and uses the Caddy API to
+   reverse proxy `sub1.example.com` to port 9001 on the server. Caddy
+   automatically retrieves an HTTPS cert for `sub1.example.com`.
+
+**Note:** The `-t` is necessary so that doing CTRL-C on your laptop stops the
+`sirtunnel.py` command on the server, which allows it to clean up the tunnel
+on Caddy. Otherwise it would leave `sirtunnel.py` running and just kill your
+SSH tunnel locally.
+
+
+# How is it different?
+
+There are a lot of solutions to this problem. In fact, I've made something of
+a hobby of maintaining [a list][0] of the ones I've found so far.
+
+The main advantages of SirTunnel are:
+
+* Minimal. It leverages [Caddy][1] and whatever SSH server you already have
+  running on your server. Other than that, it consists of a 50-line Python
+  script on the server.  That's it. Any time you spend learning to customize
+  and configure it will be time well spent because you're learning Caddy and
+  your SSH server.
+* 0-configuration. There is no configuration on the server side.  Not even CLI
+  arguments.
+* Essentially stateless. The only state is the certs (which is handled entirely
+  by Caddy) and the tunnel mappings, which are ephemeral and controlled by the
+  clients.
+* No special client is required. You can use any standard SSH client that
+  supports remote tunnels.
+* Automatic HTTPS certificate management. Some other solutions do this as well,
+  so it's important but not unique.
+
+
+
+[0]: https://github.com/anderspitman/awesome-tunneling
+
+[1]: https://caddyserver.com/
+
+[2]: https://www.ssh.com/ssh/tunneling/example#remote-forwarding