{ "meta": { "title": "Añadir GPU a VM | Documentación de ProxMenux", "description": "Asigna una GPU física a una VM de Proxmox. ProxMenux revisa IOMMU, configura VFIO y dispositivos de la VM y detecta conflictos con otras VM o LXC." }, "header": { "title": "Añadir GPU a VM (Passthrough)", "description": "Detecta GPU Intel, AMD o NVIDIA y prepara acceso directo desde una VM. Revisa IOMMU y los dispositivos asociados, configura VFIO y la VM y aplica sus reglas de compatibilidad. Comprueba siempre todos los dispositivos afectados.", "section": "Hardware: GPU y Coral-TPU" }, "intro": { "title": "Qué hace", "body": "Automatiza la configuración del host y hostpci descrita en la documentación de passthrough PCI de Proxmox. Comprueba asignaciones en otros invitados y ofrece resolver conflictos. No garantiza compatibilidad con cualquier GPU, método de reinicio o controlador invitado." }, "who": { "heading": "¿Para quién es esto?", "body": "Para que una máquina virtual use directamente una GPU mediante VFIO. Mientras esté vinculada a VFIO, el controlador del host no puede usarla, aunque la VM esté parada. Para compartirla con LXC, usa Añadir GPU a LXC." }, "prereqs": { "title": "Antes de empezar", "gpu": "GPU compatible instalada físicamente. El script detecta Intel, AMD y NVIDIA con lspci.", "gpuCheck": "lspci | grep -iE 'VGA|3D|Display'", "iommu": "Soporte IOMMU en hardware y firmware cuando lo requiera (Intel VT-d o AMD-Vi). Comprueba el sistema y puede añadir parámetros Linux; no cambia BIOS/UEFI ni demuestra que un IOMMU inactivo esté desactivado en firmware.", "q35": "Este asistente exige tipo de máquina q35 y rechaza i440fx. El chipset es independiente de BIOS/UEFI; cambiarlo en una VM existente requiere planificación y no se hace automáticamente.", "q35Check": "qm config VMID | grep machine", "moreGpus": "Prepara otra GPU o acceso alternativo mediante SSH, IPMI o serie. La consola puede perder imagen al reservar la GPU principal. En NVIDIA, otra tarjeta fuera del grupo IOMMU afectado puede seguir en el host.", "nvidiaInstalled": "Con NVIDIA instalado en el host, las funciones elegidas se reservan para vfio-pci, no para nvidia. El módulo nvidia puede seguir disponible para otras tarjetas fuera del grupo IOMMU afectado. Verifícalas con nvidia-smi." }, "pickOne": { "title": "Asignación exclusiva a VM o compartición LXC", "body": "Una GPU vinculada a vfio-pci para passthrough a VM no puede usarla simultáneamente el host ni un LXC. Si tienes dos GPUs, puedes dedicar una a cada ruta. Si solo tienes una, elige:", "vmItem": "VM: acceso directo y exclusivo para esa VM.", "lxcItem": "LXC (Añadir GPU a LXC): comparte el dispositivo con host y otros contenedores mediante el controlador nativo." }, "running": { "heading": "Ejecutar el instalador", "body": "Abre ProxMenux y ve a Hardware: GPU y Coral-TPU → Añadir GPU a VM.", "imageAlt": "Opción del menú para añadir GPU a VM" }, "howRuns": { "heading": "Cómo funciona el script", "body": "Detecta y selecciona antes de aplicar los cambios principales y confirma el plan en un resumen final. Activar IOMMU tiene una confirmación anterior y puede modificar ya el arranque. La limpieza posterior de audio asociado también puede pedir una elección." }, "walkthrough": { "heading": "Proceso paso a paso", "detect": { "title": "Detectar GPUs y comprobar IOMMU", "body": "Considera IOMMU activo solo si el kernel en ejecución tiene intel_iommu=on o amd_iommu=on y existen grupos IOMMU. Si el parámetro ya está guardado para el próximo arranque, continúa en modo pendiente de reinicio; si no, con confirmación aparte puede añadirlo con iommu=pt. Elige /etc/kernel/cmdline si encuentra una marca ZFS como root=ZFS=; si no, /etc/default/grub. Es una heurística, no una prueba del cargador. Reinicia para activar el cambio y revisa los grupos reales.", "tipTitle": "¿Ya configuraste la postinstalación?", "tipBody": "Si el soporte VFIO IOMMU ya está configurado y activo en el kernel, supera la comprobación. Guardarlo para el próximo arranque no prueba que esté activo ahora.", "imageAlt": "Lista de GPUs detectadas con fabricante y dirección PCI" }, "preflight": { "title": "Elegir GPU y ejecutar comprobaciones previas", "intro": "Una vez eliges la GPU, el script ejecuta una serie de comprobaciones que pueden bloquear el progreso:", "items": [ "Protección SR-IOV. Rechaza VF y PF con VF activas porque configura dispositivos completos, no SR-IOV. Configura SR-IOV por separado con hardware compatible.", "Una sola GPU. La consola local puede perder su salida al reservarla para VFIO. Comprueba antes el acceso SSH o web desde otro equipo.", "Política de reinicio AMD. Lee /sys/bus/pci/devices/<pci>/reset_method. Una APU o dedicada sin FLR queda bloqueada por la política del asistente; un subtipo desconocido sin FLR exige confirmación. No demuestra que sea imposible en todo entorno.", "Estado D3cold. El asistente bloquea tarjetas AMD que indican D3cold por riesgo de fallo al activarlas. Revisa alimentación y firmware antes de continuar.", "Grupo IOMMU. Lee /sys/kernel/iommu_groups/ e incluye todos los miembros que no sean puentes, incluso controladores de red o discos. Si el grupo contiene dispositivos de otro slot, el script los muestra antes del resumen; comprueba que el host no necesite ninguno. Si falta reiniciar para activar IOMMU, solo puede planificar inicialmente la función GPU; comprueba el aislamiento después." ], "audioIntro": "Audio asociado. Dos casos según dónde esté el controlador:", "audioDgpu": "GPU dedicada: el audio HDMI suele ocupar la función .1 del mismo slot y se incluye al detectarlo. Si el host lo usaba, pierde acceso al reservarlo para la VM.", "audioIgpu": "Sin función de audio .1: puede estar en otro dispositivo, como 00:1f.3. Lista controladores y sus drivers, por ejemplo snd_hda_intel. Por defecto no selecciona ninguno; elige solo los necesarios." }, "pickVm": { "title": "Elige la VM destino", "body": "Elige la VM de la lista. Exige q35 y reutiliza entradas GPU existentes cuando puede. BIOS/UEFI es una opción distinta, no un tipo de máquina. No cambia automáticamente el chipset ni el arranque del invitado instalado.", "imageAlt": "Selección de VM por nombre, ID y estado" }, "switchMode": { "title": "Resolver asignaciones existentes", "intro": "El script escanea cada config de VM y cada config de LXC en el host buscando la GPU que elegiste. Tres resultados posibles:", "items": [ "GPU disponible. Continúa sin retirar asignaciones.", "Asignada a otra VM. Detén primero la VM origen. Puedes conservar sus entradas y desactivar el arranque automático o retirarlas conservando el arranque automático. Si ya usa vfio-pci y no requiere cambios del host, el traspaso VM→VM puede evitar reiniciar el host.", "Usada por LXC. En contenedores normales elige conservar configuración y desactivar arranque automático o eliminar la configuración de la GPU y conservar arranque automático. Esta opción elimina las entradas devN y, en AMD/Intel, también las reglas antiguas lxc.mount.entry de /dev/dri y lxc.cgroup2.devices.allow. OCI conserva la configuración y se detiene sin arranque automático; elimina su GPU desde Apps del gestor OCI. La detección por familia puede afectar a otras tarjetas similares." ], "imageAlt": "Diálogo que ofrece eliminar la GPU de un LXC antes de asignarla a la VM", "smartTitle": "Revisión de audio asociado al retirar la GPU", "smartBody": "Después ofrece una lista de audio posiblemente sin uso en la VM origen. Desmarca lo que aún necesite. Por ejemplo, puede conservar 02:00.1 y ofrecer retirar 00:1f.3. La lista decide qué audio adicional se elimina; no garantiza toda asociación entre pantalla y audio." }, "audioPick": { "title": "Si no hay audio .1, selecciona los controladores que necesites", "body": "Solo ocurre para iGPUs Intel y setups similares con audio separado. Una checklist muestra cada controlador de audio PCI del host (excluyendo cualquiera ya en el grupo IOMMU de la GPU), etiquetado con su driver actual. Selecciona los que quieras — o ninguno, si la VM no necesita audio del hardware del host.", "imageAlt": "Diálogo checklist con cada controlador de audio PCI del host (BDF + driver) cuando la GPU no tiene audio hermano .1", "warnTitle": "No selecciones audio que necesita el host", "warnBody": "Asignar audio puede dejar al host sin acceso; tampoco puede pertenecer a otra VM activa a la vez. Deja audio opcional sin seleccionar si no lo necesitas y revisa sus asignaciones. El pitido de consola no procede necesariamente del audio PCI." }, "summary": { "title": "Revisar el resumen de confirmación", "body": "Revisa el plan final y cancela si no es correcto. Muestra el grupo IOMMU y su número de dispositivos; los miembros de otro slot aparecen en el paso anterior. Cancelar detiene los cambios principales, pero no revierte una activación de IOMMU confirmada anteriormente.", "imageAlt": "Resumen de cambios previstos en host y VM" }, "hostApply": { "title": "Se aplican los cambios del host", "intro": "La fase de aplicación cambia host y VM. La limpieza de audio asociado aún puede pedir una elección. Puede modificar:", "items": [ "/etc/modules — añade vfio, vfio_iommu_type1, vfio_pci (más vfio_virqfd en kernels < 6.2).", "/etc/modprobe.d/vfio.conf — AMD/Intel: options vfio-pci ids=<vendor:device,...> disable_vga=1. NVIDIA: softdep nvidia pre: vfio-pci (_drm/_modeset/_uvm); la asignación real es por BDF. AMD añade orden de carga softdep: vfio-pci → radeon/amdgpu.", "Escribe /etc/modprobe.d/iommu_unsafe_interrupts.conf y kvm.conf con allow_unsafe_interrupts=1 e ignore_msrs=1. Son ajustes del script, no requisitos universales de Windows/macOS; permitir interrupciones inseguras reduce esa protección.", "/etc/modprobe.d/blacklist.conf: NVIDIA — nouveau/lbm-nouveau; AMD — radeon + amdgpu; Intel — i915. Estas reglas por fabricante pueden afectar a otras tarjetas con el mismo controlador. El módulo nvidia se bloquea solo mediante /etc/modprobe.d/proxmenux-nvidia-vfio-blacklist.conf cuando todas las NVIDIA del host están reservadas a VFIO.", "/etc/udev/rules.d/10-proxmenux-vfio-bind.rules + /etc/proxmenux/vfio-bind.bdfs — Solo NVIDIA. Aplica ATTR'{'driver_override'}'=\"vfio-pci\" al evento PCI ADD de BDF registrados, incluidas funciones del grupo IOMMU afectado. Fuera de esos grupos puede conservarse nvidia. La política por BDF no divide grupos IOMMU.", "Solo AMD. Intenta extraer ROM de /sys/bus/pci/.../rom o ACPI VFCT a /usr/share/kvm/vbios_<vendor>_<device>.bin. Si funciona, usa romfile=. Una ROM válida no garantiza que la GPU se inicialice.", "Solo NVIDIA. Detiene y deshabilita nvidia-persistenced, nvidia-powerd, nvidia-fabricmanager solo cuando todas las NVIDIA están reservadas para VFIO. En uso mixto conserva los servicios y nvidia para las tarjetas nativas.", "update-initramfs -u -k all — solo se ejecuta si algo de lo de arriba ha cambiado realmente." ] }, "vmApply": { "title": "La config de la VM se aplica vía qm set", "body": "La config de la VM en /etc/pve/qemu-server/<vmid>.conf se actualiza vía qm set (nunca por sed directo):", "after1": "Añade x-vga=1 para AMD y NVIDIA, no para Intel. Es la política del script; no demuestra que todas las iGPU Intel carezcan de firmware o que ese ajuste siempre provoque bloqueos.", "after2": "Se añaden líneas hostpciN adicionales si el grupo IOMMU de la GPU contiene otros dispositivos que necesitas pasar juntos." }, "reboot": { "title": "Reinicia si lo requiere el cambio del host", "body": "Sigue el aviso de reinicio si cambia arranque o controladores y comprueba la vinculación activa antes de iniciar la VM. Guardar configuración no prueba que esté aplicada. Un traspaso VM→VM con VFIO correcto puede evitar reiniciar el host.", "imageAlt": "Pantalla de resumen mostrando qué se cambió, seguida de un prompt de reinicio" } }, "vendors": { "heading": "Notas por fabricante", "nvidiaHeading": "NVIDIA", "nvidiaBody": "Conserva un ajuste heredado para Code 43: hidden=1, ID NV43FIX en args y kvm=off. No es requisito universal de GeForce actuales: NVIDIA añadió soporte de passthrough Windows en R465. El error puede tener otras causas; verifica GPU y controlador.", "nvidiaMultiHeading": "Soporte NVIDIA multi-GPU", "nvidiaMultiBody": "Admite uso mixto NVIDIA por BDF. Registra funciones de vfio-pci por dirección, no solo por ID vendor:device. Fuera de los grupos afectados pueden conservar nvidia; compruébalas con nvidia-smi. No aísla dos tarjetas del mismo grupo.", "amdHeading": "AMD", "amdBody": "Algunas AMD fallan al reiniciar tras parar una VM. El asistente comprueba capacidades declaradas, no todos los ciclos reales. vendor-reset admite una lista limitada y exige kernel compatible y carga temprana; no lo instala. RadeonResetBugFix en Windows también depende del hardware, sin garantía universal.", "intelHeading": "iGPU Intel", "intelBody": "Asignar toda la iGPU Intel y usar SR-IOV son procesos distintos. Este asistente reserva el dispositivo para una VM y omite x-vga=1. i915-sriov-dkms requiere hardware y kernel compatibles; «UHD 630+» no es una regla válida. Prevé acceso alternativo al host." }, "verification": { "heading": "Verificación" }, "troubleshoot": { "heading": "Solución de problemas", "code43Title": "Code 43 en Windows (NVIDIA)", "code43Body": "Code 43 no prueba un fallo de ocultación. Consulta qm config VMID | grep -E \"cpu|args\" sustituyendo VMID y revisa hidden=1 y hv_vendor_id=NV43FIX. Comprueba también controlador invitado, firmware y asignación. Repetir el script puede salir si ya está asignada.", "amdResetTitle": "La GPU AMD funciona una vez, falla al reiniciar la VM", "amdResetBody": "Una causa posible es el fallo de reinicio de la GPU. Reiniciar o apagar el host puede recuperarla temporalmente. Comprueba soporte de vendor-reset y carga temprana; softdep amdgpu pre: vendor-reset no garantiza por sí solo cargar antes de VFIO. RadeonResetBugFix en Windows también requiere GPU compatible.", "stuckBootTitle": "VM colgada arrancando / GPU no detectada", "stuckBootBody": "Consulta la dirección real con lspci -nnk -s PCI_ADDRESS; espera Kernel driver in use: vfio-pci. Sustituye PCI_ADDRESS. Si sigue el driver nativo, revisa su política de vinculación, no solo /etc/modprobe.d/blacklist.conf; NVIDIA usa estado por BDF. Consulta dmesg | grep vfio. Tras corregir configuración, ejecuta update-initramfs -u -k all y sigue el plan de reinicio.", "darkTitle": "La consola del host se queda a oscuras tras reiniciar y no puedo entrar por SSH", "darkBody": "Una pantalla negra no prueba que el host esté caído. Si falla SSH, revisa red y controladores incluidos en el grupo IOMMU. Recupera acceso por IPMI, serie o entorno de rescate; revisa /etc/pve/qemu-server/<vmid>.conf y revierte solo asignaciones y reglas relacionadas. No borres configuración ajena.", "logTitle": "Revisa el log de instalación", "logBody": "Cada ejecución escribe /tmp/add_gpu_vm.log. Adjunta el registro al pedir ayuda." }, "revert": { "heading": "Deshacer cambios manualmente", "intro": "Detén la VM y retira solo sus asignaciones PCI correspondientes desde Hardware o mediante el índice explícito del ejemplo. Eliminarla de la VM no devuelve la GPU al controlador del host. Para eso usa Cambiar modo de GPU y revisa los invitados afectados antes de confirmar." }, "related": { "heading": "Relacionado", "items": [ { "label": "Instalar drivers NVIDIA (Host)", "href": "/docs/hardware/nvidia-host", "tail": " — prepara el controlador para tarjetas que sigan en el host; una GPU en VFIO no puede usarlo a la vez." }, { "label": "Añadir GPU a LXC", "href": "/docs/hardware/igpu-acceleration-lxc", "tail": " — modelo alternativo: comparte la GPU con varios contenedores en lugar de dedicarla a una VM." }, { "label": "Cambiar modo de GPU (VM ↔ LXC)", "href": "/docs/hardware/switch-gpu-mode", "tail": " — cambia la misma GPU entre uso compartido y asignación exclusiva." }, { "label": "Comandos de GPU Passthrough", "href": "/docs/help-info/gpu-commands", "tail": " — referencia de lspci, verificación de IOMMU, qm set hostpci." } ] } }