docs: Split qemu-pr-helper documentation into tools manual
[qemu.git] / docs / system / pr-manager.rst
1 ======================================
2 Persistent reservation managers
3 ======================================
4
5 SCSI persistent Reservations allow restricting access to block devices
6 to specific initiators in a shared storage setup.  When implementing
7 clustering of virtual machines, it is a common requirement for virtual
8 machines to send persistent reservation SCSI commands.  However,
9 the operating system restricts sending these commands to unprivileged
10 programs because incorrect usage can disrupt regular operation of the
11 storage fabric.
12
13 For this reason, QEMU's SCSI passthrough devices, ``scsi-block``
14 and ``scsi-generic`` (both are only available on Linux) can delegate
15 implementation of persistent reservations to a separate object,
16 the "persistent reservation manager".  Only PERSISTENT RESERVE OUT and
17 PERSISTENT RESERVE IN commands are passed to the persistent reservation
18 manager object; other commands are processed by QEMU as usual.
19
20 -----------------------------------------
21 Defining a persistent reservation manager
22 -----------------------------------------
23
24 A persistent reservation manager is an instance of a subclass of the
25 "pr-manager" QOM class.
26
27 Right now only one subclass is defined, ``pr-manager-helper``, which
28 forwards the commands to an external privileged helper program
29 over Unix sockets.  The helper program only allows sending persistent
30 reservation commands to devices for which QEMU has a file descriptor,
31 so that QEMU will not be able to effect persistent reservations
32 unless it has access to both the socket and the device.
33
34 ``pr-manager-helper`` has a single string property, ``path``, which
35 accepts the path to the helper program's Unix socket.  For example,
36 the following command line defines a ``pr-manager-helper`` object and
37 attaches it to a SCSI passthrough device::
38
39       $ qemu-system-x86_64
40           -device virtio-scsi \
41           -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock
42           -drive if=none,id=hd,driver=raw,file.filename=/dev/sdb,file.pr-manager=helper0
43           -device scsi-block,drive=hd
44
45 Alternatively, using ``-blockdev``::
46
47       $ qemu-system-x86_64
48           -device virtio-scsi \
49           -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock
50           -blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0
51           -device scsi-block,drive=hd
52
53 You will also need to ensure that the helper program
54 :command:`qemu-pr-helper` is running, and that it has been
55 set up to use the same socket filename as your QEMU commandline
56 specifies. See the qemu-pr-helper documentation or manpage for
57 further details.
58
59 ---------------------------------------------
60 Multipath devices and persistent reservations
61 ---------------------------------------------
62
63 Proper support of persistent reservation for multipath devices requires
64 communication with the multipath daemon, so that the reservation is
65 registered and applied when a path is newly discovered or becomes online
66 again.  :command:`qemu-pr-helper` can do this if the ``libmpathpersist``
67 library was available on the system at build time.
68
69 As of August 2017, a reservation key must be specified in ``multipath.conf``
70 for ``multipathd`` to check for persistent reservation for newly
71 discovered paths or reinstated paths.  The attribute can be added
72 to the ``defaults`` section or the ``multipaths`` section; for example::
73
74     multipaths {
75         multipath {
76             wwid   XXXXXXXXXXXXXXXX
77             alias      yellow
78             reservation_key  0x123abc
79         }
80     }
81
82 Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede
83 its usage on regular SCSI devices.