diff options
author | Peter Maydell <peter.maydell@linaro.org> | 2020-11-12 14:40:40 +0000 |
---|---|---|
committer | Peter Maydell <peter.maydell@linaro.org> | 2020-11-23 11:10:04 +0000 |
commit | 773ee3f1ea50eb996cced930cc29b1b27bfbc6fa (patch) | |
tree | 2e5952023dd1b0ffdc4a1c4357beea9bd4a6ec15 /docs/tools | |
parent | 0daf34fd3a18aa2a43217c320e2a39d69e52d3f4 (diff) | |
download | qemu-773ee3f1ea50eb996cced930cc29b1b27bfbc6fa.zip qemu-773ee3f1ea50eb996cced930cc29b1b27bfbc6fa.tar.gz qemu-773ee3f1ea50eb996cced930cc29b1b27bfbc6fa.tar.bz2 |
docs: Split qemu-pr-helper documentation into tools manual
Split the documentation of the qemu-pr-helper binary into the tools
manual, and give it a manpage like our other standalone executables.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Diffstat (limited to 'docs/tools')
-rw-r--r-- | docs/tools/conf.py | 2 | ||||
-rw-r--r-- | docs/tools/index.rst | 1 | ||||
-rw-r--r-- | docs/tools/qemu-pr-helper.rst | 90 |
3 files changed, 93 insertions, 0 deletions
diff --git a/docs/tools/conf.py b/docs/tools/conf.py index 9052d17..4760d36 100644 --- a/docs/tools/conf.py +++ b/docs/tools/conf.py @@ -22,6 +22,8 @@ man_pages = [ ['Fabrice Bellard'], 1), ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server', ['Anthony Liguori <anthony@codemonkey.ws>'], 8), + ('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper', + [], 8), ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool', [], 1), ('virtfs-proxy-helper', 'virtfs-proxy-helper', diff --git a/docs/tools/index.rst b/docs/tools/index.rst index 232ce9f..b99f86c 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -12,6 +12,7 @@ Contents: qemu-img qemu-nbd + qemu-pr-helper qemu-trace-stap virtfs-proxy-helper virtiofsd diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst new file mode 100644 index 0000000..ac03618 --- /dev/null +++ b/docs/tools/qemu-pr-helper.rst @@ -0,0 +1,90 @@ +QEMU persistent reservation helper +================================== + +Synopsis +-------- + +**qemu-pr-helper** [*OPTION*] + +Description +----------- + +Implements the persistent reservation helper for QEMU. + +SCSI persistent reservations allow restricting access to block devices +to specific initiators in a shared storage setup. When implementing +clustering of virtual machines, it is a common requirement for virtual +machines to send persistent reservation SCSI commands. However, +the operating system restricts sending these commands to unprivileged +programs because incorrect usage can disrupt regular operation of the +storage fabric. QEMU's SCSI passthrough devices ``scsi-block`` +and ``scsi-generic`` support passing guest persistent reservation +requests to a privileged external helper program. :program:`qemu-pr-helper` +is that external helper; it creates a socket which QEMU can +connect to to communicate with it. + +If you want to run VMs in a setup like this, this helper should be +started as a system service, and you should read the QEMU manual +section on "persistent reservation managers" to find out how to +configure QEMU to connect to the socket created by +:program:`qemu-pr-helper`. + +After connecting to the socket, :program:`qemu-pr-helper` can +optionally drop root privileges, except for those capabilities that +are needed for its operation. + +:program:`qemu-pr-helper` can also use the systemd socket activation +protocol. In this case, the systemd socket unit should specify a +Unix stream socket, like this:: + + [Socket] + ListenStream=/var/run/qemu-pr-helper.sock + +Options +------- + +.. program:: qemu-pr-helper + +.. option:: -d, --daemon + + run in the background (and create a PID file) + +.. option:: -q, --quiet + + decrease verbosity + +.. option:: -v, --verbose + + increase verbosity + +.. option:: -f, --pidfile=PATH + + PID file when running as a daemon. By default the PID file + is created in the system runtime state directory, for example + :file:`/var/run/qemu-pr-helper.pid`. + +.. option:: -k, --socket=PATH + + path to the socket. By default the socket is created in + the system runtime state directory, for example + :file:`/var/run/qemu-pr-helper.sock`. + +.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] + + .. include:: ../qemu-option-trace.rst.inc + +.. option:: -u, --user=USER + + user to drop privileges to + +.. option:: -g, --group=GROUP + + group to drop privileges to + +.. option:: -h, --help + + Display a help message and exit. + +.. option:: -V, --version + + Display version information and exit. |