]>
Commit | Line | Data |
---|---|---|
c6ff7856 | 1 | =============================== |
7c9e5276 | 2 | Persistent reservation managers |
c6ff7856 | 3 | =============================== |
7c9e5276 | 4 | |
c6ff7856 | 5 | SCSI persistent reservations allow restricting access to block devices |
7c9e5276 PB |
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 | |
b855f8d1 | 52 | |
773ee3f1 PM |
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. | |
fe8fc5ae PB |
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. |