# Конфигурационные параметры wg-obfuscator

## Формат файла конфигурации

Конфигурационный файл — текстовый INI-подобный формат.

```ini
# Комментарий (символ # и всё правее него игнорируется)
[имя_инстанса]
параметр = значение
```

- Каждый **`[раздел]`** задаёт отдельный инстанс обфускатора. При запуске процесс форкается для каждого раздела.
- Имя раздела используется в логах как метка (`section_name`). Если инстанс один, раздел необязателен — по умолчанию применяется имя `main`.
- Пробелы вокруг `=` и в начале/конце строки игнорируются.
- Пустые строки игнорируются.

Пример файла с двумя инстансами: `/opt/Phobos/server/wg-obfuscator.conf`

---

## Основные параметры

### `source-lport`

**Обязательный.** UDP-порт, на котором обфускатор принимает входящие пакеты.

| | |
|---|---|
| Флаг CLI | `-p` / `--source-lport` |
| Тип | целое число |
| Допустимые значения | 1–65535 |
| Умолчание | нет (обязателен) |

На стороне **сервера** — публичный порт, открытый для клиентов.  
На стороне **клиента** — локальный порт, на который WireGuard-интерфейс отправляет пакеты (`127.0.0.1:<source-lport>`).

---

### `target`

**Обязательный.** Адрес и порт назначения, куда обфускатор пересылает (де-)обфусцированный трафик.

| | |
|---|---|
| Флаг CLI | `-t` / `--target` |
| Формат | `<host>:<port>` |
| Умолчание | нет (обязателен) |

На стороне **сервера** — локальный WireGuard-демон, например `127.0.0.1:51820`.  
На стороне **клиента** — публичный адрес серверного обфускатора, например `1.2.3.4:13255`.  
Поддерживаются как IP-адреса, так и DNS-имена — разрешаются при старте.

---

### `key`

**Обязательный.** Ключ обфускации. Одинаковый на обеих сторонах.

| | |
|---|---|
| Флаг CLI | `-k` / `--key` |
| Тип | строка |
| Длина | 1–255 символов |
| Умолчание | нет (обязателен) |

Используется для XOR-преобразования пакетов: из ключа с помощью CRC8 строится маска, применяемая к данным. Более длинный ключ — более разнообразная маска, но незначительно увеличивает нагрузку.

---

### `source-if`

Сетевой интерфейс (IP-адрес), на котором открывается слушающий сокет.

| | |
|---|---|
| Флаг CLI | `-i` / `--source-if` |
| Тип | IP-адрес или DNS-имя |
| Умолчание | `0.0.0.0` (все интерфейсы) |

Используется, если нужно привязать обфускатор к конкретному сетевому интерфейсу.

---

## Параметры маскировки

### `masking`

Режим маскировки пакетов под легитимный протокол для обхода DPI.

| | |
|---|---|
| Флаг CLI | `-a` / `--masking` |
| Тип | строка (регистронезависимо) |
| Допустимые значения | `AUTO`, `STUN`, `MEDIA`, `NONE` |
| Умолчание | `AUTO` |

| Значение | Поведение |
|----------|-----------|
| `AUTO` | Сервер: маскировка отключена, тип автоопределяется по первому пакету клиента. Клиент: использует `STUN` |
| `STUN` | Трафик оборачивается в STUN-сообщения. Автоопределяется по magic cookie `0x2112A442` |
| `MEDIA` | Трафик маскируется под RTP/H.264 медиапоток (видеозвонок/стрим). **Задаётся явно на обеих сторонах** — автоопределение недоступно |
| `NONE` | Маскировка отключена. Обфускация XOR остаётся активной |

---

### `obfuscate-bytes`

Сколько первых байт пакета преобразовывать XOR. Остаток пакета остаётся нетронутым.

| | |
|---|---|
| Флаг CLI | `-O` / `--obfuscate-bytes` |
| Тип | целое число |
| Допустимые значения | `0`–∞ |
| Умолчание | `0` (весь пакет); для `MEDIA` — `16` автоматически |

| Значение | Поведение |
|----------|-----------|
| `0` | Обфусцируется весь пакет |
| `≥1` | Обфусцируются только первые N байт. При этом padding (`max-dummy`) отключается |

**Минимально безопасное значение для скрытия сигнатуры WireGuard — `4`** (тип сообщения + reserved-байты). Меньше нельзя.

Рекомендация при ограниченных ресурсах: `obfuscate-bytes = 4` — скрывает сигнатуру, не тратит CPU на шифрование высокоэнтропийной WireGuard-нагрузки.

> Значение обязано быть **одинаковым на обеих сторонах**.

---

## Параметры режима MEDIA

Применяются только при `masking = MEDIA`. Значения на обеих сторонах должны быть согласованы (см. правила ниже).

### `media-pt`

RTP payload type («тип кодека» в заголовке RTP).

| | |
|---|---|
| Флаг CLI | `-P` / `--media-pt` |
| Тип | целое число |
| Допустимые значения | `0`–`127` |
| Умолчание | `0` |

| Значение | Поведение |
|----------|-----------|
| `0` | Случайный из ~50 типовых H.264-пресетов на каждое подключение. Проверка PT при приёме **отключена** — согласование не нужно |
| `96`–`127` | Фиксированное значение. Проверяется при приёме. **Должно совпадать на обеих сторонах** |

---

### `media-ssrc`

RTP SSRC — идентификатор потока в заголовке RTP. При ненулевом значении служит скрытым токеном распознавания.

| | |
|---|---|
| Флаг CLI | `-S` / `--media-ssrc` |
| Тип | число (decimal или `0x`-hex) |
| Допустимые значения | `0`–`0xFFFFFFFF` |
| Умолчание | `0` |

| Значение | Поведение |
|----------|-----------|
| `0` | Случайный для каждого подключения (свой в каждую сторону). Проверка SSRC **отключена** |
| `≠0` | Фиксированное значение с проверкой при приёме. **Должно совпадать на обеих сторонах** |

---

### `media-clock`

Частота кадров (fps), задающая шаг инкремента RTP timestamp (`ts_step = 90000 / fps`).

| | |
|---|---|
| Флаг CLI | `-C` / `--media-clock` |
| Тип | целое число |
| Допустимые значения | `0`–`1000` |
| Умолчание | `0` |

| Значение | Поведение |
|----------|-----------|
| `0` | Случайный пресет из набора. Приёмником **не проверяется** — согласование не нужно |
| `≠0` | Фиксированный шаг timestamp (`90000 / fps`). Не проверяется приёмником, согласование не требуется |

Не влияет на нагрузку CPU и размер пакетов — задаёт лишь поле 4-байтного RTP timestamp.

---

### Правила согласования параметров MEDIA

| Параметр | Совпадение обязательно |
|----------|----------------------|
| `masking = MEDIA` | да |
| `key` | **да** |
| `obfuscate-bytes` | **да** |
| `media-pt` | только если задан ненулевым |
| `media-ssrc` | только если задан ненулевым |
| `media-clock` | нет |

**Правило:** для `media-pt` и `media-ssrc` — либо `0` на обеих сторонах (случайно), либо одно и то же ненулевое значение. Смешивать нельзя.

---

## Дополнительные параметры

### `max-dummy`

Максимальный размер случайного padding (dummy-байтов), добавляемых к каждому пакету для обфускации размеров.

| | |
|---|---|
| Флаг CLI | `-d` / `--max-dummy` |
| Тип | целое число |
| Допустимые значения | `0`–`1024` |
| Умолчание | `4` |

| Тип пакета | Ограничение |
|------------|-------------|
| Handshake / Handshake Response | до `MIN(max-dummy, 512)` байт |
| Data / Cookie | до `MIN(max-dummy, max-dummy)` байт; `0` — без padding |

> При использовании `obfuscate-bytes > 0` (частичный XOR) padding **автоматически отключается** (всегда `0` независимо от значения `max-dummy`). Это связано с тем, что при частичном XOR размер пакета должен быть предсказуем на обеих сторонах.  
> В режиме `MEDIA` padding также не действует.

Суммарный размер пакета с padding не превысит `1024` байт.

---

### `idle-timeout`

Время в секундах, после которого неактивное клиентское соединение удаляется.

| | |
|---|---|
| Флаг CLI | `-l` / `--idle-timeout` |
| Тип | целое число (секунды) |
| Допустимые значения | `> 0` |
| Умолчание | `300` (5 минут) |

Не рукопожавшиеся соединения удаляются через `5000 мс` (константа `HANDSHAKE_TIMEOUT`) независимо от этого параметра.  
Статические биндинги (`static-bindings`) не удаляются никогда.

---

### `max-clients`

Максимальное количество одновременных клиентских соединений.

| | |
|---|---|
| Флаг CLI | `-m` / `--max-clients` |
| Тип | целое число |
| Допустимые значения | `> 0` |
| Умолчание | `1024` |

При достижении лимита новые клиенты отклоняются с ошибкой в лог.

---

### `static-bindings`

Список статических биндингов для двустороннего режима (когда сервер одновременно является клиентом другого узла).

| | |
|---|---|
| Флаг CLI | `-b` / `--static-bindings` |
| Формат | `<client_ip>:<client_port>:<local_port>[, ...]` |
| Умолчание | нет |

Каждый биндинг: `<ip клиента>:<UDP порт клиента>:<локальный UDP порт для соединений с сервером>`.

```ini
static-bindings = 1.2.3.4:12883:6670, 5.6.7.8:12083:6679
```

Статические биндинги не удаляются по `idle-timeout`. Используются, когда у обеих сторон есть публичный статический IP.

---

### `fwmark`

Firewall mark, проставляемый на все исходящие пакеты (Linux `SO_MARK`).

| | |
|---|---|
| Флаг CLI | `-f` / `--fwmark` |
| Тип | целое число (decimal или `0x`-hex) |
| Допустимые значения | `1`–`65535` |
| Умолчание | `0` (отключено) |
| Платформа | только Linux |

Применяется для маршрутизации по политикам (`ip rule`) — например, чтобы исходящий трафик обфускатора не попадал в WireGuard-туннель.

---

### `reuseport`

Включает `SO_REUSEPORT` на слушающем сокете.

| | |
|---|---|
| Флаг CLI | `-R` / `--reuseport` |
| Тип | флаг (без значения) |
| Умолчание | выключено |
| Платформа | только Linux |

Позволяет нескольким процессам/потокам слушать один и тот же порт (балансировка на уровне ядра). Полезно при запуске нескольких инстансов на одном порту.

---

### `verbose`

Уровень детализации логов в stderr.

| | |
|---|---|
| Флаг CLI | `-v` / `--verbose` |
| Тип | строка или число `0`–`4` |
| Умолчание | `INFO` (`2`) |

| Уровень | Числовое значение | Описание |
|---------|------------------|----------|
| `error` / `errors` | `0` | Только критические ошибки |
| `warn` / `warnings` | `1` | Важные предупреждения |
| `info` | `2` | Информационные сообщения: статус, подключения |
| `debug` | `3` | Детальная отладочная информация |
| `trace` | `4` | Дамп каждого пакета в hex; **резко повышает нагрузку на CPU** |

На боевом сервере рекомендуется `verbose = error`.

---

## Многоинстансный режим

Один файл конфигурации может содержать несколько секций `[имя]`. При запуске процесс форкается для каждой секции, создавая независимые инстансы обфускатора.

```ini
[server_443]
source-lport = 443
target = 127.0.0.1:51820
key = key_for_443
masking = AUTO

[server_80]
source-lport = 80
target = 127.0.0.1:51820
key = key_for_80
masking = STUN
```

Каждый инстанс пишет в лог с меткой `[имя_секции]`.

---

## Путь к конфигурационному файлу

| Компонент | Путь |
|-----------|------|
| Серверный конфиг | `/opt/Phobos/server/wg-obfuscator.conf` |
| Переменные окружения сервера | `/opt/Phobos/server/server.env` |
| Systemd-сервис | `wg-obfuscator.service` |

---

## Переменные server.env

Файл `/opt/Phobos/server/server.env` хранит серверные настройки, используемые скриптами управления Phobos. Изменяются через интерактивное меню `phobos` или напрямую.

| Переменная | Назначение | Умолчание |
|------------|------------|-----------|
| `OBFUSCATOR_PORT` | UDP-порт обфускатора | `51821` |
| `OBFUSCATOR_KEY` | Ключ обфускации | `KEY` |
| `OBFUSCATOR_DUMMY` | Значение `max-dummy` | `4` |
| `OBFUSCATOR_IDLE` | Значение `idle-timeout` (секунды) | `300` |
| `OBFUSCATOR_MASKING` | Режим `masking` | `AUTO` |
| `WG_LOCAL_ENDPOINT` | Адрес локального WireGuard (`target`) | `127.0.0.1:51820` |
| `CLIENT_WG_PORT` | Порт клиентского обфускатора (Endpoint в конфиге клиента) | `13255` |
| `SERVER_PUBLIC_IP_V4` | Публичный IPv4-адрес сервера | `0.0.0.0` |
| `SERVER_PUBLIC_IP_V6` | Публичный IPv6-адрес сервера | (пусто) |
| `SERVER_WG_IPV4_NETWORK` | Туннельная сеть IPv4 | `10.25.0.0/16` |
| `SERVER_WG_IPV6_NETWORK` | Туннельная сеть IPv6 | `fd00:10:25::/48` |
| `TOKEN_TTL` | Время жизни клиентских токенов (секунды) | `86400` |

---

## Полный пример конфигурации

### Серверная сторона

```ini
[instance]
source-if = 0.0.0.0
source-lport = 13255
target = 127.0.0.1:51820
key = my_secret_key
masking = AUTO
verbose = error
idle-timeout = 300
max-dummy = 4
```

### Клиентская сторона (STUN)

```ini
[client]
source-lport = 13800
target = 1.2.3.4:13255
key = my_secret_key
masking = STUN
verbose = error
```

### Клиентская сторона (MEDIA)

```ini
[client]
source-lport = 13800
target = 1.2.3.4:13255
key = my_secret_key
masking = MEDIA
obfuscate-bytes = 4
max-dummy = 0
verbose = error
```

Серверная сторона для MEDIA — та же конфигурация, что выше, но с `masking = MEDIA` и теми же значениями `key`, `obfuscate-bytes`.

---

## Внутренние константы (справочно)

Значения заданы в исходном коде и не настраиваются через конфиг.

| Константа | Значение | Назначение |
|-----------|----------|------------|
| `BUFFER_SIZE` | `65535` байт | Размер буфера приёма/отправки |
| `POLL_TIMEOUT` | `5000 мс` | Таймаут epoll/poll на каждой итерации |
| `HANDSHAKE_TIMEOUT` | `5000 мс` | Время ожидания завершения рукопожатия |
| `ITERATE_INTERVAL` | `1000 мс` | Интервал проверки idle и таймеров маскировки |
| `MAX_DUMMY_LENGTH_TOTAL` | `1024` байт | Максимальный допустимый размер padding |
| `MAX_DUMMY_LENGTH_HANDSHAKE` | `512` байт | Максимальный padding для handshake-пакетов |
| `PENDING_SEND_SIZE` | `8` пакетов | Размер очереди отложенных отправок на клиента |
| `QUEUE_SIZE` | `4096` слотов | Размер lock-free очереди пакетов (многопоточный режим) |
| `MAX_WORKER_THREADS` | `16` | Максимальное число рабочих потоков |
| `RTP_HEADER_SIZE` | `12` байт | Накладные расходы на пакет в режиме MEDIA |