Proxmox

Проброс USB-устройства в виртуальную машину Proxmox VE

Пошаговый проброс физического USB-устройства с узла Proxmox VE в виртуальную машину с проверкой идентификаторов, подключением и безопасным отключением.

USB passthrough позволяет передать физическое USB-устройство, подключённое к узлу Proxmox VE, непосредственно виртуальной машине.

Такой способ используют для:

  • аппаратных ключей;
  • USB-модемов;
  • ИБП;
  • адаптеров Zigbee и Z-Wave;
  • программаторов;
  • принтеров;
  • специализированного оборудования.

В этой инструкции рассматривается только проброс одного USB-устройства в одну виртуальную машину.

Подходит для: Proxmox VE 8 и 9
Уровень сложности: средний
Время выполнения: около 15 минут
Требуемый доступ: права управления VM и shell-доступ к узлу Proxmox VE

Важные ограничения

Перед настройкой учитывайте:

  • устройство сможет использовать только одна VM;
  • live migration такой VM обычно становится недоступна;
  • после переноса VM на другой узел устройства там может не быть;
  • USB-устройство должно стабильно определяться после перезагрузки;
  • физическое отключение устройства может нарушить работу приложения;
  • некоторые устройства меняют bus и port после переподключения.

Для кластерной VM USB passthrough создаёт зависимость от конкретного узла.

Что будет настроено

После выполнения инструкции можно будет:

  • найти USB-устройство на узле;
  • определить Vendor ID и Product ID;
  • проверить bus и port;
  • добавить устройство через веб-интерфейс;
  • добавить устройство через CLI;
  • проверить его внутри Linux-гостя;
  • выбрать привязку по порту или идентификатору;
  • безопасно отключить устройство.

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

Подключите USB-устройство к физическому порту сервера.

Проверьте события ядра:

dmesg --follow

Подключите устройство и найдите новые строки.

Остановите просмотр:

Ctrl+C

Последние события USB:

journalctl -k -n 100 --no-pager |
grep -i usb

Просмотр USB-устройств

На узле Proxmox VE:

lsusb

Пример:

Bus 002 Device 004: ID 1234:5678 Example USB Device

Здесь:

1234

— Vendor ID;

5678

— Product ID.

Полная пара:

1234:5678

Подробная информация

lsusb -v -d 1234:5678

Вывод может быть большим.

Кратко:

udevadm info   --query=property   --name=/dev/bus/usb/002/004

Замените bus и device фактическими значениями из lsusb.

Проверка дерева USB

lsusb -t

Пример:

/:  Bus 02.Port 1: Dev 1, Class=root_hub
    |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class

Физический путь в этом примере:

2-3

То есть:

  • bus 2;
  • port 3.

Vendor/Product ID и физический порт

Proxmox VE позволяет привязать устройство двумя основными способами.

По Vendor ID и Product ID

Пример:

1234:5678

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

  • устройство находится независимо от номера Device;
  • удобно, если подключён один экземпляр такой модели.

Недостаток:

  • если подключено несколько одинаковых устройств, выбор может быть неоднозначным.

По USB-порту

Пример:

2-3

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

  • можно различать одинаковые устройства;
  • VM получает устройство из конкретного физического порта.

Недостаток:

  • после перестановки кабеля привязка перестанет работать.

Проверка виртуальной машины

qm status VM_ID

Покажите конфигурацию:

qm config VM_ID

Проверьте существующие USB-устройства:

qm config VM_ID |
grep '^usb'

Создание резервной копии конфигурации

Сохраните конфигурацию VM:

qm config VM_ID   > /root/vm-VM_ID-config-before-usb.txt

Проверьте:

cat /root/vm-VM_ID-config-before-usb.txt

Нужно ли останавливать VM

Некоторые USB-устройства можно подключить к работающей VM, но для предсказуемой настройки лучше выполнить корректное завершение:

qm shutdown VM_ID

Проверьте:

qm status VM_ID

Ожидаемый результат:

status: stopped

Добавление через веб-интерфейс

Откройте:

VM → Hardware

Нажмите:

Add → USB Device

Выберите один из вариантов:

Use USB Vendor/Device ID
Use USB Port

Выберите найденное устройство.

Нажмите:

Add

USB 3

Если устройство должно работать через контроллер USB 3, включите:

Use USB3

Это особенно важно для устройств, которым требуется:

  • высокая скорость;
  • режим SuperSpeed;
  • совместимость с xHCI.

Для простых аппаратных ключей и адаптеров USB 2 обычно достаточно.

Добавление по Vendor/Product ID через CLI

qm set VM_ID   --usb0 host=1234:5678

Пример:

qm set 100   --usb0 host=1234:5678

Проверьте:

qm config 100 |
grep '^usb0'

Ожидаемая строка:

usb0: host=1234:5678

Добавление по физическому USB-порту

qm set VM_ID   --usb0 host=2-3

Проверьте:

qm config VM_ID |
grep '^usb0'

Добавление USB 3 через CLI

qm set VM_ID   --usb0 host=1234:5678,usb3=1

Проверьте конфигурацию:

qm config VM_ID |
grep '^usb0'

Несколько USB-устройств

Используйте последовательные номера:

usb0
usb1
usb2

Пример:

qm set VM_ID   --usb0 host=1234:5678

qm set VM_ID   --usb1 host=8765:4321

Проверьте:

qm config VM_ID |
grep '^usb'

Запуск VM

qm start VM_ID

Проверьте:

qm status VM_ID

Откройте консоль виртуальной машины.

Проверка внутри Linux-гостя

Установите usbutils, если пакет отсутствует:

sudo apt update
sudo apt install -y usbutils

Покажите устройства:

lsusb

В списке должна появиться та же пара:

1234:5678

Проверка событий ядра гостя

sudo journalctl -k -n 100 --no-pager |
grep -i usb

Либо:

dmesg |
grep -i usb

Проверка устройства в /dev

Конкретный путь зависит от класса устройства.

USB serial adapter

ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

USB storage

lsblk

HID

ls -l /dev/hidraw* 2>/dev/null

Принтер

ls -l /dev/usb/ 2>/dev/null

Проверка драйвера

Для USB serial:

udevadm info   --query=property   --name=/dev/ttyUSB0

Проверьте модуль:

lsmod |
grep -E 'usbserial|cp210x|ftdi|ch341'

Набор модулей зависит от устройства.

Права внутри гостевой системы

Проверьте владельца устройства:

ls -l /dev/ttyUSB0

Пример:

crw-rw---- 1 root dialout ...

Добавьте пользователя в нужную группу:

sudo usermod -aG dialout ADMIN_USER

После этого пользователь должен выйти из сессии и войти снова.

Не назначайте устройству права 777.

Постоянное имя устройства

Имя вида:

/dev/ttyUSB0

может измениться после перезагрузки.

Проверьте стабильные ссылки:

ls -l /dev/serial/by-id/ 2>/dev/null

Пример:

/dev/serial/by-id/usb-Example_Device-if00

В конфигурации приложения лучше использовать путь из:

/dev/serial/by-id/

Устройство занято узлом Proxmox

Иногда драйвер или служба на самом узле начинает использовать устройство.

Проверьте:

lsof /dev/DEVICE_PATH

Пример:

lsof /dev/ttyUSB0

Проверьте процессы:

fuser -v /dev/ttyUSB0

Перед passthrough остановите службу, которая использует устройство на хосте.

USB-накопитель

Перед пробросом USB-диска убедитесь, что он не смонтирован на узле.

Проверьте:

lsblk

findmnt

Размонтируйте:

umount /dev/sdX1

Не пробрасывайте накопитель одновременно в VM и не используйте его на хосте.

Это может привести к повреждению файловой системы.

Проверка после перезагрузки узла

После перезагрузки Proxmox VE:

lsusb

Проверьте конфигурацию VM:

qm config VM_ID |
grep '^usb'

Запустите VM и проверьте устройство внутри гостя.

Привязка одинаковых устройств

Если подключены два устройства с одной парой:

1234:5678

используйте физические порты:

2-3
2-4

Проверьте дерево:

lsusb -t

Не используйте одну Vendor/Product-привязку для нескольких одинаковых устройств.

USB-хаб

Устройство за USB-хабом может иметь путь вида:

2-3.4

После замены хаба или перестановки подключения путь может измениться.

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

  • фиксированный физический порт;
  • качественный powered hub;
  • документированную схему подключения;
  • маркировку кабелей.

Live migration

VM с USB passthrough привязана к физическому устройству конкретного узла.

Перед миграцией:

  1. Остановите приложение внутри VM.
  2. Удалите USB passthrough.
  3. Выполните миграцию.
  4. Подключите эквивалентное устройство на целевом узле.
  5. Добавьте его в конфигурацию VM.
  6. Проверьте приложение.

Обычная online migration такой VM может быть недоступна.

High Availability

USB passthrough плохо совместим с HA, потому что при автоматическом запуске VM на другом узле устройство будет отсутствовать.

Для HA-сервиса лучше использовать:

  • сетевое устройство;
  • USB-over-IP;
  • специализированный device server;
  • внешний сетевой контроллер;
  • одинаковое оборудование и mapping на всех узлах, если это поддерживается.

Безопасное отключение устройства

Сначала остановите приложение внутри VM.

Для USB storage размонтируйте файловую систему:

sudo umount /mount/point

Выключите VM:

qm shutdown VM_ID

Удалите passthrough.

Через веб-интерфейс:

VM → Hardware → USB Device → Remove

Через CLI:

qm set VM_ID   --delete usb0

Проверьте:

qm config VM_ID |
grep '^usb'

После этого физическое устройство можно отключить.

Замена USB-устройства

Если новое устройство имеет другую пару Vendor/Product ID:

lsusb

Удалите старую запись:

qm set VM_ID   --delete usb0

Добавьте новую:

qm set VM_ID   --usb0 host=NEW_VENDOR:NEW_PRODUCT

Проверьте внутри гостя новое имя устройства и права.

Типичные проблемы

Устройство не отображается в списке Proxmox

Проверьте на узле:

lsusb
journalctl -k -n 100 --no-pager

Попробуйте другой физический порт.

Проверьте питание устройства.

VM не запускается после добавления USB

Проверьте:

qm start VM_ID

Откройте журнал задачи.

Проверьте, что устройство всё ещё подключено и не используется другой VM.

Устройство видно на хосте, но не видно в VM

Проверьте:

qm config VM_ID |
grep '^usb'

Выполните полный shutdown и start VM.

Проверьте USB 2 и USB 3 режимы.

Устройство периодически исчезает

Проверьте:

  • кабель;
  • питание;
  • USB-хаб;
  • autosuspend;
  • события ядра;
  • физический порт;
  • качество оборудования.

В госте:

journalctl -k --since today |
grep -iE 'usb|disconnect|reset'

На узле:

journalctl -k --since today |
grep -iE 'usb|disconnect|reset'

После reboot изменился путь устройства

Используйте привязку по Vendor/Product ID или фиксированному USB-порту.

Внутри Linux используйте:

/dev/serial/by-id/

вместо /dev/ttyUSB0.

Permission denied внутри VM

Проверьте владельца и группу:

ls -l /dev/DEVICE

Добавьте сервисного пользователя в соответствующую группу.

Миграция VM заблокирована

Удалите USB passthrough перед миграцией либо выполните offline-перенос после изменения конфигурации.

Безопасный порядок настройки

  1. Подключить устройство к узлу.
  2. Проверить lsusb.
  3. Записать Vendor ID и Product ID.
  4. Проверить физический USB-порт.
  5. Убедиться, что устройство не используется хостом.
  6. Создать копию конфигурации VM.
  7. Остановить VM.
  8. Добавить USB Device.
  9. Запустить VM.
  10. Проверить устройство внутри гостя.
  11. Настроить права и стабильный путь.
  12. Проверить работу после перезагрузки.

Быстрый набор команд

Найти устройство:

lsusb
lsusb -t

Добавить по ID:

qm set VM_ID   --usb0 host=1234:5678

Добавить по порту:

qm set VM_ID   --usb0 host=2-3

Проверить:

qm config VM_ID |
grep '^usb'

Удалить:

qm set VM_ID   --delete usb0

Итог

После выполнения инструкции:

  • USB-устройство найдено на узле;
  • определены Vendor ID, Product ID и физический порт;
  • устройство добавлено в VM;
  • проверена работа внутри Linux;
  • настроены права и стабильный путь;
  • рассмотрены ограничения миграции и HA;
  • показано безопасное отключение.

Для критичных сервисов USB passthrough следует использовать только при наличии запасного устройства и документированной процедуры восстановления.

← Предыдущая статья Настройка QEMU Guest Agent в Proxmox VE Следующая статья → Проброс PCI-устройства в виртуальную машину Proxmox VE