docs: Fix dm_restrict documentation

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@citrix.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>

diff --git a/docs/features/qemu-deprivilege.pandoc b/docs/features/qemu-deprivilege.pandoc
index 20d6ac2189604325b0fce35568cede4a25eec59f..cfe528b1d39f2ed02e57eda2f1d3d2fcce4ed885 100644 (file)
--- 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 3b92f39d8d5c7730c3390ad87c97d8400ad0bd51..ad81af1ed8cc983c76b5ec2c3aa02e28f042cc63 100644 (file)
--- 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, ... ]>