Configure SCSI passthrough for virtual machines

To provide a virtual machine (VM) with direct access to a host SCSI device, such as a Storage Area Network (SAN) Logical Unit Number (LUN) disk device, you can configure SCSI passthrough.

Before you begin

About this task

You can pass local disks or multipath devices with SCSI passthrough.

  • When passing local disks, the VM uses one path to the disk, for example, a single /dev/disk/by-path/ or /dev/sdb device.
  • With multipath devices, the host presents the same LUN through multiple paths and aggregates them into one mapper device, for example /dev/mapper/mpatha. This provides redundancy and failover if one path fails.

Procedure

  1. Open the XML configuration of the VM: 
    # virsh edit <vm_name>
  2. In the <devices> section, add a line for the VirtIO-SCSI controller, if it is not present already: 
    <controller type='scsi' model='virtio-scsi' index='0'/>
  3. For multipath devices, identify the multipath device mapper on the host: 
    # multipath -l
     
    mpatha (36001438005deb1d00000000000000001) dm-0 NETAPP   ,LUN
size=100G features='0' hwhandler='0' wp=rw
`-+- policy='service-time 0' prio=50 status=active
  `- 2:0:0:1 sdb 8:16  active ready running
  `- 3:0:0:1 sdc 8:32  active ready running

    Note the multipath device name, for example, mpatha. The device path is /dev/mapper/<name>, for example, /dev/mapper/mpatha. You can also list multipath device nodes with the ls /dev/mapper/ command.

  4. Create and open an XML file to define the SCSI disk device on the host. For example: 
    # vim scsi-passthrough-device.xml
  5. Add the SCSI device configuration to the XML file:
    • For a multipath device: 
      <disk type='block' device='lun'>
        <driver name='qemu' type='raw'/>
        <source dev='/dev/mapper/mpatha'/>
        <target dev='sdb' bus='scsi'/>
        <alias name='ua-scsi-mpath0'/>
        <address type='drive' controller='0' bus='0' target='0' unit='1'/>
</disk>

      In this example, the multipath device is defined as a single disk element:

      • The <source dev='/dev/mapper/mpatha'/> specifies the device-mapper multipath device on the host.
      • The host multipath layer already aggregates the paths, so the VM receives one block device and path failover is handled on the host.
    • For passing a local disk: 
      <disk type='block' device='lun'>
        <driver name='qemu' type='raw'/>
        <source dev='/dev/sdb'/>
        <target dev='sdc' bus='scsi'/>
        <alias name='ua-scsi-lun0'/>
        <address type='drive' controller='0' bus='0' target='0' unit='0'/>
</disk>

      In this example, a SCSI disk device is defined with the following parameters:

      • type='block': Specifies that the device is a block device.
      • device='lun': Indicates that this is a SCSI Logical Unit Number (LUN) device passthrough.
      • <driver name='qemu' type='raw'/>: Specifies the QEMU driver with raw format for direct device access.
      • <source dev='/dev/sdb'/>: Specifies the host block device path. You can use device nodes, for example /dev/sdb, directly or use /dev/disk/by-path/ entries for better persistence across reboots.
      • <target dev='sdc' bus='scsi'/>: Specifies how the device is displayed in the VM. The device is displayed as sdc on the SCSI bus.
      • alias: This is an optional user-defined alias that you can use to specify the intended device, for example when detaching the device with libvirt commands. All user-defined aliases in libvirt must start with the "ua-" prefix.
      • <address type='drive' controller='0' bus='0' target='0' unit='0'/>: Specifies how the device is displayed in the VM. The controller attribute refers to a SCSI controller in the VM, which must exist before attaching the device.
  6. Use the XML file to attach the defined SCSI disk device to a VM. For example, to permanently attach the device defined in scsi-passthrough-device.xml to the running <vm_name> VM: 
    # virsh attach-device <vm_name> scsi-passthrough-device.xml --live --config

    The --live option attaches the device to a running VM only, without persistence between boots. The --config option makes the configuration changes persistent. You can also attach the device to a shutdown VM without the --live option.

  7. Optional: When you no longer need the SCSI disk to be attached to the VM, you can detach it by using the virsh detach-device command:
    1. To detach a SCSI disk device from a shut-down VM: 
      # virsh detach-device <vm_name> scsi-passthrough-device.xml --config
    2. To detach a SCSI disk device from a running VM: 
      # virsh detach-device <vm_name> scsi-passthrough-device.xml --live --config
      Warning

      Detaching a SCSI device from a running VM might cause data loss or corruption if the device is in use. Ensure that the device is not being accessed by any applications in the guest operating system before detaching it.

Results

  • In RHEL VMs, you can list block devices to verify the SCSI device is visible in the guest. For multipath configuration, the LUN disk is listed as a single block device: 
    # lsblk -nd -o name,size,type,wwn
     
    NAME   SIZE TYPE WWN
sda    20G  disk
sdb   100G  disk  0x36001438005deb1d00000000000000001

    In this example, the SCSI device is listed as a disk with a World Wide Name (WWN). For multipath configuration, the guest is presented with a single block device and path failover is handled on the host.

    Check that the size of the presented device is the same as the size of the LUN disk on the host.

  • On the host, you can verify the device attachment by displaying the XML configuration of the running VM: 
    # virsh dumpxml <vm_name>
     
    <domain type='kvm'>
  <name>vm_name</name>
  ...
  <devices>
    ...
    <disk type='block' device='lun'>
      <driver name='qemu' type='raw'/>
      <source dev='/dev/sdb'/>
      <target dev='sdc' bus='scsi'/>
      <alias name='ua-scsi-lun0'/>
      <address type='drive' controller='0' bus='0' target='0' unit='0'/>
    </disk>
    ...
  </devices>
  ...
</domain>

    In this example, the disk element shows that the SCSI device from the host path /dev/sdb is attached to the VM as sdc on the SCSI bus.