mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 08:24:42 +01:00
c386d93581
Move suggested bug reporting from launchpad to gitlab Signed-off-by: John Johansen <john.johansen@canonical.com> Acked-by: Steve Beattie <steve.beattie@canonical.com>
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 documentation 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://gitlab.com/apparmor/apparmor/-/issues>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
apparmor(7), apparmor_parser(8), aa_change_hat(2) and
|
|
L<https://wiki.apparmor.net>.
|
|
|
|
=cut
|