Provided by: apparmor_2.8.95~2430-0ubuntu5_amd64 
NAME
apparmor.d - syntax of security profiles for AppArmor.
DESCRIPTION
AppArmor profiles describe mandatory access rights granted to given programs and are fed
to the AppArmor policy enforcement module using apparmor_parser(8). This man page
describes the format of the AppArmor configuration files; see apparmor(7) for an overview
of AppArmor.
FORMAT
The following is a BNF-style description of AppArmor policy configuration files; see below
for an example AppArmor policy file. AppArmor configuration files are line-oriented; #
introduces a comment, similar to shell scripting languages. The exception to this rule is
that #include will include the contents of a file inline to the policy; this behaviour is
modelled after cpp(1).
INCLUDE = '#include' ( ABS PATH | MAGIC PATH )
ABS PATH = '"' path '"' (the path is passed to open(2))
MAGIC PATH = '<' relative path '>' (the path is relative to /etc/apparmor.d/)
COMMENT = '#' TEXT
TEXT = any characters
PROFILE = [ COMMENT ... ] [ VARIABLE ASSIGNMENT ... ] ( '"' PROGRAM '"' | PROGRAM ) [
'flags=(complain)' ]'{' [ ( RESOURCE RULE | COMMENT | INCLUDE | SUBPROFILE |
'capability ' CAPABILITY | NETWORK RULE | MOUNT RULE | DBUS RULE | FILE RULE |
'change_profile -> ' PROGRAMCHILD ) ... ] '}'
SUBPROFILE = [ COMMENT ... ] ( PROGRAMHAT | 'profile ' PROGRAMCHILD ) '{' [ ( FILE
RULE | COMMENT | INCLUDE ) ... ] '}'
CAPABILITY = (lowercase capability name without 'CAP_' prefix; see capabilities(7))
NETWORK RULE = 'network' [ [ DOMAIN ] [ TYPE ] [ I <PROTOCOL> ] ] ','
DOMAIN = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' | 'bridge' | 'atmpvc' |
'x25' | 'inet6' | 'rose' | 'netbeui' | 'security' | 'key' | 'packet' | 'ash' |
'econet' | 'atmsvc' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' ) ','
TYPE = ( 'stream' | 'dgram' | 'seqpacket' | 'rdm' | 'raw' | 'packet' )
PROTOCOL = ( 'tcp' | 'udp' | 'icmp' )
PROGRAM = (non-whitespace characters except for '^', must start with '/'. Embedded
spaces or tabs must be quoted.)
PROGRAMHAT = '^' (non-whitespace characters; see aa_change_hat(2) for a description
of how this "hat" is used.)
PROGRAMCHILD = SUBPROFILE name
MOUNT RULE = ( MOUNT | REMOUNT | UMOUNT | PIVOT ROOT )
MOUNT = [ 'audit' ] [ 'deny' ] 'mount' [ MOUNT CONDITIONS ] [ SOURCE FILEGLOB ] [ -> [
MOUNTPOINT FILEGLOB ]
REMOUNT = [ 'audit' ] [ 'deny' ] 'remount' [ MOUNT CONDITIONS ] MOUNTPOINT FILEGLOB
UMOUNT = [ 'audit' ] [ 'deny' ] 'umount' [ MOUNT CONDITIONS ] MOUNTPOINT FILEGLOB
PIVOT ROOT = [ 'audit' ] [ 'deny' ] pivot_root [ OLD ABS PATH ] [ MOUNTPOINT ABS PATH
] [ -> PROGRAMCHILD ]
MOUNT CONDITIONS = [ ( 'fstype' | 'vfstype' ) ( '=' | 'in' ) MOUNT FSTYPE EXPRESSION ]
[ 'options' ( '=' | 'in' ) MOUNT FLAGS EXPRESSION ]
MOUNT FSTYPE EXPRESSION = ( MOUNT FSTYPE LIST | MOUNT EXPRESSION )
MOUNT FSTYPE LIST = Comma separated list of valid filesystem and virtual filesystem
types (eg ext4, debugfs, devfs, etc)
MOUNT FLAGS EXPRESSION = ( MOUNT FLAGS LIST | MOUNT EXPRESSION )
MOUNT FLAGS LIST = Comma separated list of MOUNT FLAGS.
MOUNT FLAGS = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec' | 'exec'
| 'sync' | 'async' | 'remount' | 'mand' | 'nomand' | 'dirsync' | 'nodirsync' |
'noatime' | 'atime' | 'nodiratime' | 'diratime' | 'bind' | 'move' | 'rec' | 'verbose'
| 'silent' | 'load' | 'acl' | 'noacl' | 'unbindable' | 'private' | 'slave' | 'shared'
| 'relative' | 'norelative' | 'iversion' | 'noiversion' | 'strictatime' | 'nouser' |
'user' )
MOUNT EXPRESSION = ( ALPHANUMERIC | AARE ) ...
PTRACE_RULE = [ 'audit' ] [ 'deny' ] 'ptrace' [ PTRACE ACCESS PERMISSIONS ] [ PTRACE
PEER ]
PTRACE ACCESS PERMISSIONS = PTRACE ACCESS | PTRACE ACCESS LIST
PTRACE ACCESS LIST = '(' Comma or space separated list of PTRACE ACCESS ')'
PTRACE ACCESS = ( 'r' | 'w' | 'rw' | 'read' | 'readby' | 'trace' | 'tracedby' )
PTRACE PEER = 'peer' '=' AARE
SIGNAL_RULE = [ 'audit' ] [ 'deny' ] 'signal' [ SIGNAL ACCESS PERMISSIONS ] [ SIGNAL
SET ] [ SIGNAL PEER ]
SIGNAL ACCESS PERMISSIONS = SIGNAL ACCESS | SIGNAL ACCESS LIST
SIGNAL ACCESS LIST = '(' Comma or space separated list of SIGNAL ACCESS ')'
SIGNAL ACCESS = ( 'r' | 'w' | 'rw' | 'read' | 'write' | 'send' | 'receive' )
SIGNAL SET = 'set' '=' '(' SIGNAL LIST ')'
SIGNAL LIST = Comma or space separated list of SIGNALS
SIGNALS = ( 'hup' | 'int' | 'quit' | 'ill' | 'trap' | 'abrt' | 'bus' | 'fpe' | 'kill'
| 'usr1' | 'segv' | 'usr2' | 'pipe' | 'alrm' | 'term' | 'stkflt' | 'chld' | 'cont' |
'stop' | 'stp' | 'ttin' | 'ttou' | 'urg' | 'xcpu' | 'xfsz' | 'vtalrm' | 'prof' |
'winch' | 'io' | 'pwr' | 'sys' | 'emt' | 'exists' )
SIGNAL PEER = 'peer' '=' AARE
DBUS RULE = ( DBUS MESSAGE RULE | DBUS SERVICE RULE | DBUS EAVESDROP RULE | DBUS
COMBINED RULE )
DBUS MESSAGE RULE = [ 'audit' ] [ 'deny' ] 'dbus' [ DBUS ACCESS EXPRESSION ] [ DBUS
BUS ] [ DBUS PATH ] [ DBUS INTERFACE ] [ DBUS MEMBER ] [ DBUS PEER ]
DBUS SERVICE RULE = [ 'audit' ] [ 'deny' ] 'dbus' [ DBUS ACCESS EXPRESSION ] [ DBUS
BUS ] [ DBUS NAME ]
DBUS EAVESDROP RULE = [ 'audit' ] [ 'deny' ] 'dbus' [ DBUS ACCESS EXPRESSION ] [ DBUS
BUS ]
DBUS COMBINED RULE = [ 'audit' ] [ 'deny' ] 'dbus' [ DBUS ACCESS EXPRESSION ] [ DBUS
BUS ]
DBUS ACCESS EXPRESSION = ( DBUS ACCESS | '(' DBUS ACCESS LIST ')' )
DBUS BUS = 'bus' '=' '(' 'system' | 'session' | '"' AARE '"' | AARE ')'
DBUS PATH = 'path' '=' '(' '"' AARE '"' | AARE ')'
DBUS INTERFACE = 'interface' '=' '(' '"' AARE '"' | AARE ')'
DBUS MEMBER = 'member' '=' '(' '"' AARE '"' | AARE ')'
DBUS PEER = 'peer' '=' '(' [ DBUS NAME ] [ DBUS LABEL ] ')'
DBUS NAME = 'name' '=' '(' '"' AARE '"' | AARE ')'
DBUS LABEL = 'label' '=' '(' '"' AARE '"' | AARE ')'
DBUS ACCESS LIST = Comma separated list of DBUS ACCESS
DBUS ACCESS = ( 'send' | 'receive' | 'bind' | 'eavesdrop' ) (some accesses are
incompatible with some rules; see below.)
AARE = ?*[]{}^ (see below for meanings)
FILE RULE = RULE QUALIFIER ( '"' FILEGLOB '"' | FILEGLOB ) ACCESS ','
RULE QUALIFIER = [ 'audit' ] [ 'deny' ] [ 'owner' ]
FILEGLOB = (must start with '/' (after variable expansion), AARE have special
meanings; see below. May include VARIABLE. Rules with embedded spaces or tabs must be
quoted. Rules must end with '/' to apply to directories.)
ACCESS = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' PROGRAMCHILD
| 'Cx -> ' PROGRAMCHILD | 'm' ) [ ACCESS ... ] (not all combinations are allowed; see
below.)
VARIABLE = '@{' ALPHA [ ( ALPHANUMERIC | '_' ) ... ] '}'
VARIABLE ASSIGNMENT = VARIABLE ('=' | '+=') (space separated values)
ALIAS RULE = ABS PATH '->' REWRITTEN ABS PATH ','
ALPHA = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
ALPHANUMERIC = ('0', '1', '2', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
All resources and programs need a full path. There may be any number of subprofiles (aka
child profiles) in a profile, limited only by kernel memory. Subprofile names are limited
to 974 characters. Child profiles can be used to confine an application in a special way,
or when you want the child to be unconfined on the system, but confined when called from
the parent. Hats are a special child profile that can be used with the aa_change_hat(2)
API call. Applications written or modified to use aa_change_hat(2) can take advantage of
subprofiles to run under different confinements, dependent on program logic. Several
aa_change_hat(2)-aware applications exist, including an Apache module, mod_apparmor(5); a
PAM module, pam_apparmor; and a Tomcat valve, tomcat_apparmor. Applications written or
modified to use change_profile(2) transition permanently to the specified profile. libvirt
is one such application.
Access Modes
File permission access modes consists of combinations of the following modes:
r - read
w - write -- conflicts with append
a - append -- conflicts with write
ux - unconfined execute
Ux - unconfined execute -- scrub the environment
px - discrete profile execute
Px - discrete profile execute -- scrub the environment
cx - transition to subprofile on execute
Cx - transition to subprofile on execute -- scrub the environment
ix - inherit execute
m - allow PROT_EXEC with mmap(2) calls
l - link
k - lock
Access Modes Details
r - Read mode
Allows the program to have read access to the file or directory listing. Read access
is required for shell scripts and other interpreted content.
w - Write mode
Allows the program to have write access to the file. Files and directories must have
this permission if they are to be unlinked (removed.) Write mode is not required on a
directory to rename or create files within the directory.
This mode conflicts with append mode.
a - Append mode
Allows the program to have a limited appending only write access to the file. Append
mode will prevent an application from opening the file for write unless it passes the
O_APPEND parameter flag on open.
The mode conflicts with Write mode.
ux - Unconfined execute mode
Allows the program to execute the program without any AppArmor profile being applied
to the program.
This mode is useful when a confined program needs to be able to perform a privileged
operation, such as rebooting the machine. By placing the privileged section in another
executable and granting unconfined execution rights, it is possible to bypass the
mandatory constraints imposed on all confined processes. For more information on what
is constrained, see the apparmor(7) man page.
WARNING 'ux' should only be used in very special cases. It enables the designated
child processes to be run without any AppArmor protection. 'ux' does not scrub the
environment of variables such as LD_PRELOAD; as a result, the calling domain may have
an undue amount of influence over the callee. Use this mode only if the child
absolutely must be run unconfined and LD_PRELOAD must be used. Any profile using this
mode provides negligible security. Use at your own risk.
Incompatible with 'Ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
Ux - unconfined execute -- scrub the environment
'Ux' allows the named program to run in 'ux' mode, but AppArmor will invoke the Linux
Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
(See ld.so(8) for some information on setuid/setgid environment scrubbing.)
WARNING 'Ux' should only be used in very special cases. It enables the designated
child processes to be run without any AppArmor protection. Use this mode only if the
child absolutely must be run unconfined. Use at your own risk.
Incompatible with 'ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
px - Discrete Profile execute mode
This mode requires that a discrete security profile is defined for a program executed
and forces an AppArmor domain transition. If there is no profile defined then the
access will be denied.
WARNING 'px' does not scrub the environment of variables such as LD_PRELOAD; as a
result, the calling domain may have an undue amount of influence over the callee.
Incompatible with 'Ux', 'ux', 'Px', 'cx', 'Cx', 'ix'.
Px - Discrete Profile execute mode -- scrub the environment
'Px' allows the named program to run in 'px' mode, but AppArmor will invoke the Linux
Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
(See ld.so(8) for some information on setuid/setgid environment scrubbing.)
Incompatible with 'Ux', 'ux', 'px', 'cx', 'Cx', 'ix'.
cx - Transition to Subprofile execute mode
This mode requires that a local security profile is defined and forces an AppArmor
domain transition to the named profile. If there is no profile defined then the access
will be denied.
WARNING 'cx' does not scrub the environment of variables such as LD_PRELOAD; as a
result, the calling domain may have an undue amount of influence over the callee.
Incompatible with 'Ux', 'ux', 'px', 'Px', 'Cx', 'ix'.
Cx - Transition to Subprofile execute mode -- scrub the environment
'Cx' allows the named program to run in 'cx' mode, but AppArmor will invoke the Linux
Kernel's unsafe_exec routines to scrub the environment, similar to setuid programs.
(See ld.so(8) for some information on setuid/setgid environment scrubbing.)
Incompatible with 'Ux', 'ux', 'px', 'Px', 'cx', 'ix'.
ix - Inherit execute mode
Prevent the normal AppArmor domain transition on execve(2) when the profiled program
executes the named program. Instead, the executed resource will inherit the current
profile.
This mode is useful when a confined program needs to call another confined program
without gaining the permissions of the target's profile, or losing the permissions of
the current profile. There is no version to scrub the environment because 'ix'
executions don't change privileges.
Incompatible with 'Ux', 'ux', 'Px', 'px', 'cx', 'Cx'. Implies 'm'.
m - Allow executable mapping
This mode allows a file to be mapped into memory using mmap(2)'s PROT_EXEC flag. This
flag marks the pages executable; it is used on some architectures to provide non-
executable data pages, which can complicate exploit attempts. AppArmor uses this mode
to limit which files a well-behaved program (or all programs on architectures that
enforce non-executable memory access controls) may use as libraries, to limit the
effect of invalid -L flags given to ld(1) and LD_PRELOAD, LD_LIBRARY_PATH, given to
ld.so(8).
l - Link mode
Allows the program to be able to create a link with this name. When a link is
created, the new link MUST have a subset of permissions as the original file (with the
exception that the destination does not have to have link access.) If there is an 'x'
rule on the new link, it must match the original file exactly.
k - lock mode
Allows the program to be able lock a file with this name. This permission covers both
advisory and mandatory locking.
Comments
Comments start with # and may begin at any place within a line. The comment ends when the
line ends. This is the same comment style as shell scripts.
Capabilities
The only capabilities a confined process may use may be enumerated; for the complete list,
please refer to capabilities(7). Note that granting some capabilities renders AppArmor
confinement for that domain advisory; while open(2), read(2), write(2), etc., will still
return error when access is not granted, some capabilities allow loading kernel modules,
arbitrary access to IPC, ability to bypass discretionary access controls, and other
operations that are typically reserved for the root user.
Network Rules
AppArmor supports simple coarse grained network mediation. The network rule restrict all
socket(2) based operations. The mediation done is a course grained check on whether a
socket of a given type and family can be created, read, or written. There is no mediation
based of port number or protocol beyond tcp, udp, and raw.
AppArmor network rules are accumulated so that the granted network permissions are the
union of all the listed network rule permissions.
AppArmor network rules are broad and general and become more restrictive as further
information is specified.
eg.
network, #allow access to all networking
network tcp, #allow access to tcp
network inet tcp, #allow access to tcp only for inet4 addresses
network inet6 tcp, #allow access to tcp only for inet6 addresses
Mount Rules
AppArmor supports mount mediation and allows specifying filesystem types and mount flags.
The syntax of mount rules in AppArmor is based on the mount(8) command syntax. Mount rules
must contain one of the mount, remount, umount or pivot_root keywords, but all mount
conditions are optional. Unspecified optional conditionals are assumed to match all
entries (eg, not specifying fstype means all fstypes are matched). Due to the complexity
of the mount command and how options may be specified, AppArmor allows specifying
conditionals three different ways:
1. If a conditional is specified using '=', then the rule only grants permission for
mounts matching the exactly specified options. For example, an AppArmor policy with
the following rule:
mount options=ro /dev/foo -> /mnt/,
Would match:
$ mount -o ro /dev/foo /mnt
but not either of these:
$ mount -o ro,atime /dev/foo /mnt
$ mount -o rw /dev/foo /mnt
2. If a conditional is specified using 'in', then the rule grants permission for mounts
matching any combination of the specified options. For example, if an AppArmor policy
has the following rule:
mount options in (ro,atime) /dev/foo -> /mnt/,
all of these mount commands will match:
$ mount -o ro /dev/foo /mnt
$ mount -o ro,atime /dev/foo /mnt
$ mount -o atime /dev/foo /mnt
but none of these will:
$ mount -o ro,sync /dev/foo /mnt
$ mount -o ro,atime,sync /dev/foo /mnt
$ mount -o rw /dev/foo /mnt
$ mount -o rw,noatime /dev/foo /mnt
$ mount /dev/foo /mnt
3. If multiple conditionals are specified in a single mount rule, then the rule grants
permission for each set of options. This provides a shorthand when writing mount rules
which might help to logically break up a conditional. For example, if an AppArmor
policy has the following rule:
mount options=ro options=atime
both of these mount commands will match:
$ mount -o ro /dev/foo /mnt
$ mount -o atime /dev/foo /mnt
but this one will not:
$ mount -o ro,atime /dev/foo /mnt
Note that separate mount rules are distinct and the options do not accumulate. For
example, these AppArmor mount rules:
mount options=ro, mount options=atime,
are not equivalent to either of these mount rules:
mount options=(ro,atime),
mount options in (ro,atime),
To help clarify the flexibility and complexity of mount rules, here are some example rules
with accompanying matching commands:
mount,
the 'mount' rule without any conditionals is the most generic and allows any mount.
Equivalent to 'mount fstype=** options=** ** -> /**'.
mount /dev/foo,
allow mounting of /dev/foo anywhere with any options. Some matching mount commands:
$ mount /dev/foo /mnt
$ mount -t ext3 /dev/foo /mnt
$ mount -t vfat /dev/foo /mnt
$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint
mount options=ro /dev/foo,
allow mounting of /dev/foo anywhere, as read only. Some matching mount commands:
$ mount -o ro /dev/foo /mnt
$ mount -o ro /dev/foo /some/where/else
mount options=(ro,atime) /dev/foo,
allow mount of /dev/foo anywhere, as read only and using inode access times. Some
matching mount commands:
$ mount -o ro,atime /dev/foo /mnt
$ mount -o ro,atime /dev/foo /some/where/else
mount options in (ro,atime) /dev/foo,
allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime' (see
above). Some matching mount commands:
$ mount -o ro /dev/foo /mnt
$ mount -o atime /dev/foo /some/where/else
$ mount -o ro,atime /dev/foo /some/other/place
mount options=ro /dev/foo, mount options=atime /dev/foo,
allow mount of /dev/foo anywhere as read only, and allow mount of /dev/foo anywhere
using inode access times. Note this is expressed as two different rules. Matches:
$ mount -o ro /dev/foo /mnt/1
$ mount -o atime /dev/foo /mnt/2
mount -> /mnt/**,
allow mounting anything under a directory in /mnt/**. Some matching mount commands:
$ mount /dev/foo1 /mnt/1
$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2
mount options=ro -> /mnt/**,
allow mounting anything under /mnt/**, as read only. Some matching mount commands:
$ mount -o ro /dev/foo1 /mnt/1
$ mount -o ro /dev/foo2 /mnt/deep/path/foo2
mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/,
allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and using
inode access times. Matches only:
$ mount -o rw,atime /dev/sdb1 /mnt/stick
mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/,
allow mounting /dev/foo on /mmt/ read only and using inode access times or allow
mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'. Matches only:
$ mount -o ro,atime /dev/foo /mnt
$ mount -o nodev /dev/foo /mnt
$ mount -o user /dev/foo /mnt
$ mount -o nodev,user /dev/foo /mnt
PTrace rules
AppArmor supports mediation of ptrace(2). AppArmor PTrace rules are accumulated so that
the granted PTrace permissions are the union of all the listed PTrace rule permissions.
AppArmor PTrace permissions are implied when a rule does not explicitly state an access
list. By default, all PTrace permissions are implied.
The trace and tracedby permissions govern ptrace(2) while read and readby govern certain
proc(5) filesystem accesses, kcmp(2), futexes (get_robust_list(2)) and perf trace events.
For a ptrace operation to be allowed the profile of the tracing process and the profile of
the target task must both have the correct permissions. For example, the profile of the
process attaching to another task must have the trace permission for the target task's
profile, and the task being traced must have the tracedby permission for the tracing
process' profile.
Example AppArmor PTrace rules:
# Allow all PTrace access
ptrace,
# Explicitly allow all PTrace access,
ptrace (read, readby, trace, tracedby),
# Explicitly deny use of ptrace(2)
deny ptrace (trace),
# Allow unconfined processes (eg, a debugger) to ptrace us
ptrace (readby, tracedby) peer=unconfined,
# Allow ptrace of a process running under the /usr/bin/foo profile
ptrace (trace) peer=/usr/bin/foo,
Signal rules
AppArmor supports mediation of signal(7). AppArmor signal rules are accumulated so that
the granted signal permissions are the union of all the listed signal rule permissions.
AppArmor signal permissions are implied when a rule does not explicitly state an access
list. By default, all signal permissions are implied.
For the sending of a signal to be allowed, the profile of the sending process and the
profile of the target task must both have the correct permissions. For example, the
profile of a process sending a signal to another task must have the send permission for
the target task's profile, and the task receiving the signal must have a receive
permission for the sending process' profile.
Example AppArmor signal rules:
# Allow all signal access
signal,
# Explicitly deny sending the HUP and INT signals
deny signal (send) set=(hup, int),
# Allow unconfined processes to send us signals
signal (receive) peer=unconfined,
# Allow sending of signals to a process running under the /usr/bin/foo
# profile
signal (send) peer=/usr/bin/foo,
# Allow checking for PID existence
signal (receive, send) set=("exists"),
# Allow us to signal ourselves using the built-in @{profile_name} variable
signal peer=@{profile_name},
DBus rules
AppArmor supports DBus mediation. The mediation is performed in conjunction with the DBus
daemon. The DBus daemon verifies that communications over the bus are permitted by
AppArmor policy.
AppArmor DBus rules are accumulated so that the granted DBus permissions are the union of
all the listed DBus rule permissions.
AppArmor DBus rules are broad and general and become more restrictive as further
information is specified. Policy may be specified down to the interface member level
(method or signal name), however the contents of messages are not examined.
Some AppArmor DBus permissions are not compatible with all AppArmor DBus rules. The
'bind' permission cannot be used in message rules. The 'send' and 'receive' permissions
cannot be used in service rules. The 'eavesdrop' permission cannot be used in rules
containing any conditionals outside of the 'bus' conditional.
AppArmor DBus permissions are implied when a rule does not explicitly state an access
list. By default, all DBus permissions are implied. Only message permissions are implied
for message rules and only service permissions are implied for service rules.
Example AppArmor DBus rules:
# Allow all DBus access
dbus,
# Explicitly allow all DBus access,
dbus (send, receive, bind),
# Deny send/receive/bind access to the session bus
deny dbus bus=session,
# Allow bind access for a particular name on any bus
dbus bind name=com.example.ExampleName,
# Allow receive access for a particular path and interface
dbus receive path=/com/example/path interface=com.example.Interface,
# Deny send/receive access to the system bus for a particular interface
deny dbus bus=system interface=com.example.ExampleInterface,
# Allow send access for a particular path, interface, member, and pair of
# peer names:
dbus send
bus=session
path=/com/example/path
interface=com.example.Interface
member=ExampleMethod
peer=(name=(com.example.ExampleName1|com.example.ExampleName2)),
# Allow eavesdropping on the system bus
dbus eavesdrop bus=system,
# Allow and audit all eavesdropping
audit dbus eavesdrop,
Variables
AppArmor's policy language allows embedding variables into file rules to enable easier
configuration for some common (and pervasive) setups. Variables may have multiple values
assigned, but any variable assignments must be made before the start of the profile.
The parser will automatically expand variables to include all values that they have been
assigned; it is an error to reference a variable without setting at least one value.
At the time of this writing, the following variables are defined in the provided AppArmor
policy:
@{HOME}
@{HOMEDIRS}
@{multiarch}
@{pid}
@{PROC}
@{securityfs}
@{sys}
@{tid}
@{XDG_DESKTOP_DIR}
@{XDG_DOWNLOAD_DIR}
@{XDG_TEMPLATES_DIR}
@{XDG_PUBLICSHARE_DIR}
@{XDG_DOCUMENTS_DIR}
@{XDG_MUSIC_DIR}
@{XDG_PICTURES_DIR}
@{XDG_VIDEOS_DIR}
These are defined in files in /etc/apparmor.d/tunables and are used in many of the
abstractions described later.
You may also add files in /etc/apparmor.d/tunables/home.d for site-specific customization
of @{HOMEDIRS}, /etc/apparmor.d/tunables/multiarch.d for @{multiarch} and
/etc/apparmor.d/tunables/xdg-user-dirs.d for @{XDG_*}.
The special @{profile_name} variable is set to the profile name and may be used in all
policy.
Alias rules
AppArmor also provides alias rules for remapping paths for site-specific layouts. They are
an alternative form of path rewriting to using variables, and are done after variable
resolution. Alias rules must occur within the preamble of the profile. System-wide aliases
are found in /etc/apparmor.d/tunables/alias, which is included by
/etc/apparmor.d/tunables/global. /etc/apparmor.d/tunables/global is typically included at
the beginning of an AppArmor profile.
Globbing
File resources may be specified with a globbing syntax similar to that used by popular
shells, such as csh(1), bash(1), zsh(1).
* can substitute for any number of characters, excepting '/'
** can substitute for any number of characters, including '/'
? can substitute for any single character excepting '/'
[abc]
will substitute for the single character a, b, or c
[a-c]
will substitute for the single character a, b, or c
[^a-c]
will substitute for any single character not matching a, b or c
{ab,cd}
will expand to one rule to match ab, one rule to match cd
When AppArmor looks up a directory the pathname being looked up will end with a slash
(e.g., /var/tmp/); otherwise it will not end with a slash. Only rules that match a
trailing slash will match directories. Some examples, none matching the /tmp/ directory
itself, are:
/tmp/*
Files directly in /tmp.
/tmp/*/
Directories directly in /tmp.
/tmp/**
Files and directories anywhere underneath /tmp.
/tmp/**/
Directories anywhere underneath /tmp.
Rule Qualifiers
There are several rule qualifiers that can be applied to permission rules. Rule
qualifiers can modify the rule and/or permissions within the rule.
audit
Specifies that permissions requests that match the rule should be recorded to the
audit log.
deny
Specifies that permissions requests that match the rule should be denied without
logging. Can be combined with 'audit' to enable logging.
owner
Specifies that the task must have the same euid/fsuid as the object being referenced
by the permission check.
#include mechanism
AppArmor provides an easy abstraction mechanism to group common file access requirements;
this abstraction is an extremely flexible way to grant site-specific rights and makes
writing new AppArmor profiles very simple by assembling the needed building blocks for any
given program.
The use of '#include' is modelled directly after cpp(1); its use will replace the
'#include' statement with the specified file's contents. #include "/absolute/path"
specifies that /absolute/path should be used. #include "relative/path" specifies that
relative/path should be used, where the path is relative to the current working directory.
#include <magic/path> is the most common usage; it will load magic/path relative to a
directory specified to apparmor_parser(8). /etc/apparmor.d/ is the AppArmor default.
The supplied AppArmor profiles follow several conventions; the abstractions stored in
/etc/apparmor.d/abstractions/ are some large clusters that are used in most profiles. What
follows are short descriptions of how some of the abstractions are used.
abstractions/audio
Includes accesses to device files used for audio applications.
abstractions/authentication
Includes access to files and services typically necessary for services that perform
user authentication.
abstractions/base
Includes files that should be readable and writable in all profiles.
abstractions/bash
Includes many files used by bash; useful for interactive shells and programs that call
system(3).
abstractions/consoles
Includes read and write access to the device files controlling the virtual console,
sshd(8), xterm(1), etc. This abstraction is needed for many programs that interact
with users.
abstractions/fonts
Includes access to fonts and the font libraries.
abstractions/gnome
Includes read and write access to GNOME configuration files, as well as read access to
GNOME libraries.
abstractions/kde
Includes read and write access to KDE configuration files, as well as read access to
KDE libraries.
abstractions/kerberosclient
Includes file access rules needed for common kerberos clients.
abstractions/nameservice
Includes file rules to allow DNS, LDAP, NIS, SMB, user and group password databases,
services, and protocols lookups.
abstractions/perl
Includes read access to perl modules.
abstractions/user-download
abstractions/user-mail
abstractions/user-manpages
abstractions/user-tmp
abstractions/user-write
Some profiles for typical "user" programs will use these include files to describe
rights that users have in the system.
abstractions/wutmp
Includes write access to files used to maintain wtmp(5) and utmp(5) databases, used
with the w(1) and associated commands.
abstractions/X
Includes read access to libraries, configuration files, X authentication files, and
the X socket.
The abstractions stored in /etc/apparmor.d/program-chunks/ are intended for use by
specific program suites, and are not generally useful.
Some of the abstractions rely on variables that are set in files in the
/etc/apparmor.d/tunables/ directory. These variables are currently @{HOME} and
@{HOMEDIRS}. Variables cannot be set in profile scope; they can only be set before the
profile. Therefore, any profiles that use abstractions should either #include
<tunables/global> or otherwise ensure that @{HOME} and @{HOMEDIRS} are set before starting
the profile definition. The aa-autodep(8) and aa-genprof(8) utilities will automatically
emit #include <tunables/global> in generated profiles.
EXAMPLE
An example AppArmor profile:
# a variable definition in the preamble
@{HOME} = /home/*/ /root/
# a comment about foo.
/usr/bin/foo {
/bin/mount ux,
/dev/{,u}random r,
/etc/ld.so.cache r,
/etc/foo.conf r,
/etc/foo/* r,
/lib/ld-*.so* rmix,
/lib/lib*.so* r,
/proc/[0-9]** r,
/usr/lib/** r,
/tmp/foo.pid wr,
/tmp/foo.* lrw,
/@{HOME}/.foo_file rw,
/usr/bin/baz Cx -> baz,
# a comment about foo's hat (subprofile), bar.
^bar {
/lib/ld-*.so* rmix,
/usr/bin/bar rmix,
/var/spool/* rwl,
}
# a comment about foo's subprofile, baz.
profile baz {
#include <abstractions/bash>
owner /proc/[0-9]*/stat r,
/bin/bash ixr,
/var/lib/baz/ r,
owner /var/lib/baz/* rw,
}
}
FILES
/etc/init.d/boot.apparmor
/etc/apparmor.d/
KNOWN BUGS
Mount options support the use of pattern matching but mount flags are not correctly
intersected against specified patterns. Eg, 'mount options=**,' should be equivalent
to 'mount,', but it is not. (LP: #965690)
The fstype may not be matched against when certain mount command flags are used.
Specifically fstype matching currently only works when creating a new mount and not
remount, bind, etc.
Mount rules with multiple 'options' conditionals are not applied as documented but
instead merged such that 'options in (ro,nodev) options in (atime)' is equivalent to
'options in (ro,nodev,atime)'.
When specifying mount options with the 'in' conditional, both the positive and
negative values match when specifying one or the other. Eg, 'rw' matches when 'ro' is
specified and 'dev' matches when 'nodev' is specified such that 'options in
(ro,nodev)' is equivalent to 'options in (rw,dev)'.
SEE ALSO
apparmor(7), apparmor_parser(8), aa-complain(1), aa-enforce(1), aa_change_hat(2),
mod_apparmor(5), and <http://wiki.apparmor.net>.