add comprehensive README documentation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
8e132d8293
commit
9296b3572e
1 changed files with 157 additions and 0 deletions
157
README.md
Normal file
157
README.md
Normal file
|
|
@ -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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue