ProxMenux/web/messages/es/guides/nvidia-manual.json

{
  "meta": {
    "title": "Instalación de drivers NVIDIA en Proxmox VE 9 (procedimiento manual) | Guías ProxMenux",
    "description": "Instalación y configuración manual de los controladores NVIDIA en un host Proxmox VE 9 y del acceso a la GPU desde uno o varios contenedores LXC. Incluye el controlador, el servicio de persistencia, el parche NVENC opcional y la configuración de cada contenedor.",
    "ogTitle": "Instalación de drivers NVIDIA en Proxmox VE 9 (procedimiento manual)",
    "ogDescription": "Instalación manual de drivers NVIDIA en PVE 9 — driver del host, servicio de persistencia, parche NVENC opcional y cableado LXC por contenedor."
  },
  "header": {
    "title": "Instalación de drivers de tarjeta gráfica NVIDIA en Proxmox VE 9 (procedimiento manual)",
    "description": "Instalación y configuración manual de los controladores NVIDIA en un host Proxmox VE 9 y del acceso a la GPU desde uno o varios contenedores LXC. Incluye el controlador, el servicio de persistencia, el parche NVENC opcional y la configuración de cada contenedor.",
    "section": "Guías"
  },
  "intro": {
    "calloutTitle": "Nota",
    "calloutBody": "Este procedimiento manual se conserva como referencia. Para la mayoría de usuarios recomendamos el asistente de ProxMenux: <strong>Instalar controladores NVIDIA en el host</strong>, en <em>GPUs y Coral-TPU</em>, y después <strong>Agregar GPU a un LXC</strong> o <strong>Añadir GPU a VM</strong> para configurar el invitado. El asistente realiza los mismos pasos con comprobaciones adicionales de las cabeceras del kernel, IOMMU y conflictos VFIO. Esta página permite entender cada comando o adaptar la configuración.",
    "targetNote": "Dirigido a <strong>Proxmox VE 9</strong> (Debian Trixie). PVE 7 (Bullseye) y PVE 8 (Bookworm) ya no se cubren.",
    "stepsTitle": "Qué vas a hacer",
    "steps": [
      "Preparar el host Proxmox VE 9 (blacklist de nouveau, repos, prerrequisitos).",
      "Instalar el driver NVIDIA en el host.",
      "Instalar el servicio de persistencia NVIDIA.",
      "(Opcional) Aplicar el parche de keylase para levantar el límite de sesiones concurrentes de NVENC en GPUs de consumo.",
      "Dar acceso a la GPU a uno o varios contenedores LXC e instalar la versión correspondiente del controlador en cada uno."
    ]
  },
  "prepareHost": {
    "heading": "1. Preparar el host (PVE 9)",
    "blacklistHeading": "1.1 Bloquear nouveau",
    "blacklistBody": "Comprueba si el driver open-source <code>nouveau</code> ya está en la blacklist:",
    "blacklistCheckCode": "cat /etc/modprobe.d/blacklist.conf",
    "blacklistAdd": "Si <code>blacklist nouveau</code> no aparece, añádelo y reinicia:",
    "blacklistAddCode": "echo \"blacklist nouveau\" >> /etc/modprobe.d/blacklist.conf\nupdate-initramfs -u -k all\nreboot",
    "blacklistImageAlt": "Comprobación de blacklist",
    "reposHeading": "1.2 Verificar repositorios (PVE 9 / Trixie)",
    "reposBody": "Las herramientas de postinstalación pueden haber configurado ya los repositorios. Revisa las fuentes existentes y omite los cambios que ya estén hechos; no dupliques entradas.",
    "reposOtherwise": "Si no, en una instalación PVE 9 limpia sin suscripción enterprise:",
    "reposEditCode": "nano /etc/apt/sources.list.d/proxmox.sources",
    "reposPveBody": "Asegúrate de que contiene la fuente no-subscription para Trixie:",
    "reposPveCode": "Types: deb\nURIs: http://download.proxmox.com/debian/pve\nSuites: trixie\nComponents: pve-no-subscription\nSigned-By: /usr/share/keyrings/proxmox-archive-keyring.gpg",
    "reposDebianBody": "Y las fuentes Debian en <code>/etc/apt/sources.list.d/debian.sources</code>:",
    "reposDebianCode": "Types: deb\nURIs: http://deb.debian.org/debian/\nSuites: trixie trixie-updates\nComponents: main contrib non-free non-free-firmware\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg\n\nTypes: deb\nURIs: http://security.debian.org/debian-security/\nSuites: trixie-security\nComponents: main contrib non-free non-free-firmware\nSigned-By: /usr/share/keyrings/debian-archive-keyring.gpg",
    "updateHeading": "1.3 Actualizar el sistema e instalar prerrequisitos",
    "updateCode": "apt update && apt dist-upgrade -y",
    "buildToolsBody": "Instala las herramientas de build y los kernel headers necesarios para compilar el módulo del kernel NVIDIA:",
    "buildToolsCode": "apt-get install -y git\napt-get install -qqy pve-headers-$(uname -r) gcc make"
  },
  "installDriver": {
    "heading": "2. Instalar el driver NVIDIA en el host",
    "pickHeading": "2.1 Elegir una versión de driver",
    "pickBody": "Elige una rama del controlador compatible con tu GPU y el kernel en uso. La más reciente puede excluir modelos antiguos; consulta la lista de productos compatibles de la versión NVIDIA elegida:",
    "pickUrlCode": "https://download.nvidia.com/XFree86/Linux-x86_64/latest.txt",
    "nvencCallout": "Si vas a aplicar el parche NVENC (paso 4), verifica primero que el parche soporte tu versión de driver: <patchLink>github.com/keylase/nvidia-patch</patchLink>",
    "nvencCalloutTitle": "Aviso",
    "pickReplace": "Reemplaza <code>latest.txt</code> en la URL por el número de versión para encontrar el archivo de instalación que termina en <code>.run</code>. La lista completa de drivers está en:",
    "pickListCode": "https://download.nvidia.com/XFree86/Linux-x86_64/",
    "pickImageAlt": "Descarga del driver NVIDIA",
    "pickVersionNote": "A lo largo del resto de esta guía, reemplaza <code>'<'VERSION'>'</code> por la versión real (por ejemplo, <code>580.95.05</code>).",
    "downloadHeading": "2.2 Descargar y ejecutar el instalador",
    "downloadCode": "mkdir -p /opt/nvidia\ncd /opt/nvidia\nwget https://download.nvidia.com/XFree86/Linux-x86_64/VERSION/NVIDIA-Linux-x86_64-VERSION.run\nchmod +x NVIDIA-Linux-x86_64-VERSION.run",
    "firstPassBody": "Ejecuta el instalador. La opción siguiente puede desactivar <code>nouveau</code> si hace falta; quizá necesites reiniciar antes de completar la instalación:",
    "firstPassCode": "./NVIDIA-Linux-x86_64-VERSION.run --no-questions --ui=none --disable-nouveau\nreboot",
    "secondPassBody": "Cuando el host vuelva, ejecuta el instalador de nuevo para compilar e instalar el módulo del kernel:",
    "secondPassCode": "/opt/nvidia/NVIDIA-Linux-x86_64-VERSION.run --no-questions --ui=none",
    "modulesHeading": "2.3 Cargar módulos NVIDIA en el arranque",
    "modulesBody": "Edita la configuración de carga de módulos:",
    "modulesEditCode": "nano /etc/modules-load.d/modules.conf",
    "modulesAddBody": "Añade los módulos NVIDIA necesarios para el host y LXC. Los módulos VFIO son para acceso directo desde una VM y no hacen falta para este procedimiento LXC:",
    "modulesAddCode": "nvidia\nnvidia_uvm",
    "modulesSaveBody": "Guarda (<code>Ctrl+X</code>) y reconstruye initramfs:",
    "modulesSaveCode": "update-initramfs -u -k all",
    "udevHeading": "2.4 Crear reglas udev",
    "udevBody": "Para que los nodos de dispositivo <code>/dev/nvidia*</code> se creen cuando se cargan los módulos:",
    "udevEditCode": "nano /etc/udev/rules.d/70-nvidia.rules",
    "udevRulesCode": "# /etc/udev/rules.d/70-nvidia.rules\nKERNEL==\"nvidia\", RUN+=\"/bin/bash -c '/usr/bin/nvidia-smi -L'\"\nKERNEL==\"nvidia_uvm\", RUN+=\"/bin/bash -c '/usr/bin/nvidia-modprobe -c0 -u'\"",
    "udevSaveBody": "Guarda (<code>Ctrl+X</code>)."
  },
  "persistence": {
    "heading": "3. Servicio de persistencia del driver NVIDIA",
    "body": "El servicio de persistencia mantiene la GPU inicializada cuando ninguna otra aplicación la usa. Reduce la latencia de reinicialización y conserva el estado de inicialización entre clientes:",
    "installCode": "cd /opt/nvidia\ngit clone https://github.com/NVIDIA/nvidia-persistenced.git\ncd nvidia-persistenced/init\n./install.sh\nreboot",
    "verifyBody": "Verifica que el driver está cargado y el servicio está en marcha tras reiniciar:",
    "verifySmiCode": "nvidia-smi",
    "smiImageAlt": "Salida de NVIDIA SMI",
    "verifyServiceCode": "systemctl status nvidia-persistenced",
    "serviceImageAlt": "Estado del servicio de persistencia NVIDIA"
  },
  "nvenc": {
    "heading": "4. (Opcional) Levantar el límite de sesiones concurrentes de NVENC",
    "body": "El límite de sesiones NVENC depende del modelo de GPU y de la versión del controlador; consulta la matriz de NVIDIA en vez de asumir una cifra por generación. El parche keylase elimina el límite de software en las versiones compatibles. Puede ayudar en tareas de codificación como la transcodificación de Plex o Jellyfin.",
    "code": "cd /opt/nvidia\ngit clone https://github.com/keylase/nvidia-patch.git\ncd nvidia-patch\n./patch.sh",
    "imageAlt": "Aplicación del parche NVIDIA",
    "after": "El parche debe reaplicarse después de cada actualización del driver. El repositorio de keylase también incluye <code>patch-fbc.sh</code> para el límite de FBC (frame buffer capture) si lo necesitas."
  },
  "lxcSetup": {
    "heading": "5. Configurar un contenedor LXC para usar la GPU",
    "identifyHeading": "5.1 Identificar los números de dispositivo",
    "identifyBody": "En el host:",
    "identifyCode": "ls -l /dev/nv*",
    "identifyImageAlt": "Listado de dispositivos NVIDIA",
    "identifyNote": "Anota los números major — varían entre sistemas. Valores típicos:",
    "tableHeaders": {
      "device": "Dispositivo",
      "major": "Major típico"
    },
    "tableRows": [
      {
        "device": "<code>/dev/nvidia0</code>, <code>/dev/nvidiactl</code>",
        "major": "195"
      },
      {
        "device": "<code>/dev/nvidia-uvm</code>, <code>/dev/nvidia-uvm-tools</code>",
        "major": "509 (varía)"
      },
      {
        "device": "<code>/dev/dri/*</code>",
        "major": "226"
      },
      {
        "device": "<code>/dev/nvidia-modeset</code>",
        "major": "195 (comparte con nvidia)"
      }
    ],
    "editHeading": "5.2 Editar la config del LXC",
    "editBody": "Para el contenedor primero si está corriendo. Abre su archivo de configuración (reemplaza <code>'<'CTID'>'</code> por el ID del contenedor):",
    "editCode": "nano /etc/pve/lxc/CTID.conf",
    "editConfigBody": "Comenta las líneas <code>lxc.cgroup2.devices.allow</code> o <code>/dev/dri</code> preexistentes que entren en conflicto, luego añade el cableado NVIDIA (ajusta los números major a lo que <code>ls -l /dev/nv*</code> mostró en <strong>tu</strong> host):",
    "editConfigCode": "lxc.cgroup2.devices.allow: c 195:* rwm\nlxc.cgroup2.devices.allow: c 509:* rwm\nlxc.mount.entry: /dev/nvidia0 dev/nvidia0 none bind,optional,create=file\nlxc.mount.entry: /dev/nvidiactl dev/nvidiactl none bind,optional,create=file\nlxc.mount.entry: /dev/nvidia-uvm dev/nvidia-uvm none bind,optional,create=file\nlxc.mount.entry: /dev/nvidia-modeset dev/nvidia-modeset none bind,optional,create=file\nlxc.mount.entry: /dev/nvidia-uvm-tools dev/nvidia-uvm-tools none bind,optional,create=file",
    "editConfigImageAlt": "Configuración del LXC",
    "editSave": "Guarda (<code>Ctrl+X</code>) y arranca el contenedor.",
    "installCtHeading": "5.3 Instalar el driver dentro del contenedor",
    "installCtCalloutTitle": "Importante",
    "installCtCalloutBody": "Esta parte se ejecuta <strong>dentro</strong> del contenedor, no en el host.",
    "installCtBody": "El módulo del kernel ya está cargado por el host — el contenedor solo necesita las librerías de userland que coincidan con la misma versión del driver:",
    "installCtCode": "mkdir -p /opt/nvidia\ncd /opt/nvidia\nwget https://download.nvidia.com/XFree86/Linux-x86_64/VERSION/NVIDIA-Linux-x86_64-VERSION.run\nchmod +x NVIDIA-Linux-x86_64-VERSION.run\n./NVIDIA-Linux-x86_64-VERSION.run --no-kernel-module",
    "installCtAfter": "Revisa las preguntas y limita esta instalación a las bibliotecas de espacio de usuario. No compiles ni instales un módulo del kernel dentro del LXC.",
    "installCtImageAlt": "Instalación del driver NVIDIA",
    "verifyCtHeading": "5.4 Verificar dentro del contenedor",
    "verifyCtSmiCode": "nvidia-smi",
    "verifyCtSmiImageAlt": "NVIDIA SMI en LXC",
    "verifyCtLsCode": "ls -l /dev/nv*",
    "verifyCtLsImageAlt": "Dispositivos NVIDIA en LXC",
    "verifyCtAfter": "Deberías ver la GPU listada y los nodos de dispositivo montados en el sistema de archivos del contenedor.",
    "workloadHeading": "5.5 Confirmar que una carga real usa la GPU",
    "workloadBody": "Activa la aceleración NVIDIA en Plex o Jellyfin, transcodifica un vídeo y comprueba el uso real de la GPU en su panel o registros. Instalar el controlador no activa por sí solo la aceleración en la aplicación.",
    "workloadImage1Alt": "Plex usando la GPU NVIDIA",
    "workloadImage2Alt": "Plex usando la GPU NVIDIA - sesión activa",
    "repeatNote": "Repite la <strong>sección 5</strong> para cada contenedor adicional que necesite la GPU. Cuando actualices el controlador del host, mantén sincronizadas las bibliotecas de espacio de usuario de todos los contenedores."
  },
  "docker": {
    "heading": "6. (Opcional) NVIDIA Docker dentro de un LXC",
    "body": "Si Docker ya está instalado en el LXC, instala <code>nvidia-container-toolkit</code> dentro para dar acceso a la GPU a sus contenedores Docker. El acceso desde el LXC debe funcionar primero. Estos comandos son para Docker ejecutado como root:",
    "code": "apt-get update\napt-get install -y ca-certificates curl gnupg\ncurl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor --yes -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg\ncurl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' > /etc/apt/sources.list.d/nvidia-container-toolkit.list\napt-get update\napt-get install -y nvidia-container-toolkit\nnvidia-ctk runtime configure --runtime=docker\nsystemctl restart docker",
    "after": "Estos comandos configuran el repositorio de NVIDIA, instalan el toolkit, configuran el entorno de Docker y lo reinician. Siguen aplicándose los permisos de dispositivos y las restricciones cgroup del LXC; verifica la GPU con una carga de prueba."
  },
  "troubleshoot": {
    "heading": "Solución de problemas",
    "items": [
      "<strong><code>nvidia-smi</code> funciona en el host, pero muestra “No devices found” en el contenedor:</strong> revisa los montajes, permisos y versiones de las bibliotecas. Si difieren, instala la misma <code>'<'VERSION'>'</code> del host dentro del contenedor con <code>--no-kernel-module</code>.",
      "<strong>Falla la compilación del controlador:</strong> consulta el registro. “No precompiled kernel interface was found” puede indicar que el instalador debe compilar localmente. Instala las cabeceras de <code>uname -r</code> con <code>apt-get install pve-headers-$(uname -r)</code> o el paquete proxmox-headers equivalente.",
      "<strong>Las sesiones NVENC siguen limitadas:</strong> confirma que el parche admita el controlador activo. Una actualización puede sobrescribirlo. Para una versión compatible, vuelve a aplicar <code>./patch.sh</code> desde <code>/opt/nvidia/nvidia-patch</code> y revisa su salida.",
      "<strong>La GPU deja de responder tras estar inactiva:</strong> comprueba <code>systemctl status nvidia-persistenced</code> y activa el servicio si corresponde. Revisa también los registros del kernel y del controlador; no es la única causa posible.",
      "<strong>El contenedor arranca, pero <code>ls /dev/nv*</code> no muestra dispositivos NVIDIA:</strong> revisa los bind mounts y las rutas del host. Usa <code>ls -l /dev/nv*</code> en el host para verificar los números major de NVIDIA y comprueba las reglas <code>lxc.cgroup2.devices.allow</code> y los permisos."
    ]
  }
}