commit 19b50974436f42b22f69afef63c03cb2152dfe08
Author: Tobias <tobias@tobiastime.xyz>
Date:   Sat Jun 6 14:39:06 2026 +0100

    Add README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cc2451a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+# Information relating to my WireGuard VPN server and its Ansible playbook for automated deployment
+
+## Motivation
+
+I have various mass-storage NFS/SMB shares which are only available locally, moreover I have strict firewall rules in place to only allow SSH access to my servers from within the same broadcast zone.
+
+Though secure, this imposes the obvious limitation of only being able to access said servers or shares when I'm at home.
+
+While maintaining security, and exposing my network as little as possible, I desired a reliable and minimalistic way to access these resources when away from home. 
+
+For this task, WireGuard's cryptography, asymmetric key-paring and minimal overhead provided the perfect solution.
+
+## Architecture
+
+```
++------------------+
+|  Proxmox Host    |
+|                  |
+|  +------------+  |
+|  | AlmaLinux  |  |
+|  |    VM      |  |
+|  |            |  |
+|  | WireGuard  |  |
+|  |   Server   |  |
+|  +------------+  |
++--------+---------+
+         |
++------------------+
+| Firewall/Router  |
+|   51820:51820    |
+|    UDP --> VM    |
++------------------+
+         |
+ +----------------+
+ |    Internet    |
+ +----------------+
+         |
+ +----------------+
+ |WireGuard-Client|
+ +----------------+     
+
+```
+
+## Features
+
+- Fully automated server-side deployment via an Ansible playbook
+
+- Efficent use of address space with a /31 subnet prefix following RFC 3021, intended for 1 man use and management
+
+- Dynamic IP hosting supported via utilizing [BashDDNS](https://git.tobiastime.xyz/Tobias/BashDDNS), and specifying a domain name as the endpoint for the client
+
+- Lightweight, with a dedicated virtual machine requiring less than 256MBs of RAM
+
+- Secure through WireGuard's dual-key asymmetric [cryptography](https://www.wireguard.com/protocol/)
+
+- Automated and unattended security updates keeping the underlying virtual machine patched
+
+## Notes for playbook and automated deployment
+
+This only automates the server-side set up, the client will still need to be manually configured.
+
+The wireguard.ini file must be edited with the relevant host/user/python interpreter information.
+
+The playbook is written for a RHEL-based WireGuard server.
+
+To set up from scratch after cloning this repository, from the root of the directory run,
+
+``` bash
+ansible -i wireguard.ini playbooks/master.yml
+```
+
+Relevant port forwarding will need to be implemented on the router/firewall, it is also highly recommended to make a DHCP reservation for the WireGuard VM, or to manaully assign a static IP, to avoid the VPN tunnel breaking through IP changes.
+
+Client and server public/private keys will be located in ``` /etc/wireguard/ ``` after set up and can be relocated as desired.
+
+A typical client set up is, 
+
+- Interface
+Name, Client Private Key, Addresses (10.10.10.1/32)
+
+- Peer
+Server Public Key, Allowed IPs (10.10.10.0/31, LAN IP range), Endpoint:51820, Persistent Keep Alive 25 seconds
+
+Persistent keep alive will send a dummy packet every 25 seconds to maintain a connection when you are roaming with a mobile device and subject to frequent IP change.
+
+## Extremely useful Linux tools in debugging
+
+- tcpdump
+
+- nmap
+
+- ss
+
+- wg
+
+- ip
+
+- ping
+
+## Extremely useful documentation
+
+- https://www.wireguard.com/quickstart/
+
+- https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/10/html/configuring_and_managing_networking/setting-up-a-wireguard-vpn
+
+- https://gist.github.com/lanceliao/5d2977f417f34dda0e3d63ac7e217fd6
+
+- https://www.rfc-editor.org/info/rfc3021/
\ No newline at end of file