Block layer support for Persistent Reservations

The Linux kernel supports a user space interface for simplifiedPersistent Reservations which map to block devices that supportthese (like SCSI). Persistent Reservations allow restrictingaccess to block devices to specific initiators in a shared storagesetup.

This document gives a general overview of the support ioctl commands.For a more detailed reference please refer to the SCSI PrimaryCommands standard, specifically the section on Reservations and the“PERSISTENT RESERVE IN” and “PERSISTENT RESERVE OUT” commands.

All implementations are expected to ensure the reservations survivea power loss and cover all connections in a multi path environment.These behaviors are optional in SPC but will be automatically appliedby Linux.

The following types of reservations are supported:

  • PR_WRITE_EXCLUSIVE

    Only the initiator that owns the reservation can write to thedevice. Any initiator can read from the device.

  • PR_EXCLUSIVE_ACCESS

    Only the initiator that owns the reservation can access thedevice.

  • PR_WRITE_EXCLUSIVE_REG_ONLY

    Only initiators with a registered key can write to the device,Any initiator can read from the device.

  • PR_EXCLUSIVE_ACCESS_REG_ONLY

    Only initiators with a registered key can access the device.

  • PR_WRITE_EXCLUSIVE_ALL_REGS

    Only initiators with a registered key can write to the device,Any initiator can read from the device.All initiators with a registered key are considered reservationholders.Please reference the SPC spec on the meaning of a reservationholder if you want to use this type.

  • PR_EXCLUSIVE_ACCESS_ALL_REGS

    Only initiators with a registered key can access the device.All initiators with a registered key are considered reservationholders.Please reference the SPC spec on the meaning of a reservationholder if you want to use this type.

The following ioctl are supported:

1. IOC_PR_REGISTER

This ioctl command registers a new reservation if the new_key argumentis non-null. If no existing reservation exists old_key must be zero,if an existing reservation should be replaced old_key must containthe old reservation key.

If the new_key argument is 0 it unregisters the existing reservation passedin old_key.

2. IOC_PR_RESERVE

This ioctl command reserves the device and thus restricts access for otherdevices based on the type argument. The key argument must be the existingreservation key for the device as acquired by the IOC_PR_REGISTER,IOC_PR_REGISTER_IGNORE, IOC_PR_PREEMPT or IOC_PR_PREEMPT_ABORT commands.

3. IOC_PR_RELEASE

This ioctl command releases the reservation specified by key and flagsand thus removes any access restriction implied by it.

4. IOC_PR_PREEMPT

This ioctl command releases the existing reservation referred to byold_key and replaces it with a new reservation of type for thereservation key new_key.

5. IOC_PR_PREEMPT_ABORT

This ioctl command works like IOC_PR_PREEMPT except that it also abortsany outstanding command sent over a connection identified by old_key.

6. IOC_PR_CLEAR

This ioctl command unregisters both key and any other reservation keyregistered with the device and drops any existing reservation.

Flags

All the ioctls have a flag field. Currently only one flag is supported:

  • PR_FL_IGNORE_KEY

    Ignore the existing reservation key. This is commonly supported forIOC_PR_REGISTER, and some implementation may support the flag forIOC_PR_RESERVE.

For all unknown flags the kernel will return -EOPNOTSUPP.