From 548b4a94a3e936aab2f8a519bb0e54b9ab4dc476 Mon Sep 17 00:00:00 2001
From: David Drysdale <drysdale@google.com>
Date: Thu, 18 Feb 2016 13:26:37 +0000
Subject: Update README for dropprivs, troubleshooting

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/README.md b/README.md
index dbcf7fa06..ad288b535 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,9 @@ This is all implemented in [this coverage patch](https://github.com/dvyukov/linu
 once the patch is applied, the kernel should be configured with `CONFIG_KCOV` plus `CONFIG_KASAN`
 or `CONFIG_KTSAN`.
 
+(Note that if the kernel under test does not include support for all namespaces, the `dropprivs`
+configuration value should be set to `false`.)
+
 ### QEMU Setup
 
 Syzkaller runs its fuzzer processes inside QEMU virtual machines, so a working QEMU system is needed
@@ -95,6 +98,9 @@ following keys in its top-level object:
    the virtual machine.
  - `cpu`: Number of CPUs to simulate in the VM (*not currently used*).
  - `mem`: Amount of memory (in MiB) for the VM; this is passed as the `-m` option to `qemu-system-x86_64`.
+ - `dropprivs` : Whether the executor program should try to use namespaces to drop privileges
+   before executing (requires a kernel built with `CONFIG_NAMESPACES`, `CONFIG_UTS_NS`,
+   `CONFIG_USER_NS`, `CONFIG_PID_NS` and `CONFIG_NET_NS`).
  - `enable_syscalls`: List of syscalls to test (optional).
  - `disable_syscalls`: List of system calls that should be treated as disabled (optional).
  - `suppressions`: List of regexps for known bugs.
@@ -151,4 +157,51 @@ open_mode = S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWO
 
 The description is contained in [sys/sys.txt](sys/sys.txt) file.
 
+## Troubleshooting
+
+Here are some things to check if there are problems running syzkaller.
+
+ - Check that QEMU can successfully boot the virtual machine.  For example,
+   if `IMAGE` is set to the VM's disk image (as per the `image` config value)
+   and `KERNEL` is set to the test kernel (as per the `kernel` config value)
+   then something like the following command should start the VM successfully:
+
+       ```qemu-system-x86_64 -hda $IMAGE -m 256 -net nic -net user,host=10.0.2.10,hostfwd=tcp::23505-:22 -enable-kvm -kernel $KERNEL -append root=/dev/sda```
+
+ - Check that inbound SSH to the running virtual machine works.  For example, with
+   a VM running and with `SSHKEY` set to the SSH identity (as per the `sshkey` config value) the
+   following command should connect:
+
+       ```ssh -i $SSHKEY -p 23505 root@localhost```
+
+ - Check that the `CONFIG_KCOV` option is available inside the VM:
+    - `ls /sys/kernel/debug       # Check debugfs mounted`
+    - `ls /sys/kernel/debug/kcov  # Check kcov enabled`
+    - Build the test program from `Documentation/kcov.txt` and run it inside the VM.
+
+ - Check that debug information (from the `CONFIG_DEBUG_INFO` option) is available
+    - Pass the hex output from the kcov test program to `addrline -a -i -f -e $VMLINUX` (where
+      `VMLINUX` is the vmlinux file, as per the `vmlinux` config value), to confirm
+      that symbols for the kernel are available.
+
+ - Use the `-v N` command line option to increase the amount of logging output, from both
+   the `syz-manager` top-level program and the `syz-fuzzer` instances (which go to the
+   output files in the `crashes` subdirectory of the working directory). Higher values of
+   N give more output.
+
+ - If logging indicates problems with the executor program (e.g. `executor failure`),
+   try manually running a short sequence of system calls:
+     - Build additional tools with `make all-tools`
+     - Copy `syz-executor` and `syz-execprog` into a running VM.
+     - In the VM run `./syz-execprog -executor ./syz-executor -debug sampleprog` where
+       sampleprog is a simple system call script (e.g. just containing `getpid()`).
+     - For example, if this reports that `clone` has failed, this probably indicates
+       that the test kernel does not include support for all of the required namespaces.
+       In this case, running the `syz-execprog` test with the `-nobody=0` option fixes the problem,
+       so the main configuration needs to be updated to set `dropprivs` to `false`.
+ 
+
+## Disclaimer
+
 This is not an official Google product.
+
-- 
cgit mrf-deployment