<pre>
MULTIPATH.CONF(5)                                            MULTIPATH.CONF(5)


NAME
       multipath.conf - multipath daemon configuration file

DESCRIPTION
       multipath.conf  is  the configuration file for the multipath daemon. It
       is used to overwrite the built-in configuration  table  of  multipathd.
       Any line whose first non-white-space character is a ’#’ is considered a
       comment line. Empty lines are ignored.

SYNTAX
       The configuration file contains entries of the form:

              <section> {
                     <attribute> <value>
                     ...
                     <subsection> {
                             <attribute> <value>
                             ...
                     }
              }

       Each section contains one or more attributes or subsections. The recog-
       nized  keywords  for attributes or subsections depend on the section in
       which they occor.

       The following section keywords are recognized:

       defaults         This section defines default settings for devices-map-
                        per-multipath.  These values can be overwritten by the
                        devices and multipaths sections.

       blacklist        This section defines which devices should be  excluded
                        from the multipath topology discovery.

       blacklist_exceptions
                        This  section defines which devices should be included
                        in the multipath  topology  discovery,  despite  being
                        listed in the blacklist section.

       multipaths       This  section defines the settings for individual mul-
                        tipath devices.  These values overwrite what is speci-
                        fied  in  the defaults and devices section of the con-
                        figuration file.  The devices are  identified  by  the
                        wwid  keyword, which is a regular expression that must
                        match the result of the getuid_callout program.

       devices          This section defines the settings for individual stor-
                        age  controller  types.  These value overwrite what is
                        specified in the defaults section of the configuration
                        file.   These  controller  types are identified by the
                        vendor, product, and revision keywords, which are reg-
                        ular expressions that must match the sysfs information
                        about this device.  If you are using a  storage  array
                        that is not supported by default, you may need to cre-
                        ate a devices subsection for your array.

       The priority of configuration in multipath.conf is:
       multipaths is greater than devices is greater that defaults


defaults section
       The defaults section recognizes the following keywords:

       polling_interval interval between two path checks in seconds For  prop-
                        erly  functioning  paths,  the interval between checks
                        will gradually increase  to  (4  *  polling_interval);
                        default is 5

       udev_dir         directory where udev creates its device nodes; default
                        is /dev

       multipath_dir    directory where the dynamic shared objects are stored;
                        default is system dependent, commonly /lib/multipath

       find_multipaths  If  set  to yes , instead of trying to create a multi-
                        path device for every non-blacklisted path,  multipath
                        will  only  create a device if one of three condidions
                        are met.  1 There are  at  least  two  non-blacklisted
                        paths  with  the same wwid, 2 the user manually forces
                        the creation, by specifying a device with  the  multi-
                        path  command, or 3 a path has the same WWID as a mul-
                        tipath  device  that  was  previously  created   while
                        find_multipaths was set (even if that multipath device
                        doesn’t currently exist).  Whenever a multipath device
                        is  created  with  find_multipaths set, multipath will
                        remeber the WWID of the device, so that it will  auto-
                        matically  create the device again, as soon as it sees
                        a path with that WWID. This should allow most users to
                        have  multipath automatically choose the correct paths
                        to make into multipath devices, without having to edit
                        the blacklist; Default is no

       verbosity        default  verbosity.  Higher  values  increase the ver-
                        bosity level.  Valid  levels  are  between  0  and  6;
                        default is 2

       path_selector    The  default  path selector algorithm to use; they are
                        offered by the  kernel  multipath  target.  There  are
                        three selector algorithms.

                        round-robin 0
                                    Loop through every path in the path group,
                                    sending the same amount of IO to each.

                        queue-length 0
                                    Send the next bunch of IO  down  the  path
                                    with the least amount of outstanding IO.

                        service-time 0
                                    Choose  the  path for the next bunch of IO
                                    based on the amount of outstanding  IO  to
                                    the path and its relative throughput.

       path_grouping_policy
                        The  default path grouping policy to apply to unspeci-
                        fied multipaths. Possible values are

                        failover    1 path per priority group

                        multibus    all paths in 1 priority group

                        group_by_serial
                                    1 priority group per serial number

                        group_by_prio
                                    1 priority group per priority value.  Pri-
                                    orities are determined by callout programs
                                    specified as a global,  per-controller  or
                                    per-multipath  option in the configuration
                                    file.

                        group_by_node_name
                                    1 priority group  per  target  node  name.
                                    Target   node   names   are   fetched   in
                                    /sys/class/fc_transport/target*/node_name.

                        Default value is multibus.

       getuid_callout   The  default  program  and args to callout to obtain a
                        unique path identifier. Should be  specified  with  an
                        absolute path. Default value is /sbin/scsi_id -g -u -s

       prio             The default method used  to  obtain  a  path  priority
                        value. Possible values are

                        const       Set a priority of one to all paths

                        emc         Generate the path priority for EMC arrays

                        alua        Generate  the  path  priority based on the
                                    SCSI-3 ALUA settings.

                        tpg_pref    Generate the path  prority  based  on  the
                                    SCSI-3  ALUA settings, using the preferred
                                    port bit.

                        ontap       Generate  the  path  priority  for  NetApp
                                    arrays.

                        rdac        Generate  the  path priority for LSI/Enge-
                                    nio/NetApp E-Series RDAC controller.

                        hp_sw       Generate the path priority  for  Compaq/HP
                                    controller in active/standby mode.

                        hds         Generate the path priority for Hitachi HDS
                                    Modular storage arrays.

                        Default value is const.

       features         Specify any device-mapper features to be used.  Syntax
                        is  num  list  where  num is the number of features in
                        list.  Possible values for the feature list are

                        queue_if_no_path
                                    Queue IO if no path is  active;  identical
                                    to the no_path_retry keyword.

                        no_partitions
                                    Disable  automatic  partitions  generation
                                    via kpartx.

       path_checker     The default method used to determine the paths’ state.
                        Possible values are

                        readsector0 Read the first sector of the device

                        tur         Issue  a  TEST  UNIT  READY command to the
                                    device.

                        emc_clariion
                                    Query the EMC Clariion specific EVPD  page
                                    0xC0 to determine the path state.

                        hp_sw       Check the path state for HP storage arrays
                                    with Active/Standby firmware.

                        rdac        Check  the  path   state   for   LSI/Enge-
                                    nio/NetApp   E-Series  RDAC  storage  con-
                                    troller.

                        directio    Read the first sector with direct I/O.

                        Default value is readsector0.

       failback         Tell multipathd how to manage path group failback.

                        immediate   Immediately failback to the highest prior-
                                    ity  pathgroup that contains active paths.

                        manual      Do not perform automatic failback.

                        followover  Only perform automatic failback  when  the
                                    first  path of a pathgroup becomes active.
                                    This keeps a node from automatically fail-
                                    ing  back  when another node requested the
                                    failover.

                        values > 0  deferred failback (time to defer  in  sec-
                                    onds)

                        Default value is manual.

       rr_min_io        The  number  of IO to route to a path before switching
                        to the next in the same path  group,  using  bio-based
                        device-mapper-multipath. This is only for systems run-
                        ning kernels older that 2.6.31. Newer  systems  should
                        use rr_min_io_rq. Default is 1000

       rr_min_io_rq     The  number  of IO to route to a path before switching
                        to the next in the same  path  group,  using  request-
                        based device-mapper-multipath.  This setting should be
                        used on systems running current kernels.   On  systems
                        running  kernels  older  than  2.6.31,  use rr_min_io.
                        Default is 1

       rr_weight        If set to priorities the multipath  configurator  will
                        assign path weights as "path prio * rr_min_io". Possi-
                        ble values are priorities or uniform uniform

       no_path_retry    Specify the number of retries until disable  queueing,
                        or fail for immediate failure (no queueing), queue for
                        never stop queueing. Default is 0.

       user_friendly_names
                        If set to yes , using the  bindings  file  /etc/multi-
                        path/bindings  to assign a persistent and unique alias
                        to the multipath, in the form of mpath<n>.  If set  to
                        no  use  the WWID as the alias. In either case this be
                        will be overriden by any specific aliases in the  mul-
                        tipaths section.  Default is no

       queue_without_daemon
                        If  set  to  no , multipathd will disable queueing for
                        all devices when it is shut down.  Default is yes

       flush_on_last_del
                        If set to yes , multipathd will disable queueing  when
                        the last path to a device has been deleted. Default is
                        no

       max_fds          Specify the maximum number of  file  descriptors  that
                        can  be  opened  by multipath and multipathd.  This is
                        equivalent to ulimit -n. A value of max will set  this
                        to the system limit from /proc/sys/fs/nr_open. If this
                        is not set, the maximum number of open  fds  is  taken
                        from  the  calling  process. It is usually 1024. To be
                        safe, this should be set  to  the  maximum  number  of
                        paths plus 32, if that number is greated than 1024.

       checker_timeout  Specify  the  timeout  to  user for path checkers that
                        issue scsi commands with an explict timeout,  in  sec-
                        onds; default taken from /sys/block/sd<x>/device/time-
                        out

       fast_io_fail_tmo Specify the number of seconds the scsi layer will wait
                        after  a problem has been detected on a FC remote port
                        before failing IO to  devices  on  that  remote  port.
                        This should be smaller than dev_loss_tmo. Setting this
                        to off will disable the timeout.

       dev_loss_tmo     Specify the number of seconds the scsi layer will wait
                        after  a problem has been detected on a FC remote port
                        before removing it from the system. This can be set to
                        "infinity"   which   sets  it  to  the  max  value  of
                        2147483647 seconds, or 68 years.

       log_checker_err  If set to  once  ,  multipathd  logs  the  first  path
                        checker error at logging level 2. Any later errors are
                        logged at level 3 until the device is restored. If set
                        to  always  ,  multipathd always logs the path checker
                        error at logging level 2. Default is always

       hwtable_regex_match
                        If set to yes , user device configs  will  be  regular
                        expression  matched  against  the  builtin  configs to
                        determine if they should modify an existing config  or
                        create  a new one.  If set to no , user device configs
                        will be string matched against the builtin configs  to
                        determine  if they should modify an existing config or
                        create a new one. Default is no

       reservation_key  This is the service action  reservation  key  used  by
                        mpathpersist.   It  must  be  set  for  all  multipath
                        devices using persistent reservations, and it must  be
                        the  same  as the RESERVATION KEY field of the PERSIS-
                        TENT RESERVE OUT  parameter  list  which  contains  an
                        8-byte value provided by the application client to the
                        device server to identify the I_T nexus. It  is  unset
                        by default.

       detect_prio      If  set  to  yes , multipath will try to detect if the
                        device supports ALUA. If so, the device will automati-
                        cally  use  the  alua prioritizer. If not, the priori-
                        tizer will be selected as usual. Default is no

       reload_readwrite If set to yes , multipathd will monitor change  events
                        on  path devices.  When it receives a change event for
                        a path of a readonly multipath device, it  will  check
                        if the path is now read/write.  If so, multipathd will
                        reload  the  multipath  device   to   switch   it   to
                        read/write. Default is no

blacklist section
       The blacklist section is used to exclude specific device from inclusion
       in the multipath topology. It is most commonly used  to  exclude  local
       disks or LUNs for the array controller.

       The following keywords are recognized:

       wwid             The World Wide Identification of a device.

       devnode          Regular expression of the device nodes to be excluded.

       device           Subsection for the device description. This subsection
                        recognizes the vendor and product keywords. For a full
                        description of these keywords please see  the  devices
                        section description.

blacklist_exceptions section
       The  blacklist_exceptions  section is used to revert the actions of the
       blacklist section, ie to  include  specific  device  in  the  multipath
       topology.  This  allows to selectively include devices which would nor-
       mally be excluded via the blacklist section.

       The following keywords are recognized:

       wwid             The World Wide Identification of a device.

       devnode          Regular expression of the device nodes to be excluded.

       device           Subsection for the device description. This subsection
                        recognizes the vendor and product keywords. For a full
                        description  of  these keywords please see the devices
                        section description.

multipaths section
       The only recognized attribute for the multipaths section is the  multi-
       path subsection.

       The multipath subsection recognizes the following attributes:

       wwid             Index of the container. Mandatory for this subsection.

       alias            (Optional) symbolic name for the multipath map.

       The following attributes are optional; if not set  the  default  values
       are taken from the defaults section:

              path_grouping_policy
              path_selector
              failback
              prio
              no_path_retry
              rr_min_io
              rr_min_io_rq
              rr_weight
              flush_on_last_del
              reservation_key


devices section
       The  only  recognized  attribute  for the devices section is the device
       subsection.

       The device subsection recognizes the following attributes:

       vendor           (Mandatory) Vendor identifier

       product          (Mandatory) Product identifier

       revision         Revision identifier

       product_blacklist
                        Product strings to blacklist for this vendor

       hardware_handler (Optional) The hardware handler to use for this device
                        type.  The following hardware handler are implemented:

                        1 emc       Hardware handler for EMC storage arrays.

                        1 alua      Hardware handler for SCSI-3 ALUA arrays.

                        1 hp_sw     Hardware  handler   for   Compaq/HP   con-
                                    trollers.

                        1 rdac      Hardware   handler   for   the   LSI/Enge-
                                    nio/NetApp  E-Series  RDAC  storage   con-
                                    troller.

       The  following  attributes  are optional; if not set the default values
       are taken from the defaults section:

              path_grouping_policy
              getuid_callout
              path_selector
              path_checker
              features
              prio
              failback
              rr_weight
              no_path_retry
              rr_min_io
              rr_min_io_rq
              fast_io_fail_tmo
              dev_loss_tmo
              flush_on_last_del
              detect_prio


KNOWN ISSUES
       The usage of queue_if_no_path option can  lead  to  D  state  processes
       being  hung  and  not killable in situations where all the paths to the
       LUN go offline.  It  is  advisable  to  use  the  no_path_retry  option
       instead.

SEE ALSO
       udev(8), dmsetup(8) multipath(8) multipathd(8)

AUTHORS
       multipath   was  developed  by  Christophe  Varoqui,  <christophe.varo-
       qui@free.fr> and others.


                               30 November 2006              MULTIPATH.CONF(5)
</pre>