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