ProxMenux/web/messages/it/docs/oci-manager/hardware.json

{
  "meta": {
    "title": "Dispositivi e accelerazione | ProxMenux",
    "description": "Come OCI manager Apps passa GPU, NVIDIA, Coral, USB, FUSE e altri dispositivi a un contenitore OCI come risorse native Proxmox VE convalidate."
  },
  "header": {
    "title": "Dispositivi e accelerazione",
    "description": "I dispositivi GPU, NVIDIA, Coral, USB, FUSE e a blocchi diventano risorse native convalidate Proxmox VE del contenitore.",
    "section": "OCI manager Apps"
  },
  "sections": [
    {
      "id": "principle",
      "title": "Il dispositivo di cui l'applicazione ha bisogno, non l'intero host",
      "blocks": [
        {
          "p": "Un dispositivo richiesto dal file Compose o dal profilo dell’applicazione viene configurato come voce <code>devN</code> specifica o come montaggio LXC. Richiedere una GPU, un dispositivo USB o un acceleratore Coral non rende il container privilegiato."
        },
        {
          "flow": {
            "nodes": [
              {
                "label": "Inventario host",
                "detail": "/dev/dri/renderD128\nGID 993 · Intel"
              },
              {
                "label": "ProxMenux",
                "detail": "produttore e\npermessi verificati"
              },
              {
                "label": "LXC",
                "detail": "stesso dispositivo\nGID effettivo"
              }
            ]
          }
        }
      ]
    },
    {
      "id": "origin",
      "title": "Da dove proviene la richiesta del dispositivo",
      "blocks": [
        {
          "table": {
            "headers": [
              "Fonte",
              "Cosa si legge",
              "Cosa fa l'installatore"
            ],
            "rows": [
              [
                "Docker Compose",
                "<code>devices</code>, <code>group_add</code>, <code>deploy.resources</code> e NVIDIA richieste",
                "Ogni esigenza diventa una richiesta di dispositivo mostrata per la revisione"
              ],
              [
                "Profilo del catalogo",
                "Il supporto effettivo dell’applicazione per GPU, Coral, OpenCL, USB o FUSE",
                "Solo le opzioni convalidate per quell'immagine sono offerte"
              ],
              [
                "Metadati e documentazione dell’immagine",
                "VA-API, Selkies, mod LinuxServer o runtime NVIDIA",
                "Vengono aggiunte le variabili documentate e la preparazione"
              ],
              [
                "Selezione utente",
                "CPU solo, Intel/AMD, OpenCL, NVIDIA o un dispositivo opzionale",
                "La selezione viene memorizzata nel contratto di istanza"
              ]
            ]
          }
        },
        {
          "calloutWarning": {
            "title": "I dispositivi rilevati non vengono collegati automaticamente",
            "body": "Viene creato un inventario dell’host, ma solo i dispositivi dichiarati dal file Compose o da un profilo compatibile sono offerti e allegati. Una GPU, USB dongle o Coral presente sull'host non è esposto ad ogni LXC."
          }
        }
      ]
    },
    {
      "id": "identify",
      "title": "Come viene identificato il dispositivo host",
      "intro": "Prima della modifica del LXC, il dispositivo viene letto sull'host e abbinato al profilo scelto.",
      "blocks": [
        {
          "table": {
            "headers": [
              "Tipo",
              "Identità",
              "Validazione"
            ],
            "rows": [
              [
                "Intel/AMD DRM",
                "<code>/dev/dri/renderD*</code> e <code>/sys/class/drm/NODE/device/vendor</code>",
                "Un dispositivo a caratteri con il fornitore <code>0x8086</code> (Intel) o <code>0x1002</code> (AMD)"
              ],
              [
                "AMD OpenCL",
                "Il nodo di rendering, più <code>/dev/kfd</code> quando il profilo ne ha bisogno",
                "Esistenza, tipo, fornitore, autorizzazioni e compatibilità dichiarata"
              ],
              [
                "AMD ROCm",
                "Il nodo di rendering, <code>/dev/kfd</code> e la generazione indicata dal driver di calcolo in <code>/sys/class/kfd/kfd/topology/nodes/*/properties</code>",
                "Una generazione per cui l’immagine ROCm dell’applicazione include kernel di calcolo — le GPU RDNA2 indicate e quelle più recenti — viene proposta così com’è. Le altre GPU di queste famiglie, come Radeon 680M e 780M, sono proposte come sperimentali e non sono mai preselezionate: ROCm non le supporta ufficialmente, l’applicazione le presenta come la generazione della rispettiva famiglia (<code>HSA_OVERRIDE_GFX_VERSION</code>) e l’installatore chiede conferma prima di scaricare l’immagine più grande. Una GPU precedente, come la grafica integrata di un Ryzen 5000U, non viene proposta e Immich mantiene il riconoscimento sulla CPU."
              ],
              [
                "NVIDIA",
                "<code>nvidia-smi</code> e <code>nvidia-container-cli</code>",
                "GPU, UUID, bus PCI, versione driver, Toolkit, nodi <code>/dev/nvidia*</code>, binari e librerie"
              ],
              [
                "Coral PCIe/M.2",
                "<code>/dev/apex_N</code> e il suo collegamento in <code>/sys/dev/char/MAJOR:MINOR</code>",
                "Nodo a caratteri, numeri major/minor, proprietario, GID e permessi"
              ],
              [
                "USB e seriale",
                "<code>/dev/ttyUSB*</code>, <code>/dev/ttyACM*</code> o <code>/dev/bus/usb/BBB/DDD</code>",
                "Nodo di carattere; per USB anche produttore, prodotto e seriale quando sysfs li pubblica"
              ],
              [
                "KVM, TUN, FUSE, video e SCSI generici",
                "<code>/dev/kvm</code>, <code>/dev/net/tun</code>, <code>/dev/fuse</code>, <code>/dev/videoN</code> o <code>/dev/sgN</code>",
                "Percorso supportato, tipo nodo e permessi effettivi"
              ],
              [
                "Unità ottica",
                "<code>/dev/srN</code>",
                "Un dispositivo a blocchi"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "install",
      "title": "Cosa succede durante l'installazione",
      "blocks": [
        {
          "steps": {
            "items": [
              {
                "title": "Il modello offre i suoi profili",
                "body": "Ad esempio solo CPU, Intel/AMD VA-API, AMD OpenCL, Intel OpenCL o NVIDIA. Le opzioni appartengono all'immagine, non a un menu comune."
              },
              {
                "title": "Viene scelto un profilo",
                "body": "Definisce i nodi del dispositivo, ambiente, mod o runtime di cui l'applicazione ha bisogno."
              },
              {
                "title": "Si propone un percorso",
                "body": "Per DRM, <code>/dev/dri/renderD128</code>, che può essere modificato su un host con diversi nodi di rendering. Per USB o seriale, viene selezionato il nodo specifico."
              },
              {
                "title": "Validazione",
                "body": "Esistenza, tipo, fornitore consentito, autorizzazioni e GID sono controllati. Un errore blocca l'operazione."
              },
              {
                "title": "Il contratto è scritto",
                "body": "Percorso, modalità, GID, accesso scrittura e profilo sono registrati per aggiornamenti e ricreazioni."
              },
              {
                "title": "Collega e verifica",
                "body": "<code>pct set</code> aggiunge l'ingresso <code>devN</code> e l'accesso viene quindi controllato all'interno del LXC. Le immagini LinuxServer vengono anche controllate come utente <code>abc</code>."
              }
            ]
          }
        }
      ]
    },
    {
      "id": "config",
      "title": "Come appare nella configurazione LXC",
      "intro": "Valori illustrativi: <code>dev0</code> e <code>dev1</code> sono gli slot liberi assegnati da Proxmox VE; <code>renderD128</code>, <code>apex_0</code> e il GID dipendono dall’hardware del nodo.",
      "blocks": [
        {
          "codeGrid": {
            "items": [
              {
                "title": "Intel/AMD VA-API",
                "code": "dev0: path=/dev/dri/renderD128,mode=0660,gid=993,deny-write=0"
              },
              {
                "title": "Coral PCIe/M.2",
                "code": "dev0: path=/dev/apex_0,mode=0660,gid=GID,deny-write=0"
              },
              {
                "title": "Un dispositivo USB specifico",
                "code": "dev0: path=/dev/bus/usb/003/004,mode=0660,gid=GID,deny-write=0"
              },
              {
                "title": "AMD OpenCL",
                "code": "dev0: path=/dev/dri/renderD128,mode=0660,gid=GID,deny-write=0\ndev1: path=/dev/kfd,mode=0660,gid=GID,deny-write=0"
              }
            ]
          }
        },
        {
          "p": "Il GID è letto con <code>stat</code> sull'host e scritto all'ingresso <code>devN</code>; i gruppi <code>render</code> e <code>video</code> non si presume abbiano un numero fisso. Il dispositivo mantiene lo stesso percorso <code>/dev</code> all'interno del LXC, dove i propri meccanismi dell'applicazione lo cercano."
        }
      ]
    },
    {
      "id": "profiles",
      "title": "Profili che un’immagine può offrire",
      "blocks": [
        {
          "table": {
            "headers": [
              "Profilo",
              "Configurazione risultante",
              "Offerto quando"
            ],
            "rows": [
              [
                "Intel/AMD VA-API",
                "Nodo di rendering <code>/dev/dri</code>",
                "L'applicazione supporta l'accelerazione video"
              ],
              [
                "OpenCL",
                "Nodo di rendering, <code>/dev/kfd</code> quando necessario e mod ufficiale",
                "L'immagine o il profilo lo documentano"
              ],
              [
                "NVIDIA",
                "Dispositivi driver e librerie dell'host",
                "L’host dispone di un driver funzionante e di NVIDIA Container Toolkit"
              ],
              [
                "Coral",
                "<code>/dev/apex_0</code> o il bus USB",
                "Il profilo dichiara il supporto Coral (Frigate)"
              ],
              [
                "USB, seriale, FUSE",
                "Un singolo dispositivo, un albero convalidato o una funzione LXC",
                "Il contratto lo chiede"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "nvidia",
      "title": "NVIDIA",
      "blocks": [
        {
          "calloutWarning": {
            "title": "Requisito del nodo: NVIDIA Container Toolkit",
            "body": "Un driver funzionante su Proxmox VE non è sufficiente per dare un NVIDIA GPU ad un'immagine OCI. OCI manager Apps utilizza <code>nvidia-container-cli</code>, dal NVIDIA Container Toolkit, per identificare i dispositivi e per ottenere i binari e le librerie che corrispondono al driver caricato."
          }
        },
        {
          "p": "L’<nvidiaLink>installatore NVIDIA di ProxMenux</nvidiaLink> installa NVIDIA Container Toolkit dal repository ufficiale NVIDIA insieme al driver. Controlla i quattro pacchetti, convalida <code>nvidia-container-cli</code> e registra il risultato nel registro delle modifiche di <auditLink>Audit & Report</auditLink>."
        },
        {
          "p": "Questi due comandi sull'host mostrano se il driver e il Toolkit sono disponibili:"
        },
        {
          "shell": {
            "code": "nvidia-smi -L\nnvidia-container-cli --version"
          }
        },
        {
          "p": "Su un host dove il driver è stato installato con altri mezzi, il Toolkit è installato dal repository ufficiale stabile:"
        },
        {
          "shell": {
            "code": "apt-get update\napt-get install -y --no-install-recommends ca-certificates curl gnupg2\n\ncurl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \\\n  | gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg\n\ncurl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \\\n  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \\\n  > /etc/apt/sources.list.d/nvidia-container-toolkit.list\n\napt-get update\napt-get install -y nvidia-container-toolkit libnvidia-container-tools"
          }
        },
        {
          "p": "L’inventario utilizzato da OCI manager Apps è l'output di:"
        },
        {
          "shell": {
            "code": "nvidia-container-cli list --device all --libraries --binaries --firmwares --ipcs"
          }
        },
        {
          "calloutInfo": {
            "title": "La configurazione di runtime Docker non è coinvolta",
            "body": "I container sono LXC nativi e non usano un demone Docker, quindi <code>nvidia-ctk runtime configure --runtime=docker</code> non interviene: ProxMenux interroga direttamente <code>nvidia-container-cli</code> e configura dispositivi e montaggi LXC. I comandi e le piattaforme supportate sono mantenuti nella <toolkitLink>guida di installazione di NVIDIA Container Toolkit</toolkitLink>."
          }
        },
        {
          "cards": {
            "items": [
              {
                "icon": "cpu",
                "title": "Inventario dal driver",
                "body": "<code>nvidia-container-cli</code> elenca i nodi del dispositivo, i binari, il firmware e le librerie del driver installato."
              },
              {
                "icon": "refresh",
                "title": "Nessuna versione fissa",
                "body": "Il modello non nomina i file della libreria. Il profilo viene generato dall'host corrente."
              },
              {
                "icon": "shield",
                "title": "Montaggi in sola lettura",
                "body": "Le librerie ospitanti sono montate in sola lettura invece di essere copiate nel contenitore."
              },
              {
                "icon": "hardDrive",
                "title": "Modifiche dei driver",
                "body": "Dopo che un driver cambia l'inventario viene generato nuovamente prima dell'avvio dei LXC colpiti."
              }
            ]
          }
        },
        {
          "code": {
            "title": "Risultati NVIDIA (semplificati)",
            "code": "devN: path=/dev/nvidia0,...\ndevN: path=/dev/nvidiactl,...\ndevN: path=/dev/nvidia-uvm,...\nlxc.mount.entry: HOST_LIBRARY CONTAINER_LIBRARY none ro,bind,create=file 0 0"
          }
        },
        {
          "p": "Passare solo <code>/dev/nvidia0</code> non è sufficiente. I componenti user-space del driver caricato sono montati in sola lettura e <code>nvidia-smi</code> poi funziona all'interno del LXC per confrontare GPU, UUID, PCI bus e versione con l'inventario host."
        }
      ]
    },
    {
      "id": "usb",
      "title": "USB, seriale e USB Coral",
      "blocks": [
        {
          "calloutWarning": {
            "title": "Numerazione USB può cambiare",
            "body": "Un percorso come <code>/dev/bus/usb/003/004</code> può cambiare quando il dispositivo viene ricollegato o l'host si riavvia. Il profilo registra il fornitore, il prodotto e la serie quando sono disponibili, ma un nuovo indirizzo del bus non viene rimappato automaticamente."
          }
        },
        {
          "p": "Una periferica è data dal suo nodo specifico: <code>/dev/ttyUSB0</code>, <code>/dev/ttyACM0</code>, <code>/dev/apex_0</code> o <code>/dev/bus/usb/BBB/DDD</code>. Passare l'intero <code>/dev</code> non è accettato. Coral è offerto solo a applicazioni il cui profilo lo dichiara."
        }
      ]
    },
    {
      "id": "trees",
      "title": "Alberi dei dispositivi e funzionalità LXC",
      "blocks": [
        {
          "table": {
            "headers": [
              "Richiesta",
              "Configurazione risultante",
              "Ambito"
            ],
            "rows": [
              [
                "<code>/dev/dvb</code>, <code>/dev/snd</code> o <code>/dev/bus/usb</code>",
                "Ogni nodo di carattere dell'albero ottiene il proprio ingresso <code>devN</code> con la modalità host e GID",
                "Solo l'albero richiesto, non il resto di <code>/dev</code>"
              ],
              [
                "<code>/dev/fuse</code>",
                "Il nodo e, quando il profilo ne ha bisogno, la funzione <code>fuse=1</code>",
                "FUSE da solo non rende disponibili i montaggi agli altri LXC"
              ],
              [
                "<code>/dev/net/tun</code>",
                "Un ingresso <code>devN</code> nello stesso percorso all'interno del LXC",
                "La configurazione VPN o di rete rimane nell’applicazione"
              ],
              [
                "<code>/dev/kvm</code>",
                "Una voce valida <code>devN</code>",
                "Offerto solo quando il contratto lo chiede"
              ]
            ]
          }
        }
      ]
    },
    {
      "id": "security",
      "title": "Conferma per livello di rischio",
      "blocks": [
        {
          "p": "Dispositivi concreti, privilegio facoltativo, privilegio richiesto, allentamento di AppArmor o seccomp e accesso al namespace PID host sono trattati come casi separati, non sotto una generica etichetta privilegiata. Ogni opzione con un rischio viene spiegata e confermata durante l'installazione."
        }
      ]
    }
  ]
}