| Peter Maydell | 773ee3f | 2020-11-12 14:40:40 +0000 | [diff] [blame] | 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. |
