doc: add man page for aa-log.

Makefile

@@ -9,7 +9,7 @@ PKGDEST := /tmp/pkg
 PKGNAME := apparmor.d
 P = $(filter-out dpkg,$(notdir $(wildcard ${BUILD}/apparmor.d/*)))
 
-.PHONY: all build enforce full install local $(P) pkg dpkg rpm tests lint clean
+.PHONY: all build enforce full install local $(P) pkg dpkg rpm tests lint man docs serve clean
 
 all: build
 	@./${BUILD}/prebuild --complain
@@ -24,7 +24,7 @@ enforce: build
 full: build
 	@./${BUILD}/prebuild --complain --full
 
-ROOT = $(shell find "${BUILD}/root" -type f -printf "%P\n")
+ROOT = $(shell find "${BUILD}/root" -type f -not -name "*.md" -printf "%P\n")
 PROFILES = $(shell find "${BUILD}/apparmor.d" -type f -printf "%P\n")
 DISABLES = $(shell find "${BUILD}/apparmor.d" -type l -printf "%P\n")
 install:
@@ -56,7 +56,7 @@ local:
 ABSTRACTIONS = $(shell find ${BUILD}/apparmor.d/abstractions/ -type f -printf "%P\n")
 TUNABLES = $(shell find ${BUILD}/apparmor.d/tunables/ -type f -printf "%P\n")
 $(P):
-	@[ -f ${BUILD}/aa-log ] || exit 0; install -Dm755 ${BUILD}/aa-log ${DESTDIR}/usr/bin/aa-log
+	@install -Dm0755 ${BUILD}/aa-log ${DESTDIR}/usr/bin/aa-log
 	@for file in ${ABSTRACTIONS}; do \
 		install -Dm0644 "${BUILD}/apparmor.d/abstractions/$${file}" "${DESTDIR}/etc/apparmor.d/abstractions/$${file}"; \
 	done;
@@ -99,6 +99,15 @@ lint:
 		tests/packer/init/init.sh tests/packer/src/aa-update tests/packer/init/clean.sh \
 		debian/${PKGNAME}.postinst debian/${PKGNAME}.postrm
 
+man:
+	pandoc -t man -s -o root/usr/share/man/man8/aa-log.8 root/usr/share/man/man8/aa-log.md
+
+docs:
+	ENABLED_GIT_REVISION_DATE=false MKDOCS_OFFLINE=true mkdocs build --strict
+
+serve:
+	ENABLED_GIT_REVISION_DATE=false MKDOCS_OFFLINE=false mkdocs serve
+
 clean:
 	@rm -rf \
 		debian/.debhelper debian/debhelper* debian/*.debhelper debian/${PKGNAME} \

dists/apparmor.d.spec

@@ -51,4 +51,6 @@ systemctl is-active -q apparmor && systemctl reload apparmor ||:
 %dir /usr/share/zsh/site-functions
 /usr/share/zsh/site-functions/_aa-log.zsh
 
+%doc %{_mandir}/man8/aa-log.8.gz
+
 %changelog

root/usr/share/man/man8/aa-log.8

@@ -0,0 +1,79 @@
+.\" Automatically generated by Pandoc 3.1.9
+.\"
+.TH "aa-log" "8" "September 2024" "" ""
+.SH NAME
+aa-log \[em] Review AppArmor generated messages in a colorful way.
+.SH SYNOPSIS
+\f[B]aa-log\f[R] [\f[I]options\&...\f[R]] [\f[I]profile\f[R]]
+.SH DESCRIPTION
+Review AppArmor generated messages in a colourful way.
+Support logs from \f[I]auditd\f[R], \f[I]systemd\f[R], \f[I]syslog\f[R]
+as well as \f[I]dbus session\f[R] events.
+.PP
+It can be given an optional profile name to filter the output with.
+.PP
+It can be used to generate AppArmor rules from the logs and it therefore
+an alternative to \f[CR]aa-logprof(8)\f[R].
+The generated rules should be manually reviewed and inserted into the
+profile.
+.PP
+Default logs are read from \f[CR]/var/log/audit/audit.log\f[R].
+Other files in \f[CR]/var/log/audit/\f[R] can easily be checked:
+\f[B]aa-log -f 1\f[R] parses \f[CR]audit.log.1\f[R]
+.SH OPTIONS
+\f[B]aa-log\f[R] [\f[I]options\&...\f[R]] [\f[I]profile\f[R]]
+.TP
+[\f[I]profile\f[R]]
+Optional profile name to filter the output with.
+.TP
+\f[CR]--file\f[R], \f[CR]-f\f[R]
+Set a logfile or a suffix to the default log file.
+.TP
+\f[CR]--systemd\f[R], \f[CR]-s\f[R]
+Parse systemd logs from journalctl.
+Provides all AppArmor logs since the last boot.
+.TP
+\f[CR]--rules\f[R], \f[CR]-r\f[R]
+Convert the log into AppArmor rules.
+.TP
+\f[CR]--raw\f[R], \f[CR]-R\f[R]
+Print the raw log without any formatting.
+Useful for reporting logs.
+.TP
+\f[CR]--help\f[R], \f[CR]-h\f[R]
+Print the program usage.
+.SH USAGE
+To read the AppArmor log from \f[CR]/var/log/audit/audit.log\f[R]:
+.IP
+.EX
+aa-log
+.EE
+.PP
+To optionally filter a given profile name:
+\f[CR]aa-log <profile-name>\f[R] (your shell will autocomplete the
+profile name):
+.IP
+.EX
+$ aa-log dnsmasq
+DENIED  dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r
+DENIED  dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r
+DENIED  dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r
+.EE
+.PP
+To generate AppArmor rule:
+.IP
+.EX
+$ aa-log -r dnsmasq
+profile dnsmasq {
+  \[at]{PROC}/\[at]{pid}/environ r,
+  \[at]{PROC}/cmdline r,
+  \[at]{PROC}/sys/kernel/osrelease r,
+}
+.EE
+.SH SEE ALSO
+\f[CR]aa-logprof(8)\f[R], \f[CR]apparmor(7)\f[R],
+\f[CR]apparmor.d(5)\f[R], \f[CR]aa-genprof(1)\f[R],
+\f[CR]aa-enforce(1)\f[R], \f[CR]aa-complain(1)\f[R],
+\f[CR]aa-disable(1)\f[R], and https://apparmor.pujol.io.
+.SH AUTHORS
+aa-log was written by Alexandre Pujol (alexandre\[at]pujol.io).

root/usr/share/man/man8/aa-log.md

@@ -0,0 +1,80 @@
+% aa-log(8)
+% aa-log was written by Alexandre Pujol (alexandre@pujol.io)
+% September 2024
+
+# NAME
+
+aa-log — Review AppArmor generated messages in a colorful way.
+
+# SYNOPSIS
+
+**aa-log** [*options…*] [*profile*]
+
+# DESCRIPTION
+
+Review AppArmor generated messages in a colourful way. Support logs from *auditd*, *systemd*, *syslog* as well as *dbus session* events.
+
+It can be given an optional profile name to filter the output with.
+
+It can be used to generate AppArmor rules from the logs and it therefore an alternative to `aa-logprof(8)`. The generated rules should be manually reviewed and inserted into the profile.
+
+Default logs are read from `/var/log/audit/audit.log`. Other files in `/var/log/audit/` can easily be checked: **aa-log -f 1** parses `audit.log.1`
+
+# OPTIONS
+
+**aa-log** [*options…*] [*profile*]
+
+[*profile*]
+
+: Optional profile name to filter the output with.
+
+`--file`, `-f`
+
+: Set a logfile or a suffix to the default log file.
+
+`--systemd`, `-s`
+
+: Parse systemd logs from journalctl. Provides all AppArmor logs since the last boot.
+
+`--rules`, `-r`
+
+: Convert the log into AppArmor rules.
+
+`--raw`, `-R`
+
+: Print the raw log without any formatting. Useful for reporting logs.
+
+`--help`, `-h`
+
+: Print the program usage.
+
+
+# USAGE
+
+To read the AppArmor log from `/var/log/audit/audit.log`:
+```sh
+aa-log
+```
+
+To optionally filter a given profile name: `aa-log <profile-name>` (your shell will autocomplete the profile name):
+```
+$ aa-log dnsmasq
+DENIED  dnsmasq open /proc/sys/kernel/osrelease comm=dnsmasq requested_mask=r denied_mask=r
+DENIED  dnsmasq open /proc/1/environ comm=dnsmasq requested_mask=r denied_mask=r
+DENIED  dnsmasq open /proc/cmdline comm=dnsmasq requested_mask=r denied_mask=r
+```
+
+To generate AppArmor rule:
+```
+$ aa-log -r dnsmasq
+profile dnsmasq {
+  @{PROC}/@{pid}/environ r,
+  @{PROC}/cmdline r,
+  @{PROC}/sys/kernel/osrelease r,
+}
+```
+
+# SEE ALSO
+
+`aa-logprof(8)`, `apparmor(7)`, `apparmor.d(5)`, `aa-genprof(1)`, `aa-enforce(1)`, `aa-complain(1)`, `aa-disable(1)`, and
+https://apparmor.pujol.io.