Home | History | Annotate | Download | only in docs 
      1 # Executing syzkaller programs
      2 
      3 This page describes how to execute existing syzkaller programs for the purpose
      4 of bug reproduction. This way you can replay a single program or a whole
      5 execution log with several programs.
      6 
      7 1. Setup Go toolchain (if you don't yet have it, you need version 1.9 or higher):
      8 Download latest Go distribution from (https://golang.org/dl/). Unpack it to `$HOME/go1.9`.
      9 ``` bash
     10 $ export GOROOT=$HOME/go1.9
     11 $ export GOPATH=$HOME/gopath
     12 ```
     13 
     14 2. Download syzkaller sources:
     15 ``` bash
     16 $ go get -u -d github.com/google/syzkaller/...
     17 ```
     18 
     19 3. Build necessary syzkaller binaries:
     20 ``` bash
     21 $ cd $GOPATH/src/github.com/google/syzkaller
     22 $ make
     23 ```
     24 
     25 4. Copy binaries and the program to test machine (substitue target `linux_amd64`
     26 as necessary):
     27 ``` bash
     28 $ scp bin/linux_amd64/syz-execprog bin/linux_amd64/syz-executor program test@machine
     29 ```
     30 
     31 5. Run the program on the test machine:
     32 ``` bash
     33 $ ./syz-execprog -cover=0 -repeat=0 -procs=16 program
     34 ```
     35 
     36 Several useful `syz-execprog` flags:
     37 ```
     38   -collide
     39     	collide syscalls to provoke data races (default true)
     40   -procs int
     41     	number of parallel processes to execute programs (default 1)
     42   -repeat int
     43     	repeat execution that many times (0 for infinite loop) (default 1)
     44   -sandbox string
     45     	sandbox for fuzzing (none/setuid/namespace) (default "setuid")
     46   -threaded
     47     	use threaded mode in executor (default true)
     48 ```
     49 
     50 If you pass `-threaded=0 -collide=0`, programs will be executed as a simple single-threaded sequence of syscalls. `-threaded=1` forces execution of each syscall in a separate thread, so that execution can proceed over blocking syscalls. `-collide=0` forces second round of execution of syscalls when pairs of syscalls are executed concurrently.
     51 
     52 If you are replaying a reproducer program that contains a header along the following lines:
     53 ```
     54 #{Threaded:true Collide:true Repeat:true Procs:8 Sandbox:namespace Fault:false FaultCall:-1 FaultNth:0 EnableTun:true UseTmpDir:true HandleSegv:true WaitRepeat:true Debug:false Repro:false}
     55 ```
     56 then you need to adjust `syz-execprog` flags based on the values in the header. Namely, `Threaded`/`Collide`/`Procs`/`Sandbox` directly relate to `-threaded`/`-collide`/`-procs`/`-sandbox` flags. If `Repeat` is set to `true`, add `-repeat=0` flag to `syz-execprog`.
     57