Manage SCSI Persistent Reservations on a Multipath Device

You will finish with a controlled workflow for inspecting SCSI persistent reservation state, registering a host key, creating a reservation on a device-mapper multipath map, and releasing it again with mpathpersist. The examples target the installed multipath-tools package, version 0.9.4-5ubuntu8.2.

Allow about twenty minutes for inspection and a further maintenance window for any change. You need root access, a working multipath map, and a storage design that explicitly permits persistent reservation changes. These commands can affect access to shared storage. Do not experiment on a production LUN, and confirm the map path before every PR Out command.

1. Confirm the installed command

Check which binary will run and record the package version. These are ordinary read-only commands:

$ command -v mpathpersist
/usr/sbin/mpathpersist
$ dpkg-query -W -f='\${Package} \${Version}\n' multipath-tools
multipath-tools 0.9.4-5ubuntu8.2

On this installation, even mpathpersist --help reports need to be root. Use an elevated shell for the utility itself. It supports the option set of sg_persist, but the local mpathpersist(8) page is the contract used here.

The command takes a device either as its final argument or with -d/--device. Prefer the long form while checking a new command, then shorten it only after the operation is understood.

2. Confirm the map and the multipath prerequisite

Choose the map from your storage documentation or from the output of your normal multipath inspection process. Substitute an exact path below. Do not guess a map number, and do not replace a map with an underlying path unless your storage procedure explicitly requires that:

$ MAP=/dev/mapper/mpath9
$ sudo test -b "$MAP" && printf 'block device: %s\n' "$MAP"
block device: /dev/mapper/mpath9

The map must be backed by paths managed by device-mapper multipath. Before making a change, check your normal multipath -ll output and confirm that the map is the LUN you intend to operate on. A successful block-device test only proves that the node exists; it does not identify the storage array for you.

mpathpersist also requires a reservation_key attribute in /etc/multipath.conf for multipathd to check persistent reservations on newly discovered or reinstated paths. Review that configuration with the storage owner before relying on automatic path checks. This guide does not edit it.

3. Read keys and reservation status

Start with read-only PR In operations. First list registered keys:

$ sudo mpathpersist --in --read-keys --device="$MAP"
# registered-key output is device-specific
$ printf 'exit status: %s\n' "$?"
exit status: 0

The output is supplied by the target and can differ between arrays. Treat the command's exit status as the first check, then record the keys shown by the target. Next read the full reservation status:

$ sudo mpathpersist --in --read-full-status --device="$MAP"
# full-status output is device-specific
$ printf 'exit status: %s\n' "$?"
exit status: 0

If you need the current reservation rather than full registration details, use --read-reservation instead. --report-capabilities asks the target what it supports. These operations do not register, reserve or release anything.

4. Register a host key

Registration is a PR Out operation. Choose a key according to your cluster's reservation plan; the example value is deliberately a placeholder. The key is hexadecimal and may be up to eight bytes:

$ KEY=123abc
$ sudo mpathpersist --out --register --param-sark="$KEY" --device="$MAP"
$ printf 'exit status: %s\n' "$?"
exit status: 0

The manpage's example uses --param-sark for the service-action reservation key during registration. A zero exit status means the command completed successfully; verify the registration with the read-keys command from step 3. Do not assume that a key shown in a shell variable is registered until the target reports it.

To remove this host's current key later, use register-ignore with the same old key and a zero new key:

$ sudo mpathpersist --out --register-ignore --param-rk="$KEY" --param-sark=0 --device="$MAP"
$ sudo mpathpersist --in --read-keys --device="$MAP"

This recovery command changes registration state. Use it only when the reservation plan says that this host's key should be removed.

5. Create a reservation

Reserve the map only after the registered key and reservation type have been agreed with every host that shares the device. The type is a target-defined numeric value. The installed manpage example uses type 8:

$ PR_TYPE=8
$ sudo mpathpersist --out --reserve --param-rk="$KEY" --prout-type="$PR_TYPE" --device="$MAP"
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ sudo mpathpersist --in --read-reservation --device="$MAP"
# reservation output is device-specific

Keep the same reservation type when releasing this reservation. A reservation is not the same thing as a filesystem mount or a Linux file lock. It is a SCSI target state that can change which initiators may access shared storage, so coordinate the operation with the cluster and storage teams.

6. Release the reservation and recover carefully

When the maintenance action is complete, release the reservation using the registered key and the same type:

$ sudo mpathpersist --out --release --param-rk="$KEY" --prout-type="$PR_TYPE" --device="$MAP"
$ sudo mpathpersist --in --read-reservation --device="$MAP"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Verify the target's response rather than assuming that an empty-looking result means success. If a previous reservation must be forcibly replaced, --preempt and --preempt-abort exist, but they can disrupt another initiator. Use them only with a documented recovery procedure and the exact service-action keys.

$ sudo mpathpersist --out --clear --param-rk="$KEY" --device="$MAP"
$ sudo mpathpersist --in --read-keys --device="$MAP"
$ sudo mpathpersist --in --read-reservation --device="$MAP"

There is no generic undo for a clear operation. Re-registration requires the keys and the storage plan to be known, and any other initiator's registration may no longer be recoverable from this host. Prefer release and deliberate unregister operations whenever possible.

7. Batch repeatable read or change operations

For several commands, a batch file lets mpathpersist scan paths and maps once at startup. Each line is a separate command, and every line must name its map. Comments begin with #; continuation across lines is not supported:

# Inspect two maps
--in --read-keys --device=/dev/mapper/mpath9
--in --read-reservation --device=/dev/mapper/mpath9
--in --read-keys --device=/dev/mapper/mpath10

Run it as root:

$ sudo mpathpersist --batch-file=/path/to/checked-requests.txt
$ printf 'batch exit status: %s\n' "$?"
batch exit status: 0

Batch processing does not stop at the first failed line. Later commands still run, and the process exit status is the first failed command's status. Do not put -f inside the file; it is an error, and -v is ignored there. Review a batch file as carefully as a shell script before including PR Out operations.