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