OLD | NEW |
(Empty) | |
| 1 ========================= |
| 2 Installation instructions |
| 3 ========================= |
| 4 |
| 5 This document provides basic installation instructions and discusses known |
| 6 issues for a variety of platforms. See README for the general instruction |
| 7 manual. |
| 8 |
| 9 1) Linux on x86 |
| 10 --------------- |
| 11 |
| 12 This platform is expected to work well. Compile the program with: |
| 13 |
| 14 $ make |
| 15 |
| 16 You can start using the fuzzer without installation, but it is also possible to |
| 17 install it with: |
| 18 |
| 19 # make install |
| 20 |
| 21 There are no special dependencies to speak of; you will need GNU make and a |
| 22 working compiler (gcc or clang). Some of the optional scripts bundled with the |
| 23 program may depend on bash, gdb, and similar basic tools. |
| 24 |
| 25 If you are using clang, please review llvm_mode/README.llvm; the LLVM |
| 26 integration mode can offer substantial performance gains compared to the |
| 27 traditional approach. |
| 28 |
| 29 You may have to change several settings to get optimal results (most notably, |
| 30 disable crash reporting utilities and switch to a different CPU governor), but |
| 31 afl-fuzz will guide you through that if necessary. |
| 32 |
| 33 2) OpenBSD, FreeBSD, NetBSD on x86 |
| 34 ---------------------------------- |
| 35 |
| 36 Similarly to Linux, these platforms are expected to work well and are |
| 37 regularly tested. Compile everything with GNU make: |
| 38 |
| 39 $ gmake |
| 40 |
| 41 Note that BSD make will *not* work; if you do not have gmake on your system, |
| 42 please install it first. As on Linux, you can use the fuzzer itself without |
| 43 installation, or install it with: |
| 44 |
| 45 # gmake install |
| 46 |
| 47 Keep in mind that if you are using csh as your shell, the syntax of some of the |
| 48 shell commands given in the README and other docs will be different. |
| 49 |
| 50 The llvm_mode requires a dynamically linked, fully-operational installation of |
| 51 clang. At least on FreeBSD, the clang binaries are static and do not include |
| 52 some of the essential tools, so if you want to make it work, you may need to |
| 53 follow the instructions in llvm_mode/README.llvm. |
| 54 |
| 55 Beyond that, everything should work as advertised. |
| 56 |
| 57 The QEMU mode is currently supported only on Linux. I think it's just a QEMU |
| 58 problem, I couldn't get a vanilla copy of user-mode emulation support working |
| 59 correctly on BSD at all. |
| 60 |
| 61 3) MacOS X on x86 |
| 62 ----------------- |
| 63 |
| 64 MacOS X should work, but there are some gotchas due to the idiosyncrasies of |
| 65 the platform. On top of this, I have limited release testing capabilities |
| 66 and depend mostly on user feedback. |
| 67 |
| 68 To build AFL, install Xcode and follow the general instructions for Linux. |
| 69 |
| 70 The Xcode 'gcc' tool is just a wrapper for clang, so be sure to use afl-clang |
| 71 to compile any instrumented binaries; afl-gcc will fail unless you have GCC |
| 72 installed from another source (in which case, please specify AFL_CC and |
| 73 AFL_CXX to point to the "real" GCC binaries). |
| 74 |
| 75 Only 64-bit compilation will work on the platform; porting the 32-bit |
| 76 instrumentation would require a fair amount of work due to the way OS X |
| 77 handles relocations, and today, virtually all MacOS X boxes are 64-bit. |
| 78 |
| 79 The crash reporting daemon that comes by default with MacOS X will cause |
| 80 problems with fuzzing. You need to turn it off by following the instructions |
| 81 provided here: http://goo.gl/CCcd5u |
| 82 |
| 83 The fork() semantics on OS X are a bit unusual compared to other unix systems |
| 84 and definitely don't look POSIX-compliant. This means two things: |
| 85 |
| 86 - Fuzzing will be probably slower than on Linux. In fact, some folks report |
| 87 considerable performance gains by running the jobs inside a Linux VM on |
| 88 MacOS X. |
| 89 |
| 90 - Some non-portable, platform-specific code may be incompatible with the |
| 91 AFL forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the |
| 92 environment before starting afl-fuzz. |
| 93 |
| 94 User emulation mode of QEMU does not appear to be supported on MacOS X, so |
| 95 black-box instrumentation mode (-Q) will not work. |
| 96 |
| 97 The llvm_mode requires a fully-operational installation of clang. The one that |
| 98 comes with Xcode is missing some of the essential headers and helper tools. |
| 99 See llvm_mode/README.llvm for advice on how to build the compiler from scratch. |
| 100 |
| 101 4) Linux or *BSD on non-x86 systems |
| 102 ----------------------------------- |
| 103 |
| 104 Standard build will fail on non-x86 systems, but you should be able to |
| 105 leverage two other options: |
| 106 |
| 107 - The LLVM mode (see llvm_mode/README.llvm), which does not rely on |
| 108 x86-specific assembly shims. It's fast and robust, but requires a |
| 109 complete installation of clang. |
| 110 |
| 111 - The QEMU mode (see qemu_mode/README.qemu), which can be also used for |
| 112 fuzzing cross-platform binaries. It's slower and more fragile, but |
| 113 can be used even when you don't have the source for the tested app. |
| 114 |
| 115 If you're not sure what you need, you need the LLVM mode. To get it, try: |
| 116 |
| 117 $ AFL_NO_X86=1 gmake && gmake -C llvm_mode |
| 118 |
| 119 ...and compile your target program with afl-clang-fast or afl-clang-fast++ |
| 120 instead of the traditional afl-gcc or afl-clang wrappers. |
| 121 |
| 122 5) Solaris on x86 |
| 123 ----------------- |
| 124 |
| 125 The fuzzer reportedly works on Solaris, but I have not tested this first-hand, |
| 126 and the user base is fairly small, so I don't have a lot of feedback. |
| 127 |
| 128 To get the ball rolling, you will need to use GNU make and GCC or clang. I'm |
| 129 being told that the stock version of GCC that comes with the platform does not |
| 130 work properly due to its reliance on a hardcoded location for 'as' (completely |
| 131 ignoring the -B parameter or $PATH). |
| 132 |
| 133 To fix this, you may want to build stock GCC from the source, like so: |
| 134 |
| 135 $ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \ |
| 136 --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr |
| 137 $ make |
| 138 $ sudo make install |
| 139 |
| 140 Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that |
| 141 ignores the -B flag and you will be back to square one. |
| 142 |
| 143 If you have system-wide crash reporting enabled, you may run into problems |
| 144 similar to the gotchas for Linux and MacOS X, but I have not verified this. |
| 145 More information about AppCrash can be found here: |
| 146 |
| 147 http://www.oracle.com/technetwork/server-storage/solaris10/app-crash-142906.ht
ml |
| 148 |
| 149 User emulation mode of QEMU is not available on Solaris, so black-box |
| 150 instrumentation mode (-Q) will not work. |
| 151 |
| 152 6) Everything else |
| 153 ------------------ |
| 154 |
| 155 You're on your own. On POSIX-compliant systems, you may be able to compile and |
| 156 run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code. |
| 157 |
| 158 The fuzzer will not run on Windows. It will also not work under Cygwin. It |
| 159 could be ported to the latter platform fairly easily, but it's a pretty bad |
| 160 idea, because Cygwin is extremely slow. It makes much more sense to use |
| 161 VirtualBox or so to run a hardware-accelerated Linux VM; it will run around |
| 162 20x faster or so. If you have a *really* compelling use case for Cygwin, let |
| 163 me know. |
| 164 |
| 165 Although Android on x86 should theoretically work, the stock kernel has SHM |
| 166 support compiled out, so you will need to address this issue first. It's |
| 167 possible that all you need is this: |
| 168 |
| 169 https://github.com/pelya/android-shmem |
OLD | NEW |