> For the complete documentation index, see [llms.txt](https://docs.mikopbx.com/mikopbx/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mikopbx.com/mikopbx/modules/miko/module-vpn.md).

# VPN

Модуль **VPN** позволяет подключить MikoPBX к удалённой сети по защищённому туннелю. Это удобно, когда станция стоит за NAT и к ней нужен доступ извне или когда требуется объединить несколько площадок в одну сеть.

MikoPBX выступает в роли **VPN-клиента**: вы готовите конфигурацию на стороне VPN-сервера, а затем переносите её в модуль. Модуль сам поднимает туннель после настройки сети и при загрузке станции, следит за его состоянием и автоматически переподнимает соединение, если оно оборвалось.

{% hint style="warning" %}
**Важно!** В соответствии с требованиями законодательства об информации, информационных технологиях и защите информации текущий модуль может быть использован исключительно для целей построения и функционирования виртуальной частной сети, обеспечивающей безопасную передачу данных, передача которых не запрещена законом. Компания МИКО не несёт ответственности за действия пользователя в случае использования им указанной информации в целях, противоречащих законодательству Российской Федерации.
{% endhint %}

## Поддерживаемые типы VPN <a href="#types" id="types"></a>

Модуль поддерживает четыре типа подключений. Тип выбирается при создании соединения и определяет формат конфигурации.

| Тип                        | Назначение                        | Особенности                                                                   |
| -------------------------- | --------------------------------- | ----------------------------------------------------------------------------- |
| **WireGuard**              | Современный быстрый туннель       | Минимум настроек, высокая скорость, шифрование ChaCha20‑Poly1305              |
| **WireGuard (обфускация)** | WireGuard с обфускацией трафика   | Те же возможности WireGuard, плюс изменение сигнатуры трафика                 |
| **OpenVPN**                | Универсальный совместимый туннель | Поддержка TUN/TAP, в том числе устаревших шифров (BF‑CBC, DES, RC4)           |
| **Tailscale**              | Управляемая mesh‑сеть             | Авторизация по ключу, работа через облако Tailscale или собственный Headscale |

{% hint style="info" %}
Бинарные файлы всех VPN-клиентов (включая модуль ядра для режима обфускации) поставляются прямо в составе модуля и собраны статически под архитектуры **x86\_64** и **arm64**. Устанавливать что-либо на саму станцию вручную не требуется.
{% endhint %}

## Создание подключения <a href="#create" id="create"></a>

1. Убедитесь, что модуль **VPN** установлен и включён в разделе **«Управление модулями»**.
2. Откройте настройки модуля и добавьте новое подключение.
3. Заполните общие поля и в зависимости от выбранного типа — конфигурацию или параметры Tailscale.
4. Включите подключение и сохраните изменения. Туннель поднимется автоматически.

Каждое соединение описывается единым набором общих полей:

| Поле                     | Назначение                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| **Название подключения** | Произвольное имя для удобства (обязательное поле).                                                 |
| **Тип VPN**              | OpenVPN, WireGuard (в том числе с обфускацией) или Tailscale.                                      |
| **Конфигурация**         | Текст конфигурационного файла VPN (для Tailscale заменяется отдельными полями). Обязательное поле. |
| **Описание**             | Необязательный комментарий.                                                                        |
| **Включено**             | Поднимать ли туннель. Выключенное соединение хранится, но не запускается.                          |

{% hint style="warning" %}
Конфигурация проверяется при сохранении. Если в ней не хватает обязательных директив для выбранного типа  подключения, модуль выведет предупреждение.
{% endhint %}

Для каждого типа ниже приведены пример клиентской конфигурации, которую нужно вставить в поле **«Конфигурация»**, и разбор опций.

## WireGuard <a href="#wireguard" id="wireguard"></a>

WireGuard — это компактный современный протокол: текстовый конфиг, высокая скорость и стойкое шифрование. Подходит как основной вариант для большинства сценариев.

### Пример конфигурации

```ini
[Interface]
PrivateKey = <ПРИВАТНЫЙ_КЛЮЧ_КЛИЕНТА>
Address = 10.10.0.2/24

[Peer]
PublicKey = <ОТКРЫТЫЙ_КЛЮЧ_СЕРВЕРА>
Endpoint = <IP_СЕРВЕРА>:51820
AllowedIPs = 10.10.0.0/24
PersistentKeepalive = 25
```

### Опции

| Параметр              | Секция        | Назначение                                                                    |
| --------------------- | ------------- | ----------------------------------------------------------------------------- |
| `PrivateKey`          | `[Interface]` | Приватный ключ MikoPBX. Уникален, хранится только на станции. **Обязателен.** |
| `Address`             | `[Interface]` | IP-адрес и подсеть станции внутри туннеля.                                    |
| `PublicKey`           | `[Peer]`      | Открытый ключ VPN-сервера. **Обязателен.**                                    |
| `Endpoint`            | `[Peer]`      | Адрес и порт сервера (`IP:порт`, по умолчанию `51820`). **Обязателен.**       |
| `AllowedIPs`          | `[Peer]`      | Подсети, трафик в которые направляется в туннель. **Обязателен.**             |
| `PersistentKeepalive` | `[Peer]`      | Интервал keepalive (сек). Нужен, когда станция за NAT (рекомендуется `25`).   |

{% hint style="info" %}
Директива `DNS = …` автоматически удаляется при запуске: в MikoPBX нет `resolvconf`, и её наличие помешало бы поднять интерфейс.
{% endhint %}

Обязательные секции и параметры: `[Interface]` с `PrivateKey`, `[Peer]` с `PublicKey`, `AllowedIPs` и `Endpoint`.

## WireGuard с обфускацией <a href="#wireguard-obfuscation" id="wireguard-obfuscation"></a>

Это вариант WireGuard с **обфускацией трафика**: за счёт служебного «шума» и модификации заголовков сигнатура потока отличается от стандартного WireGuard. Скорость остаётся близкой к WireGuard.

### Пример конфигурации

```ini
[Interface]
PrivateKey = <ПРИВАТНЫЙ_КЛЮЧ_КЛИЕНТА>
Address = 10.30.0.2/24
Jc = 4
Jmin = 40
Jmax = 70
S1 = 53
S2 = 17
H1 = 983740153
H2 = 462767079
H3 = 1539016181
H4 = 805765999

[Peer]
PublicKey = <ОТКРЫТЫЙ_КЛЮЧ_СЕРВЕРА>
Endpoint = <IP_СЕРВЕРА>:51821
AllowedIPs = 10.30.0.0/24
PersistentKeepalive = 25
```

### Опции обфускации

К стандартным параметрам WireGuard добавляются параметры маскировки. Все они должны **точно совпадать** со значениями на сервере, иначе туннель не поднимется.

| Параметр        | Назначение                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------- |
| `Jc`            | Количество «мусорных» пакетов, добавляемых для зашумления потока.                              |
| `Jmin` / `Jmax` | Минимальный и максимальный размер случайного джиттера.                                         |
| `S1` / `S2`     | Размеры «магических» заголовков, маскирующих служебные пакеты.                                 |
| `H1`–`H4`       | Числовые маркеры заголовков, изменяющие сигнатуру пакетов относительно стандартного WireGuard. |

{% hint style="warning" %}
Режим обфускации работает на уровне ядра и требует соответствующий модуль ядра, собранный под ядро MikoPBX (**6.12.73‑MikoPBX**). Он уже входит в состав модуля VPN — отдельно ничего ставить не нужно. Как и в WireGuard, директива `DNS = …` удаляется автоматически.
{% endhint %}

Обязательные параметры: все обязательные параметры WireGuard плюс параметр обфускации `Jc`.

## OpenVPN <a href="#openvpn" id="openvpn"></a>

OpenVPN — наиболее универсальный вариант: работает с большинством существующих серверов, поддерживает режимы TUN и TAP, аутентификацию по сертификатам или по статическому ключу. Конфигурация задаётся в формате обычного `.ovpn`-файла.

### Пример конфигурации (статический ключ)

```ini
dev tun
remote <IP_СЕРВЕРА> 1194
proto udp
cipher AES-256-CBC
ifconfig 10.20.0.2 10.20.0.1
secret [inline]
keepalive 10 60
persist-tun
persist-key
verb 3
allow-deprecated-insecure-static-crypto

<secret>
-----BEGIN OpenVPN Static key V1-----
<СТАТИЧЕСКИЙ_КЛЮЧ>
-----END OpenVPN Static key V1-----
</secret>
```

### Опции

| Директива                                 | Назначение                                                                        |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| `dev tun` / `dev tap`                     | Тип интерфейса: `tun` (уровень IP) или `tap` (уровень Ethernet). **Обязательна.** |
| `remote`                                  | Адрес и порт сервера. **Обязательна** (либо блок `<connection>`).                 |
| `proto`                                   | Транспорт: `udp` (быстрее) или `tcp` (надёжнее проходит фильтры).                 |
| `cipher`                                  | Алгоритм шифрования (например, `AES-256-CBC`).                                    |
| `ifconfig`                                | IP клиента и сервера в туннеле (для режима статического ключа).                   |
| `secret`                                  | Статический ключ: `[inline]` — встроен в блок `<secret>`, либо путь к файлу.      |
| `keepalive`                               | Интервал и таймаут проверки соединения.                                           |
| `allow-deprecated-insecure-static-crypto` | Разрешает режим статического ключа в OpenVPN 2.7+.                                |

{% hint style="info" %}
Если в конфигурации используются устаревшие шифры (**BF‑CBC, DES, RC4, IDEA, CAST5, SEED**), модуль автоматически запускает специальную сборку `openvpn-legacy` со встроенным legacy-провайдером OpenSSL. Это нужно только для совместимости со старыми серверами OpenVPN (например, 2.2.x); вручную ничего переключать не требуется.
{% endhint %}

Обязательные директивы: `remote` (или блок `<connection>`) и `dev tun`/`dev tap`.

## Tailscale <a href="#tailscale" id="tailscale"></a>

Tailscale — это не просто туннель, а **управляемая mesh‑сеть**. Узлы находят друг друга через сервер управления (control plane), получают адреса из диапазона `100.64.0.0/10` и соединяются напрямую. Для Tailscale в модуле вместо текстового конфига используются отдельные поля.

### Поля Tailscale

| Поле                         | Назначение                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Сервер авторизации**       | URL control plane. Оставьте пустым для облака Tailscale или укажите адрес своего Headscale.             |
| **Ключ авторизации**         | Auth key для неинтерактивного входа. Если оставить пустым — будет предложена авторизация через браузер. |
| **Имя хоста**                | Имя станции в сети (tailnet), например `mikopbx-office`.                                                |
| **Дополнительные параметры** | Прочие флаги `tailscale up`, по одному на строку (например, `--advertise-exit-node`).                   |

### Пример дополнительных параметров

```bash
--advertise-exit-node
--advertise-routes=192.168.0.0/24
--accept-routes
```

{% hint style="info" %}
Состояние Tailscale (идентичность узла и ключи) сохраняется на постоянном хранилище модуля и переживает перезагрузку станции и переустановку модуля. Поэтому при последующих запусках выполняется «тёплый» старт — без повторной авторизации.
{% endhint %}

Для уже подключённого соединения в интерфейсе доступны действия **переавторизации** (получить новую ссылку для входа) и **выхода** (logout с удалением сохранённого состояния).

{% hint style="info" %}
Сборка Tailscale в модуле поддерживает транспорт **с обфускацией**: при наличии параметров обфускации они автоматически применяются к туннелю Tailscale. Это позволяет совместить удобство mesh‑сети с обфускацией транспорта.
{% endhint %}

Обязательный параметр для автоматического (неинтерактивного) подключения — ключ авторизации (`--authkey`). Без него потребуется ручная авторизация по ссылке.

## Запуск и контроль состояния <a href="#status" id="status"></a>

Модуль поднимает все включённые соединения автоматически: после настройки сети и после загрузки станции. Состояние каждого туннеля проверяется по расписанию (раз в минуту) — если соединение оборвалось, оно поднимается заново.

В списке соединений отображается текущий статус, а для активных туннелей — назначенный IP-адрес, время последнего рукопожатия и объём переданных данных.

{% hint style="warning" %}
При выключении или удалении соединения соответствующий туннель немедленно останавливается, и связанные с ним сетевые маршруты удаляются.
{% endhint %}

## Настройка VPN-сервера <a href="#server" id="server"></a>

Модуль — это клиентская часть. Конфигурацию для вставки готовят на стороне VPN-сервера. В репозитории модуля (каталог `samples-server-configs`) есть готовые скрипты для быстрого разворачивания тестового сервера каждого типа (WireGuard, WireGuard с обфускацией, OpenVPN со статическим ключом, Headscale для Tailscale) — они генерируют пары ключей и сразу формируют клиентский конфиг, который остаётся скопировать в модуль.

Ключевые параметры по умолчанию в этих примерах:

| Тип                    | Порт        | Подсеть туннеля |
| ---------------------- | ----------- | --------------- |
| WireGuard              | `51820/udp` | `10.10.0.0/24`  |
| WireGuard (обфускация) | `51821/udp` | `10.30.0.0/24`  |
| OpenVPN                | `1194/udp`  | `10.20.0.0/24`  |
| Tailscale / Headscale  | `443/tcp`   | `100.64.0.0/10` |

Пошаговый пример объединения двух АТС MikoPBX по WireGuard (включая ручную настройку на стороне сервера) приведён здесь:

{% content-ref url="/pages/qX0N5BWFXH3wEls6E9yp" %}
[WireGuard - VPN](/mikopbx/faq/interconnections/wireguard-vpn.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mikopbx.com/mikopbx/modules/miko/module-vpn.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.