mirror of
https://github.com/reactos/syzkaller.git
synced 2025-01-31 17:12:52 +00:00
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.
This commit is contained in:
Dmitry Vyukov
parent
8285069f89
commit
e503f048b0
@ -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:
|
||||
- `<workdir>/crashes/*`: crash output files (see [Crash Reports](#crash-reports))
|
||||
- `<workdir>/corpus.db`: corpus with interesting programs
|
||||
- `<workdir>/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).
|
||||
|
||||
99
pkg/mgrconfig/config.go
Normal file
99
pkg/mgrconfig/config.go
Normal file
@ -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:
|
||||
// - <workdir>/crashes/*: crash output files
|
||||
// - <workdir>/corpus.db: corpus with interesting programs
|
||||
// - <workdir>/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:"-"`
|
||||
}
|
||||
@ -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 {
|
||||
@ -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)
|
||||
}
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user