1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
1 |
# This publication is intellectual property of Novell Inc. and Canonical |
2 |
# Ltd. Its contents can be duplicated, either in part or in whole, provided |
|
3 |
# that a copyright label is visibly located on each copy. |
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
4 |
#
|
5 |
# All information found in this book has been compiled with utmost |
|
6 |
# attention to detail. However, this does not guarantee complete accuracy. |
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
7 |
# Neither SUSE LINUX GmbH, Canonical Ltd, the authors, nor the translators |
8 |
# shall be held liable for possible errors or the consequences thereof. |
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
9 |
#
|
10 |
# Many of the software and hardware descriptions cited in this book |
|
11 |
# are registered trademarks. All trade names are subject to copyright |
|
12 |
# restrictions and may be registered trade marks. SUSE LINUX GmbH |
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
13 |
# and Canonical Ltd. essentially adhere to the manufacturer's spelling. |
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
14 |
#
|
15 |
# Names of products and trademarks appearing in this book (with or without
|
|
16 |
# specific notation) are likewise subject to trademark and trade protection
|
|
17 |
# laws and may thus fall under copyright restrictions.
|
|
18 |
#
|
|
19 |
||
20 |
||
21 |
=pod
|
|
22 |
||
23 |
=head1 NAME
|
|
24 |
||
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
25 |
mod_apparmor - fine-grained AppArmor confinement for Apache
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
26 |
|
27 |
=head1 DESCRIPTION
|
|
28 |
||
29 |
An AppArmor profile applies to an executable program; if a portion of
|
|
30 |
the program needs different access permissions than other portions,
|
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
31 |
the program can "change hats" via aa_change_hat(2) to a different role,
|
32 |
also known as a subprofile. The mod_apparmor Apache module uses the
|
|
33 |
aa_change_hat(2) mechanism to offer more fine-grained confinement of dynamic
|
|
34 |
elements within Apache such as individual php and perl scripts, while
|
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
35 |
still allowing the performance benefits of using mod_php and mod_perl.
|
36 |
||
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
37 |
To use mod_apparmor with Apache, ensure that mod_apparmor is configured to
|
38 |
be loaded into Apache, either via a2enmod, yast or manual editing of the
|
|
39 |
apache2(8)/httpd(8) configuration files, and restart Apache. Make sure that
|
|
40 |
apparmor is also functioning.
|
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
41 |
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
42 |
Once mod_apparmor is loaded within Apache, all requests to Apache will
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
43 |
cause mod_apparmor to attempt to change into a hat named by the URI
|
44 |
(e.g. /app/some.cgi). If no such hat is found, it will fall back to
|
|
45 |
attempting to use the hat DEFAULT_URI; if that also does not exist,
|
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
46 |
it will fall back to using the global Apache profile. Most static web
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
47 |
pages can simply make use of the DEFAULT_URI hat.
|
48 |
||
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
49 |
Additionally, before any requests come in to Apache, mod_apparmor
|
50 |
will attempt to change hat into the HANDLING_UNTRUSTED_INPUT hat.
|
|
51 |
mod_apparmor will attempt to use this hat while Apache is doing the
|
|
52 |
initial parsing of a given http request, before its given to a specific
|
|
53 |
handler (like mod_php) for processing.
|
|
54 |
||
55 |
Because defining hats for every URI/URL often becomes tedious, mod_apparmor
|
|
56 |
provides the AAHatName and AADefaultHatName Apache configuration options.
|
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
57 |
|
58 |
=over 4
|
|
59 |
||
60 |
=item B<AAHatName>
|
|
61 |
||
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
62 |
AAHatName allows you to specify a hat to be used for a given Apache
|
63 |
E<lt>DirectoryE<gt>, E<lt>DirectoryMatch>, E<lt>LocationE<gt> or
|
|
64 |
E<lt>LocationMatchE<gt> directive (see the Apache documenation for more
|
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
65 |
details). Note that mod_apparmor behavior can become confused if
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
66 |
E<lt>Directory*E<gt> and E<lt>Location*E<gt> directives are intermingled
|
67 |
and it is recommended to use one type of directive. If the hat specified by
|
|
68 |
AAHatName does not exist in the Apache profile, then it falls back to the
|
|
69 |
behavior described above.
|
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
70 |
|
71 |
=item B<AADefaultHatName>
|
|
72 |
||
73 |
AADefaultHatName allows you to specify a default hat to be used for
|
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
74 |
virtual hosts and other Apache server directives, so that you can have
|
75 |
different defaults for different virtual hosts. This can be overridden by
|
|
76 |
the AAHatName directive and is checked for only if there isn't a matching |
|
77 |
AAHatName or hat named by the URI. If the AADefaultHatName hat does not |
|
78 |
exist, it falls back to the DEFAULT_URI hat if it exists (as described |
|
79 |
above). |
|
80 |
||
81 |
=back |
|
82 |
||
83 |
=head1 URI REQUEST SUMMARY |
|
84 |
||
85 |
When profiling with mod_apparmor, it is helpful to keep the following order |
|
86 |
of operations in mind: |
|
87 |
||
88 |
On each URI request, mod_apparmor will first aa_change_hat(2) into |
|
89 |
^HANDLING_UNTRUSTED_INPUT, if it exists. |
|
90 |
||
91 |
Then, after performing the initial parsing of the request, mod_apparmor |
|
92 |
will: |
|
93 |
||
94 |
=over 2 |
|
95 |
||
96 |
1. try to aa_change_hat(2) into a matching AAHatName hat if it exists and |
|
97 |
applies, otherwise it will |
|
98 |
||
99 |
2. try to aa_change_hat(2) into the URI itself, otherwise it will |
|
100 |
||
101 |
3. try to aa_change_hat(2) into an AADefaultHatName hat if it has been defined |
|
102 |
for the server/vhost, otherwise it will |
|
103 |
||
104 |
4. try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it |
|
105 |
will
|
|
106 |
||
107 |
5. fall back to the global Apache policy |
|
108 |
||
109 |
=back |
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
110 |
|
111 |
=head1 BUGS |
|
112 |
||
113 |
mod_apparmor() currently only supports apache2, and has only been tested |
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
114 |
with the prefork MPM configuration -- threaded configurations of Apache |
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
115 |
may not work correctly. |
116 |
||
117 |
There are likely other bugs lurking about; if you find any, please report |
|
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
118 |
them at L<http://https://bugs.launchpad.net/apparmor/+filebug>. |
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
119 |
|
120 |
=head1 SEE ALSO |
|
121 |
||
1.1.15
by Kees Cook
Import upstream version 2.6~devel+bzr1601 |
122 |
apparmor(7), subdomain.conf(5), apparmor_parser(8), aa_change_hat(2) and |
123 |
L<http://wiki.apparmor.net>. |
|
1.1.1
by Mathias Gug
Import upstream version 2.1+961 |
124 |
|
125 |
=cut |