update rule prefixes with basic info

Add basic info about rule prefixes

Signed-off-by: John Johansen <john.johansen@canonical.com>

rule-prefixes-and-modes.md

@@ -1 +1,141 @@
-foo
+# AppArmor Rule Prefixes and Modes
+
+Rule qualifiers allow modifying the behavior of individual
+profile rules. There are qualifiers for setting the rule mode, priority,
+and qualifiers that modify the rules audit behavior.
+
+
+## Rule Modes
+
+Rule mode allow controlling the enforcement behavior of a profile rule.
+The default is to make the rule an ```allow``` rule if no mode qualifier
+is specified.
+
+* **allow** - The default mode, the qualifier is optional. For a given
+       action is the rule matches the action will be allowed. The
+       default audit action of an allow rule is to NOT audit that the
+       action was allowed.
+
+* **deny** - For a given action, if the rule is matched, permission the
+       action will be denied, with an EACCES or EPERM error code returned
+       to userspace, and by default the violation will be logged with a tag
+       of the access being DENIED.
+
+       Within a given priority level deny rules have priority over all
+       other rule modes. They can be used to carve out permissions from
+       an allow rule of the same priority.
+       
+* **kill** (**new** AppArmor 4.0) - This is a variant of enforce deny where
+       in addition to returning I<EACCES> or I<EPERM> for a violation, the
+       task is also sent a signal to kill it. Within a given priority level
+       kill rules have priority over deny rules.
+
+* **complain** (**new** AppArmor 4.0) - For a given action, if the rule
+       is matched the action will be allowed, but the violation will be
+       logged with a tag of the access being ALLOWED (similar to the
+       complain mode profile flag).
+
+* **prompt** (**new** AppArmor 4.0) - This is a variant of complain rule
+       mode where the access request is sent to a user space daemon to
+       determine if it is allowed. This only works with select rules and
+       only if supported by the kernel. If the usespace daemon is not
+       present the access request will be denied.
+
+* **access** (**new** AppArmor 4.0**) - This mode declares the rule as
+       an audit modifier to other rules. It allows setting broad audit
+       controls without granting or denying permission.
+
+
+## audit control for rules
+
+* **audit** -
+* **quiet** -
+
+## rule priority
+
+The priority qualifer allows raising and lowering the priority of a
+rule so it can override another rule when/where they overlap. Rules
+of the same priority will accumulate permissions in a declarative
+manner as they have always done. But when two rules overlap with a
+different priority the higher priority permission are used for the
+overlapping portion of the rule.
+
+If a priority is not specified the default priority is 0.
+
+* **priority=X** (**new** AppArmor 4.0) - allows specifying the priority
+        for a given rule. The priority can be possitive or negative. The
+	priority if specified comes before the audit and rule mode qualifiers.
+	
+
+```
+priority=10 audit allow file rw @{HOME}/.ssh/*.pub,
+deny file @{HOME}/.ssh/*,
+```
+
+### Priority and rule blocks
+
+#### Priority overlap will only determine permission for the set of rules
+       within the rule block. The block of rules will then be treated
+       as a whole as a single rule.
+
+Eg.
+```
+profile Eg. {
+        deny file w /foo/bar,
+
+        {
+                priority=2 allow file rw /foo/**,
+                deny file rw /**,
+        }
+}
+```
+
+In this example the ```deny file w /foo/bar``` in the profile block will
+take priority over the ```priority=2 allow file rw /foo/**``` rule in
+the block, because the whole block at the profile level has the same
+priority as the ```deny file w /foo/bar``` rule.
+
+Within the block however the ```priority=2 allow file rw /foo/**``` has
+priority over the deny rule.
+
+If the rule block should be treated with a different priority the
+priority qualifier can be added to the rule block.
+
+```
+priority=2 {
+
+}
+```
+
+
+
+## ordered block qualifier
+
+* **ordered ** (**new** AppArmor 4.0) - The ordered block qualifier
+       allows a block of rules to be treated as an ordered set of
+       rules where the first rule matched will be applied. This block
+       allows specifying rules in a manner similar to many firewalls
+       and as such may be more natural for some network rules. Rules
+       within an ordered block do not accumumate permissions the way a
+       normal appamor declarative block does.
+
+       The ordered block effectively gives each rule in the block a
+       unique priority with the first rule having the highest priority
+       and each following rule a lower priority.
+
+       The priority qualifier is not allowed within an ordered block.
+
+```
+profile Eg {
+
+       ordered {
+           allow network inet stream,
+	   deny network tcp,
+
+       }
+}
+```
+
+In this example the ```network inet stream``` rule will have priority over
+the ```deny network tcp``` rule even though normally the deny rule would
+dominate and disallow the access.