Manage SCSI Persistent Reservations with mpathpersist

mpathpersist reads and writes SCSI reservation state on a multipath map, and a wrong device name can lock other hosts out of shared storage. This covers inspecting state, registering a key, reserving, and releasing, with multipath-tools 0.9.4-5ubuntu8.2.

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

1. Confirm the installed command

Ordinary read-only checks:

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

• Root is required even to ask for help. On this install, even mpathpersist --help reports need to be root.
• It shares an option set with sg_persist. But the local mpathpersist(8) page is the contract used here.
• The device comes last, or via -d/--device. Prefer the long form while you are still learning the command, then shorten it once the operation is understood.

2. Confirm the map and the multipath prerequisite

Pull the map from your storage documentation or your normal multipath inspection, not from a guess:

$ 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. Check your normal multipath -ll output first and confirm the map really is the LUN you intend to operate on: a successful block-device test only proves the node exists, not which array it is.

mpathpersist also needs a reservation_key attribute in /etc/multipath.conf before multipathd will check persistent reservations on newly discovered or reinstated paths. Review that 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. List registered keys first:

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

The output comes from the target and differs between arrays. Check the exit status first, then record the keys shown. Next, 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

• --read-reservation. Use instead when you only need the current reservation, not full registration detail.
• --report-capabilities. Asks the target what it supports.

None of these register, reserve or release anything.

4. Register a host key

Registration is a PR Out operation. Pick a key from your cluster's reservation plan; the example below is a placeholder. The key is hexadecimal, 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 own example uses --param-sark for the service-action reservation key during registration. A zero exit status means the command completed; verify the registration with the read-keys command from step 3 rather than trusting a shell variable. To remove this host's key later, use register-ignore with the 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"

That changes registration state, so only run it when the reservation plan actually calls for removing this host's key.

5. Create a reservation

Reserve the map only after every host that shares the device has agreed the key and reservation type. The type is a target-defined number; the installed manpage's 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 type on hand for releasing this reservation later. A reservation is a SCSI target state, not a filesystem mount or a Linux file lock; it can change which initiators may access shared storage, so coordinate it with the cluster and storage teams.

6. Release the reservation and recover carefully

Once the maintenance is done, release with the same key and 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

Check the target's actual response rather than assuming an empty-looking result means success. --preempt and --preempt-abort exist for forcibly replacing a previous reservation, 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. Re-registration needs the keys and the storage plan to be known, and another initiator's registration may not be recoverable from this host at all. Prefer release and deliberate unregister operations whenever you can.

7. Batch repeatable read or change operations

A batch file lets mpathpersist scan paths and maps once at startup instead of per command. Each line is a separate command and must name its own map; comments start with #, and 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

$ 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 there, and -v is ignored. Review a batch file as carefully as a shell script before it includes any PR Out operation.