1 # How to set up syzkaller 2 3 Below are the generic instructions for how to set up syzkaller to fuzz the Linux kernel. 4 Instructions for a particular VM type or kernel arch can be found on these pages: 5 6 - [Setup: Ubuntu host, QEMU vm, x86-64 kernel](setup_ubuntu-host_qemu-vm_x86-64-kernel.md) 7 - [Setup: Ubuntu host, Odroid C2 board, arm64 kernel](setup_ubuntu-host_odroid-c2-board_arm64-kernel.md) 8 - [Setup: Linux host, QEMU vm, arm64 kernel](setup_linux-host_qemu-vm_arm64-kernel.md) 9 - [Setup: Linux host, QEMU vm, arm kernel](setup_linux-host_qemu-vm_arm-kernel.md) 10 - [Setup: Linux host, Android device, arm64 kernel](setup_linux-host_android-device_arm64-kernel.md) 11 - [Setup: Ubuntu host, Android device, arm32 kernel](setup_ubuntu-host_android-device_arm32-kernel.md) 12 - [Setup: Linux isolated host](setup_linux-host_isolated.md) 13 14 ## Install 15 16 The following components are needed to use syzkaller: 17 18 - C compiler with coverage support 19 - Linux kernel with coverage additions 20 - Virtual machine or a physical device 21 - syzkaller itself 22 23 Generic steps to set up syzkaller are described below. 24 25 If you encounter any troubles, check the [troubleshooting](/docs/troubleshooting.md) page. 26 27 ### C Compiler 28 29 Syzkaller is a coverage-guided fuzzer and therefore it needs the kernel to be built with coverage support, which requires a recent GCC version. 30 Coverage support was submitted to GCC in revision `231296`, released in GCC v6.0. 31 32 ### Linux Kernel 33 34 Besides coverage support in GCC, you also need support for it on the kernel side. 35 KCOV was committed upstream in Linux kernel version 4.6 and can be enabled by configuring the kernel with `CONFIG_KCOV=y`. 36 For older kernels you need to backport commit [kernel: add kcov code coverage](https://github.com/torvalds/linux/commit/5c9a8750a6409c63a0f01d51a9024861022f6593). 37 38 To enable more syzkaller features and improve bug detection abilities, it's recommended to use additional config options. 39 See [this page](kernel_configs.md) for details. 40 41 ### VM Setup 42 43 Syzkaller performs kernel fuzzing on slave virtual machines or physical devices. 44 These slave enviroments are referred to as VMs. 45 Out-of-the-box syzkaller supports QEMU, kvmtool and GCE virtual machines, Android devices and Odroid C2 boards. 46 47 These are the generic requirements for a syzkaller VM: 48 49 - The fuzzing processes communicate with the outside world, so the VM image needs to include 50 networking support. 51 - The program files for the fuzzer processes are transmitted into the VM using SSH, so the VM image 52 needs a running SSH server. 53 - The VM's SSH configuration should be set up to allow root access for the identity that is 54 included in the `syz-manager`'s configuration. In other words, you should be able to do `ssh -i 55 $SSHID -p $PORT root@localhost` without being prompted for a password (where `SSHID` is the SSH 56 identification file and `PORT` is the port that are specified in the `syz-manager` configuration 57 file). 58 - The kernel exports coverage information via a debugfs entry, so the VM image needs to mount 59 the debugfs filesystem at `/sys/kernel/debug`. 60 61 To use QEMU syzkaller VMs you have to install QEMU on your host system, see [QEMU docs](http://wiki.qemu.org/Manual) for details. 62 The [create-image.sh](/tools/create-image.sh) script can be used to create a suitable Linux image. 63 Detailed steps for setting up syzkaller with QEMU on a Linux host are avaialble for [x86-64](setup_ubuntu-host_qemu-vm_x86-64-kernel.md) and [arm64](setup_linux-host_qemu-vm_arm64-kernel.md) kernels. 64 65 For some details on fuzzing the kernel on an Android device check out [this page](setup_linux-host_android-device_arm64-kernel.md) and the explicit instructions for an Odroid C2 board are available [here](setup_ubuntu-host_odroid-c2-board_arm64-kernel.md). 66 67 ### Syzkaller 68 69 The syzkaller tools are written in [Go](https://golang.org), so a Go compiler (>= 1.8) is needed 70 to build them. 71 72 Go distribution can be downloaded from https://golang.org/dl/. 73 Unpack Go into a directory, say, `$HOME/go`. 74 Then, set `GOROOT=$HOME/go` env var. 75 Then, add Go binaries to `PATH`, `PATH=$HOME/go/bin:$PATH`. 76 Then, set `GOPATH` env var to some empty dir, say `GOPATH=$HOME/gopath`. 77 Then, run `go get -u -d github.com/google/syzkaller/...` to checkout syzkaller sources. 78 Then, `cd $GOPATH/src/github.com/google/syzkaller` and 79 build with `make`, which generates compiled binaries in the `bin/` folder. 80 Note: if you want to do cross-OS/arch testing, you need to specify `TARGETOS`, 81 `TARGETVMARCH` and `TARGETARCH` arguments to `make`. See the [Makefile](/Makefile) for details. 82
