A.1.7. The multipath Mapping Target

A.1.7. The multipath Mapping Target

The multipath mapping target supports the mapping of a multipathed device. The format of a multipath target is as follows:

start length multipath #features [feature1 ... featureN] #handlerargs [handlerarg1 ... handlerargN] #pathgroups pathgroup pathgroupargs1 ... pathgroupargsN

There is one set of pathgroupargs parameters for each path group.

start

starting block in virtual device

length

length of this segment

#features

The number of multipath features, followed by those features. If this parameter is zero, then there is no feature parameter and the next device mapping parameter is #handlerargs. Currently there is one supported multipath feature, queue_if_no_path. This indicates that this multipathed device is currently set to queue I/O operations if there is no path available.

For example, if the no_path_retry option in the multipath.conf file has been set to queue I/O operations only until all paths have been marked as failed after a set number of attempts have been made to use the paths, the mapping would appear as follows until all the path checkers have failed the specified number of checks.

0 71014400 multipath 1 queue_if_no_path 0 2 1 round-robin 0 2 1 66:128 \
1000 65:64 1000 round-robin 0 2 1 8:0 1000 67:192 1000

After all the path checkers have failed the specified number of checks, the mapping would appear as follows.

0 71014400 multipath 0 0 2 1 round-robin 0 2 1 66:128 1000 65:64 1000 \
round-robin 0 2 1 8:0 1000 67:192 1000
#handlerargs

The number of hardware handler arguments, followed by those arguments. A hardware handler specifies a module that will be used to perform hardware-specific actions when switching path groups or handling I/O errors. If this is set to 0, then the next parameter is #pathgroups.

#pathgroups

The number of path groups. A path group is the set of paths over which a multipathed device will load balance. There is one set of pathgroupargs parameters for each path group.

pathgroup

The next path group to try.

pathgroupsargs

Each path group consists of the following arguments:

pathselector #selectorargs #paths #pathargs device1 ioreqs1 ... deviceN ioreqsN 

There is one set of path arguments for each path in the path group.

pathselector

Specifies the algorithm in use to determine what path in this path group to use for the next I/O operation.

#selectorargs

The number of path selector arguments which follow this argument in the multipath mapping. Currently, the value of this argument is always 0.

#paths

The number of paths in this path group.

#pathargs

The number of path arguments specified for each path in this group. Currently this number is always 1, the ioreqs argument.

device

The block device number of the path, referenced by the major and minor numbers in the format major:minor

ioreqs

The number of I/O requests to route to this path before switching to the next path in the current group.

The following illustration shows the format of a multipath target with two path groups.

                             [----------- 1st path group -----------] [--------- 2nd path group -----------]
0 71014400 multipath 0 0 2 1 round-robin 0 2 1 66:128 1000 65:64 1000 round-robin 0 2 1 8:0 1000 67:192 1000
^     ^       ^      ^ ^ ^ ^      ^      ^ ^ ^   ^      ^
|     |       |      | | | |      |      | | |   |      # of I/O requests to send to this path before switching
|     |       |      | | | |      |      | | |   path major:minor numbers 
|     |       |      | | | |      |      | | # of path arguments (always 1)
|     |       |      | | | |      |      | # of paths in this path group
|     |       |      | | | |      |      # of selector arguments (always 0)
|     |       |      | | | |      path selector
|     |       |      | | | next path group to try
|     |       |      | | # of path groups
|     |       |      | # of hwhandler arguments
|     |       |      # of features
|     |       target name
|     target length in 512-bytes blocks
starting offset of the target

The following example shows a pure failover target definition for the same multipath device. In this target there are four path groups, with only one open path per path group so that the multipathed device will use only one path at a time.

0 71014400 multipath 0 0 4 1 round-robin 0 1 1 66:112 1000 \
round-robin 0 1 1 67:176 1000 round-robin 0 1 1 68:240 1000 \
round-robin 0 1 1 65:48 1000

The following example shows a full spread (multibus) target definition for the same multipathed device. In this target there is only one path group, which includes all of the paths. In this setup, multipath spreads the load evenly out to all of the paths.

0 71014400 multipath 0 0 1 1 round-robin 0 4 1 66:112 1000 \
 67:176 1000 68:240 1000 65:48 1000

For further information about multipathing, see the Using Device Mapper Multipath document.


Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.