Commit c48d7dc7 authored by Steve Beattie's avatar Steve Beattie

manpages: incorporate podchecker; fix errors and (most) warnings

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.
Signed-off-by: Steve Beattie's avatarSteve Beattie <steve@nxnw.org>
Acked-by: 's avatarSeth Arnold <seth.arnold@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(-)
parent b7ff639d
......@@ -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
......@@ -64,7 +64,7 @@ provides the AAHatName and AADefaultHatName Apache configuration options.
=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 first aa_change_hat(2) into
Then, after performing the initial parsing of the request, mod_apparmor
will:
=over 2
=over 4
=item 1
1. try to aa_change_hat(2) into a matching AAHatName hat if it exists and
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
......
......@@ -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
## 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
......@@ -291,7 +291,7 @@ tst_%: parser_%.c parser.h $(filter-out parser_%.o, ${TEST_OBJECTS})
.SILENT: check
.PHONY: check
check: tests
check: check_pod_files tests
.SILENT: tests
tests: apparmor_parser ${TESTS}
......
This diff is collapsed.
......@@ -90,9 +90,10 @@ check_severity_db: /usr/include/linux/capability.h severity.db
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
......
......@@ -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.
......
......@@ -26,7 +26,7 @@ aa-complain - set an AppArmor security profile to I<complain> mode.
=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
......
......@@ -6,7 +6,7 @@ aa-decode - decode hex-encoded in AppArmor log files
=head1 SYNOPSIS
B<aa-decode> [option] <HEX STRING>
B<aa-decode> [option] E<lt>HEX STRINGE<gt>
=head1 DESCRIPTION
......
......@@ -25,7 +25,7 @@ aa-easyprof - AppArmor profile generation made easy.
=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 and templates directory. The specified
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 unspecified, policy is sent to stdout.
=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
......
......@@ -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
......
......@@ -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:
......
......@@ -31,12 +31,12 @@ B<aa-logprof [I<-d /path/to/profiles>] [I<-f /path/to/logfile>] [I<-m E<lt>mark
=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.
......
......@@ -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 to the sandboxed application. In
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) server to use.
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 and server interpreted values for
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 confinement and usability:
=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
......
......@@ -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
......
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment