[apparmor] PATCH: apparmor.d man page

[Christian Boltz]

Hello,

Am Donnerstag, 9. Juni 2016, 00:47:30 CEST schrieb John Johansen:
> Add documentation of the profile flags and how to debug apparmor
> policy to the apparmor.d man page
> 
> v2. Added in most of Seth and Christians feedback
> 
> ---
> 
> === modified file 'parser/apparmor.d.pod'
> --- parser/apparmor.d.pod	2016-06-01 20:55:14 +0000
> +++ parser/apparmor.d.pod	2016-06-09 07:43:10 +0000
> @@ -299,6 +299,91 @@
>  written or modified to use change_profile(2) transition permanently
> to the specified profile. libvirt is one such application.
> 
> +=head2 Profile Flags
> +
> +The profile flags allow for quick global control over profile
> behavior +and some override rule qualifiers allowing for quick global
> changes +for profile debugging or development. While multiple profile
> flags can +be specified some of the flags conflict (see below).
> +
> +If profile flags are not specified a the default flag set will be

... not specified_,__ the default ...

> +  flags=(enforce, namespace_relative, no_attach_disconnected)
> +
> +=over 8
> +
> +=head3 Profile Audit Flags
> +
> +=item B<audit>
> +places the profile in audit mode which will cause all allowed
> accesses to +be audited. This is equivalent to placing the audit
> qualifier on all +allow rules in the profile.

See the comment in my other mail for deny rules - but if this 
description matches the current behaviour, it's OK _for now_.

> +=item B<debug>
> +removed in apparmor 2.5 and may result in a parse error (tested on
> 2.8), +See below I<Debugging AppArmor Policy> for other options.

I'd completely get rid of mentioning the debug flag - 2.5 is ooooold and 
hopefully not used anymore ;-)

> +=head3 Profile Mode Flags
> +
> +The profile mode flags conflict with each other, so you can't use
> more +than one. If no profile mode flags the default value of

... If no profile mode _flag is specified,_ the default ...
("flag" instead of "flags" because we allow only one, + "is specified")

> I<enforce> will +be used.
> +
> +=item B<complain> -- conflicts with allow, enforce, kill, stop

That's what I meant with "you should use 'conflicts with other profile 
mode flags'" - without the documentation of the not-yet-existing allow, 
kill and stop flags, the conflicts list looks funny[tm]

> +places the profile in complain mode which will cause all unknown
> accesses +to be audited and allowed. Complain mode is used for
> profile development +so that unknown accesses can be logged without
> affecting program behavior +as the default white listing behavior
> would.
> +
> +Note that deny rules will be enforced even in complain mode. The
> auditing +and quieting of existing allow and deny rules will be
> applied, so known +accesses and denials will not show up in the audit
> stream (unless the +rule contains B<audit>).
> +
> +Note: there is a known bug where rules with a prefix with B<audit
> deny> will +be treated as unknown accesses.
> +
> +=item B<enforce> DEFAULT -- conflicts with allow, complain, stop,
> kill +The default profile mode, if no profile mode flag is specified.

The conflicts list needs to be shortened, see above.

...
> +=head1 Debugging AppArmor Policy
> +
> +=over 4
> +
> +In addition to setting profile mode flags AppArmor provides a few
> global +controls that can help in debugging how policy is being
> enforced. To use +these controls the policy author must have
> sufficient privilege to +manage policy for the namespace.
> +
> +The most useful are the I<noquiet> audit value, and turning on the
> +debug parameters. These two values should suffice in most situations.
> +The setting these values and the full set of possible parameters are
> +documented below.

The setting_s of_ these values... (sounds better, but still strange - 
what exactly do you mean with this sentence?)

...
> +=head2 sys/module/apparmor/parameters/mode

_/_sys/...

> +The mode parameter allows overriding the profiles enforcement mode.
> +
> +=item B<enforce> - enfoce profile as specified by its flags

...enfo_r_ce profile...


With these things fixed (or not fixed for a good reason ;-)
    Acked-by: Christian Boltz <apparmor at cboltz.de>



Regards,

Christian Boltz
-- 
Bill Gates bei einer Privataudienz beim Papst: "Ich biete 100 Millionen
Dollar, wenn das "Vater unser" geändert wird." - "Was haben Sie sich
vorgestellt?" - "Es soll heißen: Unser tägliches Windows gib uns heute."
Der Papst denkt kurz nach, greift zum Haustelefon: "Sofort den Vertrag
beim Bäcker kündigen!"
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20160609/159ce2d3/attachment.pgp>