From e503f048b0f40379900055c31da154292d105791 Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Tue, 21 May 2019 11:47:51 +0200 Subject: [PATCH] docs: don't duplicate manager config parameters Currently we have them duplicated in docs/configuration.md and the actual source in pkg/mgrconfig/config.go. Documentation is missing in one place or another, some is outdated, some is phrased slightly differently. Move all docs to pkg/mgrconfig/config.go and reference it from docs/configuration.md instead. --- docs/configuration.md | 47 +----------- pkg/mgrconfig/config.go | 99 +++++++++++++++++++++++++ pkg/mgrconfig/{mgrconfig.go => load.go} | 79 -------------------- vm/qemu/qemu.go | 16 ++-- 4 files changed, 113 insertions(+), 128 deletions(-) create mode 100644 pkg/mgrconfig/config.go rename pkg/mgrconfig/{mgrconfig.go => load.go} (65%) diff --git a/docs/configuration.md b/docs/configuration.md index bb793a15..7e4dbc30 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,45 +1,6 @@ # Configuration -The operation of the syzkaller `syz-manager` process is governed by a configuration file, passed at -invocation time with the `-config` option. This configuration can be based on the -[example](/pkg/mgrconfig/testdata/qemu.cfg); the file is in JSON format with the -following keys in its top-level object: - - - `http`: URL that will display information about the running `syz-manager` process. - - `email_addrs`: Optional list of email addresses to receive notifications when bugs are encountered for the first time. - Mailx is the only supported mailer. Please set it up prior to using this function. - - `workdir`: Location of a working directory for the `syz-manager` process. Outputs here include: - - `/crashes/*`: crash output files (see [Crash Reports](#crash-reports)) - - `/corpus.db`: corpus with interesting programs - - `/instance-x`: per VM instance temporary files - - `syzkaller`: Location of the `syzkaller` checkout, `syz-manager` will look - for binaries in `bin` subdir (does not have to be `syzkaller` checkout as - long as it preserves `bin` dir structure) - - `kernel_obj`: Directory with object files (e.g. `vmlinux` for linux) - (used for report symbolization and coverage reports, optional). - - `procs`: Number of parallel test processes in each VM (4 or 8 would be a reasonable number). - - `image`: Location of the disk image file for the QEMU instance; a copy of this file is passed as the - `-hda` option to `qemu-system-x86_64`. - - `sshkey`: Location (on the host machine) of a root SSH identity to use for communicating with - the virtual machine. - - `sandbox` : Sandboxing mode, the following modes are supported: - - "none": don't do anything special (has false positives, e.g. due to killing init), default - - "setuid": impersonate into user nobody (65534) - - "namespace": use namespaces to drop privileges - (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. - - `type`: Type of virtual machine to use, e.g. `qemu` or `adb`. - - `vm`: object with VM-type-specific parameters; for example, for `qemu` type paramters include: - - `count`: Number of VMs to run in parallel. - - `kernel`: Location of the `bzImage` file for the kernel to be tested; - this is passed as the `-kernel` option to `qemu-system-x86_64`. - - `cmdline`: Additional command line options for the booting kernel, for example `root=/dev/sda1`. - - `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`. - -See also: - - [config.go](/pkg/mgrconfig/mgrconfig.go) for all config parameters; - - [qemu.go](/vm/qemu/qemu.go) for all vm parameters. +The operation of the syzkaller `syz-manager` process is governed by a +configuration file, passed at invocation time with the `-config` option. +This configuration can be based on the [example](/pkg/mgrconfig/testdata/qemu.cfg); +the file is in JSON format and contains the the [following parameters](/pkg/mgrconfig/config.go). diff --git a/pkg/mgrconfig/config.go b/pkg/mgrconfig/config.go new file mode 100644 index 00000000..48609d5c --- /dev/null +++ b/pkg/mgrconfig/config.go @@ -0,0 +1,99 @@ +// Copyright 2015 syzkaller project authors. All rights reserved. +// Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file. + +package mgrconfig + +import "encoding/json" + +type Config struct { + // Instance name (used for identification and as GCE instance prefix). + Name string `json:"name"` + // Target OS/arch, e.g. "linux/arm64" or "linux/amd64/386" (amd64 OS with 386 test process). + Target string `json:"target"` + // URL that will display information about the running syz-manager process (e.g. "localhost:50000"). + HTTP string `json:"http"` + // TCP address to serve RPC for fuzzer processes (optional). + RPC string `json:"rpc,omitempty"` + // Location of a working directory for the syz-manager process. Outputs here include: + // - /crashes/*: crash output files + // - /corpus.db: corpus with interesting programs + // - /instance-x: per VM instance temporary files + Workdir string `json:"workdir"` + // Directory with kernel object files (e.g. `vmlinux` for linux) + // (used for report symbolization and coverage reports, optional). + KernelObj string `json:"kernel_obj"` + // Kernel source directory (if not set defaults to KernelObj). + KernelSrc string `json:"kernel_src,omitempty"` + // Arbitrary optional tag that is saved along with crash reports (e.g. branch/commit). + Tag string `json:"tag,omitempty"` + // Location of the disk image file. + Image string `json:"image,omitempty"` + // Location (on the host machine) of a root SSH identity to use for communicating with + // the virtual machine (may be empty for some VM types). + SSHKey string `json:"sshkey,omitempty"` + // SSH user ("root" by default). + SSHUser string `json:"ssh_user,omitempty"` + + HubClient string `json:"hub_client,omitempty"` + HubAddr string `json:"hub_addr,omitempty"` + HubKey string `json:"hub_key,omitempty"` + + // List of email addresses to receive notifications when bugs are encountered for the first time (optional). + // Mailx is the only supported mailer. Please set it up prior to using this function. + EmailAddrs []string `json:"email_addrs,omitempty"` + + DashboardClient string `json:"dashboard_client,omitempty"` + DashboardAddr string `json:"dashboard_addr,omitempty"` + DashboardKey string `json:"dashboard_key,omitempty"` + + // Location of the syzkaller checkout, syz-manager will look + // for binaries in bin subdir (does not have to be syzkaller checkout as + // long as it preserves `bin` dir structure) + Syzkaller string `json:"syzkaller"` + + // Number of parallel test processes inside of each VM. + // 1 by default, 4 or 8 would be reasonable numbers too. + Procs int `json:"procs"` + + // Type of sandbox to use during fuzzing: + // "none": don't do anything special beyond resource sandboxing, default + // "setuid": impersonate into user nobody (65534). Supported only for some OSes. + // "namespace": create a new namespace for fuzzer using CLONE_NEWNS/CLONE_NEWNET/CLONE_NEWPID/etc, + // requires building kernel with CONFIG_NAMESPACES, CONFIG_UTS_NS, CONFIG_USER_NS, + // CONFIG_PID_NS and CONFIG_NET_NS. Supported only for some OSes. + // "android_untrusted_app": (Android) Emulate permissions of an untrusted app. + Sandbox string `json:"sandbox"` + + // Use KCOV coverage (default: true). + Cover bool `json:"cover"` + // Reproduce, localize and minimize crashers (default: true). + Reproduce bool `json:"reproduce"` + + // List of syscalls to test (optional). + EnabledSyscalls []string `json:"enable_syscalls,omitempty"` + // List of system calls that should be treated as disabled (optional). + DisabledSyscalls []string `json:"disable_syscalls,omitempty"` + // List of regexps for known bugs. + // Don't save reports matching these regexps, but reboot VM after them, + // matched against whole report output. + Suppressions []string `json:"suppressions,omitempty"` + // Completely ignore reports matching these regexps (don't save nor reboot), + // must match the first line of crash message. + Ignores []string `json:"ignores,omitempty"` + + // Type of virtual machine to use, e.g. "qemu", "gce", "android", "isolated", etc. + Type string `json:"type"` + // VM-type-specific parameters. + // Parameters for concrete types are in Config type in vm/TYPE/TYPE.go, e.g. vm/qemu/qemu.go. + VM json.RawMessage `json:"vm"` + + // Implementation details beyond this point. + // Parsed Target: + TargetOS string `json:"-"` + TargetArch string `json:"-"` + TargetVMArch string `json:"-"` + // Syzkaller binaries that we are going to use: + SyzFuzzerBin string `json:"-"` + SyzExecprogBin string `json:"-"` + SyzExecutorBin string `json:"-"` +} diff --git a/pkg/mgrconfig/mgrconfig.go b/pkg/mgrconfig/load.go similarity index 65% rename from pkg/mgrconfig/mgrconfig.go rename to pkg/mgrconfig/load.go index e4c9efc0..1fdcc015 100644 --- a/pkg/mgrconfig/mgrconfig.go +++ b/pkg/mgrconfig/load.go @@ -4,7 +4,6 @@ package mgrconfig import ( - "encoding/json" "fmt" "os" "path/filepath" @@ -17,84 +16,6 @@ import ( "github.com/google/syzkaller/sys/targets" ) -type Config struct { - // Instance name (used for identification and as GCE instance prefix). - Name string `json:"name"` - // Target OS/arch, e.g. "linux/arm64" or "linux/amd64/386" (amd64 OS with 386 test process). - Target string `json:"target"` - // TCP address to serve HTTP stats page (e.g. "localhost:50000"). - HTTP string `json:"http"` - // TCP address to serve RPC for fuzzer processes (optional). - RPC string `json:"rpc,omitempty"` - Workdir string `json:"workdir"` - // Directory with kernel object files. - KernelObj string `json:"kernel_obj"` - // Kernel source directory (if not set defaults to KernelObj). - KernelSrc string `json:"kernel_src,omitempty"` - // Arbitrary optional tag that is saved along with crash reports (e.g. branch/commit). - Tag string `json:"tag,omitempty"` - // Linux image for VMs. - Image string `json:"image,omitempty"` - // SSH key for the image (may be empty for some VM types). - SSHKey string `json:"sshkey,omitempty"` - // SSH user ("root" by default). - SSHUser string `json:"ssh_user,omitempty"` - - HubClient string `json:"hub_client,omitempty"` - HubAddr string `json:"hub_addr,omitempty"` - HubKey string `json:"hub_key,omitempty"` - - // syz-manager will send crash emails to this list of emails using mailx (optional). - EmailAddrs []string `json:"email_addrs,omitempty"` - - DashboardClient string `json:"dashboard_client,omitempty"` - DashboardAddr string `json:"dashboard_addr,omitempty"` - DashboardKey string `json:"dashboard_key,omitempty"` - - // Path to syzkaller checkout (syz-manager will look for binaries in bin subdir). - Syzkaller string `json:"syzkaller"` - // Number of parallel processes inside of every VM. - Procs int `json:"procs"` - - // Type of sandbox to use during fuzzing: - // "none": don't do anything special (has false positives, e.g. due to killing init), default - // "setuid": impersonate into user nobody (65534) - // "namespace": create a new namespace for fuzzer using CLONE_NEWNS/CLONE_NEWNET/CLONE_NEWPID/etc, - // requires building kernel with CONFIG_NAMESPACES, CONFIG_UTS_NS, CONFIG_USER_NS, - // CONFIG_PID_NS and CONFIG_NET_NS. - // "android_untrusted_app": (Android) Emulate permissions of an untrusted app - Sandbox string `json:"sandbox"` - - // Use KCOV coverage (default: true). - Cover bool `json:"cover"` - // Reproduce, localize and minimize crashers (default: true). - Reproduce bool `json:"reproduce"` - - EnabledSyscalls []string `json:"enable_syscalls,omitempty"` - DisabledSyscalls []string `json:"disable_syscalls,omitempty"` - // Don't save reports matching these regexps, but reboot VM after them, - // matched against whole report output. - Suppressions []string `json:"suppressions,omitempty"` - // Completely ignore reports matching these regexps (don't save nor reboot), - // must match the first line of crash message. - Ignores []string `json:"ignores,omitempty"` - - // VM type (qemu, gce, android, isolated, etc). - Type string `json:"type"` - // VM-type-specific config. - VM json.RawMessage `json:"vm"` - - // Implementation details beyond this point. - // Parsed Target: - TargetOS string `json:"-"` - TargetArch string `json:"-"` - TargetVMArch string `json:"-"` - // Syzkaller binaries that we are going to use: - SyzFuzzerBin string `json:"-"` - SyzExecprogBin string `json:"-"` - SyzExecutorBin string `json:"-"` -} - func LoadData(data []byte) (*Config, error) { cfg, err := LoadPartialData(data) if err != nil { diff --git a/vm/qemu/qemu.go b/vm/qemu/qemu.go index f3332e57..6609a61a 100644 --- a/vm/qemu/qemu.go +++ b/vm/qemu/qemu.go @@ -28,15 +28,19 @@ func init() { } type Config struct { - Count int `json:"count"` // number of VMs to use - Qemu string `json:"qemu"` // qemu binary name (qemu-system-arch by default) - QemuArgs string `json:"qemu_args"` // additional command line arguments for qemu binary - Kernel string `json:"kernel"` // kernel for injected boot (e.g. arch/x86/boot/bzImage) - Cmdline string `json:"cmdline"` // kernel command line (can only be specified with kernel) + Count int `json:"count"` // number of VMs to run in parallel + Qemu string `json:"qemu"` // qemu binary name (qemu-system-arch by default) + QemuArgs string `json:"qemu_args"` // additional command line arguments for qemu binary + // Location of the kernel for injected boot (e.g. arch/x86/boot/bzImage, optional). + // This is passed to qemu as the -kernel option. + Kernel string `json:"kernel"` + // Additional command line options for the booting kernel, for example `root=/dev/sda1`. + // Can only be specified with kernel. + Cmdline string `json:"cmdline"` Initrd string `json:"initrd"` // linux initial ramdisk. (optional) ImageDevice string `json:"image_device"` // qemu image device (hda by default) CPU int `json:"cpu"` // number of VM CPUs - Mem int `json:"mem"` // amount of VM memory in MBs + Mem int `json:"mem"` // amount of VM memory in MiB Snapshot bool `json:"snapshot"` // For building kernels without -snapshot (for pkg/build) }