Русский

English

Русский

English

Тема

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

Концепция ​

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

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

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

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

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

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

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

DNS ​

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

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

Клиент SPN ​

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

Установка ​

macOS ​

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

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

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

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

Cask устанавливает Cloudnetip SPN.app в /Applications, а CLI netip-spn устанавливается через Homebrew Formula.

GUI для macOS содержит собственный зафиксированный WireGuard runtime (wg + wireguard-go). При первом подключении через GUI или после изменения WireGuard runtime в новой версии macOS запросит пароль администратора и установит защищённую root-owned копию в /Library/PrivilegedHelperTools/cloudnetip-spn/. После этого обычные Connect/Disconnect не требуют пароль до следующего изменения встроенного WireGuard runtime.

CLI работает независимо от GUI runtime и использует wg-quick из wireguard-tools. При установке CLI через Homebrew эта зависимость устанавливается автоматически.

Для обновления откройте About Cloudnetip SPN. Приложение в фоне проверит версию в Homebrew и покажет кнопку Update to new version X.Y.Z, если версия GUI или CLI отличается от опубликованной в Homebrew. Обновление выполняется через Homebrew, после чего GUI перезапускается автоматически.

Также можно обновиться вручную:

bash
brew update
brew reinstall --formula cloudnetip/tap/cloudnetip-spn
brew reinstall --cask --force cloudnetip/tap/cloudnetip-spn

Linux ​

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

bash
# Установить зависимости
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):

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

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

  1. CLI открывает браузер по адресу cloudnetip.com/app/shared/authorize.
  2. В веб-интерфейсе вы выбираете, к какому SPN подключиться.
  3. WireGuard-конфиг сохраняется:
    • macOS: /Library/Application Support/Cloudnetip SPN/spn.conf (root:wheel, режим 600). При установке или замене защищённого конфига macOS запросит пароль администратора.
    • Linux: ~/.cloudnetip/spn.conf (режим 600).

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

bash
# Удалить сохранённый конфиг
netip-spn auth logout

На macOS для удаления защищённого конфига потребуется пароль администратора.

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

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

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

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

Конфиг проверяется и сохраняется по указанному выше пути для текущей платформы. На macOS установленная копия принадлежит root и не может быть заменена обычным пользовательским процессом.

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

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

CLI использует wg-quick и запрашивает пароль sudo для настройки интерфейса WireGuard. На macOS используется wireguard-tools из Homebrew; CLI не использует встроенный WireGuard runtime GUI.

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

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

Отключение ​

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

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

Приложение в menubar использует собственный встроенный WireGuard runtime и минимальный root-owned helper. Для GUI подключений Homebrew wg-quick не используется.

Возможности ​

  • Иконка в Menubar: Показывает статус подключения.
  • Скорость в Menubar: Опциональный двухстрочный вывод upload/download через Show stats in bar.
  • Sign In / Sign Out: Авторизация через браузер и удаление сохранённого SPN-конфига.
  • Управление конфигом: Импорт существующего WireGuard-конфига через нативный file picker.
  • Connect / Disconnect: Работают через защищённый встроенный WireGuard runtime.
  • Защищённый конфиг: На macOS активный SPN-конфиг принадлежит root и не может быть заменён обычным пользователем.
  • Connect/Disconnect без пароля: Пароль администратора нужен только для установки/обновления privileged WireGuard runtime, а не при каждом подключении.
  • Show Logs: Открывает лог WireGuard для GUI.
  • Встроенная проверка обновлений: About Cloudnetip SPN асинхронно проверяет Homebrew и может обновить GUI и CLI.

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

  1. Запустите Cloudnetip SPN.app из Applications.
  2. Кликните на иконку в menubar.
  3. Выберите Sign In или Choose config. macOS запросит пароль администратора, чтобы установить конфиг в /Library/Application Support/Cloudnetip SPN/spn.conf.
  4. Нажмите Connect. При первом подключении macOS один раз запросит пароль администратора для установки встроенного WireGuard runtime и минимального passwordless helper.
  5. Последующие Connect и Disconnect не запрашивают пароль, пока встроенный WireGuard runtime не изменится.

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

macOS ​

ПутьНазначение
/Library/Application Support/Cloudnetip SPN/spn.confАктивный WireGuard-конфиг SPN (root:wheel, режим 600)
/Library/PrivilegedHelperTools/cloudnetip-spn/Root-owned helper GUI, wg, wireguard-go и runtime.version
/etc/sudoers.d/netip-spnУзкие правила NOPASSWD только для GUI-команд check, up и down
~/Library/Logs/Cloudnetip SPN/wireguard.logЛог подключений GUI
~/Library/Logs/Cloudnetip SPN/update.logЛог обновления через Homebrew
/var/run/netip-spn/Временное root-owned состояние активного туннеля
/var/run/wireguard/wg-netip.nameМаркер текущего WireGuard-интерфейса utun

Linux ​

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

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

ini
[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

На macOS для замены защищённого конфига используйте Sign In, Choose config, netip-spn auth login или netip-spn config. На Linux сохранённый ~/.cloudnetip/spn.conf также можно редактировать напрямую при отключённом туннеле.

Удаление ​

macOS ​

Для полного удаления сначала отключите туннель и закройте приложение в menubar. Затем, пока netip-spn ещё установлен, выполните:

bash
# Удалить защищённый конфиг SPN
netip-spn auth logout

# Удалить passwordless sudo-правило и root-owned WireGuard runtime/helper
netip-spn sudoers remove

# Удалить GUI и CLI
brew uninstall --zap --cask cloudnetip-spn
brew uninstall cloudnetip-spn

# Удалить пользовательские логи
rm -rf "$HOME/Library/Logs/Cloudnetip SPN"

# Удалить пустую защищённую директорию конфига, если она осталась
sudo rmdir "/Library/Application Support/Cloudnetip SPN" 2>/dev/null || true

netip-spn sudoers remove при необходимости останавливает туннель GUI и удаляет /Library/PrivilegedHelperTools/cloudnetip-spn/ вместе с /etc/sudoers.d/netip-spn.

Если tap Cloudnetip больше не используется другими пакетами, его также можно удалить:

bash
brew untap cloudnetip/tap

Linux ​

Если CLI устанавливался через sudo make install:

bash
netip-spn disconnect
netip-spn auth logout
sudo rm -f /usr/local/bin/netip-spn
rm -rf "$HOME/.cloudnetip"

Удаляйте wireguard-tools отдельно только если он больше не нужен другим WireGuard-подключениям.

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

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

Для туннеля, поднятого GUI на macOS:

bash
# Проверить WireGuard через встроенный root-owned wg
sudo "/Library/PrivilegedHelperTools/cloudnetip-spn/wg" show

# Посмотреть защищённый конфиг
sudo cat "/Library/Application Support/Cloudnetip SPN/spn.conf"

# Смотреть лог GUI в реальном времени
tail -f "$HOME/Library/Logs/Cloudnetip SPN/wireguard.log"

Для подключений через CLI используйте системные/Homebrew WireGuard tools:

bash
sudo wg show
netip-spn status

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

GUI на macOS запрашивает пароль администратора, когда требуется установить/обновить privileged WireGuard runtime или установить/удалить защищённый конфиг. После настройки обычные Connect/Disconnect работают без пароля.

Проверить состояние GUI helper:

bash
netip-spn sudoers check

CLI по-прежнему требует wg-quick и sudo:

bash
# CLI на macOS
brew install wireguard-tools

# CLI на Debian/Ubuntu
sudo apt install wireguard-tools

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

Проверьте путь конфига для вашей платформы:

bash
# macOS
sudo ls -l "/Library/Application Support/Cloudnetip SPN/spn.conf"

# Linux
ls -l ~/.cloudnetip/spn.conf

Пересохранить конфиг:

bash
netip-spn config ~/путь/к/вашему/spn.conf

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

Используйте этот раздел только как аварийный способ восстановления.

Для подключения через GUI на macOS сначала попросите установленный privileged helper выполнить штатную очистку. Он удалит маршруты GUI, DNS-запись, runtime state и остановит интерфейс WireGuard:

bash
sudo "/Library/PrivilegedHelperTools/cloudnetip-spn/helper" _privileged down

Если GUI/helper аварийно завершился и DNS Cloudnetip остался зарегистрирован в системе, его можно удалить вручную:

bash
printf 'remove State:/Network/Service/cloudnetip-spn/DNS\nquit\n' \
  | sudo /usr/sbin/scutil

sudo /usr/bin/dscacheutil -flushcache
sudo /usr/bin/killall -HUP mDNSResponder

В самом крайнем случае, если завис именно встроенный процесс wireguard-go, завершите только экземпляр Cloudnetip:

bash
sudo pkill -f '/Library/PrivilegedHelperTools/cloudnetip-spn/wireguard-go utun'

Если helper не смог штатно выполнить очистку и пришлось завершать wireguard-go вручную, перезагрузите macOS перед повторным подключением. Жёсткое завершение процесса не может надёжно восстановить маршруты при повреждённом runtime state.

Для подключения через CLI сначала попробуйте опустить туннель напрямую по временному конфигу:

bash
sudo wg-quick down /var/run/netip-spn/wg-netip.conf

После очистки можно снова выполнить netip-spn connect.