MPATHPERSIST(8)

💅 MPATHPERSIST(8) — like, the whole manual, but you'll actually get it

okay bestie, so this one's mpathpersist from the System Manager's Manual and honestly? she's a whole icon. she manages SCSI persistent reservations on dm multipath devices. that's the vibe. let's get into it 🫶

---

✨ NAME ✨

mpathpersist — manages SCSI persistent reservations on dm multipath devices. periodt. 💅

---

🌸 SYNOPSIS 🌸

mpathpersist [OPTIONS] device

---

🦋 DESCRIPTION 🦋

so bestie, this utility is literally here to manage SCSI persistent reservations on Device Mapper Multipath devices. no cap. but here's the catch — before you can even use this functionality, the reservation_key attribute must be defined in the /etc/multipath.conf file. otherwise the multipathd daemon will not check for persistent reservation for newly discovered paths or reinstated paths. and then you're just standing there like 😭. so define it. don't skip it. that's the rule.

also, fun fact: mpathpersist supports the same command-line options as the sg_persist utility. so if you want the full in-depth discussion of the various options, go consult the sg_persist(8) manual page. she's the older sister. iykyk.

---

👑 OPTIONS 👑

okay this is the long part, stay with me, we're gonna get through it together 🌈

• -verbose|-v level — verbosity, girl. pick your level:

0 — critical messages. 1 — error messages. 2 — warning messages. 3 — informational messages. 4 — informational messages with trace enabled.

(yes i know it's a numbered list inside a bullet, that's just how she is 💀)

• --device=DEVICE|-d DEVICE — query or change DEVICE.
• --batch-file=DEVICE|-f FILE — read commands from FILE. peek at the section "BATCH FILES" below. this option can be given at most once. don't push her.
• --help|-h — output this usage message. the classic.
• --hex|-H — output response in hex. 🔥
• --in|-i — request PR In command.
• --out|-o — request PR Out command.
• --param-alltgpt|-Y — PR Out parameter 'ALL_TG_PT'.
• --param-aptpl|-Z — PR Out parameter 'APTPL'.
• --read-keys|-k — PR In: Read Keys.
• --param-rk=RK|-K RK — PR Out parameter reservation key (RK is in hex, up to 8 bytes).
• --param-sark=SARK|-S SARK — PR Out parameter service action reservation key (SARK is in hex).
• --preempt|-P — PR Out: Preempt.
• --clear|-C — PR Out: Clear registrations.
• --preempt-abort|-A — PR Out: Preempt and Abort.
• --prout-type=TYPE|-T TYPE — PR Out command type.
• --read-full-status|-s — PR In: Read Full Status.
• --read-keys|-k — PR In: Read Keys. (yes she's listed twice in the original. she said it twice because she meant it. 🎀)
• --read-reservation|-r — PR In: Read Reservation.
• --register|-G — PR Out: Register.
• --register-ignore|-I — PR Out: Register and Ignore.
• --release|-L — PR Out: Release.
• --report-capabilities|-c — PR In: Report Capabilities.
• --reserve|-R — PR Out: Reserve.
• --transport-id=TIDS|-X TIDS — TransportIDs can be mentioned in several forms. mysterious. love that for her ✨
• --alloc-length=LEN|-l LEN — PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.

---

🌟 EXAMPLE 🌟

okay these are the actually useful bits, screenshot them, save them, tattoo them 🧚

Register the key "123abc" for the /dev/mapper/mpath9 device:

mpathpersist --out --register --param-sark=123abc
/dev/mapper/mpath9

Read registered reservation keys for the /dev/mapper/mpath9 device:

mpathpersist -i -k /dev/mapper/mpath9

Create a reservation for the /dev/mapper/mpath9 device with the given reservation key:

mpathpersist --out --reserve --param-rk=123abc --prout-type=8 -d
/dev/mapper/mpath9

Read the reservation status of the /dev/mapper/mpath9 device:

mpathpersist -i -s -d /dev/mapper/mpath9

Release the previously created reservation (note that the prout-type needs to be the same as above — do not come for her with a different type):

mpathpersist --out --release --param-rk=123abc --prout-type=8 -d
/dev/mapper/mpath9

Remove the current key registered for this host (i.e. reset it to 0):

mpathpersist --out --register-ignore -K 123abc -S 0
/dev/mapper/mpath9

Remove current reservation, and unregister all registered keys from all I_T nexuses:

mpathpersist -oCK 123abc /dev/mapper/mpath9

---

🍓 BATCH FILES 🍓

okay so the option --batch-file (-f) sets an input file to be processed by mpathpersist. grouping commands in batch files can provide a speed improvement, in particular on large installments, because mpathpersist needs to scan existing paths and maps only once during startup. efficiency queen 👑

the input file is a text file that is parsed line by line. every line of the file is interpreted as a command line (i.e. list of options and parameters) for mpathpersist. options and parameters are separated by one or more whitespace characters (space or TAB). lines can, but do not have to, begin with the word "mpathpersist". the "#" character, either at the beginning of the line or following some whitespace, denotes the start of a comment that lasts until the end of the line. empty lines are allowed. continuation of mpathpersist commands over multiple lines is not supported. so don't try it. 😤

all options listed in this man page, except -f and -v, are allowed in batch files. both short and long option formats may be used. using the -f option inside the batch file is an error. the -v option is ignored in batch files.

the multipath map on which to act must be specified on every input line, e.g. using the -d option. commands acting on different multipath maps may be combined in a batch file, and multiple commands may act on the same multipath map. commands are executed one by one, so that commands further down in the file see status changes caused by previous commands. if mpathpersist encounters an error while processing a line in the batch file, batch file processing is not aborted; subsequent commands are executed nonetheless. the exit status of mpathpersist is the status of the first failed command, or 0 if all commands succeeded.

if other options and parameters are used along with -f on the mpathpersist command line, the command line will be executed first, followed by the commands from the batch file.

below is an example of a valid batch input file. look at her go 💖

# This is an mpathpersist input file.
# Short and long forms of the same command
-i -k /dev/dm-1 # short form, this comment is ignored
mpathpersist --in --read-keys --device=/dev/dm-1

# Mixing of long and short options, variable white space
  --out  --register    -S  abcde     /dev/dm-1

# Mixing of commands for different maps
-ir /dev/dm-0
-ir /dev/dm-1

mpathpersist --out --param-rk abcde --reserve --prout-type 5 /dev/dm-1
# This should now show a reservation
-ir /dev/dm-1
-oCK abcde /dev/dm-1
--in --read-reservation /dev/dm-1

---

🔍 SEE ALSO 🔍

multipath(8), multipathd(8), sg_persist(8). go read those too, bestie, they're all in the family 🫶

---

💜 AUTHORS 💜

multipath-tools was developed by Christophe Varoqui <christophe.varoqui@opensvc.com> and others. shoutout to "and others", the real mvps 🌈⭐

---

okay that's the whole thing, you slayed it, go forth and reserve responsibly 💅✨

this page is from Linux, dated 2021-11-12 — mwah, xoxo 🎀