| 1 | .. |
| 2 | SPDX-License-Identifier: GPL-2.0-or-later |
| 3 | |
| 4 | .. _scsi_migrate_pr: |
| 5 | |
| 6 | SCSI Persistent Reservation Live Migration |
| 7 | ========================================== |
| 8 | |
| 9 | This document explains how to live migrate SCSI Persistent Reservations. |
| 10 | |
| 11 | The ``scsi-block`` device migrates SCSI Persistent Reservations when the |
| 12 | ``migrate-pr=on`` parameter is given. Migration is enabled by default in |
| 13 | versioned machine types since QEMU 11.0. It is disabled by default on older |
| 14 | machine types and needs to be explicitly enabled with ``--device |
| 15 | scsi-block,migrate-pr=on,...``. |
| 16 | |
| 17 | When migration is enabled, QEMU snoops PERSISTENT RESERVATION OUT commands and |
| 18 | tracks the reservation key registered by the guest as well as reservations that |
| 19 | the guest acquires. This information is migrated along with the guest and the |
| 20 | destination QEMU submits a PERSISTENT RESERVATION OUT command with the PREEMPT |
| 21 | service action to atomically transfer the reservation to the destination before |
| 22 | the guest starts running on the destination. |
| 23 | |
| 24 | The following persistent reservation capabilities reported by the PERSISTENT |
| 25 | RESERVATION IN command with the REPORT CAPABILITIES service action are masked |
| 26 | from the guest by QEMU when migration is enabled: |
| 27 | |
| 28 | * Specify Initiator Ports Capable (SIP_C) |
| 29 | * All Target Ports Capable (ATC_C) |
| 30 | |
| 31 | When migration is disabled, the ``scsi-block`` device is live migrated but |
| 32 | reservations remain in place on the source. Usually this is not the intended |
| 33 | behavior unless there is another mechanism to update reservations during |
| 34 | migration. The PERSISTENT RESERVATION IN command also does not mask |
| 35 | capabilities reported to the guest when migration is disabled. |
| 36 | |
| 37 | Limitations |
| 38 | ----------- |
| 39 | |
| 40 | QEMU does not remember snooped reservation details across restart, so software |
| 41 | inside the guest must acquire the reservation after boot in order for live |
| 42 | migration to work. Similarly, if the reservation is acquired outside the guest |
| 43 | then it will not live migrate along with the guest. |
| 44 | |
| 45 | Snooping only considers the PERSISTENT RESERVATION OUT commands from the guest |
| 46 | and does not track reservation changes made by other SCSI initiators. QEMU's |
| 47 | snooped reservation details can become stale if another SCSI initiator |
| 48 | makes changes to the reservation. |
| 49 | |
| 50 | Guests running on the same host share a single SCSI initiator identity unless |
| 51 | Fibre Channel N_Port ID Virtualization is configured. As a consequence, |
| 52 | multiple guests on the same hosts may observe unexpected behavior if they use |
| 53 | the same physical LUN. From the LUN's perspective all guests are the same |
| 54 | initiator and there is no way to distinguish between guests. |