AWG2_harness/docs/CONFIGURATION.md

Конфигурация AWG2 Harness

AWG2 Harness разрабатывался для self-hosted AmneziaWG/AWG 2.0 и совместимого legacy-сценария AmneziaWG/AWG 1.5. Конфиг живёт в /etc/awg2-harness/config.toml. Он общий для всего пакета и должен содержать только эксплуатационно значимые параметры.

Рекомендуемый config.toml

[amnezia]
container_names = ["amnezia-awg2", "amnezia-awg"]
interface_candidates = ["awg0", "wg0", "amnezia0", "tun0"]
interface_patterns = ["awg*", "wg*", "amnezia*", "tun*"]
peer_ipv4_cidr = "10.8.1.0/24"

[traffic]
enabled = true
peer_limit = "50mbit"
root_rate = "500mbit"
reconcile_interval_secs = 15
container_ready_timeout_secs = 120
class_start_id = 10
ifb_name = "ifb0"

[host_firewall]
enabled = true
ssh_port = 2323
amnezia_port = 443
amnezia_protocols = ["udp"]
allow_icmp = true
default_input_policy = "drop"

[anti_torrent]
enabled = true
max_connections_per_peer = 150
peer_ipv4_cidr = "10.8.1.0/24"
apply_in_amnezia_netns = true

[reboot]
enabled = true
window_start_utc = "01:00"
window_end_utc = "02:00"

[swap]
enabled = true
path = "/swapfile"
size_mb = 2048
priority = 1
swappiness = 1

Пояснения

amnezia.container_names — имена контейнеров, которые считаются Amnezia/AWG. Порядок важен. По текущему production-снимку основной вариант — amnezia-awg2, fallback — amnezia-awg.

amnezia.interface_candidates — точные имена интерфейса, которые пробуются первыми.

amnezia.interface_patterns — fallback-паттерны для устойчивости к обновлениям Amnezia. Они нужны для снижения риска переименования интерфейса между awg0, wg0, amnezia0, tun0.

amnezia.peer_ipv4_cidr — подсеть VPN peers. Production default — 10.8.1.0/24; значение конфигурируемое.

traffic.peer_limit — per-peer лимит в обе стороны. Текущий production default — 50mbit.

traffic.root_rate — верхний HTB-класс, в текущем production default — 500mbit.

traffic.reconcile_interval_secs — период фоновой проверки. Он нужен не вместо Docker events, а вместе с ними.

traffic.container_ready_timeout_secs — сколько ждать появления интерфейса после старта контейнера.

traffic.class_start_id — первый class id. Production default — 10, что даёт классы 1:10, 2:10 и дальше.

traffic.ifb_name — имя IFB-интерфейса для ingress shaping. Production default — ifb0. Этот параметр можно оставить в конфиге, потому что бинарь реально создаёт/удаляет этот интерфейс.

При drift orchestrator всегда делает controlled rebuild owned topology.

anti_torrent.enabled — включает nftables connection-count guard против high-peer-count P2P-нагрузки. Это отдельный AWG2 Harness module и часть текущего production-контракта.

host_firewall.enabled — включает host-level INPUT firewall в отдельной AWG2-owned таблице inet awg2_host_firewall.

host_firewall.ssh_port — SSH порт хоста, который обязательно должен быть открыт. Production default/example: 2323. Значение обязано совпадать с реально слушающим sshd портом до применения apply-firewall.

host_firewall.amnezia_port — внешний UDP/TCP порт Amnezia, который AWG2 открывает в host INPUT (в зависимости от host_firewall.amnezia_protocols). В текущей целевой конфигурации default — 443; значение должно совпадать с реально опубликованным Amnezia UDP/TCP port.

Для диагностического блока Docker/Amnezia port path в status приоритет сопоставления такой: сначала ищется published UDP binding с HostPort == host_firewall.amnezia_port, затем fallback на ключ "<amnezia_port>/udp" как container port, затем (если UDP binding ровно один) берётся он. Если UDP bindings несколько и однозначного совпадения нет, статус показывает published_udp_port: unknown.

Диагностика FORWARD в этом блоке является best-effort: сначала используется iptables -S FORWARD, затем fallback через nft list ruleset; результаты только отображаются в status и не изменяют host FORWARD/Docker NAT.

host_firewall.amnezia_protocols — протоколы для порта Amnezia (udp, tcp или оба).

Важно: awg2-harness не управляет host FORWARD/Docker NAT-цепочками. Проект сознательно не добавляет универсальные правила в FORWARD и не меняет Docker-managed forwarding path.

host_firewall.allow_icmp — разрешать ICMP/ICMPv6 на входе.

host_firewall.default_input_policy — политика INPUT chain (drop или accept). Для production рекомендуется drop.

anti_torrent.max_connections_per_peer — максимум одновременных conntrack flows на один VPN peer IP. Текущий пример использует 150: это мягче, чем строгий 100, и обычно безопаснее как первый production baseline. 100 можно использовать как более жёсткий режим; 200/250 — более permissive варианты.

anti_torrent.peer_ipv4_cidr — подсеть, на которую распространяется правило. Обычно должна совпадать с amnezia.peer_ipv4_cidr.

anti_torrent.apply_in_amnezia_netns — выбор namespace для применения anti-torrent правил:

• true (default): применять в network namespace контейнера Amnezia;
• false: применять в host namespace.

Для production рекомендуется true, если peer source IP (10.8.1.x) видны именно внутри netns контейнера.

apply-firewall в текущей модели делает оба reconcile: host firewall (host namespace) и anti-torrent firewall (configured namespace).

reboot.enabled — включает плановую перезагрузку.

reboot.window_start_utc / reboot.window_end_utc — UTC-окно плановой перезагрузки. Production default/example — 01:00–02:00 UTC.

swap.enabled — включает setup-задачу swap.

swap.path, swap.size_mb, swap.priority, swap.swappiness — параметры managed swap. При swap.enabled=true пакет приводит swap-state к exclusive состоянию: активен ровно один swap (swap.path), остальные выключаются и swap-entries в /etc/fstab пересобираются в одну managed строку. Рекомендуемый low priority — 1, swappiness = 1.

Что не выносить в конфиг

Не нужно выносить:

• handles 1:, 2:, ffff:;
• имена внутренних Rust-модулей;
• формат команд tc;
• retry micro-tuning;
• формат логов;
• путь lock-файла, если нет эксплуатационной причины;
• hardening systemd;
• nftables hook/priority/table names, если нет осознанной причины.

Handles и структура HTB + fq_codel + ingress + ifb — это contract traffic module, а не настройка оператора.