Coordinating backup with the guest

Why this matters in production

The snapshot is taken by the storage layer and the state that needs flushing lives in the guest, so something has to bridge them.

Coordinating from the hypervisor

# freeze guest filesystems via the guest agent, snapshot, thaw
DOMAIN=vm-db-01
POOL=rbd-vms
IMAGE=vm-disk-01
virsh domfsfreeze ${DOMAIN}
rbd snap create ${POOL}/${IMAGE}@consistent-$(date +%Y%m%d)
virsh domfsthaw ${DOMAIN}

# Substitute your own value before running:
DOMAIN=vm-db-01

# verify the agent is present and responding first
virsh qemu-agent-command "$DOMAIN" '{"execute":"guest-ping"}'

Without the guest agent, domfsfreeze fails and the snapshot proceeds
unquiesced — which is why the freeze result must be checked rather than
assumed.

#!/bin/bash
set -euo pipefail
DOM=$1; POOL=$2; IMG=$3
SNAP="consistent-$(date +%Y%m%d-%H%M)"

if virsh domfsfreeze "$DOM" >/dev/null 2>&1; then
  FROZEN=1
else
  echo "WARNING: freeze failed for $DOM; snapshot will be crash consistent" >&2
  FROZEN=0
fi

rbd snap create "$POOL/$IMG@$SNAP"

[ "$FROZEN" = "1" ] && virsh domfsthaw "$DOM" >/dev/null
echo "$POOL/$IMG@$SNAP frozen=$FROZEN"

Recording whether the freeze succeeded is what makes the snapshot's
consistency level knowable at restore time.

Guests without an agent

# Substitute your own values before running:
GUEST=vm-db-01.example.com
POOL=rbd-vms
IMAGE=vm-disk-01

# from inside the guest, if a login is possible
ssh "$GUEST" 'sync && fsfreeze -f /data'
rbd snap create "$POOL/$IMAGE@consistent"
ssh "$GUEST" 'fsfreeze -u /data'

Freezing the root filesystem from inside the guest over SSH can freeze
the SSH session itself. Freeze data filesystems, not the root.

Multi-image sequencing

# Substitute your own value before running:
POOL=rbd-vms

rbd group create "$POOL/vm-db"
rbd group image add "$POOL/vm-db" "$POOL/vm-db-root"
rbd group image add "$POOL/vm-db" "$POOL/vm-db-data"
rbd group image add "$POOL/vm-db" "$POOL/vm-db-log"

# Substitute your own value before running:
POOL=rbd-vms

virsh domfsfreeze vm-db
rbd group snap create "$POOL/vm-db@consistent-$(date +%Y%m%d)"
virsh domfsthaw vm-db

# Substitute your own value before running:
POOL=rbd-vms

rbd group snap ls "$POOL/vm-db"

The group snapshot is atomic across the images, so the freeze window is
one snapshot operation regardless of image count.

When crash consistency is acceptable

Acceptable when the workload's own recovery handles it:
  a journalling filesystem holding files
  a database honouring fsync, on a single image
  a stateless workload whose disk is reproducible

Not acceptable when:
  data spans images not captured together
  the application caches writes without durability
  recovery on start is untested

Quiz

Production discipline

Check and record whether the guest freeze succeeded — domfsfreeze fails silently to the caller when the agent is absent, leaving snapshots whose consistency level nobody knows. Freeze data filesystems rather than root; an in-guest root freeze can block the thaw itself.

Cross-course references

• Kubernetes: pre-snapshot hooks that fail silently produce the same unknown state
• Linux: a freeze whose thaw path lives inside the frozen scope deadlocks