/FirstTimeProfileImport /MergeProfileFromUpstream /Upstream |
This is the documentation for Debian package maintainers who (want to) ship AppArmor profiles with their packages. It is still under heavy development, please do not hesitate to edit this page.
Debian / Upstream relationship
Every distribution has adopted a different strategy to handle their profiles.
Ubuntu and OpenSuSe ship AppArmor by default and most of Debian's AppArmor profiles are imported directly from the Ubuntu's repositories. On Ubuntu's side, development of profiles takes place over Bazaar at Launchpad:
https://launchpad.net/apparmor-profiles https://bazaar.launchpad.net/~apparmor-dev/apparmor-profiles/master/files
In Ubuntu, once a profile is "ready", it is taken out of the profile development branch and inserted directly into the corresponding package (eg. The AppArmor profile for evince is included into the evince package).
In Debian, on the long run, profiles should also be delivered within their package. This is already the case for some packages (fixme link). For now, package maintainers can however still rely on the Debian AppArmor packaging team which provides the profiles via the apparmor-profiles-extra.
Upstream/bzr |
Debian source package |
Debian binary package |
Ubuntu source package |
Ubuntu binary package |
?apparmor |
- |
- |
||
- |
- |
|||
ubuntu-evince |
Ship AppArmor profiles with your package
If you, as a package maintainer, want to provide a profile with your package, you should first check if
- that profile is included in apparmor-profiles-extra
- that profile already exists upstream
- that profile needs to be written
How does an AppArmor profile look like
To understand the profile contents, please read the following resources:
Packaging with dh_apparmor
dh_apparmor provides the debhelper tools used to install/migrate/remove AppArmor profiles. It also reloads the specified AppArmor profile in postinst using:
apparmor_parser -r -W -T /etc/apparmor.d/<profilename>
By using '-W -T' we ensure that any abstraction updates are also pulled in.
In order to use it, you will first need to add a Build-Dependency on dh-apparmor in debian/control:
Build-Depends: dh-apparmor
In debian/rules you will need copy the AppArmor profiles to /etc/apparmor.d/, then run dh_apparmor on them.
Packages that have multiple binary packages need the '-p<package name>' parameter for dh_apparmor, otherwise dh_apparmor will add AppArmor reload commands for all packages rather than just the one that ships the profile.
Example from the vidalia package:
cp debian/apparmor-profile debian/vidalia/etc/apparmor.d/usr.bin.vidalia dh_apparmor --profile-name=usr.bin.vidalia -pvidalia
Example from the torbrowser-launcher package :
override_dh_install: for PROFILE in usr.bin.torbrowser-launcher torbrowser.Tor.tor torbrowser.start-tor-browser torbrowser.Browser.firefox ; do \ cp apparmor/$$PROFILE debian/torbrowser-launcher/etc/apparmor.d/ ; \ dh_apparmor --profile-name=$$PROFILE -ptorbrowser-launcher ; \ done
Testing
In general, it is useful if a profile is tested by someone who's knowledgeable about the program that is being confined by the proposed profile, to make sure the confinement profile doesn't break common usecases. The package maintainer generally is one of the best-placed people to do this.
In a nutshell, fire up a sid VM, apt install apparmor, add apparmor=1 security=apparmor to the kernel command-line, drop the profile in place, reboot and test at will (also see AppArmor/HowToUse).
Debugging
Diagnose if a bug reported against my package might have been caused by AppArmor
Find out if AppArmor is enabled - this should return true if AppArmor is enabled
test -d /sys/module/apparmor
- Find out which profiles are enabled
sudo aa-status
- Request Logs
sudo tail -f /var/log/syslog | grep 'DENIED'
- Ask to disable the profile and test again if it works
sudo aa-disable /etc/apparmor.d/profile*
Debugging a profile
Read https://wiki.ubuntu.com/DebuggingApparmor.
TL;DR
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
- 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
- restart application, reverify logs.
Get help
Report, tag & triage bugs
When reporting bugs which might involve a malfunctioning AppArmor profile, one should always provide the logs, and in particular the lines containing "DENIED": sudo tail -f /var/log/syslog | grep DENIED
Furthermore, we have set up usertags on the BTS, which will make the Debian AppArmor packaging team aware that a certain bug might be due to a misconfigured profile.
Please use these tags when you can, as follows:
Usertag bugs
(fixme)