docs: move executing syzkaller page from wiki

2 files changed, 48 insertions, 1 deletions

diff --git a/README.md b/README.md
index 1210be9e6..e20d51a6c 100644
--- a/README.md
+++ b/README.md
@@ -181,7 +181,7 @@ When `syzkaller` finds a crasher, it saves information about it into `workdir/cr
 
 Descriptions are extracted using a set of [regular expressions](report/report.go#L33). This set may need to be extended if you are using a different kernel architecture, or are just seeing a previously unseen kernel error messages.
 
-`logN` files contain raw `syzkaller` logs and include kernel console output as well as programs executed before the crash. These logs can be fed to `syz-repro` tool for [crash location and minimization](https://github.com/google/syzkaller/wiki/Tools:-execprog,-prog2c,-repro), or to `syz-execprog` tool for [manual localization](https://github.com/google/syzkaller/wiki/How-to-execute-syzkaller-programs). `reportN` files contain post-processed and symbolized kernel crash reports (e.g. a KASAN report). Normally you need just 1 pair of these files (i.e. `log0` and `report0`), because they all presumably describe the same kernel bug. However, `syzkaller` saves up to 100 of them for the case when the crash is poorly reproducible, or if you just want to look at a set of crash reports to infer some similarities or differences.
+`logN` files contain raw `syzkaller` logs and include kernel console output as well as programs executed before the crash. These logs can be fed to `syz-repro` tool for [crash location and minimization](https://github.com/google/syzkaller/wiki/Tools:-execprog,-prog2c,-repro), or to `syz-execprog` tool for [manual localization](docs/executing_syzkaller_programs.md). `reportN` files contain post-processed and symbolized kernel crash reports (e.g. a KASAN report). Normally you need just 1 pair of these files (i.e. `log0` and `report0`), because they all presumably describe the same kernel bug. However, `syzkaller` saves up to 100 of them for the case when the crash is poorly reproducible, or if you just want to look at a set of crash reports to infer some similarities or differences.
 
 There are 3 special types of crashes:
  - `no output from test machine`: the test machine produces no output whatsoever
diff --git a/docs/executing_syzkaller_programs.md b/docs/executing_syzkaller_programs.md
new file mode 100644
index 000000000..bd1570c0e
--- /dev/null
+++ b/docs/executing_syzkaller_programs.md
@@ -0,0 +1,47 @@
+# Executing syzkaller programs
+
+This page describes how to execute existing syzkaller programs for the purpose of bug reproduction. This way you can replay a single program or a whole execution log with several programs.
+
+1. Setup Go toolchain (if you don't yet have it, you need version 1.8 or higher):
+Download latest Go distribution from (https://golang.org/dl/). Unpack it to `$HOME/go1.8`.
+``` bash
+$ export GOROOT=$HOME/go1.8
+$ export GOPATH=$HOME/gopath
+```
+
+2. Download syzkaller sources:
+``` bash
+$ go get -u -d github.com/google/syzkaller/...
+```
+
+3. Build necessary syzkaller binaries:
+``` bash
+$ cd $GOPATH/src/github.com/google/syzkaller
+$ make
+```
+
+4. Copy binaries and the program to test machine:
+``` bash
+$ scp bin/syz-execprog bin/syz-executor program test@machine
+```
+
+5. Run the program on the test machine:
+``` bash
+$ ./syz-execprog -executor ./syz-executor -cover=0 -repeat=0 -procs=16 program
+```
+
+Several useful `syz-execprog` flags:
+```
+  -collide
+    	collide syscalls to provoke data races (default true)
+  -procs int
+    	number of parallel processes to execute programs (default 1)
+  -repeat int
+    	repeat execution that many times (0 for infinite loop) (default 1)
+  -sandbox string
+    	sandbox for fuzzing (none/setuid/namespace) (default "setuid")
+  -threaded
+    	use threaded mode in executor (default true)
+```
+
+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.