diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/devel/fuzzing.txt | 39 | ||||
| -rw-r--r-- | docs/devel/testing.rst | 4 | ||||
| -rw-r--r-- | docs/system/deprecated.rst | 23 | ||||
| -rw-r--r-- | docs/tools/virtiofsd.rst | 193 |
4 files changed, 239 insertions, 20 deletions
diff --git a/docs/devel/fuzzing.txt b/docs/devel/fuzzing.txt index 96d71c94d7..03585c1a9b 100644 --- a/docs/devel/fuzzing.txt +++ b/docs/devel/fuzzing.txt @@ -125,6 +125,45 @@ provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the fuzzer loops over the byte-array interpreting it as a list of qtest commands, addresses, or values. +== The Generic Fuzzer == +Writing a fuzz target can be a lot of effort (especially if a device driver has +not be built-out within libqos). Many devices can be fuzzed to some degree, +without any device-specific code, using the generic-fuzz target. + +The generic-fuzz target is capable of fuzzing devices over their PIO, MMIO, +and DMA input-spaces. To apply the generic-fuzz to a device, we need to define +two env-variables, at minimum: + +QEMU_FUZZ_ARGS= is the set of QEMU arguments used to configure a machine, with +the device attached. For example, if we want to fuzz the virtio-net device +attached to a pc-i440fx machine, we can specify: +QEMU_FUZZ_ARGS="-M pc -nodefaults -netdev user,id=user0 \ + -device virtio-net,netdev=user0" + +QEMU_FUZZ_OBJECTS= is a set of space-delimited strings used to identify the +MemoryRegions that will be fuzzed. These strings are compared against +MemoryRegion names and MemoryRegion owner names, to decide whether each +MemoryRegion should be fuzzed. These strings support globbing. For the +virtio-net example, we could use QEMU_FUZZ_OBJECTS= + * 'virtio-net' + * 'virtio*' + * 'virtio* pcspk' (Fuzz the virtio devices and the PC speaker...) + * '*' (Fuzz the whole machine) + +The "info mtree" and "info qom-tree" monitor commands can be especially useful +for identifying the MemoryRegion and Object names used for matching. + +As a generic rule-of-thumb, the more MemoryRegions/Devices we match, the greater +the input-space, and the smaller the probability of finding crashing inputs for +individual devices. As such, it is usually a good idea to limit the fuzzer to +only a few MemoryRegions. + +To ensure that these env variables have been configured correctly, we can use: + +./qemu-fuzz-i386 --fuzz-target=generic-fuzz -runs=0 + +The output should contain a complete list of matched MemoryRegions. + = Implementation Details = == The Fuzzer's Lifecycle == diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index 0c3e79d31c..0aa7a13bba 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -654,7 +654,7 @@ To manually install Avocado and its dependencies, run: Alternatively, follow the instructions on this link: - http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html#installing-avocado + https://avocado-framework.readthedocs.io/en/latest/guides/user/chapters/installing.html Overview -------- @@ -837,7 +837,7 @@ Parameter reference To understand how Avocado parameters are accessed by tests, and how they can be passed to tests, please refer to:: - http://avocado-framework.readthedocs.io/en/latest/WritingTests.html#accessing-test-parameters + https://avocado-framework.readthedocs.io/en/latest/guides/writer/chapters/writing.html#accessing-test-parameters Parameter values can be easily seen in the log files, and will look like the following: diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst index 905628f3a0..0ebce37a19 100644 --- a/docs/system/deprecated.rst +++ b/docs/system/deprecated.rst @@ -21,17 +21,6 @@ deprecated. System emulator command line arguments -------------------------------------- -``-machine enforce-config-section=on|off`` (since 3.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -The ``enforce-config-section`` parameter is replaced by the -``-global migration.send-configuration={on|off}`` option. - -``-no-kvm`` (since 1.3.0) -''''''''''''''''''''''''' - -The ``-no-kvm`` argument is now a synonym for setting ``-accel tcg``. - ``-usbdevice`` (since 2.10.0) ''''''''''''''''''''''''''''' @@ -504,6 +493,12 @@ System emulator command line arguments The ``name`` parameter of the ``-net`` option was a synonym for the ``id`` parameter, which should now be used instead. +``-no-kvm`` (removed in 5.2) +'''''''''''''''''''''''''''' + +The ``-no-kvm`` argument was a synonym for setting ``-machine accel=tcg``. + + QEMU Machine Protocol (QMP) commands ------------------------------------ @@ -688,6 +683,12 @@ Support for invalid topologies is removed, the user must ensure topologies described with -smp include all possible cpus, i.e. *sockets* * *cores* * *threads* = *maxcpus*. +``-machine enforce-config-section=on|off`` (removed 5.2) +'''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The ``enforce-config-section`` property was replaced by the +``-global migration.send-configuration={on|off}`` option. + Block devices ------------- diff --git a/docs/tools/virtiofsd.rst b/docs/tools/virtiofsd.rst index 7ecee49834..34a9e40146 100644 --- a/docs/tools/virtiofsd.rst +++ b/docs/tools/virtiofsd.rst @@ -17,13 +17,24 @@ This program is designed to work with QEMU's ``--device vhost-user-fs-pci`` but should work with any virtual machine monitor (VMM) that supports vhost-user. See the Examples section below. -This program must be run as the root user. Upon startup the program will -switch into a new file system namespace with the shared directory tree as its -root. This prevents "file system escapes" due to symlinks and other file -system objects that might lead to files outside the shared directory. The -program also sandboxes itself using seccomp(2) to prevent ptrace(2) and other -vectors that could allow an attacker to compromise the system after gaining -control of the virtiofsd process. +This program must be run as the root user. The program drops privileges where +possible during startup although it must be able to create and access files +with any uid/gid: + +* The ability to invoke syscalls is limited using seccomp(2). +* Linux capabilities(7) are dropped. + +In "namespace" sandbox mode the program switches into a new file system +namespace and invokes pivot_root(2) to make the shared directory tree its root. +A new pid and net namespace is also created to isolate the process. + +In "chroot" sandbox mode the program invokes chroot(2) to make the shared +directory tree its root. This mode is intended for container environments where +the container runtime has already set up the namespaces and the program does +not have permission to create namespaces itself. + +Both sandbox modes prevent "file system escapes" due to symlinks and other file +system objects that might lead to files outside the shared directory. Options ------- @@ -69,6 +80,13 @@ Options * readdirplus|no_readdirplus - Enable/disable readdirplus. The default is ``readdirplus``. + * sandbox=namespace|chroot - + Sandbox mode: + - namespace: Create mount, pid, and net namespaces and pivot_root(2) into + the shared directory. + - chroot: chroot(2) into shared directory (use in containers). + The default is "namespace". + * source=PATH - Share host directory tree located at PATH. This option is required. @@ -109,6 +127,167 @@ Options timeout. ``always`` sets a long cache lifetime at the expense of coherency. The default is ``auto``. +xattr-mapping +------------- + +By default the name of xattr's used by the client are passed through to the server +file system. This can be a problem where either those xattr names are used +by something on the server (e.g. selinux client/server confusion) or if the +virtiofsd is running in a container with restricted privileges where it cannot +access some attributes. + +A mapping of xattr names can be made using -o xattrmap=mapping where the ``mapping`` +string consists of a series of rules. + +The first matching rule terminates the mapping. +The set of rules must include a terminating rule to match any remaining attributes +at the end. + +Each rule consists of a number of fields separated with a separator that is the +first non-white space character in the rule. This separator must then be used +for the whole rule. +White space may be added before and after each rule. + +Using ':' as the separator a rule is of the form: + +``:type:scope:key:prepend:`` + +**scope** is: + +- 'client' - match 'key' against a xattr name from the client for + setxattr/getxattr/removexattr +- 'server' - match 'prepend' against a xattr name from the server + for listxattr +- 'all' - can be used to make a single rule where both the server + and client matches are triggered. + +**type** is one of: + +- 'prefix' - is designed to prepend and strip a prefix; the modified + attributes then being passed on to the client/server. + +- 'ok' - Causes the rule set to be terminated when a match is found + while allowing matching xattr's through unchanged. + It is intended both as a way of explicitly terminating + the list of rules, and to allow some xattr's to skip following rules. + +- 'bad' - If a client tries to use a name matching 'key' it's + denied using EPERM; when the server passes an attribute + name matching 'prepend' it's hidden. In many ways it's use is very like + 'ok' as either an explict terminator or for special handling of certain + patterns. + +**key** is a string tested as a prefix on an attribute name originating +on the client. It maybe empty in which case a 'client' rule +will always match on client names. + +**prepend** is a string tested as a prefix on an attribute name originating +on the server, and used as a new prefix. It may be empty +in which case a 'server' rule will always match on all names from +the server. + +e.g.: + + ``:prefix:client:trusted.:user.virtiofs.:`` + + will match 'trusted.' attributes in client calls and prefix them before + passing them to the server. + + ``:prefix:server::user.virtiofs.:`` + + will strip 'user.virtiofs.' from all server replies. + + ``:prefix:all:trusted.:user.virtiofs.:`` + + combines the previous two cases into a single rule. + + ``:ok:client:user.::`` + + will allow get/set xattr for 'user.' xattr's and ignore + following rules. + + ``:ok:server::security.:`` + + will pass 'securty.' xattr's in listxattr from the server + and ignore following rules. + + ``:ok:all:::`` + + will terminate the rule search passing any remaining attributes + in both directions. + + ``:bad:server::security.:`` + + would hide 'security.' xattr's in listxattr from the server. + +A simpler 'map' type provides a shorter syntax for the common case: + +``:map:key:prepend:`` + +The 'map' type adds a number of separate rules to add **prepend** as a prefix +to the matched **key** (or all attributes if **key** is empty). +There may be at most one 'map' rule and it must be the last rule in the set. + +xattr-mapping Examples +---------------------- + +1) Prefix all attributes with 'user.virtiofs.' + +:: + +-o xattrmap=":prefix:all::user.virtiofs.::bad:all:::" + + +This uses two rules, using : as the field separator; +the first rule prefixes and strips 'user.virtiofs.', +the second rule hides any non-prefixed attributes that +the host set. + +This is equivalent to the 'map' rule: + +:: +-o xattrmap=":map::user.virtiofs.:" + +2) Prefix 'trusted.' attributes, allow others through + +:: + + "/prefix/all/trusted./user.virtiofs./ + /bad/server//trusted./ + /bad/client/user.virtiofs.// + /ok/all///" + + +Here there are four rules, using / as the field +separator, and also demonstrating that new lines can +be included between rules. +The first rule is the prefixing of 'trusted.' and +stripping of 'user.virtiofs.'. +The second rule hides unprefixed 'trusted.' attributes +on the host. +The third rule stops a guest from explicitly setting +the 'user.virtiofs.' path directly. +Finally, the fourth rule lets all remaining attributes +through. + +This is equivalent to the 'map' rule: + +:: +-o xattrmap="/map/trusted./user.virtiofs./" + +3) Hide 'security.' attributes, and allow everything else + +:: + + "/bad/all/security./security./ + /ok/all///' + +The first rule combines what could be separate client and server +rules into a single 'all' rule, matching 'security.' in either +client arguments or lists returned from the host. This stops +the client seeing any 'security.' attributes on the server and +stops it setting any. + Examples -------- |