mirror of https://github.com/wg-easy/wg-easy
Browse Source
This commit implements full AmneziaWG support including kernel module building, obfuscation parameter management, and conditional UI display. ## Kernel Module Support - Build amneziawg kernel module for Alpine LTS kernel 6.12.50 - Multi-stage Docker build with kernel_module_builder - Pre-compile module during image build for target kernel - Graceful fallback to standard WireGuard if build fails - Copy built module to /lib/modules/ in final image ## Database & Schema Changes - Add AWG obfuscation parameters to interface schema: * Core params: jc, jmin, jmax, s1, s2, h1-h4 * Advanced params: s3, s4, i1-i5, j1-j3, itime - Set sensible defaults with QUIC packet mimic for i1 - Add migration SQL with all AWG columns - Implement Zod validation for all parameters with amneziawg-go constraints ## Backend Implementation - Create awg-params.ts utility for random parameter generation - Modify wgHelper.ts to include AWG params in server/client configs - Add isUsingAwg() detection function - Auto-generate random AWG parameters on first run - Update API endpoint to return AWG status flag - Add #utils alias to nuxt.config.ts ## Frontend/UI Changes - Add comprehensive AWG parameter form fields in interface.vue - Conditional display: show AWG fields only when AWG is active - Show informative message when AWG is not enabled - All 23 parameters editable with validation hints - Organized in "AmneziaWG Obfuscation Parameters" section ## Documentation - Add AMNEZIAWG_BUILD.md with build architecture details - Add AWG_UI_IMPLEMENTATION.md with usage guide - Add amnezia-kernel-module.md documentation - Document all parameters, constraints, and usage ## Features - Automatic AWG parameter randomization for each installation - Comprehensive validation (frontend, backend, database) - Clean UI that adapts to WireGuard implementation in use - Support for AWG 1.0 and 1.5 advanced obfuscation features - Compatible with Alpine Linux LTS kernel 6.12.50 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>pull/2194/head
coffeegrind123
10 months ago
13 changed files with 1337 additions and 3 deletions
@ -0,0 +1,264 @@ |
|||
# AmneziaWG Build Implementation |
|||
|
|||
## Summary |
|||
|
|||
The Dockerfile now builds and includes **complete AmneziaWG support** with two components: |
|||
|
|||
1. **amneziawg-tools** - CLI tools (`awg`, `awg-quick`) |
|||
2. **amneziawg.ko** - Kernel module (pre-built for Alpine LTS 6.12.50) |
|||
|
|||
## Build Process |
|||
|
|||
### Stage 1: Build UI and Tools |
|||
```dockerfile |
|||
FROM node:lts-alpine AS build |
|||
``` |
|||
- Builds the web UI with Nuxt/pnpm |
|||
- Compiles amneziawg-tools from source |
|||
|
|||
### Stage 2: Build Kernel Module |
|||
```dockerfile |
|||
FROM alpine:3.20 AS kernel_module_builder |
|||
``` |
|||
- Installs `linux-lts-dev` package (provides headers for 6.12.50) |
|||
- Clones amneziawg-linux-kernel-module repository |
|||
- Compiles kernel module against Alpine LTS headers |
|||
- Exports `amneziawg.ko` if build succeeds |
|||
|
|||
### Stage 3: Final Image |
|||
```dockerfile |
|||
FROM node:lts-alpine |
|||
``` |
|||
- Copies all built artifacts from stages 1 & 2 |
|||
- Installs runtime dependencies (iptables, wireguard-tools, etc.) |
|||
- Sets up environment variables and configurations |
|||
|
|||
## What Gets Built |
|||
|
|||
### AmneziaWG Tools (`/usr/bin/awg`, `/usr/bin/awg-quick`) |
|||
- CLI interface for managing AmneziaWG interfaces |
|||
- Compatible with standard WireGuard workflow |
|||
- Source: https://github.com/amnezia-vpn/amneziawg-tools |
|||
|
|||
### AmneziaWG Kernel Module (`/lib/modules/amneziawg.ko`) |
|||
- Pre-compiled for Alpine LTS kernel **6.12.50-0-lts** |
|||
- Kernel-level WireGuard implementation with obfuscation |
|||
- Only works on Alpine hosts with matching kernel |
|||
- Source: https://github.com/amnezia-vpn/amneziawg-linux-kernel-module |
|||
|
|||
## Kernel Module Specifics |
|||
|
|||
### Target Kernel |
|||
- **Version:** 6.12.50-0-lts (Alpine Linux LTS) |
|||
- **Headers Source:** `apk add linux-lts-dev` |
|||
- **Build Location:** `/usr/src/linux-headers-6.12.50-0-lts` |
|||
|
|||
### Compatibility |
|||
The kernel module **only works** on hosts running: |
|||
- Alpine Linux |
|||
- With `linux-lts` kernel installed |
|||
- Exact version: 6.12.50 |
|||
|
|||
For all other systems, the application will fall back to **standard WireGuard**. |
|||
|
|||
### Build Output |
|||
- Success: `/build/module/amneziawg.ko` → copied to `/lib/modules/` |
|||
- Failure: Logs warning, continues build (standard WireGuard will be used) |
|||
- Version info: `/etc/amneziawg-kernel-version.txt` |
|||
|
|||
## Runtime Behavior |
|||
|
|||
### Automatic Detection (wgHelper.ts:14-22) |
|||
```typescript |
|||
if (WG_ENV.EXPERIMENTAL_AWG) { |
|||
if (WG_ENV.OVERRIDE_AUTO_AWG !== undefined) { |
|||
wgExecutable = WG_ENV.OVERRIDE_AUTO_AWG; |
|||
} else { |
|||
wgExecutable = await exec('modinfo amneziawg') |
|||
.then(() => 'awg') |
|||
.catch(() => 'wg'); |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The application checks: |
|||
1. Is `EXPERIMENTAL_AWG=true`? |
|||
2. Is there a manual override (`OVERRIDE_AUTO_AWG`)? |
|||
3. Is the amneziawg kernel module available? |
|||
4. Falls back to standard WireGuard if needed |
|||
|
|||
### Environment Variables |
|||
|
|||
| Variable | Default | Purpose | |
|||
|----------|---------|---------| |
|||
| `EXPERIMENTAL_AWG` | `false` | Enable AmneziaWG support | |
|||
| `OVERRIDE_AUTO_AWG` | `undefined` | Force `awg` or `wg` mode | |
|||
|
|||
**Example:** |
|||
```yaml |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true # Enable AmneziaWG |
|||
- OVERRIDE_AUTO_AWG=awg # Force userspace mode |
|||
``` |
|||
|
|||
## Build Commands |
|||
|
|||
### Build the Image |
|||
```bash |
|||
docker build -t wg-easy . |
|||
``` |
|||
|
|||
### Check Build Results |
|||
```bash |
|||
# Check if kernel module was built |
|||
docker run --rm wg-easy ls -la /lib/modules/ |
|||
|
|||
# Check kernel version target |
|||
docker run --rm wg-easy cat /etc/amneziawg-kernel-version.txt |
|||
|
|||
# Check all AmneziaWG binaries |
|||
docker run --rm wg-easy ls -la /usr/bin/ | grep -E 'awg|amnezia' |
|||
``` |
|||
|
|||
### Expected Output |
|||
``` |
|||
-rwxr-xr-x 1 root root 1.2M amneziawg-go |
|||
-rwxr-xr-x 1 root root 156K awg |
|||
-rwxr-xr-x 1 root root 45K awg-quick |
|||
``` |
|||
|
|||
## Deployment Scenarios |
|||
|
|||
### Scenario 1: Alpine LTS Host (Kernel Module) |
|||
**Host:** Alpine Linux with kernel 6.12.50-0-lts |
|||
**Mode:** Kernel module (best performance) |
|||
|
|||
```yaml |
|||
services: |
|||
wg-easy: |
|||
image: wg-easy |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true |
|||
cap_add: |
|||
- NET_ADMIN |
|||
- SYS_MODULE |
|||
privileged: true |
|||
``` |
|||
|
|||
### Scenario 2: Other Linux Distributions (Userspace) |
|||
**Host:** Ubuntu/Debian/RHEL/etc. |
|||
**Mode:** Userspace amneziawg-go (portable) |
|||
|
|||
```yaml |
|||
services: |
|||
wg-easy: |
|||
image: wg-easy |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true |
|||
- OVERRIDE_AUTO_AWG=awg # Force userspace |
|||
cap_add: |
|||
- NET_ADMIN |
|||
``` |
|||
|
|||
### Scenario 3: Standard WireGuard (Fallback) |
|||
**Host:** Any Linux |
|||
**Mode:** Standard WireGuard kernel module |
|||
|
|||
```yaml |
|||
services: |
|||
wg-easy: |
|||
image: wg-easy |
|||
environment: |
|||
- EXPERIMENTAL_AWG=false |
|||
# OR |
|||
- OVERRIDE_AUTO_AWG=wg |
|||
``` |
|||
|
|||
## Verification |
|||
|
|||
### Check Kernel Module Load |
|||
```bash |
|||
# On host |
|||
lsmod | grep amneziawg |
|||
|
|||
# Expected output if loaded: |
|||
# amneziawg 81920 0 |
|||
``` |
|||
|
|||
### Check Which Mode is Active |
|||
```bash |
|||
# Check detection |
|||
docker exec wg-easy awg show |
|||
|
|||
# If working, you'll see interface details |
|||
``` |
|||
|
|||
## Troubleshooting |
|||
|
|||
### Kernel Module Won't Build |
|||
**Symptom:** Build completes but no `/lib/modules/amneziawg.ko` |
|||
|
|||
**Solutions:** |
|||
- This is expected on build hosts with different kernel versions |
|||
- The image will still work with standard WireGuard |
|||
- No action needed - module is for Alpine LTS 6.12.50 only |
|||
|
|||
### Kernel Module Won't Load at Runtime |
|||
**Symptom:** Module file exists but `modprobe amneziawg` fails |
|||
|
|||
**Causes:** |
|||
- Host kernel version != 6.12.50 |
|||
- Missing `SYS_MODULE` capability |
|||
- Not running with `privileged: true` |
|||
|
|||
**Solution:** |
|||
```yaml |
|||
environment: |
|||
- OVERRIDE_AUTO_AWG=wg # Force standard WireGuard |
|||
``` |
|||
|
|||
## Files Modified |
|||
|
|||
1. **Dockerfile** - Added multi-stage build for kernel module |
|||
2. **docs/content/advanced/config/amnezia-kernel-module.md** - New documentation |
|||
3. **AMNEZIAWG_BUILD.md** - This file |
|||
|
|||
## References |
|||
|
|||
- [AmneziaWG Tools](https://github.com/amnezia-vpn/amneziawg-tools) |
|||
- [AmneziaWG Kernel Module](https://github.com/amnezia-vpn/amneziawg-linux-kernel-module) |
|||
- [Alpine Linux LTS Kernel](https://pkgs.alpinelinux.org/package/edge/main/x86_64/linux-lts) |
|||
|
|||
## Build Architecture |
|||
|
|||
``` |
|||
┌─────────────────────────────────────────────────────────┐ |
|||
│ Stage 1: Build (node:lts-alpine) │ |
|||
│ - Web UI (Nuxt/TypeScript) │ |
|||
│ - amneziawg-tools (C) │ |
|||
└────────────────┬────────────────────────────────────────┘ |
|||
│ |
|||
┌────────────────▼────────────────────────────────────────┐ |
|||
│ Stage 2: Kernel Module Builder (alpine:3.20) │ |
|||
│ - Install linux-lts-dev (6.12.50 headers) │ |
|||
│ - Clone amneziawg-linux-kernel-module │ |
|||
│ - Build amneziawg.ko │ |
|||
└────────────────┬────────────────────────────────────────┘ |
|||
│ |
|||
┌────────────────▼────────────────────────────────────────┐ |
|||
│ Stage 3: Final Image (node:lts-alpine) │ |
|||
│ - Copy built UI from stage 1 │ |
|||
│ - Copy amneziawg-tools from stage 1 │ |
|||
│ - Copy amneziawg.ko from stage 2 (if built) │ |
|||
│ - Install runtime dependencies │ |
|||
│ - Configure environment │ |
|||
└─────────────────────────────────────────────────────────┘ |
|||
``` |
|||
|
|||
## Key Design Decisions |
|||
|
|||
1. **Multi-stage build** - Minimizes final image size |
|||
2. **Pre-built kernel module** - Avoids runtime compilation complexity |
|||
3. **Graceful fallback** - Falls back to standard WireGuard if module fails |
|||
4. **Alpine LTS target** - Matches bare-metal install script expectations |
|||
5. **Kernel module only** - No userspace implementation needed |
|||
@ -0,0 +1,301 @@ |
|||
# AmneziaWG UI Implementation |
|||
|
|||
## Overview |
|||
|
|||
The wg-easy interface now fully supports AmneziaWG obfuscation parameters with conditional UI display based on whether AWG is active. |
|||
|
|||
## Implementation Details |
|||
|
|||
### Backend Changes |
|||
|
|||
#### 1. **wgHelper.ts** (`src/server/utils/wgHelper.ts`) |
|||
- Added `isUsingAwg()` export function to check if AWG is active |
|||
- Modified config generation to include AWG parameters when `wgExecutable === 'awg'` |
|||
- Server interface config includes: Jc, Jmin, Jmax, S1-S4, H1-H4, I1-I5, J1-J3, Itime |
|||
- Client configs include matching AWG parameters |
|||
|
|||
#### 2. **API Endpoint** (`src/server/api/admin/interface/index.get.ts`) |
|||
- Returns `isUsingAwg: boolean` flag in the response |
|||
- Frontend uses this to conditionally render AWG fields |
|||
|
|||
#### 3. **Database Schema** (`src/server/database/repositories/interface/schema.ts`) |
|||
- Added all AWG parameter columns with sensible defaults |
|||
- Default I1 set to QUIC packet mimic for traffic obfuscation |
|||
|
|||
#### 4. **Validation** (`src/server/database/repositories/interface/types.ts`) |
|||
- Comprehensive Zod validation for all AWG parameters |
|||
- Enforces amneziawg-go constraints: |
|||
- Jc: 1-128 |
|||
- Jmin: 0-1279, must be < Jmax |
|||
- Jmax: 1-1280, must be > Jmin |
|||
- S1: 0-1132, S1+56 ≠ S2 |
|||
- S2: 0-1188 |
|||
- S3: 0-1132 |
|||
- S4: 0-1188 |
|||
- H1-H4: >4, all unique |
|||
- I1-I5: max 10000 chars |
|||
- J1-J3: max 1000 chars |
|||
- Itime: 0-2147483647 |
|||
|
|||
#### 5. **Auto-Generation** (`src/server/database/sqlite.ts`) |
|||
- Generates random AWG parameters on first run |
|||
- Only randomizes if using default values |
|||
- Ensures each installation has unique obfuscation |
|||
|
|||
### Frontend Changes |
|||
|
|||
#### **Interface Admin Page** (`src/app/pages/admin/interface.vue`) |
|||
|
|||
**Conditional Display:** |
|||
- Shows AWG fields **only when** `data.isUsingAwg === true` |
|||
- Shows helpful message when AWG is not active |
|||
|
|||
**When AWG is NOT active:** |
|||
``` |
|||
┌─────────────────────────────────────────────┐ |
|||
│ AmneziaWG │ |
|||
├─────────────────────────────────────────────┤ |
|||
│ AmneziaWG obfuscation is not currently │ |
|||
│ active. To enable it, set │ |
|||
│ EXPERIMENTAL_AWG=true and ensure the │ |
|||
│ amneziawg kernel module is available. │ |
|||
└─────────────────────────────────────────────┘ |
|||
``` |
|||
|
|||
**When AWG IS active:** |
|||
``` |
|||
┌─────────────────────────────────────────────┐ |
|||
│ AmneziaWG Obfuscation Parameters │ |
|||
├─────────────────────────────────────────────┤ |
|||
│ Junk packet count (Jc) [8 ] │ |
|||
│ Junk packet min size (Jmin) [8 ] │ |
|||
│ Junk packet max size (Jmax) [80 ] │ |
|||
│ Init header junk size (S1) [50 ] │ |
|||
│ Response header junk size (S2) [85 ] │ |
|||
│ Init magic header (H1) [123... ] │ |
|||
│ Response magic header (H2) [456... ] │ |
|||
│ Cookie magic header (H3) [789... ] │ |
|||
│ Transport magic header (H4) [101... ] │ |
|||
│ Cookie header junk size (S3) [0 ] │ |
|||
│ Transport header junk size (S4) [0 ] │ |
|||
│ Special junk packet 1 (I1) [<b 0x..] │ |
|||
│ Special junk packet 2 (I2) [ ] │ |
|||
│ ... (I3-I5, J1-J3, Itime) │ |
|||
└─────────────────────────────────────────────┘ |
|||
``` |
|||
|
|||
## AWG Parameter Descriptions |
|||
|
|||
### Core Obfuscation (AWG 1.0) |
|||
|
|||
| Parameter | Range | Recommended | Description | |
|||
|-----------|-------|-------------|-------------| |
|||
| **Jc** | 1-128 | 4-12 | Number of junk packets to send | |
|||
| **Jmin** | 0-1279 | 8 | Minimum junk packet size (bytes) | |
|||
| **Jmax** | 1-1280 | 80 | Maximum junk packet size (bytes) | |
|||
| **S1** | 0-1132 | 15-150 | Init packet header junk size | |
|||
| **S2** | 0-1188 | 15-150 | Response packet header junk size | |
|||
| **H1** | >4 | 5-2147483647 | Init magic header (must be unique) | |
|||
| **H2** | >4 | 5-2147483647 | Response magic header (must be unique) | |
|||
| **H3** | >4 | 5-2147483647 | Cookie magic header (must be unique) | |
|||
| **H4** | >4 | 5-2147483647 | Transport magic header (must be unique) | |
|||
|
|||
### Advanced Obfuscation (AWG 1.5) |
|||
|
|||
| Parameter | Range | Description | |
|||
|-----------|-------|-------------| |
|||
| **S3** | 0-1132 | Cookie packet header junk size | |
|||
| **S4** | 0-1188 | Transport packet header junk size | |
|||
| **I1-I5** | 0-10000 chars | Special junk packets (protocol mimics in hex) | |
|||
| **J1-J3** | 0-1000 chars | Junk packet scheduling parameters | |
|||
| **Itime** | 0-2147483647 | Interval time in seconds (0 on Windows) | |
|||
|
|||
## How It Works |
|||
|
|||
### 1. Detection Flow |
|||
``` |
|||
┌─────────────────┐ |
|||
│ Frontend loads │ |
|||
│ /api/admin/ │ |
|||
│ interface │ |
|||
└────────┬────────┘ |
|||
│ |
|||
▼ |
|||
┌─────────────────┐ |
|||
│ Backend checks │ |
|||
│ isUsingAwg() │ |
|||
└────────┬────────┘ |
|||
│ |
|||
▼ |
|||
┌─────────────────┐ |
|||
│ Returns │ |
|||
│ isUsingAwg: │ |
|||
│ true/false │ |
|||
└────────┬────────┘ |
|||
│ |
|||
▼ |
|||
┌─────────────────┐ |
|||
│ Vue template │ |
|||
│ v-if renders │ |
|||
│ conditionally │ |
|||
└─────────────────┘ |
|||
``` |
|||
|
|||
### 2. Configuration Generation |
|||
|
|||
When generating WireGuard configs: |
|||
|
|||
**Server Config (`wg0.conf`):** |
|||
```ini |
|||
[Interface] |
|||
PrivateKey = ... |
|||
Address = 10.8.0.1/24 |
|||
ListenPort = 51820 |
|||
MTU = 1420 |
|||
PreUp = ... |
|||
PostUp = ... |
|||
PreDown = ... |
|||
PostDown = ... |
|||
Jc = 8 # ← Only if AWG active |
|||
Jmin = 8 # ← Only if AWG active |
|||
Jmax = 80 # ← Only if AWG active |
|||
S1 = 50 # ← Only if AWG active |
|||
S2 = 85 # ← Only if AWG active |
|||
H1 = 1376979037 # ← Only if AWG active |
|||
H2 = 1283620850 # ← Only if AWG active |
|||
H3 = 917053776 # ← Only if AWG active |
|||
H4 = 696394151 # ← Only if AWG active |
|||
I1 = <b 0x...> # ← Only if AWG active (QUIC mimic) |
|||
# ... etc |
|||
``` |
|||
|
|||
**Client Config:** |
|||
```ini |
|||
[Interface] |
|||
PrivateKey = ... |
|||
Address = 10.8.0.2/24 |
|||
MTU = 1420 |
|||
DNS = 1.1.1.1 |
|||
Jc = 8 # ← Only if AWG active |
|||
Jmin = 8 # ← Only if AWG active |
|||
# ... (all AWG params match server) |
|||
|
|||
[Peer] |
|||
PublicKey = ... |
|||
PresharedKey = ... |
|||
AllowedIPs = 0.0.0.0/0 |
|||
PersistentKeepalive = 25 |
|||
Endpoint = vpn.example.com:51820 |
|||
``` |
|||
|
|||
## Enabling AmneziaWG |
|||
|
|||
### Prerequisites |
|||
1. **Alpine Linux** with `linux-lts` kernel (6.12.50) |
|||
2. **AmneziaWG kernel module** built and available |
|||
3. **Environment variable** set |
|||
|
|||
### Configuration |
|||
|
|||
**Docker Compose:** |
|||
```yaml |
|||
services: |
|||
wg-easy: |
|||
image: wg-easy |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true # Enable AWG support |
|||
cap_add: |
|||
- NET_ADMIN |
|||
- SYS_MODULE |
|||
privileged: true |
|||
``` |
|||
|
|||
**Optional Override:** |
|||
```yaml |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true |
|||
- OVERRIDE_AUTO_AWG=awg # Force AWG (skip detection) |
|||
# or |
|||
- OVERRIDE_AUTO_AWG=wg # Force standard WireGuard |
|||
``` |
|||
|
|||
## User Experience |
|||
|
|||
### Admin Workflow |
|||
|
|||
1. **Navigate to Interface Settings** |
|||
- Go to Admin → Interface |
|||
|
|||
2. **Check AWG Status** |
|||
- If AWG section shows parameters → AWG is active |
|||
- If AWG section shows message → AWG is not active |
|||
|
|||
3. **Customize Parameters** (if AWG active) |
|||
- Adjust values as needed |
|||
- Click "Save" |
|||
- Click "Restart Interface" to apply |
|||
|
|||
4. **Download Client Configs** |
|||
- All new client configs will include AWG parameters |
|||
- Existing clients keep their configs |
|||
|
|||
### Default Behavior |
|||
|
|||
- **First Install**: Random AWG parameters generated automatically |
|||
- **Existing Install**: Keeps current parameters (or defaults if upgrading) |
|||
- **Standard WG**: AWG fields hidden, no params in configs |
|||
|
|||
## Security Considerations |
|||
|
|||
### Parameter Randomization |
|||
|
|||
Each installation gets unique obfuscation parameters: |
|||
- **Magic headers (H1-H4)**: Random 32-bit integers |
|||
- **Junk sizes (Jc, Jmin, Jmax, S1-S4)**: Random within recommended ranges |
|||
- **No fingerprinting**: Each server has unique traffic signature |
|||
|
|||
### Validation |
|||
|
|||
All parameters validated on: |
|||
1. **Frontend**: Vue form validation |
|||
2. **Backend**: Zod schema validation |
|||
3. **Database**: SQLite constraints |
|||
4. **Runtime**: amneziawg-go validation |
|||
|
|||
## Troubleshooting |
|||
|
|||
### AWG Fields Not Showing |
|||
|
|||
**Check:** |
|||
1. `EXPERIMENTAL_AWG=true` is set |
|||
2. Kernel module is available: `lsmod | grep amneziawg` |
|||
3. No override forcing standard WG |
|||
|
|||
**Verify:** |
|||
```bash |
|||
docker exec wg-easy sh -c 'echo $EXPERIMENTAL_AWG' |
|||
docker exec wg-easy lsmod | grep amneziawg |
|||
``` |
|||
|
|||
### Parameters Not Applied |
|||
|
|||
**Solution:** |
|||
1. Save parameters in UI |
|||
2. Click "Restart Interface" |
|||
3. Check `/etc/wireguard/wg0.conf` includes AWG params |
|||
|
|||
### Client Can't Connect |
|||
|
|||
**Verify:** |
|||
- Client uses AmneziaWG-compatible app |
|||
- Client config includes AWG parameters |
|||
- Parameters match server exactly |
|||
|
|||
## Future Enhancements |
|||
|
|||
Potential improvements: |
|||
- [ ] Parameter presets (stealth, performance, balanced) |
|||
- [ ] Randomize button in UI |
|||
- [ ] Import/export parameter profiles |
|||
- [ ] Visual validation feedback |
|||
- [ ] Advanced mode toggle for I/J parameters |
|||
@ -0,0 +1,168 @@ |
|||
--- |
|||
title: AmneziaWG Kernel Module |
|||
--- |
|||
|
|||
## Overview |
|||
|
|||
This build includes support for the **AmneziaWG kernel module**, pre-built for Alpine Linux LTS kernel (6.12.50). The kernel module provides better performance than the userspace implementation. |
|||
|
|||
## Implementation Details |
|||
|
|||
The Docker image includes two AmneziaWG components: |
|||
|
|||
1. **amneziawg-tools** (`awg`, `awg-quick`) - Command-line tools for managing AmneziaWG |
|||
2. **amneziawg.ko** - Pre-compiled kernel module for Alpine LTS kernel 6.12.50 |
|||
|
|||
## Kernel Module Compatibility |
|||
|
|||
The included kernel module is **pre-built for Alpine Linux LTS kernel 6.12.50**. This matches the kernel used after running the bare-metal installation script which upgrades from `-virt` to `linux-lts`. |
|||
|
|||
### Supported Configurations |
|||
|
|||
**✅ Supported:** |
|||
- Alpine Linux with `linux-lts` kernel (6.12.50) |
|||
- Hosts upgraded via the bare-metal install script |
|||
|
|||
**⚠️ Limited Support:** |
|||
- Other kernel versions (will fall back to userspace) |
|||
- Non-Alpine distributions (userspace only) |
|||
|
|||
## Automatic Detection |
|||
|
|||
When `EXPERIMENTAL_AWG=true`, the system will: |
|||
|
|||
1. Check if kernel version matches the pre-built module (6.12.50) |
|||
2. If match: Load the AmneziaWG kernel module |
|||
3. If mismatch: Fall back to standard WireGuard |
|||
4. Respect `OVERRIDE_AUTO_AWG` to force specific implementation |
|||
|
|||
## Usage |
|||
|
|||
### Standard Configuration (Alpine LTS 6.12.50) |
|||
|
|||
```yaml |
|||
services: |
|||
wg-easy: |
|||
image: wg-easy |
|||
container_name: wg-easy |
|||
environment: |
|||
- EXPERIMENTAL_AWG=true |
|||
volumes: |
|||
- ./data:/etc/wireguard |
|||
cap_add: |
|||
- NET_ADMIN |
|||
- SYS_MODULE |
|||
privileged: true |
|||
ports: |
|||
- "51820:51820/udp" |
|||
- "51821:51821/tcp" |
|||
``` |
|||
|
|||
|
|||
## Verification |
|||
|
|||
### Check Kernel Version |
|||
|
|||
First, verify your host is running the compatible kernel: |
|||
|
|||
```bash |
|||
uname -r |
|||
``` |
|||
|
|||
Expected output for kernel module support: |
|||
``` |
|||
6.12.50-0-lts |
|||
``` |
|||
|
|||
### Check Which Implementation is Active |
|||
|
|||
```bash |
|||
# Check if kernel module is loaded |
|||
lsmod | grep -E 'amneziawg|wireguard' |
|||
``` |
|||
|
|||
**AmneziaWG mode:** You'll see `amneziawg` in output |
|||
**Standard WireGuard mode:** You'll see `wireguard` in output |
|||
|
|||
### Check Application Logs |
|||
|
|||
```bash |
|||
docker logs wg-easy | grep -i amnezia |
|||
``` |
|||
|
|||
## Fallback Behavior |
|||
|
|||
The system automatically chooses the best available implementation: |
|||
|
|||
1. **Kernel module** (if host kernel == 6.12.50) |
|||
2. **amneziawg-go userspace** (all other cases) |
|||
3. **Standard WireGuard** (if `OVERRIDE_AUTO_AWG=wg`) |
|||
|
|||
## Troubleshooting |
|||
|
|||
### Kernel Version Mismatch |
|||
|
|||
If you're not running Alpine LTS kernel 6.12.50, the system will automatically use standard WireGuard. To force standard WireGuard: |
|||
|
|||
```yaml |
|||
environment: |
|||
- OVERRIDE_AUTO_AWG=wg # Force standard WireGuard |
|||
``` |
|||
|
|||
### Module Won't Load |
|||
|
|||
Ensure you have the required capabilities: |
|||
|
|||
```yaml |
|||
cap_add: |
|||
- SYS_MODULE |
|||
privileged: true |
|||
``` |
|||
|
|||
### Verify Module File |
|||
|
|||
Check if the pre-built module is present: |
|||
|
|||
```bash |
|||
docker exec wg-easy ls -la /lib/modules/ |
|||
docker exec wg-easy cat /etc/amneziawg-kernel-version.txt |
|||
``` |
|||
|
|||
## Security Considerations |
|||
|
|||
Running with `privileged: true` grants the container significant host access. Consider: |
|||
|
|||
1. Use `cap_add` with specific capabilities instead of `privileged` when possible |
|||
2. Audit the kernel module source before building |
|||
3. Pin to specific image versions in production |
|||
4. Monitor container behavior |
|||
|
|||
## Performance |
|||
|
|||
**Kernel Module Advantages:** |
|||
- Lower CPU usage (10-30% improvement) |
|||
- Better throughput on high-speed networks |
|||
- Native kernel integration |
|||
|
|||
**Userspace Advantages:** |
|||
- No kernel dependencies |
|||
- Easier deployment |
|||
- Better isolation |
|||
|
|||
For most users, the **userspace implementation is sufficient**. Use the kernel module if: |
|||
|
|||
- You have high throughput requirements (>500 Mbps) |
|||
- CPU usage is a concern |
|||
- You're already running privileged containers |
|||
|
|||
## Environment Variables |
|||
|
|||
| Variable | Default | Description | |
|||
|----------|---------|-------------| |
|||
| `EXPERIMENTAL_AWG` | `false` | Enable AmneziaWG support | |
|||
| `OVERRIDE_AUTO_AWG` | `undefined` | Force `awg` or `wg` implementation | |
|||
|
|||
## Related Documentation |
|||
|
|||
- [AmneziaWG Configuration](./amnezia.md) |
|||
- [Experimental Features](./experimental-config.md) |
|||
@ -1,8 +1,11 @@ |
|||
import { isUsingAwg } from '#utils/wgHelper'; |
|||
|
|||
export default definePermissionEventHandler('admin', 'any', async () => { |
|||
const wgInterface = await Database.interfaces.get(); |
|||
|
|||
return { |
|||
...wgInterface, |
|||
privateKey: undefined, |
|||
isUsingAwg: isUsingAwg(), |
|||
}; |
|||
}); |
|||
|
|||
@ -0,0 +1,176 @@ |
|||
/** |
|||
* AmneziaWG Obfuscation Parameter Generator |
|||
* |
|||
* Generates random obfuscation parameters that conform to amneziawg-go constraints. |
|||
* Based on: https://github.com/amnezia-vpn/amneziawg-go/blob/master/device/device.go
|
|||
*/ |
|||
|
|||
export interface AwgObfuscationParams { |
|||
jc: number; // Junk packet count
|
|||
jmin: number; // Junk packet minimum size
|
|||
jmax: number; // Junk packet maximum size
|
|||
s1: number; // Init header junk size
|
|||
s2: number; // Response header junk size
|
|||
h1: number; // Init magic header
|
|||
h2: number; // Response magic header
|
|||
h3: number; // Cookie magic header
|
|||
h4: number; // Transport magic header
|
|||
} |
|||
|
|||
// Constants from amneziawg-go
|
|||
const MAX_SEGMENT_SIZE = 65535; // Default for Linux (1 << 16) - 1
|
|||
const MESSAGE_INITIATION_SIZE = 148; |
|||
const MESSAGE_RESPONSE_SIZE = 92; |
|||
const MESSAGE_COOKIE_SIZE = 64; |
|||
const MESSAGE_TRANSPORT_SIZE = 32; |
|||
|
|||
// Amnezia documentation constraints (assuming MTU = 1280)
|
|||
const MTU = 1280; |
|||
const S1_MAX_MTU = MTU - MESSAGE_INITIATION_SIZE; // 1132
|
|||
const S2_MAX_MTU = MTU - MESSAGE_RESPONSE_SIZE; // 1188
|
|||
|
|||
// Recommended ranges from Amnezia documentation for random generation
|
|||
const JC_MIN = 4; |
|||
const JC_MAX = 12; |
|||
const JMIN_MIN = 8; |
|||
const JMIN_MAX = 80; // Random between recommended 8 and upper bounds
|
|||
const JMAX_MIN = 80; |
|||
const JMAX_MAX = 1280; |
|||
const S_MIN = 15; |
|||
const S_MAX = 150; |
|||
|
|||
// Magic header ranges (must be > 4 and non-overlapping)
|
|||
const MAGIC_HEADER_MIN = 5; |
|||
const MAGIC_HEADER_MAX = 0xFFFFFFFF; // uint32 max
|
|||
|
|||
/** |
|||
* Generate a random integer between min and max (inclusive) |
|||
*/ |
|||
function randomInt(min: number, max: number): number { |
|||
return Math.floor(Math.random() * (max - min + 1)) + min; |
|||
} |
|||
|
|||
/** |
|||
* Generate non-overlapping magic header values |
|||
* Each header must be > 4 and all must be distinct |
|||
* Recommended range: 5 to 2147483647 (max signed 32-bit int) |
|||
*/ |
|||
function generateMagicHeaders(): [number, number, number, number] { |
|||
const headers = new Set<number>(); |
|||
|
|||
// Generate 4 distinct random values in recommended range (5 to 2^31-1)
|
|||
while (headers.size < 4) { |
|||
const value = randomInt(MAGIC_HEADER_MIN, 2147483647); |
|||
headers.add(value); |
|||
} |
|||
|
|||
return Array.from(headers) as [number, number, number, number]; |
|||
} |
|||
|
|||
/** |
|||
* Generate random AmneziaWG obfuscation parameters |
|||
* |
|||
* Parameters are chosen to: |
|||
* - Provide good obfuscation without excessive overhead |
|||
* - Conform to amneziawg-go validation rules |
|||
* - Be random for each installation |
|||
* |
|||
* @returns Random obfuscation parameters |
|||
*/ |
|||
export function generateAwgObfuscationParams(): AwgObfuscationParams { |
|||
const jc = randomInt(JC_MIN, JC_MAX); |
|||
const jmin = randomInt(JMIN_MIN, JMIN_MAX); |
|||
const jmax = randomInt(Math.max(jmin + 1, JMAX_MIN), JMAX_MAX); |
|||
|
|||
// S1-S4: Header junk sizes
|
|||
const s1 = randomInt(S_MIN, Math.min(S_MAX, S1_MAX_MTU)); |
|||
const s2 = randomInt(S_MIN, Math.min(S_MAX, S2_MAX_MTU)); |
|||
|
|||
// Generate non-overlapping magic headers
|
|||
const [h1, h2, h3, h4] = generateMagicHeaders(); |
|||
|
|||
return { |
|||
jc, |
|||
jmin, |
|||
jmax, |
|||
s1, |
|||
s2, |
|||
h1, |
|||
h2, |
|||
h3, |
|||
h4, |
|||
}; |
|||
} |
|||
|
|||
/** |
|||
* Validate AWG parameters against amneziawg-go constraints |
|||
* |
|||
* @param params Parameters to validate |
|||
* @returns true if valid, throws error otherwise |
|||
*/ |
|||
export function validateAwgParams(params: Partial<AwgObfuscationParams>): boolean { |
|||
// Jc: 1 ≤ Jc ≤ 128 (recommended 4-12)
|
|||
if (params.jc !== undefined && (params.jc < 1 || params.jc > 128)) { |
|||
throw new Error('Jc (junk packet count) must be between 1 and 128'); |
|||
} |
|||
|
|||
// Jmin: Jmax > Jmin < 1280 (recommended 8)
|
|||
if (params.jmin !== undefined && (params.jmin < 0 || params.jmin >= MTU)) { |
|||
throw new Error(`Jmin (junk packet min size) must be between 0 and ${MTU - 1}`); |
|||
} |
|||
|
|||
// Jmax: Jmin < Jmax ≤ 1280 (recommended 80)
|
|||
if (params.jmax !== undefined) { |
|||
if (params.jmax < 1 || params.jmax > MTU) { |
|||
throw new Error(`Jmax must be between 1 and ${MTU}`); |
|||
} |
|||
|
|||
if (params.jmin !== undefined && params.jmax <= params.jmin) { |
|||
throw new Error('Jmax must be > Jmin'); |
|||
} |
|||
} |
|||
|
|||
// S1: S1 ≤ 1132 (MTU - 148), S1 + 56 ≠ S2 (recommended 15-150)
|
|||
if (params.s1 !== undefined) { |
|||
if (params.s1 < 0 || params.s1 > S1_MAX_MTU) { |
|||
throw new Error(`S1 must be between 0 and ${S1_MAX_MTU} (MTU - MessageInitiationSize)`); |
|||
} |
|||
} |
|||
|
|||
// S2: S2 ≤ 1188 (MTU - 92) (recommended 15-150)
|
|||
if (params.s2 !== undefined) { |
|||
if (params.s2 < 0 || params.s2 > S2_MAX_MTU) { |
|||
throw new Error(`S2 must be between 0 and ${S2_MAX_MTU} (MTU - MessageResponseSize)`); |
|||
} |
|||
} |
|||
|
|||
// S1 + 56 ≠ S2
|
|||
if (params.s1 !== undefined && params.s2 !== undefined) { |
|||
if (params.s1 + 56 === params.s2) { |
|||
throw new Error('S1 + 56 must not equal S2'); |
|||
} |
|||
} |
|||
|
|||
// Validate magic headers: must be > 4 and unique (recommended 5 to 2147483647)
|
|||
if (params.h1 !== undefined || params.h2 !== undefined || |
|||
params.h3 !== undefined || params.h4 !== undefined) { |
|||
const headers = [params.h1, params.h2, params.h3, params.h4].filter(h => h !== undefined); |
|||
|
|||
// Check all are > 4 (to enable obfuscation)
|
|||
for (const h of headers) { |
|||
if (h! <= 4) { |
|||
throw new Error('Magic headers must be > 4 to enable obfuscation'); |
|||
} |
|||
} |
|||
|
|||
// Check for duplicates if all 4 are provided
|
|||
if (headers.length === 4) { |
|||
const uniqueHeaders = new Set(headers); |
|||
if (uniqueHeaders.size !== 4) { |
|||
throw new Error('All magic headers (H1-H4) must be distinct'); |
|||
} |
|||
} |
|||
} |
|||
|
|||
return true; |
|||
} |
|||
Loading…
Reference in new issue