Netmaker: mesh-VPN на базе WireGuard с веб-панелью

MAATRIX

Когда узлов в VPN больше двух-трёх, ручное ведение конфигов WireGuard превращается в рутину: каждое новое устройство — это новый блок [Peer] в конфигах всех остальных, и любая ошибка в ключе рвёт туннель без внятной причины. Netmaker решает эту задачу иначе: он держит полную топологию сети в базе, сам раздаёт узлам актуальные конфиги и выстраивает mesh — сеть, где каждый узел напрямую видит каждый, без единой точки отказа. Ниже — как поднять Netmaker через Docker, добавить узлы и настроить egress- и ingress-шлюзы.

Что такое Netmaker и чем он отличается от обычного WireGuard

Обычный WireGuard — это протокол и утилита wg-quick, которые устанавливают туннель по конфигу, написанному вручную. Топология в такой схеме статична: если вы хотите, чтобы узел A напрямую общался с узлами B, C и D, придётся прописать три блока [Peer] на узле A и по одному — на каждом из остальных. При десяти узлах это уже полсотни строк конфигов, которые нужно синхронно обновлять при любом изменении.

Netmaker добавляет поверх WireGuard уровень оркестрации:

• сервер Netmaker хранит состояние сети — список узлов, их ключи, IP-адреса и правила доступа — и отдаёт агентам актуальные конфиги;
• агент netclient ставится на каждый узел, поднимает интерфейс WireGuard и периодически синхронизируется с сервером;
• веб-панель показывает топологию сети, состояние узлов и позволяет управлять пирами без единой команды в терминале;
• mesh-топология строится автоматически: каждый узел получает пиров-соседей и держит с ними прямые туннели, а не звезду через центральный сервер.

Ключевое отличие от классического WireGuard-хаба в том, что сервер Netmaker — не обязательно точка, через которую идёт весь трафик. Он управляет сетью, но данные между узлами по умолчанию ходят напрямую, peer-to-peer. Это ближе к идеологии Tailscale или ZeroTier, но целиком на вашей инфраструктуре, без привязки к чужому облаку.

Смысл это имеет там, где WireGuard-конфигов становится много: три сервера в разных локациях и десяток удалённых сотрудников с доступом к внутренним ресурсам — уже повод не пересобирать конфиги вручную при каждом изменении. Узел добавляется через панель или CLI, и сеть перестраивается сама.

Требования и подготовка сервера

Netmaker разворачивается через Docker Compose и требует немного ресурсов для управляющего сервера, но с оговорками по сети. Минимум для контроллера — 1 vCPU, 2 ГБ RAM и белый статический IP; для реальной нагрузки в 15-20 узлов комфортнее взять 2 vCPU и 4 ГБ RAM.

Важные условия по сети:

• сервер должен иметь публичный IP без NAT — иначе узлы не смогут до него достучаться;
• домен, направленный на IP сервера, — Netmaker использует поддомены для API, панели и брокера сообщений (MQTT);
• открытые порты: 443/tcp (панель и API через reverse proxy), 51821-51830/udp (WireGuard-интерфейсы сети по умолчанию), 8883/tcp (MQTT для связи агентов с сервером).

Поставьте Docker и Docker Compose, если их ещё нет:

apt update && apt install -y docker.io docker-compose-plugin
systemctl enable --now docker

Если Docker уже настроен, этот шаг можно пропустить — подробности установки с нуля разобраны в статье про установку Docker Compose для продакшена.

Заранее направьте DNS-записи на IP сервера: как минимум netmaker.example.com (панель), api.netmaker.example.com (API), broker.netmaker.example.com (MQTT). Замените example.com на свой домен во всех примерах ниже.

Устанавливаем Netmaker и создаём первую сеть

Проще всего поднять стек официальным установочным скриптом — он генерирует docker-compose.yml, конфиг Caddy как reverse proxy и запрашивает нужные переменные интерактивно:

wget -qO netmaker.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh
chmod +x netmaker.sh
./netmaker.sh

Скрипт спросит домен, email для TLS-сертификата (Let's Encrypt через Caddy) и предложит установить дополнительные модули — например, панель мониторинга. Для базовой установки достаточно указать домен и подтвердить установку панели управления.

Если хотите контролировать процесс сами, разверните стек вручную. Создайте docker-compose.yml:

services:
  netmaker:
    image: gravitl/netmaker:v0.24.0
    restart: unless-stopped
    network_mode: host
    environment:
      SERVER_NAME: "netmaker.example.com"
      SERVER_HOST: "203.0.113.10"
      BROKER_ENDPOINT: "wss://broker.netmaker.example.com"
      MQ_HOST: "mq"
      API_PORT: "8081"
      MASTER_KEY: "замените-на-длинный-случайный-ключ"
      DNS_MODE: "off"
      DISPLAY_KEYS: "on"
    volumes:
      - netmaker-data:/root/data
      - /etc/netmaker:/etc/netmaker

  mq:
    image: eclipse-mosquitto:2.0
    restart: unless-stopped
    network_mode: host
    volumes:
      - mosquitto-data:/mosquitto/data
      - /etc/netmaker/mosquitto.conf:/mosquitto/config/mosquitto.conf

  netmaker-ui:
    image: gravitl/netmaker-ui:v0.24.0
    restart: unless-stopped
    environment:
      BACKEND_URL: "https://api.netmaker.example.com"
    ports:
      - "8082:80"

volumes:
  netmaker-data:
  mosquitto-data:

MASTER_KEY — главный секрет установки: он нужен для первого входа в панель и генерации API-токенов, сгенерируйте его командой openssl rand -base64 32 и сохраните отдельно. network_mode: host для контейнера netmaker обязателен — он поднимает сетевые интерфейсы WireGuard, а это требует прямого доступа к сетевому стеку хоста, что невозможно из изолированной bridge-сети Docker.

Перед этим стеком нужен reverse proxy (Caddy или Nginx) с TLS-терминацией на 443 порт и проксированием на 8081 (API) и 8082 (UI), с корректными заголовками для WebSocket — панель и MQTT-брокер держат постоянные соединения.

Запустите стек:

docker compose up -d
docker compose ps

Все три контейнера должны быть в статусе Up. Проверьте логи, если что-то не поднялось:

docker compose logs netmaker --tail=50

Откройте https://netmaker.example.com в браузере. При первом входе панель попросит MASTER_KEY и предложит создать учётную запись администратора — email и пароль сохраняются в базе Netmaker и дальше используются для входа.

Дальше создайте сеть (network) — это изолированное адресное пространство для группы узлов:

1. В панели откройте Networks → Create Network.
2. Задайте имя сети, например office-mesh.
3. Укажите диапазон адресов — 10.100.0.0/24 подойдёт для сети на 200+ узлов.
4. Опционально включите Default ACL — по умолчанию все узлы видят друг друга, но это можно ограничить позже через матрицу доступа.

Одна установка Netmaker может держать несколько независимых сетей одновременно — например, отдельную для продакшен-серверов и отдельную для удалённых рабочих мест, без пересечения адресных пространств и без видимости друг друга.

Добавляем узлы через netclient

На каждом узле, который должен войти в mesh, ставится агент netclient. Для Ubuntu/Debian:

curl -sfL https://raw.githubusercontent.com/gravitl/netclient/master/scripts/nm-quick-client.sh | bash -s -- -s netmaker.example.com -n office-mesh -k <ENROLLMENT_KEY>

ENROLLMENT_KEY — ключ регистрации, который генерируется в панели: Networks → office-mesh → Access Keys → Create Access Key. Ключ можно ограничить по числу использований и сроку действия — удобно, если раздаёте доступ временным подрядчикам.

Ручная установка без one-liner делается так:

wget -O netclient https://github.com/gravitl/netclient/releases/latest/download/netclient-linux-amd64
chmod +x netclient
mv netclient /usr/local/bin/
netclient join -t <TOKEN>

Токен -t тоже берётся из панели при создании ключа доступа — он включает в себя адрес сервера и права на подключение к конкретной сети.

После присоединения узел появляется в панели во вкладке Nodes со своим внутренним IP из подсети 10.100.0.0/24, статусом соединения и временем последней синхронизации. Проверить туннель на самом узле можно привычной командой:

wg show netmaker

Netmaker создаёт интерфейс с именем сети (или netmaker в старых версиях), а не wg0 — это позволяет держать несколько независимых WireGuard-интерфейсов на одном узле, если он состоит в нескольких сетях Netmaker одновременно.

Добавьте так три-четыре узла в разных локациях, и панель покажет граф mesh-сети: линии между узлами — это активные WireGuard-туннели, которые Netmaker выстроил автоматически. При добавлении нового узла остальным не нужно ничего перенастраивать — сервер сам разошлёт обновлённые конфиги.

Egress и ingress: выход наружу и вход для внешних клиентов

По умолчанию узлы mesh видят только друг друга в пределах адресного пространства сети. Для двух других сценариев — доступ к внешней подсети и доступ для устройств без агента — у Netmaker есть два типа шлюзов.

Egress-узел открывает участникам mesh доступ к внешней сети за одним из узлов — например, к локальной сети офиса. В панели: Nodes → выбрать узел → Create Egress Gateway, укажите диапазон внешней сети, например 192.168.1.0/24. Netmaker сам добавит правила iptables для форвардинга и NAT, а остальным узлам — маршрут через этот шлюз. Проверьте, что форвардинг на узле включён:

sysctl net.ipv4.ip_forward
# если 0 — включить вручную
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf && sysctl -p

Это типичная схема для подключения удалённых сотрудников к внутренней сети офиса или дата-центра без второго VPN-сервиса.

Ingress-узел решает обратную задачу — даёт доступ в mesh устройствам, где netclient не поставить (телефон гостя, IoT, чужой ноутбук). Он работает как классический WireGuard-сервер и настраивается там же: Nodes → выбрать узел → Create Ingress Gateway, а затем в разделе External Clients создаются клиентские профили — панель сгенерирует конфиг и QR-код, аналогичный обычному клиенту WireGuard из статьи про установку WireGuard на VPS. Разница в том, что такой клиент подключается к одному узлу-шлюзу, но через него получает доступ ко всей mesh-сети.

Мониторинг, обновление и обслуживание

Панель показывает базовые метрики: последнюю синхронизацию узла, объём трафика через WireGuard-интерфейс и статус (online/offline). Для более серьёзного мониторинга Netmaker поддерживает интеграцию с Prometheus — метрики отдаются на отдельном порту API-контейнера, если включена опция при установке.

Обновление стека — стандартная процедура Docker Compose:

docker compose pull
docker compose up -d

Перед обновлением на минорную или мажорную версию стоит свериться с release notes на GitHub — Netmaker развивается быстро, и между версиями иногда меняется формат данных в базе, что требует миграции. Бэкапьте том netmaker-data перед обновлением — там хранится вся топология сети:

docker run --rm -v netmaker-data:/data -v $(pwd):/backup alpine tar czf /backup/netmaker-backup.tar.gz /data

Если узел выпал из сети (статус offline дольше нескольких минут при живом сервере), первым делом проверьте на самом узле, жив ли процесс netclient:

systemctl status netclient
journalctl -u netclient -n 50

Частая причина обрыва — узел сменил публичный IP (динамический адрес у домашнего провайдера) и не смог обновить эндпоинт вовремя; netclient должен подхватить смену автоматически при следующей синхронизации, но если этого не произошло, поможет netclient pull вручную на узле.

Частые вопросы