virtio-fs, virtio-rng, vmgenid and the rest of the device model

A virtual machine’s device list is usually a disk, a NIC, a display and whatever was passed through. Three more devices exist, each solving a problem that otherwise gets solved badly:

• virtio-fs, so a guest can read a host directory without an NFS server in the middle.
• virtio-rng, so a guest that needs entropy gets it instead of blocking.
• vmgenid, so a guest can find out it has been rolled back to an earlier state.

The third one has no performance implications at all and is the one whose absence causes the most damage.

virtio-fs: sharing a host directory

The option:

--virtiofs[n] [dirid=]<mapping-id> [,cache=<enum>] [,direct-io=<1|0>]
             [,expose-acl=<1|0>] [,expose-xattr=<1|0>]

documented as “configuration for sharing a directory between host and guest using Virtio-fs”.

The important detail is in the argument type. dirid is a mapping-id, not a path. You do not point a VM at /srv/media; you define a directory mapping at the datacenter level, per node, and then reference it by name.

set -euo pipefail

# On each node that should be able to run the guest, the directory must exist
# and the mapping must name it. Create the directory first.
install -d -m 0755 /srv/shared-media

# Then define the mapping (Datacenter > Resource Mappings > Directory), giving
# it an id such as shared-media and pointing it at /srv/shared-media on each
# node where the guest may run.

# Attach it to the guest by mapping id, not by path.
qm set 118 --virtiofs0 dirid=shared-media,expose-xattr=1,expose-acl=0

qm shutdown 118 --timeout 300
qm start 118

set -euo pipefail

mkdir -p /mnt/media
mount -t virtiofs shared-media /mnt/media

# Persist it. The nofail option matters: a guest that may be started on a
# node without the mapping should still boot.
printf '%s\n' 'shared-media /mnt/media virtiofs defaults,nofail 0 0' >> /etc/fstab
findmnt /mnt/media

virtio-rng: entropy for guests

rng0: [source=]</dev/urandom|/dev/random|/dev/hwrng>
      [,max_bytes=<integer>] [,period=<integer>]

with max_bytes defaulting to 1024 and period to 1000 — that is, a rate limit of 1024 bytes per 1000 milliseconds.

set -euo pipefail

qm set 118 --rng0 source=/dev/urandom,max_bytes=1024,period=1000

# Inside the guest, confirm the device arrived and something is using it.
#   ls -l /dev/hwrng
#   cat /sys/devices/virtual/misc/hw_random/rng_current

When a guest actually needs this: a guest that boots slowly with services blocked on entropy — historically common on minimal images before Linux 5.6 changed getrandom() behaviour — and guests doing high-volume cryptographic work such as a busy TLS terminator or a certificate authority. For an ordinary application server on a current kernel, adding an RNG device solves a problem it does not have.

vmgenid: telling a guest it has been rolled back

--vmgenid <UUID> (default = 1 (autogenerated))

“Set VM Generation ID. Use 1 to autogenerate on create or update, pass 0 to disable explicitly.”

The generation ID is a 128-bit value the guest can read. Proxmox changes it when the VM’s history forks — the documentation names restoring a backup and rolling back a snapshot as the events it detects.

set -euo pipefail

# Which guests have no vmgenid?
for vmid in $(qm list | awk 'NR>1 {print $1}'); do
qm config "$vmid" | grep -q '^vmgenid:' || echo "VM $vmid has no vmgenid"
done

# Add one. This is a device change and takes effect at the next cold start.
qm set 118 --vmgenid 1

# Explicitly disable it, for a guest whose OS mishandles the device. Do this
# with a reason you have written down, not as a troubleshooting step.
#   qm set 118 --vmgenid 0

Two small options worth knowing

set -euo pipefail

for vmid in 101 102 118; do
qm set "$vmid" --protection 1
done

qm config 118 | grep -E '^(protection|tags):'

Knowledge check