Merge remote-tracking branch 'remotes/cschoenebeck/tags/pull-9p-20211027' into staging
[qemu.git] / docs / tools / qemu-pr-helper.rst
1 ==================================
2 QEMU persistent reservation helper
3 ==================================
4
5 Synopsis
6 --------
7
8 **qemu-pr-helper** [*OPTION*]
9
10 Description
11 -----------
12
13 Implements the persistent reservation helper for QEMU.
14
15 SCSI persistent reservations allow restricting access to block devices
16 to specific initiators in a shared storage setup.  When implementing
17 clustering of virtual machines, it is a common requirement for virtual
18 machines to send persistent reservation SCSI commands.  However,
19 the operating system restricts sending these commands to unprivileged
20 programs because incorrect usage can disrupt regular operation of the
21 storage fabric. QEMU's SCSI passthrough devices ``scsi-block``
22 and ``scsi-generic`` support passing guest persistent reservation
23 requests to a privileged external helper program. :program:`qemu-pr-helper`
24 is that external helper; it creates a socket which QEMU can
25 connect to to communicate with it.
26
27 If you want to run VMs in a setup like this, this helper should be
28 started as a system service, and you should read the QEMU manual
29 section on "persistent reservation managers" to find out how to
30 configure QEMU to connect to the socket created by
31 :program:`qemu-pr-helper`.
32
33 After connecting to the socket, :program:`qemu-pr-helper` can
34 optionally drop root privileges, except for those capabilities that
35 are needed for its operation.
36
37 :program:`qemu-pr-helper` can also use the systemd socket activation
38 protocol.  In this case, the systemd socket unit should specify a
39 Unix stream socket, like this::
40
41     [Socket]
42     ListenStream=/var/run/qemu-pr-helper.sock
43
44 Options
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.