xref: /openbmc/qemu/docs/tools/qemu-pr-helper.rst (revision 84369d76)
1==================================
2QEMU persistent reservation helper
3==================================
4
5Synopsis
6--------
7
8**qemu-pr-helper** [*OPTION*]
9
10Description
11-----------
12
13Implements the persistent reservation helper for QEMU.
14
15SCSI persistent reservations allow restricting access to block devices
16to specific initiators in a shared storage setup.  When implementing
17clustering of virtual machines, it is a common requirement for virtual
18machines to send persistent reservation SCSI commands.  However,
19the operating system restricts sending these commands to unprivileged
20programs because incorrect usage can disrupt regular operation of the
21storage fabric. QEMU's SCSI passthrough devices ``scsi-block``
22and ``scsi-generic`` support passing guest persistent reservation
23requests to a privileged external helper program. :program:`qemu-pr-helper`
24is that external helper; it creates a listener socket which will
25accept incoming connections for communication with QEMU.
26
27If you want to run VMs in a setup like this, this helper should be
28started as a system service, and you should read the QEMU manual
29section on "persistent reservation managers" to find out how to
30configure QEMU to connect to the socket created by
31:program:`qemu-pr-helper`.
32
33After connecting to the socket, :program:`qemu-pr-helper` can
34optionally drop root privileges, except for those capabilities that
35are needed for its operation.
36
37:program:`qemu-pr-helper` can also use the systemd socket activation
38protocol.  In this case, the systemd socket unit should specify a
39Unix stream socket, like this::
40
41    [Socket]
42    ListenStream=/var/run/qemu-pr-helper.sock
43
44Options
45-------
46
47.. program:: qemu-pr-helper
48
49.. option:: -d, --daemon
50
51  run in the background (and create a PID file)
52
53.. option:: -q, --quiet
54
55  decrease verbosity
56
57.. option:: -v, --verbose
58
59  increase verbosity
60
61.. option:: -f, --pidfile=PATH
62
63  PID file when running as a daemon. By default the PID file
64  is created in the system runtime state directory, for example
65  :file:`/var/run/qemu-pr-helper.pid`.
66
67.. option:: -k, --socket=PATH
68
69  path to the socket. By default the socket is created in
70  the system runtime state directory, for example
71  :file:`/var/run/qemu-pr-helper.sock`.
72
73.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
74
75  .. include:: ../qemu-option-trace.rst.inc
76
77.. option:: -u, --user=USER
78
79  user to drop privileges to
80
81.. option:: -g, --group=GROUP
82
83  group to drop privileges to
84
85.. option:: -h, --help
86
87  Display a help message and exit.
88
89.. option:: -V, --version
90
91  Display version information and exit.
92