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