inject(8)

🎀 inject(8) ✨ System Manager's Manual

inject(8), bestie, and it's giving main character energy 💅🦋

✨ NAME ✨

okay so inject is the tool that injects the right error into a function when your input call chain and predicates all line up 🫶 It runs on Linux eBPF/bcc, so it's giving low-level and I'm obsessed 🧚

🌸 SYNOPSIS 🌸

inject -h [-I header] [-P probability] [-v] [-c count] <mode> <spec>

💖 DESCRIPTION 💖

okay so inject breaks things on purpose: it injects errors into the kernel functionality you pick, but only when your call chain and its predicates are satisfied 😭✨

⚠️ WARNING: this tool injects failures into key kernel functions and may crash the kernel 💀 Know what you're doing before you touch it, bestie. Seriously.

This one leans on a Linux 4.16 feature, bpf_override_return() 🔥

Since it's built on BPF, only the root user can run it. No cap 👑

🎀 OPTIONS 🎀

• -h — prints the usage message 🍓
• -v — shows you the generated BPF program, so you can debug it or tweak it 🔍
• -I header — the headers you need included 📎
• -P probability — the optional chance of failure. It defaults to 1 🎲
• -c count — how many errors to inject before it stops. By default it never stops, iykyk 🙈

🦋 MODE 🦋

• kmalloc — makes the following function report failure:

int should_failslab(struct kmem_cache *s, gfp_t gfpflags)

• bio — makes the following function report failure:

int should_fail_bio(struct bio *bio)

• alloc_page — makes the following function report failure:

bool should_fail_alloc_page(gfp_t gfp_mask, unsigned int order)

🧚 SPEC 🧚

the spec is shaped like this 👇

FUNCTION([ARGS])[(TEST)] [=> ...]

It's a list of predicates separated by "=>". Each predicate is a function signature (name plus arguments) sitting in a call stack, along with a test on that function's arguments 💜

Missing predicates are implicitly true, and so are missing tests 🫶 You only have to spell out the function arguments if your test actually uses them. And if the error injection function isn't listed as the first predicate, it gets added automatically, periodt ✨

Functions are listed in the reverse order they get called. So if a() calls b(), the spec is "b() => a()" 🔄

🔥 REQUIREMENTS 🔥

you'll need CONFIG_BPF, CONFIG_BPF_KPROBE_OVERRIDE, and bcc 💅

🌈 EXAMPLES 🌈

inject kmalloc -v 'SyS_mount()'

inject kmalloc -v 'mount_subtree() => btrfs_mount()'

inject -P 0.5 -c 100 alloc_page "should_fail_alloc_page(gfp_t gfp_mask, unsigned int order) (order == 1) => qlge_refill_bq()"

For more, run -h and check out tools/inject_example.txt 🧁

🍓 SOURCE 🍓

this is from bcc 🫶

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file. It has example usage, output, and commentary for this tool 📚

🌸 OS 🌸

Linux only, bestie 🐧

⭐ STABILITY ⭐

Unstable, it's still in development 🚧

👑 AUTHOR 👑

written by Howard McLauchlan 💜

---

okay that's the whole thing, bestie 💖 This page is from the USER COMMANDS section, dated 2018-03-16, and it's the inject(8) page 🎀✨