Translation(s): none
/Contribute /Debug /HowToUse /OutReachyRound9 /Progress /Reportbug /UserStories |
Contents
Desktop notifications
The aa-notify command, from the apparmor-notify package, is able to provide a desktop notification whenever a program causes a DENIED message in /var/log/kern.log. It can be started like this (the user who starts aa-notify needs to have read permissions for /var/log/kern.log):
sudo aa-notify -p
If you use auditd, you should start aa-notify like this:
sudo aa-notify -p -f /var/log/audit/audit.log
(We are obliged to start aa-notify manually and as root because of 670305 and 759604.)
Diagnose if a bug might have been caused by AppArmor
The apparmor-utils package provides many useful commands to debug AppArmor.
Find out if AppArmor is enabled. This will return Y if true.
$ cat /sys/module/apparmor/parameters/enabled
- Find out which profiles are enabled
sudo aa-status This will list all loaded AppArmor profiles for applications and processes and detail their status (enforced, complain, unconfined).
$ ps auxZ | grep -v '^unconfined'
will list running executables which are currently confined by an AppArmor profile.
- Sometimes, it's useful to disable a profile and to test again if the bug persists:
sudo aa-disable /etc/apparmor.d/$profile e.g. sudo aa-disable /etc/apparmor.d/usr.bin.pidgin One can re-enable the profile like this: sudo aa-enforce /etc/apparmor.d/$profile
- Verify the logs
sudo tail -f /var/log/syslog | grep 'DENIED' or (if auditd is installed): sudo tail -f /var/log/auditd/auditd.log | grep 'DENIED' The "DENIED" lines should provide more information on what concrete process or access to the file system has been denied.
Output a list of processes with tcp or udp ports that do not have AppArmor profiles loaded
sudo aa-unconfined also possible with the --paranoid parameter
Note that aa-unconfined is currently buggy with some profiles, which are named a certain way, so do not rely on it. To be sure, for debugging purposes, to identify what apparmor profile the kernel has applied to a given process, find the pid of the process that you're interested in and then examine the contents of /proc/PID/attr/current (replacing PID with the pid you identified earlier). If it contains 'unconfined', then there is no apparmor policy applied. Otherwise, it should contain the name of the profile.
Debug a profile
Quick guide
Read syslog sudo tail -f /var/log/syslog | grep DENIED or sudo tail -f /var/log/auditd/audit.log | grep DENIED
sudo aa-disable /etc/apparmor.d/$profile where "$profile" is the name of the application's profile, e.g. sudo aa-disable /etc/apparmor.d/usr.bin.pidgin
- edit the profile, using a text editor
sudo aa-enforce /etc/apparmor.d/$profile where "$profile" is the name of the application's profile
or sudo aa-complain /etc/apparmor.d/$profile where "$profile" is the name of the application's profile
To simply reload one profile into the kernel once you've modified its contents use apparmor_parser(8):
sudo apparmor_parser -r /etc/apparmor.d/profile.name e.g. sudo apparmor_parser -r /etc/apparmor.d/usr.bin.pidgin
- restart application, reverify logs.
Testing
Testing new profiles in particular should always be done in a clean Sid environment.
In a nutshell:
- fire up a sid VM
apt-get install apparmor
add apparmor=1 security=apparmor to the kernel command-line
- drop the profile in place, that is /etc/apparmor.d`
- reboot
- test the software at will.
External documentation
As a quick introduction, we recommend reading https://wiki.ubuntu.com/DebuggingApparmor.
There are many useful commands on handling and using profiles at Ubuntu's help page about AppArmor
For a more detailed guide to debugging AppArmor profiles, read upstream's documentation on the subject.
Report a bug
If you've found a bug in an AppArmor profile provided either by apparmor-profiles-extra or a software in Debian which ships its own profile, you might want to report a bug. As the Debian Bug Tracking System is package-centric, only the package maintainers will be automatically made aware you reported this bug. That is why we kindly ask you to usertag your bugs, so that the Debian AppArmor Packaging Team will also be notified if AppArmor is involved or if you need help diagnosing this very fact.
The usertags you should use are:
with the tag "help-needed", to request help for initial diagnosis.
with the tag "buggy-profile", if and once an AppArmor profile has been identified as the culprit
You can find out more on usertagging bugs in our dedicated documentation.