1QEMU-PR-HELPER(8)                    QEMU                    QEMU-PR-HELPER(8)
2
3
4

NAME

6       qemu-pr-helper - QEMU persistent reservation helper
7

SYNOPSIS

9       qemu-pr-helper [OPTION]
10

DESCRIPTION

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,  the
18       operating  system restricts sending these commands to unprivileged pro‐
19       grams because incorrect usage can  disrupt  regular  operation  of  the
20       storage   fabric.   QEMU's  SCSI  passthrough  devices  scsi-block  and
21       scsi-generic support passing guest persistent reservation requests to a
22       privileged  external  helper  program.  qemu-pr-helper is that external
23       helper; it creates a listener socket which will accept incoming connec‐
24       tions for communication with QEMU.
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  sec‐
28       tion  on "persistent reservation managers" to find out how to configure
29       QEMU to connect to the socket created by qemu-pr-helper.
30
31       After connecting to the socket, qemu-pr-helper can optionally drop root
32       privileges, except for those capabilities that are needed for its oper‐
33       ation.
34
35       qemu-pr-helper can also use the systemd socket activation protocol.  In
36       this case, the systemd socket unit should specify a Unix stream socket,
37       like this:
38
39          [Socket]
40          ListenStream=/var/run/qemu-pr-helper.sock
41

OPTIONS

43       -d, --daemon
44              run in the background (and create a PID file)
45
46       -q, --quiet
47              decrease verbosity
48
49       -v, --verbose
50              increase verbosity
51
52       -f, --pidfile=PATH
53              PID file when running as a daemon. By default the  PID  file  is
54              created  in  the  system  runtime  state  directory, for example
55              /var/run/qemu-pr-helper.pid.
56
57       -k, --socket=PATH
58              path to the socket. By default the socket is created in the sys‐
59              tem      runtime      state      directory,      for     example
60              /var/run/qemu-pr-helper.sock.
61
62       -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
63              Specify tracing options.
64
65              [enable=]PATTERN
66                 Immediately enable events matching PATTERN (either event name
67                 or  a  globbing  pattern).   This option is only available if
68                 QEMU has been compiled with the simple, log or ftrace tracing
69                 backend.  To specify multiple events or patterns, specify the
70                 -trace option multiple times.
71
72                 Use -trace help to print a list of names of trace points.
73
74              events=FILE
75                 Immediately enable events listed in FILE.  The file must con‐
76                 tain  one event name (as listed in the trace-events-all file)
77                 per line; globbing patterns are accepted too.  This option is
78                 only available if QEMU has been compiled with the simple, log
79                 or ftrace tracing backend.
80
81              file=FILE
82                 Log output traces to FILE.  This option is only available  if
83                 QEMU has been compiled with the simple tracing backend.
84
85       -u, --user=USER
86              user to drop privileges to
87
88       -g, --group=GROUP
89              group to drop privileges to
90
91       -h, --help
92              Display a help message and exit.
93
94       -V, --version
95              Display version information and exit.
96

98       2023, The QEMU Project Developers
99
100
101
102
1038.1.3                            Nov 28, 2023                QEMU-PR-HELPER(8)
Impressum