QEMU-PR-HELPER(8)

💖 qemu-pr-helper(8) — the QEMU persistent reservation helper, bestie edition 💖

okay so before we even get into it — this is the manual page for qemu-pr-helper, coming at you from the QEMU fam. grab a snack, it's giving "niche but iconic" 🍓

---

✨ NAME ✨

qemu-pr-helper — the QEMU persistent reservation helper. yes that's the whole name. she's a helper, she's persistent, she's reserved. main character energy fr 💅

---

🦋 SYNOPSIS 🦋

qemu-pr-helper [OPTION]

literally that's it. one binary, a bunch of options, no cap.

---

🌸 DESCRIPTION 🌸

So. This thing implements the persistent reservation helper for QEMU. That's the vibe.

SCSI persistent reservations are how you restrict access to block devices to specific initiators in a shared storage setup — think VIP list but for storage. When you're implementing clustering of virtual machines, it's a super common requirement for VMs to send persistent reservation SCSI commands. highkey essential.

But here's the plot twist 😭 the operating system restricts sending these commands to unprivileged programs, because incorrect usage can disrupt regular operation of the storage fabric. like, actually disrupt it. so yeah, the OS is being a protective parent and honestly valid for it.

Enter: QEMU's SCSI passthrough devices scsi-block and scsi-generic, which support passing guest persistent reservation requests to a privileged external helper program. And qemu-pr-helper IS that external helper. she creates a listener socket which will accept incoming connections for communication with QEMU. networking era ✨

If you want to run VMs in a setup like this, this helper should be started as a system service, and you should read the QEMU manual section on "persistent reservation managers" to find out how to configure QEMU to connect to the socket created by qemu-pr-helper. iykyk, go read the docs, they're right there 🫶

After connecting to the socket, qemu-pr-helper can optionally drop root privileges, except for those capabilities that are needed for its operation. so she can glow down the privileges but keep the ones she actually needs. queen behavior 👑

qemu-pr-helper can also use the systemd socket activation protocol. In this case, the systemd socket unit should specify a Unix stream socket, like this:

[Socket]
ListenStream=/var/run/qemu-pr-helper.sock

copy paste slay. that's the whole config bestie 💖

---

🎀 OPTIONS 🎀

• -d, --daemon — run in the background (and create a PID file). ghost mode activated 👻
• -q, --quiet — decrease verbosity. she's being chill, she's not gonna overshare.
• -v, --verbose — increase verbosity. okay now she's telling you EVERYTHING that happened in her day.
• -f, --pidfile=PATH — the PID file when running as a daemon. By default the PID file is created in the system runtime state directory, for example /var/run/qemu-pr-helper.pid. so like, she'll put it in the default spot unless you tell her otherwise 🗂️
• -k, --socket=PATH — path to the socket. By default the socket is created in the system runtime state directory, for example /var/run/qemu-pr-helper.sock. same deal — default location unless you say something 💫
• -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] — specify tracing options. this one's got layers, buckle up:
  • [enable=]PATTERN — immediately enable events matching PATTERN (either event name or a globbing pattern). This option is only available if QEMU has been compiled with the simple, log or ftrace tracing backend. To specify multiple events or patterns, specify the -trace option multiple times. Also, use -trace help to print a list of names of trace points. very "ask for the menu" of her.
  • events=FILE — immediately enable events listed in FILE. The file must contain one event name (as listed in the trace-events-all file) per line; globbing patterns are accepted too. This option is only available if QEMU has been compiled with the simple, log or ftrace tracing backend. one event per line, no chaos, we love a list 🧚
  • file=FILE — log output traces to FILE. This option is only available if QEMU has been compiled with the simple tracing backend. only the simple backend gets this one, sorry to the other backends 💀
• -u, --user=USER — the user to drop privileges to. glow-down time 🦋
• -g, --group=GROUP — the group to drop privileges to. matching set, obviously.
• -h, --help — display a help message and exit. she'll explain herself, briefly, then dip.
• -V, --version — display version information and exit. she'll tell you who she is, then dip. iconic.

---

👑 Copyright 👑

2026, The QEMU Project Developers — putting that here so nobody forgets who raised her 💜

---

aaaand that's the whole page bestie!! no notes, she ate 🔥

this little sign-off is brought to you by version 11.1.3, dated Oct 29, 2026, and yes it's still QEMU-PR-HELPER(8) — mwah 💋