docs: update reproduction instructions

1. Get rid of executing_syzkaller_programs.md as it now mostly overlaps with reproducing_crashes.md. 2. Update the instructions on building the kernel with syzbot compilers. 3. Update the links throughout the documentation.
google · Nov 29, 2024 · 8f3b15c · 8f3b15c
1 parent b5d2be8
commit 8f3b15c
Show file tree

Hide file tree

Showing 9 changed files with 84 additions and 92 deletions.
diff --git a/docs/executing_syzkaller_programs.md b/docs/executing_syzkaller_programs.md
diff --git a/docs/internals.md b/docs/internals.md
@@ -63,7 +63,7 @@ This set may need to be extended if you are using a different kernel architectur
 
 `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](reproducing_crashes.md),
-or to `syz-execprog` tool for [manual localization](executing_syzkaller_programs.md).
+or to `syz-execprog` tool for [manual localization](reproducing_crashes.md#from-execution-logs).
 `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.

diff --git a/docs/linux/reporting_kernel_bugs.md b/docs/linux/reporting_kernel_bugs.md
@@ -42,7 +42,7 @@ If there are stalls or hangs, only report them if they are frequent enough or ha
 
 Overall, bugs without reproducers are way less likely to be triaged and fixed.
 If the bug is reproducible, include the reproducer (C source if possible, otherwise a syzkaller program) and the `.config` you used for your kernel.
-If the reproducer is available only in the form of a syzkaller program, please link [the instructions on how to execute them](/docs/executing_syzkaller_programs.md) in your report.
+If the reproducer is available only in the form of a syzkaller program, please link [the instructions on how to execute them](/docs/reproducing_crashes.md#using-a-c-reproducer) in your report.
 Check that the reproducer works if you run it manually.
 Syzkaller tries to simplify the reproducer, but the result might not be ideal.
 You can try to simplify or annotate the reproducer manually, that greatly helps kernel developers to figure out why the bug occurs.

diff --git a/docs/reproducing_crashes.md b/docs/reproducing_crashes.md
@@ -71,16 +71,65 @@ $ cd syzkaller
 $ ./tools/syz-env make
 ```
 
-Build the kernel and boot the VM as described above.
+Build the kernel and boot the VM as described in the section above.
 
-Download and run the reproducer:
+Download the reproducer:
 ```
-$ export SYZKALLER_PATH="~/syzkaller"
 $ wget -O 'repro.syz' 'https://syzkaller.appspot.com/x/repro.syz?x=137beac0580000'
+```
+
+Copy the reproducer and the syzkaller binaries to the test machine:
+```
+$ export SYZKALLER_PATH="~/syzkaller"
 $ scp -P 10022 -o UserKnownHostsFile=/dev/null  -o StrictHostKeyChecking=no -o IdentitiesOnly=yes $SYZKALLER_PATH/bin/linux_amd64/* ./repro.syz [email protected]:/root/
+```
+
+Now you can use the `syz-execprog` tool to actually execute the program.
+
+```
 $ ssh -p 10022 -o UserKnownHostsFile=/dev/null  -o StrictHostKeyChecking=no -o IdentitiesOnly=yes [email protected] './syz-execprog -enable=all -repeat=0 -procs=6 ./repro.syz'
 ```
 
+Several useful `syz-execprog` flags:
+```
+  -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`, all syscalls will be executed in the same thread.
+`-threaded=1` forces execution of each syscall in a separate thread, so that
+execution can proceed over blocking syscalls.
+
+Before 2021, `syz-execprog` also supported the following flag:
+```
+  -collide
+    	collide syscalls to provoke data races (default true)
+```
+`-collide=1` forced second round of execution of syscalls when pairs of syscalls
+are executed concurrently.
+
+Starting from the revision
+[fd8caa54](https://github.com/google/syzkaller/commit/fd8caa5462e64f37cb9eebd75ffca1737dde447d),
+the behavior is controlled [directly in syzlang](/docs/program_syntax.md#async).
+If you are running older reproducers, you might still need to set the `-collide=1` flag.
+
+
+If you are replaying a reproducer program that contains a header along the
+following lines:
+```
+# {Threaded:true Repeat:true RepeatTimes:0 Procs:8 Slowdown:1 Sandbox:none Leak:false NetInjection:true NetDevices:true NetReset:true Cgroups:true BinfmtMisc:true CloseFDs:true KCSAN:false DevlinkPCI:false USB:true VhciInjection:true Wifi:true IEEE802154:true Sysctl:true UseTmpDir:true HandleSegv:true Repro:false Trace:false LegacyOptions:{Collide:false Fault:false FaultCall:0 FaultNth:0}}
+```
+then you need to adjust `syz-execprog` flags based on the values in the
+header. Namely, `Threaded`/`Procs`/`Sandbox` directly relate to
+`-threaded`/`-procs`/`-sandbox` flags. If `Repeat` is set to `true`, add
+`-repeat=0` flag to `syz-execprog`.
+
 ## Using ktest
 
 [ktest](https://evilpiepirate.org/git/ktest.git/tree/README.md) is a collection

diff --git a/docs/syzbot.md b/docs/syzbot.md
@@ -300,28 +300,35 @@ reply with a `#syz fix: commit-title` so that syzbot can close the bug report.
 
 <div id="syzkaller-reproducers"/>
 
-## syzkaller reproducers
+## Running reproducers
+
+*Detailed instructions on running reproducers can be found [here](/docs/reproducing_crashes.md).*
 
 `syzbot` aims at providing stand-alone C reproducers for all reported bugs.
 However, sometimes it can't extract a reproducer at all, or can only extract a
 syzkaller reproducer. syzkaller reproducers are programs in a special syzkaller
 notation and they can be executed on the target system with a little bit more
-effort. See [this](/docs/executing_syzkaller_programs.md) for instructions.
+effort.
 
 A syskaller program can also give you an idea as to what syscalls with what
 arguments were executed (note that some calls can actually be executed in
 parallel).
 
-A syzkaller program can be converted to an almost equivalent C source using `syz-prog2c` utility. `syz-prog2c`
-has lots of flags in common with [syz-execprog](/docs/executing_syzkaller_programs.md),
-e.g. `-threaded` which controls if the syscalls are executed sequentially or in parallel.
+A syzkaller program can be converted to an almost equivalent C source using
+`syz-prog2c` utility. `syz-prog2c` has lots of flags in common with
+[syz-execprog](/docs/reproducing_crashes.md#from-execution-logs),
+e.g. `-threaded` which controls if the syscalls are executed sequentially or
+concurrently.
+
 An example invocation:
 
 ```
 syz-prog2c -prog repro.syz.txt -enable=all -threaded -repeat -procs=8 -sandbox=namespace -segv -tmpdir -waitrepeat
 ```
 
-However, note that if `syzbot` did not provide a C reproducer, it wasn't able to trigger the bug using the C program (though, it can be just because the bug is triggered by a subtle race condition).
+However, note that if `syzbot` did not provide a C reproducer, it wasn't able to
+trigger the bug using the C program (it might also be the case that the bug is
+triggered by a rare race condition).
 
 ## Downloadable assets
 
@@ -345,14 +352,23 @@ then the program needs to be built with `-m32` flag.
 If the reproducer exits quickly, try to run it several times, or in a loop.
 There can be some races involved.
 
-Latest compiler used by syzbot is contained in `gcr.io/syzkaller/syzbot:gcc-10.2.1` docker image.
-For in-tree kernel build in current directory it can be used as follows:
+Sometimes it might be important to build the kernel using the exact same
+compiler that was used by syzbot. Normally that information is included in every
+email report, e.g.:
+
+```
+compiler:       Debian clang version 15.0.6, GNU ld (GNU Binutils for Debian) 2.40
+```
+
+The latest compilers used by syzbot are contained in the
+`gcr.io/syzkaller/syzbot` docker image. For in-tree kernel build in current
+directory it can be used as follows:
 
 ```
-docker pull gcr.io/syzkaller/syzbot:gcc-10.2.1
+docker pull gcr.io/syzkaller/syzbot
 docker run -it --user $(id -u ${USER}):$(id -g ${USER}) \
 	--volume "$PWD:/syzkaller/pwd" --workdir /syzkaller/pwd \
-	gcr.io/syzkaller/syzbot:gcc-10.2.1
+	gcr.io/syzkaller/syzbot:latest
 make
 ```
 

diff --git a/docs/syzbot_assets.md b/docs/syzbot_assets.md
@@ -93,7 +93,7 @@ $ ssh -p 10022 -o UserKnownHostsFile=/dev/null  -o StrictHostKeyChecking=no -o I
 In some time, you'll see the same bug report in the VM's serial output.
 
 The commands above execute the `./syz-execprog -enable=all -repeat=0 -procs=6 ./repro.syz`
-command inside the VM. For more details see [this document](/docs/executing_syzkaller_programs.md).
+command inside the VM. More details can be found in [this document](/docs/reproducing_crashes.md).
 
 #### Use the `tools/syz-crush` tool
 

diff --git a/docs/translations/zh_CN/executing_syzkaller_programs.md b/docs/translations/zh_CN/executing_syzkaller_programs.md
@@ -1,6 +1,6 @@
 > [!WARNING]
 >
-> **请注意，这是社区驱动的官方 syzkaller 文档翻译。当前文档的最新版本（英文版）可在 [docs/executing_syzkaller_programs.md](/docs/executing_syzkaller_programs.md) 找到。**
+> **请注意，这是社区驱动的官方 syzkaller 文档翻译。当前文档的最新版本（英文版）可在 [docs/reproducing_crashes.md](/docs/reproducing_crashes.md) 找到。**
 
 # 运行 syzkaller 程序
 

diff --git a/docs/translations/zh_CN/internals.md b/docs/translations/zh_CN/internals.md
@@ -59,7 +59,7 @@ Syzkaller 是一种覆盖率导向的模糊测试器。有关覆盖率收集的
 如果使用不同的内核架构或看到以前未见过的内核错误消息，则可能需要扩展此正则表达式集合。
 
 `logN` 文件包含原始的 `syzkaller` 日志，包括内核控制台输出以及崩溃前执行的程序。
-这些日志可以提供给 `syz-repro` 工具进行[崩溃定位和最小化](/docs/reproducing_crashes.md)，或者提供给 `syz-execprog` 工具进行[手动定位](/docs/executing_syzkaller_programs.md)。
+这些日志可以提供给 `syz-repro` 工具进行[崩溃定位和最小化](/docs/reproducing_crashes.md)，或者提供给 `syz-execprog` 工具进行[手动定位](/docs/reproducing_crashes.md)。
 `reportN` 文件包含经过处理和符号化的内核崩溃报告（例如，KASAN 报告）。
 我们通常只需要这一对文件（如 `log0` 和 `report0`）中的一个，因为它们可能描述相同的内核错误。然而，`syzkaller` 最多保存100对这样的文件，以防崩溃难以重现或者您只是想通过查看一组崩溃报告来推断一些相似之处或不同之处的情况。
 

diff --git a/docs/translations/zh_CN/linux/reporting_kernel_bugs.md b/docs/translations/zh_CN/linux/reporting_kernel_bugs.md
@@ -10,7 +10,7 @@
 
 在提交报告前需要字斟句酌。如今，Linux 维护者被日益增加的 bug 报告所淹没，因此仅仅增加报告的提交量无助于解决内核错误本身。因此，您的报告越详细越具有可操作性，解决它的可能性就越大。请注意，人们更关心内核崩溃，如释放后使用（use-after-frees）或严重错误（panics）而非仅仅是 INFO 错误信息或者类似的信息，除非从报告中清楚地指出了到底在哪里出现了什么具体问题。如果有停顿（stalls）或挂起异常（hangs），只有在它们发生得足够频繁或能够定位错误原因时才报告它们。
 
-总体而言，没有重现用例 (reproducers) 的错误不太可能被分类和修复。如果内核错误是可复现的，请提交包括重现用例（如果可能的话，使用 C 源代码，否则使用 syzkaller 程序）和编译内核使用的 `.config` 文件。如果重现用例仅以 syzkaller 程序的形式提供，请在您的报告中给出链接说明[如何执行它们](/docs/executing_syzkaller_programs.md)。如果您手动运行，请检查重现用例是否正常工作。Syzkaller 试图简化复制器，但结果可能并不理想。您可以尝试手动简化或注释重现用例，这极大地帮助内核开发人员找出错误发生的原因。
+总体而言，没有重现用例 (reproducers) 的错误不太可能被分类和修复。如果内核错误是可复现的，请提交包括重现用例（如果可能的话，使用 C 源代码，否则使用 syzkaller 程序）和编译内核使用的 `.config` 文件。如果重现用例仅以 syzkaller 程序的形式提供，请在您的报告中给出链接说明[如何执行它们](/docs/reproducing_crashes.md)。如果您手动运行，请检查重现用例是否正常工作。Syzkaller 试图简化复制器，但结果可能并不理想。您可以尝试手动简化或注释重现用例，这极大地帮助内核开发人员找出错误发生的原因。
 
 如果您想进一步做出贡献，您可以尝试了解错误并尝试自行修复内核程序。如果您无法找到正确的修复方法，但对错误有一定的了解，也请在报告中添加您的想法和结论，这将为内核开发人员节省时间。