[apparmor] [patch] manpages: incorporate podchecker; fix errors and (most) warnings
Steve Beattie
steve at nxnw.org
Sat Sep 13 08:47:05 UTC 2014
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.
I also cleaned up some additional issues I found, where text had been
indented to be treated as a code example, but did not have a blank line
between it and the previous paragraph, meaning the code example kept
the same formatting and was appended to the previous paragraph's text.
(I also not that the libapparmor pod files aren't set up to generate
and install html versions of the manpages; if someone wants to take that
on, that'd be great.)
Signed-off-by: Steve Beattie <steve at nxnw.org>
---
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(-)
Index: b/utils/aa-cleanprof.pod
===================================================================
--- a/utils/aa-cleanprof.pod
+++ b/utils/aa-cleanprof.pod
@@ -14,7 +14,7 @@ B<-d --dir /path/to/profiles>
Specifies where to look for the AppArmor security profile set.
Defaults to /etc/apparmor.d.
-
+
B<-s --silent>
Silently overwrites the profile without user prompt.
Index: b/utils/aa-complain.pod
===================================================================
--- a/utils/aa-complain.pod
+++ b/utils/aa-complain.pod
@@ -26,7 +26,7 @@ aa-complain - set an AppArmor security p
=head1 SYNOPSIS
-B<aa-complain I<E<lt>executableE<gt>> [I<E<lt>executableE<gt>> ...] [I<-d /path/to/profiles>]
+B<< aa-complain I<E<lt>executableE<gt>> [I<E<lt>executableE<gt>> ...] [I<-d /path/to/profiles>] >>
=head1 OPTIONS
Index: b/common/Make.rules
===================================================================
--- a/common/Make.rules
+++ b/common/Make.rules
@@ -266,3 +266,7 @@ ENSCRIPT_ARGS=-C -2jGr -f Courier6 -E
%.pm.ps: %.pm
enscript ${ENSCRIPT_ARGS} -o $@ $<
+
+.PHONY: check_pod_files
+check_pod_files:
+ LANG=C podchecker -warning -warning *.pod
Index: b/utils/Makefile
===================================================================
--- a/utils/Makefile
+++ b/utils/Makefile
@@ -90,9 +90,10 @@ check_severity_db: /usr/include/linux/ca
done ; \
test "$$RC" -eq 0
+# check_pod_files is defined in common/Make.rules
.PHONY: check
.SILENT: check
-check: check_severity_db
+check: check_severity_db check_pod_files
for i in ${PERLTOOLS} ; do \
perl -c $$i || exit 1; \
done
Index: b/utils/aa-decode.pod
===================================================================
--- a/utils/aa-decode.pod
+++ b/utils/aa-decode.pod
@@ -6,7 +6,7 @@ aa-decode - decode hex-encoded in AppArm
=head1 SYNOPSIS
-B<aa-decode> [option] <HEX STRING>
+B<aa-decode> [option] E<lt>HEX STRINGE<gt>
=head1 DESCRIPTION
Index: b/utils/aa-easyprof.pod
===================================================================
--- a/utils/aa-easyprof.pod
+++ b/utils/aa-easyprof.pod
@@ -25,7 +25,7 @@ aa-easyprof - AppArmor profile generatio
=head1 SYNOPSIS
-B<aa-easyprof> [option] <path to binary>
+B<aa-easyprof> [option] E<lt>path to binaryE<gt>
=head1 DESCRIPTION
@@ -125,14 +125,11 @@ VENDOR/VERSION within the policy-groups
version must be a positive decimal number compatible with the JSON Number type.
Eg, when using:
-=over
- $ aa-easyprof --templates-dir=/usr/share/apparmor/easyprof/templates \
- --policy-groups-dir=/usr/share/apparmor/easyprof/policygroups \
- --policy-vendor="foo" \
- --policy-version=1.0
-
-=back
+ $ aa-easyprof --templates-dir=/usr/share/apparmor/easyprof/templates \
+ --policy-groups-dir=/usr/share/apparmor/easyprof/policygroups \
+ --policy-vendor="foo" \
+ --policy-version=1.0
Then /usr/share/apparmor/easyprof/templates/foo/1.0 will be searched for
templates and /usr/share/apparmor/easyprof/policygroups/foo/1.0 for policy
@@ -255,49 +252,37 @@ Specify output directory for profile. If
=back
-=head1 EXAMPLE
+=head1 EXAMPLES
Example usage for a program named 'foo' which is installed in /opt/foo:
-=over
-
- $ aa-easyprof --template=user-application --template-var="@{APPNAME}=foo" \
- --policy-groups=opt-application,user-application \
- /opt/foo/bin/FooApp
-
-=back
+ $ aa-easyprof --template=user-application --template-var="@{APPNAME}=foo" \
+ --policy-groups=opt-application,user-application \
+ /opt/foo/bin/FooApp
When using a manifest file:
-=over
-
- $ aa-easyprof --manifest=manifest.json
-
-=back
+ $ aa-easyprof --manifest=manifest.json
To output a manifest file based on aa-easyprof arguments:
-=over
-
- $ aa-easyprof --output-format=json \
- --author="Your Name" \
- --comment="Unstructured single-line comment" \
- --copyright="Unstructured single-line copyright statement" \
- --name="My Foo App" \
- --profile-name="com.example.foo" \
- --template="user-application" \
- --policy-groups="user-application,networking" \
- --abstractions="audio,gnome" \
- --read-path="/tmp/foo_r" \
- --read-path="/tmp/bar_r/" \
- --write-path="/tmp/foo_w" \
- --write-path=/tmp/bar_w/ \
- --template-var="@{APPNAME}=foo" \
- --template-var="@{VAR1}=bar" \
- --template-var="@{VAR2}=baz" \
- "/opt/foo/**"
-
-=back
+ $ aa-easyprof --output-format=json \
+ --author="Your Name" \
+ --comment="Unstructured single-line comment" \
+ --copyright="Unstructured single-line copyright statement" \
+ --name="My Foo App" \
+ --profile-name="com.example.foo" \
+ --template="user-application" \
+ --policy-groups="user-application,networking" \
+ --abstractions="audio,gnome" \
+ --read-path="/tmp/foo_r" \
+ --read-path="/tmp/bar_r/" \
+ --write-path="/tmp/foo_w" \
+ --write-path=/tmp/bar_w/ \
+ --template-var="@{APPNAME}=foo" \
+ --template-var="@{VAR1}=bar" \
+ --template-var="@{VAR2}=baz" \
+ "/opt/foo/**"
=head1 BUGS
Index: b/utils/aa-enforce.pod
===================================================================
--- a/utils/aa-enforce.pod
+++ b/utils/aa-enforce.pod
@@ -27,7 +27,7 @@ being disabled or I<complain> mode.
=head1 SYNOPSIS
-B<aa-enforce I<E<lt>executableE<gt>> [I<E<lt>executableE<gt>> ...] [I<-d /path/to/profiles>]
+B<< aa-enforce I<E<lt>executableE<gt>> [I<E<lt>executableE<gt>> ...] [I<-d /path/to/profiles>] >>
=head1 OPTIONS
Index: b/utils/aa-genprof.pod
===================================================================
--- a/utils/aa-genprof.pod
+++ b/utils/aa-genprof.pod
@@ -36,7 +36,7 @@ B<-d --dir /path/to/profiles>
Defaults to /etc/apparmor.d.
B<-f --file /path/to/logfile>
-
+
Specifies the location of logfile.
Default locations are read from F</etc/apparmor/logprof.conf>.
Typical defaults are:
Index: b/utils/aa-logprof.pod
===================================================================
--- a/utils/aa-logprof.pod
+++ b/utils/aa-logprof.pod
@@ -31,12 +31,12 @@ B<aa-logprof [I<-d /path/to/profiles>]
=head1 OPTIONS
B<-d --dir /path/to/profiles>
-
+
Specifies where to look for the AppArmor security profile set.
Defaults to /etc/apparmor.d.
B<-f --file /path/to/logfile>
-
+
Specifies the location of logfile that contains AppArmor security events.
Default locations are read from F</etc/apparmor/logprof.conf>.
Typical defaults are:
@@ -45,7 +45,7 @@ B<-f --file /path/to/logfile>
/var/log/messages
B< -m --logmark "mark">
-
+
aa-logprof will ignore all events in the system log before the
specified mark is seen. If the mark contains spaces, it must
be surrounded with quotes to work correctly.
Index: b/utils/aa-sandbox.pod
===================================================================
--- a/utils/aa-sandbox.pod
+++ b/utils/aa-sandbox.pod
@@ -25,7 +25,7 @@ aa-sandbox - AppArmor sandboxing
=head1 SYNOPSIS
-B<aa-sandbox> [option] <path to binary>
+B<aa-sandbox> [option] E<lt>path to binaryE<gt>
=head1 DESCRIPTION
@@ -89,11 +89,7 @@ with care to not allow too much access t
particular, the profile specified with --profile must add a rule to deny access
to ~/.Xauthority for X sandboxing to be effective. Eg:
-=over
-
-audit deny @{HOME}/.Xauthority mrwlk,
-
-=back
+ audit deny @{HOME}/.Xauthority mrwlk,
=item --with-xserver=XSERVER
@@ -115,35 +111,19 @@ The starting geometry for the Xephyr(1)
Use the existing system profile 'firefox' to sandbox /usr/bin/firefox:
-=over
-
-$ aa-sandbox -X --profile=firefox /usr/bin/firefox
-
-=back
+ $ aa-sandbox -X --profile=firefox /usr/bin/firefox
Sandbox xeyes:
-=over
-
-$ aa-sandbox -X /usr/bin/xeyes
-
-=back
+ $ aa-sandbox -X /usr/bin/xeyes
Sandbox glxgears:
-=over
-
-$ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears
-
-=back
+ $ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears
Sandbox uptime:
-=over
-
-$ aa-sandbox --read-path="/proc/*" /usr/bin/uptime
-
-=back
+ $ aa-sandbox --read-path="/proc/*" /usr/bin/uptime
=head1 NOTES
@@ -152,19 +132,15 @@ xhost access controls need to be enabled
localuser must be removed. One way of achieving this is adding a late running
Xsession(5) script of the form:
-=over
-
-# Create an Xauthority file if it doesn't exist
-
-[ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] &&
- xauth generate :0 . trusted > /dev/null
+ # Create an Xauthority file if it doesn't exist
-# Default to the Xauthority file
+ [ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] &&
+ xauth generate :0 . trusted > /dev/null
-[ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] &&
- xhost -si:localuser:`id -un` > /dev/null
+ # Default to the Xauthority file
-=back
+ [ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] &&
+ xhost -si:localuser:`id -un` > /dev/null
After adding the above, it is recommended you remove the existing ~/.Xauthority
file, then restart your session.
@@ -176,27 +152,27 @@ of limitations regarding both confinemen
=over
-As mentioned, the quality of the template or the specified profile directly
+=item * As mentioned, the quality of the template or the specified profile directly
affects the application's confinement.
-DBus system access is all or nothing and DBus session access is unconditionally
+=item * DBus system access is all or nothing and DBus session access is unconditionally
allowed.
-No environment filtering is performed.
+=item * No environment filtering is performed.
-X server usage has not been fully audited (though simple attacks are believed
+=item * X server usage has not been fully audited (though simple attacks are believed
to be protected against when the system is properly setup. See B<NOTES>,
above).
-Using a nested X server for each application is expensive.
+=item * Using a nested X server for each application is expensive.
-Only the old X cursor is available with B<xpra> and B<xpra3d>.
+=item * Only the old X cursor is available with B<xpra> and B<xpra3d>.
-The Ubuntu global menu is not currently supported. Gtk and Qt applications
+=item * The Ubuntu global menu is not currently supported. Gtk and Qt applications
should display the non-global menu by default, but applications like Firefox
and Thunderbird should be adjusted to disable the global menu.
-Xpra does not handle screen resizing when hotplugging monitors gracefully.
+=item * Xpra does not handle screen resizing when hotplugging monitors gracefully.
Restarting the sandbox will resolve the issue.
=back
Index: b/utils/logprof.conf.pod
===================================================================
--- a/utils/logprof.conf.pod
+++ b/utils/logprof.conf.pod
@@ -61,7 +61,7 @@ own hat.
The B<[globs]> section allows modification of the logprof rule engine
with respect to globbing suggestions that the user will be prompted with.
-The format of each line is-- "<perl glob> = <apparmor glob>".
+The format of each line is-- "E<lt>perl globE<gt> = E<lt>apparmor globE<gt>".
When aa-logprof(1) asks about a specific path, if the perl glob matches the
path, it replaces the part of the path that matched with the corresponding
Index: b/parser/Makefile
===================================================================
--- a/parser/Makefile
+++ b/parser/Makefile
@@ -291,7 +291,7 @@ tst_%: parser_%.c parser.h $(filter-out
.SILENT: check
.PHONY: check
-check: tests
+check: check_pod_files tests
.SILENT: tests
tests: apparmor_parser ${TESTS}
Index: b/parser/apparmor.d.pod
===================================================================
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -48,20 +48,20 @@ B<INCLUDE> = '#include' ( I<ABS PATH> |
B<ABS PATH> = '"' path '"' (the path is passed to open(2))
-B<MAGIC PATH> = '<' relative path '>' (the path is relative to F</etc/apparmor.d/>)
+B<MAGIC PATH> = 'E<lt>' relative path 'E<gt>' (the path is relative to F</etc/apparmor.d/>)
B<COMMENT> = '#' I<TEXT>
B<TEXT> = any characters
-B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<PIVOT ROOT RULE> | I<DBUS RULE> | I<UNIX RULE> I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<PIVOT ROOT RULE> | I<DBUS RULE> | I<UNIX RULE> I<FILE RULE> | 'change_profile -E<gt> ' I<PROGRAMCHILD> ) ... ] '}'
B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
B<CAPABILITY> = (lowercase capability name without 'CAP_' prefix; see
capabilities(7))
-B<NETWORK RULE> = 'network' [ [ I<DOMAIN> ] [ I<TYPE> ] [ I <PROTOCOL> ] ] ','
+B<NETWORK RULE> = 'network' [ [ I<DOMAIN> ] [ I<TYPE> ] [ I<PROTOCOL> ] ] ','
B<DOMAIN> = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' | 'bridge' | 'atmpvc' | 'x25' | 'inet6' | 'rose' | 'netbeui' | 'security' | 'key' | 'packet' | 'ash' | 'econet' | 'atmsvc' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' | 'netlink' ) ','
@@ -77,7 +77,7 @@ B<PROGRAMCHILD> = I<SUBPROFILE> name
B<MOUNT RULE> = ( I<MOUNT> | I<REMOUNT> | I<UMOUNT> )
-B<MOUNT> = [ 'audit' ] [ 'deny' ] 'mount' [ I<MOUNT CONDITIONS> ] [ I<SOURCE FILEGLOB> ] [ -> [ I<MOUNTPOINT FILEGLOB> ]
+B<MOUNT> = [ 'audit' ] [ 'deny' ] 'mount' [ I<MOUNT CONDITIONS> ] [ I<SOURCE FILEGLOB> ] [ -E<gt> [ I<MOUNTPOINT FILEGLOB> ]
B<REMOUNT> = [ 'audit' ] [ 'deny' ] 'remount' [ I<MOUNT CONDITIONS> ] I<MOUNTPOINT FILEGLOB>
@@ -97,7 +97,7 @@ B<MOUNT FLAGS> = ( 'ro' | 'rw' | 'nosuid
B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
-B<PIVOT ROOT RULE> = [ 'audit' ] [ 'deny' ] pivot_root [ oldroot=I<OLD PUT FILEGLOB> ] [ I<NEW ROOT FILEGLOB> ] [ -> I<PROGRAMCHILD> ]
+B<PIVOT ROOT RULE> = [ 'audit' ] [ 'deny' ] pivot_root [ oldroot=I<OLD PUT FILEGLOB> ] [ I<NEW ROOT FILEGLOB> ] [ -E<gt> I<PROGRAMCHILD> ]
B<PTRACE_RULE> = [ 'audit' ] [ 'deny' ] 'ptrace' [ I<PTRACE ACCESS PERMISSIONS> ] [ I<PTRACE PEER> ]
@@ -166,14 +166,14 @@ B<UNIX ACCESS EXPR> = ( I<UNIX ACCESS> |
B<UNIX ACCESS> = ( 'create' | 'bind' | 'listen' | 'accept' | 'connect' | 'shutdown' | 'getattr' | 'setattr' | 'getopt' | 'setopt' | 'send' | 'receive' | 'r' | 'w' | 'rw' )
(some access modes are incompatible with some rules or require additional parameters)
-B<UNIX ACCESS LIST> = '(' I<UNIX ACCESS> ( [','] <UNIX ACCESS> )* ')'
+B<UNIX ACCESS LIST> = '(' I<UNIX ACCESS> ( [','] I<UNIX ACCESS> )* ')'
B<UNIX RULE CONDS> = ( I<TYPE COND> | I<PROTO COND> )
each cond can appear at most once
-B<TYPE COND> = 'type' '=' ( <AARE> | '(' ( '"' <AARE> '"' | <AARE> )+ ')' )
+B<TYPE COND> = 'type' '=' ( I<AARE> | '(' ( '"' I<AARE> '"' | I<AARE> )+ ')' )
-B<PROTO COND> = 'protocol' '=' ( <AARE> | '(' ( '"' <AARE> '"' | <AARE> )+ ')' )
+B<PROTO COND> = 'protocol' '=' ( I<AARE> | '(' ( '"' I<AARE> '"' | I<AARE> )+ ')' )
B<UNIX LOCAL EXPR> = ( I<UNIX ADDRESS COND> | I<UNIX LABEL COND> | I<UNIX ATTR COND> | I<UNIX OPT COND> )*
each cond can appear at most once
@@ -181,13 +181,13 @@ B<UNIX LOCAL EXPR> = ( I<UNIX ADDRESS CO
B<UNIX PEER EXPR> = 'peer' '=' ( I<UNIX ADDRESS COND> | I<UNIX LABEL COND> )+
each cond can appear at most once
-B<UNIX ADDRESS COND> 'addr' '=' ( <AARE> | '(' '"' <AARE> '"' | <AARE> ')' )
+B<UNIX ADDRESS COND> 'addr' '=' ( I<AARE> | '(' '"' I<AARE> '"' | I<AARE> ')' )
-B<UNIX LABEL COND> 'label' '=' ( <AARE> | '(' '"' <AARE> '"' | <AARE> ')' )
+B<UNIX LABEL COND> 'label' '=' ( I<AARE> | '(' '"' I<AARE> '"' | I<AARE> ')' )
-B<UNIX ATTR COND> 'attr' '=' ( <AARE> | '(' '"' <AARE> '"' | <AARE> ')' )
+B<UNIX ATTR COND> 'attr' '=' ( I<AARE> | '(' '"' I<AARE> '"' | I<AARE> ')' )
-B<UNIX OPT COND> 'opt' '=' ( <AARE> | '(' '"' <AARE> '"' | <AARE> ')' )
+B<UNIX OPT COND> 'opt' '=' ( I<AARE> | '(' '"' I<AARE> '"' | I<AARE> ')' )
B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
@@ -195,13 +195,13 @@ B<RULE QUALIFIER> = [ 'audit' ] [ 'deny'
B<FILEGLOB> = (must start with '/' (after variable expansion), B<AARE> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
-B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I<PROGRAMCHILD> | 'Cx -> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ] (not all combinations are allowed; see below.)
+B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -E<gt> ' I<PROGRAMCHILD> | 'Cx -E<gt> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ] (not all combinations are allowed; see below.)
B<VARIABLE> = '@{' I<ALPHA> [ ( I<ALPHANUMERIC> | '_' ) ... ] '}'
B<VARIABLE ASSIGNMENT> = I<VARIABLE> ('=' | '+=') (space separated values)
-B<ALIAS RULE> = I<ABS PATH> '->' I<REWRITTEN ABS PATH> ','
+B<ALIAS RULE> = I<ABS PATH> '-E<gt>' I<REWRITTEN ABS PATH> ','
B<ALPHA> = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
@@ -230,31 +230,57 @@ modes:
=over 8
-=item B<r> - read
+=item B<r>
-=item B<w> - write -- conflicts with append
+- read
-=item B<a> - append -- conflicts with write
+=item B<w>
-=item B<ux> - unconfined execute
+- write -- conflicts with append
-=item B<Ux> - unconfined execute -- scrub the environment
+=item B<a>
-=item B<px> - discrete profile execute
+- append -- conflicts with write
-=item B<Px> - discrete profile execute -- scrub the environment
+=item B<ux>
-=item B<cx> - transition to subprofile on execute
+- unconfined execute
-=item B<Cx> - transition to subprofile on execute -- scrub the environment
+=item B<Ux>
-=item B<ix> - inherit execute
+- unconfined execute -- scrub the environment
-=item B<m> - allow PROT_EXEC with mmap(2) calls
+=item B<px>
-=item B<l> - link
+- discrete profile execute
-=item B<k> - lock
+=item B<Px>
+
+- discrete profile execute -- scrub the environment
+
+=item B<cx>
+
+- transition to subprofile on execute
+
+=item B<Cx>
+
+- transition to subprofile on execute -- scrub the environment
+
+=item B<ix>
+
+- inherit execute
+
+=item B<m>
+
+- allow PROT_EXEC with mmap(2) calls
+
+=item B<l>
+
+- link
+
+=item B<k>
+
+- lock
=back
@@ -459,29 +485,17 @@ If a conditional is specified using '=',
for mounts matching the exactly specified options. For example, an AppArmor
policy with the following rule:
-=over 4
-
-mount options=ro /dev/foo -> /mnt/,
-
-=back
+ mount options=ro /dev/foo -E<gt> /mnt/,
Would match:
-=over 4
-
-$ mount -o ro /dev/foo /mnt
-
-=back
+ $ mount -o ro /dev/foo /mnt
but not either of these:
-=over 4
-
-$ mount -o ro,atime /dev/foo /mnt
+ $ mount -o ro,atime /dev/foo /mnt
-$ mount -o rw /dev/foo /mnt
-
-=back
+ $ mount -o rw /dev/foo /mnt
=item 2.
@@ -489,39 +503,27 @@ If a conditional is specified using 'in'
mounts matching any combination of the specified options. For example, if an
AppArmor policy has the following rule:
-=over 4
-
-mount options in (ro,atime) /dev/foo -> /mnt/,
-
-=back
+ mount options in (ro,atime) /dev/foo -> /mnt/,
all of these mount commands will match:
-=over 4
+ $ mount -o ro /dev/foo /mnt
-$ mount -o ro /dev/foo /mnt
+ $ mount -o ro,atime /dev/foo /mnt
-$ mount -o ro,atime /dev/foo /mnt
-
-$ mount -o atime /dev/foo /mnt
-
-=back
+ $ mount -o atime /dev/foo /mnt
but none of these will:
-=over 4
-
-$ mount -o ro,sync /dev/foo /mnt
-
-$ mount -o ro,atime,sync /dev/foo /mnt
+ $ mount -o ro,sync /dev/foo /mnt
-$ mount -o rw /dev/foo /mnt
+ $ mount -o ro,atime,sync /dev/foo /mnt
-$ mount -o rw,noatime /dev/foo /mnt
+ $ mount -o rw /dev/foo /mnt
-$ mount /dev/foo /mnt
+ $ mount -o rw,noatime /dev/foo /mnt
-=back
+ $ mount /dev/foo /mnt
=item 3.
@@ -530,51 +532,32 @@ grants permission for each set of option
writing mount rules which might help to logically break up a conditional. For
example, if an AppArmor policy has the following rule:
-=over 4
-
-mount options=ro options=atime
-
-=back
+ mount options=ro options=atime
both of these mount commands will match:
-=over 4
-
-$ mount -o ro /dev/foo /mnt
-
-$ mount -o atime /dev/foo /mnt
+ $ mount -o ro /dev/foo /mnt
-=back
+ $ mount -o atime /dev/foo /mnt
but this one will not:
-=over 4
-
-$ mount -o ro,atime /dev/foo /mnt
-
-=back
+ $ mount -o ro,atime /dev/foo /mnt
=back
Note that separate mount rules are distinct and the options do not accumulate.
For example, these AppArmor mount rules:
-=over 4
-
-mount options=ro,
-mount options=atime,
+ mount options=ro,
-=back
+ mount options=atime,
are not equivalent to either of these mount rules:
-=over 4
-
-mount options=(ro,atime),
+ mount options=(ro,atime),
-mount options in (ro,atime),
-
-=back
+ mount options in (ro,atime),
To help clarify the flexibility and complexity of mount rules, here are some
example rules with accompanying matching commands:
@@ -584,65 +567,49 @@ example rules with accompanying matching
=item B<mount,>
the 'mount' rule without any conditionals is the most generic and allows any
-mount. Equivalent to 'mount fstype=** options=** ** -> /**'.
+mount. Equivalent to 'mount fstype=** options=** ** -E<gt> /**'.
=item B<mount /dev/foo,>
allow mounting of /dev/foo anywhere with any options. Some matching mount
commands:
-=over 4
-
-$ mount /dev/foo /mnt
+ $ mount /dev/foo /mnt
-$ mount -t ext3 /dev/foo /mnt
+ $ mount -t ext3 /dev/foo /mnt
-$ mount -t vfat /dev/foo /mnt
+ $ mount -t vfat /dev/foo /mnt
-$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
-
-=back
+ $ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
=item B<mount options=ro /dev/foo,>
allow mounting of /dev/foo anywhere, as read only. Some matching mount
commands:
-=over 4
-
-$ mount -o ro /dev/foo /mnt
-
-$ mount -o ro /dev/foo /some/where/else
+ $ mount -o ro /dev/foo /mnt
-=back
+ $ mount -o ro /dev/foo /some/where/else
=item B<mount options=(ro,atime) /dev/foo,>
allow mount of /dev/foo anywhere, as read only and using inode access times.
Some matching mount commands:
-=over 4
-
-$ mount -o ro,atime /dev/foo /mnt
+ $ mount -o ro,atime /dev/foo /mnt
-$ mount -o ro,atime /dev/foo /some/where/else
-
-=back
+ $ mount -o ro,atime /dev/foo /some/where/else
=item B<mount options in (ro,atime) /dev/foo,>
allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime'
(see above). Some matching mount commands:
-=over 4
-
-$ mount -o ro /dev/foo /mnt
+ $ mount -o ro /dev/foo /mnt
-$ mount -o atime /dev/foo /some/where/else
+ $ mount -o atime /dev/foo /some/where/else
-$ mount -o ro,atime /dev/foo /some/other/place
-
-=back
+ $ mount -o ro,atime /dev/foo /some/other/place
=item B<mount options=ro /dev/foo, mount options=atime /dev/foo,>
@@ -650,68 +617,48 @@ allow mount of /dev/foo anywhere as read
anywhere using inode access times. Note this is expressed as two different
rules. Matches:
-=over 4
-
-$ mount -o ro /dev/foo /mnt/1
+ $ mount -o ro /dev/foo /mnt/1
-$ mount -o atime /dev/foo /mnt/2
+ $ mount -o atime /dev/foo /mnt/2
-=back
-
-=item B<< mount -> /mnt/**, >>
+=item B<< mount -E<gt> /mnt/**, >>
allow mounting anything under a directory in /mnt/**. Some matching mount
commands:
-=over 4
+ $ mount /dev/foo1 /mnt/1
-$ mount /dev/foo1 /mnt/1
+ $ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
-$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
-
-=back
-
-=item B<< mount options=ro -> /mnt/**, >>
+=item B<< mount options=ro -E<gt> /mnt/**, >>
allow mounting anything under /mnt/**, as read only. Some matching mount
commands:
-=over 4
+ $ mount -o ro /dev/foo1 /mnt/1
-$ mount -o ro /dev/foo1 /mnt/1
-
-$ mount -o ro /dev/foo2 /mnt/deep/path/foo2
-
-=back
+ $ mount -o ro /dev/foo2 /mnt/deep/path/foo2
-=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/, >>
+=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -E<gt> /mnt/stick/, >>
allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and
using inode access times. Matches only:
-=over 4
-
-$ mount -o rw,atime /dev/sdb1 /mnt/stick
-
-=back
+ $ mount -o rw,atime /dev/sdb1 /mnt/stick
-=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/, >>
+=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -E<gt> /mnt/, >>
allow mounting /dev/foo on /mmt/ read only and using inode access times or
allow mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'.
Matches only:
-=over 4
-
-$ mount -o ro,atime /dev/foo /mnt
+ $ mount -o ro,atime /dev/foo /mnt
-$ mount -o nodev /dev/foo /mnt
+ $ mount -o nodev /dev/foo /mnt
-$ mount -o user /dev/foo /mnt
+ $ mount -o user /dev/foo /mnt
-$ mount -o nodev,user /dev/foo /mnt
-
-=back
+ $ mount -o nodev,user /dev/foo /mnt
=back
@@ -898,6 +845,7 @@ domain sockets, see unix(7) for more inf
The sun_path component (aka the socket address) of a unix domain socket is
specified by the
+
addr=
conditional. If an address conditional is not specified as part of
@@ -911,17 +859,20 @@ characters must be specified by using an
I<\x00>. The pattern matching is the same as is used by file path matching
so * will not match I</> even though it has no special meaning with
in an abstract socket name. Eg.
+
unix addr=@*,
Anonymous unix domain sockets have no sun_path associated with the socket
address, however it can be specified with the special I<none> keyword to
indicate the rule only applies to anonymous unix domain sockets. Eg.
+
unix addr=none,
If the address component of a rule is not specified then the rule applies
to both abstract and anonymous sockets.
=head3 Unix socket permissions
+
Unix domain socket rules are accumulated so that the granted unix
socket permissions are the union of all the listed unix rule permissions.
@@ -988,18 +939,20 @@ sockets as well. When fine grained unix
the coarse grained network rule is mapped into the equivalent unix socket
rule.
-Eg.
+E.G.
+
network unix, => unix,
network unix stream, => unix stream,
Fine grained mediation rules however can not be lossly converted back
-to the coarse grained network rule. Eg
+to the coarse grained network rule; e.g.
unix bind addr=@example,
Has no exact match under coarse grained network rules, the closest match is
-the much wider permission rule of.
+the much wider permission rule of
+
network unix,
=head2 Variables
@@ -1308,18 +1261,26 @@ An example AppArmor profile:
=over 4
+=item *
+
Mount options support the use of pattern matching but mount flags are not
correctly intersected against specified patterns. Eg, 'mount options=**,'
should be equivalent to 'mount,', but it is not. (LP: #965690)
+=item *
+
The fstype may not be matched against when certain mount command flags are
used. Specifically fstype matching currently only works when creating a new
mount and not remount, bind, etc.
+=item *
+
Mount rules with multiple 'options' conditionals are not applied as documented
but instead merged such that 'options in (ro,nodev) options in (atime)' is
equivalent to 'options in (ro,nodev,atime)'.
+=item *
+
When specifying mount options with the 'in' conditional, both the positive and
negative values match when specifying one or the other. Eg, 'rw' matches when
'ro' is specified and 'dev' matches when 'nodev' is specified such that
Index: b/changehat/mod_apparmor/Makefile
===================================================================
--- a/changehat/mod_apparmor/Makefile
+++ b/changehat/mod_apparmor/Makefile
@@ -95,3 +95,6 @@ install: ${TARGET} ${MANPAGES}
clean: _clean
rm -rf .libs
rm -f *.la *.lo *.so *.o *.slo Make.rules
+
+.PHONY: check
+check: check_pod_files
Index: b/changehat/mod_apparmor/mod_apparmor.pod
===================================================================
--- a/changehat/mod_apparmor/mod_apparmor.pod
+++ b/changehat/mod_apparmor/mod_apparmor.pod
@@ -64,7 +64,7 @@ provides the AAHatName and AADefaultHatN
=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>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
@@ -95,23 +95,35 @@ On each URI request, mod_apparmor will f
Then, after performing the initial parsing of the request, mod_apparmor
will:
-=over 2
+=over 4
-1. try to aa_change_hat(2) into a matching AAHatName hat if it exists and
+=item 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 an AADefaultHatName hat, either the
+=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
-3. try to aa_change_hat(2) into the ServerName-URI, otherwise it will
+=item 3
+
+try to aa_change_hat(2) into the ServerName-URI, otherwise it will
-4. try to aa_change_hat(2) into the URI itself, otherwise it will
+=item 4
-5. try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it
+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
-6. fall back to the global Apache policy
+=item 6
+
+fall back to the global Apache policy
=back
Index: b/libraries/libapparmor/doc/Makefile.am
===================================================================
--- a/libraries/libapparmor/doc/Makefile.am
+++ b/libraries/libapparmor/doc/Makefile.am
@@ -1,6 +1,10 @@
## Process this file with automake to produce Makefile.in
POD2MAN = pod2man
+PODCHECKER = podchecker
+
+# No perl, no manpages
+if HAVE_PERL
man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2
@@ -12,9 +16,12 @@ EXTRA_DIST = $(man_MANS) $(PODS)
BUILT_SOURCES = $(man_MANS)
%.2: %.pod
+ $(PODCHECKER) -warnings -warnings $<
$(POD2MAN) \
--section=2 \
--release="AppArmor $(VERSION)" \
--center="AppArmor" \
--stderr \
$< > $@
+
+endif
Index: b/utils/vim/Makefile
===================================================================
--- a/utils/vim/Makefile
+++ b/utils/vim/Makefile
@@ -25,7 +25,7 @@ install: apparmor.vim manpages
$(MAKE) install_manpages DESTDIR=${DESTDIR}
.PHONY: check
-check:
+check: check_pod_files
#Testing with all pythons
$(call pyalldo, create-apparmor.vim.py > /dev/null)
--
Steve Beattie
<sbeattie at ubuntu.com>
http://NxNW.org/~steve/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20140913/736c3e13/attachment-0001.pgp>
More information about the AppArmor
mailing list