Roll src/third_party/afl/src/ 2.14b..2.30b (16 versions).

third_party/afl/src/docs/parallel_fuzzing.txt

 =========================
 Tips for parallel fuzzing
 =========================
 
   This document talks about synchronizing afl-fuzz jobs on a single machine
   or across a fleet of systems. See README for the general instruction manual.
 
 1) Introduction
 ---------------
 
@@ skipping 33 matching lines @@
 $ ./afl-fuzz -i testcase_dir -o sync_dir -S fuzzer03 [...other stuff...]
 
 Each fuzzer will keep its state in a separate subdirectory, like so:
 
   /path/to/sync_dir/fuzzer01/
 
 Each instance will also periodically rescan the top-level sync directory
 for any test cases found by other fuzzers - and will incorporate them into
 its own fuzzing when they are deemed interesting enough.
 
-The only difference between the -M and -S modes is that the master instance
-will still perform deterministic checks; while the secondary instances will
+The difference between the -M and -S modes is that the master instance will
+still perform deterministic checks; while the secondary instances will
 proceed straight to random tweaks. If you don't want to do deterministic
 fuzzing at all, it's OK to run all instances with -S. With very slow or complex
 targets, or when running heavily parallelized jobs, this is usually a good plan.
 
-You can monitor the progress of your jobs from the command line with the
+Note that running multiple -M instances is wasteful, although there is an
+experimental support for parallelizing the deterministic checks. To leverage
+that, you need to create -M instances like so:
+
+$ ./afl-fuzz -i testcase_dir -o sync_dir -M masterA:1/3 [...]
+$ ./afl-fuzz -i testcase_dir -o sync_dir -M masterB:2/3 [...]
+$ ./afl-fuzz -i testcase_dir -o sync_dir -M masterC:3/3 [...]
+
+...where the first value after ':' is the sequential ID of a particular master
+instance (starting at 1), and the second value is the total number of fuzzers to
+distribute the deterministic fuzzing across. Note that if you boot up fewer
+fuzzers than indicated by the second number passed to -M, you may end up with
+poor coverage.
+
+You can also monitor the progress of your jobs from the command line with the
 provided afl-whatsup tool. When the instances are no longer finding new paths,
 it's probably time to stop.
 
 WARNING: Exercise caution when explicitly specifying the -f option. Each fuzzer
 must use a separate temporary file; otherwise, things will go south. One safe
 example may be:
 
 $ ./afl-fuzz [...] -S fuzzer10 -f file10.txt ./fuzzed/binary @@
 $ ./afl-fuzz [...] -S fuzzer11 -f file11.txt ./fuzzed/binary @@
 $ ./afl-fuzz [...] -S fuzzer12 -f file12.txt ./fuzzed/binary @@
@@ skipping 122 matching lines @@
   - Having some of the fuzzers invoke the binary in different ways.
     For example, 'djpeg' supports several DCT modes, configurable with
     a command-line flag, while 'dwebp' supports incremental and one-shot
     decoding. In some scenarios, going after multiple distinct modes and then
     pooling test cases will improve coverage.
 
   - Much less convincingly, running the synchronized fuzzers with different
     starting test cases (e.g., progressive and standard JPEG) or dictionaries.
     The synchronization mechanism ensures that the test sets will get fairly
     homogeneous over time, but it introduces some initial variability.