[Xen-devel] [PATCH-for-4.12] docs: Fix dm_restrict documentation

[George Dunlap <george.dunlap@xxxxxxxxxx>]

Remove "chatty" and redundant information from the xl man page;
restrict it to functional descriptions only, and point instead to
qemu-depriv.pandoc and SUPPORT.md as locations for "canonical"
information.

Add a man page entry for device_model_user.

Update qemu-deprivilege.pandoc:

Changes in missing feature list:
- Migration is functional
- But qdisk backends are not

Add a missing restriction list.

The following statements from the man page are dropped:
- Mentioning PV; PV guests never have a device model.
- Drop the confusing statement about stdvga and cirrus vga options.
- Re-used domain IDs are now handled.
- Device models should no longer be able to create world-readable
  files on dom0's filesystem.

Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx>
---
RFC: I don't know what the 'vga' limitation thing was about -- I tried
both 'default' and 'stgvga' with dm_restrict and they worked fine.

Freeze exception justification:
- Fixing a "bug" in the docs
- No functional change

CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Anthony Perard <anthony.perard@xxxxxxxxxx>
CC: Juergen Gross <jgross@xxxxxxxx>
---
 docs/features/qemu-deprivilege.pandoc |  12 ++--
 docs/man/xl.cfg.5.pod.in              | 100 +++-----------------------
 2 files changed, 16 insertions(+), 96 deletions(-)

diff --git a/docs/features/qemu-deprivilege.pandoc 
b/docs/features/qemu-deprivilege.pandoc
index 20d6ac2189..cfe528b1d3 100644
--- a/docs/features/qemu-deprivilege.pandoc
+++ b/docs/features/qemu-deprivilege.pandoc
@@ -110,10 +110,14 @@ See docs/design/qemu-deprivilege.md for technical details.
 
 The following features still need to be implemented:
  * Inserting a new cdrom while the guest is running (xl cdrom-insert)
- * Migration / save / restore
-
-dm_restrict is totally unsupported and may have unexpected security
-problems if used with a dom0 Linux kernel earlier than 2.6.18.
+ * Support for qdisk backends
+
+A number of restrictions still need to be implemented.  A compromised
+device model may be able to do the following:
+ * Delay or exploit weaknesses in the toolstack
+ * Launch "fork bombs" or other resource exhaustion attacks
+ * Make network connections on the management network
+ * Break out of the restrictions after migration
 
 Additionally, getting PCI passthrough to work securely would require a
 significant rework of how passthrough works at the moment.  It may be
diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
index 3b92f39d8d..ad81af1ed8 100644
--- a/docs/man/xl.cfg.5.pod.in
+++ b/docs/man/xl.cfg.5.pod.in
@@ -1316,104 +1316,20 @@ connectors=id0:1920x1080;id1:800x600;id2:640x480
 Restrict the device model after startup,
 to limit the consequencese of security vulnerabilities in qemu.
 
-With this feature enabled,
-a compromise of the device model,
-via such a vulnerability,
-will not provide a privilege escalation attack on the whole system.
+See docs/features/qemu-depriv.pandoc for more information
+on Linux and QEMU version requirements, device model user setup,
+and current limitations.
 
 This feature is a B<technology preview>.
-There are some significant limitations:
+See SUPPORT.md for a security support statement.
 
-=over 4
-
-=item
-
-This is not likely to work at all for PV guests
-nor guests using qdisk backends for their block devices.
-
-=item
-
-You must have a new enough qemu.
-In particular,
-if your qemu does not have the commit
-B<xen: restrict: use xentoolcore_restrict_all>
-the restriction request will be silently ineffective!
-
-=item
-
-The mechanisms used are not effective against
-denial of service problems.
-A compromised qemu can probably still impair
-or perhaps even prevent
-the proper functioning of the whole system,
-(at the very least, but not limited to,
-through resource exhaustion).
-
-=item
-
-It is not known whether the protection is
-effective when a domain is migrated.
-
-=item
-
-Some domain management functions do not work.
-For example, cdrom insert will fail.
-
-=item
+=item B<device_model_user=USERNAME>
 
-You should say C<vga="none">.
-Domains with stdvga graphics cards to not work.
-Domains with cirrus vga may seem to work.
+When running dm_restrict, run the device model as this user.
 
-=item
+NOTE: Each domain MUST have a SEPARATE username.
 
-You must create user(s) for qemu to run as.
-
-Ideally, set aside a range of 32752 uids
-(from N to N+32751)
-and create a user
-whose name is B<xen-qemuuser-range-base>
-and whose uid is N
-and whose gid is a plain unprivileged gid.
-libxl will use one such user for each domid.
-
-Alternatively, either create
-B<xen-qemuuser-domid$domid>
-for every $domid from 1 to 32751 inclusive,
-or
-B<xen-qemuuser-shared>
-(in which case different guests will not
-be protected against each other).
-
-=item
-
-There are no countermeasures taken against reuse
-of the same unix user (uid)
-for subsequent domains,
-even if the B<xen-qemuuser-domid$domid> users are created.
-So a past domain with the same domid may be able to
-interferer with future domains.
-Possibly, even after a reboot.
-
-=item
-
-A compromised qemu will be able to read world-readable
-files in the dom0 operating system.
-
-=item
-
-Because of these limitations, this functionality,
-while it may enhance your security,
-should not be relied on.
-Any further limitations discovered in the current version
-will B<not> be handled via the Xen Project Security Process.
-
-=item
-
-In the future as we enhance this feature to improve the security,
-we may break backward compatibility.
-
-=back
+See docs/features/qemu-depriv.pandoc for more information.
 
 =item B<vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]>
 
-- 
2.20.1


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel