github.com/google/syzkaller@v0.0.0-20251211124644-a066d2bc4b02/docs/linux/setup.md (about)

     1  # How to set up syzkaller
     2  
     3  Generic instructions on how to set up Linux kernel fuzzing with syzkaller are [below](setup.md#install).
     4  
     5  Instructions for a particular VM type or kernel architecture can be found on these pages:
     6  
     7  - [Setup: Ubuntu host, QEMU vm, x86-64 kernel](setup_ubuntu-host_qemu-vm_x86-64-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, QEMU vm, riscv64 kernel](setup_linux-host_qemu-vm_riscv64-kernel.md)
    11  - [Setup: Linux host, QEMU vm, s390x kernel](setup_linux-host_qemu-vm_s390x-kernel.md)
    12  - [Setup: Linux host, Android device, arm32/64 kernel](setup_linux-host_android-device_arm-kernel.md)
    13  - [Setup: Linux host, Android virtual device, x86-64 kernel](setup_linux-host_android-virtual-device_x86-64-kernel.md)
    14  - [Setup: Linux isolated host](setup_linux-host_isolated.md)
    15  - [Setup: Ubuntu host, VMware vm, x86-64 kernel](setup_ubuntu-host_vmware-vm_x86-64-kernel.md)
    16  - [Setup: Ubuntu host, VirtualBox vm, x86-64 kernel](setup_ubuntu-host_virtualbox-vm_x86-64-kernel.md)
    17  
    18  ## Install
    19  
    20  The following components are needed to use syzkaller:
    21  
    22   - Go compiler and syzkaller itself
    23   - C compiler with coverage support
    24   - Linux kernel with coverage additions
    25   - Virtual machine or a physical device
    26  
    27  If you encounter any troubles, check the [troubleshooting](/docs/troubleshooting.md) page.
    28  
    29  ### Go and syzkaller
    30  
    31  `syzkaller` is written in [Go](https://golang.org), and `Go 1.23+` toolchain is required for build.
    32  Generally we aim at supporting 2 latest releases of Go.
    33  The toolchain can be installed with:
    34  
    35  ```
    36  wget https://dl.google.com/go/go1.23.6.linux-amd64.tar.gz
    37  tar -xf go1.23.6.linux-amd64.tar.gz
    38  export GOROOT=`pwd`/go
    39  export PATH=$GOROOT/bin:$PATH
    40  ```
    41  
    42  See [Go: Download and install](https://golang.org/doc/install) for other options.
    43  
    44  To download and build `syzkaller`:
    45  
    46  ``` bash
    47  git clone https://github.com/google/syzkaller
    48  cd syzkaller
    49  make
    50  ```
    51  
    52  As the result compiled binaries should appear in the `bin/` dir.
    53  
    54  Note: if you want to do cross-OS/arch testing, you need to specify `TARGETOS`,
    55  `TARGETVMARCH` and `TARGETARCH` arguments to `make`. See the [Makefile](/Makefile) for details.
    56  
    57  ### Environment
    58  
    59  You might need to properly setup `binutils` if you're fuzzing in a cross-arch environment as described [here](coverage.md#binutils).
    60  
    61  ### C Compiler
    62  
    63  Syzkaller is a coverage-guided fuzzer and therefore it needs the kernel to be built with coverage support, which requires a recent GCC version.
    64  Coverage support was submitted to GCC, released in GCC 6.1.0 or later.
    65  Make sure that your GCC meets this requirement, or get a GCC that [syzbot](/docs/syzbot.md) uses [here](/docs/syzbot.md#crash-does-not-reproduce).
    66  
    67  ### Linux Kernel
    68  
    69  Besides coverage support in GCC, you also need support for it on the kernel side.
    70  KCOV was added into mainline Linux kernel in version 4.6 and is be enabled by `CONFIG_KCOV=y` kernel configuration option.
    71  For older kernels you need to at least backport commit [kernel: add kcov code coverage](https://github.com/torvalds/linux/commit/5c9a8750a6409c63a0f01d51a9024861022f6593).
    72  Besides that, it's recommended to backport all kernel patches that touch `kernel/kcov.c`.
    73  
    74  To enable more syzkaller features and improve bug detection abilities, it's recommended to use additional config options.
    75  See [this page](kernel_configs.md) for details.
    76  
    77  ### VM Setup
    78  
    79  Syzkaller performs kernel fuzzing on worker virtual machines or physical devices.
    80  These worker environments are referred to as VMs.
    81  Out-of-the-box syzkaller supports QEMU, kvmtool and GCE virtual machines, Android devices and Odroid C2 boards.
    82  
    83  These are the generic requirements for a syzkaller VM:
    84  
    85   - The fuzzing processes communicate with the outside world, so the VM image needs to include
    86     networking support.
    87   - The program files for the fuzzer processes are transmitted into the VM using SSH, so the VM image
    88     needs a running SSH server.
    89   - The VM's SSH configuration should be set up to allow root access for the identity that is
    90     included in the `syz-manager`'s configuration.  In other words, you should be able to do `ssh -i
    91     $SSHID -p $PORT root@localhost` without being prompted for a password (where `SSHID` is the SSH
    92     identification file and `PORT` is the port that are specified in the `syz-manager` configuration
    93     file).
    94   - The kernel exports coverage information via a debugfs entry, so the VM image needs to mount
    95     the debugfs filesystem at `/sys/kernel/debug`.
    96  
    97  To use QEMU syzkaller VMs you have to install QEMU on your host system, see [QEMU docs](http://wiki.qemu.org/Manual) for details.
    98  The [create-image.sh](/tools/create-image.sh) script can be used to create a suitable Linux image.
    99  
   100  See the links at the top of the document for instructions on setting up syzkaller for QEMU, Android and some other types of VMs.
   101  
   102  ### Troubleshooting
   103  
   104  * QEMU requires root for `-enable-kvm`.
   105  
   106      Solution: add your user to the `kvm` group (`sudo usermod -a -G kvm` and relogin).
   107  
   108  * QEMU crashes with:
   109  
   110      ```
   111      qemu-system-x86_64: error: failed to set MSR 0x48b to 0x159ff00000000
   112      qemu-system-x86_64: /build/qemu-EmNSP4/qemu-4.2/target/i386/kvm.c:2947: kvm_put_msrs: Assertion `ret == cpu->kvm_msr_buf->nmsrs' failed.
   113     ```
   114  
   115      Solution: remove `-cpu host,migratable=off` from the QEMU command line. The easiest way to do that is to set `qemu_args` to `-enable-kvm` in the `syz-manager` config file.