1MULTIPATH.CONF(5)             File Formats Manual            MULTIPATH.CONF(5)
2
3
4

NAME

6       multipath.conf - multipath daemon configuration file.
7

DESCRIPTION

9       /etc/multipath.conf is the configuration file for the multipath daemon.
10       It is used to overwrite the built-in configuration table of multipathd.
11       Any line whose first non-white-space character is a '#' is considered a
12       comment line. Empty lines are ignored.
13
14       Currently used multipathd configuration can be displayed with the  mul‐
15       tipath -t or multipathd show config command.
16

SYNTAX

18       The configuration file contains entries of the form:
19
20              <section> {
21                     <attribute> <value>
22                     ...
23                     <subsection> {
24                            <attribute> <value>
25                            ...
26                     }
27              }
28
29       Each section contains one or more attributes or subsections. The recog‐
30       nized keywords for attributes or subsections depend on the  section  in
31       which they occur.
32
33       <attribute>  and  <value> must be on a single line.  <attribute> is one
34       of the keywords listed in this man page.  <value> is  either  a  simple
35       word (containing no whitespace and none of the characters '"', '#', and
36       '!') or one string enclosed in double quotes ("..."). Outside a  quoted
37       string,  text  starting  with '#', and '!' is regarded as a comment and
38       ignored until the end of the line. Inside a quoted string, '#' and  '!'
39       are  normal  characters,  and  whitespace is preserved.  To represent a
40       double quote character inside a double quoted string, use two  consecu‐
41       tive  double  quotes  ('""').  Thus '2.5" SSD' can be written as "2.5""
42       SSD".
43
44       Opening braces ('{') must follow the  (sub)section  name  on  the  same
45       line.  Closing braces ('}') that mark the end of a (sub)section must be
46       the only non-whitespace character on the line.  Whitespace  is  ignored
47       except  inside  double  quotes, thus the indentation shown in the above
48       example is helpful for human readers but not mandatory.
49
50       Note on regular expressions: The multipath.conf syntax allows many  at‐
51       tribute  values  to  be specified as POSIX Extended Regular Expressions
52       (see regex(7)). These regular expressions are case  sensitive  and  not
53       anchored,  thus the expression "bar" matches "barbie", "rhabarber", and
54       "wunderbar", but not "Barbie". To  avoid  unwanted  substring  matches,
55       standard regular expression syntax using the special characters "^" and
56       "$" can be used.
57
58       The following section keywords are recognized:
59
60       defaults         This section defines  default  values  for  attributes
61                        which are used whenever no values are given in the ap‐
62                        propriate device or multipath sections.
63
64       blacklist        This section defines which devices should be  excluded
65                        from the multipath topology discovery.
66
67       blacklist_exceptions
68                        This  section defines which devices should be included
69                        in the multipath  topology  discovery,  despite  being
70                        listed in the blacklist section.
71
72       multipaths       This  section  defines  the multipath topologies. They
73                        are indexed by a World Wide Identifier(WWID). For  de‐
74                        tails  on the WWID generation see section WWID genera‐
75                        tion below. Attributes set in this section take prece‐
76                        dence over all others.
77
78       devices          This section defines the device-specific settings. De‐
79                        vices are identified by vendor, product, and revision.
80
81       overrides        This section defines values for attributes that should
82                        override the device-specific settings for all devices.
83

defaults section

85       The defaults section recognizes the following keywords:
86
87       verbosity        Default  verbosity.  Higher  values  increase the ver‐
88                        bosity level. Valid levels are between 0 and 6.
89
90                        The default is: 2
91
92       polling_interval Interval between two path checks in seconds. For prop‐
93                        erly  functioning  paths,  the interval between checks
94                        will gradually increase to max_polling_interval.  This
95                        value will be overridden by the WatchdogSec setting in
96                        the multipathd.service definition if systemd is used.
97
98                        The default is: 5
99
100       max_polling_interval
101                        Maximal interval between two path checks in seconds.
102
103                        The default is: 4 * polling_interval
104
105       reassign_maps    Enable reassigning of device-mapper  maps.  With  this
106                        option  multipathd  will  remap existing device-mapper
107                        maps to always point to multipath device, not the  un‐
108                        derlying  block  devices.  Possible values are yes and
109                        no.
110
111                        The default is: no
112
113       multipath_dir    Directory where the dynamic shared objects are stored.
114                        Defined at compile time, commonly /lib64/multipath/ or
115                        /lib/multipath/.
116
117                        The default is: <system dependent>
118
119       path_selector    The default path selector algorithm to use;  they  are
120                        offered  by  the  kernel  multipath  target. There are
121                        three selector algorithms:
122
123                        round-robin 0
124                                    Loop through every path in the path group,
125                                    sending  the  same  amount of I/O to each.
126                                    Some aspects of behavior can be controlled
127                                    with     the     attributes:    rr_min_io,
128                                    rr_min_io_rq and rr_weight.
129
130                        queue-length 0
131                                    (Since 2.6.31 kernel) Choose the path  for
132                                    the  next bunch of I/O based on the amount
133                                    of outstanding I/O to the path.
134
135                        service-time 0
136                                    (Since 2.6.31 kernel) Choose the path  for
137                                    the  next bunch of I/O based on the amount
138                                    of outstanding I/O to  the  path  and  its
139                                    relative throughput.
140
141                        historical-service-time 0
142                                    (Since 5.8 kernel) Choose the path for the
143                                    next bunch of IOs based on the  estimation
144                                    of  future  service time based on the his‐
145                                    tory of previous  I/O  submitted  to  each
146                                    path.
147
148                        The default is: service-time 0
149
150       path_grouping_policy
151                        The  default path grouping policy to apply to unspeci‐
152                        fied multipaths. Possible values are:
153
154                        failover    One path per priority group.
155
156                        multibus    All paths in one priority group.
157
158                        group_by_serial
159                                    One priority group per serial number.
160
161                        group_by_prio
162                                    One priority  group  per  priority  value.
163                                    Priorities  are determined by callout pro‐
164                                    grams  specified  as  a  global,  per-con‐
165                                    troller  or  per-multipath  option  in the
166                                    configuration file.
167
168                        group_by_node_name
169                                    One priority group per target  node  name.
170                                    Target   node   names   are   fetched   in
171                                    /sys/class/fc_transport/target*/node_name.
172
173                        The default is: failover
174
175       uid_attrs        Setting this option activates merging uevents by WWID,
176                        which  may  improve  uevent processing effiency. More‐
177                        over, it's an alternative method to configure the udev
178                        properties  to use for determining unique path identi‐
179                        fiers (WWIDs).
180
181                        The value of this option is a space separated list  of
182                        records   like  "type:ATTR",  where  type  is  matched
183                        against the beginning of the device  node  name  (e.g.
184                        sd:ATTR matches sda), and ATTR is the name of the udev
185                        property to use for matching devices.
186
187                        If this option is configured and  matches  the  device
188                        node  name of a device, it overrides any other config‐
189                        ured  methods for determining the WWID  for  this  de‐
190                        vice.
191
192                        The default is: <unset>. To enable uevent merging, set
193                        it e.g. to "sd:ID_SERIAL dasd:ID_UID nvme:ID_WWN".
194
195       uid_attribute    The udev attribute providing a unique path  identifier
196                        (WWID).  If  uid_attribute is set to the empty string,
197                        WWID determination is  done  using  the  sysfs  method
198                        rather then using udev (not recommended in production;
199                        see WWID generation below).
200
201                        The default is: ID_SERIAL, for SCSI devices
202
203                        The default is: ID_UID, for DASD devices
204
205                        The default is: ID_WWN, for NVMe devices
206
207       getuid_callout   (Superseded by uid_attribute) The default program  and
208                        args  to  callout  to obtain a unique path identifier.
209                        Should be specified with an absolute path.
210
211                        The default is: <unset>
212
213       prio             The name of the path priority routine.  The  specified
214                        routine  should  return a numeric value specifying the
215                        relative priority of this path. Higher number  have  a
216                        higher  priority.   "none" is a valid value. Currently
217                        the following path priority routines are implemented:
218
219                        const       Return a constant priority of 1.
220
221                        sysfs       Use the sysfs attributes access_state  and
222                                    preferred_path to generate the path prior‐
223                                    ity. This prioritizer accepts the optional
224                                    prio_arg exclusive_pref_bit.
225
226                        emc         (Hardware-dependent)   Generate  the  path
227                                    priority for DGC class arrays as  CLARiiON
228                                    CX/AX and EMC VNX and Unity families.
229
230                        alua        (Hardware-dependent)   Generate  the  path
231                                    priority based on  the  SCSI-3  ALUA  set‐
232                                    tings.  This  prioritizer  accepts the op‐
233                                    tional prio_arg exclusive_pref_bit.
234
235                        ontap       (Hardware-dependent)  Generate  the   path
236                                    priority  for  NetApp  ONTAP class and OEM
237                                    arrays as IBM NSeries.
238
239                        rdac        (Hardware-dependent)  Generate  the   path
240                                    priority for LSI/Engenio/NetApp RDAC class
241                                    as NetApp SANtricity E/EF Series, and  OEM
242                                    arrays from IBM DELL SGI STK and SUN.
243
244                        hp_sw       (Hardware-dependent)   Generate  the  path
245                                    priority  for  HP/COMPAQ/DEC   HSG80   and
246                                    MSA/HSV  arrays  with  Active/Standby mode
247                                    exclusively.
248
249                        hds         (Hardware-dependent)  Generate  the   path
250                                    priority  for  Hitachi AMS families of ar‐
251                                    rays other than AMS 2000.
252
253                        random      Generate a random priority between  1  and
254                                    10.
255
256                        weightedpath
257                                    Generate  the  path  priority based on the
258                                    regular expression and the  priority  pro‐
259                                    vided as argument. Requires prio_args key‐
260                                    word.
261
262                        path_latency
263                                    Generate the path priority based on a  la‐
264                                    tency  algorithm.  Requires prio_args key‐
265                                    word.
266
267                        ana         (Hardware-dependent)  Generate  the   path
268                                    priority based on the NVMe ANA settings.
269
270                        datacore    (Hardware-dependent)   Generate  the  path
271                                    priority for some DataCore storage arrays.
272                                    Requires prio_args keyword.
273
274                        iet         (iSCSI  only)  Generate  path priority for
275                                    iSCSI targets based  on  IP  address.  Re‐
276                                    quires prio_args keyword.
277
278                        The default depends on the detect_prio setting: If de‐
279                        tect_prio is yes (default), the default priority algo‐
280                        rithm  is  sysfs (except for NetAPP E-Series, where it
281                        is alua). If detect_prio is no, the  default  priority
282                        algorithm is const.
283
284       prio_args        Arguments  to  pass to to the prio function. This only
285                        applies to certain prioritizers:
286
287                        weighted    Needs a  value  of  the  form  "<hbtl|dev‐
288                                    name|serial|wwn> <regex1> <prio1> <regex2>
289                                    <prio2> ..."
290
291                                    hbtl    Regex can be of SCSI H:B:T:L  for‐
292                                            mat.   For   example:   1:0:.:.  ,
293                                            *:0:0:.
294
295                                    devname Regex can be of device  name  for‐
296                                            mat. For example: sda , sd.e
297
298                                    serial  Regex can be of serial number for‐
299                                            mat. For  example:  .*J1FR.*324  .
300                                            The   serial   can  be  looked  up
301                                            through sysfs or by running multi‐
302                                            pathd  show paths format "%z". For
303                                            example: 0395J1FR904324
304
305                                    wwn     Regex   can   be   of   the   form
306                                            "host_wwnn:host_wwpn:tar‐
307                                            get_wwnn:target_wwpn" these values
308                                            can  be looked up through sysfs or
309                                            by running multipathd  show  paths
310                                            format "%N:%R:%n:%r". For example:
311                                            0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.*
312                                            ,       .*:.*:iqn.2009-10.com.red‐
313                                            hat.msp.lab.ask-06:.*
314
315                        path_latency
316                                    Needs a value  of  the  form  "io_num=<20>
317                                    base_num=<10>"
318
319                                    io_num  The number of read IOs sent to the
320                                            current path continuously, used to
321                                            calculate  the  average  path  la‐
322                                            tency.  Valid Values: Integer, [2,
323                                            200].
324
325                                    base_num
326                                            The base number value of logarith‐
327                                            mic scale, used to partition  dif‐
328                                            ferent  priority ranks. Valid Val‐
329                                            ues: Integer, [2, 10]. And Max av‐
330                                            erage  latency  value is 100s, min
331                                            average latency value is 1us.  For
332                                            example: If base_num=10, the paths
333                                            will be grouped in priority groups
334                                            with  path  latency  <=1us,  (1us,
335                                            10us],  (10us,   100us],   (100us,
336                                            1ms],  (1ms, 10ms], (10ms, 100ms],
337                                            (100ms,  1s],  (1s,  10s],   (10s,
338                                            100s], >100s.
339
340                        alua        If  exclusive_pref_bit  is set, paths with
341                                    the preferred path bit set will always  be
342                                    in their own path group.
343
344                        sysfs       If  exclusive_pref_bit  is set, paths with
345                                    the preferred path bit set will always  be
346                                    in their own path group.
347
348                        datacore
349
350                                    preferredsds
351                                            (Mandatory)   The  preferred  "SDS
352                                            name".
353
354                                    timeout (Optional) The timeout for the IN‐
355                                            QUIRY, in ms.
356
357                        iet
358
359                                    preferredip=...
360                                            (Mandatory)  Th  preferred  IP ad‐
361                                            dress, in dotted decimal notation,
362                                            for iSCSI targets.
363
364                        The default is: <unset>
365
366       features         Specify  any device-mapper features to be used. Syntax
367                        is num list where num is the number, between 0 and  8,
368                        of  features in list.  Possible values for the feature
369                        list are:
370
371                        queue_if_no_path
372                                    (Deprecated, superseded by  no_path_retry)
373                                    Queue I/O if no path is active.  Identical
374                                    to the no_path_retry with queue value.  If
375                                    both  this  feature  and no_path_retry are
376                                    set, the latter  value  takes  precedence.
377                                    See KNOWN ISSUES.
378
379                        pg_init_retries <times>
380                                    (Since  kernel  2.6.24) Number of times to
381                                    retry pg_init, it must be  between  1  and
382                                    50.
383
384                        pg_init_delay_msecs <msecs>
385                                    (Since  kernel 2.6.38) Number of msecs be‐
386                                    fore pg_init retry, it must be  between  0
387                                    and 60000.
388
389                        queue_mode <mode>
390                                    (Since kernel 4.8) Select the the queueing
391                                    mode per multipath device.  <mode> can  be
392                                    bio,  rq  or mq, which corresponds to bio-
393                                    based, request-based, and block-multiqueue
394                                    (blk-mq) request-based, respectively.  The
395                                    default depends on  the  kernel  parameter
396                                    dm_mod.use_blk_mq.  It is mq if the latter
397                                    is set, and rq otherwise.
398
399                        The default is: <unset>
400
401       path_checker     The default method used to determine the path's state.
402                        The synchronous checkers (all except tur and directio)
403                        will cause multipathd to pause most activity,  waiting
404                        up to checker_timeout seconds for the path to respond.
405                        The asynchronous checkers (tur and directio) will  not
406                        pause multipathd. Instead, multipathd will check for a
407                        response once per second, until  checker_timeout  sec‐
408                        onds have elapsed. Possible values are:
409
410                        readsector0 (Deprecated)  Read the first sector of the
411                                    device. This checker is being  deprecated,
412                                    please use tur instead.
413
414                        tur         Issue a TEST UNIT READY command to the de‐
415                                    vice.
416
417                        emc_clariion
418                                    (Hardware-dependent)  Query  the   DGC/EMC
419                                    specific  EVPD  page 0xC0 to determine the
420                                    path state for CLARiiON CX/AX and EMC  VNX
421                                    and Unity arrays families.
422
423                        hp_sw       (Hardware-dependent)  Check the path state
424                                    for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
425                                    with Active/Standby mode exclusively.
426
427                        rdac        (Hardware-dependent)  Check the path state
428                                    for LSI/Engenio/NetApp RDAC class  as  Ne‐
429                                    tApp  SANtricity  E/EF Series, and OEM ar‐
430                                    rays from IBM DELL SGI STK and SUN.
431
432                        directio    Read the first  sector  with  direct  I/O.
433                                    This  checker  could  cause  spurious path
434                                    failures  under  high   load.   Increasing
435                                    checker_timeout can help with this.
436
437                        cciss_tur   (Hardware-dependent)  Check the path state
438                                    for  HP/COMPAQ  Smart  Array(CCISS)   con‐
439                                    trollers.
440
441                        none        Do  not  check the device, fallback to use
442                                    the values retrieved from sysfs
443
444                        The default is: tur
445
446       alias_prefix     The user_friendly_names prefix.
447
448                        The default is: mpath
449
450       failback         Tell multipathd how to manage path group failback.  To
451                        select  immediate  or a value, it's mandatory that the
452                        device has support for a working prioritizer.
453
454                        immediate   Immediately failback to the highest prior‐
455                                    ity pathgroup that contains active paths.
456
457                        manual      Do not perform automatic failback.
458
459                        followover  Used  to  deal with multiple computers ac‐
460                                    cessing the  same  Active/Passive  storage
461                                    devices.  Only  perform automatic failback
462                                    when the first path of a pathgroup becomes
463                                    active. This keeps a cluster node from au‐
464                                    tomatically failing back when another node
465                                    requested the failover.
466
467                        values > 0  Deferred  failback  (time to defer in sec‐
468                                    onds).
469
470                        The default is: manual
471
472       rr_min_io        Number of I/O requests  to  route  to  a  path  before
473                        switching  to the next in the same path group. This is
474                        only for Block I/O(BIO) based multipath and only apply
475                        to round-robin path_selector.
476
477                        The default is: 1000
478
479       rr_min_io_rq     Number  of  I/O  requests  to  route  to a path before
480                        switching to the next in the same path group. This  is
481                        only  for  Request  based  multipath and only apply to
482                        round-robin path_selector.
483
484                        The default is: 1
485
486       max_fds          Specify the maximum number of  file  descriptors  that
487                        can  be  opened  by  multipath and multipathd. This is
488                        equivalent to ulimit -n. A value of max will set  this
489                        to the system limit from /proc/sys/fs/nr_open. If this
490                        is not set, the maximum number of open  fds  is  taken
491                        from  the  calling  process. It is usually 1024. To be
492                        safe, this should be set  to  the  maximum  number  of
493                        paths plus 32, if that number is greated than 1024.
494
495                        The default is: max
496
497       rr_weight        If  set  to priorities the multipath configurator will
498                        assign path weights as "path prio * rr_min_io". Possi‐
499                        ble  values are priorities or uniform .  Only apply to
500                        round-robin path_selector.
501
502                        The default is: uniform
503
504       no_path_retry    Specify what to do when all paths are  down.  Possible
505                        values are:
506
507                        value > 0   Number of retries until disable I/O queue‐
508                                    ing.
509
510                        fail        For immediate failure (no I/O queueing).
511
512                        queue       For never stop I/O  queueing,  similar  to
513                                    queue_if_no_path. See KNOWN ISSUES.
514
515                        The default is: fail
516
517       queue_without_daemon
518                        If set to no , when multipathd stops, queueing will be
519                        turned off for all devices.  This is  useful  for  de‐
520                        vices  that  set  no_path_retry.  If a machine is shut
521                        down while all paths to a device are down, it is  pos‐
522                        sible  to  hang waiting for I/O to return from the de‐
523                        vice after multipathd has been stopped. Without multi‐
524                        pathd running, access to the paths cannot be restored,
525                        and the kernel cannot be told to  stop  queueing  I/O.
526                        Setting queue_without_daemon to no , avoids this prob‐
527                        lem.
528
529                        The default is: no
530
531       checker_timeout  Specify the timeout to use for path checkers and  pri‐
532                        oritizers,  in  seconds.  Only prioritizers that issue
533                        scsi commands use checker_timeout.  If a path does not
534                        respond  to  the checker command after checker_timeout
535                        seconds have elapsed, it is considered down.
536
537                        The default is: in /sys/block/sd<x>/device/timeout
538
539       allow_usb_devices
540                        If set to no , all USB devices will be skipped  during
541                        path  discovery. If you intend to use multipath on USB
542                        attached devices, set this to yes.
543
544                        The default is: no
545
546       flush_on_last_del
547                        If set to yes , multipathd will disable queueing  when
548                        the last path to a device has been deleted.
549
550                        The default is: no
551
552       user_friendly_names
553                        If  set  to  yes , using the bindings file /etc/multi‐
554                        path/bindings to assign a persistent and unique  alias
555                        to  the  multipath, in the form of mpath<n>. If set to
556                        no use the WWID as the alias. In either case  this  be
557                        will be overridden by any specific aliases in the mul‐
558                        tipaths section.
559
560                        The default is: no
561
562       fast_io_fail_tmo Specify the number of seconds the SCSI layer will wait
563                        after  a problem has been detected on a FC remote port
564                        before failing I/O to devices  on  that  remote  port.
565                        This should be smaller than dev_loss_tmo. Setting this
566                        to off will disable the timeout.
567
568                        The default is: 5
569
570       dev_loss_tmo     Specify the number of seconds the SCSI layer will wait
571                        after  a problem has been detected on a FC remote port
572                        before removing it from the system. This can be set to
573                        "infinity"   which   sets  it  to  the  max  value  of
574                        2147483647 seconds, or 68 years. It will be  automati‐
575                        cally   adjusted   to   the   overall  retry  interval
576                        no_path_retry * polling_interval if a  number  of  re‐
577                        tries  is  given  with  no_path_retry  and the overall
578                        retry  interval   is   longer   than   the   specified
579                        dev_loss_tmo  value.   The  Linux kernel will cap this
580                        value to 600 if fast_io_fail_tmo is not set. See KNOWN
581                        ISSUES.
582
583                        The default is: 600
584
585       eh_deadline      Specify  the  maximum number of seconds the SCSI layer
586                        will spend doing  error  handling  when  scsi  devices
587                        fail. After this timeout the scsi layer will perform a
588                        full HBA reset. Setting this may be necessary in cases
589                        where the rport is never lost, so fast_io_fail_tmo and
590                        dev_loss_tmo will never trigger, but (frequently do to
591                        load)  scsi  commands  still hang. Note: when the scsi
592                        error handler performs the HBA reset, all target paths
593                        on  that HBA will be affected. eh_deadline should only
594                        be set in cases where all targets on the affected HBAs
595                        are multipathed.
596
597                        The default is: <unset>
598
599       bindings_file    The  full pathname of the binding file to be used when
600                        the user_friendly_names option is set.
601
602                        The default is: /etc/multipath/bindings
603
604       wwids_file       The full pathname of the WWIDs file, which is used  by
605                        multipath  to  keep track of the WWIDs for LUNs it has
606                        created multipath devices on in the past.
607
608                        The default is: /etc/multipath/wwids
609
610       prkeys_file      The full pathname of the prkeys file, which is used by
611                        multipathd to keep track of the persistent reservation
612                        key used for a specific WWID, when reservation_key  is
613                        set to file.
614
615                        The default is: /etc/multipath/prkeys
616
617       log_checker_err  If  set  to  once  ,  multipathd  logs  the first path
618                        checker error at logging level 2. Any later errors are
619                        logged at level 3 until the device is restored. If set
620                        to always , multipathd always logs  the  path  checker
621                        error at logging level 2.
622
623                        The default is: always
624
625       reservation_key  This  is  the  service  action reservation key used by
626                        mpathpersist. It must be set for all multipath devices
627                        using persistent reservations, and it must be the same
628                        as the RESERVATION KEY field of the PERSISTENT RESERVE
629                        OUT parameter list which contains an 8-byte value pro‐
630                        vided by the application client to the  device  server
631                        to identify the I_T nexus. If the --param-aptpl option
632                        is used when registering the  key  with  mpathpersist,
633                        :aptpl  must be appended to the end of the reservation
634                        key.
635
636                        Alternatively, this can be set  to  file,  which  will
637                        store  the  RESERVATION KEY registered by mpathpersist
638                        in the prkeys_file. multipathd will then use this  key
639                        to register additional paths as they appear.  When the
640                        registration is removed, the RESERVATION  KEY  is  re‐
641                        moved from the prkeys_file. The prkeys file will auto‐
642                        matically keep track of whether the key was registered
643                        with --param-aptpl.
644
645                        The default is: <unset>
646
647       all_tg_pt        Set the 'all targets ports' flag when registering keys
648                        with mpathpersist. Some arrays automatically  set  and
649                        clear  registration  keys  on  all target ports from a
650                        host,  instead  of  per  target  port  per  host.  The
651                        ALL_TG_PT  flag must be set to successfully use mpath‐
652                        persist on these arrays. Setting this option is  iden‐
653                        tical to calling mpathpersist with --param-alltgpt
654
655                        The default is: no
656
657       retain_attached_hw_handler
658                        (Obsolete  for  kernels  >= 4.3) If set to yes and the
659                        SCSI layer has already attached a hardware_handler  to
660                        the device, multipath will not force the device to use
661                        the hardware_handler specified  by  mutipath.conf.  If
662                        the  SCSI  layer  has not attached a hardware handler,
663                        multipath will continue to use its configured hardware
664                        handler.
665
666                        The default is: yes
667
668                        Important  Note:  Linux kernel 4.3 or newer always be‐
669                        haves as if "retain_attached_hw_handler yes" was set.
670
671       detect_prio      If set to yes , multipath will try to  detect  if  the
672                        device  supports  SCSI-3  ALUA. If so, the device will
673                        automatically use the sysfs  prioritizer  if  the  re‐
674                        quired sysf attributes access_state and preferred_path
675                        are supported, or the alua prioritizer if not. If  set
676                        to no , the prioritizer will be selected as usual.
677
678                        The default is: yes
679
680       detect_checker   if  set  to  yes , multipath will try to detect if the
681                        device supports SCSI-3 ALUA. If so,  the  device  will
682                        automatically  use the tur checker. If set to no , the
683                        checker will be selected as usual.
684
685                        The default is: yes
686
687       force_sync       If set to yes , multipathd will call the path checkers
688                        in  sync  mode only.  This means that only one checker
689                        will run at a time.  This is useful in the case  where
690                        many  multipathd  checkers  running in parallel causes
691                        significant CPU pressure.
692
693                        The default is: no
694
695       strict_timing    If set to yes ,  multipathd  will  start  a  new  path
696                        checker  loop  after  exactly one second, so that each
697                        path check will occur at exactly polling_interval sec‐
698                        onds.  On  busy  systems path checks might take longer
699                        than one second; here the missing ticks  will  be  ac‐
700                        counted  for  on  the  next  round.  A warning will be
701                        printed if path checks take longer than polling_inter‐
702                        val seconds.
703
704                        The default is: no
705
706       deferred_remove  If  set  to yes , multipathd will do a deferred remove
707                        instead of a regular remove when the last path  device
708                        has  been  deleted.   This means that if the multipath
709                        device is still in use, it will be freed when the last
710                        user closes it.  If path is added to the multipath de‐
711                        vice before the last user closes it, the deferred  re‐
712                        move will be canceled.
713
714                        The default is: no
715
716       partition_delimiter
717                        This  parameter  controls  how  multipath  chooses the
718                        names of partition devices of multipath maps if a mul‐
719                        tipath map is renamed (e.g. if a map alias is added or
720                        changed). If this parameter is set to a  string  other
721                        than  "/UNSET/" (even the empty string), multipath in‐
722                        serts that string between device  name  and  partition
723                        number to construct the partition device name.  Other‐
724                        wise (i.e. if this parameter is unset or has the value
725                        "/UNSET/"),  the  behavior depends on the map name: if
726                        it ends in a digit, a "p" is inserted between name and
727                        partition  number;  otherwise, the partition number is
728                        simply appended.  Distributions may use a non-null de‐
729                        fault  value  for  this option; in this case, the user
730                        must set it to "/UNSET/" to obtain the  original  <un‐
731                        set>  behavior.  Use multipath -T to check the current
732                        settings.
733
734                        The default is: <unset>
735
736       config_dir       If set to  anything  other  than  "",  multipath  will
737                        search  this  directory alphabetically for file ending
738                        in ".conf" and it will read configuration  information
739                        from  them,  just as if it was in /etc/multipath.conf.
740                        config_dir must either be "" or a fully qualified  di‐
741                        rectory name.
742
743                        The default is: /etc/multipath/conf.d/
744
745       san_path_err_threshold
746                        If  set  to  a  value  greater than 0, multipathd will
747                        watch paths and check how many times a path  has  been
748                        failed  due  to  errors.If the number of failures on a
749                        particular    path     is     greater     then     the
750                        san_path_err_threshold,  then  the path will not rein‐
751                        state  till  san_path_err_recovery_time.  These   path
752                        failures   should  occur  within  a  san_path_err_for‐
753                        get_rate checks, if not we will consider the  path  is
754                        good  enough  to reinstantate. See "Shaky paths detec‐
755                        tion" below.
756
757                        The default is: no
758
759       san_path_err_forget_rate
760                        If set to a value  greater  than  0,  multipathd  will
761                        check  whether  the  path  failures  has exceeded  the
762                        san_path_err_threshold within  this  many  checks  i.e
763                        san_path_err_forget_rate  .  If  so  we will not rein‐
764                        stante the path till  san_path_err_recovery_time.  See
765                        "Shaky paths detection" below.
766
767                        The default is: no
768
769       san_path_err_recovery_time
770                        If set to a value greater than 0, multipathd will make
771                        sure  that  when  path  failures  has   exceeded   the
772                        san_path_err_threshold within san_path_err_forget_rate
773                        then the path will  be  placed  in  failed  state  for
774                        san_path_err_recovery_time               duration.Once
775                        san_path_err_recovery_time has timeout  we will  rein‐
776                        stante  the  failed path .  san_path_err_recovery_time
777                        value should be in secs.  See "Shaky paths  detection"
778                        below.
779
780                        The default is: no
781
782       marginal_path_double_failed_time
783                        One  of  the  four parameters of supporting path check
784                        based on accounting IO error such as intermittent  er‐
785                        ror.  When  a  path  failed event occurs twice in mar‐
786                        ginal_path_double_failed_time seconds due to an IO er‐
787                        ror and all the other three parameters are set, multi‐
788                        pathd will fail the path and enqueue this path into  a
789                        queue of which members are sent a couple of continuous
790                        direct reading asynchronous IOs at a fixed sample rate
791                        of  10HZ  to  start  IO  error accounting process. See
792                        "Shaky paths detection" below.
793
794                        The default is: no
795
796       marginal_path_err_sample_time
797                        One of the four parameters of  supporting  path  check
798                        based  on accounting IO error such as intermittent er‐
799                        ror. If it is set to a value no less than 120, when  a
800                        path  fail  event  occurs  twice in marginal_path_dou‐
801                        ble_failed_time second due to an IO error,  multipathd
802                        will  fail the path and enqueue this path into a queue
803                        of which members are sent a couple of  continuous  di‐
804                        rect  reading  asynchronous IOs at a fixed sample rate
805                        of 10HZ to start the IO  accounting  process  for  the
806                        path  will last for marginal_path_err_sample_time.  If
807                        the rate of IO error on a particular path  is  greater
808                        than  the  marginal_path_err_rate_threshold,  then the
809                        path     will     not     reinstate      for      mar‐
810                        ginal_path_err_recheck_gap_time  seconds  unless there
811                        is    only    one    active    path.    After     mar‐
812                        ginal_path_err_recheck_gap_time expires, the path will
813                        be requeueed for rechecking.  If  checking  result  is
814                        good  enough,  the path will be reinstated. See "Shaky
815                        paths detection" below.
816
817                        The default is: no
818
819       marginal_path_err_rate_threshold
820                        The error rate threshold as a permillage (1/1000). One
821                        of  the four parameters of supporting path check based
822                        on accounting IO error such as intermittent error. Re‐
823                        fer  to  marginal_path_err_sample_time. If the rate of
824                        IO errors on a particular path is  greater  than  this
825                        parameter,  then  the path will not reinstate for mar‐
826                        ginal_path_err_recheck_gap_time seconds  unless  there
827                        is  only  one active path. See "Shaky paths detection"
828                        below.
829
830                        The default is: no
831
832       marginal_path_err_recheck_gap_time
833                        One of the four parameters of  supporting  path  check
834                        based  on accounting IO error such as intermittent er‐
835                        ror. Refer to marginal_path_err_sample_time.  If  this
836                        parameter  is set to a positive value, the failed path
837                        of  which the  IO  error  rate  is  larger  than  mar‐
838                        ginal_path_err_rate_threshold  will  be kept in failed
839                        state for marginal_path_err_recheck_gap_time  seconds.
840                        When  marginal_path_err_recheck_gap_time  seconds  ex‐
841                        pires, the path will be  requeueed  for  checking.  If
842                        checking result is good enough, the path will be rein‐
843                        stated, or else it will keep failed. See "Shaky  paths
844                        detection" below.
845
846                        The default is: no
847
848       delay_watch_checks
849                        This    option    is   deprecated,   and   mapped   to
850                        san_path_err_forget_rate.  If this is set to  a  value
851                        greater  than  0  and no san_path_err options are set,
852                        san_path_err_forget_rate will be set to the  value  of
853                        delay_watch_checks  and san_path_err_threshold will be
854                        set  to  1.   See  the  san_path_err_forget_rate   and
855                        san_path_err_threshold  options,  and "Shaky paths de‐
856                        tection" below for more information.
857
858                        The default is: no
859
860       delay_wait_checks
861                        This   option   is   deprecated,   and    mapped    to
862                        san_path_err_recovery_time.  If this is set to a value
863                        greater than 0 and no san_path_err  options  are  set,
864                        san_path_err_recovery_time will be set to the value of
865                        delay_wait_checks  times  max_polling_interval.   This
866                        will  give  approximately  the  same  wait time as de‐
867                        lay_wait_checks      previously      did.        Also,
868                        san_path_err_threshold  will  be  set  to  1.  See the
869                        san_path_err_recovery_time and  san_path_err_threshold
870                        options,  and  "Shaky  paths detection" below for more
871                        information.
872
873                        The default is: no
874
875       marginal_pathgroups
876                        If set to no, the delay_*_checks, marginal_path_*, and
877                        san_path_err_* options will keep marginal, or "shaky",
878                        paths from being reinstated until they have been moni‐
879                        tored  for  some time. This can cause situations where
880                        all non-marginal paths are down, and no paths are  us‐
881                        able  until  multipathd  detects this and reinstates a
882                        marginal path. If the multipath device is not  config‐
883                        ured  to queue IO in this case, it can cause IO errors
884                        to occur, even though there are marginal paths  avail‐
885                        able.  However, if this option is set to yes, when one
886                        of the marginal path detecting methods determines that
887                        a  path  is marginal, it will be reinstated and placed
888                        in a seperate pathgroup that will only be  used  after
889                        all the non-marginal pathgroups have been tried first.
890                        This prevents the possibility of  IO  errors  occuring
891                        while  marginal paths are still usable. After the path
892                        has been monitored for the configured time, and is de‐
893                        clared  healthy,  it  will  be  returned to its normal
894                        pathgroup. See "Shaky paths detection" below for  more
895                        information.
896
897                        The default  is: no
898
899       find_multipaths  This  option controls whether multipath and multipathd
900                        try to create multipath maps over non-blacklisted  de‐
901                        vices they encounter. This matters a) when a device is
902                        encountered by multipath -u during udev rule  process‐
903                        ing  (a  device  is blocked from further processing by
904                        higher layers - such as LVM - if and only if it´s con‐
905                        sidered  a  valid  multipath device path), and b) when
906                        multipathd detects a new device. The following  values
907                        are possible:
908
909                        strict    Both  multipath  and  multipathd  treat only
910                                  such devices as multipath devices which have
911                                  been part of a multipath map previously, and
912                                  which   are   therefore   listed   in    the
913                                  wwids_file. Users can manually set up multi‐
914                                  path maps using the multipathd add map  com‐
915                                  mand.  Once  set up manually, the map is re‐
916                                  membered in the wwids file and will  be  set
917                                  up automatically in the future.
918
919                        no        Multipath  behaves  like  strict. Multipathd
920                                  behaves like greedy.
921
922                        yes       Both multipathd and multipath treat a device
923                                  as  multipath  device  if the conditions for
924                                  strict are met, or  if  at  least  two  non-
925                                  blacklisted  paths  with  the same WWID have
926                                  been detected.
927
928                        greedy    Both multipathd and  multipath  treat  every
929                                  non-blacklisted  device  as multipath device
930                                  path.
931
932                        smart     This differs from find_multipaths  yes  only
933                                  in  the  way it treats new devices for which
934                                  only one path has been  detected  yet.  When
935                                  such  a  device  is  first encounted in udev
936                                  rules, it is treated as a multipath  device.
937                                  multipathd  waits  whether  additional paths
938                                  with the same WWID appears. If that happens,
939                                  it  sets  up  a multipath map. If it doesn´t
940                                  happen until a timeout expires, or  if  set‐
941                                  ting up the map fails, a new uevent is trig‐
942                                  gered for the device; at second encounter in
943                                  the  udev  rules, the device will be treated
944                                  as non-multipath and passed on to upper lay‐
945                                  ers.  Note: this may cause delays during de‐
946                                  vice detection if there are single-path  de‐
947                                  vices which aren´t blacklisted.
948
949                        The default is: strict
950
951       find_multipaths_timeout
952                        Timeout,  in seconds, to wait for additional paths af‐
953                        ter  detecting  the  first  one,  if   find_multipaths
954                        "smart"  (see above) is set. If the value is positive,
955                        this timeout is used for all unknown,  non-blacklisted
956                        devices  encountered. If the value is negative (recom‐
957                        mended), it's only applied  to  "known"  devices  that
958                        have an entry in multipath's hardware table, either in
959                        the built-in table or in a device section; other ("un‐
960                        known") devices will use a timeout of only 1 second to
961                        avoid booting delays.  The  value  0  means  "use  the
962                        built-in default". If find_multipath has a value other
963                        than smart, this option has no effect.
964
965                        The default is: -10 (10s for known and 1s for  unknown
966                        hardware)
967
968       uxsock_timeout   CLI  receive  timeout in milliseconds. For larger sys‐
969                        tems CLI commands might timeout before the  multipathd
970                        lock is released and the CLI command can be processed.
971                        This will result in  errors  like  "timeout  receiving
972                        packet"  to  be  returned from CLI commands.  In these
973                        cases it is recommended to increase the CLI timeout to
974                        avoid those issues.
975
976                        The default is: 4000
977
978       retrigger_tries  Sets  the  number  of times multipathd will try to re‐
979                        trigger a uevent to get the WWID.
980
981                        The default is: 3
982
983       retrigger_delay  Sets the amount of time, in seconds, to  wait  between
984                        retriggers.
985
986                        The default is: 10
987
988       missing_uev_wait_timeout
989                        Controls  how many seconds multipathd will wait, after
990                        a new multipath device is created, to receive a change
991                        event  from  udev for the device, before automatically
992                        enabling device reloads. Usually multipathd will delay
993                        reloads  on a device until it receives a change uevent
994                        from the initial table load.
995
996                        The default is: 30
997
998       skip_kpartx      If set to yes , kpartx will not  automatically  create
999                        partitions on the device.
1000
1001                        The default is: no
1002
1003       disable_changed_wwids
1004                        This  option is deprecated and ignored. If the WWID of
1005                        a path suddenly changes, multipathd handles it  as  if
1006                        it was removed and then added again.
1007
1008       remove_retries   This  sets how may times multipath will retry removing
1009                        a device that is in-use.  Between each attempt, multi‐
1010                        path will sleep 1 second.
1011
1012                        The default is: 0
1013
1014       max_sectors_kb   Sets  the  max_sectors_kb device parameter on all path
1015                        devices and the  multipath  device  to  the  specified
1016                        value.
1017
1018                        The default is: <device dependent>
1019
1020       ghost_delay      Sets  the  number  of seconds that multipath will wait
1021                        after creating a device with only ghost  paths  before
1022                        marking  it  ready  for use in systemd. This gives the
1023                        active paths time to appear before the multipath  runs
1024                        the  hardware handler to switch the ghost paths to ac‐
1025                        tive ones. Setting this to 0 or on makes multipath im‐
1026                        mediately  mark  a  device  with  only  ghost paths as
1027                        ready.
1028
1029                        The default is: no
1030
1031       enable_foreign   Enables or disables  foreign  libraries  (see  section
1032                        FOREIGN MULTIPATH SUPPORT below). The value is a regu‐
1033                        lar expression; foreign libraries are loaded if  their
1034                        name (e.g. "nvme") matches the expression. By default,
1035                        no foreign libraries are enabled. Set this  to  "nvme"
1036                        to  enable  NVMe  native multipath support, or ".*" to
1037                        enable all foreign libraries.
1038
1039                        The default is: "NONE"
1040
1041

blacklist and blacklist_exceptions sections

1043       The blacklist section is used to exclude specific devices from the mul‐
1044       tipath  topology.  It  is  most commonly used to exclude local disks or
1045       non-disk devices (such as LUNs for the storage array  controller)  from
1046       being handled by multipath-tools.
1047
1048       In  the  blacklist and blacklist_exceptions sections, starting a quoted
1049       value with an exclamation mark "!" will invert the matching of the rest
1050       of  the  regular  expression.  For instance, "!^sd[a-z]" will match all
1051       values that do not start with "sd[a-z]". The exclamation  mark  can  be
1052       escaped "\!" to match a literal ! at the start of a regular expression.
1053       Note: The exclamation mark must be inside quotes, otherwise it will  be
1054       treated as starting a comment.
1055
1056       The  blacklist_exceptions  section is used to revert the actions of the
1057       blacklist section. This allows one to selectively include ("whitelist")
1058       devices  which  would normally be excluded via the blacklist section. A
1059       common usage is to blacklist "everything" using a catch-all regular ex‐
1060       pression,  and  create  specific blacklist_exceptions entries for those
1061       devices that should be handled by multipath-tools.
1062
1063       The following keywords are recognized in both  sections.  The  defaults
1064       are empty unless explicitly stated.
1065
1066       devnode          Regular expression matching the device nodes to be ex‐
1067                        cluded/included.
1068
1069                        The default blacklist consists of the regular  expres‐
1070                        sion  "!^(sd[a-z]|dasd[a-z]|nvme[0-9])".  This  causes
1071                        all device types other than scsi, dasd, and nvme to be
1072                        excluded from multipath handling by default.
1073
1074       wwid             Regular  expression for the World Wide Identifier of a
1075                        device to be excluded/included.
1076
1077       device           Subsection for the device description. This subsection
1078                        recognizes  the  vendor and product keywords. Both are
1079                        regular expressions. For a full description  of  these
1080                        keywords please see the devices section description.
1081
1082       property         Regular  expression  for an udev property. All devices
1083                        that  have  matching  udev  properties  will  be   ex‐
1084                        cluded/included.  The handling of the property keyword
1085                        is special, because if a property  blacklist_exception
1086                        is  set,  devices  must  have at least one whitelisted
1087                        udev property; otherwise  they're  treated  as  black‐
1088                        listed,  and  the  message "blacklisted, udev property
1089                        missing" is displayed in the logs.  For example,  set‐
1090                        ting     the     property    blacklist_exception    to
1091                        (SCSI_IDENT_|ID_WWN), will cause well-behaved SCSI de‐
1092                        vices  and devices that provide a WWN (World Wide Num‐
1093                        ber) to be included, and all others  to  be  excluded.
1094                        This works to exclude most non-multipathable devices.
1095
1096                        Note:  The behavior of this option has changed in mul‐
1097                        tipath-tools  0.8.2  compared  to  previous  versions.
1098                        Blacklisting  by missing properties is only applied to
1099                        devices  which  do  have  the  property  specified  by
1100                        uid_attribute (e.g. ID_SERIAL) set. Previously, it was
1101                        applied to every device, possibly causing  devices  to
1102                        be  blacklisted  because of temporary I/O error condi‐
1103                        tions.
1104
1105       protocol         Regular expression for the protocol of a device to  be
1106                        excluded/included.
1107
1108                        The  protocol  strings  that  multipath recognizes are
1109                        scsi:fcp,  scsi:spi,  scsi:ssa,  scsi:sbp,   scsi:srp,
1110                        scsi:iscsi, scsi:sas, scsi:adt, scsi:ata, scsi:unspec,
1111                        ccw, cciss, nvme, and undef.  The protocol that a path
1112                        is  using  can  be  viewed  by running multipathd show
1113                        paths format "%d %P"
1114
1115       For every device, these 5 blacklist criteria are evaluated in  the  the
1116       order  "property,  devnode,  device, protocol, wwid". If a device turns
1117       out to be blacklisted by any criterion, it's excluded from handling  by
1118       multipathd,  and the later criteria aren't evaluated any more. For each
1119       criterion, the whitelist takes precedence over the blacklist if  a  de‐
1120       vice matches both.
1121
1122       Note:  Besides the blacklist and whitelist, other configuration options
1123       such as find_multipaths have an impact on whether or not a given device
1124       is handled by multipath-tools.
1125

multipaths section

1127       The multipaths section allows setting attributes of multipath maps. The
1128       attributes that are set via the multipaths  section  (see  list  below)
1129       take  precedence over all other configuration settings, including those
1130       from the overrides section.
1131
1132       The only recognized attribute for the multipaths section is the  multi‐
1133       path subsection. If there are multiple multipath subsections matching a
1134       given WWID, the contents of these sections  are  merged,  and  settings
1135       from later entries take precedence.
1136
1137       The multipath subsection recognizes the following attributes:
1138
1139       wwid             (Mandatory)  World Wide Identifier. Detected multipath
1140                        maps are matched agains this  attribute.   Note  that,
1141                        unlike  the  wwid  attribute in the blacklist section,
1142                        this is not a regular expression or a substring; WWIDs
1143                        must match exactly inside the multipaths section.
1144
1145       alias            Symbolic name for the multipath map. This takes prece‐
1146                        dence over a an entry for the same WWID in  the  bind‐
1147                        ings_file.
1148
1149       The  following  attributes  are optional; if not set the default values
1150       are taken from the overrides, devices, or defaults section:
1151
1152              path_grouping_policy
1153              path_selector
1154              prio
1155              prio_args
1156              failback
1157              rr_weight
1158              no_path_retry
1159              rr_min_io
1160              rr_min_io_rq
1161              flush_on_last_del
1162              features
1163              reservation_key
1164              user_friendly_names
1165              deferred_remove
1166              san_path_err_threshold
1167              san_path_err_forget_rate
1168              san_path_err_recovery_time
1169              marginal_path_err_sample_time
1170              marginal_path_err_rate_threshold
1171              marginal_path_err_recheck_gap_time
1172              marginal_path_double_failed_time
1173              delay_watch_checks
1174              delay_wait_checks
1175              skip_kpartx
1176              max_sectors_kb
1177              ghost_delay
1178

devices section

1180       multipath-tools have a built-in device table with  reasonable  defaults
1181       for  more than 100 known multipath-capable storage devices. The devices
1182       section can be used to override these settings. If there  are  multiple
1183       matches  for a given device, the attributes of all matching entries are
1184       applied to it.  If an attribute is specified in several matching device
1185       subsections,  later entries take precedence. Thus, entries in files un‐
1186       der config_dir (in reverse alphabetical order) have the highest  prece‐
1187       dence, followed by entries in multipath.conf; the built-in hardware ta‐
1188       ble has the lowest precedence. Inside a configuration file,  later  en‐
1189       tries have higher precedence than earlier ones.
1190
1191       The  only  recognized  attribute  for the devices section is the device
1192       subsection. Devices detected in the system are matched against the  de‐
1193       vice  entries using the vendor, product, and revision fields, which are
1194       all POSIX Extended regular expressions (see regex(7)).
1195
1196       The vendor, product, and revision fields that multipath  or  multipathd
1197       detect  for devices in a system depend on the device type. For SCSI de‐
1198       vices, they correspond to the respective fields  of  the  SCSI  INQUIRY
1199       page.  In  general,  the command 'multipathd show paths format "%d %s"'
1200       command can be used to see the detected properties for all  devices  in
1201       the system.
1202
1203       The device subsection recognizes the following attributes:
1204
1205       vendor           (Mandatory)  Regular  expression  to  match the vendor
1206                        name.
1207
1208       product          (Mandatory) Regular expression to  match  the  product
1209                        name.
1210
1211       revision         Regular  expression  to match the product revision. If
1212                        not specified, any revision matches.
1213
1214       product_blacklist
1215                        Products with the given vendor  matching  this  string
1216                        are  blacklisted. This is equivalent to a device entry
1217                        in the blacklist section with the vendor attribute set
1218                        to  this entry's vendor, and the product attribute set
1219                        to the value of product_blacklist.
1220
1221       alias_prefix     The user_friendly_names prefix to use for this  device
1222                        type, instead of the default "mpath".
1223
1224       vpd_vendor       The  vendor  specific  vpd page information, using the
1225                        vpd page abbreviation.  The vpd page abbreviation  can
1226                        be  found  by  running  sg_vpd -e. multipathd will use
1227                        this information to gather device specific information
1228                        that can be displayed with the %g wilcard for the mul‐
1229                        tipathd show maps format  and  multipathd  show  paths
1230                        format commands. Currently only the hp3par vpd page is
1231                        supported.
1232
1233       hardware_handler The hardware handler to use for this device type.  The
1234                        following hardware handler are implemented:
1235
1236                        1 emc       (Hardware-dependent)  Hardware handler for
1237                                    DGC class arrays as CLARiiON CX/AX and EMC
1238                                    VNX and Unity families.
1239
1240                        1 rdac      (Hardware-dependent)  Hardware handler for
1241                                    LSI/Engenio/NetApp RDAC  class  as  NetApp
1242                                    SANtricity  E/EF  Series,  and  OEM arrays
1243                                    from IBM DELL SGI STK and SUN.
1244
1245                        1 hp_sw     (Hardware-dependent) Hardware handler  for
1246                                    HP/COMPAQ/DEC  HSG80  and  MSA/HSV  arrays
1247                                    with Active/Standby mode exclusively.
1248
1249                        1 alua      (Hardware-dependent) Hardware handler  for
1250                                    SCSI-3 ALUA compatible arrays.
1251
1252                        1 ana       (Hardware-dependent)  Hardware handler for
1253                                    NVMe ANA compatible arrays.
1254
1255                        The default is: <unset>
1256
1257                        Important Note: Linux kernels 4.3 and newer  automati‐
1258                        cally  attach a device handler to known devices (which
1259                        includes all devices supporting SCSI-3 ALUA) and  dis‐
1260                        allow  changing  the handler afterwards. Setting hard‐
1261                        ware_handler for such devices on these kernels has  no
1262                        effect.
1263
1264       The  following  attributes  are optional; if not set the default values
1265       are taken from the defaults section:
1266
1267              path_grouping_policy
1268              uid_attribute
1269              getuid_callout
1270              path_selector
1271              path_checker
1272              prio
1273              prio_args
1274              features
1275              failback
1276              rr_weight
1277              no_path_retry
1278              rr_min_io
1279              rr_min_io_rq
1280              fast_io_fail_tmo
1281              dev_loss_tmo
1282              flush_on_last_del
1283              user_friendly_names
1284              retain_attached_hw_handler
1285              detect_prio
1286              detect_checker
1287              deferred_remove
1288              san_path_err_threshold
1289              san_path_err_forget_rate
1290              san_path_err_recovery_time
1291              marginal_path_err_sample_time
1292              marginal_path_err_rate_threshold
1293              marginal_path_err_recheck_gap_time
1294              marginal_path_double_failed_time
1295              delay_watch_checks
1296              delay_wait_checks
1297              skip_kpartx
1298              max_sectors_kb
1299              ghost_delay
1300              all_tg_pt
1301

overrides section

1303       The overrides section recognizes the following optional attributes;  if
1304       not set the values are taken from the devices or defaults sections:
1305
1306              path_grouping_policy
1307              uid_attribute
1308              getuid_callout
1309              path_selector
1310              path_checker
1311              alias_prefix
1312              features
1313              prio
1314              prio_args
1315              failback
1316              rr_weight
1317              no_path_retry
1318              rr_min_io
1319              rr_min_io_rq
1320              flush_on_last_del
1321              fast_io_fail_tmo
1322              dev_loss_tmo
1323              user_friendly_names
1324              retain_attached_hw_handler
1325              detect_prio
1326              detect_checker
1327              deferred_remove
1328              san_path_err_threshold
1329              san_path_err_forget_rate
1330              san_path_err_recovery_time
1331              marginal_path_err_sample_time
1332              marginal_path_err_rate_threshold
1333              marginal_path_err_recheck_gap_time
1334              marginal_path_double_failed_time
1335              delay_watch_checks
1336              delay_wait_checks
1337              skip_kpartx
1338              max_sectors_kb
1339              ghost_delay
1340              all_tg_pt
1341

WWID generation

1343       Multipath  uses  a  World Wide Identification (WWID) to determine which
1344       paths belong to the same device. Each path presenting the same WWID  is
1345       assumed to point to the same device.
1346
1347       The WWID is generated by four methods (in the order of preference):
1348
1349       uid_attrs        The  WWID  is derived from udev attributes by matching
1350                        the device node name; cf uid_attrs above.
1351
1352       getuid_callout   Use the specified external program; cf  getuid_callout
1353                        above.   Care  should be taken when using this method;
1354                        the external program needs to be loaded from disk  for
1355                        execution,  which might lead to deadlock situations in
1356                        an all-paths-down scenario.
1357
1358       uid_attribute    Use the value of  the  specified  udev  attribute;  cf
1359                        uid_attribute  above.  This method is preferred to ge‐
1360                        tuid_callout as multipath does not need  to  call  any
1361                        external programs here. However, under certain circum‐
1362                        stances udev might not be able  to  generate  the  re‐
1363                        quested variable.
1364
1365       sysfs            Try  to determine the WWID from sysfs attributes.  For
1366                        SCSI devices, this means  reading  the  Vital  Product
1367                        Data (VPD) page "Device Identification" (0x83).
1368
1369       The  default settings (using udev and uid_attribute configured from the
1370       built-in hardware table) should work fine in most scenarios. Users  who
1371       want to enable uevent merging must set uid_attrs.
1372

Shaky paths detection

1374       A common problem in SAN setups is the occurence of intermittent errors:
1375       a path is unreachable, then reachable again for a  short  time,  disap‐
1376       pears again, and so forth. This happens typically on unstable intercon‐
1377       nects. It is undesirable to switch  pathgroups  unnecessarily  on  such
1378       frequent,  unreliable events. multipathd supports three different meth‐
1379       ods for detecting this situation and dealing with it. All methods share
1380       the  same  basic mode of operation: If a path is found to be "shaky" or
1381       "flipping", and appears to be in healthy status, it is  not  reinstated
1382       (put  back  to use) immediately. Instead, it is placed in the "delayed"
1383       state and watched for some time, and only  reinstated  if  the  healthy
1384       state  appears to be stable.  If the marginal_pathgroups option is set,
1385       the path will reinstated immediately, but placed in a special pathgroup
1386       for  marginal  paths.  Marginal  pathgroups  will not be used until all
1387       other pathgroups have been tried. At the time when the path would  nor‐
1388       mally  be  reinstated, it will be returned to its normal pathgroup. The
1389       logic of determining "shaky" condition, as well as the  logic  when  to
1390       reinstate, differs between the three methods.
1391
1392       "delay_checks" failure tracking
1393               This  method  is  deprecated  and  mapped to the "san_path_err"
1394               method.  See the delay_watch_checks and  delay_wait_checks  op‐
1395               tions above for more information.
1396
1397
1398       "marginal_path" failure tracking
1399               If  a second failure event (good->bad transition) occurs within
1400               marginal_path_double_failed_time seconds after a failure, high-
1401               frequency  monitoring  is started for the affected path: I/O is
1402               sent at a rate  of  10  per  second.  This  is  done  for  mar‐
1403               ginal_path_err_sample_time  seconds.  During  this  period, the
1404               path is not reinstated. If the rate  of  errors  remains  below
1405               marginal_path_err_rate_threshold  during the monitoring period,
1406               the path is reinstated. Otherwise, it is kept in  failed  state
1407               for  marginal_path_err_recheck_gap_time,  and after that, it is
1408               monitored again. For this method, time intervals  are  measured
1409               in seconds.
1410
1411       "san_path_err" failure tracking
1412               multipathd  counts path failures for each path. Once the number
1413               of failures exceeds the value given by  san_path_err_threshold,
1414               the  path is not reinstated for san_path_err_recovery_time sec‐
1415               onds. While counting failures, multipathd  "forgets"  one  past
1416               failure  every "san_path_err_forget_rate" ticks; thus if errors
1417               don't occur more often then once in the forget  rate  interval,
1418               the  failure  count doesn't increase and the threshold is never
1419               reached. Ticks are the time between path checks by  multipathd,
1420               which  is  variable  and controlled by the polling_interval and
1421               max_polling_interval parameters.
1422
1423               This method is deprecated in favor of the "marginal_path" fail‐
1424               ure  tracking method, and only offered for backward compatibil‐
1425               ity.
1426
1427       See the documentation of the individual options above for details.   It
1428       is  strongly  discouraged to use more than one of these methods for any
1429       given multipath map, because the two concurrent methods may interact in
1430       unpredictable  ways.  If  the  "marginal_path"  method  is  active, the
1431       "san_path_err" parameters are implicitly set to 0.
1432

FOREIGN MULTIPATH SUPPORT

1434       multipath and multipathd can load "foreign" libraries  to  add  support
1435       for  other  multipathing  technologies besides the Linux device mapper.
1436       Currently this support is  limited  to  printing  detected  information
1437       about  multipath  setup.  In topology output, the names of foreign maps
1438       are prefixed by the foreign library name in square brackets, as in this
1439       example:
1440
1441       # multipath -ll
1442       uuid.fedcba98-3579-4567-8765-123456789abc [nvme]:nvme4n9 NVMe,Some NVMe controller,FFFFFFFF
1443       size=167772160 features='n/a' hwhandler='ANA' wp=rw
1444       |-+- policy='n/a' prio=50 status=optimized
1445       | `- 4:38:1    nvme4c38n1 0:0     n/a   optimized    live
1446       `-+- policy='n/a' prio=50 status=optimized
1447         `- 4:39:1    nvme4c39n1 0:0     n/a   optimized    live
1448
1449       The  "nvme"  foreign  library  provides  support for NVMe native multi‐
1450       pathing in the kernel. It is part of the standard multipath package.
1451

KNOWN ISSUES

1453       The usage of queue_if_no_path option can lead to D state processes  be‐
1454       ing  hung and not killable in situations where all the paths to the LUN
1455       go offline. It is advisable to use the no_path_retry option instead.
1456
1457       The use of queue_if_no_path or no_path_retry might lead to  a  deadlock
1458       if the dev_loss_tmo setting results in a device being removed while I/O
1459       is still queued. The multipath daemon will update the dev_loss_tmo set‐
1460       ting accordingly to avoid this deadlock. Hence if both values are spec‐
1461       ified the  order  of  precedence  is  no_path_retry,  queue_if_no_path,
1462       dev_loss_tmo.
1463

SEE ALSO

1465       udev(8), dmsetup(8), multipath(8), multipathd(8).
1466

AUTHORS

1468       multipath-tools  was developed by Christophe Varoqui, <christophe.varo‐
1469       qui@opensvc.com> and others.
1470
1471
1472
1473Linux                             2018-05-21                 MULTIPATH.CONF(5)
Impressum