# 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 named by the URI
(e.g. /app/some.cgi). If no such hat is found, it will first fall
back by attempting to change into a hat that matches the ServerName
for the server/vhost. 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>DirectoryMatch>, 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 or hat named by the URI. The default
value of AADefaultHatName is the ServerName for the server/vhost
configuration. If the AADefaultHatName hat does not exist, it falls
back to the DEFAULT_URI hat if it exists (as 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 2

1. try to aa_change_hat(2) into a matching AAHatName hat if it exists and
applies, otherwise it will

2. try to aa_change_hat(2) into the URI itself, otherwise it will

3. 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

4. try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it
will

5. 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.

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