/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. Most of Debian's AppArmor profiles are imported directly from the upstream repositories. The development of profiles takes place over Bazaar at Launchpad:
Ubuntu and openSUSE ship AppArmor by default. For Ubuntu, who base their profiles on the same upstream source, 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 in the package that ships the software they are confining. 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 additional profiles via the apparmor-profiles-extra package.
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 is shipped in Ubuntu
- that profile already exists upstream
- that profile needs to be written
Migrate a profile to the package that ships the confined application
(TODO: describe how to migrate a profile from e.g. apparmor-profiles-extra to the actual package)
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 install 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' or (if auditd is installed): sudo tail -f /var/log/auditd/auditd.log | grep 'DENIED'
- Ask to disable the profile and test again if it works
sudo aa-disable /etc/apparmor.d/profile* e.g. sudo aa-disable /etc/apparmor.d/usr.bin.pidgin
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, 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
- 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
or (if auditd is installed): sudo tail -f /var/log/auditd/auditd.log | grep 'DENIED'
Usertags
Usertagging bugs is useful and can provide a transversal view of several bugs. A bug, which has been reported against a package but which might involve AppArmor, will show up on the Debian AppArmor packaging team's radar if you add a usertag to it. This will make us aware that you might need our help, for example.
We have agreed to user certain usertags on the BTS. Please use these tags when you can, as follows:
(fixme)
See all usertags for user pkg-apparmor-team AT lists.alioth.debian.org