From 63c9dd365666c35a0c10444e56367c2d13e15562 Mon Sep 17 00:00:00 2001
From: Andrei Vagin <avagin@google.com>
Date: Thu, 4 Feb 2021 10:39:04 -0800
Subject: [PATCH] images: Rework syzkaller documentation.

PiperOrigin-RevId: 355660221
---
 images/syzkaller/Dockerfile |  2 ++
 images/syzkaller/README.md  | 55 +++++++++++++++++++++++++++++--------
 2 files changed, 46 insertions(+), 11 deletions(-)

diff --git a/images/syzkaller/Dockerfile b/images/syzkaller/Dockerfile
index df6680f40..9a85ae345 100644
--- a/images/syzkaller/Dockerfile
+++ b/images/syzkaller/Dockerfile
@@ -1,5 +1,7 @@
 FROM gcr.io/syzkaller/env
 
+# This image is mostly for investigating syzkaller crashes, so let's install
+# developer tools.
 RUN apt update && apt install -y git vim strace gdb procps
 
 WORKDIR  /syzkaller/gopath/src/github.com/google/syzkaller
diff --git a/images/syzkaller/README.md b/images/syzkaller/README.md
index 1eac474f3..47e309422 100644
--- a/images/syzkaller/README.md
+++ b/images/syzkaller/README.md
@@ -5,21 +5,54 @@ syzkaller is an unsupervised coverage-guided kernel fuzzer.
 
 # How to run syzkaller.
 
-*   Build the syzkaller docker image `make load-syzkaller`
-*   Build runsc and place it in /tmp/syzkaller. `make RUNTIME_DIR=/tmp/syzkaller
-    refresh`
-*   Copy the syzkaller config in /tmp/syzkaller `cp
-    images/syzkaller/default-gvisor-config.cfg /tmp/syzkaller/syzkaller.cfg`
-*   Run syzkaller `docker run --privileged -it --rm -v
-    /tmp/syzkaller:/tmp/syzkaller gvisor.dev/images/syzkaller:latest`
+First, we need to load a syzkaller docker image:
+
+```bash
+make load-syzkaller
+```
+
+or we can rebuild it to use an up-to-date version of the master branch:
+
+```bash
+make rebuild-syzkaller
+```
+
+Then we need to create a directory with all artifacts that we will need to run a
+syzkaller. Then we will bind-mount this directory to a docker container.
+
+We need to build runsc and place it on the artifact directory:
+
+```bash
+make RUNTIME_DIR=/tmp/syzkaller refresh
+```
+
+The next step is to create a syzkaller config. We can copy the default one and
+customize it:
+
+```bash
+cp images/syzkaller/default-gvisor-config.cfg /tmp/syzkaller/syzkaller.cfg
+```
+
+Now we can start syzkaller in a docker container:
+
+```bash
+docker run --privileged -it --rm \
+    -v /tmp/syzkaller:/tmp/syzkaller \
+    gvisor.dev/images/syzkaller:latest
+```
+
+All logs will be in /tmp/syzkaller/workdir.
 
 # How to run a syz repro.
 
-*   Repeate all steps except the last one from the previous section.
+We need to repeat all preparation steps from the previous section and save a
+syzkaller repro in /tmp/syzkaller/repro.
 
-*   Save a syzkaller repro in /tmp/syzkaller/repro
+Now we can run syz-repro to reproduce a crash:
 
-*   Run syz-repro `docker run --privileged -it --rm -v
+```bash
+docker run --privileged -it --rm -v
     /tmp/syzkaller:/tmp/syzkaller --entrypoint=""
     gvisor.dev/images/syzkaller:latest ./bin/syz-repro -config
-    /tmp/syzkaller/syzkaller.cfg /tmp/syzkaller/repro`
+    /tmp/syzkaller/syzkaller.cfg /tmp/syzkaller/repro
+```