MrTheory/os-amneziawg
GitHub: MrTheory/os-amneziawg
一个 OPNsense 的 AmneziaWG 插件，提供混淆 WireGuard 隧道以绕过 DPI 审查。
Stars: 26 | Forks: 5
# os-amneziawg
**AmneziaWG VPN плагин для OPNsense** — v2.6.0
AmneziaWG — обфусцированный форк WireGuard для обхода DPI-блокировок. Этот плагин добавляет AmneziaWG в OPNsense как нативный VPN-клиент с поддержкой селективной маршрутизации.
## 功能
- Импорт клиентского `.conf` файла одной кнопкой — **Parse & Fill**
- Полная поддержка параметров обфускации AmneziaWG (Jc, Jmin, Jmax, S1, S2, H1–H4)
- Генерация keypair прямо в GUI — публичный ключ отображается для передачи администратору сервера
- Приватный ключ хранится в защищённом файле `private.key` (0600) — не попадает в бэкапы конфига
- Управление туннелем через GUI: **VPN → AmneziaWG** — кнопки Start/Stop/Restart
- Автозапуск туннеля при перезагрузке OPNsense (rc.syshook)
- Статус туннеля через `awg show` в реальном времени
- Валидация всех полей: CIDR, host:port, Base64 ключи
- Совместимость с селективной маршрутизацией OPNsense (Firewall Rules + Gateway)
- Корректное отображение статуса сервиса в дашборде OPNsense
- Журнал операций `/var/log/amneziawg.log` с автоматической ротацией
- ACL-контроль доступа к API через `System → Access → Groups`
## 系统要求
| Компонент | Версия |
|---|---|
| OPNsense | 25.x / 26.x |
| FreeBSD | 14.x amd64 |
| AmneziaWG server | Любая актуальная версия |
## 快速开始
### 1. 服务器（VPS Ubuntu/Debian）
```
curl -fsSL https://raw.githubusercontent.com/Toujifushiguro/vps-scripts/main/amneziawg-install.sh \
-o amneziawg-install.sh
bash amneziawg-install.sh
```
Клиентский конфиг будет в `/etc/amnezia/amneziawg/clients/.conf`.
### 2. 在 OPNsense 上安装插件
```
scp os-amneziawg/ root@:/tmp/os-amneziawg
ssh root@
cd /tmp/os-amneziawg
sh install.sh
```
Скрипт автоматически:
- проверит целостность `pkg` — если был обновлён из FreeBSD quarterly, предложит восстановить
- покажет текущую и новую версию плагина и запросит подтверждение
- проверит наличие `awg` и модуля ядра `if_amn`
- предложит установить недостающие пакеты из FreeBSD quarterly repo (`[Y/n]`)
- заблокирует `pkg` от самообновления на время установки из quarterly
- проверит совместимость модуля ядра с версией FreeBSD (ABI check)
- создаст временный repo-конфиг, установит пакеты, удалит конфиг
- заблокирует `amnezia-kmod` от случайного обновления (`pkg lock`)
- загрузит модуль ядра и пропишет его в `/boot/loader.conf`
- скопирует файлы плагина
- установит конфиг ротации лога newsyslog
- перезапустит configd и очистит кэш
Проверить установленную версию:
```
configctl amneziawg version
```
### 3. GUI 设置
1. Обнови браузер (Ctrl+F5) → **VPN → AmneziaWG**
2. Нажми **Import .conf** → вставь конфиг → **Parse & Fill**
3. Поле **DNS** — оставь пустым, если используешь Unbound (рекомендуется)
4. Перейди на вкладку **General** → поставь галочку **Enable AmneziaWG**
5. Нажми **Apply**
6. Проверь туннель:
```
awg show
# 应显示：latest handshake: N 秒前
```
### 4. 接口和网关
| Шаг | Путь в GUI |
|---|---|
| Назначить интерфейс | Interfaces → Assignments → awg0 → **+** |
| Настроить интерфейс | Interfaces → AWG_VPN → Enable, IPv4: None |
| Создать шлюз | System → Gateways → **+** |
Параметры шлюза:
- **Interface:** AWG_VPN
- **Gateway IP:** IP пира из туннеля (например `10.8.1.1`)
- **Far Gateway:** ✅
- **Disable Monitoring:** ✅
### 5. MSS Clamping（必须！）
Без этого видео и тяжёлые страницы могут не работать.
**Firewall → Settings → Normalization → +**
| Поле | Значение |
|---|---|
| Interface | AWG_VPN |
| Protocol | TCP |
| Max MSS | 1380 |
### 6. 选择性路由
- **Firewall → Aliases** — создай список IP/сетей для маршрутизации через VPN
- **Firewall → Rules → LAN** — добавь правило:
- Source: `LAN net`
- Destination: созданный alias
- Gateway: `AWG_GW`
### 7. 出站 NAT（必须！）
Без этого трафик через туннель не будет NATиться и не уйдёт дальше VPN-сервера.
**Firewall → NAT → Outbound**
1. Переключи режим на **Hybrid outbound NAT rule generation** (если ещё не переключён)
2. Добавь правило **+**:
| Поле | Значение |
|---|---|
| Interface | AWG (awg) |
| TCP/IP Version | IPv4 |
| Protocol | any |
| Source address | LAN net |
| Source port | any |
| Destination address | any |
| Destination port | any |
| Translation / target | Interface address |
## 故障排除
### 诊断——从何处开始
```
# 1. 插件版本
configctl amneziawg version
# 2. 隧道状态
awg show
# 3. 插件操作日志
cat /var/log/amneziawg.log
# 4. 内核模块已加载？
kldstat | grep amn
# 5. 二进制文件在位？
ls -la /usr/local/bin/awg /usr/local/bin/awg-quick
# 6. 生成的配置
cat /usr/local/etc/amnezia/awg0.conf
# 7. 接口存在？
ifconfig -a | grep awg
```
### `pkg update` 因段错误崩溃
Если после установки плагина `pkg update` завершается с `Segmentation fault` — это значит, что `pkg` был обновлён из FreeBSD quarterly repo до несовместимой с OPNsense версии.
**Автоматическое исправление:** переустановите плагин — `sh install.sh` обнаружит проблему и предложит восстановить `pkg`.
**Ручное исправление:**
```
pkg-static install -f pkg # восстановить pkg из репозитория OPNsense
pkg-static update -f # обновить каталоги
pkg lock amnezia-kmod # заблокировать kmod от случайного обновления
```
### 内核崩溃/安装后随机重启
Модуль ядра `amnezia-kmod` из FreeBSD quarterly может быть собран для другой версии FreeBSD, чем использует OPNsense. Это вызывает kernel panic.
```
# 检查内核版本
uname -r
# 检查从哪个仓库安装了 kmod
pkg query '%R' amnezia-kmod
# 如果版本不匹配——删除并重新安装
pkg unlock amnezia-kmod
pkg delete amnezia-kmod
# 安装兼容版本或等待软件包更新
```
### 加载时卡在“Configuring AmneziaWG”
Если модуль ядра `if_amn` не загружается (несовместимость с ядром), boot hook может зависнуть. В v2.6.0+ добавлена проверка: если `kldload if_amn` не удаётся — запуск туннеля пропускается без зависания.
```
# 检查加载日志
cat /tmp/amneziawg_syshook.log
# 如果看到“FATAL: cannot load if_amn”——内核不兼容模块
# 重新安装 amnezia-kmod 或等待更新
```
### 隧道无法建立
```
# 手动运行并查看输出
php /usr/local/opnsense/scripts/AmneziaWG/amneziawg-service-control.php reconfigure
```
| Ошибка в логе | Причина | Решение |
|---|---|---|
| `ERROR: binary not found` | awg/g-quick не установлены | Запусти `install.sh` заново |
| `ERROR: if_amn kernel module not available` | Модуль ядра не загружается | Переустанови amnezia-kmod, проверь `kldload if_amn` |
| `ERROR: private key file not found` | Файл ключа отсутствует | Сгенерируй keypair в GUI |
| `up awg0 rc=1` | Ошибка конфига или модуль не загружен | Проверь `kldstat`, проверь конфиг |
| `SKIP: another instance` | Lock занят параллельным процессом | Подожди или удали `/var/run/amneziawg.lock` |
| `EXEC TIMEOUT: 30s` | awg-quick завис | Процесс убит автоматически, проверь сеть/DNS |
Если модуль ядра не загружен:
```
kldload if_amn
grep -q 'if_amn_load' /boot/loader.conf || echo 'if_amn_load="YES"' >> /boot/loader.conf
```
### 服务在重启后显示“stopped”
AmneziaWG запускается автоматически при загрузке через syshook (`/usr/local/etc/rc.syshook.d/start/50-amneziawg`), если `General → Enable AmneziaWG` включён. Если не стартует:
```
# 检查日志
tail /var/log/amneziawg.log
# 检查 syshook 脚本
cat /usr/local/etc/rc.syshook.d/start/50-amneziawg
# 手动运行
configctl amneziawg start
```
### 菜单 VPN → AmneziaWG 不显示
```
rm -f /var/lib/php/tmp/opnsense_menu_cache.xml
# 然后在浏览器中按 Ctrl+F5
```
### 部分工作（网站可打开，视频/重页面无法加载）
Не настроен MSS Clamping (шаг 5). **Firewall → Settings → Normalization → +**:
- Interface: AWG_VPN, Protocol: TCP, Max MSS: **1380**
- Если не помогает — попробуй 1360 или 1280
### Apply / Start / Stop 按钮无响应（“No response from configd”）
```
# 1. 重启 configd
service configd restart
# 2. 检查锁文件——是否有进程挂起？
cat /var/run/amneziawg.lock
# 如果显示 PID：
kill -9 $(cat /var/run/amneziawg.lock) 2>/dev/null
rm -f /var/run/amneziawg.lock
service configd restart
# 3. 查看日志
tail -20 /var/log/amneziawg.log
```
### Apply 显示“AmneziaWG is disabled”
Это ожидаемое поведение когда `General → Enable AmneziaWG` не отмечен. Включи сервис и нажми Apply снова.
### 私钥问题
```
# 密钥文件存在吗？
ls -la /usr/local/etc/amnezia/private.key
# config.xml 中必须包含 sentinel（不是密钥本身！）
grep -A1 'private_key' /conf/config.xml
# 期望格式：::file::
# 重新生成密钥对
configctl amneziawg gen_keypair
```
### 日志查找位置
| Лог | Путь | Содержит |
|---|---|---|
| Плагин | `/var/log/amneziawg.log` | Все операции с временными метками |
| PHP ошибки | `/var/lib/php/tmp/PHP_errors.log` | Ошибки OPNsense PHP |
| Система | `/var/log/system/latest.log` | Ошибки configd |
### 有用命令
```
awg show # статус туннеля, handshake
awg show awg0 transfer # переданные байты
configctl amneziawg status # статус через configd (JSON)
configctl amneziawg version # версия плагина
ifconfig awg0 # детали интерфейса
netstat -rn | grep awg # таблица маршрутизации
tail -f /var/log/amneziawg.log # мониторинг лога в реальном времени
```
### 卸载插件
```
sh install.sh uninstall
```
## 文件结构
```
plugin/
├── scripts/AmneziaWG/
│ └── amneziawg-service-control.php # Управление туннелем: start/stop/reconfigure/status/gen_keypair
├── service/conf/actions.d/
│ └── actions_amneziawg.conf # Команды configd
├── etc/
│ ├── inc/plugins.inc.d/
│ │ └── amneziawg.inc # Регистрация сервиса в OPNsense
│ └── newsyslog.conf.d/
│ └── amneziawg.conf # Ротация лога (1MB / daily, 5 архивов, gzip)
└── mvc/app/
├── models/OPNsense/AmneziaWG/
│ ├── General.xml / General.php # Модель: флаг enabled
│ ├── Instance.xml / Instance.php # Модель: все параметры туннеля (плоская)
│ ├── ACL/ACL.xml # ACL: права доступа к API и UI
│ └── Menu/Menu.xml # Пункт меню VPN → AmneziaWG
├── controllers/OPNsense/AmneziaWG/
│ ├── IndexController.php # Рендеринг страницы
│ ├── Api/GeneralController.php # API: get/set general.enabled
│ ├── Api/InstanceController.php # API: get/set + genKeyPair (SEC-1/SEC-2)
│ ├── Api/ServiceController.php # API: reconfigure/start/stop/restart/tunnelStatus/version
│ ├── Api/ImportController.php # API: парсинг .conf файла (POST only)
│ └── forms/
│ ├── general.xml # Форма общих настроек
│ └── instance.xml # Форма параметров туннеля
└── views/OPNsense/AmneziaWG/
└── general.volt # Шаблон GUI (вкладки Instance + General)
```
**Файлы на OPNsense после установки:**
```
/usr/local/etc/amnezia/private.key (0600) — приватный ключ (не в бэкапах)
/usr/local/etc/amnezia/awg0.conf (0600) — конфиг туннеля
/usr/local/opnsense/mvc/app/models/OPNsense/AmneziaWG/version.txt — версия плагина
/var/run/amneziawg.pid — PID файл статуса
/var/run/amneziawg.lock — lock файл от параллельных запусков
/var/log/amneziawg.log — лог операций
```
## 架构设计
**Table = off** — `awg-quick` не трогает таблицу маршрутизации. Маршрутами управляет OPNsense через Firewall Rules + Gateway. Это позволяет реализовать селективную маршрутизацию идентично Xray/WireGuard плагинам.
**Плоская модель** — один туннель, одна модель без ArrayField. XML-путь: `//OPNsense/amneziawg/instance`. Подходит для большинства сценариев использования AmneziaWG как клиента.
**Sentinel private.key** — в `config.xml` хранится строка `::file::` вместо ключа. Реальный ключ в `private.key` (0600). `InstanceController` перехватывает `get`/`set`/`genKeyPair` и управляет файлом напрямую. GUI показывает bullet-плейсхолдер.
**Конфиг туннеля** записывается в `/usr/local/etc/amnezia/awg0.conf` (права 0600) при каждом Apply.
**PID файл** `/var/run/amneziawg.pid` создаётся после успешного `awg-quick up` и удаляется при `stop` — обеспечивает корректный статус в дашборде OPNsense.
**flock защита** — параллельные вызовы `reconfigure` (от configd и ручного запуска) не конкурируют: второй вызов немедленно возвращает `OK` и выходит.
## 许可证
BSD 2-Clause License
Copyright (c) 2026 Merkulov Pavel Sergeevich (Меркулов Павел Сергеевич)
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## 作者
**Меркулов Павел Сергеевич**
Февраль–Март 2026
## 致谢
- [AmneziaVPN](https://github.com/amnezia-vpn) — за разработку AmneziaWG
- [OPNsense](https://opnsense.org) — за открытую архитектуру плагинов
- [Toujifushiguro](https://github.com/Toujifushiguro) — за скрипт установки сервера
标签：AmneziaWG, DPI绕过, ffuf, FreeBSD, GUI管理, OPNsense, SEO: DPI绕过, SEO: OPNsense插件, SEO: VPN插件, SEO: WireGuard混淆, Streamlit, VPN插件, WireGuard, 安全, 客户端, 密钥对, 开源, 日志轮转, 服务端, 混淆, 系统插件, 网络, 访问控制, 超时处理, 路由, 进程监控, 选择性路由, 配置文件导入, 隧道