多路径配置文件 multipath.conf（译）

名字

multipath.conf - 多路径守护程序配置文件

版本

multipath-tools v0.9.6 (07/05, 2023)

描述

/etc/multipath.conf 是多路径守护程序的配置文件。它用于覆盖multipathd的内置配置表。 任何第一个非空白字符为“#”的行都被视为注释行。 空行将被忽略。

当前使用的 multipathd 配置可以使用 multipath -t 或 multipathd show config 命令显示。

语法

配置文件包含以下形式的条目：

<章节> {
    <配置项> <值>
    ...
    <章节> {
        <配置项> <值>
        ...
    }
}

每个部分包含一个或多个属性或小节。 属性或小节的可识别关键字取决于它们出现的部分。

<配置项> 和 <值> 必须位于同一行。 <配置项> 是本手册页中列出的关键字之一。 <值> 可以是一个简单的单词（不包含空格，也不包含字符 ‘“‘、’#’ 和 ‘!’），也可以是用双引号 (“…”) 括起来的一个字符串。在带引号的字符串之外， 以“#”和“!”开头的文本 被视为注释并被忽略直到行尾。在带引号的字符串内，’#’ 和 ‘!’ 是普通字符，并且保留空格。要在双引号字符串中表示双引号字符，请使用两个连续的双引号 (‘“”‘)。因此 ‘2.5” SSD’ 可以写为 “2.5” “ SSD”。

左大括号 (‘{‘) 必须跟在同一行的（子）节名称之后。 标记（子）节结束的右大括号 (‘}’) 必须是该行中唯一的非空白字符。 除了双引号内的空格之外，空格都会被忽略，因此上面示例中显示的缩进对人类读者有帮助，但不是强制性的。

正则表达式注意事项：multipath.conf 语法允许将许多属性值指定为 POSIX 扩展正则表达式（请参阅 regex(7)）。 这些正则表达式区分大小写且不锚定，因此表达式“bar”匹配“barbie”、“rhabarber”和“wunderbar”，但不匹配“Barbie”。 为了避免不需要的子字符串匹配，可以使用使用特殊字符“^”和“$”的标准正则表达式语法。

可以识别以下章节关键字：

• defaults 本节定义了属性的默认值，只要在适当的设备或多路径部分中没有给出值，就会使用这些默认值。

• blacklist 本节定义应从多路径拓扑发现中排除哪些设备。

• blacklist_exceptions 本部分定义哪些设备应包含在多路径拓扑发现中，尽管已列在黑名单部分中。

• multipaths 本节定义多路径拓扑。 它们通过全球标识符 (WWID) 进行索引。 有关 WWID 生成的详细信息，请参阅下面的 WWID 生成部分。 本节中设置的属性优先于所有其他属性。

• devices 本节定义设备特定的设置。 设备按供应商、产品和版本进行标识。

• overrides 本节定义应覆盖所有设备的设备特定设置的属性值。

defaults

defaults 部分可识别以下关键字：

• verbosity 默认详细程度。 值越高，详细程度越高。 有效级别在 0 到 6 之间。

  默认值：2

• polling_interval 两次路径检查之间的时间间隔（以秒为单位）。 对于正常运行的路径，检查之间的间隔将逐渐增加到 max_polling_interval。如果使用 systemd，则该值将被 multipathd.service 定义中的 WatchdogSec 设置覆盖。

  默认值：5

• max_polling_interval 两次路径检查之间的最大间隔（以秒为单位）。

  默认值：4 * polling_interval

• reassign_maps 启用设备映射器映射的重新分配。 使用此选项，multipathd 将重新映射现有的设备映射器映射，以始终指向多路径设备，而不是底层块设备。 可能的值为 yes 和 no。

  默认值：依赖于特定的系统

• multipath_dir 存储动态共享对象的目录。 在编译时定义，通常为/lib64/multipath/或/lib/multipath/。

• path_selector 使用的默认路径选择器算法； 它们由内核多路径目标（target）提供。 选择器算法共有三种：

  • round-robin 0 循环路径组中的每个路径，向每个路径发送相同数量的 I/O。 行为的某些方面可以通过以下属性进行控制：rr_min_io、rr_min_io_rq 和 rr_weight。
  • queue-length 0 （自 2.6.31 内核起）根据路径上未完成的 I/O 数量选择下一批 I/O 的路径。
  • service-time 0 （自 2.6.31 内核起）根据路径的未完成 I/O 量及其相对吞吐量选择下一组 I/O 的路径。

  默认值：service-time 0

• path_grouping_policy 应用于未指定多路径的默认路径分组策略。 可能的值为：

  • failover 每个优先级组一条路径。
  • multibus 一个优先级组中的所有路径。
  • group_by_serial 每个序列号一个优先级组。
  • group_by_prio 每个优先级值一个优先级组。 优先级由配置文件中指定为全局、每个控制器或每个多路径选项的标注程序确定。
  • group_by_node_name 每个目标节点名称一个优先级组。 目标节点名称在 /sys/class/fc_transport/target*/node_name 中获取。

  默认值：failover

• uid_attrs 设置此选项会激活按 WWID 合并 uevent，这可能会提高 uevent 处理效率。 此外，它是配置 udev 属性以用于确定唯一路径标识符 (WWID) 的替代方法。

  该选项的值是一个空格分隔的记录列表，如“type:ATTR”，其中 type 与设备节点名称的开头匹配（例如 sd:ATTR 与 sda 匹配），ATTR 是 udev 属性的名称 用于匹配设备。

  如果此选项已配置并且与设备的设备节点名称匹配，它将覆盖用于确定此设备的 WWID 的任何其他已配置方法。

  默认值为：<未设置>。 要启用 uevent 合并，请将其设置为 到“sd：ID_SERIAL dasd：ID_UID nvme：ID_WWN”。

• uid_attribute udev 属性提供唯一的路径标识符 (WWID)。 如果 uid_attribute 设置为空字符串，则使用 sysfs 方法而不是使用 udev 来确定 WWID（在生产中不推荐；请参阅下面的 WWID 生成）。

  默认值为：ID_SERIAL，适用于 SCSI 设备。

  默认值为：ID_UID，适用于 DASD 设备。

  默认为：ID_WWN，适用于 NVMe 设备。

• getuid_callout （由 uid_attribute 取代）用于标注的默认程序和参数，以获取唯一路径标识符。 应使用绝对路径指定。

  默认值：未设置。

• prio 路径优先级例程的名称。指定的例程应该返回一个数值，指定该路径的相对优先级。数字越高，优先级越高。“none”是一个有效值。目前实现了以下路径优先级例程：

  • const 返回常量优先级 1。
  • sysfs 使用 sysfs 属性 access_state 和 Preferred_path 生成路径优先级。 该优先级排序器接受可选的 prio_arg exclusive_pref_bit。
  • emc （取决于硬件）为 CLARiiON CX/AX 和 EMC VNX 以及 Unity 系列等 DGC 类阵列生成路径优先级。
  • alua （取决于硬件）根据 SCSI-3 ALUA 设置生成路径优先级。 该优先级排序器接受可选的 prio_arg Exclusive_pref_bit。
  • ontap （取决于硬件）生成 NetApp ONTAP 类和 OEM 阵列作为 IBM NSeries 的路径优先级。
  • rdac （取决于硬件）为 LSI/Engenio/NetApp RDAC 类（如 NetApp SANtricity E/EF 系列）以及来自 IBM DELL SGI STK 和 SUN 的 OEM 阵列生成路径优先级。
  • hp_sw （取决于硬件）专门为具有活动/备用模式的 HP/COMPAQ/DEC HSG80 和 MSA/HSV 阵列生成路径优先级。
  • hds （取决于硬件）为除 AMS 2000 之外的 Hitachi AMS 系列阵列生成路径优先级。
  • random 生成 1 到 10 之间的随机优先级。
  • weightedpath 根据正则表达式和作为参数提供的优先级生成路径优先级。 需要 prio_args 关键字。
  • path_latency 基于延迟算法生成路径优先级。 需要 prio_args 关键字。
  • ana （取决于硬件）根据 NVMe ANA 设置生成路径优先级。
  • datacore （取决于硬件）为某些 DataCore 存储阵列生成路径优先级。 需要 prio_args 关键字。
  • iet （仅限 iSCSI）根据 IP 地址生成 iSCSI 目标的路径优先级。 需要 prio_args 关键字。

  默认值取决于 detector_prio 设置：如果 detector_prio 为 yes（默认），则默认优先级算法为 sysfs（NetAPP E 系列除外，该算法为 alua）。 如果 detector_prio 为 no，则默认优先级算法为 const。

• prio_args 要传递给 prio 函数的参数。 这仅适用于某些优先级器：

  • weighted 需要“<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> …”形式的值。

    • hbtl 正则表达式可以是 SCSI H:B:T:L 格式。 例如：1:0:.:. ，*：0：0：。
    • devname 正则表达式可以是设备名称格式。 例如： sda 、 sd.e。
    • serial 正则表达式可以是序列号格式。 例如： .*J1FR.*324 。 可以通过 sysfs 或运行 multipathd show paths format “%z” 来查找序列号。 例如：0395J1FR904324。
    • wwn 正则表达式的形式可以是“host_wwnn:host_wwpn:target_wwnn:target_wwpn”，这些值可以通过 sysfs 或运行 multipathd show paths 格式“%N:%R:%n:%r”来查找。 例如： 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*。

  • path_latency 需要“io_num=<20> base_num=<10>”形式的值。

    • io_num 连续发送到当前路径的读IO数量，用于计算平均路径延迟。 有效值：整数，[2, 200]。

    • base_num 对数刻度的基数值，用于划分不同的优先级。 有效值：整数，[2, 10]。 最大平均延迟值为 100s，最小平均延迟值为 1us。 例如：如果base_num=10，路径将被分组为路径延迟 <=1us、(1us, 10us]、(10us, 100us]、(100us, 1ms]、(1ms, 10ms]、(10ms, 100ms]、（100ms、1s]、（1s、10s]、（10s、100s]、>100s。

    • alua 如果设置了 exclusive_pref_bit，则设置了首选路径位的路径将始终位于其自己的路径组中。

    • sysfs 如果设置了 exclusive_pref_bit，则设置了首选路径位的路径将始终位于其自己的路径组中。

    • datacore

      • preferredsds （强制）首选的“SDS 名称”。
      • timeout （可选）查询的超时时间，以毫秒为单位。

    • iet

      • preferredip=… （强制）iSCSI 目标的首选 IP 地址（采用点分十进制表示法）。

    默认值： 未设置

• features 指定要使用的任何设备映射器功能。 语法为 num list，其中 num 是列表中功能的数量（介于 0 到 8 之间）。 功能列表的可能值为：

  • queue_if_no_path （已弃用，由 no_path_retry 取代）如果没有活动路径，则对 I/O 进行队列。 与队列值的 no_path_retry 相同。 如果同时设置了此功能和 no_path_retry，则后一个值优先。 请参阅已知问题。

  • pg_init_retries <times> (自内核2.6.24起) 重试pg_init的次数，必须在1到50之间。

  • pg_init_delay_msecs (自内核 2.6.38 起) pg_init 重试之前的毫秒数，必须在 0 到 60000 之间。

  • queue_mode <mode> （自内核 4.8 起）选择每个多路径设备的排队模式。 <mode>可以是bio、rq或mq，分别对应基于bio、基于请求和基于块多队列（blk-mq）请求。 默认值取决于内核参数 dm_mod.use_blk_mq。 如果设置了后者则为 mq，否则为 rq。

    默认值：未设置

• path_checker 用于确定路径状态的默认方法。 可能的值为：

  • readsector0 （已弃用）读取设备的第一个扇区。 此检查器已被弃用，请使用 tur 代替。

  • tur 向设备发出 TEST UNIT READY 命令。

  • emc_clariion （取决于硬件）查询 DGC/EMC 特定 EVPD 页 0xC0 以确定 CLARiiON CX/AX 以及 EMC VNX 和 Unity 阵列系列的路径状态。

  • hp_sw （取决于硬件）仅在活动/备用模式下检查 HP/COMPAQ/DEC HSG80 和 MSA/HSV 阵列的路径状态。

  • rdac （取决于硬件）检查 LSI/Engenio/NetApp RDAC 类（如 NetApp SANtricity E/EF 系列）以及来自 IBM DELL SGI STK 和 SUN 的 OEM 阵列的路径状态。

  • directio （已弃用）使用直接 I/O 读取第一个扇区。 此检查器已被弃用，它可能会在高负载下导致虚假路径故障。 请使用 tur 代替。

  • cciss_tur （取决于硬件）检查 HP/COMPAQ 智能阵列 (CCISS) 控制器的路径状态。

  • none 不检查设备，回退使用从 sysfs 检索的值。

    默认值：tur

• alias_prefix user_friend_names 前缀。

  默认值：mpath

• failback 告诉 multipathd 如何管理路径组故障恢复。 要选择立即数或值，设备必须支持工作优先级排序器。

  • immediate 立即故障回复到包含活动路径的最高优先级路径组。
  • manual 不执行自动故障恢复。
  • followover 用于处理多台计算机访问相同的主动/被动存储设备。 仅当路径组的第一条路径变为活动状态时才执行自动故障恢复。 当另一个节点请求故障转移时，这可以防止集群节点自动故障恢复。
  • value > 0 延迟故障回复（延迟时间以秒为单位）。

  默认值：manual

• rr_min_io 在切换到同一路径组中的下一个路径之前路由到路径的 I/O 请求数。 这仅适用于基于块 I/O(BIO) 的多路径，并且仅适用于循环路径选择器。

  默认值：1000

• rr_min_io_rq 在切换到同一路径组中的下一个路径之前路由到路径的 I/O 请求数。 这仅适用于基于请求的多路径，并且仅适用于循环路径选择器。

  默认值：1

• max_fds 指定 multipath 和 multipathd 可以打开的文件描述符的最大数量。 这相当于 ulimit -n。 max 值会将其设置为 /proc/sys/fs/nr_open 的系统限制。 如果未设置，则从调用进程中获取打开的 fd 的最大数量。 通常为 1024。为了安全起见，如果该数字大于 1024，则应将其设置为最大路径数加 32。

  默认值：max

• rr_weight 如果设置为优先级，多路径配置器会将路径权重分配为“path prio * rr_min_io”。 可能的值是priority 或uniform。 仅适用于循环路径选择器。

  默认值：uniform

• no_path_retry 指定当所有路径均已关闭时要执行的操作。 可能的值为：

  • value > 0 禁用 I/O 队列之前的重试次数。
  • fail 立即失败（无 I/O 排队）。
  • queue 用于永不停止 I/O 队列，类似于queue_if_no_path。 请参阅已知问题。

  默认值：fail

• queue_without_daemon 如果设置为 no ，当 multipathd 停止时，所有设备的排队将被关闭。 这对于设置 no_path_retry 的设备很有用。 如果在设备的所有路径都关闭时关闭计算机，则可能会在 multipathd 停止后挂起，等待 I/O 从设备返回。 如果不运行 multipathd，则无法恢复对路径的访问，并且无法告知内核停止排队 I/O。 将queue_without_daemon设置为no可以避免这个问题。

  默认值：no

• checker_timeout 指定用于发出具有显式超时的 SCSI 命令的路径检查器和优先级排序器的超时（以秒为单位）。

  默认值：在/sys/block/sd<x>/device/timeout

• flush_on_last_del 如果设置为 yes ，当设备的最后一个路径被删除时，multipathd 将禁用排队。

  默认值：no

• user_friendly_names 如果设置为 yes ，则使用绑定文件 /etc/multipath/bindings 为多路径分配持久且唯一的别名，格式为 mpath<n>。 如果设置为 no，则使用 WWID 作为别名。 无论哪种情况，这都将被多路径部分中的任何特定别名覆盖。

  默认值：no

• fast_io_fail_tmo 指定在 FC 远程端口上检测到问题后，SCSI 层在对该远程端口上的设备进行 I/O 失败之前将等待的秒数。 这应该小于 dev_loss_tmo。 将其设置为关闭将禁用超时。

  默认值：5

• dev_loss_tmo 指定在 FC 远程端口上检测到问题后将其从系统中删除之前 SCSI 层将等待的秒数。 可以将其设置为“无穷大”，将其设置为最大值 2147483647 秒，即 68 年。 如果通过 no_path_retry 给出重试次数并且总体重试间隔长于指定的 dev_loss_tmo 值，则会自动调整为总体重试间隔 no_path_retry * polling_interval。 如果未设置 fast_io_fail_tmo，Linux 内核会将此值限制为 600。 请参阅已知问题。

  默认值：600

• bindings_file 设置 user_Friendly_names 选项时要使用的绑定文件的完整路径名。

  默认值：/etc/multipath/bindings

• wwids_file WWID 文件的完整路径名，多路径使用该文件来跟踪它过去在其上创建的多路径设备的 LUN 的 WWID。

  默认值：/etc/multipath/wwids

• prkeys_file prkeys 文件的完整路径名，当reservation_key 设置为file 时，multipathd 使用该文件来跟踪用于特定WWID 的持久保留密钥。

  默认值：/etc/multipath/prkeys

• log_checker_err 如果设置为 Once ，multipathd 将在日志记录级别 2 记录第一个路径检查器错误。任何后续错误都将在级别 3 记录，直到设备恢复为止。 如果设置为 always ，multipathd 始终以日志记录级别 2 记录路径检查器错误。

  默认值：always

• reservation_key 这是 mpathpersist 使用的服务操作保留密钥。 必须为所有使用持久保留的多路径设备设置它，并且它必须与 PERSISTENT RESERVE OUT 参数列表的 RESERVATION KEY 字段相同，该字段包含应用程序客户端向设备服务器提供的 8 字节值，用于标识 I_T 关系。 如果在使用 mpathpersist 注册密钥时使用 –param-aptpl 选项，则必须将 :aptpl 附加到保留密钥的末尾。

• all_tg_pt 使用 mpathpersist 注册密钥时设置“所有目标端口”标志。 某些阵列会自动设置和清除主机所有目标端口上的注册密钥，而不是每个主机的每个目标端口。 必须设置 ALL_TG_PT 标志才能在这些阵列上成功使用 mpathpersist。 设置此选项与使用 –param-alltgpt 调用 mpathpersist 相同。

  默认值：no

• retain_attached_hw_handler （对于 >= 4.3 的内核已过时）如果设置为 yes 并且 SCSI 层已将 hardware_handler 附加到设备，则多路径不会强制设备使用 mutipath.conf 指定的 hardware_handler。 如果 SCSI 层未附加硬件处理程序，多路径将继续使用其配置的硬件处理程序。

  默认值：no

• detect_prio 如果设置为 yes ，多路径将尝试检测设备是否支持 SCSI-3 ALUA。 如果是这样，如果支持所需的 sysf 属性 access_state 和 Preferred_path，设备将自动使用 sysfs 优先级排序器，如果不支持，则设备将自动使用 alua 优先级排序器。 如果设置为 no ，将照常选择优先级。

  默认值：yes

• detect_checker 如果设置为 yes ，multipath将尝试检测设备是否支持 SCSI-3 ALUA。 如果是这样，设备将自动使用 tur 检查器。 如果设置为 no ，将照常选择检查器。

  默认值：yes

• force_sync 如果设置为 yes ，multipathd 将仅在同步模式下调用路径检查器。这意味着一次只会运行一个检查器。 这在许多并行运行的多路径检查器导致 CPU 压力很大的情况下非常有用。

  默认值：no

• strict_timing 如果设置为 yes ，multipathd 将在一秒后启动新的路径检查器循环，以便每次路径检查将恰好在 polling_interval 秒内发生。在繁忙的系统上，路径检查可能需要超过一秒的时间； 此处，缺失的刻度将在下一轮中计算在内。 如果路径检查花费的时间超过 polling_interval 秒，则会打印警告。

  默认值：no

• deferred_remove 如果设置为 yes ，当删除最后一个路径设备时，multipathd 将执行延迟删除而不是常规删除。这意味着，如果多路径设备仍在使用中，则当最后一个用户关闭它时，它将被释放。如果在最后一个用户关闭多路径设备之前将路径添加到多路径设备，则延迟删除将被取消。

  默认值：no

• partition_delimiter 如果重命名多路径映射（例如，如果添加或更改映射别名），此参数控制多路径如何选择多路径映射的分区设备名称。 如果此参数设置为“/UNSET/”以外的字符串（甚至是空字符串），则多路径会在设备名称和分区号之间插入该字符串以构造分区设备名称。 否则（即，如果此参数未设置或值为“/UNSET/”），则行为取决于映射名称：如果以数字结尾，则在名称和分区号之间插入“p”； 否则，只需附加分区号。 发行版可以为此选项使用非空默认值； 在这种情况下，用户必须将其设置为“/UNSET/”以获得原始的<unset>行为。 使用 multipath -T 检查当前设置。

  默认值：未设置

• config_dir 如果设置为“”以外的任何值，multipath 将按字母顺序搜索此目录中以“.conf”结尾的文件，并从中读取配置信息，就像在 /etc/multipath.conf 中一样。 config_dir 必须是“”或完全限定的目录名。

  默认值：/etc/multipath/conf.d/

• san_path_err_threshold 如果设置为大于 0 的值，multipathd 将监视路径并检查路径因错误而失败的次数。如果特定路径上的失败次数大于 san_path_err_threshold，则该路径将在 san_path_err_recovery_time 之前不会恢复 。这些路径故障应该发生在 san_path_err_forget_rate 检查中，如果没有，我们将认为该路径足够好以恢复。请参阅下面的“不稳定路径检测”。

  默认值：no

• san_path_err_forget_rate 如果设置为大于 0 的值，multipathd 将在多次检查中检查路径故障是否超过 san_path_err_threshold，即 san_path_err_forget_rate 。 如果是这样，我们将不会恢复路径，直到 san_path_err_recovery_time。请参阅下面的“不稳定路径检测”。

  默认值：no

• san_path_err_recovery_time 如果设置为大于 0 的值，multipathd 将确保当路径故障超过 san_path_err_forget_rate 内的 san_path_err_threshold 时，路径将在 san_path_err_recovery_time 持续时间内处于故障状态。一旦 san_path_err_recovery_time 超时，我们将恢复故障路径。 san_path_err_recovery_time 值应以秒为单位。 请参阅下面的“不稳定路径检测”。

  默认值：no

• marginal_path_double_failed_time 支持基于统计IO错误（例如间歇性错误）进行路径检查的四个参数之一。 当由于 IO 错误而在 margin_path_double_failed_time 秒内发生两次路径失败事件并且设置了所有其他三个参数时，multipathd 将使该路径失败并将该路径排入一个队列，该队列的成员将被发送几个连续的直接读取异步 IO 10HZ 的固定采样率启动 IO 错误核算过程。 请参阅下面的“不稳定路径检测”。

  默认值：no

• marginal_path_err_sample_time 支持基于统计IO错误（例如间歇性错误）进行路径检查的四个参数之一。 如果设置为不小于120的值，则当由于IO错误而在marginal_path_double_failed_time秒内发生两次路径失败事件时，multipathd将使该路径失败，并将该路径加入到一个队列中，该队列的成员会被连续发送几次直接 以 10HZ 的固定采样率读取异步 IO 以启动路径的 IO 统计过程将持续 margin_path_err_sample_time。 如果特定路径上的 IO 错误率大于 margin_path_err_rate_threshold，则该路径将不会在 margin_path_err_recheck_gap_time 秒内恢复，除非只有一个活动路径。 margin_path_err_recheck_gap_time到期后，该路径将被重新排队以进行重新检查。 如果检查结果足够好，该路径将被恢复。 请参阅下面的“不稳定路径检测”。

  默认值：no

• marginal_path_err_rate_threshold 错误率阈值以百分比 (1/1000) 表示。 支持基于统计IO错误（例如间歇性错误）进行路径检查的四个参数之一。 请参阅marginal_path_err_sample_time。 如果特定路径上的 IO 错误率大于此参数，则除非只有一个活动路径，否则该路径将在 margin_path_err_recheck_gap_time 秒内不会恢复。 请参阅下面的“不稳定路径检测”。

  默认值：no

• marginal_path_err_recheck_gap_time 支持基于统计IO错误（例如间歇性错误）进行路径检查的四个参数之一。 请参阅marginal_path_err_sample_time。 如果该参数设置为正值，则IO错误率大于marginal_path_err_rate_threshold的失败路径将在marginal_path_err_recheck_gap_time秒内保持失败状态。 当 margin_path_err_recheck_gap_time 秒到期时，该路径将被重新排队进行检查。 如果检查结果足够好，则该路径将被恢复，否则将保持失败。 请参阅下面的“不稳定路径检测”。

  默认值：no

• delay_watch_checks 此选项已弃用，并映射到 san_path_err_forget_rate。 如果将此值设置为大于 0 的值并且未设置 san_path_err 选项，则 san_path_err_forget_rate 将设置为delay_watch_checks 的值，并且 san_path_err_threshold 将设置为 1。有关详细信息，请参阅 san_path_err_forget_rate 和 san_path_err_threshold 选项以及下面的“不稳定路径检测” 信息。

  默认值：no

• delay_wait_checks 此选项已弃用，并映射到 san_path_err_recovery_time。 如果将此值设置为大于 0 的值并且未设置 san_path_err 选项，则 san_path_err_recovery_time 将设置为 delay_wait_checks 乘以 max_polling_interval 的值。 这将提供与之前的delay_wait_checks 大致相同的等待时间。 此外，san_path_err_threshold 将设置为 1。有关详细信息，请参阅 san_path_err_recovery_time 和 san_path_err_threshold 选项以及下面的“不稳定路径检测”。

• marginal_pathgroups 如果设置为 no，delay_*checks、marginal_path* 和 san_path_err_* 选项将阻止边缘或“不稳定”路径恢复，直到它们被监视一段时间。 这可能会导致所有非边缘路径都关闭的情况，并且在 multipathd 检测到此情况并恢复边缘路径之前没有路径可用。 如果在这种情况下多路径设备未配置为对 IO 进行排队，则即使存在可用的边际路径，也可能会导致发生 IO 错误。 但是，如果此选项设置为 yes，当其中一种边缘路径检测方法确定路径是边缘路径时，它将恢复并放置在单独的路径组中，只有在尝试了所有非边缘路径组后才会使用该路径组 第一的。 这可以防止边缘路径仍然可用时发生 IO 错误的可能性。 在路径经过配置的时间监控并被声明为健康后，它将返回到其正常路径组。 有关详细信息，请参阅下面的“不稳定路径检测”。

  默认值：no

• find_multipaths 此选项控制 multipath 和 multipathd 是否尝试在它们遇到的非黑名单设备上创建多路径映射。这很重要 a)当在 udev 规则处理期间 multipath -u 遇到设备时（设备被更高层阻止进一步处理 - 例如 LVM - 当且仅当它被认为是有效的多路径设备路径时）。以及 b)当 multipathd 检测到新设备时。以下值是可能的：

  • strict multipath 和 multipathd 都只将此类设备视为多路径设备，这些设备先前已成为多路径映射的一部分，因此列在 wwids_file 中。 用户可以使用 multipathd add map 命令手动设置多路径映射。 手动设置后，地图将被记录在 wwids 文件中，并在将来自动设置。

  • no multipath的行为类似struct模式。 multipathd的行为类似greedy模式。

  • yes 如果满足 strict 条件，或者检测到至少两个具有相同 WWID 的非黑名单路径，multipathd 和 multipath 都会将设备视为多路径设备。

  • greedy multipathd 和 multipath 都将每个非黑名单设备视为多路径设备路径。

  • smart 这与 find_multipaths yes 的不同之处仅在于它处理仅检测到一条路径的新设备的方式。 当此类设备首次出现在 udev 规则中时，它将被视为多路径设备。 multipathd 等待是否出现具有相同 WWID 的其他路径。 如果发生这种情况，它会设置一个多路径映射。 如果直到超时才发生，或者设置地图失败，则会为设备触发一个新的 uevent； 在 udev 规则中第二次遇到时，该设备将被视为非多路径并传递给
    上层。 注意：如果存在未列入黑名单的单路径设备，这可能会导致设备检测期间出现延迟。

    默认值：strict

• find_multipaths_timeout 如果设置了 find_multipaths“smart”（见上文），则在检测到第一个路径后等待其他路径的超时（以秒为单位）。 如果该值为正数，则此超时将用于遇到的所有未知的非黑名单设备。 如果该值为负数（推荐），则它仅适用于在多路径硬件表（内置表或设备部分）中具有条目的“已知”设备； 其他（“未知”）设备将使用仅 1 秒的超时以避免启动延迟。 值 0 表示“使用内置默认值”。 如果 find_multipath 的值不是 smart，则此选项无效。

  默认值：-10（已知硬件为 10 秒，未知硬件为 1 秒）

• uxsock_timeout CLI 接收超时（以毫秒为单位）。 对于较大的系统，在释放 multipathd 锁定并且可以处理 CLI 命令之前，CLI 命令可能会超时。 这将导致 CLI 命令返回“超时接收数据包”等错误。 在这些情况下，建议增加 CLI 超时以避免这些问题。

  默认值：1000

• retrigger_tries 设置 multipathd 尝试重新触发 uevent 以获取 WWID 的次数。

  默认值：3

• retrigger_delay 设置重新触发之间等待的时间（以秒为单位）。

  默认值：10

• missing_uev_wait_timeskip_kpartxout 控制在创建新的多路径设备后，在自动启用设备重新加载之前，multipathd 将等待多少秒以从 udev 接收设备的更改事件。 通常，multipathd 会延迟设备上的重新加载，直到收到来自初始表加载的更改 uevent。

  默认值：30

• skip_kpartx 如果设置为 yes ，kpartx 将不会自动在设备上创建分区。

  默认值：no

• disable_changed_wwids 此选项已被弃用并被忽略。 如果路径的 WWID 突然更改，multipathd 会像删除然后再次添加一样处理它。

• remove_retries 这设置多路径重试删除正在使用的设备的次数。 在每次尝试之间，多路径将休眠 1 秒。

  默认值：0

• max_sectors_kb 将所有路径设备和多路径设备上的 max_sectors_kb 设备参数设置为指定值。

  默认值：依赖于对应的设备

• ghost_delay 设置在创建仅包含幽灵路径的设备之后多路径在将其标记为可在 systemd 中使用之前等待的秒数。这使得在多路径运行硬件处理程序将幽灵路径切换到活动路径之前，活动路径有时间出现。将其设置为 0 或打开会使多路径立即将仅具有幽灵路径的设备标记为就绪。

  默认值：no

• enable_foreign 启用或禁用外部库（请参阅下面的“外部多路径支持”部分）。 该值是一个正则表达式； 如果外部库的名称（例如“nvme”）与表达式匹配，则加载外部库。 默认情况下，启用所有外部库。

  默认值：””

blacklist and blacklist_exceptions

blacklist 部分用于从多路径拓扑中排除特定设备。 它最常用于排除多路径工具处理本地磁盘或非磁盘设备（例如存储阵列控制器的 LUN）。

blacklist_exceptions 部分用于恢复黑名单部分的操作。 这允许人们有选择地包括（“白名单”）通常通过黑名单部分排除的设备。 常见用法是使用包罗万象的正则表达式将“所有内容”列入黑名单，并为应由多路径工具处理的那些设备创建特定的 blacklist_exceptions 条目。

两个部分均识别以下关键字。 除非明确说明，否则默认值为空。

• devnode 与要排除/包含的设备节点匹配的正则表达式。

  默认黑名单由正则表达式“^(ram|zram|raw|loop|fd|md|dm-|sr|scd|st|dcssblk)[0-9]”和“^(td|hd|vd)”组成 [a-z]”。 默认情况下，这会导致虚拟设备、非磁盘设备和某些其他设备类型被排除在多路径处理之外。

• wwid 要排除/包含的设备的全球标识符的正则表达式。

• device 设备描述子节。 本小节识别供应商和产品关键字。 两者都是正则表达式。 有关这些关键字的完整说明，请参阅设备部分说明。

• property udev 属性的正则表达式。 所有具有匹配 udev 属性的设备都将被排除/包含。 property 关键字的处理是特殊的，因为如果设置了属性 blacklist_exception，则设备必须至少有一个列入白名单的 udev 属性； 否则，它们将被视为黑名单，并在日志中显示消息“黑名单，udev 属性丢失”。 例如，将属性 blacklist_exception 设置为 (SCSI_IDENT_|ID_WWN) 将导致包含正常运行的 SCSI 设备和提供 WWN（全球号码）的设备，并排除所有其他设备。 这可以排除大多数非多路径设备。

  注意: 与以前的版本相比，multipath-tools 0.8.2 中此选项的行为发生了变化。 按缺失属性列入黑名单仅适用于确实设置了 uid_attribute（例如 ID_SERIAL）指定的属性的设备。 以前，它应用于所有设备，可能会导致设备因临时 I/O 错误情况而被列入黑名单。

• protocol 要排除/包含的设备协议的正则表达式。

  多路径识别的协议字符串为 scsi:fcp、scsi:spi、scsi:ssa、scsi:sbp、scsi:srp、scsi:iscsi、scsi:sas、scsi:adt、scsi:ata、scsi:unspec、ccw、cciss 、nvme 和 undef。 可以通过运行 multipathd show paths format “%d %P” 查看路径正在使用的协议。

对于每个设备，这 5 个黑名单标准按照“property、devnode、device、protocol、wwid”的顺序进行评估。 如果设备被任何标准列入黑名单，则它将被排除在 multipathd 处理之外，并且不再评估后面的标准。 对于每个标准，如果设备同时匹配白名单和黑名单，则白名单优先于黑名单。

注意：除了黑名单和白名单之外，其他配置选项（例如 find_multipaths）也会影响给定设备是否由多路径工具处理。

multipath

多路径部分允许设置多路径映射的属性。 通过多路径部分设置的属性（请参见下面的列表）优先于所有其他配置设置，包括来自覆盖部分的属性。

多路径部分唯一可识别的属性是多路径子部分。 如果存在与给定 WWID 匹配的多个多路径子部分，则这些部分的内容将被合并，并且后面条目中的设置优先。

多路径子节识别以下属性：

• wwid （强制）全球标识符。 检测到的多路径映射与此属性进行匹配。 请注意，与黑名单部分中的 wwid 属性不同，这不是正则表达式或子字符串； WWID 必须在多路径部分内完全匹配。
• alias 多路径映射的符号名称。 这优先于绑定文件中相同 WWID 的条目。

以下属性是可选的； 如果未设置，默认值将从overrides、devices或defaults部分获取：

• path_grouping_policy
• path_selector
• prio
• prio_args
• failback
• rr_weight
• no_path_retry
• rr_min_io
• rr_min_io_rq
• flush_on_last_del
• features
• reservation_key
• user_friendly_names
• deferred_remove
• san_path_err_threshold
• san_path_err_forget_rate
• san_path_err_recovery_time
• marginal_path_err_sample_time
• marginal_path_err_rate_threshold
• marginal_path_err_recheck_gap_time
• marginal_path_double_failed_time
• delay_watch_checks
• delay_wait_checks
• skip_kpartx
• max_sectors_kb
• ghost_delay

devices

multipath-tools 有一个内置设备表，其中包含 100 多个已知的支持多路径的存储设备的合理默认值。 设备部分可用于覆盖这些设置。 如果给定设备有多个匹配项，则所有匹配条目的属性都将应用于该设备。 如果在多个匹配的设备小节中指定了某个属性，则后面的条目优先。 因此，config_dir 下的文件中的条目（按相反的字母顺序）具有最高优先级，其次是 multipath.conf 中的条目； 内置硬件表的优先级最低。 在配置文件中，后面的条目比前面的条目具有更高的优先级。

devices 部分唯一可识别的属性是 device 子部分。 系统中检测到的设备使用供应商、产品和修订字段与设备条目进行匹配，这些字段都是 POSIX 扩展正则表达式（请参阅 regex(7)）。

multipath 或multipathd检测系统中设备的供应商（vendor）、产品（product）和版本（revision）字段取决于设备类型。 对于 SCSI 设备，它们对应于 SCSI INQUIRY 页的相应字段。 一般来说，命令“multipathd show paths format “%d %s””可用于查看系统中所有设备的检测到的属性。

设备部分识别以下属性：

• vendor （强制）匹配供应商名称的正则表达式。

• product （强制）匹配产品名称的正则表达式。

• revision 匹配产品版本的正则表达式。 如果未指定，则任何修订版都会匹配。

• product_blacklist 给定供应商与此字符串匹配的产品将被列入黑名单。 这相当于黑名单部分中的设备条目，其供应商属性设置为该条目的供应商，产品属性设置为product_blacklist 的值。

• alias_prefix 用于此设备类型的 user_Friendly_names 前缀，而不是默认的“mpath”。

• vpd_vendor 供应商特定的 vpd 页面信息，使用 vpd 页面缩写。 vpd 页面缩写可以通过运行 sg_vpd -e 找到。 multipathd 将使用此信息来收集设备特定信息，这些信息可以通过 multipathd show paths format 和 multipathd show paths format 命令的 %g 通配符显示。 目前仅支持 hp3par vpd 页面。

• hardware_handler 用于此设备类型的硬件处理程序。 实现了以下硬件处理程序：

  • 1 emc （取决于硬件）DGC 类阵列（如 CLARiiON CX/AX 和 EMC VNX 以及 Unity 系列）的硬件处理程序。
  • 1 rdac （依赖于硬件）LSI/Engenio/NetApp RDAC 类（如 NetApp SANtricity E/EF 系列）以及来自 IBM DELL SGI STK 和 SUN 的 OEM 阵列的硬件处理程序。
  • 1 hp_sw （取决于硬件）专用于具有活动/备用模式的 HP/COMPAQ/DEC HSG80 和 MSA/HSV 阵列的硬件处理程序。
  • 1 alua （取决于硬件）SCSI-3 ALUA 兼容阵列的硬件处理程序。
  • 1 ana （取决于硬件）NVMe ANA 兼容阵列的硬件处理程序。

  重要提示：Linux 内核 4.3 及更高版本会自动将设备处理程序附加到已知设备（包括所有支持 SCSI-3 ALUA 的设备），并且之后不允许更改处理程序。 在这些内核上为此类设备设置 hardware_handler 没有任何效果。

以下属性是可选的； 如果未设置，则默认值将从defaults部分获取：

• path_grouping_policy
• uid_attribute
• getuid_callout
• path_selector
• path_checker
• prio
• prio_args
• features
• failback
• rr_weight
• no_path_retry
• rr_min_io
• rr_min_io_rq
• fast_io_fail_tmo
• dev_loss_tmo
• flush_on_last_del
• user_friendly_names
• retain_attached_hw_handler
• detect_prio
• detect_checker
• deferred_remove
• san_path_err_threshold
• san_path_err_forget_rate
• san_path_err_recovery_time
• marginal_path_err_sample_time
• marginal_path_err_rate_threshold
• marginal_path_err_recheck_gap_time
• marginal_path_double_failed_time
• delay_watch_checks
• delay_wait_checks
• skip_kpartx
• max_sectors_kb
• ghost_delay
• all_tg_pt

overrides

overrides 部分识别以下可选属性； 如果未设置，则从设备或defaults部分获取值：

• path_grouping_policy
• uid_attribute
• getuid_callout
• path_selector
• path_checker
• alias_prefix
• features
• prio
• prio_args
• failback
• rr_weight
• no_path_retry
• rr_min_io
• rr_min_io_rq
• flush_on_last_del
• fast_io_fail_tmo
• dev_loss_tmo
• user_friendly_names
• retain_attached_hw_handler
• detect_prio
• detect_checker
• deferred_remove
• san_path_err_threshold
• san_path_err_forget_rate
• san_path_err_recovery_time
• marginal_path_err_sample_time
• marginal_path_err_rate_threshold
• marginal_path_err_recheck_gap_time
• marginal_path_double_failed_time
• delay_watch_checks
• delay_wait_checks
• skip_kpartx
• max_sectors_kb
• ghost_delay
• all_tg_pt

WWID 生成

多路径使用全球标识 (WWID) 来确定哪些路径属于同一设备。 假设呈现相同 WWID 的每条路径都指向同一设备。

WWID 由四种方法生成（按优先顺序排列）：

• uid_attrs WWID是通过匹配设备节点名称从udev属性派生而来的； 参见上面的 uid_attrs。
• getuid_callout 使用指定的外部程序； 参见上面的 getuid_callout。 使用此方法时应注意； 外部程序需要从磁盘加载来执行，这可能会导致全路径下场景中的死锁情况。
• uid_attribute 使用指定的udev属性的值； 参见上面的 uid_attribute。 此方法优于 getuid_callout，因为 multipath 不需要在此处调用任何外部程序。 但是，在某些情况下，udev 可能无法生成所请求的变量。
• sysfs 尝试从 sysfs 属性确定 WWID。 对于 SCSI 设备，这意味着读取重要产品数据 (VPD) 页“设备标识”(0x83)。

默认设置（使用从内置硬件表配置的 udev 和 uid_attribute）在大多数情况下应该可以正常工作。 想要启用uevent合并的用户必须设置uid_attrs。

不稳定路径检测

SAN 设置中的一个常见问题是出现间歇性错误：路径无法访问，然后短时间内再次可达，再次消失，等等。 这种情况通常发生在不稳定的互连上。 在如此频繁、不可靠的事件上不必要地切换路径组是不合需要的。 multipathd 支持三种不同的方法来检测和处理这种情况。 所有方法共享相同的基本操作模式：如果发现路径“不稳定”或“翻转”，并且看起来处于健康状态，则不会立即恢复（重新使用）。 相反，它被置于“延迟”状态并观察一段时间，只有在健康状态看起来稳定时才恢复。 如果设置了 margin_pathgroups 选项，路径将立即恢复，但会放置在边缘路径的特殊路径组中。 在尝试完所有其他路径组之前，不会使用边缘路径组。 当路径正常恢复时，它将返回到其正常路径组。 确定“不稳定”状况的逻辑以及何时恢复的逻辑在三种方法之间是不同的。

• “delay_checks” 失败跟踪。此方法已弃用并映射到“san_path_err”方法。 有关更多信息，请参阅上面的delay_watch_checks 和delay_wait_checks 选项。

• “marginal_path” 失败跟踪。如果在故障发生后的 margin_path_double_failed_time 秒内发生第二次故障事件（好->坏转换），则会对受影响的路径启动高频监控：以每秒 10 个的速率发送 I/O。 这是在 margin_path_err_sample_time 秒内完成的。 在此期间，路径不会恢复。 如果在监控期间错误率保持低于marginal_path_err_rate_threshold，则路径将恢复。 否则，将保持失败状态marginal_path_err_recheck_gap_time，之后再次进行监控。 对于此方法，时间间隔以秒为单位测量。

• “san_path_err” 失败跟踪。multipathd 对每条路径的路径故障进行计数。 一旦失败次数超过 san_path_err_threshold 给定的值，路径在 san_path_err_recovery_time 秒内不会恢复。 在计算失败次数时，multipathd 每“san_path_err_forget_rate”一次就会“忘记”一次过去的失败； 因此，如果在遗忘率间隔内错误发生的频率不高于一次，则失败计数不会增加，并且永远不会达到阈值。 时间间隔是 multipathd 路径检查之间的时间，它是可变的，由 polling_interval 和 max_polling_interval 参数控制。

  此方法已被弃用，取而代之的是“marginal_path”故障跟踪方法，并且仅提供向后兼容性。

有关详细信息，请参阅上面各个选项的文档。 强烈建议不要对任何给定的多路径映射使用多个这些方法，因为这两种并发方法可能会以不可预测的方式交互。 如果“marginal_path”方法处于活动状态，则“san_path_err”参数将隐式设置为 0。

外部多路径支持

multipath 和 multipathd 可以加载 “外部” 库，以添加对 Linux 设备映射器之外的其他多路径技术的支持。 目前，此支持仅限于打印检测到的有关多路径设置的信息。 在拓扑输出中，外部映射的名称以方括号中的外部库名称为前缀，如本例中所示：

   # multipath -ll
   uuid.fedcba98-3579-4567-8765-123456789abc [nvme]:nvme4n9 NVMe,Some NVMe controller,FFFFFFFF
   size=167772160 features='n/a' hwhandler='ANA' wp=rw
   |-+- policy='n/a' prio=50 status=optimized
   | `- 4:38:1    nvme4c38n1 0:0     n/a   optimized    live
   `-+- policy='n/a' prio=50 status=optimized
     `- 4:39:1    nvme4c39n1 0:0     n/a   optimized    live

“nvme” 外部库为内核中的 NVMe 本机多路径提供支持。 它是标准多路径包的一部分。

已知的问题

在 LUN 的所有路径都脱机的情况下，使用queue_if_no_path 选项可能会导致 D 状态进程挂起且不可终止。 建议改用 no_path_retry 选项。

如果 dev_loss_tmo 设置导致设备在 I/O 仍在排队时被删除，则使用queue_if_no_path 或 no_path_retry 可能会导致死锁。 多路径守护进程将相应地更新 dev_loss_tmo 设置以避免这种死锁。 因此，如果指定了两个值，则优先顺序为 no_path_retry、queue_if_no_path、dev_loss_tmo。

也可以看看

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

关于

multipath-tools 由 Christophe Varoqui、christophe.varoqui@opensvc.com 等人开发。

reference

[1] https://github.com/opensvc/multipath-tools