| 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. |