[apparmor] [Patch] update apparmor_parser man page

Mon Aug 13 19:16:05 UTC 2012

On Wed, Aug 08, 2012 at 08:00:04PM -0700, John Johansen wrote:
> Rework and update the apparmor_parser man page. It reworks some of the
> text but mostly just reorganizes the commands and options into logical
> grouping to make it easier to sort out how the various commands and
> options work.
> 
> Signed-off-by: John Johansen <john.johansen at canonical.com>

A nice improvement. A couple of comments inline follow.

> === modified file 'parser/apparmor_parser.pod'
> --- parser/apparmor_parser.pod	2012-02-24 12:21:59 +0000
> +++ parser/apparmor_parser.pod	2012-08-09 02:55:02 +0000
> @@ -28,22 +28,99 @@
>  
>  =head1 SYNOPSIS
>  
> -B<apparmor_parser [-adrR] [--add] [--debug]  [--replace] [--remove]
> -                  [--preprocess] [--Include n] [--base n] [ --Complain ]>
> +B<apparmor_parser [options] E<lt>commandE<gt> [profile]...>
> +
> +B<apparmor_parser [options] E<lt>commandE<gt>>
>  
>  B<apparmor_parser [-hv] [--help] [--version]>
>  
>  =head1 DESCRIPTION
>  
> -B<apparmor_parser> is used to import new apparmor.d(5) profiles
> -into the Linux kernel. The profiles restrict the operations available
> -to processes by executable name.
> +B<apparmor_parser> is used as a general tool to compile, and manage AppArmor
> +policy, including loading new apparmor.d(5) profiles into the Linux kernel.
> +
> +AppArmor profiles restrict the operations available to processes.
>  
>  The profiles are loaded into the Linux kernel by the B<apparmor_parser>
> -program, which takes its input from standard input. The input supplied to
> -B<apparmor_parser> should be in the format described in apparmor.d(5).
> -
> -=head1 OPTIONS
> +program, which by default takes its input from standard input. The input
> +supplied to B<apparmor_parser> should be in the format described in
> +apparmor.d(5).
> +
> +=head1 COMMANDS
> +
> +The command set is broken into four subcategories.
> +
> +=over 4
> +
> +=item unprivileged commands
> +
> +Commands that don't require any privilege and don't operate on profiles.
> +
> +=item unprivileged profile commands
> +
> +Commands that operate on a profile either specified on the command line or
> +read from stdin if no profile was specified.
> +
> +=item privileged commands
> +
> +Commands that require the MAC_ADMIN capability within the affected apparmor
> +policy namespace to load policy into the kernel or filesystem write
> +permissions to update the affected privileged files (cache etc).
> +
> +=item privileged profile commands
> +
> +Commands that require privilege and operate on profiles.
> +
> +=back
> +
> +=head1 Unprivileged commands
> +
> +=over 4
> +
> +=item -V, --version
> +
> +Print the version number and exit.
> +
> +=item -h, --help
> +
> +Give a quick reference guide.
> +
> +=back
> +
> +=head1 Unprivileged profile commands
> +
> +=over 4
> +
> +=item -N, --names
> +
> +Produce a list of policies from a given set of profiles (implies -K).
> +
> +=item -p, --preprocess
> +
> +Dump the input profile to stdout out applying preprocessing flattening
> +includes into the output profile.

This reads awkwardly. Perhaps:

  Apply preprocessing to the input profile by flattening includes
  into the output profile and dump to stdout.

(Preprocessing doesn't do anything besides flatten includes, IIRC?)

> +
> +=item -S, --stdout
> +
> +Writes a binary (cached) profile to stdout (implies -K and -T).
> +
> +=item -o file, --ofile file
> +
> +Writes a binary (cached) profile to the specified file (implies -K and -T)
> +
> +=back
> +
> +=head1 Privileged commands
> +
> +=over 4
> +
> +=item --purge-cache
> +
> +Unconditionally clear out cached profiles.
> +
> +=back
> +
> +=head1 Privileged profile commands
>  
>  =over 4
>  
> @@ -67,25 +144,20 @@
>  in apparmor.d(5) even though the contents of the definition aren't
>  used.
>  
> +=item -B, --binary
> +
> +Load a binary (cached) profile, as produced with the -S or -o options
> +(implies -K and -T).

Might want to reiterate that the binary profile is read from stdin. Or
am I confused as to where it takes the binary blob from?

> +
> +=back
> +
> +=head1 OPTIONS
> +
> +=over 4
> +
>  =item -C, --Complain
>  
> -For the profile to load in complain mode.
> -
> -=item -B, --binary
> -
> -Load a binary (cached) profile, as produced with the -S option.
> -
> -=item -N, --names
> -
> -Produce a list of policies from a given set of profiles (implies -K).
> -
> -=item -S, --stdout
> -
> -Writes a binary (cached) profile to stdout (implies -K and -T).
> -
> -=item -o file, --ofile file
> -
> -Writes a binary (cached) profile to the specified file (implies -K and -T)
> +Force the profile to load in complain mode.
>  
>  =item -b n, --base n
>  
> @@ -138,6 +210,11 @@
>  is running with "--replace", it may make sense to also use
>  "--skip-read-cache" with the "--write-cache" option.
>  
> +=item --skip-bad-cache
> +
> +Skip updating the cache if it contains cached profiles in a bad or
> +inconsistant state
> +
>  =item -L, --cache-loc
>  
>  Set the location of the cache directory.  If not specified the cache location
> @@ -149,6 +226,9 @@
>  This is useful for testing profile generation, caching, etc, without making
>  changes to the running kernel profiles.
>  
> +This also removes the need for privilege to execute the commands that
> +manage policy in the kernel
> +
>  =item -q, --quiet
>  
>  Do not report on the profiles as they are loaded, and not show warnings.
> @@ -157,15 +237,6 @@
>  
>  Report on the profiles as they are loaded, and show warnings.
>  
> -=item -V, --version
> -
> -Print the version number and exit.
> -
> -=item -p, --preprocess
> -
> -Dump the input profile to stdout out applying preprocessing flattening
> -includes into the output profile.
> -
>  =item -d, --debug
>  
>  Given once, only checks the profiles to ensure syntactic correctness.
> @@ -198,10 +269,6 @@
>  Use --help=optimize to see a full list of which optimization flags are
>  supported.
>  
> -=item -h, --help
> -
> -Give a quick reference guide.
> -
>  =back
>  
>  =head1 CONFIG FILE
> 
> 
> -- 
> AppArmor mailing list
> AppArmor at lists.ubuntu.com
> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor

-- 
Steve Beattie
<sbeattie at ubuntu.com>
http://NxNW.org/~steve/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20120813/fa98b9b9/attachment.pgp>