|
| From: | Aleksandar Markovic |
| Subject: | Re: [PATCH 1/4] docs: Convert security.texi to rST format |
| Date: | Wed, 26 Feb 2020 12:48:05 +0100 |
security.texi is included from qemu-doc.texi but is not used
in the qemu.1 manpage. So we can do a straightforward conversion
of the contents, which go into the system manual.
Signed-off-by: Peter Maydell <address@hidden>
---
Makefile | 2 +-
docs/system/index.rst | 1 +
docs/{security.texi => system/security.rst} | 82 +++++++++++----------
qemu-doc.texi | 3 -
4 files changed, 46 insertions(+), 42 deletions(-)
rename docs/{security.texi => system/security.rst} (77%)
diff --git a/Makefile b/Makefile
index aa9cc0b5847..5f0f803b471 100644
--- a/Makefile
+++ b/Makefile
@@ -1117,7 +1117,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
qemu-tech.texi qemu-option-trace.texi \
qemu-deprecated.texi qemu-monitor.texi \
qemu-monitor-info.texi \
- docs/qemu-cpu-models.texi docs/security.texi
+ docs/qemu-cpu-models.texi
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \
diff --git a/docs/system/index.rst b/docs/system/index.rst
index f66e6ea585c..794e5d8de03 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -15,3 +15,4 @@ Contents:
:maxdepth: 2
qemu-block-drivers
+ security
diff --git a/docs/security.texi b/docs/system/security.rst
similarity index 77%
rename from docs/security.texi
rename to docs/system/security.rst
index 0d6b30edfc0..f2092c8768b 100644
--- a/docs/security.texi
+++ b/docs/system/security.rst
@@ -1,19 +1,22 @@
-@node Security
-@chapter Security
+Security
+========
-@section Overview
+Overview
+--------
This chapter explains the security requirements that QEMU is designed to meet
and principles for securely deploying QEMU.
-@section Security Requirements
+Security Requirements
+---------------------
QEMU supports many different use cases, some of which have stricter security
requirements than others. The community has agreed on the overall security
requirements that users may depend on. These requirements define what is
considered supported from a security perspective.
-@subsection Virtualization Use Case
+Virtualization Use Case
+'''''''''''''''''''''''
The virtualization use case covers cloud and virtual private server (VPS)
hosting, as well as traditional data center and desktop virtualization. These
@@ -23,18 +26,17 @@ safely on the physical CPU at close-to-native speed.
The following entities are untrusted, meaning that they may be buggy or
malicious:
-@itemize
-@item Guest
-@item User-facing interfaces (e.g. VNC, SPICE, WebSocket)
-@item Network protocols (e.g. NBD, live migration)
-@item User-supplied files (e.g. disk images, kernels, device trees)
-@item Passthrough devices (e.g. PCI, USB)
-@end itemize
+- Guest
+- User-facing interfaces (e.g. VNC, SPICE, WebSocket)
+- Network protocols (e.g. NBD, live migration)
+- User-supplied files (e.g. disk images, kernels, device trees)
+- Passthrough devices (e.g. PCI, USB)
Bugs affecting these entities are evaluated on whether they can cause damage in
real-world use cases and treated as security bugs if this is the case.
-@subsection Non-virtualization Use Case
+Non-virtualization Use Case
+'''''''''''''''''''''''''''
The non-virtualization use case covers emulation using the Tiny Code Generator
(TCG). In principle the TCG and device emulation code used in conjunction with
@@ -47,12 +49,14 @@ Bugs affecting the non-virtualization use case are not considered security
bugs at this time. Users with non-virtualization use cases must not rely on
QEMU to provide guest isolation or any security guarantees.
-@section Architecture
+Architecture
+------------
This section describes the design principles that ensure the security
requirements are met.
-@subsection Guest Isolation
+Guest Isolation
+'''''''''''''''
Guest isolation is the confinement of guest code to the virtual machine. When
guest code gains control of execution on the host this is called escaping the
@@ -71,7 +75,8 @@ malicious guest must not gain control of other guests or access their data.
Disk image files and network traffic must be protected from other guests unless
explicitly shared between them by the user.
-@subsection Principle of Least Privilege
+Principle of Least Privilege
+''''''''''''''''''''''''''''
The principle of least privilege states that each component only has access to
the privileges necessary for its function. In the case of QEMU this means that
@@ -84,7 +89,7 @@ the guest.
Following the principle of least privilege immediately fulfills guest isolation
requirements. For example, guest A only has access to its own disk image file
-@code{a.img} and not guest B's disk image file @code{b.img}.
+``a.img`` and not guest B's disk image file ``b.img``.
In reality certain resources are inaccessible to the guest but must be
available to QEMU to perform its function. For example, host system calls are
@@ -95,7 +100,8 @@ New features must be designed to follow the principle of least privilege.
Should this not be possible for technical reasons, the security risk must be
clearly documented so users are aware of the trade-off of enabling the feature.
-@subsection Isolation mechanisms
+Isolation mechanisms
+''''''''''''''''''''
Several isolation mechanisms are available to realize this architecture of
guest isolation and the principle of least privilege. With the exception of
@@ -105,46 +111,46 @@ described briefly for Linux here.
The fundamental isolation mechanism is that QEMU processes must run as
unprivileged users. Sometimes it seems more convenient to launch QEMU as
-root to give it access to host devices (e.g. @code{/dev/net/tun}) but this poses a
+root to give it access to host devices (e.g. ``/dev/net/tun``) but this poses a
huge security risk. File descriptor passing can be used to give an otherwise
unprivileged QEMU process access to host devices without running QEMU as root.
It is also possible to launch QEMU as a non-root user and configure UNIX groups
-for access to @code{/dev/kvm}, @code{/dev/net/tun}, and other device nodes.
+for access to ``/dev/kvm``, ``/dev/net/tun``, and other device nodes.
Some Linux distros already ship with UNIX groups for these devices by default.
-@itemize
-@item SELinux and AppArmor make it possible to confine processes beyond the
-traditional UNIX process and file permissions model. They restrict the QEMU
-process from accessing processes and files on the host system that are not
-needed by QEMU.
+- SELinux and AppArmor make it possible to confine processes beyond the
+ traditional UNIX process and file permissions model. They restrict the QEMU
+ process from accessing processes and files on the host system that are not
+ needed by QEMU.
-@item Resource limits and cgroup controllers provide throughput and utilization
-limits on key resources such as CPU time, memory, and I/O bandwidth.
+- Resource limits and cgroup controllers provide throughput and utilization
+ limits on key resources such as CPU time, memory, and I/O bandwidth.
-@item Linux namespaces can be used to make process, file system, and other system
-resources unavailable to QEMU. A namespaced QEMU process is restricted to only
-those resources that were granted to it.
+- Linux namespaces can be used to make process, file system, and other system
+ resources unavailable to QEMU. A namespaced QEMU process is restricted to only
+ those resources that were granted to it.
-@item Linux seccomp is available via the QEMU @option{--sandbox} option. It disables
-system calls that are not needed by QEMU, thereby reducing the host kernel
-attack surface.
-@end itemize
+- Linux seccomp is available via the QEMU ``--sandbox`` option. It disables
+ system calls that are not needed by QEMU, thereby reducing the host kernel
+ attack surface.
-@section Sensitive configurations
+Sensitive configurations
+------------------------
There are aspects of QEMU that can have security implications which users &
management applications must be aware of.
-@subsection Monitor console (QMP and HMP)
+Monitor console (QMP and HMP)
+'''''''''''''''''''''''''''''
The monitor console (whether used with QMP or HMP) provides an interface
to dynamically control many aspects of QEMU's runtime operation. Many of the
commands exposed will instruct QEMU to access content on the host file system
and/or trigger spawning of external processes.
-For example, the @code{migrate} command allows for the spawning of arbitrary
+For example, the ``migrate`` command allows for the spawning of arbitrary
processes for the purpose of tunnelling the migration data stream. The
-@code{blockdev-add} command instructs QEMU to open arbitrary files, exposing
+``blockdev-add`` command instructs QEMU to open arbitrary files, exposing
their content to the guest as a virtual disk.
Unless QEMU is otherwise confined using technologies such as SELinux, AppArmor,
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 33b9597b1dc..c11b1a5d5ad 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -40,7 +40,6 @@
* QEMU System emulator for non PC targets::
* QEMU User space emulator::
* System requirements::
-* Security::
* Implementation notes::
* Deprecated features::
* Recently removed features::
@@ -2836,8 +2835,6 @@ added with Linux 4.5 which is supported by the major distros. And even
if RHEL7 has kernel 3.10, KVM there has the required functionality there
to make it close to a 4.5 or newer kernel.
-@include docs/security.texi
-
@include qemu-tech.texi
@include qemu-deprecated.texi
--
2.20.1
| [Prev in Thread] | Current Thread | [Next in Thread] |