Proxmox PVE Virtual Environment QEMU Agent Freeze und Thaw Skripte bei Snapshot ausführen pre-freeze-script post-thaw-script

Changelog:

• 11.05.2025 erste Version

---

Vorwort

Ich war auf der Suche wie man bei einem Snapshot eigene Skripte ausführen lassen kann. Unter VMware nutze ich das schon seit Jahren um ein Hot-Backup von MySQL-Datenbanken auszuführen.
Dabei wird unmittelbar vor einem Snapshot ein pre-freeze-script ausgeführt welches die Datenbank flusht und weitere Schreibzugriffe blockiert und unmittelbar danach ein post-thaw-script welches den Schreibzugriff wieder freigibt. Zwischen der Ausführung der beiden Skripte liegen dabei nur wenige Sekunden.
Das Backup kann danach die vollständige VM wegsichern und es ist sichergestellt das die Datenbank im inneren Konsistent ist.

Das muss doch auch unter Proxmox PVE gehen ... jupp, es geht!<vr> Da das ganz kein Selbstläufer war - ich musste mir das wieder aus verschiedenen Webseiten und Quellen zusammensuchen.

---

Voraussetzungen

Damit das ganze funktioniert müssen in der VM die QEMU-Tools installiert sein.
Unter Ubuntu / Debian z.B. mit

apt install qemu-guest-agent
systemctl enable qemu-guest-agent.service
systemctl start qemu-guest-agent.service

Unter Windows muss man diese per ISO installieren:

https://pve.proxmox.com/wiki/Windows_VirtIO_Drivers

Siehe auch: https://pve.proxmox.com/wiki/Qemu-guest-agent
Zusätzlich muss in der Option der VM der QEMU Guest Agent aktiviert sein:

Ob der Agent auch läuft und Funktioniert, kann man unter anderen in der Summary daran sehen das dort die IPs der VM zu sehen sind:

---

Linux

Es sollte ein Verzeichnis

/etc/qemu

geben in welchem ein Skript und ein Verzeichnis liegt:

/etc/qemu/
├── fsfreeze-hook
└── fsfreeze-hook.d

Das Skript wird bei jedem Snapshot 2x aufgerufen. Diese startet wiederum jedes Skript im Unterverzeichnis

/etc/qemu/fsfreeze-hook.d/

Dabei werden die Skripte beim ersten mal, unmittelbar vor dem Snapshot mit dem Parameter freeze aufgerufen und danach mit dem Parameter thaw.
Leider wird das Skript "ab Werk" nicht gestartet, das der QEMU Agent das beachten soll muss man diesem erst in die Konfiguration schreiben - und die gibt es nicht ...
Wir könnten das direkt in den Aufruf des Dienstes per qemu-guest-agent.service schreiben, eleganter geht es wie folgt:

qemu-ga -D > /etc/qemu/qemu-ga.conf

Schreibt die aktuell gültige Konfiguration in die Datei /etc/qemu/qemu-ga.conf, diese müssen wir danach aber unbedingt bearbeiten:

nano /etc/qemu/qemu-ga.conf

und wie folgt abändern:

[general]
daemon=false
method=virtio-serial
path=/dev/virtio-ports/org.qemu.guest_agent.0
pidfile=/var/run/qemu-ga.pid
statedir=/var/run
verbose=false
retry-path=false
# block-rpcs=
# allow-rpcs=
fsfreeze-hook=/etc/qemu/fsfreeze-hook

Die beiden gelben Zeilen müsst Ihr unbedingt auskommentieren (oder ganz löschen), sonst startet der Dienst hinterher nicht mehr (es darf nur eine der beiden Zeilen zur gleichen Zeit angegeben sein),
die grüne Zeile sorgt dafür das das /etc/qemu/fsfreeze-hook in Zukunft auch aufgerufen wird.
Speichert die Datei und startet den Dienst einmal neu:

systemctl restart qemu-guest-agent.service

und prüft ob das geklappt hat - wenn in der Konfigurationsdatei etwas falsch eingetragen ist, startet dieser eben nicht:

systemctl status qemu-guest-agent.service

Beispielausgabe:

● qemu-guest-agent.service - QEMU Guest Agent
     Loaded: loaded (/usr/lib/systemd/system/qemu-guest-agent.service; static)
     Active: active (running) since Sun 2025-05-11 14:33:02 CEST; 43s ago
   Main PID: 252408 (qemu-ga)
      Tasks: 2 (limit: 4609)
     Memory: 404.0K (peak: 424.0K)
        CPU: 27ms
     CGroup: /system.slice/qemu-guest-agent.service
             └─252408 /usr/sbin/qemu-ga

Zum testen erstellen wir das folgende Skript:

nano /etc/qemu/fsfreeze-hook.d/test.sh

mit folgendem Inhalt:

#!/bin/bash
LOGFILE="/tmp/test-snapshot.log"
if [[ "$1" == "freeze" ]]; then
    echo "-------------------------------------------------------------------------------------" >> $LOGFILE
    echo "$0 $(date '+%Y-%m-%d %H:%M:%S') pre-freeze called" >> $LOGFILE
elif [[ "$1" == "thaw" ]]; then
    echo "$0 $(date '+%Y-%m-%d %H:%M:%S') post-thaw called" >> $LOGFILE
else
    echo "-------------------------------------------------------------------------------------" >> $LOGFILE
    echo "$0 $(date '+%Y-%m-%d %H:%M:%S') unkown parameter: $1" >> $LOGFILE
fi

und die Datei ausführbar machen:

chmod +x /etc/qemu/fsfreeze-hook.d/test.sh

Jetzt erstellt einen Snapshot auf der VM:

und schaut euch hinterher den Inhalt der Logdatei an:

-------------------------------------------------------------------------------------
/etc/qemu/fsfreeze-hook.d/test.sh 2025-05-11 14:51:04 pre-freeze called
/etc/qemu/fsfreeze-hook.d/test.sh 2025-05-11 14:51:05 post-thaw called

Nach dem Beispiel könnt Ihr nun also eure eigenen Skripte aufbauen.
Es darf halt nur ein Skript sein welches auf die Schlüsselwörter freeze und thaw reagiert.

---

Windows

Wie in der Proxmox-Doku steht: https://pve.proxmox.com/wiki/VM_Backup_Consistency#Windows
wird per Default schon der VSS-Provider verwendet.

Bisher habe ich es nicht geschafft, über die QEMU-Tools ein Skript auszuführen.
Ich habe das zwar in die Konfig mit eingebaut (und den dienst per Parameter explizit damit gestartet), er ignoriert es aber scheinbar.
Wenn man sich die Hilfe der Windows-Version ausgeben lässt:

C:\Program Files\Qemu-ga>qemu-ga.exe --help
Usage: qemu-ga.exe [-m <method> -p <path>] [<options>]
QEMU Guest Agent 109.1.0
Copyright (c) 2003-2024 Fabrice Bellard and the QEMU Project developers

  -c, --config=PATH configuration file path (default is
                    C:\Program Files\Qemu-ga/etc/\qemu-ga.conf/qemu-ga.conf
                    unless overridden by the QGA_CONF environment variable)
  -m, --method      transport method: one of unix-listen, virtio-serial,
                    isa-serial, or vsock-listen (virtio-serial is the default)
  -p, --path        device/socket path (the default for virtio-serial is:
                    \\.\Global\org.qemu.guest_agent.0,
                    the default for isa-serial is:
                    COM1).
                    Socket addresses for vsock-listen are written as
                    <cid>:<port>.
  -l, --logfile     set logfile path, logs to stderr by default
  -f, --pidfile     specify pidfile (default is C:\ProgramData\qemu-ga\qemu-ga.pid)
  -t, --statedir    specify dir to store state information (absolute paths
                    only, default is C:\ProgramData\qemu-ga)
  -v, --verbose     log extra debugging information
  -V, --version     print version information and exit
  -d, --daemonize   become a daemon
  -s, --service     service commands: install, uninstall, vss-install, vss-uninstall
  -b, --block-rpcs  comma-separated list of RPCs to disable (no spaces,
                    use "--block-rpcs=help" to list available RPCs)
  -a, --allow-rpcs  comma-separated list of RPCs to enable (no spaces,
                    use "--allow-rpcs=help" to list available RPCs)
  -D, --dump-conf   dump a qemu-ga config file based on current config
                    options / command-line parameters to stdout
  -r, --retry-path  attempt re-opening path if it's unavailable or closed
                    due to an error which may be recoverable in the future
                    (virtio-serial driver re-install, serial device hot
                    plug/unplug, etc.)
  -h, --help        display this help and exit

See <https://qemu.org/contribute/report-a-bug> for how to report bugs.
More information on the QEMU project at <https://qemu.org>.

sieht man das in der Windows Version der Parameter -F bzw. --fsfreeze-hook schlichtweg ganz fehlt.

Es gibt in der Ereignisanzeige einen Eintrag:

Da könnte drauf triggern, aber es ist eben nur ein Eintrag.
Ich habe mit dem Prozess-Explorer von Systinternals zugesehen, da sehe ich aber auch nicht einmal einen Versuch des Zugriffs.

Hier ein paar Funde aus dem Internet dazu:

• https://forum.proxmox.com/threads/backup-script-hook-missing-events.138077/
• https://forum.proxmox.com/threads/application-aware-processing-for-linux-and-windows-database-servers-tmanok.107430/

---

Quellen

• https://pve.proxmox.com/wiki/Qemu-guest-agent
• https://forum.proxmox.com/threads/freeze-thaw-scripts.144091/
• https://forum.proxmox.com/threads/fsfreeze-hook-is-not-getting-triggered-at-the-time-of-backup.82680/#post-364099
• https://pve.proxmox.com/wiki/VM_Backup_Consistency#Windows

Kommentare

Loading comments...