docs/tools/qemu-vmsr-helper.rst

   1 ==================================
   2 QEMU virtual RAPL MSR helper
   3 ==================================
   4
   5 Synopsis
   6 --------
   7
   8 **qemu-vmsr-helper** [*OPTION*]
   9
  10 Description
  11 -----------
  12
  13 Implements the virtual RAPL MSR helper for QEMU.
  14
  15 Accessing the RAPL (Running Average Power Limit) MSR enables the RAPL powercap
  16 driver to advertise and monitor the power consumption or accumulated energy
  17 consumption of different power domains, such as CPU packages, DRAM, and other
  18 components when available.
  19
  20 However those registers are accessible under privileged access (CAP_SYS_RAWIO).
  21 QEMU can use an external helper to access those privileged registers.
  22
  23 :program:`qemu-vmsr-helper` is that external helper; it creates a listener
  24 socket which will accept incoming connections for communication with QEMU.
  25
  26 If you want to run VMs in a setup like this, this helper should be started as a
  27 system service, and you should read the QEMU manual section on "RAPL MSR
  28 support" to find out how to configure QEMU to connect to the socket created by
  29 :program:`qemu-vmsr-helper`.
  30
  31 After connecting to the socket, :program:`qemu-vmsr-helper` can
  32 optionally drop root privileges, except for those capabilities that
  33 are needed for its operation.
  34
  35 :program:`qemu-vmsr-helper` can also use the systemd socket activation
  36 protocol.  In this case, the systemd socket unit should specify a
  37 Unix stream socket, like this::
  38
  39     [Socket]
  40     ListenStream=/var/run/qemu-vmsr-helper.sock
  41
  42 Options
  43 -------
  44
  45 .. program:: qemu-vmsr-helper
  46
  47 .. option:: -d, --daemon
  48
  49   run in the background (and create a PID file)
  50
  51 .. option:: -q, --quiet
  52
  53   decrease verbosity
  54
  55 .. option:: -v, --verbose
  56
  57   increase verbosity
  58
  59 .. option:: -f, --pidfile=PATH
  60
  61   PID file when running as a daemon. By default the PID file
  62   is created in the system runtime state directory, for example
  63   :file:`/var/run/qemu-vmsr-helper.pid`.
  64
  65 .. option:: -k, --socket=PATH
  66
  67   path to the socket. By default the socket is created in
  68   the system runtime state directory, for example
  69   :file:`/var/run/qemu-vmsr-helper.sock`.
  70
  71 .. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
  72
  73   .. include:: ../qemu-option-trace.rst.inc
  74
  75 .. option:: -u, --user=USER
  76
  77   user to drop privileges to
  78
  79 .. option:: -g, --group=GROUP
  80
  81   group to drop privileges to
  82
  83 .. option:: -h, --help
  84
  85   Display a help message and exit.
  86
  87 .. option:: -V, --version
  88
  89   Display version information and exit.