Tudor Shandrov / Технические заметки
← Все заметки
Proxmox и виртуализация

Инвентаризация девяти узлов Proxmox VE в NetBox 4.7: DMI, MAC и сетевая топология

Практический кейс: read-only сбор оборудования и 362 интерфейсов девяти узлов Proxmox, сверка с NetBox 4.7, безопасное обогащение уже существующих устройств и повторный dry-run.

Статус: актуальноОпубликовано: 2026-10-19Обновлено: 2026-10-19

Проверено на: Proxmox VE · NetBox 4.7.3 · Python 3.13 · AlmaLinux 9 · Zabbix 7.0

Задача: не просто завести устройства, а проверить данные

В NetBox уже были заведены физические гипервизоры Proxmox VE. Следующим шагом стало получение фактического состояния оборудования и сетевых интерфейсов: DMI, серийных номеров, текущих MAC физических адаптеров и конфигурации Linux Bridge/VLAN. Цель — обогатить существующий DCIM и научиться проверять его на расхождения с реальной инфраструктурой.

Материал основан на проверенной эксплуатации кластера из девяти узлов в октябре 2026 года. Внутренние имена, домены, IP, site/role slugs и оборудование в командах заменены демонстрационными. Числовые результаты — агрегированные показатели выполненных проверок.

Исходники: greksw/netbox-inventory-toolkit. Это набор отдельных инструментов — не фоновый двусторонний синхронизатор NetBox и Proxmox.

01 / Архитектура

Proxmox cluster (9 hosts)
  ├─ pvesh GET: nodes, status, network
  ├─ local sysfs: DMI, NIC MAC
  └─ optional SSH to peers: DMI and NIC MAC
           │
           ▼
  private inventory v0.3 (0600)
           │
           ├─ audit topology and completeness
           ├─ read-only NetBox preview
           └─ guarded enrichment of existing DCIM objects
                         │
                         ▼
                 NetBox 4.7 / DCIM

Коллектор работает на одном узле Proxmox и использует pvesh для чтения данных всего кластера. Для DMI и MAC удалённых узлов предусмотрен отдельный opt-in SSH, только по ключам, с BatchMode=yes и StrictHostKeyChecking=yes. По умолчанию запись в NetBox отсутствует.

Сбор ориентирован на физические узлы. VM/CT, инвентаризация кабельных соединений и создание IPAM/VLAN-объектов этим коллектором не выполняются.

02 / Read-only сбор

На одном гипервизоре, в закрытом административном каталоге:

git clone https://github.com/greksw/netbox-inventory-toolkit.git
cd netbox-inventory-toolkit

# Начинаем с одного узла
python3 collectors/proxmox_inventory.py \
  --node "$(hostname -s)" \
  --cluster-label example-pve

# После настройки доверенного SSH ко всем узлам
python3 collectors/proxmox_inventory.py \
  --cluster-label example-pve \
  --dmi-ssh --mac-ssh \
  --output output/proxmox-inventory-v03.json

Первоначальную проверку можно выполнять без удалённого SSH; в этом случае аппаратные сведения удалённых узлов могут отсутствовать. Перед кластерным запуском важно отдельно убедиться, что SSH-ключи действительно предназначены для этого задания и host keys заранее проверены.

Файл инвентаризации сохраняется атомарно с правами 0600; каталог output/ исключён из Git. Даже read-only JSON содержит чувствительные данные: не публикуйте его в issue, gist или репозитории.

03 / Почему понадобился отдельный сбор MAC

Часть записей сетевой конфигурации из Proxmox не содержала MAC. Инструмент умеет читать /sys/class/net/*/address, но только для интерфейсов с физическим device в sysfs; на удалённых гипервизорах — через ограниченный SSH-запрос.

Важное различие: это текущий MAC интерфейса, а не гарантированно заводской адрес на наклейке адаптера. Значения не следует автоматически переносить на vmbr* и VLAN-подинтерфейсы.

Внутренняя проверка топологии сопоставляет ссылки на родительские VLAN-интерфейсы, bridge ports и bond slaves. Успешная топологическая проверка не доказывает работоспособность VLAN, физического кабеля или доступность сети — для этого нужны отдельные тесты.

04 / Проверенный результат

Показатель Получено
Узлы, собранные без ошибок 9/9
Сетевые интерфейсы всего 362
Физические сетевые интерфейсы с MAC 20
Серийные номера из DMI 7
Узлы без пригодного серийного номера 2
Ошибки топологических ссылок 0

Интерфейсы включают физические NIC, Linux bridges и VLAN-подинтерфейсы. Отсутствующие DMI-серийники не выдумываются и не заменяются фиктивными строками — соответствующие поля остаются пустыми.

Проверка целостности предусматривала не только счётчики, но и точное совпадение имён интерфейсов на каждом узле. Для дополнительного контроля применялся SHA-256 от отсортированного списка пар node|interface; значение хеша инфраструктуры публично не приводится.

05 / Сопоставление с NetBox, без повторного импорта

Для предварительного просмотра используется самостоятельный инструмент:

python3 netbox/preview.py \
  --inventory output/proxmox-inventory-v03.json \
  --output output/netbox-preview.json

В NetBox физические устройства и интерфейсы к этому моменту уже существовали, их не создавал данный скрипт. В отдельной административной процедуре аппаратные поля были добавлены к существующим объектам под защитой транзакции PostgreSQL. Перед изменениями была сделана резервная копия базы и проверено соответствие всех объектов.

В репозитории также есть netbox/enrich_existing.py: он работает внутри Django shell NetBox, по умолчанию делает dry-run, сверяет ожидаемые количества и в режиме записи может обновлять только пустые поля серийных номеров и основные MAC известных физических интерфейсов. Не создаёт устройства, виртуальные машины, интерфейсы, VLAN или IP-адреса. Возможность apply требует отдельного подтверждения и проверки бэкапа.

Обобщённый модуль не использовался для первоначальной записи — его проверили позже в production в режиме чтения. Это важная граница между вручную подтверждённым импортом и тестированием переиспользуемого кода.

Пример повторного запуска внутри NetBox на демонстрационной площадке:

runuser -u netbox -- /opt/netbox/venv/bin/python \
  /opt/netbox/netbox/manage.py shell -c \
  "from runpy import run_path; run_path('/secure/enrich_existing.py')['run'](
    '/secure/proxmox-inventory-v03.json',
    site_slug='example-office', role_slug='hypervisor',
    expected_devices=9, expected_interfaces=362,
    expected_serials=7, expected_macs=20
  )"

Итог проверенного повторного dry-run:

mode: DRY-RUN
verified_devices: 9
verified_interfaces: 362
serials_to_add: 0
macs_to_assign: 0
serials_matching: 7
macs_matching: 20

Нулевые изменения — нужный результат: NetBox уже содержит все доступные из этого источника аппаратные идентификаторы.

06 / Что стоит учесть в эксплуатации

Следующий логичный этап — регулярно сверять NetBox с действующим кластером. Он реализован отдельно: ежедневный Drift Audit через systemd и Zabbix.

Ссылки