Merge pull request #1676 from hMcLauchlan/inject-4.17

Add features/docs for inject (4.17)

docs/reference_guide.md

@@ -23,6 +23,7 @@ This guide is incomplete. If something feels missing, check the bcc and kernel s
         - [6. bpf_get_current_comm()](#6-bpf_get_current_comm)
         - [7. bpf_get_current_task()](#7-bpf_get_current_task)
         - [8. bpf_log2l()](#8-bpflog2l)
+        - [9. bpf_get_prandom_u32()](#9-bpf_get_prandom_u32)
     - [Debugging](#debugging)
         - [1. bpf_override_return()](#1-bpf_override_return)
     - [Output](#output)
@@ -352,6 +353,16 @@ Examples in situ:
 [search /examples](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Aexamples&type=Code),
 [search /tools](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Atools&type=Code)
 
+### 9. bpf_get_prandom_u32()
+
+Syntax: ```u32 bpf_get_prandom_u32()```
+
+Returns a pseudo-random u32.
+
+Example in situ:
+[search /examples](https://github.com/iovisor/bcc/search?q=bpf_get_prandom_u32+path%3Aexamples&type=Code),
+[search /tools](https://github.com/iovisor/bcc/search?q=bpf_get_prandom_u32+path%3Atools&type=Code)
+
 ## Debugging
 
 ### 1. bpf_override_return()

man/man8/inject.8

@@ -3,7 +3,7 @@
 inject \- injects appropriate error into function if input call chain and
 predicates are satisfied. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B trace -h [-I header] [-v]
+.B inject -h [-I header] [-P probability] [-v] mode spec
 .SH DESCRIPTION
 inject injects errors into specified kernel functionality when a given call
 chain and associated predicates are satsified.
@@ -13,13 +13,6 @@ kernel. You should know what you're doing if you're using this tool.
 
 This makes use of a Linux 4.16 feature (bpf_override_return())
 
-Additionally, use of the kmalloc failure mode is only possible with 
-
-	commit f7174d08a5fc ("mm: make should_failslab always available for
-	fault injection")
-
-which is in mm-tree but not yet in mainline (as of 4.16-rc5).
-
 Since this uses BPF, only the root user can use this tool.
 .SH REQUIREMENTS
 CONFIG_BPF, CONFIG_BPF_KPROBE_OVERRIDE, bcc
@@ -33,6 +26,9 @@ Display the generated BPF program, for debugging or modification.
 .TP
 \-I header
 Necessary headers to be included.
+.TP
+\-P probability
+Optional probability of failure, default 1.
 .SH EXAMPLES
 Please see inject_example.txt
 .SH SOURCE

tools/inject.py

@@ -22,12 +22,10 @@
 # Note: presently there are a few hacks to get around various rewriter/verifier
 # issues.
 #
-# Note: this tool requires(as of v4.16-rc5):
-# - commit f7174d08a5fc ("mm: make should_failslab always available for fault
-# injection")
+# Note: this tool requires:
 # - CONFIG_BPF_KPROBE_OVERRIDE
 #
-# USAGE: inject [-h] [-I header] [-v]
+# USAGE: inject [-h] [-I header] [-P probability] [-v] mode spec
 #
 # Copyright (c) 2018 Facebook, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
@@ -45,8 +43,9 @@ class Probe:
     }
 
     @classmethod
-    def configure(cls, mode):
+    def configure(cls, mode, probability):
         cls.mode = mode
+        cls.probability = probability
 
     def __init__(self, func, preds, length, entry):
         # length of call chain
@@ -68,15 +67,25 @@ class Probe:
         if not chk:
             return ""
 
+        if Probe.probability == 1:
+            early_pred = "false"
+        else:
+            early_pred = "bpf_get_prandom_u32() > %s" % str(int((1<<32)*Probe.probability))
         # init the map
         # dont do an early exit here so the singular case works automatically
+        # have an early exit for probability option
         enter = """
+        /*
+         * Early exit for probability case
+         */
+        if (%s)
+               return 0;
         /*
          * Top level function init map
          */
         struct pid_struct p_struct = {0, 0};
         m.insert(&pid, &p_struct);
-        """
+        """ % early_pred
 
         # kill the entry
         exit = """
@@ -221,9 +230,9 @@ class Probe:
         if (p->conds_met == %s && %s)
                 bpf_override_return(ctx, %s);
         return 0;
-}""" % (self.prep, self.length, pred, self._get_err(), self.length - 1, pred,
-            self._get_err())
-        return text
+}"""
+        return text % (self.prep, self.length, pred, self._get_err(),
+                    self.length - 1, pred, self._get_err())
 
     # presently parses and replaces STRCMP
     # STRCMP exists because string comparison is inconvenient and somewhat buggy
@@ -302,6 +311,9 @@ class Tool:
         parser.add_argument("-I", "--include", action="append",
                 metavar="header",
                 help="additional header files to include in the BPF program")
+        parser.add_argument("-P", "--probability", default=1,
+                metavar="probability", type=float,
+                help="probability that this call chain will fail")
         parser.add_argument("-v", "--verbose", action="store_true",
             help="print BPF program")
         self.args = parser.parse_args()
@@ -315,7 +327,7 @@ class Tool:
     # create_probes and associated stuff
     def _create_probes(self):
         self._parse_spec()
-        Probe.configure(self.args.mode)
+        Probe.configure(self.args.mode, self.args.probability)
         # self, func, preds, total, entry
 
         # create all the pair probes
@@ -425,8 +437,7 @@ struct pid_struct {
 
     def _generate_program(self):
         # leave out auto includes for now
-
-        self.program += "#include <linux/mm.h>\n"
+        self.program += '#include <linux/mm.h>\n'
         for include in (self.args.include or []):
             self.program += "#include <%s>\n" % include
 

tools/inject_example.txt

@@ -5,14 +5,16 @@ 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. While we cannot
-fail the mount() syscall directly (a patch is in the works), we can easily
-fail do_mount() calls like so:
+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 'do_mount()'
+# ./inject.py kmalloc -v 'SyS_mount()'
 
 The first argument indicates the mode (or what to fail). Appropriate headers are
-specified. The verbosity flag prints the generated program.
+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.
@@ -20,7 +22,7 @@ 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) => do_mount()(true)'
+# ./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
@@ -106,9 +108,14 @@ 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.
 
-USAGE message:
+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: inject.py [-h] [-I header] [-v] mode spec
+USAGE message:
+usage: inject.py [-h] [-I header] [-P probability] [-v] mode spec
 
 Fail specified kernel functionality when call chain and predicates are met
 
@@ -120,5 +127,6 @@ 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
-