| 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. |