mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 16:35:02 +01:00
c48d7dc71f
This patch adds a 'check_pod_files' make target to the common make
rules, and then fixes the errors it highlighted as well as most of
the warnings. It will cause 'make check' in most of the directories to
fail if there are errors in a pod file (but not if there are warnings).
Common issues were:
- using an '=over/=back' pair for code-like snippets that did not
contain any =items therein; the =over keyword is intended for
indenting lists of =item entries, and generates a warning if
there isn't any.
- not escaping '<' or '>'
- blank lines that contained spaces or tabs
The second -warnings flag passed to podchecker is to add additional
warnings, un-escaped '<' and '>' being of them.
I did not fix all of the warnings in apparmor.d.pod, as I have not come
up with a good warning-free way to express the BNF of the language
similar in format to what is currently generated. The existing
libapparmor warnings (complaints about duplicate =item definition
names) are actually a result of passing the second -warnings flag.
The integration into libapparmor is suboptimal due to automake's
expectation that there will be a test driver program(s) for make check
targets; that's why I added the podchecker call to the manpage
generation point.
Signed-off-by: Steve Beattie <steve@nxnw.org>
Acked-by: Seth Arnold <seth.arnold@canonical.com>
---
changehat/mod_apparmor/Makefile | 3
changehat/mod_apparmor/mod_apparmor.pod | 28 ++-
common/Make.rules | 4
libraries/libapparmor/doc/Makefile.am | 7
parser/Makefile | 2
parser/apparmor.d.pod | 275
+++++++++++++-------------------
utils/Makefile | 3
utils/aa-cleanprof.pod | 2
utils/aa-complain.pod | 2
utils/aa-decode.pod | 2
utils/aa-easyprof.pod | 69 +++-----
utils/aa-enforce.pod | 2
utils/aa-genprof.pod | 2
utils/aa-logprof.pod | 6
utils/aa-sandbox.pod | 64 ++-----
utils/logprof.conf.pod | 2
utils/vim/Makefile | 2
17 files changed, 212 insertions(+), 263 deletions(-)
145 lines
5.4 KiB
Text
145 lines
5.4 KiB
Text
# This publication is intellectual property of Novell Inc. and Canonical
|
|
# Ltd. Its contents can be duplicated, either in part or in whole, provided
|
|
# that a copyright label is visibly located on each copy.
|
|
#
|
|
# All information found in this book has been compiled with utmost
|
|
# attention to detail. However, this does not guarantee complete accuracy.
|
|
# Neither SUSE LINUX GmbH, Canonical Ltd, the authors, nor the translators
|
|
# shall be held liable for possible errors or the consequences thereof.
|
|
#
|
|
# Many of the software and hardware descriptions cited in this book
|
|
# are registered trademarks. All trade names are subject to copyright
|
|
# restrictions and may be registered trade marks. SUSE LINUX GmbH
|
|
# and Canonical Ltd. essentially adhere to the manufacturer's spelling.
|
|
#
|
|
# Names of products and trademarks appearing in this book (with or without
|
|
# specific notation) are likewise subject to trademark and trade protection
|
|
# laws and may thus fall under copyright restrictions.
|
|
#
|
|
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
mod_apparmor - fine-grained AppArmor confinement for Apache
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
An AppArmor profile applies to an executable program; if a portion of
|
|
the program needs different access permissions than other portions,
|
|
the program can "change hats" via aa_change_hat(2) to a different role,
|
|
also known as a subprofile. The mod_apparmor Apache module uses the
|
|
aa_change_hat(2) mechanism to offer more fine-grained confinement of dynamic
|
|
elements within Apache such as individual php and perl scripts, while
|
|
still allowing the performance benefits of using mod_php and mod_perl.
|
|
|
|
To use mod_apparmor with Apache, ensure that mod_apparmor is configured to
|
|
be loaded into Apache, either via a2enmod, yast or manual editing of the
|
|
apache2(8)/httpd(8) configuration files, and restart Apache. Make sure that
|
|
apparmor is also functioning.
|
|
|
|
Once mod_apparmor is loaded within Apache, all requests to Apache will
|
|
cause mod_apparmor to attempt to change into a hat that matches the
|
|
ServerName for the server/vhost. If no such hat is found, it will
|
|
first fall back by attempting to change into a hat composed of the
|
|
ServerName-URI (e.g. "www.example.com-/app/some.cgi"). If that hat
|
|
is not found, it will fall back to attempting to use the hat named
|
|
by the URI (e.g. "/app/some.cgi"). If that hat is not found, it will
|
|
fall back to attempting to use the hat DEFAULT_URI; if that also does
|
|
not exist, it will fall back to using the global Apache profile. Most
|
|
static web pages can simply make use of the DEFAULT_URI hat.
|
|
|
|
Additionally, before any requests come in to Apache, mod_apparmor
|
|
will attempt to change hat into the HANDLING_UNTRUSTED_INPUT hat.
|
|
mod_apparmor will attempt to use this hat while Apache is doing the
|
|
initial parsing of a given http request, before its given to a specific
|
|
handler (like mod_php) for processing.
|
|
|
|
Because defining hats for every URI/URL often becomes tedious, mod_apparmor
|
|
provides the AAHatName and AADefaultHatName Apache configuration options.
|
|
|
|
=over 4
|
|
|
|
=item B<AAHatName>
|
|
|
|
AAHatName allows you to specify a hat to be used for a given Apache
|
|
E<lt>DirectoryE<gt>, E<lt>DirectoryMatchE<gt>, E<lt>LocationE<gt> or
|
|
E<lt>LocationMatchE<gt> directive (see the Apache documenation for more
|
|
details). Note that mod_apparmor behavior can become confused if
|
|
E<lt>Directory*E<gt> and E<lt>Location*E<gt> directives are intermingled
|
|
and it is recommended to use one type of directive. If the hat specified by
|
|
AAHatName does not exist in the Apache profile, then it falls back to the
|
|
behavior described above.
|
|
|
|
=item B<AADefaultHatName>
|
|
|
|
AADefaultHatName allows you to specify a default hat to be used for
|
|
virtual hosts and other Apache server directives, so that you can have
|
|
different defaults for different virtual hosts. This can be overridden
|
|
by the AAHatName directive and is checked for only if there isn't
|
|
a matching AAHatName. The default value of AADefaultHatName is the
|
|
ServerName for the server/vhost configuration. If the AADefaultHatName
|
|
hat does not exist, then it falls back to the behavior described above.
|
|
|
|
=back
|
|
|
|
=head1 URI REQUEST SUMMARY
|
|
|
|
When profiling with mod_apparmor, it is helpful to keep the following order
|
|
of operations in mind:
|
|
|
|
On each URI request, mod_apparmor will first aa_change_hat(2) into
|
|
^HANDLING_UNTRUSTED_INPUT, if it exists.
|
|
|
|
Then, after performing the initial parsing of the request, mod_apparmor
|
|
will:
|
|
|
|
=over 4
|
|
|
|
=item 1
|
|
|
|
try to aa_change_hat(2) into a matching AAHatName hat if it exists and
|
|
applies, otherwise it will
|
|
|
|
=item 2
|
|
|
|
try to aa_change_hat(2) into an AADefaultHatName hat, either the
|
|
ServerName (the default) or the configuration value specified by the
|
|
AADefaultHatName directive, for the server/vhost, otherwise it will
|
|
|
|
=item 3
|
|
|
|
try to aa_change_hat(2) into the ServerName-URI, otherwise it will
|
|
|
|
=item 4
|
|
|
|
try to aa_change_hat(2) into the URI itself, otherwise it will
|
|
|
|
=item 5
|
|
|
|
try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it
|
|
will
|
|
|
|
=item 6
|
|
|
|
fall back to the global Apache policy
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
mod_apparmor() currently only supports apache2, and has only been tested
|
|
with the prefork MPM configuration -- threaded configurations of Apache
|
|
may not work correctly. For Apache 2.4 users, you should enable the mpm_prefork
|
|
module.
|
|
|
|
There are likely other bugs lurking about; if you find any, please report
|
|
them at L<https://bugs.launchpad.net/apparmor/+filebug>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
apparmor(7), subdomain.conf(5), apparmor_parser(8), aa_change_hat(2) and
|
|
L<http://wiki.apparmor.net>.
|
|
|
|
=cut
|