# Provider requirements

> What a Community machine needs, how to set up the firmware (virtualization, IOMMU) and VFIO on Ubuntu, and how to check it in a few commands.

Everything a machine needs before it hosts Community sessions, and how to check it yourself. Plan about 15 minutes, plus one reboot.

## The machine

| | |
|---|---|
| System | Ubuntu Server 24.04 LTS, installed directly on the machine. No VM, no WSL. |
| Kernel | Linux 6.12 or newer: the Ubuntu 24.04 HWE kernel. Sessions do not start on an older kernel. |
| Machine | Dedicated to Node Lodge. |
| GPU | NVIDIA, Ampere or newer, 12 GB of VRAM or more. Consumer, professional and datacenter cards. |
| CPU | Intel or AMD with hardware virtualization (VT-x or AMD-V) and an IOMMU (VT-d or AMD-Vi). |
| Disk | An SSD or NVMe drive with free space for session disks. |
| Display | No screen on the rented GPUs. Use the integrated graphics or another card for a console. |
| Network | Wired uplink, outbound internet. No inbound port. The agent measures the internet speed weekly against `speedtest.nodelodge.com`, see [Pair a machine](https://nodelodge.com/docs/pair-a-machine#internet-speed-test). |

## Check it in one go

On the machine, in a terminal:

```bash
lsb_release -ds; uname -r; nvidia-smi --query-gpu=name,memory.total --format=csv,noheader; ls /dev/kvm; ls /sys/kernel/iommu_groups | wc -l; df -h /
```

| Line | What you want to see |
|---|---|
| System | `Ubuntu 24.04` |
| Kernel | `6.12` or higher, e.g. `6.14.0-29-generic` |
| GPU | Your card and its memory, 12 GB or more |
| `/dev/kvm` | The path printed back. An error means virtualization is off. |
| IOMMU groups | A number above 0. `0` means the IOMMU is off. |
| Disk | Free space on the drive that holds session disks |

A kernel below 6.12: install the HWE kernel, then restart.

```bash
sudo apt install linux-generic-hwe-24.04 && sudo reboot
```

`nvidia-smi` answers only while the NVIDIA driver is loaded. Once the GPU is reserved for sessions (see VFIO below), it no longer shows there: that is expected.

## Firmware (BIOS or UEFI)

Open the firmware setup at boot (usually Del, F2 or F10) and set:

| Setting | Intel | AMD |
|---|---|---|
| CPU virtualization | Intel Virtualization Technology (VT-x): **On** | SVM Mode: **On** |
| IOMMU | VT-d: **On** | IOMMU: **On** (sometimes AMD-Vi) |
| Above 4G decoding | **On** | **On** |
| Boot mode | UEFI | UEFI |
| Primary display | Integrated graphics, or the card you keep for the console | Same |

Names differ between boards. Look under Advanced, CPU Configuration, Chipset or North Bridge. Save, then boot Ubuntu.

## IOMMU on the kernel command line

Intel boards need the IOMMU turned on in the kernel too. On AMD it is on by default; the same line does no harm.

1. Edit `/etc/default/grub` and add to `GRUB_CMDLINE_LINUX_DEFAULT`:
   - Intel: `intel_iommu=on iommu=pt`
   - AMD: `amd_iommu=on iommu=pt`
2. Run `sudo update-grub`, then reboot.
3. Check: `cat /proc/cmdline` shows the options, and `ls /sys/kernel/iommu_groups` lists groups.

Never add `pcie_acs_override`. It fakes the isolation between devices, and a machine that uses it fails review.

## Each GPU in its own IOMMU group

A rented GPU is attached to one VM, with every device that shares its IOMMU group. List the groups:

```bash
for g in /sys/kernel/iommu_groups/*; do echo "Group ${g##*/}"; for d in "$g"/devices/*; do echo "  $(lspci -nns "${d##*/}")"; done; done
```

Each NVIDIA GPU should share its group only with its own functions (its audio device, sometimes a USB controller on the card) and PCI bridges. If a GPU shares a group with a disk controller or a network card, move it to another PCIe slot, preferably one wired to the CPU.

## VFIO

Sessions reach the GPU through `vfio-pci`, the Linux driver that hands a device to a VM. The Community host install reserves the rented GPUs for you. To check it, or to set it up by hand:

1. Find the IDs of the GPU and its audio function: `lspci -nn -d 10de:` (for example `[10de:2684]` and `[10de:22ba]`).
2. Create `/etc/modprobe.d/vfio.conf` with:

   ```
   options vfio-pci ids=10de:2684,10de:22ba
   softdep nvidia pre: vfio-pci
   softdep nouveau pre: vfio-pci
   ```

3. Run `sudo update-initramfs -u`, then reboot.
4. Check: `lspci -nnk -d 10de:` shows `Kernel driver in use: vfio-pci` for each rented function.

Two cards of the same model share their IDs: both are reserved. Keep a different card, or the integrated graphics, for the console.

## The self-test

The Node Lodge agent runs the same checks and tells you what to fix. On the machine, in the agent folder:

```bash
node compute-host.mjs doctor --community
```

It reads the machine and changes nothing. Each line is **pass**, **warn** or **fail**:

| Check | Passes when |
|---|---|
| `node` | Node 22.12 or later |
| `privileges` | It runs as a standard user, not root |
| `inventory`, `gpu` | The hardware is read, with an NVIDIA GPU and its VRAM |
| `kernel` | Linux 6.12 or newer (Ubuntu 24.04 HWE) |
| `kvm` | `/dev/kvm` exists |
| `iommu` | IOMMU groups exist |
| `iommu-gpu` | Each GPU is alone in its IOMMU group |
| `acs-override` | No `pcie_acs_override` on the kernel command line |
| `vfio-pci` | The `vfio-pci` driver is loaded |
| `cloud-hypervisor` | The hypervisor is installed |

Fix every **fail** before you pair the machine. Next: [Pair a machine](https://nodelodge.com/docs/pair-a-machine).