docs/tools/qemu-pr-helper.rst

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