From 10ba3fb6647adfe24e3e23f17f544926a52dcfd4 Mon Sep 17 00:00:00 2001
From: Balakrishnan Balasubramanian <git.user@balki.me>
Date: Sun, 14 Dec 2025 20:04:02 -0500
Subject: [PATCH] update README with intro and internals

---
 Makefile  |  2 ++
 README.md | 16 ++++++++++++++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 2010f32..2352a5d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,7 @@
 
 PREFIX=/usr/local
 
+.PHONY: install
 install:
 	install -Dm 644 common_sshconfig -t "$(PREFIX)/lib/diyvpn"
 	install -Dm 755 diyvpn.sh -t "$(PREFIX)/lib/diyvpn"
@@ -10,6 +11,7 @@ install:
 	install -dm 755 "$(PREFIX)/lib/systemd/user-generators"
 	ln -snf ../../diyvpn/diyvpn.sh "$(PREFIX)/lib/systemd/user-generators/diyvpn"
 
+.PHONY: uninstall
 uninstall:
 	rm -rf "$(PREFIX)/lib/diyvpn" \
 		"$(PREFIX)/bin/diyvpnctl" \
diff --git a/README.md b/README.md
index 7b39f3b..a6878ac 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # Simple DIY VPN
 
+Tool to setup SOCKS proxy using ssh dynamic forward to your own server.
+Technically this is it not a VPN but practically achives the same thing for the
+most common use-case - browse websites without revealing your ip address
+
 ## Features
 
 * Starts automatically on demand and shuts down automatically when not used
@@ -7,7 +11,7 @@
 * Works on any VPS or home server with just ssh suppport.
   Distro/architecture/size does not matter. Only working ssh support required.
   No other software setup required on the server
-* Easy to setup multiple different VPNs to different server. No need to change
+* Easy to setup multiple different VPNs to different servers. No need to change
   whole system network settings.
 * Simple interactive cli utility to setup. No need to create/edit config files
 * Simple bash script with no dependencies - (ssh and systemd are usually
@@ -67,7 +71,12 @@ us1                  127.0.0.1:8070
 
 ## Internals
 
-TODO: Explain
+This sets up a systemd [user-generator][4]. The generator creates three units
+1. A [systemd-socket][5] that listens on the configured listen address.
+2. A socket activator unit that is triggered when someone connects to the
+   socket. This uses [systemd-socket-proxyd][6] to forward the request to the
+   ssh service and also setup idle timeout.
+3. The ssh service unit creates the ssh connection and setups dynamic forward.
 
 ## Future Ideas
 
@@ -79,3 +88,6 @@ TODO: Explain
 [1]: https://github.com/bekh6ex/firefox-container-proxy
 [2]: https://librewolf.net/
 [3]: https://wiki.archlinux.org/index.php?title=SSH_keys#Copying_the_public_key_to_the_remote_server
+[4]: https://man.archlinux.org/man/systemd.generator.7
+[5]: https://man.archlinux.org/man/systemd.socket.5.en
+[6]: https://man.archlinux.org/man/core/systemd/systemd-socket-proxyd.8.en