[apparmor] [patch] manpages: incorporate podchecker; fix errors and (most) warnings
Seth Arnold
seth.arnold at canonical.com
Mon Sep 15 17:58:17 UTC 2014
On Sat, Sep 13, 2014 at 01:47:05AM -0700, Steve Beattie wrote:
> 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>
Cool! Thanks :)
Acked-by: Seth Arnold <seth.arnold at canonical.com>
> ---
> 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/
> --
> AppArmor mailing list
> AppArmor at lists.ubuntu.com
> Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20140915/dd25f2c6/attachment-0001.pgp>
More information about the AppArmor
mailing list