← Back to branch summary

~ubuntu-branches/ubuntu/wily/apparmor/wily

« back to all changes in this revision

Viewing changes to changehat/mod_apparmor/mod_apparmor.pod

  • Committer: Bazaar Package Importer
  • Author(s): Kees Cook
  • Date: 2011-04-27 10:38:07 UTC
  • mfrom: (5.1.118 natty)
  • Revision ID: james.westby@ubuntu.com-20110427103807-ym3rhwys6o84ith0
Tags: 2.6.1-2
debian/copyright: clarify for some full organization names.

Show diffs side-by-side

added added

removed removed

Lines of Context:
changehat/mod_apparmor/mod_apparmor.pod
 
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.
 
4
#
 
5
# All information found in this book has been compiled with utmost
 
6
# attention to detail. However, this does not guarantee complete accuracy.
 
7
# Neither SUSE LINUX GmbH, Canonical Ltd, the authors, nor the translators
 
8
# shall be held liable for possible errors or the consequences thereof.
 
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
 
13
# and Canonical Ltd. essentially adhere to the manufacturer's spelling.
 
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
 
 
25
mod_apparmor - fine-grained AppArmor confinement for Apache
 
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,
 
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
 
35
still allowing the performance benefits of using mod_php and mod_perl.
 
36
 
 
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.
 
41
 
 
42
Once mod_apparmor is loaded within Apache, all requests to Apache will
 
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,
 
46
it will fall back to using the global Apache profile. Most static web
 
47
pages can simply make use of the DEFAULT_URI hat.
 
48
 
 
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.
 
57
 
 
58
=over 4
 
59
 
 
60
=item B<AAHatName>
 
61
 
 
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
 
65
details). Note that mod_apparmor behavior can become confused if
 
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.
 
70
 
 
71
=item B<AADefaultHatName>
 
72
 
 
73
AADefaultHatName allows you to specify a default hat to be used for
 
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
 
110
 
 
111
=head1 BUGS
 
112
 
 
113
mod_apparmor() currently only supports apache2, and has only been tested
 
114
with the prefork MPM configuration -- threaded configurations of Apache
 
115
may not work correctly.
 
116
 
 
117
There are likely other bugs lurking about; if you find any, please report
 
118
them at L<http://https://bugs.launchpad.net/apparmor/+filebug>.
 
119
 
 
120
=head1 SEE ALSO
 
121
 
 
122
apparmor(7), subdomain.conf(5), apparmor_parser(8), aa_change_hat(2) and
 
123
L<http://wiki.apparmor.net>.
 
124
 
 
125
=cut