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