1======================================
2Persistent reservation managers
3======================================
4
5SCSI persistent Reservations allow restricting access to block devices
6to specific initiators in a shared storage setup.  When implementing
7clustering of virtual machines, it is a common requirement for virtual
8machines to send persistent reservation SCSI commands.  However,
9the operating system restricts sending these commands to unprivileged
10programs because incorrect usage can disrupt regular operation of the
11storage fabric.
12
13For this reason, QEMU's SCSI passthrough devices, ``scsi-block``
14and ``scsi-generic`` (both are only available on Linux) can delegate
15implementation of persistent reservations to a separate object,
16the "persistent reservation manager".  Only PERSISTENT RESERVE OUT and
17PERSISTENT RESERVE IN commands are passed to the persistent reservation
18manager object; other commands are processed by QEMU as usual.
19
20-----------------------------------------
21Defining a persistent reservation manager
22-----------------------------------------
23
24A persistent reservation manager is an instance of a subclass of the
25"pr-manager" QOM class.
26
27Right now only one subclass is defined, ``pr-manager-helper``, which
28forwards the commands to an external privileged helper program
29over Unix sockets.  The helper program only allows sending persistent
30reservation commands to devices for which QEMU has a file descriptor,
31so that QEMU will not be able to effect persistent reservations
32unless it has access to both the socket and the device.
33
34``pr-manager-helper`` has a single string property, ``path``, which
35accepts the path to the helper program's Unix socket.  For example,
36the following command line defines a ``pr-manager-helper`` object and
37attaches 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
45Alternatively, 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----------------------------------
54Invoking :program:`qemu-pr-helper`
55----------------------------------
56
57QEMU provides an implementation of the persistent reservation helper,
58called :program:`qemu-pr-helper`.  The helper should be started as a
59system service and supports the following option:
60
61-d, --daemon              run in the background
62-q, --quiet               decrease verbosity
63-v, --verbose             increase verbosity
64-f, --pidfile=path        PID file when running as a daemon
65-k, --socket=path         path to the socket
66-T, --trace=trace-opts    tracing options
67
68By default, the socket and PID file are placed in the runtime state
69directory, for example :file:`/var/run/qemu-pr-helper.sock` and
70:file:`/var/run/qemu-pr-helper.pid`.  The PID file is not created
71unless :option:`-d` is passed too.
72
73:program:`qemu-pr-helper` can also use the systemd socket activation
74protocol.  In this case, the systemd socket unit should specify a
75Unix stream socket, like this::
76
77    [Socket]
78    ListenStream=/var/run/qemu-pr-helper.sock
79
80After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop
81root privileges, except for those capabilities that are needed for
82its operation.  To do this, add the following options:
83
84-u, --user=user           user to drop privileges to
85-g, --group=group         group to drop privileges to
86
87---------------------------------------------
88Multipath devices and persistent reservations
89---------------------------------------------
90
91Proper support of persistent reservation for multipath devices requires
92communication with the multipath daemon, so that the reservation is
93registered and applied when a path is newly discovered or becomes online
94again.  :command:`qemu-pr-helper` can do this if the ``libmpathpersist``
95library was available on the system at build time.
96
97As of August 2017, a reservation key must be specified in ``multipath.conf``
98for ``multipathd`` to check for persistent reservation for newly
99discovered paths or reinstated paths.  The attribute can be added
100to the ``defaults`` section or the ``multipaths`` section; for example::
101
102    multipaths {
103        multipath {
104            wwid   XXXXXXXXXXXXXXXX
105            alias      yellow
106            reservation_key  0x123abc
107        }
108    }
109
110Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede
111its usage on regular SCSI devices.
112