故障注入功能基础架构¶

另请参阅 scsi_debug 的 “every_nth” 模块选项。

可用的故障注入功能¶

failslab

注入 slab 分配失败。（kmalloc(), kmem_cache_alloc(), ...）
fail_page_alloc

注入页面分配失败。（alloc_pages(), get_free_pages(), ...）
fail_usercopy

在用户内存访问函数中注入失败。（copy_from_user(), get_user(), ...）
fail_futex

注入 futex 死锁和 uaddr 故障错误。
fail_sunrpc

注入内核 RPC 客户端和服务器失败。
fail_make_request

在通过设置 /sys/block/<device>/make-it-fail 或 /sys/block/<device>/<partition>/make-it-fail 允许的设备上注入磁盘 IO 错误。（submit_bio_noacct()）
fail_mmc_request

在通过设置 /sys/kernel/debug/mmc0/fail_mmc_request 下的 debugfs 条目所允许的设备上注入 MMC 数据错误
fail_function

通过设置 /sys/kernel/debug/fail_function 下的 debugfs 条目，在由 ALLOW_ERROR_INJECTION() 宏标记的特定函数上注入错误返回值。不支持引导选项。
fail_skb_realloc

向网络路径中注入 skb（套接字缓冲区）重新分配事件。主要目标是识别和防止网络子系统中与指针管理不当相关的问题。通过在关键点强制进行 skb 重新分配，此功能创建了指向 skb 标头的现有指针失效的场景。

当注入故障并触发重新分配时，缓存的 skb 标头和数据指针不再引用有效的内存位置。这种刻意的失效有助于暴露在重新分配事件后忽略正确更新指针的代码路径。

通过创建这些受控的故障场景，系统可以捕获使用陈旧指针的实例，这些指针可能会导致内存损坏或系统不稳定。

要选择要操作的接口，请将网络名称写入 /sys/kernel/debug/fail_skb_realloc/devname。如果该字段留空（这是默认值），则将在所有网络接口上强制进行 skb 重新分配。

启用 KASAN 时，此故障检测的有效性会得到增强，因为它有助于识别无效内存引用和释放后使用 (UAF) 问题。
NVMe 故障注入

在通过设置 /sys/kernel/debug/nvme*/fault_inject 下的 debugfs 条目所允许的设备上注入 NVMe 状态码和重试标志。默认状态码为 NVME_SC_INVALID_OPCODE，无重试。状态码和重试标志可以通过 debugfs 进行设置。
Null 测试块驱动程序故障注入

通过在 /sys/kernel/config/nullb/<disk>/timeout_inject 下设置配置项来注入 IO 超时，通过在 /sys/kernel/config/nullb/<disk>/requeue_inject 下设置配置项来注入重新排队请求，以及通过在 /sys/kernel/config/nullb/<disk>/init_hctx_fault_inject 下设置配置项来注入 init_hctx() 错误。

Configure fault-injection capabilities behavior¶

debugfs entries¶

fault-inject-debugfs 内核模块提供了一些 debugfs 条目，用于运行时配置故障注入功能。

/sys/kernel/debug/fail*/probability

故障注入的可能性，以百分比表示。

格式：<percent>

请注意，对于某些测试用例来说，百分之一的失败率是非常高的错误率。对于此类测试用例，请考虑设置 probability=100 并配置 /sys/kernel/debug/fail*/interval。
/sys/kernel/debug/fail*/interval

指定故障之间的间隔，适用于通过了所有其他测试的对 should_fail() 的调用。

请注意，如果您通过设置 interval>1 来启用此功能，您可能需要将 probability 设置为 100。
/sys/kernel/debug/fail*/times

指定故障最多可发生多少次。值为 -1 意味着“无限制”。
/sys/kernel/debug/fail*/space

指定初始资源“预算”，在每次调用 should_fail(,size) 时按 “size” 递减。在 “space” 达到零之前，故障注入将被抑制。
/sys/kernel/debug/fail*/verbose

格式：{ 0 | 1 | 2 }

指定注入故障时消息的详细程度。“0”表示无消息；“1”表示每次故障仅打印单行日志；“2”还将打印调用栈 —— 这对调试故障注入暴露出的问题非常有用。
/sys/kernel/debug/fail*/task-filter

格式：{ ‘Y’ | ‘N’ }

值为 ‘N’ 时禁用按进程过滤（默认）。任何正值都会将故障限制为仅由 /proc/<pid>/make-it-fail==1 指定的进程。
/sys/kernel/debug/fail*/require-start, /sys/kernel/debug/fail*/require-end, /sys/kernel/debug/fail*/reject-start, /sys/kernel/debug/fail*/reject-end

指定在栈回溯遍历期间测试的虚拟地址范围。仅当遍历的栈回溯中的某个调用者位于所需范围内，且没有任何调用者位于拒绝范围内时，才会注入故障。默认的所需范围是 [0,ULONG_MAX)（整个虚拟地址空间）。默认的拒绝范围是 [0,0)。
/sys/kernel/debug/fail*/stacktrace-depth

指定在 [require-start,require-end) 或 [reject-start,reject-end) 范围内搜索调用者时遍历的最大栈回溯深度。
/sys/kernel/debug/fail_page_alloc/ignore-gfp-highmem

格式：{ ‘Y’ | ‘N’ }

默认为 ‘Y’，将其设置为 ‘N’ 还将向高端内存/用户分配（__GFP_HIGHMEM 分配）中注入故障。
/sys/kernel/debug/failslab/cache-filter
格式：{ ‘Y’ | ‘N’ }

默认为 ‘N’，将其设置为 ‘Y’ 将仅在从特定缓存请求对象时注入故障。

通过向 /sys/kernel/slab/<cache>/failslab 写入 ‘1’ 来选择缓存。
/sys/kernel/debug/failslab/ignore-gfp-wait
/sys/kernel/debug/fail_page_alloc/ignore-gfp-wait

格式：{ ‘Y’ | ‘N’ }

默认为 ‘Y’，将其设置为 ‘N’ 还将向可以睡眠的分配（__GFP_DIRECT_RECLAIM 分配）中注入故障。
/sys/kernel/debug/fail_page_alloc/min-order

指定要注入故障的最小页面分配阶（order）。
/sys/kernel/debug/fail_futex/ignore-private

格式：{ ‘Y’ | ‘N’ }

默认为 ‘N’，将其设置为 ‘Y’ 将在处理私有（地址空间）futex 时禁用故障注入。
/sys/kernel/debug/fail_sunrpc/ignore-client-disconnect

格式：{ ‘Y’ | ‘N’ }

默认为 ‘N’，将其设置为 ‘Y’ 将禁用 RPC 客户端上的断开连接注入。
/sys/kernel/debug/fail_sunrpc/ignore-server-disconnect

格式：{ ‘Y’ | ‘N’ }

默认为 ‘N’，将其设置为 ‘Y’ 将禁用 RPC 服务器上的断开连接注入。
/sys/kernel/debug/fail_sunrpc/ignore-cache-wait

格式：{ ‘Y’ | ‘N’ }

默认为 ‘N’，将其设置为 ‘Y’ 将禁用 RPC 服务器上的缓存等待注入。
/sys/kernel/debug/fail_function/inject

格式：{ ‘function-name’ | ‘!function-name’ | ‘’ }

按名称指定错误注入的目标函数。如果函数名带有 ‘!’ 前缀，则从注入列表中移除给定的函数。如果未指定任何内容（‘’），则清除注入列表。
/sys/kernel/debug/fail_function/injectable

（只读）显示可注入错误的功能以及可以指定什么类型的错误值。错误类型将是以下之一； - NULL：返回值必须为 0。 - ERRNO：返回值必须为 -1 到 -MAX_ERRNO (-4096)。 - ERR_NULL：返回值必须为 0 或 -1 到 -MAX_ERRNO (-4096)。
/sys/kernel/debug/fail_function/<function-name>/retval

指定要注入到给定函数的“错误”返回值。当用户指定新的注入条目时将创建此文件。请注意，该文件仅接受无符号值。因此，如果您想使用负的 errno，最好使用 ‘printf’ 而不是 ‘echo’，例如：$ printf %#x -12 > retval

/sys/kernel/debug/fail_skb_realloc/devname

指定要强制进行 SKB 重新分配的网络接口。如果留空，SKB 重新分配将应用于所有网络接口。

用法示例
# Force skb reallocation on eth0
echo "eth0" > /sys/kernel/debug/fail_skb_realloc/devname

# Clear the selection and force skb reallocation on all interfaces
echo "" > /sys/kernel/debug/fail_skb_realloc/devname

Boot option¶

为了在 debugfs 不可用时（引导早期）注入故障，请使用引导选项

failslab=
fail_page_alloc=
fail_usercopy=
fail_make_request=
fail_futex=
fail_skb_realloc=
mmc_core.fail_request=<interval>,<probability>,<space>,<times>

proc entries¶

/proc/<pid>/fail-nth, /proc/self/task/<tid>/fail-nth

向该文件写入整数 N 会使任务中的第 N 次调用失败。从该文件读取会返回一个整数值。值 ‘0’ 表示通过先前写入该文件设置的故障已被注入。正整数 N 表示尚未注入故障。请注意，此文件会启用所有类型的故障（slab、futex 等）。此设置优先于所有其他通用的 debugfs 设置，如 probability、interval、times 等。但每个功能专属的设置（例如 fail_futex/ignore-private）优先于它。

此功能旨在对单个系统调用中的故障进行系统性测试。请参阅下面的示例。

Error Injectable Functions¶

本部分适用于考虑将函数添加到 ALLOW_ERROR_INJECTION() 宏的内核开发人员。

Requirements for the Error Injectable Functions¶

由于函数级错误注入会强制改变代码路径，即使输入和条件正常也会返回错误，如果您允许在不可注入错误的功能上进行错误注入，这可能会导致意外的内核崩溃。因此，您（和审阅者）必须确保：

如果失败，该函数会返回错误码，并且调用者必须正确检查它（需要从中恢复）。
在首次返回错误之前，该函数不会执行任何可以改变任何状态的代码。状态包括全局或局部变量，或输入变量。例如，清除输出地址存储（例如 *ret = NULL）、增加/减少计数器、设置标志、禁用抢占/中断或获取锁（如果在返回错误之前恢复了这些，那将是可以的）。

第一个要求非常重要，这将导致释放（释放对象）函数通常比分配函数更难以注入错误。如果此类释放函数的错误未得到正确处理，将很容易导致内存泄漏（调用者会误认为对象已被释放或损坏）。

第二个要求适用于期望该函数始终执行某些操作的调用者。因此，如果函数错误注入跳过了整个函数，则这种期望就会被打破并导致意外错误。

Type of the Error Injectable Functions¶

每个可注入错误的功能都将具有由 ALLOW_ERROR_INJECTION() 宏指定的错误类型。如果您添加新的可注入错误的功能，则必须仔细选择它。如果选择了错误的错误类型，内核可能会崩溃，因为它可能无法处理该错误。include/asm-generic/error-injection.h 中定义了 4 种类型的错误：

EI_ETYPE_NULL: 如果失败，此函数将返回 NULL。例如，返回分配的对象地址。
EI_ETYPE_ERRNO: 如果失败，此函数将返回 -errno 错误码。例如，如果输入错误则返回 -EINVAL。这将包括通过 ERR_PTR() 宏编码了 -errno 的地址的函数。
EI_ETYPE_ERRNO_NULL: 如果失败，此函数将返回 -errno 或 NULL。如果此函数的调用者使用 IS_ERR_OR_NULL() 宏检查返回值，则此类型将是合适的。
EI_ETYPE_TRUE: 如果失败，此函数将返回 true（非零正值）。

如果您指定了错误的类型，例如，为返回分配对象的函数指定 EI_TYPE_ERRNO，这可能会引起问题，因为返回值不是对象地址，并且调用者无法访问该地址。

How to add new fault injection capability¶

#include <linux/fault-inject.h>
定义故障属性

DECLARE_FAULT_ATTR(name);

有关详细信息，请参阅 fault-inject.h 中的 struct fault_attr 定义。
提供配置故障属性的方法
引导选项

如果您需要从引导时启用故障注入功能，您可以提供引导选项来对其进行配置。为此有一个辅助函数

setup_fault_attr(attr, str);
debugfs 条目

failslab、fail_page_alloc、fail_usercopy 和 fail_make_request 使用此方法。辅助函数

fault_create_debugfs_attr(name, parent, attr);
模块参数

如果故障注入功能的范围仅限于单个内核模块，则最好提供模块参数来配置故障属性。
添加钩子以插入故障

当 should_fail() 返回 true 时，客户端代码应注入故障

should_fail(attr, size);

Application Examples¶

将 slab 分配失败注入到模块 init/exit 代码中

#!/bin/bash

FAILTYPE=failslab
echo Y > /sys/kernel/debug/$FAILTYPE/task-filter
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
echo -1 > /sys/kernel/debug/$FAILTYPE/times
echo 0 > /sys/kernel/debug/$FAILTYPE/space
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
echo Y > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait

faulty_system()
{
    bash -c "echo 1 > /proc/self/make-it-fail && exec $*"
}

if [ $# -eq 0 ]
then
    echo "Usage: $0 modulename [ modulename ... ]"
    exit 1
fi

for m in $*
do
    echo inserting $m...
    faulty_system modprobe $m

    echo removing $m...
    faulty_system modprobe -r $m
done

仅为特定模块注入页面分配失败

#!/bin/bash

FAILTYPE=fail_page_alloc
module=$1

if [ -z $module ]
then
    echo "Usage: $0 <modulename>"
    exit 1
fi

modprobe $module

if [ ! -d /sys/module/$module/sections ]
then
    echo Module $module is not loaded
    exit 1
fi

cat /sys/module/$module/sections/.text > /sys/kernel/debug/$FAILTYPE/require-start
cat /sys/module/$module/sections/.data > /sys/kernel/debug/$FAILTYPE/require-end

echo N > /sys/kernel/debug/$FAILTYPE/task-filter
echo 10 > /sys/kernel/debug/$FAILTYPE/probability
echo 100 > /sys/kernel/debug/$FAILTYPE/interval
echo -1 > /sys/kernel/debug/$FAILTYPE/times
echo 0 > /sys/kernel/debug/$FAILTYPE/space
echo 2 > /sys/kernel/debug/$FAILTYPE/verbose
echo Y > /sys/kernel/debug/$FAILTYPE/ignore-gfp-wait
echo Y > /sys/kernel/debug/$FAILTYPE/ignore-gfp-highmem
echo 10 > /sys/kernel/debug/$FAILTYPE/stacktrace-depth

trap "echo 0 > /sys/kernel/debug/$FAILTYPE/probability" SIGINT SIGTERM EXIT

echo "Injecting errors into the module $module... (interrupt to stop)"
sleep 1000000

在 btrfs 挂载时注入 open_ctree 错误

#!/bin/bash

rm -f testfile.img
dd if=/dev/zero of=testfile.img bs=1M seek=1000 count=1
DEVICE=$(losetup --show -f testfile.img)
mkfs.btrfs -f $DEVICE
mkdir -p tmpmnt

FAILTYPE=fail_function
FAILFUNC=open_ctree
echo $FAILFUNC > /sys/kernel/debug/$FAILTYPE/inject
printf %#x -12 > /sys/kernel/debug/$FAILTYPE/$FAILFUNC/retval
echo N > /sys/kernel/debug/$FAILTYPE/task-filter
echo 100 > /sys/kernel/debug/$FAILTYPE/probability
echo 0 > /sys/kernel/debug/$FAILTYPE/interval
echo -1 > /sys/kernel/debug/$FAILTYPE/times
echo 0 > /sys/kernel/debug/$FAILTYPE/space
echo 1 > /sys/kernel/debug/$FAILTYPE/verbose

mount -t btrfs $DEVICE tmpmnt
if [ $? -ne 0 ]
then
    echo "SUCCESS!"
else
    echo "FAILED!"
    umount tmpmnt
fi

echo > /sys/kernel/debug/$FAILTYPE/inject

rmdir tmpmnt
losetup -d $DEVICE
rm testfile.img

仅注入 skbuff 分配失败

# mark skbuff_head_cache as faulty
echo 1 > /sys/kernel/slab/skbuff_head_cache/failslab
# Turn on cache filter (off by default)
echo 1 > /sys/kernel/debug/failslab/cache-filter
# Turn on fault injection
echo 1 > /sys/kernel/debug/failslab/times
echo 1 > /sys/kernel/debug/failslab/probability

Tool to run command with failslab or fail_page_alloc¶

为了更容易地完成上述任务，我们可以使用 tools/testing/fault-injection/failcmd.sh。请运行命令 “./tools/testing/fault-injection/failcmd.sh --help” 了解更多信息并查看以下示例。

示例

在注入 slab 分配失败的情况下运行命令 “make -C tools/testing/selftests/ run_tests”

# ./tools/testing/fault-injection/failcmd.sh \
        -- make -C tools/testing/selftests/ run_tests

与上面相同，只是最多指定 100 次失败，而不是默认的最多 1 次

# ./tools/testing/fault-injection/failcmd.sh --times=100 \
        -- make -C tools/testing/selftests/ run_tests

与上面相同，只是注入页面分配失败而不是 slab 分配失败

# env FAILCMD_TYPE=fail_page_alloc \
        ./tools/testing/fault-injection/failcmd.sh --times=100 \
        -- make -C tools/testing/selftests/ run_tests

Systematic faults using fail-nth¶

以下代码在 socketpair() 系统调用中系统性地对第 0 个、第 1 个、第 2 个等功能进行故障注入

#include <sys/types.h>
#include <sys/stat.h>
#include <sys/socket.h>
#include <sys/syscall.h>
#include <fcntl.h>
#include <unistd.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

int main()
{
      int i, err, res, fail_nth, fds[2];
      char buf[128];

      system("echo N > /sys/kernel/debug/failslab/ignore-gfp-wait");
      sprintf(buf, "/proc/self/task/%ld/fail-nth", syscall(SYS_gettid));
      fail_nth = open(buf, O_RDWR);
      for (i = 1;; i++) {
              sprintf(buf, "%d", i);
              write(fail_nth, buf, strlen(buf));
              res = socketpair(AF_LOCAL, SOCK_STREAM, 0, fds);
              err = errno;
              pread(fail_nth, buf, sizeof(buf), 0);
              if (res == 0) {
                      close(fds[0]);
                      close(fds[1]);
              }
              printf("%d-th fault %c: res=%d/%d\n", i, atoi(buf) ? 'N' : 'Y',
                      res, err);
              if (atoi(buf))
                      break;
      }
      return 0;
}

示例输出

1-th fault Y: res=-1/23
2-th fault Y: res=-1/23
3-th fault Y: res=-1/12
4-th fault Y: res=-1/12
5-th fault Y: res=-1/23
6-th fault Y: res=-1/23
7-th fault Y: res=-1/23
8-th fault Y: res=-1/12
9-th fault Y: res=-1/12
10-th fault Y: res=-1/12
11-th fault Y: res=-1/12
12-th fault Y: res=-1/12
13-th fault Y: res=-1/12
14-th fault Y: res=-1/12
15-th fault Y: res=-1/12
16-th fault N: res=0/12

Linux 内核

目录

本页