{ "content": [ { "type": "text", "text": "# MPATHPERSIST(8) (man)\n\n**Summary:** mpathpersist - Manages SCSI persistent reservations on dm multipath devices.\n\n**Synopsis:** mpathpersist [OPTIONS] device\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| — | — | — | Verbosity: 0 Critical messages. 1 Error messages. 2 Warning messages. 3 Informational messages. 4 Informational messages |\n| — | — | — | Output this usage message. |\n| — | — | — | Output response in hex. |\n| — | — | — | Request PR In command. |\n| — | — | — | Request PR Out command. |\n| — | — | — | PR Out parameter 'ALLTGPT'. |\n| — | — | — | PR Out parameter 'APTPL'. |\n| — | — | — | 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| |\n| — | — | — | PR Out: Preempt. |\n| — | — | — | PR Out: Clear registrations. |\n| — | — | — | PR Out: Preempt and Abort. --prout-type=TYPE|-T TYPE PR Out command type. |\n| — | — | — | PR In: Read Full Status. |\n| — | — | — | PR In: Read Keys. |\n| — | — | — | PR In: Read Reservation. |\n| — | — | — | PR Out: Register. |\n| — | — | — | PR Out: Register and Ignore. |\n| — | — | — | PR Out: Release. |\n| — | — | — | PR In: Report Capabilities. |\n| — | — | — | PR Out: Reserve. --transport-id=TIDS|-X TIDS TransportIDs can be mentioned in several forms. --alloc-length=LEN|-l LEN P |\n\n## Examples\n\n- `Register the key \"123abc\" for the /dev/mapper/mpath9 device:`\n- `mpathpersist --out --register --param-sark=123abc /dev/mapper/mpath9`\n- `Read registered reservation keys for the /dev/mapper/mpath9 device:`\n- `mpathpersist -i -k /dev/mapper/mpath9`\n- `Create a reservation for the /dev/mapper/mpath9 device with the given reservation key:`\n- `mpathpersist --out --reserve --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9`\n- `Read the reservation status of the /dev/mapper/mpath9 device:`\n- `mpathpersist -i -s -d /dev/mapper/mpath9`\n- `Release the previously created reservation (note that the prout-type needs to be the same as`\n- `above):`\n- `mpathpersist --out --release --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9`\n- `Remove the current key registered for this host (i.e. reset it to 0):`\n- `mpathpersist --out --register-ignore -K 123abc -S 0 /dev/mapper/mpath9`\n- `Remove current reservation, and unregister all registered keys from all IT nexuses:`\n- `mpathpersist -oCK 123abc /dev/mapper/mpath9`\n\n## See Also\n\n- multipath(8)\n- multipathd(8)\n- sgpersist(8)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (2 lines)\n- **DESCRIPTION** (8 lines)\n- **OPTIONS** (1 lines) — 19 subsections\n - -verbose|-v (19 lines)\n - --help|-h (2 lines)\n - --hex|-H (2 lines)\n - --in|-i (2 lines)\n - --out|-o (2 lines)\n - --param-alltgpt|-Y (2 lines)\n - --param-aptpl|-Z (2 lines)\n - --read-keys|-k (8 lines)\n - --preempt|-P (2 lines)\n - --clear|-C (2 lines)\n - --preempt-abort|-A (5 lines)\n - --read-full-status|-s (2 lines)\n - --read-keys|-k (2 lines)\n - --read-reservation|-r (2 lines)\n - --register|-G (2 lines)\n - --register-ignore|-I (2 lines)\n - --release|-L (2 lines)\n - --report-capabilities|-c (2 lines)\n - --reserve|-R (8 lines)\n- **EXAMPLE** (22 lines)\n- **BATCH FILES** (47 lines)\n- **SEE ALSO** (2 lines)\n- **AUTHORS** (6 lines)\n\n## Full Content\n\n### NAME\n\nmpathpersist - Manages SCSI persistent reservations on dm multipath devices.\n\n### SYNOPSIS\n\nmpathpersist [OPTIONS] device\n\n### DESCRIPTION\n\nThis utility is used to manage SCSI persistent reservations on Device Mapper Multipath de‐\nvices. To be able to use this functionality, the reservationkey attribute must be defined in\nthe /etc/multipath.conf file. Otherwise the multipathd daemon will not check for persistent\nreservation for newly discovered paths or reinstated paths.\n\nmpathpersist supports the same command-line options as the sgpersist utility. Consult the\nsgpersist (8) manual page for an in-depth discussion of the various options.\n\n### OPTIONS\n\n#### -verbose|-v\n\nVerbosity:\n\n0 Critical messages.\n\n1 Error messages.\n\n2 Warning messages.\n\n3 Informational messages.\n\n4 Informational messages with trace enabled.\n\n--device=DEVICE|-d DEVICE\nQuery or change DEVICE.\n\n--batch-file=DEVICE|-f FILE\nRead commands from FILE. See section \"BATCH FILES\" below. This option can be given at\nmost once.\n\n#### --help|-h\n\nOutput this usage message.\n\n#### --hex|-H\n\nOutput response in hex.\n\n#### --in|-i\n\nRequest PR In command.\n\n#### --out|-o\n\nRequest PR Out command.\n\n#### --param-alltgpt|-Y\n\nPR Out parameter 'ALLTGPT'.\n\n#### --param-aptpl|-Z\n\nPR Out parameter 'APTPL'.\n\n#### --read-keys|-k\n\nPR In: Read Keys.\n\n--param-rk=RK|-K RK\nPR Out parameter reservation key (RK is in hex, up to 8 bytes).\n\n--param-sark=SARK|-S SARK\nPR Out parameter service action reservation key (SARK is in hex).\n\n#### --preempt|-P\n\nPR Out: Preempt.\n\n#### --clear|-C\n\nPR Out: Clear registrations.\n\n#### --preempt-abort|-A\n\nPR Out: Preempt and Abort.\n\n--prout-type=TYPE|-T TYPE\nPR Out command type.\n\n#### --read-full-status|-s\n\nPR In: Read Full Status.\n\n#### --read-keys|-k\n\nPR In: Read Keys.\n\n#### --read-reservation|-r\n\nPR In: Read Reservation.\n\n#### --register|-G\n\nPR Out: Register.\n\n#### --register-ignore|-I\n\nPR Out: Register and Ignore.\n\n#### --release|-L\n\nPR Out: Release.\n\n#### --report-capabilities|-c\n\nPR In: Report Capabilities.\n\n#### --reserve|-R\n\nPR Out: Reserve.\n\n--transport-id=TIDS|-X TIDS\nTransportIDs can be mentioned in several forms.\n\n--alloc-length=LEN|-l LEN\nPR In: maximum allocation length. LEN is a decimal number between 0 and 8192.\n\n### EXAMPLE\n\nRegister the key \"123abc\" for the /dev/mapper/mpath9 device:\nmpathpersist --out --register --param-sark=123abc /dev/mapper/mpath9\n\nRead registered reservation keys for the /dev/mapper/mpath9 device:\nmpathpersist -i -k /dev/mapper/mpath9\n\nCreate a reservation for the /dev/mapper/mpath9 device with the given reservation key:\nmpathpersist --out --reserve --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9\n\nRead the reservation status of the /dev/mapper/mpath9 device:\nmpathpersist -i -s -d /dev/mapper/mpath9\n\nRelease the previously created reservation (note that the prout-type needs to be the same as\nabove):\nmpathpersist --out --release --param-rk=123abc --prout-type=8 -d /dev/mapper/mpath9\n\nRemove the current key registered for this host (i.e. reset it to 0):\nmpathpersist --out --register-ignore -K 123abc -S 0 /dev/mapper/mpath9\n\nRemove current reservation, and unregister all registered keys from all IT nexuses:\nmpathpersist -oCK 123abc /dev/mapper/mpath9\n\n### BATCH FILES\n\nThe option --batch-file (-f) sets an input file to be processed by mpathpersist. Grouping\ncommands in batch files can provide a speed improvement in particular on large installments,\nbecause mpathpersist needs to scan existing paths and maps only once during startup.\n\nThe input file is a text file that is parsed line by line. Every line of the file is inter‐\npreted as a command line (i.e. list of options and parameters) for mpathpersist. Options and\nparameters are separated by one or more whitespace characters (space or TAB). Lines can, but\ndo not have to, begin with the word \"mpathpersist\". The \"#\" character, either at the begin‐\nning of the line or following some whitespace, denotes the start of a comment that lasts un‐\ntil the end of the line. Empty lines are allowed. Continuation of mpathpersist commands over\nmultiple lines is not supported.\n\nAll options listed in this man page, except -f and -v, are allowed in batch files. Both short\nand long option formats may be used. Using the -f option inside the batch file is an error.\nThe -v option is ignored in batch files.\n\nThe multipath map on which to act must be specified on every input line, e.g. using the -d\noption. Commands acting on different multipath maps may be combined in a batch file, and\nmultiple commands may act on the same multipath map. Commands are executed one by one, so\nthat commands further down in the file see status changes caused by previous commands. If\nmpathpersist encounters an error while processing a line in the batch file, batch file pro‐\ncessing is not aborted; subsequent commands are executed nonetheless. The exit status of\nmpathpersist is the status of the first failed command, or 0 if all commands succeeded.\n\nIf other options and parameters are used along with -f on the mpathpersist command line, the\ncommand line will be executed first, followed by the commands from the batch file.\n\nBelow is an example of a valid batch input file.\n\n# This is an mpathpersist input file.\n# Short and long forms of the same command\n-i -k /dev/dm-1 # short form, this comment is ignored\nmpathpersist --in --read-keys --device=/dev/dm-1\n\n# Mixing of long and short options, variable white space\n--out --register -S abcde /dev/dm-1\n\n# Mixing of commands for different maps\n-ir /dev/dm-0\n-ir /dev/dm-1\n\nmpathpersist --out --param-rk abcde --reserve --prout-type 5 /dev/dm-1\n# This should now show a reservation\n-ir /dev/dm-1\n-oCK abcde /dev/dm-1\n--in --read-reservation /dev/dm-1\n\n### SEE ALSO\n\nmultipath(8), multipathd(8), sgpersist(8).\n\n### AUTHORS\n\nmultipath-tools was developed by Christophe Varoqui and oth‐\ners.\n\n\n\nLinux 2019-05-27 MPATHPERSIST(8)\n\n" } ], "structuredContent": { "command": "MPATHPERSIST", "section": "8", "mode": "man", "summary": "mpathpersist - Manages SCSI persistent reservations on dm multipath devices.", "synopsis": "mpathpersist [OPTIONS] device", "flags": [ { "flag": "", "long": null, "arg": null, "description": "Verbosity: 0 Critical messages. 1 Error messages. 2 Warning messages. 3 Informational messages. 4 Informational messages with trace enabled. --device=DEVICE|-d DEVICE Query or change DEVICE. --batch-file=DEVICE|-f FILE Read commands from FILE. See section \"BATCH FILES\" below. This option can be given at most once." }, { "flag": "", "long": null, "arg": null, "description": "Output this usage message." }, { "flag": "", "long": null, "arg": null, "description": "Output response in hex." }, { "flag": "", "long": null, "arg": null, "description": "Request PR In command." }, { "flag": "", "long": null, "arg": null, "description": "Request PR Out command." }, { "flag": "", "long": null, "arg": null, "description": "PR Out parameter 'ALLTGPT'." }, { "flag": "", "long": null, "arg": null, "description": "PR Out parameter 'APTPL'." }, { "flag": "", "long": null, "arg": null, "description": "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)." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Preempt." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Clear registrations." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Preempt and Abort. --prout-type=TYPE|-T TYPE PR Out command type." }, { "flag": "", "long": null, "arg": null, "description": "PR In: Read Full Status." }, { "flag": "", "long": null, "arg": null, "description": "PR In: Read Keys." }, { "flag": "", "long": null, "arg": null, "description": "PR In: Read Reservation." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Register." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Register and Ignore." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Release." }, { "flag": "", "long": null, "arg": null, "description": "PR In: Report Capabilities." }, { "flag": "", "long": null, "arg": null, "description": "PR Out: Reserve. --transport-id=TIDS|-X TIDS TransportIDs can be mentioned in several forms. --alloc-length=LEN|-l LEN PR In: maximum allocation length. LEN is a decimal number between 0 and 8192." } ], "examples": [ "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):", "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 IT nexuses:", "mpathpersist -oCK 123abc /dev/mapper/mpath9" ], "see_also": [ { "name": "multipath", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/multipath/8/json" }, { "name": "multipathd", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/multipathd/8/json" }, { "name": "sgpersist", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sgpersist/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 8, "subsections": [] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "-verbose|-v", "lines": 19 }, { "name": "--help|-h", "lines": 2 }, { "name": "--hex|-H", "lines": 2 }, { "name": "--in|-i", "lines": 2 }, { "name": "--out|-o", "lines": 2 }, { "name": "--param-alltgpt|-Y", "lines": 2 }, { "name": "--param-aptpl|-Z", "lines": 2 }, { "name": "--read-keys|-k", "lines": 8 }, { "name": "--preempt|-P", "lines": 2 }, { "name": "--clear|-C", "lines": 2 }, { "name": "--preempt-abort|-A", "lines": 5 }, { "name": "--read-full-status|-s", "lines": 2 }, { "name": "--read-keys|-k", "lines": 2 }, { "name": "--read-reservation|-r", "lines": 2 }, { "name": "--register|-G", "lines": 2 }, { "name": "--register-ignore|-I", "lines": 2 }, { "name": "--release|-L", "lines": 2 }, { "name": "--report-capabilities|-c", "lines": 2 }, { "name": "--reserve|-R", "lines": 8 } ] }, { "name": "EXAMPLE", "lines": 22, "subsections": [] }, { "name": "BATCH FILES", "lines": 47, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 6, "subsections": [] } ] } }