FM / doc

/usr/share/doc/bpfcc-tools/examples/doc/

/usr/share/doc/bpfcc-tools/examples/doc

Name	Size	Mode	Actions
lib/	-	0755	rm
argdist_example.txt	23029	0644	edit dl rm
bashreadline_example.txt	882	0644	edit dl rm
bindsnoop_example.txt	4530	0644	edit dl rm
biolatency_example.txt	24021	0644	edit dl rm
biolatpcts_example.txt	3040	0644	edit dl rm
biopattern_example.txt	1406	0644	edit dl rm
biosnoop_example.txt	3549	0644	edit dl rm
biotop_example.txt	9326	0644	edit dl rm
bitesize_example.txt	5100	0644	edit dl rm
bpflist_example.txt	2179	0644	edit dl rm
btrfsdist_example.txt	9545	0644	edit dl rm
btrfsslower_example.txt	6812	0644	edit dl rm
cachestat_example.txt	4012	0644	edit dl rm
cachetop_example.txt	3918	0644	edit dl rm
capable_example.txt	6655	0644	edit dl rm
cobjnew_example.txt	3044	0644	edit dl rm
compactsnoop_example.txt	10160	0644	edit dl rm
cpudist_example.txt	16876	0644	edit dl rm
cpuunclaimed_example.txt	15568	0644	edit dl rm
criticalstat_example.txt	4926	0644	edit dl rm
cthreads_example.txt	2132	0644	edit dl rm
dbslower_example.txt	3981	0644	edit dl rm
dbstat_example.txt	6656	0644	edit dl rm
dcsnoop_example.txt	4371	0644	edit dl rm
dcstat_example.txt	3343	0644	edit dl rm
deadlock_example.txt	16643	0644	edit dl rm
dirtop_example.txt	5097	0644	edit dl rm
drsnoop_example.txt	5120	0644	edit dl rm
execsnoop_example.txt	6795	0644	edit dl rm
exitsnoop_example.txt	6373	0644	edit dl rm
ext4dist_example.txt	8991	0644	edit dl rm
ext4slower_example.txt	11335	0644	edit dl rm
filegone_example.txt	743	0644	edit dl rm
filelife_example.txt	2092	0644	edit dl rm
fileslower_example.txt	5711	0644	edit dl rm
filetop_example.txt	6968	0644	edit dl rm
funccount_example.txt	13605	0644	edit dl rm
funcinterval_example.txt	15646	0644	edit dl rm
funclatency_example.txt	21485	0644	edit dl rm
funcslower_example.txt	6786	0644	edit dl rm
gethostlatency_example.txt	1317	0644	edit dl rm
hardirqs_example.txt	37936	0644	edit dl rm
inject_example.txt	6832	0644	edit dl rm
javacalls_example.txt	4000	0644	edit dl rm
javaflow_example.txt	6017	0644	edit dl rm
javagc_example.txt	3867	0644	edit dl rm
javaobjnew_example.txt	3044	0644	edit dl rm
javastat_example.txt	3052	0644	edit dl rm
javathreads_example.txt	2132	0644	edit dl rm
killsnoop_example.txt	1339	0644	edit dl rm
klockstat_example.txt	8536	0644	edit dl rm
kvmexit_example.txt	11909	0644	edit dl rm
llcstat_example.txt	3315	0644	edit dl rm
mdflush_example.txt	1780	0644	edit dl rm
memleak_example.txt	10263	0644	edit dl rm
mountsnoop_example.txt	1481	0644	edit dl rm
mysqld_qslower_example.txt	2351	0644	edit dl rm
netqtop_example.txt	12497	0644	edit dl rm
nfsdist_example.txt	8508	0644	edit dl rm
nfsslower_example.txt	7867	0644	edit dl rm
nodegc_example.txt	3867	0644	edit dl rm
nodestat_example.txt	3052	0644	edit dl rm
offcputime_example.txt	19662	0644	edit dl rm
offwaketime_example.txt	38258	0644	edit dl rm
oomkill_example.txt	1925	0644	edit dl rm
opensnoop_example.txt	10573	0644	edit dl rm
perlcalls_example.txt	4000	0644	edit dl rm
perlflow_example.txt	6017	0644	edit dl rm
perlstat_example.txt	3052	0644	edit dl rm
phpcalls_example.txt	4000	0644	edit dl rm
phpflow_example.txt	6017	0644	edit dl rm
phpstat_example.txt	3052	0644	edit dl rm
pidpersec_example.txt	677	0644	edit dl rm
ppchcalls_example.txt	7097	0644	edit dl rm
profile_example.txt	31826	0644	edit dl rm
pythoncalls_example.txt	4000	0644	edit dl rm
pythonflow_example.txt	6017	0644	edit dl rm
pythongc_example.txt	3867	0644	edit dl rm
pythonstat_example.txt	3052	0644	edit dl rm
rdmaucma_example.txt	1983	0644	edit dl rm
readahead_example.txt	3248	0644	edit dl rm
reset-trace_example.txt	9365	0644	edit dl rm
rubycalls_example.txt	4000	0644	edit dl rm
rubyflow_example.txt	6017	0644	edit dl rm
rubygc_example.txt	3867	0644	edit dl rm
rubyobjnew_example.txt	3044	0644	edit dl rm
rubystat_example.txt	3052	0644	edit dl rm
runqlat_example.txt	32051	0644	edit dl rm
runqlen_example.txt	12136	0644	edit dl rm
runqslower_example.txt	2184	0644	edit dl rm
shmsnoop_example.txt	2798	0644	edit dl rm
slabratetop_example.txt	5347	0644	edit dl rm
sofdsnoop_example.txt	3211	0644	edit dl rm
softirqs_example.txt	11286	0644	edit dl rm
solisten_example.txt	2355	0644	edit dl rm
sslsniff_example.txt	6902	0644	edit dl rm
stackcount_example.txt	21965	0644	edit dl rm
statsnoop_example.txt	3091	0644	edit dl rm
swapin.txt	2632	0644	edit dl rm
swapin_example.txt	1421	0644	edit dl rm
syncsnoop_example.txt	387	0644	edit dl rm
syscount_example.txt	6419	0644	edit dl rm
tclcalls_example.txt	4000	0644	edit dl rm
tclflow_example.txt	6017	0644	edit dl rm
tclobjnew_example.txt	3044	0644	edit dl rm
tclstat_example.txt	3052	0644	edit dl rm
tcpaccept_example.txt	2822	0644	edit dl rm
tcpcong_example.txt	34106	0644	edit dl rm
tcpconnect_example.txt	6420	0644	edit dl rm
tcpconnlat_example.txt	2616	0644	edit dl rm
tcpdrop_example.txt	2001	0644	edit dl rm
tcplife_example.txt	6995	0644	edit dl rm
tcpretrans_example.txt	3938	0644	edit dl rm
tcprtt_example.txt	10070	0644	edit dl rm
tcpstates_example.txt	2908	0644	edit dl rm
tcpsubnet_example.txt	5503	0644	edit dl rm
tcpsynbl_example.txt	1179	0644	edit dl rm
tcptop_example.txt	5890	0644	edit dl rm
tcptracer_example.txt	2029	0644	edit dl rm
threadsnoop_example.txt	1094	0644	edit dl rm
tplist_example.txt	4507	0644	edit dl rm
trace_example.txt	22136	0644	edit dl rm
ttysnoop_example.txt	3315	0644	edit dl rm
vfscount_example.txt	2221	0644	edit dl rm
vfsstat_example.txt	1696	0644	edit dl rm
virtiostat_example.txt	2678	0644	edit dl rm
wakeuptime_example.txt	34048	0644	edit dl rm
xfsdist_example.txt	6928	0644	edit dl rm
xfsslower_example.txt	7080	0644	edit dl rm
zfsdist_example.txt	9753	0644	edit dl rm
zfsslower_example.txt	7551	0644	edit dl rm

Edit: /usr/share/doc/bpfcc-tools/examples/doc/inject_example.txt (6832B)

Some examples for inject

inject guarantees the appropriate erroneous return of the specified injection
mode (kmalloc,bio,etc) given a call chain and an optional set of predicates. You
can also optionally print out the generated BPF program for
modification/debugging purposes.

As a simple example, let's say you wanted to fail all mounts. As of 4.17 we can
fail syscalls directly, so let's do that:

# ./inject.py kmalloc -v 'SyS_mount()'

The first argument indicates the mode (or what to fail). Appropriate headers are
specified, if necessary. The verbosity flag prints the generated program. Note
that some syscalls will be available as 'SyS_xyz' and some will be available as
'sys_xyz'. This is largely dependent on the number of arguments each syscall
takes.

Trying to mount various filesystems will fail and report an inability to
allocate memory, as expected.

Whenever a predicate is missing, an implicit "(true)" is inserted. The example
above can be explicitly written as:

# ./inject.py kmalloc -v '(true) => SyS_mount()(true)'

The "(true)" without an associated function is a predicate for the error
injection mechanism of the current mode. In the case of kmalloc, the predicate
would have access to the arguments of:

should_failslab(struct kmem_cache *s, gfp_t gfpflags)

Other modes work similarly.
"bio" has access to the arguments of:

should_fail_bio(struct bio *bio)

"alloc_page" has access to the arguments of:

should_fail_alloc_page(gfp_t gfp_mask, unsigned int order)

We also note that it's unnecessary to state the arguments of the function if you
have no intention to reference them in the associated predicate.

Now let's say we want to be a bit more specific; suppose you want to fail
kmalloc() from mount_subtree() when called from btrfs_mount(). This will fail
only btrfs mounts:

# ./inject.py kmalloc -v 'mount_subtree() => btrfs_mount()'

Attempting to mount btrfs filesystem during the execution of this command will
yield an error, but other filesystems will be fine.

Next, lets say we want to hit one of the BUG_ONs in fs/btrfs. As of 4.16-rc3,
there is a BUG_ON in btrfs_prepare_close_one_device() at fs/btrfs/volumes.c:1002

To hit this, we can use the following:

# ./inject.py kmalloc -v 'btrfs_alloc_device() => btrfs_close_devices()'

While the script was executing, I mounted and unmounted btrfs, causing a
segfault on umount(since that satisfied the call path indicated). A look at
dmesg will confirm that the erroneous return value injected by the script
tripped the BUG_ON, causing a segfault down the line.

In general, it's worth noting that the required specificity of the call chain is
dependent on how much granularity you need. The example above might have
performed as expected without the intermediate btrfs_alloc_device, but might
have also done something unexpected(an earlier kmalloc could have failed before
the one we were targeting).

For hot paths, the approach outlined above isn't enough. If a path is traversed
very often, we can distinguish distinct calls with function arguments. Let's say
we want to fail the dentry allocation of a file creatively named 'bananas'. We
can do the following:

# ./inject.py kmalloc -v 'd_alloc_parallel(struct dentry *parent, const struct
qstr *name)(STRCMP(name->name, 'bananas'))'

While this script is executing, any operation that would cause a dentry
allocation where the name is 'bananas' fails, as expected.

Here, since we're referencing a function argument in our predicate, we need to
provide the function signature up to the argument we're using.

To note, STRCMP is a workaround for some rewriter issues. It will take input of
the form (x->...->z, 'literal'), and generate some equivalent code that the
verifier is more friendly about. It's not horribly robust, but works for the
purposes of making string comparisons a bit easier.

Finally, we briefly demonstrate how to inject bio failures. The mechanism is
identical, so any information from above will apply.

Let's say we want to fail bio requests when the request is to some specific
sector. An example use case would be to fail superblock writes in btrfs. For
btrfs, we know that there must be a superblock at 65536 bytes, or sector 128.
This allows us to run the following:

# ./inject.py bio -v -I 'linux/blkdev.h'  '(({struct gendisk *d = bio->bi_disk;
struct disk_part_tbl *tbl = d->part_tbl; struct hd_struct **parts = (void *)tbl +
sizeof(struct disk_part_tbl); struct hd_struct **partp = parts + bio->bi_partno;
struct hd_struct *p = *partp; dev_t disk = p->__dev.devt; disk ==
MKDEV(254,16);}) && bio->bi_iter.bi_sector == 128)'

The predicate in the command above has two parts. The first is a compound
statement which shortens to "only if the system is btrfs", but is long due
to rewriter/verifier shenanigans. The major/minor information can be found
however; I used Python. The second part simply checks the starting
address of bi_iter. While executing, this script effectively fails superblock
writes to the superblock at sector 128 without affecting other filesystems.

As an extension to the above, one could easily fail all btrfs superblock writes
(we only fail the primary) by calculating the sector number of the mirrors and
amending the predicate accordingly.

Inject also provides a probability option; this allows you to fail the
path+predicates some percentage of the time. For example, let's say we want to
fail our mounts half the time:

# ./inject.py kmalloc -v -P 0.01 'SyS_mount()'

USAGE message:
usage: inject.py [-h] [-I header] [-P probability] [-v] [-c COUNT]
                 {kmalloc,bio,alloc_page} spec

Fail specified kernel functionality when call chain and predicates are met

positional arguments:
  {kmalloc,bio,alloc_page}
                        indicate which base kernel function to fail
  spec                  specify call chain

optional arguments:
  -h, --help            show this help message and exit
  -I header, --include header
                        additional header files to include in the BPF program
  -P probability, --probability probability
                        probability that this call chain will fail
  -v, --verbose         print BPF program
  -c COUNT, --count COUNT
                        Number of fails before bypassing the override

EXAMPLES:
# ./inject.py kmalloc -v 'SyS_mount()'
    Fails all calls to syscall mount
# ./inject.py kmalloc -v '(true) => SyS_mount()(true)'
    Explicit rewriting of above
# ./inject.py kmalloc -v 'mount_subtree() => btrfs_mount()'
    Fails btrfs mounts only
# ./inject.py kmalloc -v 'd_alloc_parallel(struct dentry *parent, const struct \
    qstr *name)(STRCMP(name->name, 'bananas'))'
    Fails dentry allocations of files named 'bananas'
# ./inject.py kmalloc -v -P 0.01 'SyS_mount()'
    Fails calls to syscall mount with 1% probability

cmd: