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. 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

apparmor

apparmor and apparmor-profiles

apparmor

apparmor

apparmor-profiles

apparmor-profiles-extra

apparmor-profiles-extra

apparmor-profiles

apparmor-profiles

evince

apparmor-profiles-extra

apparmor-profiles-extra

evince

evince

(We merely use evince as an example package in this table.)

Get in contact with upstream over the AppArmor upstream mailing list.

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

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

When including AppArmor profiles in a package, you might want to add to debian/control:  Suggests: apparmor

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 the software at will (also see AppArmor/HowToUse).

Debugging

Diagnose if a bug reported against my package might have been caused by AppArmor

Debugging a profile

Read https://wiki.ubuntu.com/DebuggingApparmor.

TL;DR

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 use 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

Contact the Debian AppArmor Packaging team

Get in touch with the team