Provided by: multipath-tools_0.4.9-2ubuntu1_i386 bug

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
       recognized keywords for attributes or subsections depend on the section
       in which they occor.

       The following section keywords are recognized:

       defaults         This section defines  default  values  for  attributes
                        which are used whenever no specific setting is given.

       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  multipath  topologies.  They
                        are indexed by a World Wide Identifier(wwid), which is
                        the result of the getuid_callout program.

       devices          This section defines the device-specific settings.

defaults section

       The defaults section recognizes the following keywords:

       polling_interval interval  between  two  path  checks  in  seconds  For
                        properly   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

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

       selector         The default path selector algorithm to use;  they  are
                        offered  by  the  kernel  multipath  target.  The only
                        currently implemented is round-robin 0

       path_grouping_policy
                        The  default  path  grouping  policy   to   apply   to
                        unspecified 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.
                                    Priorities  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  /lib/udev/scsi_id
                        --whitelisted --device=/dev/%n

       prio_callout     The default program and args to callout  to  obtain  a
                        path  priority  value.  The  specified program will be
                        executed and should return a numeric value  specifying
                        the relative priority of this path. Higher number have
                        a higher priority. A '%n' in the command line will  be
                        expanded  to  the device name, a '%b' will be expanded
                        to the device number in major:minor format.  none is a
                        valid  value.  Currently  the  following path priority
                        programs are implemented:

                        mpath_prio_emc /dev/%n
                                    Generate the path priority for EMC arrays

                        mpath_prio_alua /dev/%n
                                    Generate the path priority  based  on  the
                                    SCSI-3 ALUA settings.

                        mpath_prio_netapp /dev/%n
                                    Generate  the  path  priority  for  NetApp
                                    arrays.

                        mpath_prio_rdac /dev/%n
                                    Generate the path priority for LSI/Engenio
                                    RDAC controller.

                        mpath_prio_hp_sw /dev/%n
                                    Generate  the  path priority for Compaq/HP
                                    controller in active/standby mode.

                        mpath_prio_hds_modular %b
                                    Generate the path priority for Hitachi HDS
                                    Modular storage arrays.

                        Default value is none.

       features         Specify  any  device-mapper  features  to be used. The
                        most common of these features  is  1  queue_if_no_path
                        Note  that  this can also be set via the no_path_retry
                        keyword.

       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/Engenio  RDAC
                                    storage controller.

                        directio    Read the first sector with direct I/O.

                        Default value is readsector0.

       failback         Tell  the daemon to manage path group failback, or not
                        to. 0 or immediate means immediate failback, values >0
                        means deferred failback (in seconds).  manual means no
                        failback. 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. Default is 1000

       rr_weight        If  set  to priorities the multipath configurator will
                        assign  path  weights  as  "path  prio  *  rr_min_io".
                        Possible values are priorities or uniform.  Default is
                        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/multipath/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 overridden by any specific
                        aliases in the multipaths section.  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.

       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.

       queue_without_daemon
                        If set to no , when multipathd stops, queueing will be
                        turned  off  for  all  devices.   This  is  useful for
                        devices that set no_path_retry.  If a machine is  shut
                        down  while  all  paths  to  a  device are down, it is
                        possible to hang waiting for IO  to  return  from  the
                        device  after  multipathd  has  been  stopped. Without
                        multipathd running, access  to  the  paths  cannot  be
                        restored,  and  the  kernel  cannot  be  told  to stop
                        queueing IO.  Setting  queue_without_daemon  to  no  ,
                        avoids this problem. Default is yes

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
       normally 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
       multipath 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
              no_path_retry
              rr_min_io

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

       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.

       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_callout
              failback
              rr_weight
              no_path_retry
              rr_min_io
              fast_io_fail_tmo
              dev_loss_tmo

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.varoqui@opensvc.com> and others.

                               30 November 2006              MULTIPATH.CONF(5)