Xen devel - Jan 2012 - [PATCH] xl.pod.1: introduction to FLASK

Add a simple introduction to FLASK to the xl man page, at the beginning
of the FLASK chapter. Link to the xsm-flask.txt document.
Currently FLASK, TMEM and PCI PASS-THROUGH are defined as =head2 so they
look like sub-chapters of VIRTUAL DEVICE COMMANDS. Make them =head1.

Based on a text written by Daniel De Graaf.

Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>

diff --git a/docs/man/xl.pod.1 b/docs/man/xl.pod.1
index 17789b4..18fd411 100644
--- a/docs/man/xl.pod.1
+++ b/docs/man/xl.pod.1
@@ -906,7 +906,7 @@ List virtual network interfaces for a domain.
 
 =back
 
-=head2 PCI PASS-THROUGH
+=head1 PCI PASS-THROUGH
 
 =over 4
 
@@ -929,7 +929,7 @@ List pass-through pci devices for a domain.
 
 =back
 
-=head2 TMEM
+=head1 TMEM
 
 =over 4
 
@@ -995,7 +995,20 @@ Get information about how much freeable memory (MB) is
in-use by tmem.
 
 =back
 
-=head2 FLASK
+=head1 FLASK
+
+B<FLASK> is a security framework that defines a mandatory access control
policy
+providing fine-grained controls over Xen domains, allowing the policy writer
+to define what interactions between domains, devices, and the hypervisor are
+permitted. Some example of what you can do using XSM/FLASK:
+ - Prevent two domains from communicating via event channels or grants
+ - Control which domains can use device passthrough (and which devices)
+ - Restrict or audit operations performed by privileged domains
+ - Prevent a privileged domain from arbitrarily mapping pages from other
+   domains.
+
+You can find more details on how to use FLASK and an example security
+policy here: L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
 
 =over 4
 
@@ -1039,6 +1052,7 @@ And the following documents on the xen.org website:
 
 L<http://xenbits.xen.org/docs/unstable/misc/xl-network-configuration.html>
 L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>
+L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
 
 =head1 BUGS

Stefano Stabellini writes ("[Xen-devel] [PATCH] xl.pod.1: introduction to
FLASK"):
> Based on a text written by Daniel De Graaf.
We therefore need a signoff from Daniel too.
> Signed-off-by: Stefano Stabellini <stefano.stabellini@eu.citrix.com>
And that is therefore a lie.

Can I remind everyone that writing "Signed-off-by" is not a mere
formality, where you just rubber-stamp your own name.  If you wrote
the whole thing and you (your company) wants to submit it, fine.

But if any of it was written by anyone else then you need their
signoff too.

Ian.

On 01/05/2012 01:48 PM, Ian Jackson wrote:
> Stefano Stabellini writes ("[Xen-devel] [PATCH] xl.pod.1: introduction
to FLASK"):
>> Based on a text written by Daniel De Graaf.
> 
> We therefore need a signoff from Daniel too.
Signed-off-by: Daniel De Graaf <dgdegra@tycho.nsa.gov>
>> Signed-off-by: Stefano Stabellini
<stefano.stabellini@eu.citrix.com>
> 
> And that is therefore a lie.
> 
> Can I remind everyone that writing "Signed-off-by" is not a mere
> formality, where you just rubber-stamp your own name.  If you wrote
> the whole thing and you (your company) wants to submit it, fine.
> 
> But if any of it was written by anyone else then you need their
> signoff too.
> 
> Ian.
> 
-- 
Daniel De Graaf
National Security Agency

Daniel De Graaf writes ("Re: [Xen-devel] [PATCH] xl.pod.1: introduction to
FLASK"):
> Signed-off-by: Daniel De Graaf <dgdegra@tycho.nsa.gov>
Thanks, I''ve applied the patch from Stefano''s mail.

Ian.