From 71f516782bb401fd3968fdfdb2d211f496cf73c1 Mon Sep 17 00:00:00 2001 From: Andrey Konovalov Date: Wed, 14 Jun 2017 17:03:53 +0200 Subject: docs: various improvements --- docs/usage.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) (limited to 'docs/usage.md') diff --git a/docs/usage.md b/docs/usage.md index b609ff0d4..93794a643 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,15 +1,36 @@ -## Running syzkaller +# How to use syzkaller + +## Running Start the `syz-manager` process as: ``` ./bin/syz-manager -config my.cfg ``` -The `-config` command line option gives the location of the configuration file [described above](#configuration). +The `syz-manager` process will wind up VMs and start fuzzing in them. +The `-config` command line option gives the location of the configuration file, which is [described here](configuration.md). +Found crashes, statistics and other information is exposed on the HTTP address specified in the manager config. + +At this point it's important to ensure that syzkaller is able to collect code coverage of the executed programs (unless you specified `"cover": false` in the config). +The `cover` counter on the web page should be non zero. + +## Crashes + +Once syzkaller detected a kernel crash in one of the VMs, it will automatically start the process of reproducing this crash (unless you specified `"reproduce": false` in the config). +By default it will use 4 VMs to reproduce the crash and then minimize the program that caused it. +This may stop the fuzzing, since all of the VMs might be busy reproducing detected crashes. + +The process of reproducing one crash may take from a few minutes up to an hour depending on whether the crash is easily reproducible or reproducible at all. +Since this process is not perfect, there's a way to try to manually reproduce the crash, as described [here](reproducing_crashes.md). + +If a reproducer is successfully found, it can be generated in one of the two forms: syzkaller program or C program. +Syzkaller always tries to generate a more user-friendly C reproducer, but sometimes fails for various reasons (for example slightly different timings). +In case syzkaller only generated a syzkaller program, there's [a way to execute them](reproducing_crashes.md) to reproduce and debug the crash manually. + +## Reporting bugs + +Check [here](linux_kernel_reporting_bugs.md) for the instructions on how to report Linux kernel bugs. -The `syz-manager` process will wind up QEMU virtual machines and start fuzzing in them. -Found crashes, statistics and other information is exposed on the HTTP address provided in manager config. +## Other -- [How to execute syzkaller programs](executing_syzkaller_programs.md) -- [How to reproduce crashes](reproducing_crashes.md) -- [How to connect several managers via Hub](connecting_several_managers.md) +[How to connect several managers via Hub](connecting_several_managers.md) -- cgit mrf-deployment