From 0daf34fd3a18aa2a43217c320e2a39d69e52d3f4 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:39 +0000 Subject: docs: Move pr-manager.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the pr-manager documentation into the system manual. Some of it (the documentation of the pr-manager-helper tool) should be in tools, but we will split it up after moving it. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/pr-manager.rst | 111 --------------------------------------------- docs/system/index.rst | 1 + docs/system/pr-manager.rst | 111 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 111 deletions(-) delete mode 100644 docs/pr-manager.rst create mode 100644 docs/system/pr-manager.rst (limited to 'docs') diff --git a/docs/pr-manager.rst b/docs/pr-manager.rst deleted file mode 100644 index 9b1de198b1..0000000000 --- a/docs/pr-manager.rst +++ /dev/null @@ -1,111 +0,0 @@ -====================================== -Persistent reservation managers -====================================== - -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. - -For this reason, QEMU's SCSI passthrough devices, ``scsi-block`` -and ``scsi-generic`` (both are only available on Linux) can delegate -implementation of persistent reservations to a separate object, -the "persistent reservation manager". Only PERSISTENT RESERVE OUT and -PERSISTENT RESERVE IN commands are passed to the persistent reservation -manager object; other commands are processed by QEMU as usual. - ------------------------------------------ -Defining a persistent reservation manager ------------------------------------------ - -A persistent reservation manager is an instance of a subclass of the -"pr-manager" QOM class. - -Right now only one subclass is defined, ``pr-manager-helper``, which -forwards the commands to an external privileged helper program -over Unix sockets. The helper program only allows sending persistent -reservation commands to devices for which QEMU has a file descriptor, -so that QEMU will not be able to effect persistent reservations -unless it has access to both the socket and the device. - -``pr-manager-helper`` has a single string property, ``path``, which -accepts the path to the helper program's Unix socket. For example, -the following command line defines a ``pr-manager-helper`` object and -attaches it to a SCSI passthrough device:: - - $ qemu-system-x86_64 - -device virtio-scsi \ - -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock - -drive if=none,id=hd,driver=raw,file.filename=/dev/sdb,file.pr-manager=helper0 - -device scsi-block,drive=hd - -Alternatively, using ``-blockdev``:: - - $ qemu-system-x86_64 - -device virtio-scsi \ - -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock - -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 - ---------------------------------------------- -Multipath devices and persistent reservations ---------------------------------------------- - -Proper support of persistent reservation for multipath devices requires -communication with the multipath daemon, so that the reservation is -registered and applied when a path is newly discovered or becomes online -again. :command:`qemu-pr-helper` can do this if the ``libmpathpersist`` -library was available on the system at build time. - -As of August 2017, a reservation key must be specified in ``multipath.conf`` -for ``multipathd`` to check for persistent reservation for newly -discovered paths or reinstated paths. The attribute can be added -to the ``defaults`` section or the ``multipaths`` section; for example:: - - multipaths { - multipath { - wwid XXXXXXXXXXXXXXXX - alias yellow - reservation_key 0x123abc - } - } - -Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede -its usage on regular SCSI devices. diff --git a/docs/system/index.rst b/docs/system/index.rst index 2a5155c67d..e5a35817a2 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -31,6 +31,7 @@ Contents: managed-startup cpu-hotplug virtio-pmem + pr-manager targets security deprecated diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst new file mode 100644 index 0000000000..9b1de198b1 --- /dev/null +++ b/docs/system/pr-manager.rst @@ -0,0 +1,111 @@ +====================================== +Persistent reservation managers +====================================== + +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. + +For this reason, QEMU's SCSI passthrough devices, ``scsi-block`` +and ``scsi-generic`` (both are only available on Linux) can delegate +implementation of persistent reservations to a separate object, +the "persistent reservation manager". Only PERSISTENT RESERVE OUT and +PERSISTENT RESERVE IN commands are passed to the persistent reservation +manager object; other commands are processed by QEMU as usual. + +----------------------------------------- +Defining a persistent reservation manager +----------------------------------------- + +A persistent reservation manager is an instance of a subclass of the +"pr-manager" QOM class. + +Right now only one subclass is defined, ``pr-manager-helper``, which +forwards the commands to an external privileged helper program +over Unix sockets. The helper program only allows sending persistent +reservation commands to devices for which QEMU has a file descriptor, +so that QEMU will not be able to effect persistent reservations +unless it has access to both the socket and the device. + +``pr-manager-helper`` has a single string property, ``path``, which +accepts the path to the helper program's Unix socket. For example, +the following command line defines a ``pr-manager-helper`` object and +attaches it to a SCSI passthrough device:: + + $ qemu-system-x86_64 + -device virtio-scsi \ + -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock + -drive if=none,id=hd,driver=raw,file.filename=/dev/sdb,file.pr-manager=helper0 + -device scsi-block,drive=hd + +Alternatively, using ``-blockdev``:: + + $ qemu-system-x86_64 + -device virtio-scsi \ + -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock + -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 + +--------------------------------------------- +Multipath devices and persistent reservations +--------------------------------------------- + +Proper support of persistent reservation for multipath devices requires +communication with the multipath daemon, so that the reservation is +registered and applied when a path is newly discovered or becomes online +again. :command:`qemu-pr-helper` can do this if the ``libmpathpersist`` +library was available on the system at build time. + +As of August 2017, a reservation key must be specified in ``multipath.conf`` +for ``multipathd`` to check for persistent reservation for newly +discovered paths or reinstated paths. The attribute can be added +to the ``defaults`` section or the ``multipaths`` section; for example:: + + multipaths { + multipath { + wwid XXXXXXXXXXXXXXXX + alias yellow + reservation_key 0x123abc + } + } + +Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede +its usage on regular SCSI devices. -- cgit v1.2.3