From 1bf4de5647ac647ec0cbf247738b51ab685c92df Mon Sep 17 00:00:00 2001 From: Andrey Konovalov Date: Mon, 24 Jul 2017 18:17:24 +0200 Subject: docs: small fixes --- docs/setup.md | 2 + ...setup_linux-host_android-device_arm64-kernel.md | 3 + docs/setup_linux-host_isolated.md | 3 + docs/setup_linux-host_qemu-vm_arm64-kernel.md | 3 + ...tup_ubuntu-host_odroid-c2-board_arm64-kernel.md | 3 + docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md | 3 + docs/syscall_descriptions_syntax.md | 116 ++++++++++++--------- docs/troubleshooting.md | 8 +- docs/usage.md | 2 +- 9 files changed, 92 insertions(+), 51 deletions(-) (limited to 'docs') diff --git a/docs/setup.md b/docs/setup.md index 933db69cb..26c06062a 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -27,3 +27,5 @@ $ ./bin/syz-manager -config=my.cfg ``` More information on the configuration file format is available [here](configuration.md). + +See [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/setup_linux-host_android-device_arm64-kernel.md b/docs/setup_linux-host_android-device_arm64-kernel.md index 699671155..0be9cb9e8 100644 --- a/docs/setup_linux-host_android-device_arm64-kernel.md +++ b/docs/setup_linux-host_android-device_arm64-kernel.md @@ -39,3 +39,6 @@ bin/syz-manager: Mach-O 64-bit executable x86_64 ``` - Start `syz-manager -config adb.cfg` as usual. + +If you get issues after `syz-manager` starts, consider running it with the `-debug` flag. +Also see [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/setup_linux-host_isolated.md b/docs/setup_linux-host_isolated.md index 7f26efd75..8cff007f6 100644 --- a/docs/setup_linux-host_isolated.md +++ b/docs/setup_linux-host_isolated.md @@ -106,3 +106,6 @@ Run syzkaller manager: ``` bash ./bin/syz-manager -config=my.cfg ``` + +If you get issues after `syz-manager` starts, consider running it with the `-debug` flag. +Also see [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/setup_linux-host_qemu-vm_arm64-kernel.md b/docs/setup_linux-host_qemu-vm_arm64-kernel.md index 2c363dafc..3ace6b68b 100644 --- a/docs/setup_linux-host_qemu-vm_arm64-kernel.md +++ b/docs/setup_linux-host_qemu-vm_arm64-kernel.md @@ -160,3 +160,6 @@ A sample config file that exercises the required options are shown below. Modify ``` At this point, you should be able to visit `localhost:56700` and view the results of the fuzzing. + +If you get issues after `syz-manager` starts, consider running it with the `-debug` flag. +Also see [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md b/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md index 899beaaa8..01366f036 100644 --- a/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md +++ b/docs/setup_ubuntu-host_odroid-c2-board_arm64-kernel.md @@ -330,3 +330,6 @@ Now start syzkaller: ``` bash ./bin/syz-manager -config=odroid.cfg ``` + +If you get issues after `syz-manager` starts, consider running it with the `-debug` flag. +Also see [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md b/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md index 41e87ca88..85af3f8ee 100644 --- a/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md +++ b/docs/setup_ubuntu-host_qemu-vm_x86-64-kernel.md @@ -232,3 +232,6 @@ Run syzkaller manager: ``` Now syzkaller should be running, you can check manager status with your web browser at `127.0.0.1:56741`. + +If you get issues after `syz-manager` starts, consider running it with the `-debug` flag. +Also see [this page](troubleshooting.md) for troubleshooting tips. diff --git a/docs/syscall_descriptions_syntax.md b/docs/syscall_descriptions_syntax.md index 83bbe2566..a0ba540fa 100644 --- a/docs/syscall_descriptions_syntax.md +++ b/docs/syscall_descriptions_syntax.md @@ -1,59 +1,68 @@ # Syscall descriptions syntax Pseudo-formal grammar of syscall description: + ``` - syscallname "(" [arg ["," arg]*] ")" [type] - arg = argname type - argname = identifier - type = typename [ "[" type-options "]" ] - typename = "const" | "intN" | "intptr" | "flags" | "array" | "ptr" | - "buffer" | "string" | "strconst" | "filename" | - "len" | "bytesize" | "vma" | "proc" - type-options = [type-opt ["," type-opt]] +syscallname "(" [arg ["," arg]*] ")" [type] +arg = argname type +argname = identifier +type = typename [ "[" type-options "]" ] +typename = "const" | "intN" | "intptr" | "flags" | "array" | "ptr" | + "buffer" | "string" | "strconst" | "filename" | "len" | + "bytesize" | "vma" | "proc" +type-options = [type-opt ["," type-opt]] ``` + common type-options include: + ``` - "opt" - the argument is optional (like mmap fd argument, or accept peer argument) +"opt" - the argument is optional (like mmap fd argument, or accept peer argument) ``` + rest of the type-options are type-specific: + ``` - "const": integer constant, type-options: - value, underlying type (one if "intN", "intptr") - "intN"/"intptr": an integer without a particular meaning, type-options: - optional range of values (e.g. "5:10", or "-100:200") - "flags": a set of flags, type-options: - reference to flags description (see below) - "array": a variable/fixed-length array, type-options: - type of elements, optional size (fixed "5", or ranged "5:10", boundaries inclusive) - "ptr": a pointer to an object, type-options: - type of the object; direction (in/out/inout) - "buffer": a pointer to a memory buffer (like read/write buffer argument), type-options: - direction (in/out/inout) - "string": a zero-terminated memory buffer (no pointer indirection implied), type-options: - either a string value in quotes for constant strings (e.g. "foo"), - or a reference to string flags, - optionally followed by a buffer size (string values will be padded with \x00 to that size) - "filename": a file/link/dir name, no pointer indirection implied, in most cases you want `ptr[in, filename]` - "fileoff": offset within a file - "len": length of another field (for array it is number of elements), type-options: - argname of the object - "bytesize": similar to "len", but always denotes the size in bytes, type-options: - argname of the object - "vma": a pointer to a set of pages (used as input for mmap/munmap/mremap/madvise), type-options: - optional number of pages (e.g. vma[7]), or a range of pages (e.g. vma[2-4]) - "proc": per process int (see description below), type-options: - underlying type, value range start, how many values per process - "text16", "text32", "text64": machine code of the specified bitness +"const": integer constant, type-options: + value, underlying type (one if "intN", "intptr") +"intN"/"intptr": an integer without a particular meaning, type-options: + optional range of values (e.g. "5:10", or "-100:200") +"flags": a set of flags, type-options: + reference to flags description (see below) +"array": a variable/fixed-length array, type-options: + type of elements, optional size (fixed "5", or ranged "5:10", boundaries inclusive) +"ptr": a pointer to an object, type-options: + type of the object; direction (in/out/inout) +"buffer": a pointer to a memory buffer (like read/write buffer argument), type-options: + direction (in/out/inout) +"string": a zero-terminated memory buffer (no pointer indirection implied), type-options: + either a string value in quotes for constant strings (e.g. "foo"), + or a reference to string flags, + optionally followed by a buffer size (string values will be padded with \x00 to that size) +"filename": a file/link/dir name, no pointer indirection implied, in most cases you want `ptr[in, filename]` +"fileoff": offset within a file +"len": length of another field (for array it is number of elements), type-options: + argname of the object +"bytesize": similar to "len", but always denotes the size in bytes, type-options: + argname of the object +"vma": a pointer to a set of pages (used as input for mmap/munmap/mremap/madvise), type-options: + optional number of pages (e.g. vma[7]), or a range of pages (e.g. vma[2-4]) +"proc": per process int (see description below), type-options: + underlying type, value range start, how many values per process +"text16", "text32", "text64": machine code of the specified bitness ``` + flags/len/flags also have trailing underlying type type-option when used in structs/unions/pointers. Flags are described as: + ``` - flagname = const ["," const]* +flagname = const ["," const]* ``` + or for string flags as: + ``` - flagname = "\"" literal "\"" ["," "\"" literal "\""]* +flagname = "\"" literal "\"" ["," "\"" literal "\""]* ``` ## Ints @@ -80,22 +89,25 @@ example_struct { ## Structs Structs are described as: + ``` - structname "{" "\n" - (fieldname type "\n")+ - "}" +structname "{" "\n" + (fieldname type "\n")+ +"}" ``` -Structs can have trailing attributes "packed" and "align_N", -they are specified in square brackets after the struct. + +Structs can have trailing attributes `packed` and `align_N`, they are specified in square brackets after the struct. ## Unions Unions are described as: + ``` - unionname "[" "\n" - (fieldname type "\n")+ - "]" +unionname "[" "\n" + (fieldname type "\n")+ +"]" ``` + Unions can have a trailing "varlen" attribute (specified in square brackets after the union), which means that union length is not maximum of all option lengths, but rather length of a particular chosen option. @@ -103,11 +115,14 @@ but rather length of a particular chosen option. ## Resources Custom resources are described as: + ``` - resource identifier "[" underlying_type "]" [ ":" const ("," const)* ] +resource identifier "[" underlying_type "]" [ ":" const ("," const)* ] ``` + `underlying_type` is either one of `int8`, `int16`, `int32`, `int64`, `intptr` or another resource. Resources can then be used as types. For example: + ``` resource fd[int32]: 0xffffffffffffffff, AT_FDCWD, 1000000 resource sock[fd] @@ -121,6 +136,7 @@ listen(fd sock, backlog int32) ## Length You can specify length of a particular field in struct or a named argument by using `len` and `bytesize` types, for example: + ``` write(fd fd, buf buffer[in], count len[buf]) len[buf] @@ -136,6 +152,7 @@ To denote the length of a field in N-byte words use `bytesizeN`, possible values To denote the length of the parent struct, you can use `len[parent, int8]`. To denote the length of the higher level parent when structs are embedded into one another, you can specify the type name of the particular parent: + ``` struct s1 { f0 len[s2] # length of s2 @@ -159,5 +176,6 @@ As a result the executor number `n` will get values in the `[20000 + n * 4, 2000 ## Misc -Description files also contain `include` directives that refer to Linux kernel header files, `incdir` directives that refer to custom Linux kernel header directories -and `define` directives that define symbolic constant values. See the following section for details. +Description files also contain `include` directives that refer to Linux kernel header files, +`incdir` directives that refer to custom Linux kernel header directories +and `define` directives that define symbolic constant values. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index da041ca1b..4e78ceb80 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -25,6 +25,10 @@ Here are some things to check if there are problems running syzkaller. `VMLINUX` is the vmlinux file, as per the `vmlinux` config value), to confirm that symbols for the kernel are available. + - Use the `-debug` command line option to make syzkaller print all possible debug output, + from both the `syz-manager` top-level program and the `syz-fuzzer` instances. With this option + syzkaller will only run one VM instance. + - 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 @@ -41,4 +45,6 @@ Here are some things to check if there are problems running syzkaller. 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`. -If none of the above helps, file a bug on [the bug tracker](https://github.com/google/syzkaller/issues) or ask us directly on the syzkaller@googlegroups.com mailing list. +If none of the above helps, file a bug on [the bug tracker](https://github.com/google/syzkaller/issues) +or ask us directly on the syzkaller@googlegroups.com mailing list. +Please include syzkaller commit id that you use and `syz-manager` output with `-debug` flag enabled if applicable. diff --git a/docs/usage.md b/docs/usage.md index 93794a643..e639258ed 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -33,4 +33,4 @@ Check [here](linux_kernel_reporting_bugs.md) for the instructions on how to repo ## Other -[How to connect several managers via Hub](connecting_several_managers.md) +[How to connect several managers via Hub](hub.md) -- cgit mrf-deployment