redth/homelab-assist/proxmox-host-config

Proxmox host-level configuration (SSH required)

This skill covers the things the API cannot do, which live in host files. This is the fallback, not the default. We intentionally do this over SSH with guardrails rather than via a custom MCP server (an SSH-wrapping server would add risk and packaging without removing SSH's danger).

Before and during any work here, follow two homelab-core skills:

• homelab-core:homelab-safety — clear the SSH-confirmation gate: state why the API can't do it, show exactly

what you'll run/edit, get explicit approval for the SSH drop and the change.

• homelab-core:homelab-ssh — the full SSH execution discipline: confirm the host (hostname,

pveversion), secure a way back in before networking/boot changes, read → back up → show → apply → verify, validate-before-apply, and the dangerous-command list. Apply it to the whole session.

Proxmox-specific reminders on top of homelab-ssh:

• /etc/pve is the pmxcfs cluster filesystem — edits propagate to all nodes; treat with extra care.
• Validate the resulting guest config with qm config <id> / pct config <id> after editing the .conf.
• Many changes need a guest or host reboot — say so in your plan, and migrate/stop guests before rebooting

a node.

• Networking edits (/etc/network/interfaces) can cut off the node — keep console/IPMI access and apply with

ifreload -a, not a blind reboot.

• Research the version-correct approach first (homelab-core:homelab-research) — passthrough and kernel

specifics change between PVE/kernel versions. See `reference/gpu-passthrough.md`, `reference/config-files.md`, `reference/version-notes.md`.

Config file locations

/etc/pve is the cluster filesystem (pmxcfs) — edits propagate cluster-wide; treat carefully.

GPU / PCIe passthrough (high-care)

Full walkthrough in `reference/gpu-passthrough.md`. The moving parts:

1. Firmware: enable IOMMU (Intel VT-d / AMD-Vi) in BIOS/UEFI.
2. Kernel cmdline: add intel_iommu=on iommu=pt (or amd_iommu=on iommu=pt) via the correct bootloader

for this install (GRUB vs systemd-boot — check which this node uses; don't assume).

1. Modules: ensure vfio, vfio_iommu_type1, vfio_pci in /etc/modules (note: vfio_virqfd was

removed on 9.x — do not add it there).

1. Bind device to vfio / isolate driver: /etc/modprobe.d/vfio.conf with the device IDs and/or

softdep lines (e.g. softdep amdgpu pre: vfio-pci).

1. Assign to the VM: add hostpci0: 0000:01:00,pcie=1,x-vga=1 (IDs/flags vary) to

/etc/pve/qemu-server/<vmid>.conf.

1. Reboot host (steps 2-4) and VM (step 5); verify with lspci -nnk (driver in use = vfio-pci).

Discover devices/IDs read-only first: lspci -nnk, find /sys/kernel/iommu_groups/ -type l. Verify IOMMU group isolation before trusting passthrough. AMD reset bugs may need vendor-reset — research per-GPU.

Unprivileged LXC bind mounts & idmap

Bind-mounting host storage into an unprivileged container gives wrong ownership unless you remap UIDs. Two common approaches (research current best practice for the version):

• idmap remap in /etc/pve/lxc/<ctid>.conf (lxc.idmap entries) plus matching host

/etc/subuid / /etc/subgid ranges, so a container UID maps to a chosen host UID owning the data.

• Or set ownership on the host to the default mapped range (container root → host 100000).

This is fiddly and easy to get wrong — show the planned lxc.idmap block and the resulting host↔container UID mapping in your summary before applying.

LXC features for Docker-in-LXC

Running Docker inside an LXC typically needs features: nesting=1,keyctl=1 (and sometimes fuse=1) in /etc/pve/lxc/<ctid>.conf. See docker:docker-on-proxmox for the full Docker-host-in-LXC picture (privileged vs unprivileged trade-offs, storage, VLAN).

Hookscripts

A hookscript: local:snippets/<file>.pl line in a guest config runs at lifecycle phases (pre-start, post-stop) — used e.g. to bind/unbind a GPU. The script lives in /var/lib/vz/snippets/ and must be executable. Show the script and the config reference before installing.

Networking (advanced)

Basic NIC assignment is API-doable; VLAN-aware bridges, bonds, and trunk setup live in /etc/network/interfaces. A bad edit can cut off the node — always back up, and prefer applying via ifreload -a with a way back in (console/IPMI) rather than a blind reboot. See docker:docker-on-proxmox for how this ties to container VLANs.

Always

Read-first, back up, show diffs, confirm the SSH drop and the change, research the version-correct method, and note required reboots. When uncertain on a destructive passthrough/network change, propose a read-only verification step first.