"description":"How OCI manager Apps passes GPU, NVIDIA, Coral, USB, FUSE and other devices to an OCI container as validated native Proxmox VE resources."
},
"header":{
"title":"Devices and acceleration",
"description":"GPU, NVIDIA, Coral, USB, FUSE and block devices become validated native Proxmox VE resources of the container.",
"section":"OCI manager Apps"
},
"sections":[
{
"id":"principle",
"title":"The device the application needs, not the whole host",
"blocks":[
{
"p":"A device requested by the Compose file or by the application profile becomes a concrete <code>devN</code> entry or LXC mount. Asking for a GPU, a USB device or a Coral does not make the container privileged."
"title":"Detected devices are not attached on their own",
"body":"The host is inventoried, but only devices declared by the Compose file or by a compatible profile are offered and attached. A GPU, USB dongle or Coral present on the host is not exposed to every LXC."
}
}
]
},
{
"id":"identify",
"title":"How the host device is identified",
"intro":"Before the LXC is modified, the device is read on the host and matched against the chosen profile.",
"<code>/dev/dri/renderD*</code> and <code>/sys/class/drm/NODE/device/vendor</code>",
"A character device with vendor <code>0x8086</code> (Intel) or <code>0x1002</code> (AMD)"
],
[
"AMD OpenCL",
"The render node, plus <code>/dev/kfd</code> when the profile needs it",
"Existence, type, vendor, permissions and declared compatibility"
],
[
"AMD ROCm",
"The render node, <code>/dev/kfd</code> and the generation the compute driver reports in <code>/sys/class/kfd/kfd/topology/nodes/*/properties</code>",
"A GPU of a generation the application's ROCm image supports (the RDNA2 GPUs it names, and newer ones) is offered as it is. Other GPUs of those families, such as the Radeon 680M and 780M, are offered as experimental and are never the proposed option. ROCm does not support them officially: the application presents them as the generation of their family (<code>HSA_OVERRIDE_GFX_VERSION</code>), and the installer asks for confirmation before downloading the larger image. An older GPU, such as the integrated graphics of a Ryzen 5000U, is not offered, and Immich keeps recognition on the CPU"
],
[
"NVIDIA",
"<code>nvidia-smi</code> and <code>nvidia-container-cli</code>",
"body":"For example CPU only, Intel/AMD VA-API, AMD OpenCL, Intel OpenCL or NVIDIA. The options belong to the image, not to a common menu."
},
{
"title":"A profile is chosen",
"body":"It defines the device nodes, environment, mods or runtime the application needs."
},
{
"title":"A path is proposed",
"body":"For DRM, <code>/dev/dri/renderD128</code>, which can be changed on a host with several render nodes. For USB or serial, the concrete node is selected."
},
{
"title":"Validation",
"body":"Existence, type, allowed vendor, permissions and GID are checked. A mismatch stops the operation."
},
{
"title":"The contract is written",
"body":"Path, mode, GID, write access and profile are recorded for updates and recreations."
},
{
"title":"Attach and test",
"body":"<code>pct set</code> adds the <code>devN</code> entry and access is then checked inside the LXC. LinuxServer images are also checked as user <code>abc</code>."
"title":"How it appears in the LXC configuration",
"intro":"Illustrative values: <code>dev0</code> and <code>dev1</code> are the free slots Proxmox VE assigns, and <code>renderD128</code>, <code>apex_0</code> and the GID depend on the hardware of the node.",
"p":"The GID is read with <code>stat</code> on the host and written to the <code>devN</code> entry; the <code>render</code> and <code>video</code> groups are not assumed to have a fixed number. The device keeps the same <code>/dev</code> path inside the LXC, where the application's own mechanisms look for it."
"body":"A working driver on Proxmox VE is not enough to give an NVIDIA GPU to an OCI image. OCI manager Apps uses <code>nvidia-container-cli</code>, from the NVIDIA Container Toolkit, to identify the devices and to obtain the binaries and libraries that match the loaded driver."
}
},
{
"p":"The <nvidiaLink>ProxMenux NVIDIA installer</nvidiaLink> installs the NVIDIA Container Toolkit from the official NVIDIA repository together with the driver. It checks its four packages, validates <code>nvidia-container-cli</code> and records the result in the change journal of <auditLink>Audit & Report</auditLink>."
},
{
"p":"These two commands on the host show whether the driver and the Toolkit are available:"
"title":"Docker runtime configuration is not involved",
"body":"The containers are native LXCs and no Docker daemon is used, so <code>nvidia-ctk runtime configure --runtime=docker</code> plays no part: ProxMenux queries <code>nvidia-container-cli</code> directly and writes the LXC devices and mounts. The commands and supported platforms are maintained in the <toolkitLink>NVIDIA Container Toolkit installation guide</toolkitLink>."
"p":"Passing only <code>/dev/nvidia0</code> is not enough. The user-space components of the loaded driver are mounted read-only, and <code>nvidia-smi</code> then runs inside the LXC to compare GPU, UUID, PCI bus and version with the host inventory."
}
]
},
{
"id":"usb",
"title":"USB, serial and USB Coral",
"blocks":[
{
"calloutWarning":{
"title":"USB numbering can change",
"body":"A path such as <code>/dev/bus/usb/003/004</code> can change when the device is reconnected or the host restarts. The profile records vendor, product and serial when they are available, but a new bus address is not remapped automatically."
}
},
{
"p":"A peripheral is given by its concrete node: <code>/dev/ttyUSB0</code>, <code>/dev/ttyACM0</code>, <code>/dev/apex_0</code> or <code>/dev/bus/usb/BBB/DDD</code>. Passing the whole of <code>/dev</code> is not accepted. Coral is offered only to applications whose profile declares it."
"p":"Concrete devices, optional privilege, required privilege, AppArmor or seccomp relaxation and access to the host PID namespace are treated as separate cases, not under one generic privileged label. Each option with a risk is explained and confirmed during the installation."
