Почему NetBox не даёт подключить несколько радиоклиентов через Wireless Link и когда нужен Wireless LAN

Если в NetBox не получается прицепить к одному радиоинтерфейсу второго клиента через Wireless Link — это не баг: модель рассчитана строго на связь двух сторон, A и B. Для точки доступа с несколькими клиентами и радиомостов 1-ко-многим нужна другая модель — WirelessLAN. Разбираю на уровне полей и API, как я пересобрал схему клиенту, который записал Wi-Fi как пачку WirelessLink.

WirelessLink в NetBox — это не «Wi-Fi для нескольких устройств»

Регулярно вижу одну и ту же ошибку у админов, которые сами заводят NetBox без методички: точку доступа с десятком клиентов пытаются описать через Wireless Link, создавая по одной связи на каждого клиента. Через веб-форму это не пройдёт: интерфейс, у которого уже есть связь, в списке выбора неактивен. Но через REST API или CSV-импорт — пройдёт: явной проверки «интерфейс уже занят» в самой модели WirelessLink нет, и NetBox спокойно сохранит пять объектов с одним и тем же интерфейсом на стороне A. Но семантически это неправильно, и расплата приходит не сразу: когда точка доступа падает, вы физически не можете одним запросом достать список «всё, что было подключено к этой точке» — потому что связей пять, они не связаны друг с другом ничем, кроме совпадающего названия интерфейса на одной стороне.

WirelessLink в документации NetBox описан однозначно: это связь ровно между двумя беспроводными интерфейсами, точка-точка. Не «интерфейс и группа интерфейсов», не «интерфейс и сколько угодно клиентов» — именно пара. Если вы внедряете NetBox с нуля и заводите учёт сетевой и серверной инфраструктуры у себя в компании, этот нюанс стоит понять в первый же день — иначе через полгода придётся вручную пересобирать сотню объектов, как это было у клиента из кейса ниже.

Путаница обычно идёт от слова «link» — по-русски «связь», и кажется логичным описывать им любое радиосоединение, хоть к одному устройству, хоть к десяти. Но в модели данных NetBox есть вторая, отдельная сущность именно для сетей с множественным доступом — WirelessLAN. Она не про «связь двух точек», а про сегмент сети с общим SSID, к которому подключается сколько угодно интерфейсов. Дальше — как это устроено на уровне полей и REST API, без гадания по UI.

Как устроена модель WirelessLink: сторона A, сторона B и ничего третьего

В коде NetBox (netbox/wireless/api/serializers_/wirelesslinks.py) сериализатор WirelessLink отдаёт ровно два поля под интерфейсы — interface_a и interface_b, оба обязательные, оба принимают один интерфейс с типом IEEE 802.11 или аналогичным беспроводным. Рядом — status со значениями connected, planned, decommissioning, опциональный ssid (да, у линка тоже может быть SSID — просто для документирования, а не для множественного подключения), distance с единицей измерения distance_unit, и стандартный набор auth_type/auth_cipher/auth_psk для WPA Personal, WPA Enterprise, WEP или Open.

Важнее другое: на стороне интерфейса (модель Interface в netbox/dcim/models/device_components.py) поле wireless_link — это ForeignKey на WirelessLink, не ManyToMany. У одного интерфейса в один момент времени может быть только одна ссылка на WirelessLink. Именно поэтому «прицепить второго клиента» через WirelessLink не выйдет так, как ожидает админ. В веб-форме занятый интерфейс просто нельзя выбрать — он помечен как occupied. А если создать вторую связь через API, сработает сигнал сохранения: он перезапишет wireless_link на интерфейсе стороны A ссылкой на новую связь. Первая связь останется в базе, но интерфейс про неё «забудет» — трассировка и карточка порта будут показывать только последнего клиента. Я разбирал такие базы: снаружи всё выглядит сохранённым, а на деле данные молча противоречат друг другу.

Создать связь через REST API можно так — обратите внимание на endpoint /api/wireless/wireless-links/, он подтверждён в netbox/wireless/api/urls.py:

curl -s -X POST https://netbox.example.com/api/wireless/wireless-links/ \
  -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "interface_a": 431,
    "interface_b": 968,
    "status": "connected",
    "ssid": "RG-BRIDGE-01",
    "auth_type": "wpa-personal",
    "auth_cipher": "aes",
    "distance": 180,
    "distance_unit": "m"
  }'

Это ровно тот случай, для которого модель создавалась: радиомост между двумя точками — офис и склад, две антенны, два интерфейса, одна связь. Как только за одним из интерфейсов оказывается не одна точка, а несколько устройств, WirelessLink перестаёт описывать реальность, и нужен следующий раздел.

WirelessLAN: сегмент с общим SSID и сколько угодно клиентов

WirelessLAN в документации NetBox описан как «многодоступная сеть, разделяемая несколькими беспроводными клиентами, идентифицируемая общим SSID» — это прямая противоположность точке-точке. У объекта есть поле ssid, опциональная привязка group к WirelessLANGroup, status (active, reserved, disabled, deprecated), те же поля аутентификации auth_type/auth_cipher/auth_psk, и поле scope — можно привязать сеть к региону, площадке, группе площадок или локации.

Главное отличие на уровне интерфейсов: у модели Interface для WirelessLAN используется не ForeignKey, а ManyToManyField — поле wireless_lans. Значит, к одной WirelessLAN может быть привязано произвольное число интерфейсов: точка доступа и все её клиенты, или несколько точек доступа с одним SSID в разных кабинетах — типичный roaming-сценарий. И тот же интерфейс может состоять сразу в нескольких WirelessLAN одновременно, если оборудование раздаёт несколько SSID.

Создание сети и привязка интерфейсов через API — два отдельных запроса, потому что владение связью здесь на стороне интерфейса:

curl -s -X POST https://netbox.example.com/api/wireless/wireless-lans/ \
  -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ssid": "RG-MEET-WIFI",
    "group": 3,
    "vlan": 112,
    "status": "active",
    "auth_type": "wpa-enterprise",
    "auth_cipher": "aes"
  }'

curl -s -X PATCH https://netbox.example.com/api/dcim/interfaces/2214/ \
  -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"wireless_lans": [14]}'

Второй вызов можно повторить для каждой точки доступа и каждого клиентского интерфейса, которые входят в этот SSID, — вся группа окажется в одном объекте, и запрос «кто сидит на этой сети» станет одним фильтром, а не ручным перебором пяти WirelessLink. Если у вас в офисе уже есть VLAN-сегментация по отделам, поле vlan у WirelessLAN — это прямое продолжение той же схемы в эфир: переговорка получает свой VLAN, гостевой Wi-Fi — свой, и оба видно в NetBox как мост между проводным и беспроводным сегментом.

WirelessLANGroup и роль антенны: организация SSID, а не связей

WirelessLANGroup — это папка для WirelessLAN, не более того: группы можно вкладывать друг в друга произвольно глубоко (parent — ссылка сама на себя), но конкретная WirelessLAN состоит ровно в одной группе, никакого множественного членства. У меня это обычно одна группа на площадку или на функцию сети: «Офис — гостевая», «Офис — корпоративная», «Склад — служебная». Группа не участвует в маршрутизации трафика и не ограничивает, какие интерфейсы могут присоединиться к сети внутри неё — это чисто организационная сущность для фильтров и отчётов.

Отдельно на уровне самого интерфейса, а не WirelessLAN или WirelessLink, есть поле rf_role (в UI — «Wireless role») со значениями ap (точка доступа) и station (клиент). Оно не связано напрямую ни с одной из моделей выше, но именно оно объясняет, почему точка доступа и клиент — не равноправные стороны: на интерфейсе точки доступа вы ставите rf_role=ap, на клиентских — station, и уже поверх этого решаете, через WirelessLink их соединять (если клиент один) или через WirelessLAN (если клиентов несколько или запланирован roaming между точками).

Если в компании авторизация Wi-Fi идёт не по общему PSK, а по логину сотрудника через RADIUS — это WPA Enterprise на уровне auth_type, а сама проверка личности и допуск в сеть чаще всего завязаны на контроль доступа по 802.1X: NetBox тут документирует только параметры SSID, а не логику аутентификации, но связка «WirelessLAN → VLAN → политика 802.1X» — это ровно тот путь, который стоит держать согласованным между схемой сети и NetBox.

WirelessLink или WirelessLAN: таблица сравнения и как решить за 30 секунд

Свожу разницу в одну таблицу — она закрывает 90 % вопросов, которые мне присылают после чтения документации NetBox по диагонали:

Простое правило, которым пользуюсь сам: если на одном конце связи физически ровно одно устройство — берите WirelessLink. Если на конце связи может оказаться два, десять или «сколько угодно» устройств одновременно, или вы заранее знаете, что клиентов будет больше одного (Wi-Fi-точка для переговорной, мост 1-ко-многим на несколько филиалов от одной мачты) — сразу заводите WirelessLAN и привязывайте к ней все причастные интерфейсы. Передумать и переехать с одной модели на другую в NetBox можно, но это ручная пересборка объектов, а не смена одного поля, — дешевле сразу выбрать верно.

Кейс: рекрутинговая компания «РекрутГавань», 26 рабочих мест

«РекрутГавань» — рекрутинговое агентство на 26 рабочих мест, офис в бизнес-центре плюс отдельный склад документов и архива в соседнем здании, метров 180 по прямой. Между офисом и складом — радиомост на паре направленных антенн, никакого кабеля тянуть не пришлось. Внутри офиса — три точки доступа Wi-Fi с одним корпоративным SSID для четырёх переговорных комнат и общего опен-спейса, плюс отдельная гостевая сеть для клиентов, которые приходят на собеседования.

Когда я забирал у них NetBox на сопровождение, увидел ровно ту путаницу, которую описал в начале статьи: администратор до меня завёл радиомост офис↔склад как WirelessLink — и это было правильно, единственный случай в базе, где модель подошла один в один. А вот три точки доступа с корпоративным SSID он тоже описал через WirelessLink — присвоив «главной» антенне в опен-спейсе роль стороны A и загрузив CSV-импортом три отдельных объекта WirelessLink с тремя разными сторонами B, по одной на каждую переговорку. Веб-форма такого бы не позволила, импорт — позволил, и в карточке «главного» интерфейса осталась ссылка только на последнюю из трёх связей. Формально в базе всё сохранилось, но при отказе одной точки доступа не было способа быстро понять, какие клиенты и какая переговорная затронуты — потому что «клиентов» модель вообще не знала, только физические интерфейсы точек.

Пересобрал так: радиомост офис↔склад оставил как есть — WirelessLink, status: connected, distance: 180m. Для Wi-Fi завёл одну WirelessLAN с ssid: RG-CORP-WIFI, группу Офис — корпоративная, привязку к vlan: 112 (тот же VLAN, что и у проводных портов в переговорных — у них уже была рабочая VLAN-сегментация по отделам). К этой WirelessLAN через wireless_lans привязал интерфейсы всех трёх точек доступа с rf_role: ap. Отдельно завёл вторую WirelessLAN RG-GUEST-WIFI на изолированный vlan: 130 без доступа во внутреннюю сеть — для гостевого Wi-Fi. Теперь при отказе точки в переговорной №2 в NetBox один фильтр по интерфейсу показывает, что затронута ровно одна WirelessLAN и какая переговорная сидит на её VLAN — раньше на это уходило минут двадцать созвона с админом на месте, который вспоминал, что где стоит.

Заодно эта же карта стала основой для мониторинга: точки доступа и коммутатор склада добавили в буферизованный Zabbix-proxy для филиала, потому что склад — отдельная площадка за радиомостом, и при обрыве моста данные с неё должны копиться локально, а не теряться, и алерт по падению точки теперь сразу указывает на конкретный VLAN и конкретную переговорную, а не просто «Wi-Fi где-то в офисе не работает».

Типичные ошибки при моделировании беспроводных связей и как их не повторить

Самая частая ошибка уже описана выше — WirelessLink вместо WirelessLAN для сети с несколькими клиентами. Вторая по частоте — обратная: заводят WirelessLAN для банального радиомоста точка-точка между двумя офисами, потому что «так проще было завести один раз через скрипт». Работает, но теряется поле distance (его нет у WirelessLAN) и явное разделение сторон A/Б — в отчётах такая связь выглядит как обычная Wi-Fi-сеть из двух устройств, и через полгода никто не помнит, что это вообще-то направленный радиомост с зоной Френеля, которую нельзя перекрывать новой стройкой.

Третья ошибка — забыть привязать vlan у WirelessLAN. Без этого поля NetBox честно хранит SSID и список подключённых интерфейсов, но не показывает мост между эфиром и проводной сетью, и при аудите VLAN, например настраивая сегментацию сети офиса с нуля, беспроводные сегменты придётся сверять руками. Четвёртая — не выставлять group для WirelessLAN, когда сетей больше двух-трёх: без группировки список сетей на крупной площадке превращается в тот же нечитаемый список Excel, от которого вы уходили, когда заводили NetBox.

Практический чек-лист, который я применяю на новом объекте: если на одном конце радиосвязи всегда ровно одно устройство — WirelessLink с указанием distance. Если клиентов больше одного или их число может вырасти — WirelessLAN с обязательным vlan и group. Каждой точке доступа — rf_role: ap, каждому клиенту — rf_role: station. И отдельно проверяю на старте: если в базе уже есть WirelessLink, у которого сторона A совпадает у нескольких объектов, — это стопроцентный признак той самой ошибки, которую я разобрал в кейсе «РекрутГавань».

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