projects / mirror_qemu.git / blame
| Commit | Line | Data |
|---|---|---|
| 773ee3f1 PM |
1 | QEMU persistent reservation helper |
| 2 | ================================== | |
| 3 | ||
| 4 | Synopsis | |
| 5 | -------- | |
| 6 | ||
| 7 | **qemu-pr-helper** [*OPTION*] | |
| 8 | ||
| 9 | Description | |
| 10 | ----------- | |
| 11 | ||
| 12 | Implements the persistent reservation helper for QEMU. | |
| 13 | ||
| 14 | SCSI persistent reservations allow restricting access to block devices | |
| 15 | to specific initiators in a shared storage setup. When implementing | |
| 16 | clustering of virtual machines, it is a common requirement for virtual | |
| 17 | machines to send persistent reservation SCSI commands. However, | |
| 18 | the operating system restricts sending these commands to unprivileged | |
| 19 | programs because incorrect usage can disrupt regular operation of the | |
| 20 | storage fabric. QEMU's SCSI passthrough devices ``scsi-block`` | |
| 21 | and ``scsi-generic`` support passing guest persistent reservation | |
| 22 | requests to a privileged external helper program. :program:`qemu-pr-helper` | |
| 23 | is that external helper; it creates a socket which QEMU can | |
| 24 | connect to to communicate with it. | |
| 25 | ||
| 26 | If you want to run VMs in a setup like this, this helper should be | |
| 27 | started as a system service, and you should read the QEMU manual | |
| 28 | section on "persistent reservation managers" to find out how to | |
| 29 | configure QEMU to connect to the socket created by | |
| 30 | :program:`qemu-pr-helper`. | |
| 31 | ||
| 32 | After connecting to the socket, :program:`qemu-pr-helper` can | |
| 33 | optionally drop root privileges, except for those capabilities that | |
| 34 | are needed for its operation. | |
| 35 | ||
| 36 | :program:`qemu-pr-helper` can also use the systemd socket activation | |
| 37 | protocol. In this case, the systemd socket unit should specify a | |
| 38 | Unix stream socket, like this:: | |
| 39 | ||
| 40 | [Socket] | |
| 41 | ListenStream=/var/run/qemu-pr-helper.sock | |
| 42 | ||
| 43 | Options | |
| 44 | ------- | |
| 45 | ||
| 46 | .. program:: qemu-pr-helper | |
| 47 | ||
| 48 | .. option:: -d, --daemon | |
| 49 | ||
| 50 | run in the background (and create a PID file) | |
| 51 | ||
| 52 | .. option:: -q, --quiet | |
| 53 | ||
| 54 | decrease verbosity | |
| 55 | ||
| 56 | .. option:: -v, --verbose | |
| 57 | ||
| 58 | increase verbosity | |
| 59 | ||
| 60 | .. option:: -f, --pidfile=PATH | |
| 61 | ||
| 62 | PID file when running as a daemon. By default the PID file | |
| 63 | is created in the system runtime state directory, for example | |
| 64 | :file:`/var/run/qemu-pr-helper.pid`. | |
| 65 | ||
| 66 | .. option:: -k, --socket=PATH | |
| 67 | ||
| 68 | path to the socket. By default the socket is created in | |
| 69 | the system runtime state directory, for example | |
| 70 | :file:`/var/run/qemu-pr-helper.sock`. | |
| 71 | ||
| 72 | .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] | |
| 73 | ||
| 74 | .. include:: ../qemu-option-trace.rst.inc | |
| 75 | ||
| 76 | .. option:: -u, --user=USER | |
| 77 | ||
| 78 | user to drop privileges to | |
| 79 | ||
| 80 | .. option:: -g, --group=GROUP | |
| 81 | ||
| 82 | group to drop privileges to | |
| 83 | ||
| 84 | .. option:: -h, --help | |
| 85 | ||
| 86 | Display a help message and exit. | |
| 87 | ||
| 88 | .. option:: -V, --version | |
| 89 | ||
| 90 | Display version information and exit. |