apparmor_profiles.xml

<?xml version="1.0"?>
<!DOCTYPE chapter [
  <!ENTITY % entities SYSTEM "generic-entities.ent">
  %entities;
]>

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cha-apparmor-profiles">
<!-- fs 2011-11-09 - see bnc #722915
     ("set capabilities" was dropped upstream)

 <sect1 id="sec-apparmor-profiles-set-capabilities">
  <title>Setting Capabilities per Profile</title>

  <para>
   Normally &aa; only restricts existing native Linux controls and does not
   grant additional privileges. Therefore a program, having been granted
   write access to a file via its profile, would not be able to actually
   write to this file as long as the mode bits are set to read-only.
  </para>

  <para>
   The only exception to this strict rule is the <literal>set
   capability</literal> rule. This provides the ability to give non-root
   users administrative privileges, as defined in the
   <systemitem>capabilities(7)</systemitem> man page. Contrary to setting a
   program to setuid or using file system capabilities (that apply to single
   programs only), the set capability rule allows the user to apply
   capabilities to multiple programs running under a specific profile (by
   using ix transitions). For security reasons, set capability rules will
   not be inherited (when a program leaves the profile, it loses the
   elevated privilege).
  </para>

  <warning>
   <title>Use set capabilities Rules with Extreme Caution</title>
   <para>
    Using the set capabilities rules allows to give processes &rootuser;
    privileges. Therefore these rules should be used with extreme caution
    and only in exceptional cases.
   </para>
  </warning>

  <para>
   To set a capability in a profile the keyword <quote>set</quote> is
   prefixed to a capability rule. Setting a capability also implicitly adds
   a capability rule allowing that capability.
  </para>

<screen>set capability cap_chown,</screen>

  <note>
   <para>
    Currently the tools can not be used to add rlimit rules to profiles. The
    only way to add rlimit controls to a profile is to manually edit the
    profile with a text editor. The tools will still work with profiles
    containing rlimit rules and will not remove them, so it is safe to use
    the tools to update profiles containing them.
   </para>
  </note>
 </sect1>
-->
 <title>Profile Components and Syntax</title>
 <info>
      <meta name="description">Learn how to build and manage profiles using SUSE's intuitive tools for confining applications, controlling system calls, capabilities, and file access</meta>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
        <dm:bugtracker>
          </dm:bugtracker>
      </dm:docmanager>
    <revhistory xml:id="rh-cha-apparmor-profiles">
   <revision>
     <date>2026-04-09</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
    <para>
  Building &aa; profiles to confine an application is very
  straightforward and intuitive. &aa; ships with several tools that
  assist in profile creation. It does not require you to do any programming
  or script handling. The only task that is required of the administrator is
  to determine a policy of strictest access and execute permissions for each
  application that needs to be hardened.
 </para>
 <para>
  Updates or modifications to the application profiles are only required if
  the software configuration or the desired range of activities changes.
  &aa; offers intuitive tools to handle profile updates and
  modifications.
 </para>
 <para>
  You are ready to build &aa; profiles after you select the programs to
  profile. To do so, it is important to understand the components and syntax
  of profiles. &aa; profiles contain several building blocks that help
  build simple and reusable profile code:
 </para>
 <variablelist>
  <varlistentry>
   <term>Include Files</term>
   <listitem>
    <para>
     Include statements are used to pull in parts of other &aa; profiles
     to simplify the structure of new profiles.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Abstractions</term>
   <listitem>
    <para>
     Abstractions are include statements grouped by common application
     tasks.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Program Chunks</term>
   <listitem>
    <para>
     Program chunks are include statements that contain chunks of profiles
     that are specific to program suites.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Capability Entries</term>
   <listitem>
    <para>
     Capability entries are profile entries for any of the POSIX.1e
     <link xlink:href="http://en.wikipedia.org/wiki/POSIX#POSIX.1"/> Linux
     capabilities allowing a fine-grained control over what a confined
     process is allowed to do through system calls that require privileges.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Network Access Control Entries</term>
   <listitem>
    <para>
     Network Access Control Entries mediate network access based on the
     address type and family.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>Local Variable Definitions</term>
   <listitem>
    <para>
     Local variables define shortcuts for paths.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>File Access Control Entries</term>
   <listitem>
    <para>
     File Access Control Entries specify the set of files an application can
     access.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term>rlimit Entries</term>
   <listitem>
    <para>
     rlimit entries set and control an application's resource limits.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
 <para>
  For help determining the programs to profile, refer to
  <xref linkend="sec-apparmor-concept-determine"/>.
  To start building &aa; profiles with &yast;, proceed to
  <xref linkend="cha-apparmor-yast"/>. To build profiles using the &aa;
  command line interface, proceed to
  <xref linkend="cha-apparmor-commandline"/>.
 </para>
 <sect1 xml:id="sec-apparmor-profiles-parts">
  <title>Breaking an &aa; Profile into Its Parts</title>

  <para>
   The easiest way of explaining what a profile consists of and how to
   create one is to show the details of a sample profile, in this case for a
   hypothetical application called <command>/usr/bin/foo</command>:
  </para>

<screen>#include &lt;tunables/global&gt;<co xml:id="co-apparmor-profiles-vardef"/>

# a comment naming the application to confine
/usr/bin/foo<co xml:id="co-apparmor-profiles-path"/> {<co xml:id="co-apparmor-profiles-brack"/>
   #include &lt;abstractions/base&gt;<co xml:id="co-apparmor-profiles-incl"/>

   capability setgid<co xml:id="co-apparmor-profiles-capent"/>,
   network inet tcp<co xml:id="co-apparmor-profiles-netd"/>,

   link /etc/sysconfig/foo -&gt; /etc/foo.conf,<co xml:id="co-apparmor-profiles-lp"/>
   /bin/mount            ux,
   /dev/{,u}<co xml:id="co-apparmor-profiles-ext"/>random     r,
   /etc/ld.so.cache      r,
   /etc/foo/*            r,
   /lib/ld-*.so*         mr,
   /lib/lib*.so*         mr,
   /proc/[0-9]**         r,
   /usr/lib/**           mr,
   /tmp/                 r,<co xml:id="co-apparmor-profiles-pathent"/>
   /tmp/foo.pid          wr,
   /tmp/foo.*            lrw,
   /@{HOME}<co xml:id="co-apparmor-profiles-variable"/>/.foo_file   rw,
   /@{HOME}/.foo_lock    kw,
   owner<co xml:id="co-apparmor-profiles-owner"/> /shared/foo/** rw,
   /usr/bin/foobar       Cx,<co xml:id="co-apparmor-profiles-cx"/>
   /bin/**               Px -&gt; bin_generic,<co xml:id="co-apparmor-profiles-named"/>

   # a comment about foo's local (children) profile for /usr/bin/foobar.

   profile /usr/bin/foobar<co xml:id="co-apparmor-profiles-local"/> {
      /bin/bash          rmix,
      /bin/cat           rmix,
      /bin/more          rmix,
      /var/log/foobar*   rwl,
      /etc/foobar        r,
   }

  # foo's hat, bar.
   ^bar<co xml:id="co-apparmor-profiles-hat"/> {
    /lib/ld-*.so*         mr,
    /usr/bin/bar          px,
    /var/spool/*          rwl,
   }
}
</screen>

  <calloutlist>
   <callout arearefs="co-apparmor-profiles-vardef">
    <para>
     This loads a file containing variable definitions.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-path">
    <para>
     The normalized path to the program that is confined.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-brack">
    <para>
     The curly braces (<literal>{}</literal>) serve as a container for
     include statements, subprofiles, path entries, capability entries, and
     network entries.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-incl">
    <para>
     This directive pulls in components of &aa; profiles to simplify
     profiles.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-capent">
    <para>
     Capability entry statements enable each of the 29 POSIX.1e draft
     capabilities.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-netd">
    <para>
     A directive determining the kind of network access allowed to the
     application. For details, refer to
     <xref linkend="sec-apparmor-profiles-nac"/>.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-lp">
    <para>
     A link pair rule specifying the source and the target of a link. See
     <xref linkend="sec-apparmor-profiles-perm-link-pair"/> for more
     information.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-ext">
    <para>
     The curly braces (<literal>{}</literal>) here allow for each of the
     listed possibilities, one of which is the empty string.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-pathent">
    <para>
     A path entry specifying what areas of the file system the program can
     access. The first part of a path entry specifies the absolute path of a
     file (including regular expression globbing) and the second part
     indicates permissible access modes (for example <literal>r</literal>
     for read, <literal>w</literal> for write, and <literal>x</literal> for
     execute). A whitespace of any kind (spaces or tabs) can precede the
     path name, but must separate the path name and the mode specifier.
     Spaces between the access mode and the trailing comma are optional.
     Find a comprehensive overview of the available access modes in
     <xref linkend="sec-apparmor-profiles-perm"/>.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-variable">
    <para>
     This variable expands to a value that can be changed without changing
     the entire profile.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-owner">
    <para>
     An owner conditional rule, granting read and write permission on files
     owned by the user. Refer to
     <xref linkend="sec-apparmor-profiles-perm-owner"/> for more
     information.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-cx">
    <para>
     This entry defines a transition to the local profile
     <literal>/usr/bin/foobar</literal>. Find a comprehensive overview of
     the available execute modes in
     <xref linkend="sec-apparmor-profiles-exec"/>.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-named">
    <para>
     A named profile transition to the profile bin_generic located in the
     global scope. See <xref linkend="sec-apparmor-profiles-exec-named"/>
     for details.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-local">
    <para>
     The local profile <literal>/usr/bin/foobar</literal> is defined in this
     section.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-hat">
    <para>
     This section references a <quote>hat</quote> subprofile of the
     application. For more details on &aa;'s ChangeHat feature, refer to
     <xref linkend="cha-apparmor-hat"/>.
    </para>
   </callout>
  </calloutlist>

  <para>
   When a profile is created for a program, the program can access only the
   files, modes, and POSIX capabilities specified in the profile. These
   restrictions are in addition to the native Linux access controls.
  </para>

  <formalpara>
   <title>Example:</title>
   <para>
    To gain the capability <systemitem>CAP_CHOWN</systemitem>, the
    program must have both access to <systemitem>CAP_CHOWN</systemitem>
    under conventional Linux access controls (typically, be a
    &rootuser;-owned process) and have the capability
    <systemitem>chown</systemitem> in its profile. Similarly, to be able
    to write to the file <filename>/foo/bar</filename> the program must
    have both the correct user ID and mode bits set in the files
    attributes and have <literal>/foo/bar w</literal> in its profile.
   </para>
  </formalpara>

  <para>
   Attempts to violate &aa; rules are recorded in
   <filename>/var/log/audit/audit.log</filename> if the
   <systemitem class="resource">audit</systemitem> package is installed, or
   in <filename>/var/log/messages</filename>, or only in
   <systemitem>journalctl</systemitem> if no traditional syslog is
   installed. Often &aa; rules prevent an attack from working
   because necessary files are not accessible and, in all cases, &aa;
   confinement restricts the damage that the attacker can do to the set of
   files permitted by &aa;.
  </para>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-types">
  <title>Profile Types</title>

  <para>
   &aa; knows four different types of profiles: standard profiles,
   unattached profiles, local profiles and hats. Standard and unattached
   profiles are stand-alone profiles, each stored in a file under
   <filename>/etc/apparmor.d/</filename>. Local profiles and hats are
   children profiles embedded inside of a parent profile used to provide
   tighter or alternate confinement for a subtask of an application.
  </para>

  <sect2 xml:id="sec-apparmor-profiles-types-attached">
   <title>Standard Profiles</title>
   <para>
    The default &aa; profile is attached to a program by its name, so a
    profile name must match the path to the application it is to confine.
   </para>
<screen>/usr/bin/foo {
...
}
</screen>
   <para>
    This profile will be automatically used whenever an unconfined process
    executes <filename>/usr/bin/foo</filename>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-types-unattached">
   <title>Unattached Profiles</title>
   <para>
    Unattached profiles do not reside in the file system namespace and
    therefore are not automatically attached to an application. The name of
    an unattached profile is preceded by the keyword
    <literal>profile</literal>. You can freely choose a profile name, except
    for the following limitations: the name must not begin with a
    <literal>:</literal> or <literal>.</literal> character. If it contains a
    whitespace, it must be quoted. If the name begins with a
    <literal>/</literal>, the profile is considered to be a standard
    profile, so the following two profiles are identical:
   </para>
<screen>profile /usr/bin/foo {
...
}
/usr/bin/foo {
...
}</screen>
   <para>
    Unattached profiles are never used automatically, nor can they be
    transitioned to through a <literal>Px</literal> rule. They need to be
    attached to a program by either using a named profile transition (see
    <xref linkend="sec-apparmor-profiles-exec-named"/>) or with the
    <literal>change_profile</literal> rule (see
    <xref linkend="sec-apparmor-profiles-types-change"/>).
   </para>
   <para>
    Unattached profiles are useful for specialized profiles for system
    utilities that generally should not be confined by a system-wide profile
    (for example, <literal>/bin/bash</literal>). They can also be used to
    set up roles or to confine a user.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-types-local">
   <title>Local Profiles</title>
   <para>
    Local profiles provide a convenient way to provide specialized
    confinement for utility programs launched by a confined application.
    They are specified like standard profiles, except that they are embedded
    in a parent profile and begin with the <literal>profile</literal>
    keyword:
   </para>
<screen>/parent/profile {
   ...
   profile /local/profile {
      ...
   }
}</screen>
   <para>
    To transition to a local profile, either use a <literal>cx</literal>
    rule (see <xref linkend="sec-apparmor-profiles-exec-cx"/>) or a named
    profile transition (see
    <xref linkend="sec-apparmor-profiles-exec-named"/>).
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-types-hat">
   <title>Hats</title>
   <para>
    &aa; "hats" are a local profiles with some additional restrictions
    and an implicit rule allowing for <literal>change_hat</literal> to be
    used to transition to them. Refer to <xref linkend="cha-apparmor-hat"/>
    for a detailed description.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-types-change">
   <title>Change rules</title>
   <para>
    &aa; provides <literal>change_hat</literal> and
    <literal>change_profile</literal> rules that control domain
    transitioning. <literal>change_hat</literal> are specified by defining
    hats in a profile, while <literal>change_profile</literal> rules refer
    to another profile and start with the keyword
    <literal>change_profile</literal>:
   </para>
<screen>change_profile -&gt; /usr/bin/foobar,</screen>
   <para>
    Both <literal>change_hat</literal> and <literal>change_profile</literal>
    provide for an application directed profile transition, without having
    to launch a separate application. <literal>change_profile</literal>
    provides a generic one way transition between any of the loaded
    profiles. <literal>change_hat</literal> provides for a returnable parent
    child transition where an application can switch from the parent profile
    to the hat profile and if it provides the correct secret key return to
    the parent profile at a later time.
   </para>
   <para>
    <literal>change_profile</literal> is best used in situations where an
    application goes through a trusted setup phase and then can lower its
    privilege level. Any resources mapped or opened during the start-up
    phase may still be accessible after the profile change, but the new
    profile will restrict the opening of new resources, and will even limit
    some  resources opened before the switch. Specifically, memory
    resources will still be available while capability and file resources
    (as long as they are not memory mapped) can be limited.
   </para>
   <para>
    <literal>change_hat</literal> is best used in situations where an
    application runs a virtual machine or an interpreter that does not
    provide direct access to the applications resources (for example
    Apache's <literal>mod_php</literal>). Since
    <literal>change_hat</literal> stores the return secret key in the
    application's memory the phase of reduced privilege should not have
    direct access to memory. It is also important that file access is
    properly separated, since the hat can restrict accesses to a file handle
    but does not close it. If an application does buffering and provides
    access to the open files with buffering, the accesses to these files
    might not be seen by the kernel and hence not restricted by the new
    profile.
   </para>
   <warning>
    <title>Safety of Domain Transitions</title>
    <para>
     The <literal>change_hat</literal> and <literal>change_profile</literal>
     domain transitions are less secure than a domain transition done
     through an exec because they do not affect a process's memory mappings,
     nor do they close resources that have already been opened.
    </para>
   </warning>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-includes">
  <title>Include Statements</title>

  <para>
   Include statements are directives that pull in components of other
   &aa; profiles to simplify profiles. Include files retrieve access
   permissions for programs. By using an include, you can give the program
   access to directory paths or files that are also required by other
   programs. Using includes can reduce the size of a profile.
  </para>

  <para>
   Include statements normally begin with a hash (<literal>#</literal>)
   sign. This is confusing because the same hash sign is used for comments
   inside profile files. Because of this, <literal>#include</literal> is
   treated as an include only if there is no preceding #
   (<literal>##include</literal> is a comment) and there is no whitespace
   between <literal>#</literal> and <literal>include</literal> (<literal>#
   include</literal> is a comment).
  </para>

  <para>
   You can also use <literal>include</literal> without the leading
   <literal>#</literal>.
  </para>

<screen>include "/etc/apparmor.d/abstractions/foo"</screen>

  <para>
   is the same as using
  </para>

<screen>#include "/etc/apparmor.d/abstractions/foo"</screen>

  <note>
   <title>No Trailing ','</title>
   <para>
    Note that because includes follow the C pre-processor syntax, they do
    not have a trailing ',' like most &aa; rules.
   </para>
  </note>

  <para>
   By slight changes in syntax, you can modify the behavior of
   <literal>include</literal>. If you use <literal>""</literal> around the
   including path, you instruct the parser to do an absolute or relative
   path lookup.
  </para>

<screen>include "/etc/apparmor.d/abstractions/foo"   # absolute path
include "abstractions/foo"   # relative path to the directory of current file</screen>

  <para>
   Note that when using relative path includes, when the file is included,
   it is considered the new current file for its includes. For example,
   suppose you are in the <filename>/etc/apparmor.d/bar</filename> file,
   then
  </para>

<screen>include "abstractions/foo"</screen>

  <para>
   includes the file <filename>/etc/apparmor.d/abstractions/foo</filename>.
   If then there is
  </para>

<screen>include "example"</screen>

  <para>
   inside the <filename>/etc/apparmor.d/abstractions/foo</filename> file, it
   includes <filename>/etc/apparmor.d/abstractions/example</filename>.
  </para>

  <para>
   The use of <literal>&lt;&gt;</literal> specifies to try the include
   path (specified by <option>-I</option>, defaults to the
   <filename>/etc/apparmor.d</filename> directory) in an ordered way. So
   assuming the include path is
  </para>

<screen>-I /etc/apparmor.d/ -I /usr/share/apparmor/</screen>

  <para>
   then the include statement
  </para>

<screen>include &lt;abstractions/foo&gt;</screen>

  <para>
   will try <filename>/etc/apparmor.d/abstractions/foo</filename>, and if
   that file does not exist, the next try is
   <filename>/usr/share/apparmor/abstractions/foo</filename>.
  </para>

  <tip>
   <para>
    The default include path can be overridden manually by passing
    <option>-I</option> to the <command>apparmor_parser</command>, or by
    setting the include paths in
    <filename>/etc/apparmor/parser.conf</filename>:
   </para>
<screen>Include /usr/share/apparmor/
Include /etc/apparmor.d/</screen>
   <para>
    Multiple entries are allowed, and they are taken in the same order as
    when they are when using <option>-I</option> or
    <option>--Include</option> from the <command>apparmor_parser</command>
    command line.
   </para>
  </tip>

  <para>
   If an include ends with '/', this is considered a directory include, and
   all files within the directory are included.
  </para>

  <para>
   To assist you in profiling your applications, &aa; provides three
   classes of includes: abstractions, program chunks and tunables.
  </para>

  <sect2 xml:id="sec-apparmor-profiles-includes-abstractions">
   <title>Abstractions</title>
   <para>
    Abstractions are includes that are grouped by common application tasks.
    These tasks include access to authentication mechanisms, access to name
    service routines, common graphics requirements, and system accounting.
    Files listed in these abstractions are specific to the named task.
    Programs that require one of these files usually also require
    other files listed in the abstraction file (depending on the local
    configuration and the specific requirements of the program). Find
    abstractions in <filename>/etc/apparmor.d/abstractions</filename>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-includes-chunks">
   <title>Program Chunks</title>
   <para>
    The program-chunks directory
    (<filename>/etc/apparmor.d/program-chunks</filename>) contains some
    chunks of profiles that are specific to program suites and not generally
    useful outside of the suite, thus are never suggested for use in
    profiles by the profile wizards (<command>aa-logprof</command> and
    <command>aa-genprof</command>). Currently, program chunks are only
    available for the postfix program suite.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-includes-tunables">
   <title>Tunables</title>
   <para>
    The tunables directory (<filename>/etc/apparmor.d/tunables</filename>)
    contains global variable definitions. When used in a profile, these
    variables expand to a value that can be changed without changing the
    entire profile. Add all the tunables definitions that should be
    available to every profile to
    <filename>/etc/apparmor.d/tunables/global</filename>.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-capabilities">
  <title>Capability Entries (POSIX.1e)</title>

  <para>
   Capability rules are simply the word <literal>capability</literal>
   followed by the name of the POSIX.1e capability as defined in the
   <systemitem>capabilities(7)</systemitem> man page. You can list multiple
   capabilities in a single rule, or grant all implemented capabilities with
   the bare keyword <literal>capability</literal>.
  </para>

<screen>
capability dac_override sys_admin,   # multiple capabilities
capability,                          # grant all capabilities
</screen>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-nac">
  <title>Network Access Control</title>

  <para>
   &aa; allows mediation of network access based on the address type and
   family. The following illustrates the network access rule syntax:
  </para>

<screen>network [[&lt;domain&gt;<co xml:id="co-apparmor-profiles-nac-dom"/>][&lt;type<co xml:id="co-apparmor-profiles-nac-type"/>&gt;][&lt;protocol<co xml:id="co-apparmor-profiles-nac-proto"/>&gt;]]</screen>

  <calloutlist>
   <callout arearefs="co-apparmor-profiles-nac-dom">
    <para>
     Supported domains: <literal>inet</literal>, <literal>ax25</literal>,
     <literal>ipx</literal>, <literal>appletalk</literal>,
     <literal>netrom</literal>, <literal>bridge</literal>,
     <literal>x25</literal>, <literal>inet6</literal>,
     <literal>rose</literal>, <literal>netbeui</literal>,
     <literal>security</literal>, <literal>key</literal>,
     <literal>packet</literal>, <literal>ash</literal>,
     <literal>econet</literal>, <literal>atmsvc</literal>,
     <literal>sna</literal>, <literal>irda</literal>,
     <literal>pppox</literal>, <literal>wanpipe</literal>,
     <literal>bluetooth</literal>, <literal>unix</literal>,
     <literal>atmpvc</literal>,<literal>netlink</literal>,
     <literal>llc</literal>, <literal>can</literal>,
     <literal>tipc</literal>, <literal>iucv</literal>,
     <literal>rxrpc</literal>, <literal>isdn</literal>,
     <literal>phonet</literal>, <literal>ieee802154</literal>,
     <literal>caif</literal>, <literal>alg</literal>,
     <literal>nfc</literal>, <literal>vsock</literal>
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-type">
    <para>
     Supported types: <literal>stream</literal>, <literal>dgram</literal>,
     <literal>seqpacket</literal>, <literal>rdm</literal>,
     <literal>raw</literal>, <literal>packet</literal>
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-proto">
    <para>
     Supported protocols: <literal>tcp</literal>, <literal>udp</literal>,
     <literal>icmp</literal>
    </para>
   </callout>
  </calloutlist>

  <para>
   The &aa; tools support only family and type specification. The &aa;
   module emits only <literal>network <replaceable>DOMAIN</replaceable>
   <replaceable>TYPE</replaceable></literal> in <quote>ACCESS DENIED</quote>
   messages. And only these are output by the profile generation tools, both
   &yast; and command line.
  </para>

  <para>
   The following examples illustrate possible network-related rules to be
   used in &aa; profiles. Note that the syntax of the last two are not
   currently supported by the &aa; tools.
  </para>

<screen>network<co xml:id="co-apparmor-profiles-nac-nw"/>,
network inet<co xml:id="co-apparmor-profiles-nac-inet"/>,
network inet6<co xml:id="co-apparmor-profiles-nac-inet6"/>,
network inet stream<co xml:id="co-apparmor-profiles-nac-istream"/>,
network inet tcp<co xml:id="co-apparmor-profiles-nac-itcp"/>,
network tcp<co xml:id="co-apparmor-profiles-nac-tcp"/>,
</screen>

  <calloutlist>
   <callout arearefs="co-apparmor-profiles-nac-nw">
    <para>
     Allow all networking. No restrictions applied with regard to domain,
     type, or protocol.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-inet">
    <para>
     Allow general use of IPv4 networking.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-inet6">
    <para>
     Allow general use of IPv6 networking.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-istream">
    <para>
     Allow the use of IPv4 TCP networking.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-itcp">
    <para>
     Allow the use of IPv4 TCP networking, paraphrasing the rule above.
    </para>
   </callout>
   <callout arearefs="co-apparmor-profiles-nac-tcp">
    <para>
     Allow the use of both IPv4 and IPv6 TCP networking.
    </para>
   </callout>
  </calloutlist>
 </sect1>
 <sect1 role="General" xml:id="sec-apparmor-profiles-glob">
  <title>Profile Names, Flags, Paths, and Globbing</title>

  <para>
   A profile is usually attached to a program by specifying a full path to
   the program's executable. For example in the case of a standard profile
   (see <xref linkend="sec-apparmor-profiles-types-attached"/>), the profile
   is defined by
  </para>

<screen>/usr/bin/foo { ... }</screen>

  <para>
   The following sections describe several useful techniques that can be
   applied when naming a profile or putting a profile in the context of
   other existing ones, or specifying file paths.
  </para>

  <para>
   &aa; explicitly distinguishes directory path names from file path
   names. Use a trailing <literal>/</literal> for any directory path that
   needs to be explicitly distinguished:
  </para>

  <variablelist>
   <varlistentry>
    <term><filename>/some/random/example/* r</filename>
    </term>
    <listitem>
     <para>
      Allow read access to files in the
      <filename>/some/random/example</filename> directory.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/some/random/example/ r</filename>
    </term>
    <listitem>
     <para>
      Allow read access to the directory only.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/some/**/ r</filename>
    </term>
    <listitem>
     <para>
      Give read access to any directories below <filename>/some</filename>
      (but not /some/ itself).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/some/random/example/** r</filename>
    </term>
    <listitem>
     <para>
      Give read access to files and directories under
      <filename>/some/random/example</filename> (but not
      /some/random/example/ itself).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><filename>/some/random/example/**[^/] r</filename>
    </term>
    <listitem>
     <para>
      Give read access to files under
      <filename>/some/random/example</filename>. Explicitly exclude
      directories (<literal>[^/]</literal>).
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Globbing (or regular expression matching) is when you modify the
   directory path using wild cards to include a group of files or
   subdirectories. File resources can be specified with a globbing syntax
   similar to that used by popular shells, such as csh, Bash, and zsh.
  </para>

  <informaltable>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>
       <para>
        <literal>*</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for any number of any characters, except
        <literal>/</literal>.
       </para>
       <para>
        Example: An arbitrary number of file path elements.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>**</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for any number of characters, including
        <literal>/</literal>.
       </para>
       <para>
        Example: An arbitrary number of path elements, including entire
        directories.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>?</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for any single character, except <literal>/</literal>.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>[abc]</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for the single character <literal>a</literal>,
        <literal>b</literal>, or <literal>c</literal>.
       </para>
       <para>
        Example: a rule that matches <literal>/home[01]/*/.plan</literal>
        allows a program to access <filename>.plan</filename> files for
        users in both <filename>/home0</filename> and
        <filename>/home1</filename>.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>[a-c]</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for the single character <literal>a</literal>,
        <literal>b</literal>, or <literal>c</literal>.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>{ab,cd}</literal>
       </para>
      </entry>
      <entry>
       <para>
        Expands to one rule to match <literal>ab</literal> and one rule to
        match <literal>cd</literal>.
       </para>
       <para>
        Example: a rule that matches <literal>/{usr,www}/pages/**</literal>
        grants access to Web pages in both <filename>/usr/pages</filename>
        and <filename>/www/pages</filename>.
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>[^a]</literal>
       </para>
      </entry>
      <entry>
       <para>
        Substitutes for any character except <literal>a</literal>.
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>

  <sect2 xml:id="sec-apparmor-profiles-flags">
   <title>Profile Flags</title>
   <para>
    Profile flags control the behavior of the related profile. You can add
    profile flags to the profile definition by editing it manually, see the
    following syntax:
   </para>
<screen>/path/to/profiled/binary flags=(list_of_flags) {
  [...]
}</screen>
   <para>
    You can use multiple flags separated by a comma ',' or space ' '. There
    are three basic types of profile flags: mode, relative, and attach
    flags.
   </para>
   <para>
    <emphasis>Mode</emphasis> flag is <literal>complain</literal> (illegal
    accesses are allowed and logged). If it is omitted, the profile is in
    <literal>enforce</literal> mode (enforces the policy).
   </para>
   <tip>
    <para>
     A more flexible way of setting the whole profile into complain mode is
     to create a symbolic link from the profile file inside the
     <filename>/etc/apparmor.d/force-complain/</filename> directory.
    </para>
<screen>ln -s /etc/apparmor.d/bin.ping /etc/apparmor.d/force-complain/bin.ping</screen>
   </tip>
   <para>
    <emphasis>Relative</emphasis> flags are
    <literal>chroot_relative</literal> (states that the profile is relative
    to the chroot instead of namespace) or
    <literal>namespace_relative</literal> (the default, with the path being
    relative to outside the chroot). They are mutually exclusive.
   </para>
   <para>
    <emphasis>Attach</emphasis> flags consist of two pairs of mutually
    exclusive flags: <literal>attach_disconnected</literal> or
    <literal>no_attach_disconnected</literal> (determine if path names
    resolved to be outside of the namespace are attached to the root, which
    means they have the '/' character at the beginning), and
    <literal>chroot_attach</literal> or <literal>chroot_no_attach</literal>
    (control path name generation when in a chroot environment while a file
    is accessed that is external to the chroot but within the namespace).
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-glob-variables">
   <title>Using Variables in Profiles</title>
   <para>
    &aa; allows to use variables holding paths in profiles. Use global
    variables to make your profiles portable and local variables to create
    shortcuts for paths.
   </para>
   <para>
    A typical example of when global variables come in handy are network
    scenarios in which user home directories are mounted in different
    locations. Instead of rewriting paths to home directories in all
    affected profiles, you only need to change the value of a variable.
    Global variables are defined under
    <filename>/etc/apparmor.d/tunables</filename> and need to be made
    available via an include statement. Find the variable definitions for
    this use case (<envar>@{HOME}</envar> and <envar>@{HOMEDIRS}</envar>) in
    the <filename>/etc/apparmor.d/tunables/home</filename> file.
   </para>
   <para>
    Local variables are defined at the head of a profile. This is useful to
    provide the base of for a chrooted path, for example:
   </para>
<screen>@{CHROOT_BASE}=/tmp/foo
/sbin/rsyslogd {
...
# chrooted applications
@{CHROOT_BASE}/var/lib/*/dev/log w,
@{CHROOT_BASE}/var/log/** w,
...
}</screen>
   <para>
    In the following example, while @{HOMEDIRS} lists where all the user
    home directories are stored, @{HOME} is a space-separated list of home
    directories. Later on, @{HOMEDIRS} is expanded by two new specific
    places where user home directories are stored.
   </para>
<screen>@{HOMEDIRS}=/home/
@{HOME}=@{HOMEDIRS}/*/ /root/
[...]
@{HOMEDIRS}+=/srv/nfs/home/ /mnt/home/</screen>
   <note>
    <para>
     With the current &aa; tools, variables can only be used when
     manually editing and maintaining a profile.
    </para>
   </note>
  </sect2>

  <sect2 xml:id="apparmor-profiles-pattern-matching">
   <title>Pattern Matching</title>
   <para>
    Profile names can contain globbing expressions allowing the profile to
    match against multiple binaries.
   </para>
   <para>
    The following example is valid for systems where the
    <command>foo</command> binary resides either in
    <filename>/usr/bin</filename> or <filename>/bin</filename>.
   </para>
<screen>/{usr/,}bin/foo { ... }</screen>
   <para>
    In the following example, when matching against the executable
    <filename>/bin/foo</filename>, the <literal>/bin/foo</literal> profile
    is an exact match so it is chosen. For the executable
    <filename>/bin/fat</filename>, the profile <literal>/bin/foo</literal>
    does not match, and because the <literal>/bin/f*</literal> profile is
    more specific (less general) than <literal>/bin/**</literal>, the
    <literal>/bin/f*</literal> profile is chosen.
   </para>
<screen>
/bin/foo { ... }

/bin/f*  { ... }

/bin/**  { ... }
</screen>
   <para>
    For more information on profile name globbing examples, see the man page
    of &aa;, <command>man 5 apparmor.d,</command>, section
    <literal>Globbing</literal>.
   </para>
  </sect2>

  <sect2 xml:id="apparmor-profiles-namespaces">
   <title>Namespaces</title>
   <para>
    Namespaces are used to provide different profiles sets. Say one for the
    system, another for a chroot environment or container. Namespaces are
    hierarchical&mdash;a namespace can see its children but a child
    cannot see its parent. Namespace names start with a colon
    <literal>:</literal> followed by an alphanumeric string, a trailing
    colon <literal>:</literal> and an optional double slash
    <literal>//</literal>, such as
   </para>
<screen>:childNameSpace://</screen>
   <para>
    Profiles loaded to a child namespace will be prefixed with their
    namespace name (viewed from a parent's perspective):
   </para>
<screen>:childNameSpace://apache</screen>
   <para>
    Namespaces can be entered via the <literal>change_profile</literal> API,
    or named profile transitions:
   </para>
<screen>/path/to/executable px -&gt; :childNameSpace://apache</screen>
  </sect2>

  <sect2 xml:id="apparmor-profiles-naming-attachment">
   <title>Profile Naming and Attachment Specification</title>
   <para>
    Profiles can have a name, and an attachment specification. This allows
    for profiles with a logical name that can be more meaningful to
    users/administrators than a profile name that contains pattern matching
    (see <xref linkend="apparmor-profiles-pattern-matching"/>). For example,
    the default profile
   </para>
<screen>/** { ... }</screen>
   <para>
    can be named
   </para>
<screen>profile default /** { ... }</screen>
   <para>
    Also, a profile with pattern matching can be named. For example:
   </para>
<screen>/usr/lib/firefox-3.*/firefox-*bin { ... }</screen>
   <para>
    can be named
   </para>
<screen>profile firefox /usr/lib/firefox-3.*/firefox-*bin { ... }</screen>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-glob-alias">
   <title>Alias Rules</title>
   <para>
    Alias rules provide an alternative way to manipulate profile path
    mappings to site specific layouts. They are an alternative form of path
    rewriting to using variables, and are done post variable resolution. The
    alias rule says to treat rules that have the same source prefix as if
    the rules are at target prefix.
   </para>
<screen>alias /home/ -&gt; /usr/home/</screen>
   <para>
    All the rules that have a prefix match to <filename>/home/</filename>
    will provide access to <filename>/usr/home/</filename>. For example
   </para>
<screen>/home/username/** r,</screen>
   <para>
    allows as well access to
   </para>
<screen>/usr/home/username/** r,</screen>
   <para>
    Aliases provide a quick way of remapping rules without the need to
    rewrite them. They keep the source path still accessible&mdash;in our
    example, the alias rule keeps the paths under
    <filename>/home/</filename> still accessible.
   </para>
   <para>
    With the <literal>alias</literal> rule, you can point to multiple
    targets at the same time.
   </para>
<screen>alias /home/ -&gt; /usr/home/
alias /home/ -&gt; /mnt/home/</screen>
   <note>
    <para>
     With the current &aa; tools, alias rules can only be used when
     manually editing and maintaining a profile.
    </para>
   </note>
   <tip>
    <para>
     Insert global alias definitions in the file
     <filename>/etc/apparmor.d/tunables/alias</filename>.
    </para>
   </tip>
  </sect2>
 </sect1>
 <sect1 role="General" xml:id="sec-apparmor-profiles-perm">
  <title>File Permission Access Modes</title>

  <para>
   File permission access modes consist of combinations of the following
   modes:
  </para>

  <informaltable>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>
       <para>
        <literal>r</literal>
       </para>
      </entry>
      <entry>
       <para>
        Read mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>w</literal>
       </para>
      </entry>
      <entry>
       <para>
        Write mode (mutually exclusive to <literal>a</literal>)
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>a</literal>
       </para>
      </entry>
      <entry>
       <para>
        Append mode (mutually exclusive to <literal>w</literal>)
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>k</literal>
       </para>
      </entry>
      <entry>
       <para>
        File locking mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>l</literal>
       </para>
      </entry>
      <entry>
       <para>
        Link mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>link <replaceable>FILE</replaceable> -&gt;
        <replaceable>TARGET</replaceable></literal>
       </para>
      </entry>
      <entry>
       <para>
        Link pair rule (cannot be combined with other access modes)
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>

  <sect2 xml:id="sec-apparmor-profiles-perm-r">
   <title>Read Mode (r)</title>
   <para>
    Allows the program to have read access to the resource. Read access is
    required for shell scripts and other interpreted content and determines
    if an executing process can core dump.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-w">
   <title>Write Mode (w)</title>
   <para>
    Allows the program to have write access to the resource. Files must have
    this permission if they are to be unlinked (removed).
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-a">
   <title>Append Mode (a)</title>
   <para>
    Allows a program to write to the end of a file. In contrast to the
    <literal>w</literal> mode, the append mode does not include the ability
    to overwrite data, to rename, or to remove a file. The append permission
    is typically used with applications who need to be able to write to log
    files, but which should not be able to manipulate any existing data in
    the log files. As the append permission is a subset of the permissions
    associated with the write mode, the <literal>w</literal> and
    <literal>a</literal> permission flags cannot be used together and are
    mutually exclusive.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-k">
   <title>File Locking Mode (k)</title>
   <para>
    The application can take file locks. Former versions of &aa; allowed
    files to be locked if an application had access to them. By using a
    separate file locking mode, &aa; makes sure locking is restricted
    only to those files which need file locking and tightens security as
    locking can be used in several denial-of-service attack scenarios.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-link">
   <title>Link Mode (l)</title>
   <para>
    The link mode mediates access to hard links. When a link is created, the
    target file must have the same access permissions as the link created
    (but the destination does not need link access).
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-link-pair">
   <title>Link Pair</title>
   <para>
    The link mode grants permission to link to arbitrary files, provided the
    link has a subset of the permissions granted by the target (subset
    permission test).
   </para>
<screen>/srv/www/htdocs/index.html rl,</screen>
   <para>
    By specifying origin and destination, the link pair rule provides
    greater control over how hard links are created. Link pair rules by
    default do not enforce the link subset permission test that the standard
    rules link permission requires.
   </para>
<screen>link /srv/www/htdocs/index.html -&gt; /var/www/index.html</screen>
   <para>
    To force the rule to require the test, the <literal>subset</literal>
    keyword is used. The following rules are equivalent:
   </para>
<screen>/var/www/index.html l,
link subset /var/www/index.html -&gt; /**,</screen>
   <note>
    <para>
     Currently link pair rules are not supported by &yast; and the
     command line tools. Manually edit your profiles to use them. Updating
     such profiles using the tools is safe, because the link pair entries
     will not be touched.
    </para>
   </note>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-file-allow">
   <title>Optional <literal>allow</literal> and <literal>file</literal> Rules</title>
   <para>
    The <literal>allow</literal> prefix is optional, and it is idiomatically
    implied if not specified and the <literal>deny</literal> (see
    <xref linkend="sec-apparmor-profiles-perm-deny"/>) keyword is not used.
   </para>
<screen>
allow file /example r,
allow /example r,
allow network,
</screen>
   <para>
    You can also use the optional <literal>file</literal> keyword. If you
    omit it and there are no other rule types that start with a keyword,
    such as <literal>network</literal> or <literal>mount</literal>, it is
    automatically implied.
   </para>
<screen>file /example/rule r,</screen>
   <para>
    is equivalent to
   </para>
<screen>/example/rule r,</screen>
   <para>
    The following rule grants access to all files:
   </para>
<screen>file,</screen>
   <para>
    which is equal to
   </para>
<screen>/** rwmlk,</screen>
   <para>
    File rules can use leading or trailing permissions. The permissions
    should not be specified as a trailing permission, but rather used at the
    start of the rule. This is important in that it makes file rules behave
    like any other rule types.
   </para>
<screen>
/path rw,            # old style
rw /path,            # leading permission
file rw /path,       # with explicit 'file' keyword
allow file rw /path, # optional 'allow' keyword added
</screen>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-owner">
   <title>Owner Conditional Rules</title>
   <para>
    The file rules can be extended so that they can be conditional upon
    the user being the owner of the file (the fsuid needs to match the
    file's UID). For this purpose the <literal>owner</literal> keyword
    is put in front of the rule. Owner conditional rules accumulate like
    regular file rules do.
   </para>
<screen>owner /home/*/** rw</screen>
   <para>
    When using file ownership conditions with link rules the ownership test
    is done against the target file so the user must own the file to be able
    to link to it.
   </para>
   <note>
    <title>Precedence of Regular File Rules</title>
    <para>
     Owner conditional rules are considered a subset of regular file rules.
     If a regular file rule overlaps with an owner conditional file rule,
     the rules are merged. Consider the following example.
    </para>
<screen>/foo r,
owner /foo rw,  # or w,</screen>
    <para>
     The rules are merged&mdash;it results in <literal>r</literal> for
     everybody, and <literal>w</literal> for the owner only.
    </para>
   </note>
   <tip>
    <para>
     To address everybody <emphasis>but</emphasis> the owner of the file,
     use the keyword <literal>other</literal>.
    </para>
<screen>owner /foo rw,
other /foo r,</screen>
   </tip>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-perm-deny">
   <title>Deny Rules</title>
   <para>
    Deny rules can be used to annotate or quiet known rejects. The
    profile generating tools will not ask about a known reject treated
    with a deny rule. Such a reject will also not show up in the audit
    logs when denied, keeping the log files lean. If this is not
    desired, put the keyword <literal>audit</literal> in front of the
    deny entry.
   </para>
   <para>
    It is also possible to use deny rules in combination with allow rules.
    This allows you to specify a broad allow rule, and then subtract a few
    known files that should not be allowed. Deny rules can also be combined
    with owner rules, to deny files owned by the user. The following example
    allows read/write access to everything in a users directory except write
    access to the <filename>.ssh/</filename> files:
   </para>
<screen>deny /home/*/.ssh/** w,
owner /home/*/** rw,</screen>
   <para>
    The extensive use of deny rules is generally not encouraged, because it
    makes it much harder to understand what a profile does. However a
    judicious use of deny rules can simplify profiles. Therefore the tools
    only generate profiles denying specific files and will not use
    globbing in deny rules. Manually edit your profiles to add deny rules
    using globbing. Updating such profiles using the tools is safe, because
    the deny entries will not be touched.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-exec">
  <title>Execute Modes</title>

  <para>
   Execute modes, also named profile transitions, consist of the following
   modes:
  </para>

  <informaltable>
   <tgroup cols="2">
    <tbody>
     <row>
      <entry>
       <para>
        <literal>Px</literal>
       </para>
      </entry>
      <entry>
       <para>
        Discrete profile execute mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>Cx</literal>
       </para>
      </entry>
      <entry>
       <para>
        Discrete local profile execute mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>Ux</literal>
       </para>
      </entry>
      <entry>
       <para>
        Unconfined execute mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>ix</literal>
       </para>
      </entry>
      <entry>
       <para>
        Inherit execute mode
       </para>
      </entry>
     </row>
     <row>
      <entry>
       <para>
        <literal>m</literal>
       </para>
      </entry>
      <entry>
       <para>
        Allow <literal>PROT_EXEC</literal> with <command>mmap(2)</command>
        calls
       </para>
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>

  <sect2 xml:id="sec-apparmor-profiles-exec-px">
   <title>Discrete Profile Execute Mode (Px)</title>
   <para>
    This mode requires that a discrete security profile is defined for a
    resource executed at an &aa; domain transition. If there is no
    profile defined, the access is denied.
   </para>
   <para>
    Incompatible with <literal>Ux</literal>, <literal>ux</literal>,
    <literal>px</literal>, and <literal>ix</literal>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-cx">
   <title>Discrete Local Profile Execute Mode (Cx)</title>
   <para>
    As <literal>Px</literal>, but instead of searching the global profile
    set, <literal>Cx</literal> only searches the local profiles of the
    current profile. This profile transition provides a way for an
    application to have alternate profiles for helper applications.
   </para>
   <note>
    <title>Limitations of the Discrete Local Profile Execute Mode (Cx)</title>
    <para>
     Currently, Cx transitions are limited to top level profiles and cannot
     be used in hats and children profiles. This restriction will be removed
     in the future.
    </para>
   </note>
   <para>
    Incompatible with <literal>Ux</literal>, <literal>ux</literal>,
    <literal>Px</literal>, <literal>px</literal>, <literal>cx</literal>, and
    <literal>ix</literal>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-ux">
   <title>Unconfined Execute Mode (Ux)</title>
   <para>
    Allows the program to execute the resource without any &aa; profile
    applied to the executed resource. 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.
    Allowing a root process to go unconfined means it can change &aa;
    policy itself. For more information about what is constrained, see the
    <systemitem>apparmor(7)</systemitem> man page.
   </para>
   <para>
    This mode is incompatible with <literal>ux</literal>,
    <literal>px</literal>, <literal>Px</literal>, and <literal>ix</literal>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-clean">
   <title>Unsafe Exec Modes</title>
   <para>
    Use the lowercase versions of exec modes&mdash;<literal>px</literal>,
    <literal>cx</literal>, <literal>ux</literal>&mdash;only in very
    special cases. They do not scrub the environment of variables such as
    <envar>LD_PRELOAD</envar>. As a result, the calling domain may have an
    undue amount of influence over the called resource. Use these modes only
    if the child absolutely <emphasis>must</emphasis> be run unconfined and
    <envar>LD_PRELOAD</envar> must be used. Any profile using such modes
    provides negligible security. Use at your own risk.
   </para>
   <remark>jsegitz 2014-07-15: if the child absolutely needs to use the environment of the calling process. (running unconfined isn't the important part here,
   you can you px and not run unconfined)</remark>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-ix">
   <title>Inherit Execute Mode (ix)</title>
   <para>
    <literal>ix</literal> prevents the normal &aa; domain transition on
    <command>execve(2)</command> when the profiled program executes the
    named program. Instead, the executed resource inherits the current
    profile.
   </para>
   <para>
    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 <literal>ix</literal> executions do not
    change privileges.
   </para>
   <para>
    Incompatible with <literal>cx</literal>, <literal>ux</literal>, and
    <literal>px</literal>. Implies <literal>m</literal>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-m">
   <title>Allow Executable Mapping (m)</title>
   <para>
    This mode allows a file to be mapped into memory using
    <command>mmap(2)</command>'s <envar>PROT_EXEC</envar> flag. This flag
    marks the pages executable. It is used on some architectures to provide
    non executable data pages, which can complicate exploit attempts.
    &aa; 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
    <option>-L</option> flags given to <command>ld(1)</command> and
    <envar>LD_PRELOAD</envar>, <envar>LD_LIBRARY_PATH</envar>, given to
    <command>ld.so(8)</command>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-named">
   <title>Named Profile Transitions</title>
   <para>
    By default, the <literal>px</literal> and <literal>cx</literal> (and
    their clean exec variants, too) transition to a profile whose name
    matches the executable name. With named profile transitions, you can
    specify a profile to be transitioned to. This is useful if multiple
    binaries need to share a single profile, or if they need to use a
    different profile than their name would specify. Named profile
    transitions can be used with <literal>cx</literal>,
    <literal>Cx</literal>, <literal>px</literal> and <literal>Px</literal>.
    Currently there is a limit of twelve named profile transitions per
    profile.
   </para>
   <para>
    Named profile transitions use <literal>-&gt;</literal> to indicate the
    name of the profile that needs to be transitioned to:
   </para>
<screen>/usr/bin/foo
{
  /bin/** px -&gt; shared_profile,
  ...
  /usr/*bash cx -&gt; local_profile,
  ...
  profile local_profile
  {
    ...
  }
}
</screen>
   <note>
    <title>Difference Between Normal and Named Transitions</title>
    <para>
     When used with globbing, normal transitions provide a <quote>one to
     many</quote> relationship&mdash;<literal>/bin/** px</literal> will
     transition to <filename>/bin/ping</filename>,
     <filename>/bin/cat</filename>, etc, depending on the program being run.
    </para>
    <para>
     Named transitions provide a <quote>many to one</quote>
     relationship&mdash;all programs that match the rule regardless of
     their name will transition to the specified profile.
    </para>
    <para>
     Named profile transitions show up in the log as having the mode
     <literal>Nx</literal>. The name of the profile to be changed to is
     listed in the <literal>name2</literal> field.
    </para>
   </note>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-fallback">
   <title>Fallback Modes for Profile Transitions</title>
   <para>
    The <literal>px</literal> and <literal>cx</literal> transitions specify
    a hard dependency&mdash;if the specified profile does not exist, the
    exec will fail. With the inheritance fallback, the execution will
    succeed but inherit the current profile. To specify inheritance
    fallback, <literal>ix</literal> is combined with <literal>cx</literal>,
    <literal>Cx</literal>, <literal>px</literal> and <literal>Px</literal>
    into the modes <literal>cix</literal>, <literal>Cix</literal>,
    <literal>pix</literal> and <literal>Pix</literal>.
   </para>
<screen>/path Cix -&gt; profile_name,</screen>
   <para>
    or
   </para>
<screen>Cix /path -&gt; profile_name,</screen>
   <para>
    where <literal>-&gt; profile_name</literal> is optional.
   </para>
   <para>
    The same applies if you add the unconfined <literal>ux</literal> mode,
    where the resulting modes are <literal>cux</literal>,
    <literal>CUx</literal>, <literal>pux</literal> and
    <literal>PUx</literal>. These modes allow falling back to
    <quote>unconfined</quote> when the specified profile is not found.
   </para>
<screen>/path PUx -&gt; profile_name,</screen>
   <para>
    or
   </para>
<screen>PUx /path -&gt; profile_name,</screen>
   <para>
    where <literal>-&gt; profile_name</literal> is optional.
   </para>
   <para>
    The fallback modes can be used with named profile transitions, too.
   </para>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-variables">
   <title>Variable Settings in Execution Modes</title>
   <para>
    When choosing one of the Px, Cx or Ux execution modes, take into account
    that the following environment variables are removed from the
    environment before the child process inherits it. As a consequence,
    applications or processes relying on any of these variables do not work
    anymore if the profile applied to them carries Px, Cx or Ux flags:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      <envar>GCONV_PATH</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>GETCONF_DIR</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>HOSTALIASES</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_AUDIT</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_DEBUG</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_DEBUG_OUTPUT</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_DYNAMIC_WEAK</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_LIBRARY_PATH</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_ORIGIN_PATH</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_PRELOAD</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_PROFILE</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_SHOW_AUXV</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LD_USE_LOAD_BIAS</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LOCALDOMAIN</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>LOCPATH</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>MALLOC_TRACE</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>NLSPATH</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>RESOLV_HOST_CONF</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>RES_OPTIONS</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>TMPDIR</envar>
     </para>
    </listitem>
    <listitem>
     <para>
      <envar>TZDIR</envar>
     </para>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="sec-apparmor-profiles-exec-clean-keywords">
   <title><literal>safe</literal> and <literal>unsafe</literal> Keywords</title>
   <para>
    You can use the <literal>safe</literal> and <literal>unsafe</literal>
    keywords for rules instead of using the case modifier of execution
    modes. For example
   </para>
<screen>/example_rule Px,</screen>
   <para>
    is the same as any of the following
   </para>
<screen>safe /example_rule px,
safe /example_rule Px,
safe px /example_rule,
safe Px /example_rule,</screen>
   <para>
    and the rule
   </para>
<screen>/example_rule px,</screen>
   <para>
    is the same as any of
   </para>
<screen>unsafe /example_rule px,
unsafe /example_rule Px,
unsafe px /example_rule,
unsafe Px /example_rule,</screen>
   <para>
    The <literal>safe</literal>/<literal>unsafe</literal> keywords are
    mutually exclusive and can be used in a file rule after the
    <literal>owner</literal> keyword, so the order of rule keywords is
   </para>
<screen>[audit] [deny] [owner] [safe|unsafe] file_rule</screen>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-rlimit">
  <title>Resource Limit Control</title>

  <para>
   &aa; can set and control an application's resource
   limits (rlimits, also known as ulimits). By default, &aa; does not
   control application's rlimits, and it will only control those limits
   specified in the confining profile. For more information about resource
   limits, refer to the <systemitem>setrlimit(2)</systemitem>,
   <systemitem>ulimit(1)</systemitem>, or <systemitem>ulimit(3)</systemitem>
   man pages.
  </para>

  <para>
   &aa; leverages the system's rlimits and as such does not provide an
   additional auditing that would normally occur. It also cannot raise
   rlimits set by the system, &aa; rlimits can only reduce an
   application's current resource limits.
  </para>

  <para>
   The values will be inherited by the children of a process and will remain
   even if a new profile is transitioned to or the application becomes
   unconfined. So when an application transitions to a new profile, that
   profile can further reduce the application's rlimits.
  </para>

  <para>
   &aa;'s rlimit rules will also provide mediation of setting an
   application's hard limits, should it try to raise them. The application
   cannot raise its hard limits any further than specified in
   the profile. The mediation of raising hard limits is not inherited as the
   set value is, so that when the application transitions to a new profile
   it is free to raise its limits as specified in the profile.
  </para>

  <para>
   &aa;'s rlimit control does not affect an application's soft limits
   beyond ensuring that they are less than or equal to the application's
   hard limits.
  </para>

  <para>
   &aa;'s hard limit rules have the general form of:
  </para>

<screen>set rlimit <replaceable>RESOURCE</replaceable> &lt;= <replaceable>value</replaceable>,</screen>

  <para>
   where <replaceable>RESOURCE</replaceable> and
   <replaceable>VALUE</replaceable> are to be replaced with the following
   values:
  </para>

  <variablelist>
   <varlistentry>
    <term><literal>cpu</literal>
    </term>
    <listitem>
     <para>
      CPU time limit in seconds.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><literal>fsize</literal>, <literal>data</literal>, <literal>stack</literal>,
      <literal>core</literal>, <literal>rss</literal>, <literal>as</literal>,
      <literal>memlock</literal>, <literal>msgqueue</literal>
    </term>
    <listitem>
     <para>
      a number in bytes, or a number with a suffix where the suffix can be
      K/KB (kilobytes), M/MB (megabytes), G/GB (gigabytes), for example
     </para>
<screen>rlimit data &lt;= 100M,</screen>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><literal>fsize</literal>, <literal>nofile</literal>, <literal>locks</literal>,
      <literal>sigpending</literal>, <literal>nproc</literal><superscript>*</superscript>,
      <literal>rtprio</literal>
    </term>
    <listitem>
     <para>
      a number greater or equal to 0
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><literal>nice</literal>
    </term>
    <listitem>
     <para>
      a value between -20 and 19
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

<!-- apparmor.vim has some rlimit additions pending - they are probably also missing in the documentation
         See the ML for details -->

  <para>
   <superscript>*</superscript>The nproc rlimit is handled different than
   all the other rlimits. Instead of indicating the standard process rlimit
   it controls the maximum number of processes that can be running under the
   profile at any time. When the limit is exceeded the creation of new
   processes under the profile will fail until the number of currently
   running processes is reduced.
  </para>

  <note>
   <para>
    Currently the tools cannot be used to add rlimit rules to profiles. The
    only way to add rlimit controls to a profile is to manually edit the
    profile with a text editor. The tools will still work with profiles
    containing rlimit rules and will not remove them, so it is safe to use
    the tools to update profiles containing them.
   </para>
  </note>
 </sect1>
 <sect1 xml:id="sec-apparmor-profiles-audit">
  <title>Auditing Rules</title>

  <para>
   &aa; provides the ability to audit given rules so that when they are
   matched an audit message will appear in the audit log. To enable audit
   messages for a given rule, the <literal>audit</literal> keyword is
   put in front of the rule:
  </para>

<screen>audit /etc/foo/*        rw,</screen>

  <para>
   If it is desirable to audit only a given permission the rule can be split
   into two rules. The following example will result in audit messages when
   files are opened for writing, but not when they are opened for reading:
  </para>

<screen>audit /etc/foo/*  w,
/etc/foo/*        r,</screen>

  <note>
   <para>
    Audit messages are not generated for every read or write of a file but
    only when a file is opened for reading or writing.
   </para>
  </note>

  <para>
   Audit control can be combined with
   <literal>owner</literal>/<literal>other</literal> conditional file rules
   to provide auditing when users access files they own/do not own:
  </para>

<screen>audit owner /home/*/.ssh/**       rw,
audit other /home/*/.ssh/**       r,</screen>
 </sect1>
<!-- fs 2011-11-09 - see bnc #722915
     ("set capabilities" was dropped upstream)

 <sect1 id="sec-apparmor-profiles-set-capabilities">
  <title>Setting Capabilities per Profile</title>

  <para>
   Normally &aa; only restricts existing native Linux controls and does not
   grant additional privileges. Therefore a program, having been granted
   write access to a file via its profile, would not be able to actually
   write to this file as long as the mode bits are set to read-only.
  </para>

  <para>
   The only exception to this strict rule is the <literal>set
   capability</literal> rule. This provides the ability to give non-root
   users administrative privileges, as defined in the
   <systemitem>capabilities(7)</systemitem> man page. Contrary to setting a
   program to setuid or using file system capabilities (that apply to single
   programs only), the set capability rule allows the user to apply
   capabilities to multiple programs running under a specific profile (by
   using ix transitions). For security reasons, set capability rules will
   not be inherited (when a program leaves the profile, it loses the
   elevated privilege).
  </para>

  <warning>
   <title>Use set capabilities Rules with Extreme Caution</title>
   <para>
    Using the set capabilities rules allows to give processes &rootuser;
    privileges. Therefore these rules should be used with extreme caution
    and only in exceptional cases.
   </para>
  </warning>

  <para>
   To set a capability in a profile the keyword <quote>set</quote> is
   put in front of a capability rule. Setting a capability also
   implicitly adds a capability rule allowing that capability.
  </para>

<screen>set capability cap_chown,</screen>

  <note>
   <para>
    Currently the tools can not be used to add rlimit rules to profiles. The
    only way to add rlimit controls to a profile is to manually edit the
    profile with a text editor. The tools will still work with profiles
    containing rlimit rules and will not remove them, so it is safe to use
    the tools to update profiles containing them.
   </para>
  </note>
 </sect1>
-->
</chapter>