[apparmor] [patch] manual page for aa-genprof

[Andrew Clausen]

Hi all,

I changed the aa-genprof man page to:
 * give more of an overview of how aa-genprof fits into the AppArmor
ecosystem, and
 * explain where to get more information about using aa-genprof (i.e.
aa-logprof(8) and apparmor.d(5)), and why.

Cheers,
Andrew

diff --git a/utils/aa-genprof.pod b/utils/aa-genprof.pod
index 971794e..e99e33c 100644
--- a/utils/aa-genprof.pod
+++ b/utils/aa-genprof.pod
@@ -38,28 +38,35 @@ B<-d --dir /path/to/profiles>

 =head1 DESCRIPTION

-When running aa-genprof, you must specify a program to profile.  If the
+aa-genprof is a user-friendly tool for creating AppArmor security profiles.  A
+security profile specifies what behaviors of an application are normal, so that
+all abnormal behaviors may be forbidden later with aa-enforce(8).  Ideally,
+aa-genprof would automatically learn what behaviors are normal by watching the
+application run.  Instead, aa-genprof watches the application run, and asks the
+user for help in defining what consists of normal behavior.
+
+When running aa-genprof, you must specify an application to profile.  If the
 specified program is not a fully-qualified path, aa-genprof will search $PATH
-in order to find the program.
+in order to find the application.

-If a profile does not exist for the program, aa-genprof will create one using
-aa-autodep(1).
+If a profile does not exist for the application, aa-genprof will create one
+using aa-autodep(1).

 Genprof will then:

-   - set the profile to complain mode
+   - set the profile to complain mode, so that all behaviors are permitted but
+   logged, and

-   - write a mark to the system log
-
-   - instruct the user to start the application to
-     be profiled in another window and exercise its functionality
+   - instruct the user to use the application in another window and exercise
+   its normal functionality.

 It then presents the user with two options, (S)can system log for entries
 to add to profile and (F)inish.

-If the user selects (S)can or hits return, aa-genprof will parse
-the complain mode logs and iterate through generated violations
-using aa-logprof(1).
+If the user selects (S)can or hits return, aa-genprof will parse the complain
+mode logs and ask the user whether the policy violations are normal behaviors
+that should be permitted.  This step is based on aa-logprof(1), and that manual
+page contains more information about the process.

 After the user finishes selecting profile entries based on violations
 that were detected during the program execution, aa-genprof will reload
@@ -77,6 +84,11 @@ L<http://https://bugs.launchpad.net/apparmor/+filebug>.

 =head1 SEE ALSO

+aa-genprof is a thin wrapper around aa-logprof(8), and that manual page
+contains more information about using aa-genprof to create AppArmor security
+profiles.  In addition, the manual page for apparmor.d(5) is recommended
+for understanding the concepts in AppArmor security profiles.
+
 apparmor(7), apparmor.d(5), aa-enforce(1), aa-complain(1), aa-disable(1),
 aa_change_hat(2), aa-logprof(1), logprof.conf(5), and
 L<http://wiki.apparmor.net>.