docs/tools/qemu-pr-helper.rst

   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.