[apparmor] [PATCH] parser: Document pivot_root in the apparmor.d(5) man page

[Tyler Hicks]

This patch separates pivot_root rules from mount rules, since the syntax
of the two types of rules is very different. It also documents the
missing "oldroot=" prefix required for the conditional corresponding to
the put_old parameter. Finally, it briefly describes pivot_root rules
and provides some examples.

Signed-off-by: Tyler Hicks <tyhicks at canonical.com>
---
 parser/apparmor.d.pod | 55 ++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 44 insertions(+), 11 deletions(-)

diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod
index 853cd5c..ff7887d 100644
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -3,7 +3,7 @@
 #                  2008, 2009
 #    NOVELL (All rights reserved)
 #
-#    Copyright (c) 2010 - 2013
+#    Copyright (c) 2010 - 2014
 #    Canonical Ltd. (All rights reserved)
 #
 #    This program is free software; you can redistribute it and/or
@@ -54,7 +54,7 @@ B<COMMENT> = '#' I<TEXT>
 
 B<TEXT> = any characters
 
-B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<DBUS RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<PIVOT ROOT RULE> | I<DBUS RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
 
 B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
 
@@ -75,7 +75,7 @@ B<PROGRAMHAT> = '^'  (non-whitespace characters; see aa_change_hat(2) for a desc
 
 B<PROGRAMCHILD> = I<SUBPROFILE> name
 
-B<MOUNT RULE> = ( I<MOUNT> | I<REMOUNT> | I<UMOUNT> | I<PIVOT ROOT> )
+B<MOUNT RULE> = ( I<MOUNT> | I<REMOUNT> | I<UMOUNT> )
 
 B<MOUNT> = [ 'audit' ] [ 'deny' ] 'mount' [ I<MOUNT CONDITIONS> ] [ I<SOURCE FILEGLOB> ] [ -> [ I<MOUNTPOINT FILEGLOB> ]
 
@@ -83,8 +83,6 @@ B<REMOUNT> = [ 'audit' ] [ 'deny' ] 'remount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOI
 
 B<UMOUNT> = [ 'audit' ] [ 'deny' ] 'umount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
 
-B<PIVOT ROOT> = [ 'audit' ] [ 'deny' ] pivot_root [ I<OLD ABS PATH> ] [ I<MOUNTPOINT ABS PATH> ] [ -> I<PROGRAMCHILD> ]
-
 B<MOUNT CONDITIONS> = [ ( 'fstype' | 'vfstype' ) ( '=' | 'in' ) I<MOUNT FSTYPE EXPRESSION> ] [ 'options' ( '=' | 'in' ) I<MOUNT FLAGS EXPRESSION> ]
 
 B<MOUNT FSTYPE EXPRESSION> = ( I<MOUNT FSTYPE LIST> | I<MOUNT EXPRESSION> )
@@ -99,6 +97,8 @@ B<MOUNT FLAGS> = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec'
 
 B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
 
+B<PIVOT ROOT RULE> = [ 'audit' ] [ 'deny' ] pivot_root [ oldroot=I<OLD PUT FILEGLOB> ] [ I<NEW ROOT FILEGLOB> ] [ -> I<PROGRAMCHILD> ]
+
 B<DBUS RULE> = ( I<DBUS MESSAGE RULE> | I<DBUS SERVICE RULE> | I<DBUS EAVESDROP RULE> | I<DBUS COMBINED RULE> )
 
 B<DBUS MESSAGE RULE> = [ 'audit' ] [ 'deny' ] 'dbus' [ I<DBUS ACCESS EXPRESSION> ] [ I<DBUS BUS> ] [ I<DBUS PATH> ] [ I<DBUS INTERFACE> ] [ I<DBUS MEMBER> ] [ I<DBUS PEER> ]
@@ -384,12 +384,12 @@ eg.
 
 AppArmor supports mount mediation and allows specifying filesystem types and
 mount flags. The syntax of mount rules in AppArmor is based on the mount(8)
-command syntax. Mount rules must contain one of the mount, remount, umount or
-pivot_root keywords, but all mount conditions are optional. Unspecified
-optional conditionals are assumed to match all entries (eg, not specifying
-fstype means all fstypes are matched). Due to the complexity of the mount
-command and how options may be specified, AppArmor allows specifying
-conditionals three different ways:
+command syntax. Mount rules must contain one of the mount, remount or umount
+keywords, but all mount conditions are optional. Unspecified optional
+conditionals are assumed to match all entries (eg, not specifying fstype means
+all fstypes are matched). Due to the complexity of the mount command and how
+options may be specified, AppArmor allows specifying conditionals three
+different ways:
 
 =over 4
 
@@ -655,6 +655,39 @@ $ mount -o nodev,user /dev/foo /mnt
 
 =back
 
+=head2 Pivot Root Rules
+
+AppArmor mediates changing of the root filesystem through the pivot_root(2)
+system call. The syntax of 'pivot_root' rules in AppArmor is based on the
+pivot_root(2) system call parameters with the notable exception that the
+ordering is reversed. The path corresponding to the put_old parameter of
+pivot_root(2) is optionally specified in the 'pivot_root' rule using the
+'oldroot=' prefix.
+
+AppArmor 'pivot_root' rules can specify a profile transition to occur during
+the pivot_root(2) system call. Note that AppArmor will only transition the
+process calling pivot_root(2) to the new profile.
+
+Here are some example 'pivot_root' rules:
+
+    # Allow any pivot
+    pivot_root,
+
+    # Allow pivoting to any new root directory and putting the old root
+    # directory at /mnt/root/old/
+    pivot_root oldroot=/mnt/root/old/,
+
+    # Allow pivoting the root directory to /mnt/root/
+    pivot_root /mnt/root/,
+
+    # Allow pivoting to /mnt/root/ and putting the old root directory at
+    # /mnt/root/old/
+    pivot_root oldroot=/mnt/root/old/ /mnt/root/,
+
+    # Allow pivoting to /mnt/root/, putting the old root directory at
+    # /mnt/root/old/ and transition to the /mnt/root/sbin/init profile
+    pivot_root oldroot=/mnt/root/old/ /mnt/root/ -> /mnt/root/sbin/init,
+
 =head2 DBus rules
 
 AppArmor supports DBus mediation. The mediation is performed in conjunction
-- 
1.9.1