Проброс PCI-устройства в виртуальную машину Proxmox VE
Пошаговая настройка PCI passthrough в Proxmox VE: включение IOMMU, проверка групп, привязка устройства к vfio-pci и добавление в виртуальную машину.
PCI passthrough позволяет передать физическое PCI Express-устройство напрямую виртуальной машине.
Такой способ используют для:
- видеокарт;
- сетевых адаптеров;
- HBA-контроллеров;
- NVMe-накопителей;
- аппаратных ускорителей;
- специализированных плат.
В этой инструкции рассматривается только базовая настройка PCI passthrough для одной виртуальной машины.
Подходит для: Proxmox VE 8 и 9
Уровень сложности: высокий
Время выполнения: около 30–60 минут
Требуемый доступ: root-доступ, консоль узла и права управления VM
Важные ограничения
Перед настройкой учитывайте:
- устройство перестанет быть доступно самому узлу;
- VM будет зависеть от конкретного физического сервера;
- live migration обычно станет недоступна;
- High Availability потребует одинакового оборудования на других узлах;
- неправильная привязка системного контроллера может нарушить загрузку узла;
- для некоторых устройств требуется передавать несколько PCI-функций;
- GPU passthrough может требовать дополнительных настроек гостевой ОС.
Перед изменениями создайте резервную копию конфигурации узла и VM.
Что будет настроено
После выполнения инструкции можно будет:
- проверить поддержку IOMMU;
- включить IOMMU в BIOS и загрузчике;
- проверить IOMMU groups;
- определить PCI ID устройства;
- привязать устройство к
vfio-pci; - добавить устройство в VM;
- проверить его внутри Linux-гостя;
- безопасно вернуть устройство хосту.
Проверка аппаратной поддержки
Процессор и материнская плата должны поддерживать IOMMU.
Для Intel технология обычно называется:
Intel VT-d
Для AMD:
AMD-Vi
IOMMU
В BIOS или UEFI включите:
Intel Virtualization Technology
Intel VT-d
или:
SVM Mode
IOMMU
Названия параметров зависят от производителя оборудования.
Проверка виртуализации на узле
Для Intel:
grep -E 'vmx' /proc/cpuinfo |
head
Для AMD:
grep -E 'svm' /proc/cpuinfo |
head
Проверка наличия аппаратной виртуализации:
egrep -c '(vmx|svm)' /proc/cpuinfo
Значение больше нуля означает, что CPU-флаги доступны.
Определение способа загрузки Proxmox VE
Проверьте:
proxmox-boot-tool status
Если используется Proxmox Boot Tool, параметры ядра обычно задаются в:
/etc/kernel/cmdline
Если используется GRUB:
/etc/default/grub
Не изменяйте оба файла одновременно без необходимости.
Создание резервной копии
mkdir -p /root/pci-passthrough-backup
cp -a /etc/default/grub /etc/kernel/cmdline /etc/modules /etc/modprobe.d /root/pci-passthrough-backup/ 2>/dev/null
Сохраните конфигурацию VM:
qm config VM_ID > /root/pci-passthrough-backup/vm-VM_ID-config.txt
Включение IOMMU для Intel через GRUB
Откройте:
nano /etc/default/grub
Найдите строку:
GRUB_CMDLINE_LINUX_DEFAULT="quiet"
Добавьте:
intel_iommu=on iommu=pt
Пример:
GRUB_CMDLINE_LINUX_DEFAULT="quiet intel_iommu=on iommu=pt"
Примените:
update-grub
Включение IOMMU для AMD через GRUB
Используйте:
amd_iommu=on iommu=pt
Пример:
GRUB_CMDLINE_LINUX_DEFAULT="quiet amd_iommu=on iommu=pt"
Примените:
update-grub
Включение IOMMU через Proxmox Boot Tool
Откройте:
nano /etc/kernel/cmdline
Для Intel добавьте:
intel_iommu=on iommu=pt
Для AMD:
amd_iommu=on iommu=pt
Все параметры должны находиться в одной строке.
Примените:
proxmox-boot-tool refresh
Проверьте:
proxmox-boot-tool status
Загрузка модулей VFIO
Откройте:
nano /etc/modules
Добавьте:
vfio
vfio_iommu_type1
vfio_pci
На некоторых системах дополнительно используют:
vfio_virqfd
Но в новых ядрах этот функционал может быть встроен и отдельный модуль отсутствует.
Не добавляйте модуль, которого нет в вашей версии ядра.
Обновление initramfs
update-initramfs -u -k all
Перезагрузка узла
reboot
Используйте локальную консоль или IPMI для контроля загрузки.
Проверка IOMMU после перезагрузки
Для Intel:
dmesg |
grep -iE 'DMAR|IOMMU'
Для AMD:
dmesg |
grep -iE 'AMD-Vi|IOMMU'
Через journalctl:
journalctl -k -b --no-pager |
grep -iE 'DMAR|AMD-Vi|IOMMU'
Ожидаются сообщения о включённом IOMMU.
Просмотр PCI-устройств
lspci
С числовыми идентификаторами:
lspci -nn
Пример:
01:00.0 VGA compatible controller [0300]: Example GPU [1234:5678]
01:00.1 Audio device [0403]: Example HDMI Audio [1234:5679]
Здесь:
01:00.0
— PCI address;
1234:5678
— Vendor ID и Device ID.
Подробная информация об устройстве
lspci -nnk -s 01:00.0
Проверьте:
Kernel driver in use
Kernel modules
Проверка IOMMU groups
find /sys/kernel/iommu_groups/ -type l |
sort -V
Более читаемый вариант:
for group in /sys/kernel/iommu_groups/*; do
echo "IOMMU Group ${group##*/}:"
for device in "$group"/devices/*; do
lspci -nns "${device##*/}"
done
echo
done
Почему важна IOMMU group
Все устройства внутри одной IOMMU group могут быть недостаточно изолированы друг от друга.
Для безопасного passthrough желательно, чтобы передаваемое устройство:
- находилось в отдельной группе;
- либо передавалось вместе со всеми связанными функциями;
- не находилось в группе с системно важными контроллерами.
Не передавайте устройство, если в той же группе находится контроллер, необходимый хосту.
Многофункциональные устройства
Видеокарта часто имеет несколько функций:
01:00.0 — VGA
01:00.1 — HDMI Audio
Обычно в VM передают обе функции.
Проверьте:
lspci -nn -s 01:00
Проверка использования устройства хостом
lspci -nnk -s 01:00.0
Пример:
Kernel driver in use: nouveau
или:
Kernel driver in use: nvidia
или:
Kernel driver in use: amdgpu
Для passthrough устройство должно использовать:
vfio-pci
Определение PCI ID
Пример:
1234:5678
1234:5679
Запишите все функции устройства.
Привязка устройства к vfio-pci
Создайте файл:
nano /etc/modprobe.d/vfio.conf
Добавьте:
options vfio-pci ids=1234:5678,1234:5679
Используйте реальные идентификаторы устройства.
Отключение конфликтующего драйвера
Для конкретного устройства может потребоваться blacklist драйвера хоста.
Пример для nouveau:
nano /etc/modprobe.d/blacklist-passthrough.conf
blacklist nouveau
options nouveau modeset=0
Для других устройств драйвер будет другим.
Осторожно: не добавляйте в blacklist драйвер, который обслуживает системно важные устройства хоста.
Обновление initramfs после привязки
update-initramfs -u -k all
Перезагрузите узел:
reboot
Проверка драйвера после перезагрузки
lspci -nnk -s 01:00.0
Ожидаемый результат:
Kernel driver in use: vfio-pci
Проверьте вторую функцию:
lspci -nnk -s 01:00.1
Проверка VM перед добавлением
qm status VM_ID
Рекомендуется остановить VM:
qm shutdown VM_ID
Проверьте:
qm status VM_ID
Ожидаемый статус:
stopped
Добавление через веб-интерфейс
Откройте:
VM → Hardware
Нажмите:
Add → PCI Device
Выберите устройство.
В зависимости от сценария доступны параметры:
All Functions
Primary GPU
PCI-Express
ROM-Bar
Параметр All Functions
Если устройство имеет несколько функций, например GPU и аудио:
All Functions
передаёт все функции одного PCI slot.
Перед включением проверьте, что все функции действительно относятся к нужному устройству.
Параметр PCI-Express
Для современных PCIe-устройств и machine type q35 обычно включают:
PCI-Express
Проверьте тип машины:
qm config VM_ID |
grep '^machine'
Для PCIe passthrough часто используется:
q35
Добавление через CLI
Для одной функции:
qm set VM_ID --hostpci0 01:00.0
Для всех функций slot:
qm set VM_ID --hostpci0 01:00,pcie=1
Проверьте:
qm config VM_ID |
grep '^hostpci'
Пример GPU passthrough
qm set VM_ID --machine q35
qm set VM_ID --hostpci0 01:00,pcie=1
Если GPU должен быть основным видеоадаптером VM, может потребоваться:
x-vga=1
Пример:
qm set VM_ID --hostpci0 01:00,pcie=1,x-vga=1
Этот параметр нужен не для всех сценариев.
Запуск VM
qm start VM_ID
Если VM не запускается, откройте task log и не повторяйте запуск многократно без анализа ошибки.
Проверка внутри Linux-гостя
Установите PCI utilities:
sudo apt update
sudo apt install -y pciutils
Покажите устройство:
lspci
Подробно:
lspci -nnk
Устройство должно отображаться внутри VM.
Проверка драйвера в гостевой системе
Для конкретного PCI address:
lspci -nnk -s GUEST_PCI_ADDRESS
PCI address внутри гостя может отличаться от адреса на хосте.
Проверьте:
Kernel driver in use
Проверка сетевого адаптера
Для переданного NIC:
ip -br link
ethtool INTERFACE_NAME
Настройте IP внутри гостевой ОС.
Переданный NIC больше не связан с bridge Proxmox VE и работает как физическое устройство VM.
Проверка NVMe
lsblk
sudo nvme list
Если утилита отсутствует:
sudo apt install -y nvme-cli
Перед форматированием дважды проверьте имя устройства.
Проверка HBA-контроллера
lspci -nnk
lsblk
При пробросе HBA VM получает доступ к подключённым к нему физическим дискам.
Хост Proxmox VE не должен одновременно использовать эти диски.
Проверка GPU
Для NVIDIA:
nvidia-smi
Для AMD:
lspci -nnk |
grep -A3 -E 'VGA|Display'
Установка драйвера выполняется внутри гостевой ОС.
Перезагрузка VM
qm reboot VM_ID
Проверьте, что устройство стабильно появляется после reboot.
Перезагрузка узла
После тестирования VM перезагрузите узел в окно обслуживания:
reboot
Проверьте:
lspci -nnk -s 01:00.0
На хосте должен остаться:
Kernel driver in use: vfio-pci
Затем запустите VM и проверьте устройство внутри гостя.
Миграция VM
VM с PCI passthrough зависит от физического устройства узла.
Обычно недоступны:
- live migration;
- автоматическая HA migration;
- запуск на узле без эквивалентного устройства.
Перед миграцией:
- Остановите VM.
- Удалите
hostpci. - Выполните миграцию.
- Настройте устройство на целевом узле.
- Добавьте passthrough заново.
- Проверьте гостевую ОС.
High Availability
Для HA требуется:
- одинаковое оборудование;
- одинаковые mappings;
- одинаковые IOMMU-настройки;
- одинаковая доступность устройства;
- поддерживаемый механизм resource mapping.
Без этого VM не сможет автоматически стартовать на другом узле.
Снапшоты и backup
PCI passthrough может ограничивать отдельные операции VM.
Backup виртуальных дисков обычно остаётся возможным, но физическое состояние устройства в backup не сохраняется.
После восстановления на другом узле потребуется заново настроить passthrough.
Безопасное удаление passthrough
Остановите приложение внутри VM.
Выключите VM:
qm shutdown VM_ID
Удалите устройство:
qm set VM_ID --delete hostpci0
Проверьте:
qm config VM_ID |
grep '^hostpci'
Возврат устройства хосту
Удалите его ID из:
/etc/modprobe.d/vfio.conf
При необходимости удалите blacklist драйвера.
Обновите initramfs:
update-initramfs -u -k all
Перезагрузите:
reboot
Проверьте:
lspci -nnk -s 01:00.0
Устройство должно снова использовать штатный драйвер хоста.
Типичные проблемы
IOMMU не включён
Проверьте BIOS и параметры ядра:
cat /proc/cmdline
Проверьте журнал:
journalctl -k -b --no-pager |
grep -iE 'DMAR|AMD-Vi|IOMMU'
Устройство остаётся на штатном драйвере
Проверьте:
lspci -nnk -s PCI_ADDRESS
Проверьте vfio.conf, blacklist и initramfs.
VM не запускается с ошибкой device is already in use
Устройство используется хостом или другой VM.
Проверьте:
lspci -nnk -s PCI_ADDRESS
qm list
IOMMU group содержит несколько устройств
Проверьте все устройства группы.
Не передавайте системно важные контроллеры.
ACS override может искусственно разделить группы, но снижает гарантии изоляции и требует отдельной оценки рисков.
После passthrough пропала сеть узла
Вероятно, был передан NIC, используемый management-сетью.
Используйте локальную консоль, удалите hostpci, верните драйвер и восстановите сеть.
GPU показывает чёрный экран
Проверьте:
- machine type
q35; pcie=1;- передачу audio-функции;
x-vga=1;- UEFI/OVMF;
- драйвер внутри гостя;
- используемый видеовыход;
- необходимость ROM-файла.
GPU passthrough часто требует отдельной модели-зависимой диагностики.
Код ошибки драйвера GPU в Windows
Проверьте:
- драйвер;
- machine type;
- BIOS;
- параметры CPU;
- vendor reset;
- поддержку конкретной карты.
Это отдельный сценарий, не относящийся к базовой настройке PCI passthrough.
Безопасный порядок настройки
- Проверить поддержку VT-d или AMD-Vi.
- Создать резервные копии конфигурации.
- Включить IOMMU.
- Перезагрузить узел.
- Проверить IOMMU groups.
- Определить PCI ID.
- Убедиться, что устройство не нужно хосту.
- Привязать его к
vfio-pci. - Перезагрузить узел.
- Проверить драйвер
vfio-pci. - Остановить VM.
- Добавить
hostpci. - Запустить VM.
- Установить драйвер внутри гостя.
- Проверить reboot VM и узла.
Быстрый набор команд
Показать PCI-устройства:
lspci -nnk
Показать IOMMU groups:
for group in /sys/kernel/iommu_groups/*; do
echo "Group ${group##*/}"
for device in "$group"/devices/*; do
lspci -nns "${device##*/}"
done
done
Добавить устройство в VM:
qm set VM_ID --hostpci0 01:00,pcie=1
Проверить:
qm config VM_ID |
grep '^hostpci'
Удалить:
qm set VM_ID --delete hostpci0
Итог
После выполнения инструкции:
- включён IOMMU;
- проверены IOMMU groups;
- определены PCI address и device ID;
- устройство привязано к
vfio-pci; - PCI-устройство добавлено в VM;
- проверена работа внутри Linux-гостя;
- рассмотрены ограничения миграции и HA;
- показан возврат устройства хосту.
PCI passthrough следует настраивать только при наличии консольного доступа и полного понимания назначения выбранного устройства.