=======================
Environmental variables
=======================

  (See README for the general instruction manual)

Several components of American Fuzzy Lop make use of environmental variables
to implement features that may be (rarely) useful for power users or may come
handy in scripting environments.

1) Settings for afl-gcc, afl-clang, and afl-as
----------------------------------------------

  - Setting AFL_QUIET will prevent afl-cc and afl-as banners from being
    displayed during compilation, in case you find them distracting.

  - Setting AFL_HARDEN automatically adds code hardening options when invoking
    the downstream compiler. This currently includes -D_FORTIFY_SOURCE=2 and
    -fstack-protector-all. The option is useful for catching non-crashing
    memory bugs at the expense of a very slight (sub-5%) performance loss.

  - By default, the wrapper appends -O3 to optimize builds. In the exceedingly
    unlikely case this causes problems, set AFL_DONT_OPTIMIZE.

  - Setting AFL_USE_ASAN automatically enables ASAN, provided that your
    compiler supports that. Note that fuzzing with ASAN is problematic - see
    notes_for_asan.txt.

  - Setting AFL_USE_MSAN has a similar effect, but enables MSAN. Note that ASAN
    and MSAN can't be used at the same time. The caveats for MSAN are similar
    to the situation with ASAN.

  - Setting AFL_CC and AFL_CXX lets you use alternate downstream compilers,
    rather than the default 'clang' or 'gcc' binary in your $PATH.

  - Setting AFL_AS has a similar effect, but is used for selecting the
    path for the downstream GNU assembler invoked when afl-as is done.

  - AFL_PATH can be used to point to an alternate location of afl-as.

    One possible use of this is experimental/clang_asm_normalize/, which lets
    you instrument hand-written assembly when compiling clang code by plugging
    a normalizer into the chain. (There is no equivalent feature for GCC.)

  - Setting AFL_INST_RATIO to a percentage between 0 and 100% controls the
    probability of instrumenting every branch. This is (very rarely) useful
    when dealing with exceptionally complex programs that saturate the output
    bitmap. 

    (If this ever happens, afl-fuzz will warn you ahead of the time by
    displaying the "bitmap density" field in fiery red.)

  - TMPDIR is used by afl-as for temporary files; if this variable is not set,
    the tool defaults to /tmp.

  - Setting AFL_KEEP_ASSEMBLY prevents afl-as from deleting instrumented
    assembly files. Useful for troubleshooting problems or understanding how
    the tool works. To get them in a predictable place, try something like:

    mkdir assembly_here
    TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all

2) Settings for afl-showmap
---------------------------

  - Setting AFL_QUIET inhibits the banner and other non-essential messages
    from the tool.

  - Setting AFL_SINK_OUTPUT redirects all output from the tested program to
    /dev/null, so that all you see is a list of tuples recorded by the
    instrumentation. Very useful for test case de-duplication scripts.

  - Setting AFL_EDGES_ONLY makes the tool hide the edge hit count information.

3) Settings for afl-fuzz
------------------------

  - Setting AFL_SKIP_CHECKS skips the checks to detect instrumented binaries
    and shell scripts. This is useful mostly if you develop your own
    instrumentation (e.g., for interpreted languages or binary-only code).

  - Setting AFL_SKIP_CPUFREQ skips the check for CPU scaling policy. This is
    useful if you can't change the defaults and are OK with some performance
    loss.

  - Setting AFL_NO_FORKSRV disables the forkserver optimization, reverting to
    fork + execve() call for every tested input. This is useful mostly when
    working with unruly libraries that create threads or do other crazy
    things when initializing.

    Note that this setting inhibits some of the user-friendly diagnostics
    normally done when starting up the forkserver.

  - By default, LD_BIND_NOW is set to 1 to speed up fuzzing, but you can,
    theoretically, override it. I don't think there's any reason to.

  - By default, ASAN_OPTIONS are set to:

    abort_on_error=1
    detect_leaks=0
    allocator_may_return_null=1

    If you want to set your own options, be sure to include abort_on_error=1 -
    otherwise, the fuzzer will not be able to detect crashes in the tested
    app.

  - In the same vein, by default, MSAN_OPTIONS are set to:

    exit_code=86
    msan_track_origins=0

    Be sure to include the first one when customizing anything.
