Start passthrough VM and its dependents by device identity, not address

Adding a PCIe card can renumber the buses behind it, so a hostpci entry
that names a PCI address can pass through the wrong device. These start
the VM only after finding each device by vendor/device/subsystem ID or
by its MAC-pinned interface, repoint its resource mapping if it moved,
and refuse to start on anything ambiguous. Its dependents then wait for
a port on it to answer before starting, so they find their shares up.

conf/dependents.conf.example

@@ -0,0 +1,24 @@
+# Guests for start-dependents.sh, started once the passthrough VM is serving.
+#
+# Copy to conf/dependents.conf next to the scripts:
+#   cp conf/dependents.conf.example conf/dependents.conf
+#
+# The script looks for it relative to its own location, so this works both in a
+# checkout and deployed at /opt/ergosteur. Override with DEPENDENTS_CONFIG.
+#
+# Give every guest listed here onboot: 0, so that Proxmox does not start it
+# ahead of the VM it needs:
+#   qm set <vmid> --onboot 0
+#   pct set <ctid> --onboot 0
+
+# Started in this order. VM and container IDs both work.
+GUESTS=(
+    101
+    102
+)
+
+# Wait for this host:port to accept connections before starting them, for up to
+# WAIT_SECS seconds; an SMB or NFS port on the NAS, for example. Leave WAIT_FOR
+# empty to start them straight away.
+WAIT_FOR=192.0.2.10:445
+WAIT_SECS=300

conf/passthrough-vm.conf.example

@@ -0,0 +1,32 @@
+# VM and devices for start-passthrough-vm.sh.
+#
+# Copy to conf/passthrough-vm.conf next to the scripts:
+#   cp conf/passthrough-vm.conf.example conf/passthrough-vm.conf
+#
+# The script looks for it relative to its own location, so this works both in a
+# checkout and deployed at /opt/ergosteur. Override with PASSTHROUGH_VM_CONFIG.
+#
+# Give the VM onboot: 0 so that Proxmox's own autostart leaves it alone, and
+# point its hostpci entries at resource mappings rather than PCI addresses:
+#   qm set <vmid> --onboot 0
+#   qm set <vmid> --hostpci0 mapping=<mapping-id>,pcie=1
+
+VMID=100
+
+# One entry per resource mapping the VM uses: "<mapping-id> <lookup> <args>".
+#
+#   by-id <vendor:device:subvendor:subdevice>
+#       Exactly one device in the host must have these IDs, and it must already
+#       be on vfio-pci (or have no driver). Read them from sysfs:
+#       cat /sys/bus/pci/devices/<addr>/{vendor,device,subsystem_vendor,subsystem_device}
+#
+#   by-netdev <interface> <mac> <vendor:device:subvendor:subdevice>
+#       For one port of a multi-port NIC, where every port has the same IDs:
+#       the device behind <interface>, which must be pinned to <mac> by a .link
+#       file in /etc/systemd/network so that its name survives renumbering. Note
+#       that the ports of one card need not share a subsystem ID; read it from
+#       the port itself.
+DEVICES=(
+    "hba      by-id      1000:0097:1000:3090"
+    "nic-port by-netdev  nic0p1 00:11:22:33:44:55 8086:1572:8086:0000"
+)