From 9296b3572ec159475fb12d20b612072e1ae65c5b Mon Sep 17 00:00:00 2001
From: Git Sagar <git@sagar.ch>
Date: Thu, 4 Jun 2026 14:29:20 +0530
Subject: [PATCH] add comprehensive README documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a8eb048
--- /dev/null
+++ b/README.md
@@ -0,0 +1,157 @@
+# SoftEther VPN 5 (Modified Fork)
+
+A modified fork of [SoftEther VPN 5](https://www.softether.org/) with custom profile key authentication, enhanced L2TP/PPP protocol handling, and simplified TAP interface management. Built and packaged with Nix Flakes.
+
+**Upstream:** [SoftEtherVPN/SoftEtherVPN](https://github.com/SoftEtherVPN/SoftEtherVPN)
+**Version:** 5.02.5187
+**Platforms:** x86_64-linux, aarch64-linux
+
+## Features
+
+### Custom Patches Over Upstream
+
+| Patch | Description |
+|-------|-------------|
+| `ipb-profile-key.patch` | Profile key authentication via UV_TOKEN for OpenVPN and L2TP clients |
+| `simplify_l2tp_auth.patch` | Switches L2TP/PPP from EAP to PAP, increases timeouts (90s/120s) for reliability |
+| `prevent-dmesg-call.patch` | Disables VM detection via dmesg to avoid unnecessary system calls |
+| `tap-name-no-prefix.patch` | Removes prefix from TAP interface names (uses instance name directly) |
+
+### Supported VPN Protocols
+
+- **OpenVPN** - with custom profile key authentication
+- **L2TP/IPsec** - with enhanced timeout handling and PAP authentication
+- **SSTP** (Secure Socket Tunneling Protocol)
+- **Native SoftEther VPN Protocol**
+
+### SHA-0 Utility
+
+Included companion tool for converting SoftEther configuration passwords. Implements SHA-0 hashing used by SoftEther's internal password storage.
+
+```bash
+sha0 <string>    # outputs 20-byte SHA-0 hash in hexadecimal
+```
+
+## Building
+
+### Prerequisites
+
+- [Nix](https://nixos.org/) with Flakes enabled
+
+### Build with Nix
+
+```bash
+# Build SoftEther VPN server
+nix build .
+
+# Build SHA-0 utility
+nix build .#sha0
+```
+
+### Manual Build (without Nix)
+
+Requires: cmake, pkg-config, libsodium, openssl, readline, ncurses, zlib
+
+```bash
+cmake -B build \
+  -DSE_PIDDIR=/run/softether \
+  -DSE_LOGDIR=/var/log/softether \
+  -DSE_DBDIR=/var/lib/softether \
+  -DCMAKE_INSTALL_SYSTEMD_UNITDIR=
+
+cmake --build build
+cmake --install build --prefix /usr/local
+```
+
+For a debug build, add `-DCMAKE_BUILD_TYPE=Debug`.
+
+## Configuration
+
+### Default Directories
+
+| Directory | Default Path | Purpose |
+|-----------|-------------|---------|
+| PID | `/run/softether` | Process ID files |
+| Logs | `/var/log/softether` | Server and connection logs |
+| Database | `/var/lib/softether` | Configuration database |
+
+### NixOS Module
+
+The flake exports a NixOS package with configurable options:
+
+```nix
+{
+  inputs.softether5.url = "git+ssh://forgejo@git.sagar.ch:2255/sagar/softether-5.git";
+
+  # In your NixOS configuration:
+  environment.systemPackages = [ inputs.softether5.packages.${system}.default ];
+}
+```
+
+Package options available in `package.nix`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `logDir` | `/var/log/softether` | Log file directory |
+| `pidDir` | `/run/softether` | PID file directory |
+| `dbDir` | `/var/lib/softether` | Database directory |
+| `dataDir` | (derived) | Data file directory |
+| `debug` | `false` | Enable debug build |
+
+## Authentication
+
+### Standard Authentication
+
+SoftEther supports username/password and certificate-based authentication out of the box.
+
+### Profile Key Authentication (Custom)
+
+This fork adds profile key authentication for integration with external systems:
+
+1. **OpenVPN clients** - Profile keys are extracted from peer info as `UV_TOKEN`
+2. **L2TP clients** - Profile keys are passed via the standard username/password fields
+3. The first 6 characters of the token are used as the initial key, concatenated with the password
+
+### L2TP/PPP Authentication
+
+Simplified from upstream:
+- Uses **PAP** (Password Authentication Protocol) instead of EAP
+- Packet receive timeout: **90 seconds** (upstream: 15s)
+- Data timeout: **120 seconds** (upstream: 20s)
+- CHAP/EAP and IPv6CP protocol negotiation removed for streamlined L2TP handling
+
+## Project Structure
+
+```
+.
+├── flake.nix              # Nix Flakes entry point
+├── flake.lock             # Locked dependency versions
+├── package.nix            # SoftEther package derivation
+├── patches/
+│   ├── ipb-profile-key.patch
+│   ├── prevent-dmesg-call.patch
+│   ├── simplify_l2tp_auth.patch
+│   └── tap-name-no-prefix.patch
+└── sha0/
+    ├── default.nix        # SHA-0 utility build config
+    ├── sha0.c             # SHA-0 hash implementation
+    ├── main.c             # CLI interface
+    └── types.h            # Type definitions
+```
+
+## Dependencies
+
+### Build-time
+- cmake
+- pkg-config
+- libsodium
+
+### Runtime
+- OpenSSL
+- readline
+- ncurses
+- zlib
+
+## License
+
+Based on upstream [SoftEther VPN](https://github.com/SoftEtherVPN/SoftEtherVPN) licensing. The SHA-0 implementation is sourced from the Android Open Source Project (AOSP).