diff --git a/docs/meson.build b/docs/meson.build index bf8204a08f..ebd85d59f9 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -60,6 +60,7 @@ if build_docs 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), 'qemu-nbd.8': (have_tools ? 'man8' : ''), + 'qemu-pr-helper.8': (have_tools ? 'man8' : ''), 'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''), 'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''), 'virtiofsd.1': (have_virtiofsd ? 'man1' : ''), diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst index 9b1de198b1..3f5b9f94dc 100644 --- a/docs/system/pr-manager.rst +++ b/docs/system/pr-manager.rst @@ -50,39 +50,11 @@ Alternatively, using ``-blockdev``:: -blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0 -device scsi-block,drive=hd ----------------------------------- -Invoking :program:`qemu-pr-helper` ----------------------------------- - -QEMU provides an implementation of the persistent reservation helper, -called :program:`qemu-pr-helper`. The helper should be started as a -system service and supports the following option: - --d, --daemon run in the background --q, --quiet decrease verbosity --v, --verbose increase verbosity --f, --pidfile=path PID file when running as a daemon --k, --socket=path path to the socket --T, --trace=trace-opts tracing options - -By default, the socket and PID file are placed in the runtime state -directory, for example :file:`/var/run/qemu-pr-helper.sock` and -:file:`/var/run/qemu-pr-helper.pid`. The PID file is not created -unless :option:`-d` is passed too. - -: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 - -After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop -root privileges, except for those capabilities that are needed for -its operation. To do this, add the following options: - --u, --user=user user to drop privileges to --g, --group=group group to drop privileges to +You will also need to ensure that the helper program +:command:`qemu-pr-helper` is running, and that it has been +set up to use the same socket filename as your QEMU commandline +specifies. See the qemu-pr-helper documentation or manpage for +further details. --------------------------------------------- Multipath devices and persistent reservations diff --git a/docs/tools/conf.py b/docs/tools/conf.py index 9052d17d6d..4760d36ff2 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 '], 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 232ce9f3e4..b99f86c7c6 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 0000000000..ac036180ac --- /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.