home | help 
APPARMOR(7)			    AppArmor			     APPARMOR(7)

NAME
     AppArmor  -  kernel enhancement to confine programs to a limited set of re-
     sources.

DESCRIPTION
     AppArmor is a kernel enhancement to confine programs to a	limited  set  of
     resources.  AppArmor's  unique security model is to bind access control at-
     tributes to programs rather than to users.

     AppArmor confinement is provided via profiles loaded into	the  kernel  via
     apparmor_parser(8),   typically   through	 the  /etc/init.d/apparmor  SysV
     initscript (on Ubuntu, see UBUNTU POLICY LOAD, below), which is  used  like
     this:

	     # /etc/init.d/apparmor start
	     # /etc/init.d/apparmor stop
	     # /etc/init.d/apparmor restart

     AppArmor can operate in two modes: enforcement, and complain or learning:

     *	 enforcement  -   Profiles loaded in enforcement mode will result in en-
	 forcement of the policy defined in the profile  as  well  as  reporting
	 policy violation attempts to syslogd.

     *	 complain - Profiles loaded in	"complain" mode will not enforce policy.
	 Instead,  it will report policy violation attempts. This mode is conve-
	 nient for developing profiles. To manage complain mode  for  individual
	 profiles  the	utilities  aa-complain(8) and aa-enforce(8) can be used.
	 These utilities take a program name as an argument.

     Profiles are traditionally stored in files in /etc/apparmor.d/ under  file-
     names  with  the  convention of replacing the / in pathnames with . (except
     for the root /) so profiles are easier to manage (e.g.  the  /usr/sbin/nscd
     profile would be named usr.sbin.nscd).

     Profiles  are applied to a process at exec(3) time (as seen through the ex-
     ecve(2) system call); an already running process cannot be confined.   How-
     ever, once a profile is loaded for a program, that program will be confined
     on the next exec(3).

     AppArmor  supports  the  Linux  kernel's  securityfs  filesystem, and makes
     available the list of the profiles currently loaded; to mount the	filesys-
     tem:

	     # mount -tsecurityfs securityfs /sys/kernel/security
	     $ cat /sys/kernel/security/apparmor/profiles
	     /usr/bin/mutt
	     /usr/bin/gpg
		...

     Normally,	the  initscript will mount securityfs if it has not already been
     done.

     AppArmor also restricts what privileged operations a confined  process  may
     execute,  even if the process is running as root. A confined process cannot
     call the following system calls:

	     create_module(2) delete_module(2) init_module(2) ioperm(2)
	     iopl(2) ptrace(2) reboot(2) setdomainname(2)
	     sethostname(2) swapoff(2) swapon(2) sysctl(2)

UBUNTU POLICY LOAD
     Ubuntu systems use upstart(8) instead of a traditional  SysV  init  system.
     Because  upstart is an event-driven init system and understanding that pol-
     icy must be loaded before execution, Ubuntu loads policy in two ways:

      1. via upstart jobs for services started during the boot process
      2. via the AppArmor upstart job for any remaining policy

     The AppArmor upstart job is configured to make sure all  policy  is  loaded
     before  any  user sessions start. When developing policy it is important to
     know how your application is started and if policy load should  be  handled
     specially.

     The upstart job may be call with or without arguments, like so:

	     $ sudo start apparmor
	     $ sudo start apparmor ACTION=clear 	# clear policy cache
	     $ sudo start apparmor ACTION=teardown	# unload all policy
	     $ sudo start apparmor ACTION=reload	# reload policy
	     $ sudo start apparmor ACTION=force-reload	# same as 'reload'

     Because the job is an upstart(8) task, use 'start apparmor ACTION=teardown'
     to unload all policy.

     In  general, nothing extra has to be done for applications not started dur-
     ing boot or those that start after AppArmor's upstart job.

     If the confined application has an Upstart job,  adjust  the  job	to  call
     /lib/init/apparmor-profile-load with the filename of the policy file (rela-
     tive to /etc/apparmor.d/). For example:

	     pre-start script
		     /lib/init/apparmor-profile-load usr.bin.foo
	     end script

     If  the confined application does not have an Upstart job but it starts be-
     fore AppArmor's second stage initscript, then add a symlink from the policy
     file in /etc/apparmor.d to  /etc/apparmor/init/network-interface-security/.
     For example:

	     $ cd /etc/apparmor/init/network-interface-security/
	     $ sudo ln -s /etc/apparmor.d/usr.bin.foo .

     The network-interface-security Upstart job will load all the symlinked pol-
     icy files in /etc/apparmor/init/network-interface-security/ before any net-
     work  interfaces  come up. Because network interfaces come up very early in
     the boot process, this will help ensure that AppArmor policy is loaded  be-
     fore the confined application starts.

     In addition, AppArmor on Ubuntu stores policy in two places:

      1. /etc/apparmor.d for system policy
      2. /var/lib/apparmor/profiles for click policy

     See apparmor_parser(8) and aa-clickhook(1) for details.

ERRORS
     When  a confined process tries to access a file it does not have permission
     to access, the kernel will report a message through audit, similar to:

	     audit(1386511672.612:238): apparmor="DENIED" operation="exec"
	       parent=7589 profile="/tmp/sh" name="/bin/uname" pid=7605
	       comm="sh" requested_mask="x" denied_mask="x" fsuid=0 ouid=0

	     audit(1386511672.613:239): apparmor="DENIED" operation="open"
	       parent=7589 profile="/tmp/sh" name="/bin/uname" pid=7605
	       comm="sh" requested_mask="r" denied_mask="r" fsuid=0 ouid=0

	     audit(1386511772.804:246): apparmor="DENIED" operation="capable"
	       parent=7246 profile="/tmp/sh" pid=7589 comm="sh" pid=7589
	       comm="sh" capability=2  capname="dac_override"

     The permissions requested by the process are described  in  the  operation=
     and  denied_mask=	(for  files - capabilities etc. use a slightly different
     log format).  The "name" and process id of  the  running  program	are  re-
     ported, as well as the profile name including any "hat" that may be active,
     separated	by  "//". ("Name" is in quotes, because the process name is lim-
     ited to 15 bytes; it is the same as reported through the  Berkeley  process
     accounting.)

     For confined processes running under a profile that has been loaded in com-
     plain  mode,  enforcement will not take place and the log messages reported
     to audit will be of the form:

	     audit(1386512577.017:275): apparmor="ALLOWED" operation="open"
	       parent=8012 profile="/usr/bin/du" name="/etc/apparmor.d/tunables/"
	       pid=8049 comm="du" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0

	     audit(1386512577.017:276): apparmor="ALLOWED" operation="open"
	       parent=8012 profile="/usr/bin/du" name="/etc/apparmor.d/tunables/"
	       pid=8049 comm="du" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0

     If the userland auditd is not running, the kernel will send audit events to
     klogd; klogd will send the messages to syslog, which will log the	messages
     with  the	KERN facility. Thus, REJECTING and PERMITTING messages may go to
     either /var/log/audit/audit.log or /var/log/messages, depending upon  local
     configuration.

FILES
     /etc/init.d/apparmor
     /etc/apparmor/init/network-interface-security/
     /etc/apparmor.d/
     /var/lib/apparmor/
     /var/log/audit/audit.log
     /var/log/messages

SEE ALSO
     apparmor_parser(8),   aa_change_hat(2),  apparmor.d(5),  subdomain.conf(5),
     aa-autodep(1),  clean(1),	 auditd(8),   aa-unconfined(8),   aa-enforce(1),
     aa-complain(1), and <http://wiki.apparmor.net>.

AppArmor 2.11.0 		   2018-02-27			     APPARMOR(7)
home | help