18a1f7d29SPaolo Bonzini================================== 2773ee3f1SPeter MaydellQEMU persistent reservation helper 3773ee3f1SPeter Maydell================================== 4773ee3f1SPeter Maydell 5773ee3f1SPeter MaydellSynopsis 6773ee3f1SPeter Maydell-------- 7773ee3f1SPeter Maydell 8773ee3f1SPeter Maydell**qemu-pr-helper** [*OPTION*] 9773ee3f1SPeter Maydell 10773ee3f1SPeter MaydellDescription 11773ee3f1SPeter Maydell----------- 12773ee3f1SPeter Maydell 13773ee3f1SPeter MaydellImplements the persistent reservation helper for QEMU. 14773ee3f1SPeter Maydell 15773ee3f1SPeter MaydellSCSI persistent reservations allow restricting access to block devices 16773ee3f1SPeter Maydellto specific initiators in a shared storage setup. When implementing 17773ee3f1SPeter Maydellclustering of virtual machines, it is a common requirement for virtual 18773ee3f1SPeter Maydellmachines to send persistent reservation SCSI commands. However, 19773ee3f1SPeter Maydellthe operating system restricts sending these commands to unprivileged 20773ee3f1SPeter Maydellprograms because incorrect usage can disrupt regular operation of the 21773ee3f1SPeter Maydellstorage fabric. QEMU's SCSI passthrough devices ``scsi-block`` 22773ee3f1SPeter Maydelland ``scsi-generic`` support passing guest persistent reservation 23773ee3f1SPeter Maydellrequests to a privileged external helper program. :program:`qemu-pr-helper` 247a21bee2SDaniel P. Berrangéis that external helper; it creates a listener socket which will 257a21bee2SDaniel P. Berrangéaccept incoming connections for communication with QEMU. 26773ee3f1SPeter Maydell 27773ee3f1SPeter MaydellIf you want to run VMs in a setup like this, this helper should be 28773ee3f1SPeter Maydellstarted as a system service, and you should read the QEMU manual 29773ee3f1SPeter Maydellsection on "persistent reservation managers" to find out how to 30773ee3f1SPeter Maydellconfigure QEMU to connect to the socket created by 31773ee3f1SPeter Maydell:program:`qemu-pr-helper`. 32773ee3f1SPeter Maydell 33773ee3f1SPeter MaydellAfter connecting to the socket, :program:`qemu-pr-helper` can 34773ee3f1SPeter Maydelloptionally drop root privileges, except for those capabilities that 35773ee3f1SPeter Maydellare needed for its operation. 36773ee3f1SPeter Maydell 37773ee3f1SPeter Maydell:program:`qemu-pr-helper` can also use the systemd socket activation 38773ee3f1SPeter Maydellprotocol. In this case, the systemd socket unit should specify a 39773ee3f1SPeter MaydellUnix stream socket, like this:: 40773ee3f1SPeter Maydell 41773ee3f1SPeter Maydell [Socket] 42773ee3f1SPeter Maydell ListenStream=/var/run/qemu-pr-helper.sock 43773ee3f1SPeter Maydell 44773ee3f1SPeter MaydellOptions 45773ee3f1SPeter Maydell------- 46773ee3f1SPeter Maydell 47773ee3f1SPeter Maydell.. program:: qemu-pr-helper 48773ee3f1SPeter Maydell 49773ee3f1SPeter Maydell.. option:: -d, --daemon 50773ee3f1SPeter Maydell 51773ee3f1SPeter Maydell run in the background (and create a PID file) 52773ee3f1SPeter Maydell 53773ee3f1SPeter Maydell.. option:: -q, --quiet 54773ee3f1SPeter Maydell 55773ee3f1SPeter Maydell decrease verbosity 56773ee3f1SPeter Maydell 57773ee3f1SPeter Maydell.. option:: -v, --verbose 58773ee3f1SPeter Maydell 59773ee3f1SPeter Maydell increase verbosity 60773ee3f1SPeter Maydell 61773ee3f1SPeter Maydell.. option:: -f, --pidfile=PATH 62773ee3f1SPeter Maydell 63773ee3f1SPeter Maydell PID file when running as a daemon. By default the PID file 64773ee3f1SPeter Maydell is created in the system runtime state directory, for example 65773ee3f1SPeter Maydell :file:`/var/run/qemu-pr-helper.pid`. 66773ee3f1SPeter Maydell 67773ee3f1SPeter Maydell.. option:: -k, --socket=PATH 68773ee3f1SPeter Maydell 69773ee3f1SPeter Maydell path to the socket. By default the socket is created in 70773ee3f1SPeter Maydell the system runtime state directory, for example 71773ee3f1SPeter Maydell :file:`/var/run/qemu-pr-helper.sock`. 72773ee3f1SPeter Maydell 73773ee3f1SPeter Maydell.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] 74773ee3f1SPeter Maydell 75773ee3f1SPeter Maydell .. include:: ../qemu-option-trace.rst.inc 76773ee3f1SPeter Maydell 77773ee3f1SPeter Maydell.. option:: -u, --user=USER 78773ee3f1SPeter Maydell 79773ee3f1SPeter Maydell user to drop privileges to 80773ee3f1SPeter Maydell 81773ee3f1SPeter Maydell.. option:: -g, --group=GROUP 82773ee3f1SPeter Maydell 83773ee3f1SPeter Maydell group to drop privileges to 84773ee3f1SPeter Maydell 85773ee3f1SPeter Maydell.. option:: -h, --help 86773ee3f1SPeter Maydell 87773ee3f1SPeter Maydell Display a help message and exit. 88773ee3f1SPeter Maydell 89773ee3f1SPeter Maydell.. option:: -V, --version 90773ee3f1SPeter Maydell 91773ee3f1SPeter Maydell Display version information and exit. 92