Общая Частная Сеть (SPN)

Концепция

Общая частная сеть (ОЧС/SPN) — это защищённая инфраструктура для организации единого пространства взаимодействия между серверами, сервисами и разработчиками. Она реализуется на основе VPN-технологий, что обеспечивает безопасный и удобный обмен данными, а также централизованное управление доступом.

Основные принципы

• Безопасность: вся передача данных происходит в зашифрованном канале.
• Простота подключения: сотрудники и сервисы подключаются через единый доступ с учётом политик компании.
• Гибкость управления: поддержка смены шлюзов, подсетей и DNS.
• Интеграция: возможность связывать управление сотрудниками и нодами с существующими внутренними системами.

Преимущества

• Общая карта сети, включающая ноды, шлюзы и подсети. Позволяет видеть текущее состояние инфраструктуры и управлять параметрами подключения.

• Визуализированная карта сети с указанием активных соединений, статуса узлов и маршрутов. Удобна для мониторинга работы и быстрого поиска проблем.

• Модуль управления сетью через SPN API, который позволяет интегрироваться с внутренними системами управления персоналом и инфраструктурой.

• Переключить ноду-шлюз (например, для балансировки или отказоустойчивости), перенастраивать подсеть.

DNS

Система внутренних DNS-записей, доступных только сотрудникам при подключении к частной сети. Используется для:

• удобного доступа к сервисам и нодам по именам
• настройки единых правил маршрутизации и разрешения имён для сотрудников (разработчиков)

Клиент SPN

Клиент SPN (github.com/cloudnetip/netip-spn) — это инструмент на базе WireGuard для подключения к Общей Частной Сети. Предоставляет CLI для macOS и Linux, а также нативное GUI-приложение для macOS.

Установка

macOS

Установка через Homebrew (рекомендуется):

# Добавить tap
brew tap cloudnetip/tap

# Установить только CLI
brew install cloudnetip-spn

# Установить GUI + CLI (рекомендуется)
brew install --cask cloudnetip-spn

# Обновление GUI + CLI
brew update && brew upgrade --cask --greedy cloudnetip-spn && brew link cloudnetip-spn

Cask устанавливает Cloudnetip SPN.app в /Applications и добавляет CLI netip-spn в PATH. Приложение подписано ad-hoc и работает без дополнительных запросов безопасности.

Linux

Сборка из исходников:

# Установить зависимости
sudo apt install wireguard-tools zenity   # Debian/Ubuntu
# или эквивалент для вашего дистрибутива

# Клонировать и собрать
git clone https://github.com/cloudnetip/netip-spn.git
cd netip-spn
make build && sudo make install

GUI доступен только для macOS. В Linux используйте CLI напрямую или создайте .desktop launcher.

Другие системы

Для Windows, Android, iOS и других платформ используйте официальный клиент WireGuard.

Скачайте ваш конфигурационный файл SPN с cloudnetip.com/app/shared и импортируйте его в приложение WireGuard:

1. Установите WireGuard для вашей платформы
2. Скачайте файл .conf с портала SPN
3. Импортируйте конфигурацию:
   • Windows: Нажмите "Import tunnel(s) from file"
   • Android/iOS: Отсканируйте QR-код или импортируйте файл
   • Другие: Следуйте инструкциям для вашей платформы

Использование CLI

Вход через браузер

Самый быстрый способ настроить клиент — авторизация в браузере. Используется OAuth 2.0 authorization-code flow с PKCE через loopback-редирект (RFC 7636 + RFC 8252):

# Открыть браузер, выбрать SPN, конфиг сохранится автоматически
netip-spn auth login

Что происходит:

1. CLI открывает браузер по адресу cloudnetip.com/app/shared/authorize.
2. В веб-интерфейсе вы выбираете, к какому SPN подключиться.
3. Конфиг записывается в ~/.cloudnetip/spn.conf (режим 600).

Постоянного токена авторизации нет: сам WireGuard-конфиг является учётными данными. Запустите auth login повторно, чтобы ротировать ключи или переключиться на другой SPN.

# Удалить сохранённый конфиг и развёрнутую копию wg-quick
netip-spn auth logout

Первоначальная настройка (ручной конфиг)

Если хочется обойтись без браузера, скачайте конфигурационный файл с cloudnetip.com/app/shared и установите его вручную:

# Установить конфиг через file picker
netip-spn config

# Или указать путь напрямую
netip-spn config ~/Downloads/spn.conf

Конфиг проверяется и сохраняется в ~/.cloudnetip/spn.conf (режим 600).

Подключение к SPN

# Поднять туннель (требуется sudo)
netip-spn connect

Команда запросит пароль sudo для настройки интерфейса WireGuard.

Проверка статуса подключения

# Проверить состояние туннеля (sudo не требуется)
netip-spn status

Отключение

# Опустить туннель
netip-spn disconnect

Использование GUI (только macOS)

Приложение в menubar предоставляет ту же функциональность, что и CLI, с нативным интерфейсом macOS.

Возможности

• Иконка в Menubar: Показывает статус подключения
• Sign In / Sign Out: Авторизация через браузер с автоматическим сохранением конфига SPN (тот же PKCE-flow, что и в CLI)
• Быстрые действия: Подключение/Отключение одним кликом
• Автообновление статуса: Обновление состояния туннеля в реальном времени
• Управление конфигом: Загрузка WireGuard конфигов через нативный file picker (альтернатива Sign In)
• Интеграция с Terminal: Действия Connect/Disconnect открывают Terminal для ввода пароля sudo

Первоначальная настройка

1. Запустите Cloudnetip SPN.app из Applications
2. Кликните на иконку в menubar
3. Выберите Sign In — откроется браузер с порталом SPN, вы выбираете аккаунт, и конфиг автоматически записывается в ~/.cloudnetip/spn.conf. (Альтернатива: Load Config для импорта существующего WireGuard-файла.)
4. Нажмите Connect (откроется окно Terminal для ввода пароля sudo)
5. Введите пароль для поднятия туннеля

Чтобы удалить сохранённый конфиг, выберите Sign Out в menubar.

Конфигурационные файлы

Путь	Назначение
~/.cloudnetip/spn.conf	Ваш сохранённый WireGuard конфиг (режим 600)
~/.cloudnetip/wg-netip.conf	Развёрнутая копия, используемая wg-quick
/var/run/wireguard/wg-netip.name	Создаётся wg-quick когда туннель поднят

Клиент использует стандартный формат конфигурации WireGuard. Пример:

[Interface]
PrivateKey = ваш-приватный-ключ
Address = 10.11.0.2/24
DNS = 10.11.0.1

[Peer]
PublicKey = публичный-ключ-сервера
Endpoint = internal.example.ltd:51820
AllowedIPs = 10.11.0.0/16
PersistentKeepalive = 25

Каждый connect повторно разворачивает сохранённый конфиг из ~/.cloudnetip/spn.conf, так что вы можете редактировать его напрямую без повторного запуска config.

Устранение неполадок

Проблемы с подключением

# Проверить статус интерфейса WireGuard
sudo wg show

# Проверить валидность конфига
cat ~/.cloudnetip/spn.conf

# Проверить системные логи
sudo dmesg | grep wireguard

Проблемы с правами доступа

Команды connect и disconnect требуют sudo для настройки сетевых интерфейсов. Если возникают ошибки прав доступа:

# Убедитесь, что WireGuard tools установлены
which wg-quick

# На macOS
brew install wireguard-tools

# На Linux
sudo apt install wireguard-tools

Конфиг не найден

Если вы видите ошибки "config not found":

# Проверить существование конфига
ls -la ~/.cloudnetip/spn.conf

# Пересохранить ваш конфиг
netip-spn config ~/путь/к/вашему/spn.conf

Аварийная остановка подключения

Если netip-spn disconnect зависает или процесс wireguard-go остался висеть после сбоя, текущее подключение можно остановить принудительно: убить процесс и удалить файл-маркер, оставшийся от wg-quick:

sudo ps aux | grep -i '[w]ireguard-go' | awk '{print $2}' | xargs sudo kill -9 \
  && sudo rm /var/run/wireguard/wg-netip.name

После этого можно повторно выполнить netip-spn connect.